Metadata-Version: 2.1
Name: vdsim
Version: 0.7.0
Summary: VDSim — open-core vehicle-dynamics simulator (validated L1–L3 dynamics, Pacejka MF, hardpoint kinematics, FMI 2.0)
Keywords: vehicle-dynamics,simulation,pacejka,fmi,autonomous-driving
Author: Jiwon Seok
License: Apache-2.0
Project-URL: Homepage, https://onlyti.github.io/VDSim/
Requires-Python: >=3.8
Requires-Dist: numpy
Requires-Dist: pyyaml
Provides-Extra: plot
Requires-Dist: matplotlib; extra == "plot"
Requires-Dist: pillow; extra == "plot"
Description-Content-Type: text/markdown

# VDSim

**English** · [한국어](README.ko.md)

[![build](https://github.com/Onlyti/VDSim/actions/workflows/build.yml/badge.svg)](https://github.com/Onlyti/VDSim/actions/workflows/build.yml)
[![license](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
![status](https://img.shields.io/badge/status-experimental%20pre--release-orange.svg)
![tests](https://img.shields.io/badge/ctest-391%2F391-green.svg)

> **Experimental / pre-release — not for production.** Evidence and limits:
> [VALIDATION.md](docs/VALIDATION.md) (v0.5.1+).
> **Validated:** analytic + ISO maneuvers + L1↔L3 self-consistency + pure-slip same-`.tir`
> cross-check (Chrono Pac02 ~0.8%) — not MF-Tyre product parity.
> **NOT yet:** full-vehicle commercial cross-val, real-vehicle data, production sign-off.

![Grip-loss demo](docs/assets/demo_grip_loss.gif)

*Deterministic VDSim plant: controller hits an unseen low-μ patch, tyres saturate past
peak (drift>1) — real grip loss, not a soft-clamp.* Reproduce:
`python examples/demo_grip_loss.py` (`pip install vdsim[plot]` or local wheel).

> **Experimental / pre-release software — not for production use.**
> What is verified, and what is *not yet*: see [docs/VALIDATION.md](docs/VALIDATION.md).

**Verification scope.** VDSim's tire-force layer is cross-checked against an independent
implementation driven by the same `.tir` parameter file: Chrono Pac02 (BSD-3, ~0.8% / 0.7%).
This is a pure-slip cross-check between implementations, not product parity.
Full-vehicle behaviour (suspension, transient) and comparison against real-vehicle
measurements are **not yet** covered.

![Grip-loss demo](docs/assets/demo_grip_loss.gif)

*Deterministic VDSim plant: controller hits an unseen low-μ patch, tyres saturate past
peak (drift>1) — real grip loss, not a soft-clamp.* Reproduce:
`python examples/demo_grip_loss.py` (`pip install vdsim[plot]` or local wheel).

Open-core vehicle-dynamics simulator. VDSim owns the **vehicle** — implemented
L1–L5 dynamics with real Pacejka MF / LuGre / belt-transient tires, hardpoint
suspension kinematics you can design against, and bidirectional FMI 2.0 — and
delegates rendering/sensors to tools like CARLA. It is the chassis-accurate half
that perception stacks lack.

Docs (theory + reports): **https://onlyti.github.io/VDSim/** · all run modes
(API / batch / FMI): [docs/RUNNING.md](docs/RUNNING.md) · catalog & physics options:
[docs/CATALOG_AND_PHYSICS.md](docs/CATALOG_AND_PHYSICS.md)

## Quickstart (pip wheel)

Prerequisites: Python 3.8–3.12 (pre-built wheels for Linux x86_64 and Windows
AMD64). Install from PyPI (or build locally — see [from source](#from-source) below).

```bash
pip install "vdsim[plot]"           # or a local wheel: pip install "./vdsim-*.whl[plot]"
vdsim-quickstart          # writes run.csv + run.png in the current directory
```

The package ships generic presets only; `VDSimPlant()` defaults to `generic_sedan`.
A car whose parameters must stay private is kept outside the package and found first:
`export VDSIM_PRIVATE_CONFIGS=/abs/root` with `/abs/root/vehicles/<name>.yaml` (tyre under
`/abs/root/parts/tire/`), then `VDSimPlant(config="<name>.yaml")`.

Install into a clean environment: another distribution also provides a top-level
`vdsim` package, and if both are present that one wins the import. VDSim detects
this and raises `CoreShadowedError` naming the file that was loaded.

Measured on a clean conda env (Python 3.11, Linux x86_64, 2026-06-25): **first result in
seconds** — pip install `[plot]` + `vdsim-quickstart` → `run.csv` + `run.png` in **~6 s
wall-clock** (cold; lab network, matplotlib wheel included). Repeat quickstart ~1.5 s.

Verify the install:

```bash
python -c "import vdsim; from vdsim_lab import Sim; Sim(vehicle='sedan', level='L2')"
```

Source for the script: [`examples/quickstart.py`](examples/quickstart.py) — uses only
`from vdsim_lab import Sim, Road` (no repo paths).

## From source

Prerequisites: a C++17 compiler, CMake ≥ 3.16, Python ≥ 3.10.
- Linux: `g++ ≥ 9` or `clang ≥ 10`. CI builds gcc-11 and clang-14 on Ubuntu 22.04.
- Windows: Visual Studio 2019+ with "Desktop development with C++" (MSVC).
- Building the tree needs CMake ≥ 3.16, but the canonical validation run goes
  through `CMakePresets.json` (preset schema v3), which needs **CMake ≥ 3.21** —
  an older CMake builds VDSim fine and simply cannot read the preset.

Python package (editable / local wheel build):
```bash
pip install ".[plot]"
python -c "import vdsim; print('ok')"
```

Full C++ tree (tests, real-time runtime, FMI, CARLA bridge):
```bash
cmake -B build -DVDSIM_BUILD_PYTHON=ON          # add -G Ninja on Linux
cmake --build build --config Release            # -j on Linux
cd build && ctest -C Release                    # binaries in build/bin/
```
The canonical suite count lives in one place only — [docs/VALIDATION.md](docs/VALIDATION.md).
Reproduce it with the pinned preset:
```bash
cmake --preset validation && cmake --build --preset validation
ctest --preset validation
```

## Run an experiment in Python (write your own controller)

VDSim gives you the **simulation seam**; you own the loop and the algorithm. Build
the plant straight from the core (vehicle / tire / level / road) — no scenario file,
no network — then drive it: `set_input(action) → run_core_dt()`, read
`state()` / `measurements(id)`.

```python
from vdsim_lab import Sim, Road, Sensors

sim = Sim(vehicle="sedan", level="L2", road=Road.iso8608("C"),
          sensors=Sensors().gnss(pos_std=0.3).imu(), v0=12.0,
          sensor_mounts={"gnss": {"type": "gnss", "pos": [1.4, 0, 1.0]}})

while not sim.done(12.0):
    st = sim.state()                                  # ground truth
    gnss = sim.measurements("gnss")                   # noisy, at the mount
    steer, throttle, brake = my_controller(st, gnss)  # <-- YOUR algorithm
    sim.set_input(steer=steer, throttle=throttle, brake=brake)
    sim.run_core_dt()                                 # advance one core step

sim.to_csv("run.csv")                                 # ground-truth + per-wheel log
sim.metrics(["peak_ay", "cte_rms", "lap_time"])       # scalar reductions
sim.plot("run.png", signals=("vx", "ay", "r", "xy"))  # optional (needs matplotlib)
```

Copy `templates/experiment_template.py`, replace `controller(...)`, and run from a
cloned tree:
```bash
PYTHONPATH=build/python:python python3 templates/experiment_template.py
```
Runnable examples (require clone + build): `examples/experiment_quickstart.py`,
`examples/experiment_path_follow.py` (pure-pursuit + CTE). Pip users: use
[`examples/quickstart.py`](examples/quickstart.py) / `vdsim-quickstart` instead. Full reference (the
seam, `Sim(...)` options, evidence): **[docs/EXPERIMENT_API.md](docs/EXPERIMENT_API.md)**.
This is the same `set_input → tick` seam the real-time server and batch runner use —
in real-time mode the action arrives over UDP, here it comes from your function.

## Visualization — Web GUI

```bash
python3 gui/server.py --port 8100        # Windows: python gui\server.py --port 8100
```
Open `http://localhost:8100`. The GUI auto-starts the real-time runtime and
renders it: 3D view (orbit / chase / cockpit), road & terrain, per-wheel Fz /
slip (κ, α) / tire-force vectors, and a telemetry HUD. Drive with the keyboard
(↑↓ throttle/brake, ←→ steer) or a gamepad-wheel — force feedback via
`python tools/wheel_ffb_sdl.py --server <host> --udp-port 8101`.

## Visualization — headless trace render

A run can be recorded to a single `.vdtrace` file and rendered later, with no GUI,
no node/npm and no browser. Recording is opt-in and off unless enabled:

```python
plant.enable_trace("run.vdtrace", seed=0, run_id="demo")   # off unless called
...                                                        # step() as usual
path = plant.finalize_trace()
```

- `enable_trace(path, decimation=None, seed=None, run_id=None, producer=None, tags=None, role="plant")` —
  one sample is offered per `step()`, taken *before* the step is integrated, so the
  pose is the state at `t` and `u_steer` / `u_fx` are the command held over
  `[t, t+control_dt)`. Returns the resolved decimation.
- `decimation=None` picks the smallest N whose record rate stays at or above 100 Hz
  (1 kHz control → N=10; a 20 Hz loop stays at N=1 and loses nothing).
- `finalize_trace()` flushes channels, freezes the manifest and closes the file;
  it returns the written path (`None` when recording was never enabled).
- The container is a zip: `manifest.json` + `channels/*.f64` + `overlays/*.json`.
  That one file is enough to render — no re-simulation, no results file.
- The manifest declares `schema_version` (the writer emits `"0.5"`; the fields
  each version added are listed below) and a required `role`, either
  `"plant"` (the simulator under verification) or `"predictor"` (the same code
  driven as an optimiser's internal model). `enable_trace` defaults to `plant`
  because `VDSimPlant` *is* the plant; a producer that builds a
  `vdsim_trace.TraceWriter` directly must pass `role=` — there is no default,
  so a predictor run cannot be recorded as plant evidence by omission.
  Reading a legacy `0.1` trace still works: a missing `role` resolves to
  `plant` with one warning. A `0.2` or later trace without one is an error.
  The renderer prints the role in the HUD and never branches on it.

### Render presets

A preset decides *which view* of one trace is drawn. It is renderer
configuration, not trace content, so presets never change what a `.vdtrace`
holds. `overview` is the built-in — BEV, driven path, optional reference path,
speed, steer and longitudinal command:

```bash
vdsim-render run.vdtrace                      # overview is the default
vdsim-render run.vdtrace --list-presets
vdsim-render run.vdtrace --preset my.yaml     # user preset (.yaml/.yml/.json)
vdsim-render run.vdtrace --panels speed,u_fx  # CLI wins over the preset
```

- Resolution order: **CLI option > user preset file > built-in default**. A user
  preset only has to state what it changes; the rest is inherited from the
  built-in named by `extends` (default `overview`).
- A preset declares panel channels, labels, y-ranges and BEV layer visibility.
  `speed` is derived from `v_body`; every other panel names a trace channel.
- A channel the trace does not carry drops its panel silently — the same preset
  works on a run recorded with a channel subset. Mark a panel `required: true`
  to turn that omission back into an error.
- Panel positions and the BEV axis coordinate system are fixed. Data autoscale
  is allowed; text, legend or panels leaving the frame is a failure and
  `render()` reports it in `layout_violations`.
- `control` and `tire_limit` are contracted but not implemented, and
  `road_contact` is reserved until the core resolves full contact normals.
  Those names are refused rather than stubbed.

```yaml
# my.yaml — everything not named here is inherited from overview
name: steer_only
panels:
  - channel: u_steer
    label: delta
    ylim: [-0.5, 0.5]
bev:
  waypoint: false
  view_half_m: 45.0
```

Scenario knowledge is attached after the run as **overlays**. VDSim validates the
`kind` / `name` envelope and stores the object without interpreting it, so a newer
producer can write overlays that today's renderer ignores:

```python
import vdsim_trace
vdsim_trace.attach_overlay(path, {"kind": "path2d", "name": "intended_path",
                                  "xy": [[0.0, 0.0], [4.0, 0.0]]})
vdsim_trace.attach_overlay(path, {"kind": "region", "name": "mu_patch", "mu": 0.35,
                                  "polygon": [[40, -30], [60, -30], [60, 30], [40, 30]]})
```

The renderer takes one trace and writes a GIF plus a preview PNG (matplotlib +
pillow, from the `[plot]` extra):

```bash
vdsim-render run.vdtrace --out run.gif --fps 20     # installed wheel
PYTHONPATH=python python3 -m vdsim_render run.vdtrace --out run.gif   # cloned tree
```

Options: `--png` preview path · `--stride` frame stride · `--fps` · `--dpi` ·
`--title` · `--mp4` (only when `imageio-ffmpeg` is installed). Controller
horizons add `--sidecar` / `--view-half` / `--preview-frame` (below).

The bird's-eye frame shows the reference path (dashed, from a `path2d` overlay;
omitted when absent), the driven path, a body rectangle sized from manifest
`geometry`, front wheels turned by the recorded steering command, a velocity
arrow, per-wheel friction-utilization colour, a HUD in fixed screen coordinates,
and the `u_steer` / `u_fx` time series with a current-time cursor. Axis limits
come from `geometry`, never from autoscale, so the scale never drifts between
frames.

The single-run view also carries two fixed-screen instruments: a steering-wheel
dial whose rotation is the recorded road-wheel angle multiplied by manifest
`geometry.steer_ratio`, and a speedometer in km/h. The speedometer scale is fixed
for the whole trace (rounded up in 20 km/h steps), so neither needle changes
meaning between frames. These instruments are part of the headless matplotlib
output; they do not add node/npm/browser dependencies.

End to end — record, attach overlays, render:

```bash
PYTHONPATH=build/python:python python3 examples/demo_grip_loss.py \
    --out demo.gif --keep-trace
```

### Overlaying several runs

Pass two or more traces and the renderer draws them in one view — one camera, one
clock, a colour per run and the driven path in that same colour:

```bash
vdsim-render base.vdtrace tuned.vdtrace wet.vdtrace --out compare.gif \
    --labels "base,tuned,wet" --alpha 0.5
```

- Runs are aligned by **time**, not by sample index: every run is interpolated at
  the frame time, so traces recorded at different `dt`, or of different length,
  still overlay correctly. Yaw is unwrapped first, so a heading near ±π does not
  swing the long way round.
- A run whose trace ends early holds its final pose, fades to 35 % alpha, is
  marked `(ended)` in the HUD, and stops extending its path.
- `--alpha` (body fill, default 0.55) and `--path-alpha` (default 0.9) set how
  much of an overlapped vehicle shows through. `--colors` overrides the palette,
  `--labels` the legend (default: manifest `run_id`, else the file stem).
- Camera: `--follow fit` (default) is a static square window holding every route;
  `--follow 1` tracks that run with the usual geometry-derived window.
- `--speed` sets playback rate relative to wall-clock (`--stride` is single-run
  only). Each run's whole route is drawn faintly underneath; `--no-ghost` removes it.
- Body colour is spent on run identity, so grip moves to the wheels: a tyre
  outline turns red once its utilization crosses 0.8. The right-hand panels
  overlay every run's `u_steer` / `u_fx` and max utilization on one shared time axis.
- The preview PNG is taken at the frame of **maximum divergence** between runs,
  not at an arbitrary time.

End to end — the same manoeuvre at three friction levels, recorded to three
traces and overlaid from the files alone:

```bash
PYTHONPATH=build/python:python python3 examples/demo_compare_runs.py --out compare.gif
```

### Controller horizons — waypoint / target / prediction

Three curves get routinely conflated under the word "reference". They are
different objects, and the renderer keeps them apart by name — in the code, in
the sidecar keys and in the legend:

- **waypoint** — the global route the run has to follow. Time-invariant, one per
  scenario, carried by a `path2d` overlay and drawn once as a dashed grey line.
  The overlay `name` may be `waypoint`, `reference_path` or `ref_path`; the
  first is preferred, the other two stay accepted for older traces.
- **target (MPC input)** — the reference horizon handed to the controller at
  *this* step (N+1 points). Time-varying: the point spacing follows the planned
  speed, so it compresses under braking. Blue with markers, so the spacing is
  readable.
- **prediction (MPC output)** — the horizon the controller solved for at this
  step (N+1 points). Time-varying; on a failed solve it is whatever the solver
  returned. Orange, switching to thick red while the solver status is non-zero.

`target` and `prediction` are `(K, N+1, 2)` arrays and the trace container's
channel table is a whitelist of scalar / fixed-width rows, so they travel in a
**sidecar** `.npz` beside the trace rather than inside the container:

```
run.vdtrace          # the trace, renderable on its own
run.qp.npz           # optional horizons sidecar, picked up automatically
```

| key | shape | meaning |
| --- | --- | --- |
| `t` | (K,) | step time [s] — matched to trace samples by nearest time, not by index |
| `tgt_XY` | (K, N+1, 2) | target horizon, world frame [m] |
| `pred_XY` | (K, N+1, 2) | prediction horizon, world frame [m] |
| `status` | (K,) | solver status, `0` = success |
| `solve_ms` | (K,) | solve time [ms] — optional, shown in the HUD |
| `tgt_v` | (K, N+1) | planned speed along the target [m/s] — optional |
| `ego_XY` | (K, 2) | rear-axle position per step — optional, used to fit the view |

Only the first four keys are required, and the sidecar as a whole is optional:
without one the renderer behaves exactly as it did before, and the two horizon
artists are never created.

- Write the horizons in the **world** frame. A controller solving in an ego or
  Frenet frame has to undo that transform first. The check is that
  `pred_XY[k, 0]` lands within ~0.1 m of the vehicle's rear-axle position at
  step `k` — if it does not, the frame is wrong.
- Record a failed solve as it happened: keep that step's `pred_XY`, NaN
  included, instead of holding the previous one. The renderer skips non-finite
  points; overwriting them hides the failure the video is meant to show.

```bash
vdsim-render run.vdtrace --out run.gif --view-half 100 --preview-frame first-fail
```

- `--sidecar` names the `.npz` explicitly. The default is the trace path with
  its suffix swapped for `.qp.npz` (`run.vdtrace` -> `run.qp.npz`) when that
  file exists, and no sidecar otherwise; passing the flag turns a missing file
  into an error instead of a silent skip.
- `--view-half` sets the bird's-eye half-window [m]. The default window is
  derived from the wheelbase (~6 wheelbases) and is far shorter than an MPC
  horizon, so a 100 m horizon leaves the frame unless the window is widened.
- `--preview-frame util-peak` (default, unchanged) puts the preview PNG at the
  friction-utilization peak; `first-fail` puts it at the first non-zero solver
  status, printing a note and falling back to the peak when the run never
  failed.
- A run containing any failed solve also gets `<out>_firstfail.png` written next
  to the GIF, whatever `--preview-frame` says, and the BEV carries a
  `QP FAIL (status=N)` banner for as long as the status is non-zero.
- Failure times are marked on the command panel as vertical spans, merged over
  consecutive failing steps. They come from an `event` overlay named `qp_fail`
  when the producer attached one, and from the sidecar `status` array otherwise.

All three flags are single-run only — overlay mode ignores them.

### Replay in 3D — `vdsim_render3d`

The bird's-eye view above is flat by construction. A run recorded at schema
`0.3` also carries attitude, ride height, body accelerations and the road
contacts, and `python/vdsim_render3d.py` replays that in three dimensions from
the trace file alone — no simulator, no scenario, no re-run:

```bash
PYTHONPATH=python python3 -m vdsim_render3d run.vdtrace \
    --out results/replay --cameras quarter,side,chase \
    --stride 5 --fps 20 --rt1 force,accel,saturation,normal
```

End to end, record and replay in one script:

```bash
python3 examples/demo_replay3d.py --out results/replay3d
```

The 2D renderer is untouched: `vdsim_render` and `vdsim_render3d` are separate
modules that share only the container reader, so an existing BEV render of the
same trace and preset stays byte-identical.

**Render tiers.** `RT0` is always on — body box, four steered wheels, the ground
grid and the driven trajectory. `RT1` is opt-in per layer through `--rt1`:

| layer | draws | needs |
| --- | --- | --- |
| `force` | per-wheel contact-force arrows | `wheel_F` |
| `accel` | the CG acceleration vector | `a_body` |
| `saturation` | wheel colour by friction utilization | `wheel_F`, `wheel_mu` |
| `normal` | per-wheel road normals at the contact points | `wheel_road_normal` |
| `refpath` | the `path2d` overlay, dashed | a `path2d` overlay |

`--rt1 all` turns them all on. Suspension links, tyre deformation and contact
pressure (RT2) are **not** drawn: the trace has no input for them, so drawing
them would mean inventing one.

Vector lengths are fixed constants — `--force-scale` (N per drawn metre),
`--accel-scale` (m/s² per drawn metre) and `--normal-scale` (drawn length of the
unit normal), all printed on every frame. Nothing autoscales per frame: if the
same arrow length meant different things at different times the video would be
misleading in a way that is very hard to notice.

**Cameras are a combination, not a list.** A camera is
`mount` × `aim` × `offset` × `projection` × `follow_attitude`; the six names are
aliases over that:

| alias | mount | aim | projection | note |
| --- | --- | --- | --- | --- |
| `bev3d` | vehicle | vehicle | ortho | top-down, the 3D counterpart of the 2D BEV |
| `side` | vehicle | vehicle | ortho | for reading roll, pitch and ride height |
| `quarter` | vehicle | vehicle | persp | three-quarter, the default |
| `chase` | vehicle | vehicle | persp | behind the car |
| `map_fixed` | world | fixed_point | persp | whole trajectory in one frame |
| `map_track` | world | vehicle | persp | fixed viewpoint, follows the car |

`follow_attitude` defaults to `yaw`. Roll and pitch are deliberately **not**
followed: a camera that rolled with the body would keep the horizon level and
make the attitude unreadable, which is the one thing a 3D replay is for.

**One file per camera, one pass over the trace.** `--cameras quarter,side`
writes `<run_id>__<preset>__<camera>.mp4` plus a preview PNG for each; there is
no grid composite, because splitting the resolution makes the HUD unreadable.
Loading, decimation and the utilization derivation happen once regardless of how
many cameras are drawn, so the total is `base + N × draw`. Measured on a 30 s L3
run (600 frames, ailab-12): load+prep `0.19 s` either way, draw `13.3 s` for one
camera and `41.3 s` for three.

`ffmpeg` is used when it is on `PATH` and is never bundled. Without it the
render still succeeds, writing a PNG sequence and printing the one-line command
that assembles it.

**Older traces degrade instead of lying.** A `0.2` trace has no `pose_zrp`, so
the player draws `z = 0`, `roll = pitch = 0`, prints the reason once and labels
every frame. And when `contact_scope` is `C0`/`C1` the core never read the road
normal's x/y, so the normal layer carries a `normal: display-only` badge — a
tilted road drawn over flat physics is exactly the frame that would otherwise
pass review.

### Trace schema `0.3` — what a 3D replay needs recorded

Recording is still opt-in and still costs nothing when off (measured `+0.08 %`
of `step()` on the OFF path against the previous revision; the gate is 1 %).
What `0.3` adds:

- `model_level` (`L1`..`L5`) and `contact_scope` (`C0`/`C1`/`C2`) in the
  manifest, both **required**. The level is what lets a reader tell "this model
  has no roll" from "the roll was never recorded"; the scope declares how far
  the road normal actually reaches into the physics.
- `geometry` gains `mass_kg`, `cg_height_m`, `wheel_radius_m`, `wheel_width_m`
  and `body_lwh_m`. A 3D renderer sizes the body box, the wheel cylinders and
  the CG vector from these — without them it would be guessing, and a guessed
  body box is a picture that is quietly wrong.
- five channels: `pose_zrp` (z, roll, pitch), `a_body` (ax, ay, az),
  `wheel_road_dz`, `wheel_road_normal`, `wheel_travel`.

`a_body` comes straight from the dynamics. It is not the derivative of
`v_body`: at `dt = 1 ms` that difference is mostly noise, and its magnitude
would change with the decimation setting.

**A level that does not have a quantity does not record the channel.** An L2
(7-DOF) run has no ride model, so it writes no `pose_zrp` at all rather than a
column of zeros — a reader must be able to tell absence from zero, and the
writer refuses a channel the declared level cannot produce.

The plant picks its level at construction, and the control contract
`u = [delta_rad, Fx_total_N]` is the same at every level:

```python
from vdsim_plant import VDSimPlant

plant = VDSimPlant(config="generic_sedan.yaml", level="L3")   # 14-DOF ride model
plant.reset([0, 0, 0, 22.0, 0, 0])
plant.enable_trace("run.vdtrace", seed=0, run_id="demo")
...
plant.finalize_trace()
```

`0.1` and `0.2` traces stay readable. A `0.3` file that omits any of the
required fields is an error, not a warning.

### Trace schema `0.4` — whether hardpoints were attached

`0.4` adds one required manifest field, `kinematics_attached` (bool). It is the
value the suspension-hardpoint attach actually returned for that run, not a
guess from which YAML files exist. The physics of L3 and L4 differ only when
hardpoints are attached, so this field is what tells a reader whether an L3/L4
trace carries suspension kinematics.

- A `0.4` trace without `kinematics_attached` is an error.
- A `0.3` or older trace reads with the value unknown (`None`) and one warning.
  It is never read as `false`.
- `level="L4"` with no hardpoints is refused when the session is built
  (`ValueError`), so no L4 trace can carry L3 physics. `VDSimPlant` has no
  hardpoint input and refuses `level="L4"` for the same reason. An
  `Experiment` config gets hardpoints with
  `kinematics: {front: mp_front_sedan, rear: ta_rear_sedan}`.

### Trace schema `0.5` — which channels the model actually computed

`0.5` records two channels at every level, `rp_rate` (rad/s, `[n,2]` = roll
rate, pitch rate) and `wheel_travel` (m, `[n,4]`), and adds one required manifest
field, `channel_validity`, saying per channel whether the model computed it.

- Values are `modeled` or `not_modeled@<level>`; the level must equal the
  manifest `model_level`.
- The source is `IVehicleDynamics::models_channel()`, a pure virtual every
  dynamics model declares in the core. It is not derived from the level number:
  L5 stroke exists only with `l5_spatial_suspension`.
- L1 and L2 (and K/L0) model neither channel: both are recorded as exactly
  `0.0` and marked `not_modeled@L1` / `not_modeled@L2`. A `0.0` there means
  "not modeled", not "flat ride"; readers and renderers label it "not modeled".
- L3 and above read the rates from the integrated roll and pitch states
  (`state.angular_velocity`), never by numerically differentiating anything.
- A `0.5` trace without `channel_validity` is an error, and the writer refuses
  non-zero data under a `not_modeled` channel.
- A `0.4` or older trace reads with validity `unknown` and one warning. It is
  never read as `modeled`. The `0.1`–`0.4` fixtures are unchanged;
  `golden_v0_5.vdtrace` is the `0.5` fixture.

## Campaigns — many runs from one declaration

A **run** is one simulation and one `.vdtrace`. A **campaign** is a set of runs
declared in a single YAML file. The runner owns only that upper layer: it adds
no field to the trace and calls the render CLI unchanged.

```yaml
# campaign.yaml
name: mu_sweep
base: step_steer          # configs/experiments/<name>.yaml, or an inline scenario
seed: 20260922            # root seed; each run's seed derives from it
duration: 4.0             # optional override [s]
sweep:
  grid:                   # orthogonal product; `list:` names combinations instead
    mu: [0.9, 0.7, 0.5]
  repeat: 1               # repeat each combination; only the seed moves
```

```sh
vdsim-campaign run campaign.yaml --jobs 4 --render overview
vdsim-campaign run campaign.yaml --resume      # continue where it stopped
vdsim-campaign run campaign.yaml --dry         # print the expansion, run nothing
python3 tools/vdsim_batch.py run campaign.yaml # same runner, historical path
```

Axis keys are dotted paths into the scenario document (`mu`, `vehicle.*`,
`tire.*` are applied after the preset resolves). Products:

```
campaigns/mu_sweep/
├── campaign.yaml      # the declaration as executed
├── index.jsonl        # run_id · axes · seed · status · param_hash · role · trace_path · started_at · wall_s
└── 000/run.vdtrace    # one trace per run; run_id is a zero-padded ordinal
```

```python
import vdsim_campaign as vc
for row in vc.read_index("campaigns/mu_sweep"):
    print(row["run_id"], row["status"], row["axes"])
```

Rules worth knowing before you rely on them:

- **Deterministic.** `seed = derive(root_seed, run_index)` — no wall clock, no
  pid. `--jobs 4` produces the same channel bytes as `--jobs 1`.
- **Failures are isolated, not hidden.** One run is one child process; a run
  that diverges or crashes costs one index line with `status` `diverged` /
  `error` / `killed`. There are no retries unless you ask for `--retry N`.
- **Resume verifies.** `--resume` skips a run only when its status is `ok`, its
  trace still exists, and its `param_hash` matches the declaration. If the
  declaration changed, the resume is refused.
- **The index is a lookup table, not a result database.** Metrics belong in a
  consumer script that reads the index.
- A render failure is not a run failure: `status` stays `ok` and
  `render_status` carries the error.

Full schema, index keys and the migration notes for the superseded runners:
[BATCH_RUNNER](docs/design/BATCH_RUNNER.md).

## Config — parts catalog & scenes (v0.3)

Vehicles are **blueprints** over `configs/parts/` (chassis, tire, drivetrain, …).
Runs are **scenes** (`configs/scenes/*.yaml`) with a `fleet[]` of blueprint + part
overrides. See [CATALOG_AND_PHYSICS](docs/CATALOG_AND_PHYSICS.md) for layout,
GUI API, drivetrain inertia, and opt-in LuGre tire.

## Control — real-time UDP runtime

`vdsim_realtime` is VDSim's real-time application: it runs the same core against
a wall clock and exchanges fixed-format binary UDP packets — **CMD**
(steer / throttle / brake) in, **STATE** (pose, velocities, Fz, slip, tire
forces, measured sensors, …) out. This is the SIL / HIL / co-sim boundary; the
GUI and any external controller are just clients of it.

```bash
build/bin/vdsim_realtime --scene=configs/scenes/two_vehicle_race.yaml \
    --cmd-port=7001 --state-port=7002 --rate=200
```
The wire format is the canonical VDS1 binary protocol (`cosim/cosim_protocol.hpp`;
contract in [docs/vdsim_bridge_interface_requirements.md](docs/vdsim_bridge_interface_requirements.md)).
Python clients encode CMD / decode STATE through `cosim/protocol.py` to stay
byte-compatible.

## Conventions

SI units · body frame ISO 8855 RH (X forward, Y left, Z up) · world frame ENU ·
wheel index **FL = 0, FR = 1, RL = 2, RR = 3**.

## License

Apache-2.0 (core / kinematics / tools / validation / FMI export). FMI 2.0 headers
are BSD-2-Clause (Modelica Association). Third-party deps (Eigen / yaml-cpp /
spdlog / GoogleTest) keep their own licenses; fetched via CMake FetchContent.
