carsim-guide
VerifiedOperate and automate CarSim simulations from an agent, including safe output and parameter discovery, named Run Control execution contexts, structured overrides, isolated batch sweeps, dataset dependency inspection, control-mode selection, result validation, diagnostics, and version-aware CLI/Simulink/VS API routing. Use for executing, configuring, exploring, or debugging CarSim. Do not use for vehicle-dynamics theory alone, generic dataframe work, or unrelated simulators.
references/python-interface.md
View on GitHub# Python runtime interface (`scripts/carsim_batch.py`)
Use this interface for direct scenario generation, solver execution, and
native-result reading. See `compatibility.md` for verified environments and
feature boundaries.
**Install paths**: run `scripts/setup_paths.py` once per machine — it discovers the CarSim install, verifies the CLI + 64-bit DLL, and caches everything (MATLAB and an explicitly selected base with SHA256) to `~/.carsim_guide_paths.json`. Every function and CLI flag below then resolves paths automatically: explicit argument > env var (`CARSIM_PROG` / `CARSIM_DATADIR` / `CARSIM_BASE`) > that cache.
## 0. Workflow overview
```
base Run_all.par (GUI-expanded and pinned per Run Control / execution context)
| referenced by
v
override.par (appended overrides: run switches + speed table + friction + open-loop steer + WRT channels)
| referenced by INPUT
v
simfile.sim (self-contained run description, ERDFILE=run.csv)
| -sim
v
VS_SolverWrapper_CLI_64.exe (headless solve; license needs the GUI or cslm.exe running)
v
run.csv (1 kHz text CSV) --pandas--> SI-unit DataFrame
```
The script wraps this flow into three independently callable functions: `make_scenario()` (steps 1+2), `run_solver()` (3), `read_run_csv()` (4).
## 1. override_par(): why each override exists
CarSim parses parsfiles **last-write-wins**: a keyword written later replaces an earlier one. The first line of override.par is `PARSFILE <absolute base path>`, pulling in the entire expanded base, so every subsequent line naturally takes effect. Rationale per keyword group:
| Keyword | Purpose / pitfall evidence |
|---|---|
| `OPT_ERROR_DIALOG 0` | required headless: an error dialog would hang the process |
| `OPT_ALL_WRITE 0` + `WRT_<channel>` | write only declared channels. `OPT_ALL_WRITE 1` + long scenarios produces GB-scale ERD |
| `OPT_VS_FILETYPE 4` | ERD output as **text CSV** (default 2 is binary .vs, not pandas-readable) |
| `TSTOP` / `OPT_STOP 0` / `SSTOP 100000` | stop by time; disable stop-on-distance |
| `TSTEP 0.001` + `IPRINT 1` | 1 ms step, one row per step → 1 kHz sampling |
| `OPT_SC 1` + `SPEED_TARGET_COMBINE ADD` + `SPEED_TARGET_TABLE` | closed-loop speed controller, target = table (t s, km/h). **Initial speed = first row** |
| `OPT_SC_ENGINE_BRAKING 1` | EV: prefer motor regen while decelerating |
| `MU_ROAD_CARPET 2D_STEP` | friction override (3-column table: s, mu_left, mu_right). If the base is a low-mu scenario, ordinary scenarios **must** override it or the tires saturate early |
| `OPT_DM 0` + `STEER_SW_TABLE` | **open-loop steering is the only reliable steering override**. A closed-loop LTARG_TABLE is row-appended, not replaced (observed "tracking" a phantom target 14.6 m away) — never use it to override |
| `LOG_ENTRY` + `END` | log marker + parsfile terminator (every par needs END) |
| `unsafe_extra_lines=` (advanced API) | free keyword lines injected after the tables, before the WRT block; for typed and generic parameter overrides, see `references/parameters.md` |
The `_table()` helper emits `NAME <interp> … ENDTABLE` blocks; `_dedupe()` drops repeated abcissa values — CarSim rejects duplicate x values inside a table.
## 2. simfile(): field quick reference
| Field | Notes |
|---|---|
| `FILEBASE/INPUT/INPUTARCHIVE/ECHO/FINAL/LOGFILE/ERDFILE` | all absolute paths into the scenario directory → per-scenario isolated output; batch runs never collide. `ECHO` (parse echo) and `LOGFILE` (lists every dataset actually used) are debugging evidence |
| `ERDFILE <dir>/run.csv` | combined with `OPT_VS_FILETYPE 4`, yields a CSV directly |
| `PROGDIR/DATADIR` | keep trailing directory separators; native terrain paths may be constructed by concatenation |
| `VEHICLE_CODE i_i` | vehicle code (i_i = car-to-car; copy the value matching the base) |
| `EXT_MODEL_STEP` | keep equal to TSTEP |
| `DLLFILE` | **pin 64-bit** carsim_64.dll; GUI-generated simfiles may write 32-bit |
## 3. run_solver(): CLI invocation and success criteria
```python
cmd = [exe, "-sim", simfile_path.replace("\\", "/")]
subprocess.run(cmd, capture_output=True, text=True, timeout=...)
```
- Uses an **argv list** (`shell=False`), which sidesteps shell backslash-escaping entirely; the path is still normalized to forward slashes (the CLI likes those best; typing backslash paths by hand in Git Bash escapes silently — symptom: "results didn't change", check the CSV timestamp).
- **Success criterion**: stdout contains `Termination at simulation time = <TSTOP>`; on failure, raises RuntimeError with the last 40 lines of output.
- Common failures:
- `Unable to load library` / license error → GUI not open and cslm.exe not running, or a wrong DLLFILE path;
- "succeeded" but results unchanged → simfile/override path escaping issue; check the simfile path on the first line of run_log.txt.
## 4. Native CSV unit conversion
The core reader `read_run_csv(path, columns=None, units="SI")` returns every
registered channel the file contains—tire outputs (Fx/Fy/Fz/Kappa/Alpha)
included, with no special flag. `units="native"` returns raw CarSim values;
unknown channels and missing requested columns raise because units are never
guessed. The authoritative metadata lives in `output_registry.py`.
| CSV column | Native unit | → SI factor |
|---|---|---|
| Time | s | 1 |
| Vx, Vy | km/h | ×(1/3.6) |
| Ax, Ay | **g** | ×9.80665 |
| AVz | deg/s | ×(π/180) |
| Roll, Pitch, Yaw, Steer_*, Alpha_* | deg | ×(π/180) |
| AVy_L1/R1/L2/R2 (wheel speeds) | **rpm** | ×(2π/60) |
| Fx_/Fy_/Fz_ (N), My_Dr_/My_Bk_ (N·m), Kappa_ | SI / dimensionless | 1 |
| AV_Mt_* (motor speeds) | rpm | ×(2π/60), SI rad/s |
Sign conventions (verified): left turn → AVz > 0; My_Dr positive = drive, negative = regen; My_Bk non-positive while moving forward. Wheel corners `L1=FL, R1=FR, L2=RL, R2=RR`.
`UNRELIABLE_COLS = (Lat_Veh, Lat_Targ)` are known drift artifacts and are
dropped automatically. Explicitly requesting one raises with the reason;
derive lateral position from `Yo`/`Yaw`.
## 5. Usage examples
Command line (straight cruise, run then read back). After `setup_paths.py` has run once, the three path flags can be omitted entirely:
```
python scripts/carsim_batch.py ^
--prog "C:/CarSim/CarSim2024.0_Prog" --datadir "C:/CarSim/CarSim2024.0_Data" ^
--base "C:/work/base/Run_all.par" --out "C:/work/S0_straight" ^
--tstop 65 --speed-profile "0:50,65:50" --run --read
:: cached-paths equivalent - only --out is required:
python scripts/carsim_batch.py --out "C:/work/S0_straight" ^
--tstop 65 --speed-profile "0:50,65:50" --run --read
```
(`^` is the Windows cmd line continuation; use `\` in bash.)
As a library (custom lane-change scenario) — path arguments are optional once the cache exists:
```python
from carsim_batch import make_scenario, run_solver, read_run_csv
from scenario_schema import VehicleOverrides
sim = make_scenario(
out_dir="C:/work/lane_change",
base_run_all="C:/work/base/Run_all.par", # optional: explicitly bound cached base
prog="C:/CarSim/CarSim2024.0_Prog", # optional: cached
datadir="C:/CarSim/CarSim2024.0_Data", # optional: cached
tstop=300.0,
speed_rows=[(0, 43), (30, 65), (60, 72), (90, 40), (300, 50)], # s, km/h
steer_rows=[(0, 0), (95, 14), (105, 14), (110, -14), (120, -14), (300, 0)], # s, deg
mu=0.9,
vehicle_overrides=VehicleOverrides(sprung_mass_kg=1254.0),
)
run_solver(sim, timeout=600) # prog defaults to the cached install
df = read_run_csv("C:/work/lane_change/run.csv", columns=["Time", "Vx", "Ay", "AVz"])
```
The strict reader validates all loaded native CSV units. For long runs,
request only necessary WRT channels during generation to control file size;
add `outputs=cb.OUTPUTS_TIRE` when the task needs tire forces or slips.
## 6. Companion utility
`scripts/dump_dll_exports.py`: zero-dependency PE export-table parser that
lists a DLL's exported symbols. Run it as
`python scripts/dump_dll_exports.py carsim_64.dll`.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |