v0.2 — drivetrain module

Status: implemented (2026-06-06). Engine rotational inertia reflected to the wheels via final_drive_ratio²; open diff couples half-shafts through carrier inertia (core/include/vdsim/drivetrain_inertia.hpp). Set engine_rotational_inertia: 0 for legacy wheel-only spin-up.

Problem found (2026-06-05)

Under a hard power-on turn the inside driven wheel spins up far too easily, and on steering release it hooks up with a large thrust imbalance that yaws the car back out of the corner (a noticeable "reverse steer"). This was traced to a missing drivetrain inertia, not the low-speed handling.

Measured (sedan, RWD, open diff, throttle 0.5, ~0.8 g left turn): - inside rear (RL) vertical load drops to ~1086 N while the outside (RR) carries ~5533 N (lateral transfer); - with the ideal open diff splitting torque equally, RL receives ~375 N·m but can only react ~mu·Fz·R ≈ 347 N·m, so the net ~28 N·m accelerates it; - the only resisting inertia is the wheel inertia I_wheel ≈ 0.5·m_unsprung·R² ≈ 1.3 kg·m², so RL spins up at ~20 rad/s² and reaches ~66 rad/s (surface speed ~22 m/s at vx ≈ 11 m/s) — a 2× overspeed; - on steer release the load returns to RL, the spun-up wheel develops ~2300 N (vs ~1190 N on RR) → ~1100 N thrust imbalance → yaw out of the turn, and ax jumps ~1.1 → 2.1 m/s².

Root cause

core/src/seven_dof_dynamics.cpp (and bicycle_dynamics.cpp) integrate each driven wheel as an independent inertia:

domega[i] = (Td[i] + Tb[i] - fx_kin[i]*R) / I_wheel[i]

with Td = throttle·max_motor_torque·final_drive_ratio split by the diff. There is no engine/transmission rotational inertia and no carrier coupling, so: - the engine+flywheel inertia reflected to the wheel (I_engine·final_drive², on the order of several kg·m²) is missing — the dominant term resisting spin-up; - the open differential's kinematic constraint (carrier speed = mean of the two wheel speeds, with the engine inertia at the carrier) is absent, so spinning one wheel does not have to accelerate the engine or counter-rotate the other wheel.

Net effect: effective driven-wheel inertia is ~5× too small → spin-up ~5× too fast.

v0.2 fix (proposed)

Add a drivetrain module: 1. Engine/transmission rotational inertia I_engine, reflected to the wheels via final_drive_ratio² (and gear ratio when a gearbox is added). 2. A proper differential model: - Open: carrier ω = ½(ωL + ωR); engine inertia acts at the carrier so a single unloaded wheel cannot run away without spinning the engine. - Locked / LSD: torque bias vs speed difference (the current bias model is a reasonable start; couple it to the carrier/engine inertia). 3. Optional: a simple engine torque–speed curve and idle/redline so Td is not a flat throttle·max_torque.

Re-validate ISO 7401/4138/3888-2 and the acceleration/brake checks after adding inertia — throttle response will become (correctly) slower, so the benchmark numbers in docs/VALIDATION.md will shift and need re-baselining.

Belongs with the v0.2 component-workshop work (engine/motor torque–RPM + efficiency maps), so the inertia and torque curve land together.