Skip to content

zyfgi/carsim-guide-skill

carsim-guide

Verified

Operate 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.

FileKindSize
SKILL.mdskill md6.3 KB
examples/batches/friction_sweep.yamlconfig159 B
examples/batches/mass_friction_grid.yamlconfig198 B
examples/discovery/dataset_tree.pyscript693 B
examples/discovery/find_output.pyscript715 B
examples/discovery/find_parameter.pyscript761 B
examples/scenarios/basic_cruise.yamlconfig380 B
examples/scenarios/friction_change.yamlconfig379 B
examples/scenarios/steering_maneuver.yamlconfig377 B
examples/scenarios/tire_force_output.yamlconfig437 B
examples/scenarios/vehicle_override.yamlconfig376 B
examples/simulink_cosim.pyscript5.5 KB
examples/torque_vectoring.pyscript5.6 KB
references/advanced-controls.mdmarkdown4.0 KB
references/batch-workflows.mdmarkdown1.6 KB
references/compatibility.mdmarkdown1.4 KB
references/control-modes.mdmarkdown1.0 KB
references/database-exploration.mdmarkdown7.4 KB
references/dataset-syntax.mdmarkdown6.6 KB
references/outputs-and-units.mdmarkdown2.1 KB
references/parameter-discovery.mdmarkdown1.4 KB
references/parameters.mdmarkdown3.3 KB
references/python-interface.mdmarkdown7.9 KB
references/run-validation.mdmarkdown2.2 KB
references/scenarios.mdmarkdown3.3 KB
references/simulink-cosim.mdmarkdown4.0 KB
references/troubleshooting.mdmarkdown1.4 KB
references/version-compatibility.mdmarkdown811 B
references/vs-c-api.mdmarkdown3.3 KB
scripts/base_registry.pyscript4.7 KB
scripts/batch_runner.pyscript7.1 KB
scripts/carsim_batch.pyscript23.4 KB
scripts/carsim_errors.pyscript2.2 KB
scripts/control_modes.pyscript1.8 KB
scripts/cosim_model.mother4.7 KB
scripts/database_tools.pyscript16.5 KB
scripts/diagnose_run.pyscript444 B
scripts/diagnostics.pyscript6.9 KB
scripts/discovery_query.pyscript1.0 KB
scripts/dump_dll_exports.pyscript1.9 KB
scripts/output_registry.pyscript8.9 KB
scripts/override_registry.pyscript2.9 KB
scripts/parameter_discovery.pyscript8.6 KB
scripts/parameters.pyscript10.0 KB
scripts/result_contract.pyscript548 B
scripts/scenario_runner.pyscript11.3 KB
scripts/scenario_schema.pyscript4.0 KB
scripts/setup_paths.pyscript11.2 KB
scripts/tv_cosim.mother8.5 KB
scripts/validate_run.pyscript6.1 KB
scripts/version_compatibility.pyscript2.0 KB

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`.
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall