Skip to content

Latest commit

 

History

History
191 lines (139 loc) · 4.85 KB

getting_started.md

File metadata and controls

191 lines (139 loc) · 4.85 KB

Getting Started

This guide will help you get started with the vehicle simulation repository.

Installation

Prerequisites

  • Python 3.10 or higher
  • pip

Install from Source

# Clone or navigate to the repository
cd simulation_repo

# Create venv and install project (dev deps by default)
bash setup.sh

# Runtime-only install (without dev extras)
INSTALL_DEV=0 bash setup.sh

Quick Start

1. Basic Simulation

Run a simple simulation with default vehicle parameters:

from simulation.dynamics import ExtendedPlant, ExtendedPlantParams

# Use default parameters
params = ExtendedPlantParams()
plant = ExtendedPlant(params)

# Initialize and simulate
plant.reset(speed=0.0)
for _ in range(100):
    state = plant.step(0.5, dt=0.1)  # 50% throttle
    print(f"Speed: {state.speed:.2f} m/s")

See examples/basic_simulation.py for a complete example.

2. Fit Parameters from Data

Fit vehicle parameters from trip data:

python scripts/fit_params.py \
    --data data/processed/vehicle/all_trips_data.pt \
    --output fitted_params.json

Or use the GUI:

python examples/gui_usage.py

2a. Fetch Raw Trips (GUI)

Use the dedicated fetching GUI to download trips from S3 without CLI flags:

python scripts/fetch_trips_gui.py

Equivalent CLI:

python scripts/fetch_trips.py \
    --car NiroEV \
    --start 2024-01-01 \
    --end 2024-01-07 \
    --dest data/raw/trips

2b. Parse Trips Into Dataset (GUI)

Use the dedicated parser GUI to build .pt datasets from raw trip folders:

python scripts/parse_trips_gui.py

Equivalent CLI:

python scripts/parse_trips.py \
    --root data/raw/trips \
    --car NiroEV \
    --out-dir data/processed/NiroEV

3. Run Simulation with Fitted Parameters

python scripts/simulate_trip.py \
    --params fitted_params.json \
    --trip-data data/processed/vehicle/all_trips_data.pt \
    --output simulation_results.npz

4. Compare Feedforward Open-Loop vs Closed-Loop

Launch the dedicated feedforward comparison GUI:

# Script
python scripts/feedforward_compare_gui.py

# Console entry point (after pip install -e .)
feedforward-compare-gui

What this GUI provides:

  • Open-loop and closed-loop feedforward comparison against trip data
  • GT acceleration Butterworth filtering with cutoff control in Hz
  • Separate throttle and brake feedforward gain sliders
  • Full-state diagnostics in an 8-subplot layout (2 columns)

Parameter loading supports fitted params JSON, fitter config.json, and fitting_checkpoint.json payloads.

Visualization Options

Both the simulation script and examples support comprehensive plotting of all simulation states:

Simulation Script (scripts/simulate_trip.py):

# Generate plots with all internal states
python scripts/simulate_trip.py \
    --params fitted_params.json \
    --trip-data data/processed/vehicle/all_trips_data.pt \
    --output simulation_results.npz \
    --plot \
    --plot-output simulation_plot.png

# For synthetic simulation (without trip data)
python scripts/simulate_trip.py \
    --params fitted_params.json \
    --output simulation_results.npz \
    --plot \
    --duration 60.0 \
    --dt 0.1

Basic Simulation Example (examples/basic_simulation.py):

# Run with plotting enabled
python examples/basic_simulation.py --plot

# Customize duration and output path
python examples/basic_simulation.py \
    --plot \
    --plot-output my_results.png \
    --duration 20.0 \
    --dt 0.05

Plot Contents:

The plotting functionality generates a comprehensive figure with 14 subplots (all sharing the x-axis for time):

  1. Actuations - Throttle and brake commands (0-100%)
  2. Vehicle Speed - Simulated speed (and measured if available)
  3. Acceleration - Simulated acceleration (and measured if available)
  4. Road Grade - Road grade in degrees
  5. Motor Angular Speed - Motor shaft angular speed (rad/s)
  6. Motor Current - With current limit overlay
  7. Motor Voltage - Commanded voltage, back-EMF voltage, and V_max limits
  8. Drive Torque at Wheel - With motor/wheel T_max overlays
  9. Motor Power - V × I, with P_max limits
  10. Brake Torque - With brake T_max limit
  11. Forces - Tire, drag, rolling, grade, and net forces
  12. Wheel Angular Speed and Slip Ratio - Dual y-axis plot
  13. Vehicle Position - Position over time
  14. Status Flags - Held by brakes and coupling enabled (0/1)

All plots are saved as PNG files with 150 DPI resolution and can be used for detailed analysis of vehicle dynamics behavior.

Next Steps