Assumptions & limitations

A model is trustworthy partly because its boundaries are stated. This page lists what each dynamics rung (Ld1–Ld3, plus the Ld4 hardpoint add-on) represents and what it does not, so that a result is never read outside its validity envelope.

Rung names follow the theory chapters: Ld1-Bicycle, Ld2-SevenDOF, Ld3-FourteenDOF, Ld4 hardpoint kinematics.

Per-rung validity envelope

Legend: yes = modeled, no = not modeled, text = modeled with the stated limitation.

Effect	Ld1	Ld2	Ld3	Source
Path / heading kinematics	yes	yes	yes	theory 04–06
Tire lateral force from slip	yes	yes	yes	theory 03
Per-wheel forces	no	yes	yes	theory 05–06
Combined slip (friction ellipse)	per axle: host friction-circle rescale of the axle force (skipped when the tyre model provides combined slip itself, e.g. MF2002 or LuGre)	yes	yes	theory 03, 04 §4.9, 25
Load transfer	longitudinal only (quasi-static, one-step lag on a_x); no lateral	quasi-static	dynamic	theory 04, 05–06
Roll / pitch / heave	no	quasi-static roll / pitch estimate; no attitude or heave state	yes	theory 05–06
Suspension transients	no	no	yes	theory 06
Suspension kinematics from hardpoints	no	no	only with Ld4 hardpoints attached	theory 13–14
Driveline (engine / gearbox / differential)	flat motor torque split by drive_type; opt-in engine map + gearbox; no differential (axle average)	flat motor torque; opt-in engine map + gearbox; open / locked / LSD differential	as Ld2 (through its inner Ld2)	theory 04, 05, 22
Aerodynamics	drag + downforce split to the axles (four keys or aero.elements, with the drag pitch moment)	as Ld1, halves per axle	as Ld1, per wheel (element y split by each axle's track); added to tyre loads only, does not press the suspension	theory 26; params.hpp aero_*, air_density

Aerodynamics on L5 and the shared inputs (0.8.0)

• Every aero path uses air_density (default 1.225 kg/m³); aero.elements places each element at its own point; the four-key and element forms cannot be mixed (theory 26).
• L5 (free 3D) applies aero as a body wrench: each element at its own point, the four-key lift at the front and rear axle (ground height), and four-key drag at the CG unless aero_drag_height is set (theory 20 §20.3).
• L5 0.8.1 returns equal-and-opposite drive/brake torque reactions through the chassis. The axle keys are drive_reaction_front, drive_reaction_rear, brake_reaction_front, and brake_reaction_rear; drive defaults to sprung and brake defaults to unsprung.
• unsprung currently resolves to the equivalent chassis route. An explicit unsprung target on a hard-joint DAE path warns once per process and produces the bit-identical sprung result. The DAE knuckle route and its steady-speed pitch issue remain 0.8.2 work.
• Spatial-strut load transfer uses a whole-system height derived from cg_height, which still denotes sprung-mass height. Its axle transfer is about 1–3% above the analytical target; the cg_height meaning and R2 revalidation remain 0.8.2 work.

Ld4 is not a separate plant without hardpoints

Selecting level L4 without attaching suspension hardpoints is rejected at session build time: without hardpoints the plant is bit-identical to Ld3. Trace manifests record kinematics_attached so that a stored run shows which one it was.

Global assumptions

• Rigid bodies — sprung and unsprung masses are rigid; no structural compliance.
• Road input — flat by default. Graded, banked, rough (ISO 8608 PSD) and split-μ surfaces enter through a contact provider; see Tire contact & interface.
• Tire transient — the Magic Formula is steady-state. First-order relaxation length is available but off by default; LuGre / brush and belt-transient models are separate options (19, 21).
• No tire thermal or wear state. The Magic Formula coefficient set is isothermal; turn-slip, inflation-pressure and thermal terms are omitted. The only temperature state in the core is the optional brake-fade model of the actuator layer.
• Friction — a scalar μ scale, with an optional anisotropic ellipse (mu_aniso) and split-μ via the contact provider.
• Fixed-step integration — results depend on the substep size. See Numerical integration and the next section.

Known numerical limitation: first-order load channel

The state integrator is RK4, but some forcing terms are held constant over the four RK4 stages of a substep. The most visible one is the load-transfer forcing in Ld2 (seven_dof_dynamics.cpp, marked P3-7 in the source). As a result, wheel loads, pitch and roll converge first-order in the substep size, not fourth-order.

Practical meaning:

• Yaw rate and lateral acceleration are accurate at the default substep.
• Pitch and roll are the least accurate outputs. Do not build a reward, cost or estimator target on pitch or roll without checking convergence at your substep.
• The measured convergence tables are in the RL guide's accuracy section (RL guide §6); this page does not repeat the numbers.

What this means for results

• Use the lowest rung that contains the effect you study. A result outside a rung's envelope (for example, dynamic load transfer on Ld2) is an artifact, not a finding.
• Verified is not validated. Agreement with reference solvers is verification; matching a real vehicle is a separate claim. See Validation.
• Sub-limit is not limit. Linear-region agreement does not certify the saturated region.

Out of scope (by design)

VDSim is an experimental research plant. It is not a production sign-off tool and not a validated real-vehicle digital twin, and it makes no commercial tire-product parity or commercial K&C claim. See Validation — Honest limitations and the roadmap.