São Paulo World
OpenRoad Dynamics · technical reference

Motor Vehicle Dynamics

The mathematics of an open-source vehicle physics engine: every model, equation, constant and assumption as it is implemented, and how each one is checked.

Engine: OpenRoad Dynamics, C++20, MIT licence · Source: github.com/ZRosserMcIntosh/Vehicle-Dynamics · Revision of 25 October 2026 (171 automated tests)

Source on GitHub ▶ Drive it in the browser

Abstract

OpenRoad Dynamics is a free, engine-agnostic vehicle physics core written in C++20 and released under the MIT licence. It drives the cars, motorcycles, bicycles and e-scooters of São Paulo World in the browser (compiled to WebAssembly). It also ships an Unreal Engine 5 plugin, which has not yet been compiled against Unreal. This document derives and states every model the core solves, exactly as the source code implements it, at a fixed step of 1/240 s or 1/360 s:

  • a 6-degree-of-freedom rigid chassis;
  • wheel–ground contact by multi-point ray sampling of an arbitrary ground;
  • a linearly implicit unsprung-mass suspension, guided by double-wishbone or MacPherson linkages solved from their pivot geometry (camber and toe curves, roll centres and jacking, anti-dive, motion ratio);
  • a reduced Pacejka Magic Formula tyre with relaxation-length transient slip, combined slip, camber, a one-node thermal model and compounds;
  • one implicit linear system coupling engine, clutch, gearbox, differentials, wheel spin and longitudinal slip, with a stick/slip active set for friction elements;
  • an ISA atmosphere and aerodynamics with ride-height-sensitive downforce and a wing that stalls (Viterna–Corrigan);
  • driver aids that act only through actuators;
  • body-hull contact for rollover;
  • a constrained multibody single-track model reproducing the Meijaard et al. (2007) bicycle benchmark to 12 significant digits;
  • a two-mass occupant model for crash survivability;
  • level-of-detail traffic.

Each chapter ends with what the model leaves out. Chapter 16 lists what is validated and what is not.

How to read this. Equations are transcribed from the source, and each chapter names its files under src/core/. Constants are given as they appear in the code. Some statements are interpretation by the author of this document rather than a direct transcription of the code; those are set in amber-edged boxes marked Interpretation, and what a model leaves out is in red-edged boxes marked Not modelled. Notation is local to each chapter where symbols would otherwise collide.

1Conventions and notation

The core uses SI units and double precision throughout (Real = double). Axes follow ISO 8855:

  • \(x\) points forward, \(y\) to the left and \(z\) up, right-handed;
  • positive yaw is to the left;
  • gravity is the world vector \(\mathbf g = (0,0,-g)\), with \(g = 9.80665\ \mathrm{m/s^2}\).

Orientations are unit quaternions (Hamilton convention) mapping body to world:

$$q_1\otimes q_2=\big(w_1w_2-\mathbf u_1\!\cdot\!\mathbf u_2,\ \ w_1\mathbf u_2+w_2\mathbf u_1+\mathbf u_1\times\mathbf u_2\big),\qquad R(q)\,\mathbf v=\mathbf v+w\,\mathbf t+\mathbf u\times\mathbf t,\quad \mathbf t=2\,\mathbf u\times\mathbf v .$$

Four scalar helpers recur throughout:

$$\operatorname{clamp}(x,a,b),\qquad \operatorname{sign}(x)\in\{-1,0,1\},\qquad \operatorname{smoothstep}(x)=s^2(3-2s),\ s=\operatorname{clamp}(x,0,1),\qquad \operatorname{approach}(c,t,\Delta)=c+\operatorname{clamp}(t-c,-\Delta,\Delta).$$

The last one is the engine's universal rate limiter.

SymbolMeaningUnit
\(M\)total vehicle mass, unsprung masses includedkg
\(I_b=\operatorname{diag}(I_{xx},I_{yy},I_{zz})\)principal inertia about the CoM, body frame (no products of inertia)kg m²
\(\mathbf x_o,\ \mathbf x_{cm},\ \mathbf c\)body-origin position, CoM position, CoM offset in the body framem
\(\mathbf v,\ \boldsymbol\omega\)CoM velocity and angular velocity, both in the world framem/s, rad/s
\(\hat u=R(q)\hat z\)body up axis in the world–
\(\Delta t\)vehicle steps
\(F_z,\ F_x,\ F_y,\ M_z\)tyre load, longitudinal and lateral force, aligning momentN, N m
\(\kappa,\ \alpha,\ \gamma\)longitudinal slip, slip angle, inclination (camber) angle–, rad, rad
\(\omega_i,\ r_i,\ I_w\)wheel spin, rolling radius, wheel inertiarad/s, m, kg m²
\(x,\ \dot x,\ L\)suspension compression (0 at full droop, \(L\) at full bump), its rate, travelm, m/s, m

2The simulation step

One call to Vehicle::step(Δt) runs a fixed sequence (vehicle.cpp):

  1. Assists. The driver's input becomes actuator commands: steering angle, throttle, per-wheel brake torque, clutch and gear. These are computed from sensors read off the previous state; no aid acts on the chassis directly.
  2. Per wheel:
    • steer angle and heading;
    • contact rays against the ground;
    • the tilt fade (chapter 12);
    • the suspension, either the implicit unsprung degree of freedom or the algebraic massless wheel;
    • the contact frame and contact-point velocity;
    • camber.
  3. Tyre pre-pass: lateral transient slip, the longitudinal force at the start-of-step slip and its slope, low-speed damping and rolling resistance.
  4. Top-speed limiter, then one implicit solve for engine, gearbox, wheel spins and longitudinal slips together.
  5. Force assembly:
    • tyre forces at the patches;
    • inertial relief of the unsprung masses;
    • the tread-temperature update;
    • aerodynamics;
    • body-hull contact (only when tilted or airborne);
    • gravity.
  6. Chassis integration (internal mode), or hand the force and torque to a host physics engine (external mode).
  7. Fault check: any non-finite state restores the pre-step chassis, zeroes the forces and stops the car until it is reset.

The step is fixed. A FixedStepper accumulates frame time \(A\), runs \(n=\lfloor A/\Delta t\rfloor\) steps, and drops the excess beyond 16 steps per frame. It returns \(A/\Delta t\) as the render-interpolation factor. The tiers run at different rates:

  • The browser demo steps at 1/360 s.
  • The default for a game host is 60 Hz × 4 substeps = 240 Hz.
  • Level-of-detail tiers run at 120 Hz (LOD1) and 30 Hz (LOD2).

No step allocates memory; a test checks this after warm-up. Two runs from the same inputs are bit-identical.

Table 2.1. Which couplings are implicit and which are explicit or lagged.
Implicit (solved at the end-of-step state)Explicit or lagged by one step
Unsprung wheel: own spring, damper slope, own side of the anti-roll bar, bump stop, tyre radial stiffness and dampingAnti-roll bar partner's compression; body acceleration seen by the wheel; bump-stop engagement and damper branch (frozen at \(x_0,\dot x_0\))
Engine, gearbox, wheel spin, longitudinal slip, clutch/brake/differential friction (active set)Engine torque (evaluated at \(\omega_e^0\)); limited-slip capacity (uses the previous drive torque)
Lateral transient slip (backward Euler)Contact geometry (rays cast once, at the start-of-step pose); tyre lateral force; aero; body hull
—Chassis: semi-implicit (symplectic) Euler

3Rigid-body chassis

vehicle.cpp (integrateChassis, placeOnGround), math.hpp, fixed_step.hpp, host_frame.hpp

3.1 State and equations of motion

The chassis state is \((\mathbf x_o, q, \mathbf v, \boldsymbol\omega)\). Note that \(\mathbf x_o\) is the body origin, whereas \(\mathbf v\) is the velocity of the centre of mass, \(\mathbf x_{cm}=\mathbf x_o+R(q)\,\mathbf c\). With \(\mathbf F,\boldsymbol\tau\) the net force and the net torque about the CoM accumulated at state \(n\), the chassis obeys Newton–Euler in the world frame:

$$M\dot{\mathbf v}=\mathbf F,\qquad I_w\dot{\boldsymbol\omega}=\boldsymbol\tau-\boldsymbol\omega\times I_w\boldsymbol\omega,\qquad I_w=R\,I_bR^{\top},\qquad \dot q=\tfrac12\,[0,\boldsymbol\omega]\otimes q .$$

3.2 Integration

The scheme is semi-implicit (symplectic) Euler. Velocities are updated first, and positions then use the new velocities:

$$\begin{aligned} \mathbf v_{n+1}&=\mathbf v_n+\frac{\Delta t}{M}\,\mathbf F\\ \boldsymbol\omega_{n+1}&=\boldsymbol\omega_n+\Delta t\;R_nI_b^{-1}R_n^{\top}\big(\boldsymbol\tau-\boldsymbol\omega_n\times R_nI_bR_n^{\top}\boldsymbol\omega_n\big)\\ \mathbf x_{cm,n+1}&=\mathbf x_{cm,n}+\Delta t\,\mathbf v_{n+1}\\ q_{n+1}&=\frac{\tilde q}{\lVert\tilde q\rVert},\qquad \tilde q=q_n+\tfrac{\Delta t}{2}\,[0,\boldsymbol\omega_{n+1}]\otimes q_n\\ \mathbf x_{o,n+1}&=\mathbf x_{cm,n+1}-R(q_{n+1})\,\mathbf c \end{aligned}$$

Three details matter:

  • The CoM is integrated, not the origin, so rotation about an offset CoM is exact.
  • The quaternion is renormalised every step.
  • The gyroscopic term is explicit.

Interpretation. With an explicit gyroscopic term, free spin about the intermediate principal axis can slowly gain energy. For a car on its wheels this is irrelevant; it would matter only for a long tumble.

The body acceleration used by the wheels (chapter 5) is a backward difference, \(\mathbf a=(\mathbf v_{n+1}-\mathbf v_n)/\Delta t\) and \(\boldsymbol\alpha=(\boldsymbol\omega_{n+1}-\boldsymbol\omega_n)/\Delta t\). It is therefore one step old when the next step uses it. Telemetry reports four derived quantities:

  • kinetic energy \(E_k=\tfrac12M\lVert\mathbf v\rVert^2+\tfrac12\boldsymbol\omega^{\top}I_w\boldsymbol\omega\) (wheel spin excluded);
  • pitch \(-\arcsin(\hat x_b\cdot\hat z)\);
  • roll \(\arcsin(\hat y_b\cdot\hat z)\);
  • the uprightness \(\hat z_b\cdot\hat z\), which is −1 on the roof.

3.3 Gravity and the unsprung masses

Gravity \(M\mathbf g\) acts on the total mass at the CoM, and the chassis is integrated with the total mass and inertia. Each unsprung wheel has its own vertical degree of freedom (chapter 5). Its acceleration along the suspension axis is returned to the body as an inertial relief force, \(\mathbf f_i=-m_u\ddot x\,\hat u\). Along that axis the whole-vehicle momentum balance is then exact:

$$M\,\mathbf a_{\text{body}}\cdot\hat u=\textstyle\sum\mathbf F_{\text{tyre}}\cdot\hat u+M g_u-\sum m_u\ddot x .$$

The wheel's weight appears only in the wheel's own equation, so nothing is counted twice.

3.4 Placing a car and host coupling

Static placement. Placing a car on the ground is analytic.

  • Static wheel loads come from the lever rule between the first and last axle, with left/right split \((c_y-y_r)/(y_l-y_r)\). Intermediate axles each take \(W/n_a\).
  • Each wheel's static compression is \(x_s=\operatorname{clamp}((F_z-m_ug-F_p)/k,0,L)\) and its tyre deflection is \(p_s=F_z/k_t\). Its hardpoint must therefore sit \(r-p_s+(L-x_s)\) above the ground.
  • A least-squares fit of height, pitch and roll to those heights (rows \([1,-x_{hp},y_{hp}]\), small angles) places the body.
  • Reset then settles the car for 0.5 s on the brakes.

External chassis mode. The core can hand \((\mathbf F,\boldsymbol\tau)\) to a host rigid body, such as Unreal's Chaos, instead of integrating itself. With \(k\) substeps per host step \(H\), the core integrates a private copy of the chassis and returns the impulse-equivalent mean:

$$\bar{\mathbf F}=\frac1H\sum_{j=1}^{k}\mathbf F_j\,h,\qquad\bar{\boldsymbol\tau}=\frac1H\sum_{j=1}^{k}\boldsymbol\tau_j\,h .$$

When the host's pose differs from the core's prediction by \(\Delta=(\mathbf h_P-\mathbf h_H)\cdot\hat u_H\), each wheel keeps its absolute position as long as \(|\Delta|\le 0.05\) m:

$$x\leftarrow x+\Delta,\qquad \dot x\leftarrow\dot x+(\mathbf v_{h,P}-\mathbf v_{h,H})\cdot\hat u_H .$$

The suspension absorbs the host's integration error instead of the tyre. Conversion to Unreal mirrors \(y\) and scales lengths by 100:

  • polar vectors: \(\mathbf v'=100\operatorname{diag}(1,-1,1)\mathbf v\);
  • axial vectors: \(\boldsymbol\omega'=(-\omega_x,\omega_y,-\omega_z)\);
  • quaternions: \(q'=(w,-x,y,-z)\).

Tests show the following:

  • External mode with the same integrator reproduces internal mode to \(10^{-9}\).
  • A different host integrator stays within 1 % over 8 s.
  • A 60 Hz host with 4 substeps matches a 240 Hz internal run within 1 %.

Not modelled. Products of inertia; implicit gyroscopics; the gyroscopic coupling of the spinning wheels; drivetrain reaction torque on the body (squat from torque reaction). Drive and brake reactions reach the body only through the tyre forces at the contact patches.

4Wheel–ground contact

vehicle.cpp (sampleContact), ground.hpp/.cpp, ground_cache.hpp/.cpp, tire.cpp (texture)

The ground is anything that answers a ray query. GroundQuery::raycast(origin, direction, maxDistance) returns:

  • a hit point and distance;
  • a normal;
  • surface properties;
  • an identifier.

The demo implements it three ways:

  • a flat plane;
  • a height function, which iterates \(t\leftarrow(h(\mathbf o+t\mathbf d)-o_z)/d_z\) six times, with normals from central differences, \(\varepsilon=0.01\) m;
  • a measured heightfield of São Paulo.

4.1 Geometry of a wheel

The suspension is a straight slider along the body \(z\) axis. The hardpoint \(\mathbf h\) is the wheel-centre position at full bump, and the wheel travels down \(-\hat u\) from it:

$$\mathbf c(x)=\mathbf h-\hat u\,(L-x),\qquad \mathbf h=\mathbf x_o+R(q)\,\mathbf h_{\text{body}} .$$

Contact rays are cast along \(-\hat u\), the body's own down axis.

  • Each ray starts 0.15 m above the hardpoint plane, at an offset \((s,l)\) in the wheel's heading and lateral directions.
  • Rays are \(0.15+L+r+0.05\) m long.
  • A hit's distance below the hardpoint plane is \(d_k=t_{\text{hit}}-0.15\).

The heading is \(\hat e_h=R(q)(\cos\delta,\sin\delta,0)\). The contact frame projects it onto the ground normal \(\hat n\):

$$\hat e_x=\frac{\hat e_h-\hat n(\hat n\cdot\hat e_h)}{\lVert\cdot\rVert},\qquad \hat e_y=\hat n\times\hat e_x,\qquad \mathbf v_P=\mathbf v+\boldsymbol\omega\times(\mathbf p_{\text{patch}}-\mathbf x_{cm}),\qquad v_x=\mathbf v_P\cdot\hat e_x,\ v_y=\mathbf v_P\cdot\hat e_y .$$

4.2 Footprint sampling and envelope probes

A single ray per wheel makes a car feel every pebble as a spike. The patch is therefore sampled at offsets in units of its half-length \(a\) (default 0.09 m) and half-width \(b\) (default 0.10 m). Every patch sample gets weight \(w_s=1/n_{\text{patch}}\), so on a flat road the samples sum to exactly the tyre's stiffness.

SamplesLayout \((s/a,\ l/b)\)Used by
1\((0,0)\)LOD1 traffic
5\((0,0),(\pm1,0),(0,\pm1)\)LOD0 default
8perimeter of a 3×3 gridquality option
9full 3×3 gridquality option

Envelope probes let a wheel feel an edge before the patch reaches it. They are added only with the unsprung wheel and more than one patch sample: up to three per side, at

$$s_{\pm j}=\pm\max(f_j r,\ a+0.01),\qquad f=\{0.40,\ 0.55,\ 0.70\},$$

and they test penetration radially against the tyre's circle rather than against the flat footprint (§5.2).

Interpretation. On flat ground a probe at \(f_jr\) touches only when the static deflection exceeds \(r(1-\sqrt{1-f_j^2})\), that is \(0.084r\), \(0.165r\) or \(0.286r\). At normal loads (about 14 mm of deflection on a 0.33 m tyre) no probe touches, so the probes cost nothing on a smooth road.

4.3 Surface micro-texture

Cobbles and paving are a procedural height added under each sample, with amplitude \(A\), wavelength \(\lambda\), variation \(V\) and a hash \(\rho_{ij}\in[0,1)\) of the stone cell:

$$h_{\text{tex}}(x,y)=A\big(1-\operatorname{clamp}(V,0,1)\,\rho_{ij}\big)\sin^2\!\frac{\pi x}{\lambda}\,\sin^2\!\frac{\pi y}{\lambda},\qquad d_k\leftarrow d_k-\frac{h_{\text{tex}}}{\max(\hat u_z,0.2)} .$$

The texture moves the contact point but not the normal.

4.4 The ground prefetch cache

Ray casts into a game world are expensive and must happen on the game thread. Before each frame, the core therefore asks for one strip of ground per wheel. The strip runs along the wheel's horizontal velocity (or heading below 0.5 m/s):

  • its half-width is \(e=\max(a,b)+0.15\);
  • its length is \(\lVert\mathbf v_h\rVert T+2e\), with horizon \(T=1.5/60\) s.

The strip is sampled in two passes:

  1. A coarse line of rays at about 0.35 m spacing.
  2. If the line is rough, a 3-line grid at about 6 cm spacing. Rough means any miss, roughness above 0.05, a second difference \(|z_i-\tfrac12(z_{i-1}+z_{i+1})|\) above 4 mm, or a normal change above 0.03 rad. The grid is capped at 120 rays per strip.

Queries are answered from the strip in one of two ways:

  • From a single line: \(z\) and \(\hat n\) are interpolated, then extended sideways along the interpolated normal, which preserves road camber:
    $$z=z_\ell-\frac{n_xo_x+n_yo_y}{\max(n_z,0.2)} .$$
  • From a grid: bilinear interpolation, with \(\hat n=\operatorname{normalize}(\hat z-\hat e_\parallel z_u-\hat e_\perp z_w)\).

A query outside every strip is counted as a miss and extrapolated from the nearest strip, so a wheel never falls through the world. The cache matches direct ray queries within 10 % using at least three times fewer rays.

Not modelled. A toroidal car tyre: the profile is a circle in the wheel plane, and the lateral extent is the flat footprint. Patch growth with load. Contact geometry is sampled once per step, at the start-of-step pose. The 5- and 8/9-sample layouts differ by about 30 % on sharp edges; this is documented but not calibrated.

5Suspension and the unsprung mass

vehicle.cpp (per-wheel loop, damperForce), vehicle_def.hpp (SuspensionDef, AxleDef), setup.cpp

At full fidelity each wheel has a vertical degree of freedom, its compression \(x\), and it is integrated linearly implicitly. The tyre's radial stiffness (about 250 kN/m) and the wheel's small mass (about 40 kg) give a wheel-hop mode near 14 Hz. That stiffness is why the scheme is implicit.

5.1 Damper, spring, anti-roll bar and bump stops

The damper is two-stage (slow and fast) with a knee speed \(v_k\). Velocity is positive in bump:

$$F_d(v)=\begin{cases}c_s\,v,&|v|\le v_k\\[2pt]\operatorname{sign}(v)\,\big[c_s v_k+c_f(|v|-v_k)\big],&|v|>v_k\end{cases}\qquad c_s=\begin{cases}c_{\text{bump}}&v>0\\ c_{\text{reb}}&v\le0\end{cases}$$

Defaults: bump 3000 and rebound 4500 N·s/m, fast equal to slow, knee 0.1 m/s. At \((x_0,\dot x_0)\) the suspension force, positive pushing the body up, is linearised in the end-of-step rate \(\dot x_1\) using \(x_1=x_0+\Delta t\,\dot x_1\):

$$F_s(\dot x_1)=A_s+B_s\dot x_1,\qquad A_s=F_p+kx_0+k_{\text{arb}}(x_0-x_o)+F_d(\dot x_0)-c\,\dot x_0\ \big[+k_b(x_0-L)\big]_{x_0\gt L}\big[+k_bx_0\big]_{x_0\lt0},$$ $$B_s=K_s\Delta t+c,\qquad K_s=k+k_{\text{arb}}\ [+k_b\ \text{when a stop is engaged}] .$$

The symbols, with their defaults:

  • \(F_p\): preload;
  • \(k\): wheel rate, 35 kN/m;
  • \(k_b\): bump-stop rate, \(3\times10^5\) N/m;
  • \(c=\partial F_d/\partial v\) at \(\dot x_0\);
  • \(k_{\text{arb}}\): the anti-roll bar rate, acting on the difference from the axle partner's compression \(x_o\) at the start of the step.

The anti-roll bar is therefore implicit on the wheel's own side and lagged on the partner's, which makes the result independent of wheel order.

5.2 The tyre as a radial spring

Each contact sample \(k\) has a penetration \(p_k\) and a sensitivity \(\sigma_k=-\partial p_k/\partial x\):

  • Patch sample (flat footprint): \(p_k=(L-x)+r-d_k\), with direction the ground normal \(\hat n_k\) and \(\sigma_k=1\).
  • Probe (radial): \(\mathbf d=\mathbf c-\mathbf P_k\), \(p_k=r-\lVert\mathbf d\rVert\), with direction \(\hat\rho_k=\mathbf d/\lVert\mathbf d\rVert\) and \(\sigma_k=\max(0,\hat\rho_k\cdot\hat u)\).

With \(\varrho_k=\max(0,\hat\rho_k\cdot\hat u)\,\tau\), where \(\tau\) is the tilt fade of chapter 12, the samples in contact are summed:

$$P_0=\sum_k w_sp_k\varrho_k,\qquad P_{\text{prev}}=\sum_k w_sp_k^{\text{prev}}\varrho_k,\qquad W_{\text{act}}=\sum_k w_s\varrho_k\sigma_k .$$

The tyre's force along \(\hat u\) is then linearised with radial stiffness \(k_t\) and damping \(c_t\) (defaults 250 kN/m and 400 N·s/m):

$$F_{t,u}(\dot x_1)\approx A_t-B_t\dot x_1,\qquad A_t=k_tP_0+c_t\frac{P_0-P_{\text{prev}}}{\Delta t},\qquad B_t=(k_t\Delta t+c_t)\,W_{\text{act}} .$$

5.3 The implicit wheel update

Newton's law for the wheel mass \(m\) along \(\hat u\) uses the hardpoint's absolute acceleration, \(\mathbf a_{hp}=\mathbf a+\boldsymbol\alpha\times\mathbf r_{hp}+\boldsymbol\omega\times(\boldsymbol\omega\times\mathbf r_{hp})\), taken one step lagged, together with \(g_u=\mathbf g\cdot\hat u\):

$$m\,(\mathbf a_{hp}\cdot\hat u+\ddot x)=F_{t,u}-F_s+m\,g_u .$$

Backward Euler in velocity, with both forces linearised at the end of the step, gives one scalar equation per wheel with no iteration:

$$\boxed{\ \dot x_1=\frac{\dfrac{m}{\Delta t}\dot x_0-A_s+m g_u-m\,\mathbf a_{hp}\cdot\hat u+A_t}{\dfrac{m}{\Delta t}+B_t+B_s}\ },\qquad x_1=x_0+\Delta t\,\dot x_1 .$$

Contact is unilateral. If \(A_t-B_t\dot x_1\lt0\) the tyre would pull the road, so \(A_t\) and \(B_t\) are set to zero and the wheel is solved airborne. The per-sample forces are then recomputed nonlinearly at \(x_1\):

$$f_k=\tau\,\max\!\Big(0,\ w_s\big[k_tp_k+c_t\,(p_k-p_k^{\text{prev}})/\Delta t\big]\Big),\qquad \mathbf F_t=\sum_kf_k\hat\rho_k,\qquad \hat n=\frac{\mathbf F_t}{\lVert\mathbf F_t\rVert},\qquad \mathbf p_{\text{patch}}=\frac{\sum f_k\mathbf P_k}{\sum f_k},\qquad F_z=\max(0,\mathbf F_t\cdot\hat n) .$$

The full 3-D direction of \(\mathbf F_t\) is kept, so a kerb's slanted face pushes the wheel back as well as up. The chassis receives the tyre force and the inertial relief:

$$\mathbf F\mathrel{+}=\mathbf F_t-m\ddot x\,\hat u,\qquad \boldsymbol\tau\mathrel{+}=(\mathbf p_{\text{patch}}-\mathbf x_{cm})\times\mathbf F_t+(\mathbf h-\mathbf x_{cm})\times(-m\ddot x\,\hat u) .$$

The suspension force itself is internal and is not applied to the body.

5.4 The massless wheel (LOD1)

Distant cars use a rigid tyre and an algebraic suspension:

$$x=\max_k(L+r-d_k),\qquad F=F_p+k\min(x,L)+k_b\max(0,x-L)+F_d\!\Big(\frac{x-x_{\text{prev}}}{\Delta t}\Big)+k_{\text{arb}}(x-x_o),\qquad F_z=\max(0,F)\,\tau .$$

The load is applied along the mean normal of the samples within 5 mm of the deepest one.

5.5 Ride height and setup

The static compression \(x_{\text{ride}}=\operatorname{clamp}\big((F_z^{\text{static}}-mg-F_p)/k,0,L\big)\) is the reference for camber gain (chapter 6). The tuning garage converts setup-sheet units as follows:

Setup fieldEngine parameter
camber, toe (deg)staticCamber, staticToe in rad
caster (deg, steered wheels only)casterAngle in rad
camber gain (deg/cm)rad/m: \(\times\pi/180\times100\)
spring and ARB (N/mm)N/m: \(\times1000\)
bump/rebound, slow/fastdamper coefficients
ride height (mm)translates the hardpoint; travel and spring are unchanged

Two analytic checks hold:

  • The heave and wheel-hop frequencies of the reference sports car match the analytic quarter car: 1.728 / 1.728 Hz and 13.689 / 13.688 Hz.
  • The definition validator requires the springs and bump stops to carry \(1.6\,Mg/n_w\) per corner.

5.6 Linkage kinematics

kinematics.hpp/.cpp, vehicle.cpp (wheel loop), tests/test_kinematics.cpp

A wheel may be guided by a real linkage instead of a slider: a double wishbone (two A-arms on body pivots, ball joints on the upright) or a MacPherson strut (lower arm plus a strut that pivots at its top mount and telescopes), each with a tie rod and a coil spring. Points are given in the body frame relative to the wheel centre at the design position, for the left wheel; the right wheel mirrors \(y\).

Solved once. At construction the mechanism is solved over the travel by Newton's method, 41 samples: for each wheel-centre height \(s\) the lower arm's angle, the upper arm's angle (keeping the ball joints at the upright's fixed separation) or the strut's extension, and the upright's rotation \(\phi\) about its kingpin axis that keeps the tie rod at its length. A point fixed to the upright maps as \(\mathbf P=\mathbf L+R_\phi R_0(\mathbf P_0-\mathbf L_0)\), with \(R_0\) the minimal rotation taking the design kingpin axis to the current one. Each sample stores the wheel centre's scrub \((x_c,y_c)\), the camber \(\gamma\), the toe, the spring length and their derivatives. The step only interpolates. A geometry that cannot reach the travel or folds over is rejected as an invalid definition.

Every step. The compression stays the single, implicitly solved DOF of §5.3, but the wheel moves along the linkage's path. Two directions matter, per metre of compression:

$$\mathbf d=\Big(\frac{\partial x_c}{\partial s},\ \frac{\partial y_c}{\partial s},\ 1\Big),\qquad \mathbf d_p=\mathbf d+\boldsymbol\omega\times(\mathbf p-\mathbf c)=\Big(\frac{\partial x_c}{\partial s},\ \frac{\partial y_c}{\partial s}-r\,\frac{\partial\gamma}{\partial s},\ 1\Big)$$

\(\mathbf d\) is the wheel centre's path and \(\mathbf d_p\) the contact patch's: as the upright tilts along the camber curve, the bottom of the tyre swings sideways by \(r\) per radian, and for a typical short-long-arm layout that term is several times the centre's scrub. The wheel equation of §5.3 becomes

$$m\,|\mathbf d|^2\,\ddot x=\mathbf F_t\cdot\mathbf d_p+\mathbf F_{\text{tan}}\cdot\mathbf d_p-F_s+m\,\mathbf g\cdot\mathbf d-m\,\mathbf a_{hp}\cdot\mathbf d,$$

where \(\mathbf F_{\text{tan}}=F_x\hat e_x+F_y\hat e_y\) is the previous step's tyre traction. That one term is where the handling effects come from, with no separate "anti" parameters:

  • Jacking and the roll centre. A cornering force along a patch path with a sideways component pushes the outside wheel toward droop and the body is held up through the links. The front-view roll-centre height follows directly: \(h_{rc}=\tfrac{t}{2}\big(\partial y_c/\partial s-r\,\partial\gamma/\partial s\big)\), which has no singularity when the camber does not change.
  • Anti-dive and anti-squat. Pivot axes inclined in side view lean the path forward in bump; a braking force then pushes the front wheels toward droop. The same inclination on a rear axle is pro-squat, so rear axles use the opposite one.

The spring's motion ratio \(\rho(s)\), coil travel per wheel travel normalised to 1 at design, scales the wheel rate and the damping by \(\rho^2\): \(F_s=k\,\rho(s)\big(S(s)-S_{\text{droop}}\big)+\ldots\) with \(S=\int\rho\,ds\). Camber is \(\gamma_0\) plus the curve's change from design (replacing \(G(x-x_{\text{ride}})\) in §6.2); toe is the static value plus the curve's change (bump steer, and with roll, roll steer). The garage's ride height moves the operating point along the curves: lowering a car 20 mm puts its wheels 20 mm further into bump at rest, with the camber that comes with it.

Table 5.1. Kinematics checks (tests/test_kinematics.cpp).
CheckResult
3-D wishbone solve vs. an independent 2-D four-bar (circle intersection)camber and scrub agree to 1.4·10⁻⁵ over ±80 mm; MacPherson to 2·10⁻⁵
Roll centre from the path vs. the graphical construction (arm lines → instant centre → n-line)120.006 vs 120.000 mm; 55.90 vs 55.89 mm; 94.94 vs 94.94 mm
Steady 0.59 g turn, same springs and bars, roll centre at the ground vs. +95 mmroll gradient 2.54 → 2.12 deg/g; lateral load transfer unchanged within 8 %
Braking from 80 km/h, level pivots vs. 0.30 rad anti-divedive 1.69° → 1.06°; stopping distance 30.46 vs 30.46 m
Lowered 20 mm in the garagecamber at rest −0.01° → −0.59°, the curve's value at 20 mm
Kerb strike at 60 km/h, 240 vs 1000 Hzheave 13.1 vs 13.0 mm

The reference cars keep sliders, so the golden baseline of chapter 16 is unchanged. The Rosser Stella V8 and the five real-car approximations use linkages of the published types with representative coordinates (roll centres 57–112 mm).

Not modelled. Solid axles, trailing arms and multilink geometries as such (a multilink axle is approximated by the double wishbone). Bushing compliance and compliance steer. The traction work term is one step lagged and is not applied to sliders. The camber curve rotates the upright but does not yet tilt the contact samples. The damper is linearised at the start-of-step speed, with no iteration across the knee. Bump stops are linear, with no gap and no damping. The wheel equation neglects the rotation of \(\hat u\) within the step, including the Coriolis term.

6Steering and wheel geometry

vehicle.cpp (wheelSteerAngle, camber), assists.cpp (shapeSteer)

The driver's steer input \(s\in[-1,1]\) (positive to the left) maps to a road-wheel reference angle. There is no steering-wheel ratio or column model in the core. Shaping and rate limiting are described in chapter 11.

6.1 Per-wheel angle and Ackermann

Each steered wheel gets \(\delta=\delta_{\text{ref}}\,\delta_{\max,w}/\delta_{\max,\text{ref}}\). On the front axle a fraction \(A\) of ideal Ackermann is mixed in (default \(A=0.6\)), with wheelbase \(\ell\) and the wheel's lateral offset \(t\):

$$R=\frac{\ell}{\tan|\delta|},\qquad \delta_{\text{ideal}}=\arctan\frac{\ell}{\max(R\mp t,\ 0.1)},\qquad |\delta|\leftarrow(1-A)|\delta|+A\,\delta_{\text{ideal}}$$

The minus sign is for the inner wheel. Toe is added last (positive is toe-in): \(\delta\leftarrow\delta-\text{toe}\) on the left and \(\delta+\text{toe}\) on the right. Unsteered wheels get only toe.

6.2 Inclination: camber from geometry and roll

With \(\varsigma=+1\) for a left wheel and \(-1\) for a right one, the wheel's tilt in the body frame combines three terms:

  • static camber \(\gamma_0\) (negative tilts the top inward);
  • linear camber gain \(G\) with travel;
  • caster \(\theta_c\) acting through the steer angle.
$$g=\varsigma\big[\gamma_0+G(x-x_{\text{ride}})\big]+\sin\theta_c\sin\delta .$$

The axle direction is rotated into the world and measured against the contact normal:

$$\hat a=R(q)\,(-\sin\delta\cos g,\ \cos\delta\cos g,\ -\sin g),\qquad \gamma=-\arcsin\big(\operatorname{clamp}(\hat a\cdot\hat n,-1,1)\big) .$$

Body roll and road camber therefore enter through \(R(q)\) and \(\hat n\): a car rolled by \(\phi\) with no static camber sees \(\gamma=-\phi\). The tyre model then uses \(\gamma\) (chapter 7). On a wheel with a real linkage (§5.6) the camber curve replaces \(G(x-x_{\text{ride}})\), and the toe gets the linkage's bump-steer curve, so roll steer appears when the car rolls.

Not modelled. A scrub radius and caster trail at the contact patch: steering rotates the wheel about body \(z\) at the hardpoint, even though a linkage defines a kingpin axis for its own bump-steer solve. Steering compliance. Ackermann on rear-steered axles.

7The tyre model

tire.hpp, tire.cpp, tire_generator.cpp, setup.cpp (compounds, pressure, camber model), vehicle.cpp (call sites)

The tyre is a reduced Pacejka Magic Formula (Pacejka 2012, ch. 4) with:

  • first-order relaxation-length transient slip (ch. 7);
  • combined slip by MF 5.2/6.x cosine weighting functions;
  • load sensitivity;
  • camber thrust and a camber peak-grip law;
  • a one-node tread-temperature model.

It is not a full MF 6.x coefficient set: there are no \(S_H/S_V\) shifts and no .tir files. That would fit behind the same interface later.

7.1 The Magic Formula

$$y(x)=D\sin\!\Big(C\arctan\big(Bx-E\,(Bx-\arctan Bx)\big)\Big),\qquad E\le1 .$$

The peak is set by \(D\), the shape by \(C\) and the curvature by \(E\), and the initial slope is \(BCD\). Throughout, \(B\) is chosen as \(B=K/(CD)\), so the slip stiffness \(K\) is an input parameter that stays fixed whatever the friction does.

7.2 Slip without division by speed

The textbook slips, \(\kappa=(\omega r-v_x)/|v_x|\) and \(\tan\alpha=-v_y/|v_x|\), are singular at a standstill. The core never evaluates them. Slip exists only as the state of two relaxation equations, whose steady states are those textbook values:

$$\sigma_x\,\dot\kappa+|v_x|\,\kappa=r\omega-v_x,\qquad\qquad \sigma_y\,\frac{d(\tan\alpha)}{dt}+|v_x|\tan\alpha=-v_y .$$

The relaxation lengths default to \(\sigma_x=0.15\) m and \(\sigma_y=0.45\) m. At \(v_x=0\) each state integrates the carcass deflection divided by \(\sigma\), so a parked tyre behaves like a spring of stiffness about \(K/\sigma\). That gives exact standstill holding on a slope without any \(\varepsilon\) in a denominator. The lateral state is integrated by backward Euler, which is unconditionally stable:

$$(\tan\alpha)_{n+1}=\frac{(\tan\alpha)_n-\Delta t\,v_y/\sigma_y}{1+\Delta t\,|v_x|/\sigma_y},\qquad |\tan\alpha|\le10,\qquad \alpha=\arctan(\tan\alpha) .$$

The longitudinal state is solved simultaneously with the wheel spin and the drivetrain (chapter 8). Because the relaxation equations have no damping at rest, a load-proportional damper that fades out with speed holds a stopped car without chatter:

$$c_d=d_{ls}\,F_z\max\!\Big(0,\ 1-\frac{\sqrt{v_x^2+v_y^2}}{v_{\text{fade}}}\Big),\qquad d_{ls}=3.0\ \tfrac{\mathrm{N\,s/m}}{\mathrm N},\ v_{\text{fade}}=3\ \mathrm{m/s};\qquad F_y\leftarrow F_y-c_dv_y .$$

The same damper enters the longitudinal wheel equation through \(c_d(r\omega-v_x)\).

7.3 Load sensitivity and pure slip

Peak friction falls linearly with load (the role of MF \(p_{Dx2}\) and \(p_{Dy2}\)):

$$df_z=\frac{F_z-F_{z0}}{F_{z0}},\qquad \mu_x=\max\big(0,\mu_{x0}(1+p_{\mu x}df_z)\big),\qquad \mu_y=\max\big(0,\mu_{y0}(1+p_{\mu y}df_z)\big) .$$

Defaults: \(\mu_{x0}=1.10\), \(p_{\mu x}=-0.08\), \(\mu_{y0}=1.05\), \(p_{\mu y}=-0.10\), \(F_{z0}=4000\) N. Each pure-slip force is defined by its own \(D\), \(K\) and \(B\):

$$\text{longitudinal:}\quad D_x=\mu_xs_xF_z,\quad K_x=k_xF_z,\quad B_x=\frac{K_x}{C_xD_x},\quad F_{x0}=y(\kappa;B_x,C_x,D_x,E_x)$$ $$\text{lateral:}\quad D_y=\mu_ys_yF_z,\quad K_y=c_KF_{z0}\sin\!\Big(2\arctan\frac{F_z}{c_{KL}F_{z0}}\Big),\quad B_y=\frac{K_y}{C_yD_y},\quad F_{y0}=y(\alpha;B_y,C_y,D_y,E_y)$$

Defaults: \(k_x=18\), \(C_x=1.65\), \(E_x=0.10\), \(c_K=16\), \(c_{KL}=1.9\), \(C_y=1.35\), \(E_y=-0.40\). The cornering stiffness \(K_y\) saturates with load, peaking at \(F_z=c_{KL}F_{z0}\); this is the MF 6.x form, without the camber term. The grip multipliers \(s_x\) and \(s_y\) carry the surface, temperature and camber effects of §§7.5–7.7.

Interpretation. For the reference sports car's front tyre at \(F_z=F_{z0}=3600\) N, these formulas give:

  • \(K_y=47.5\) kN/rad and \(B_y=8.88\);
  • a peak lateral force at a slip angle of about 12.7°;
  • a peak longitudinal force at \(\kappa\approx0.153\);
  • at \(\kappa=1\) (a locked or spinning wheel), 0.67 of the peak.

The 12.7° peak is generous for a road tyre. It follows from \(E_y=-0.4\).

7.4 Combined slip and aligning moment

Each force is attenuated by the other slip through MF cosine weighting functions, without shifts:

$$G_{x\alpha}=\cos\!\big(r_{Cx1}\arctan(B_{x\alpha}\alpha)\big),\quad B_{x\alpha}=r_{Bx1}\cos\!\big(\arctan(r_{Bx2}\kappa)\big),\qquad F_x=G_{x\alpha}F_{x0}$$ $$G_{y\kappa}=\cos\!\big(r_{Cy1}\arctan(B_{y\kappa}\kappa)\big),\quad B_{y\kappa}=r_{By1}\cos\!\big(\arctan(r_{By2}\alpha)\big),\qquad F_y=G_{y\kappa}F_{y0}$$

Defaults: \(r_{Bx1}=13\), \(r_{Bx2}=9.7\), \(r_{By1}=10.6\), \(r_{By2}=7.8\), \(r_{C\cdot1}=1\). No friction ellipse is imposed explicitly. A test checks that \((F_x/\mu_xF_z)^2+(F_y/\mu_yF_z)^2\le1.02\) over a grid of slips. The same quantity, under its square root, is the "grip used" readout in the demo.

The aligning moment is a pneumatic trail that collapses linearly with slip, plus a camber twisting term:

$$t_p=t_0\max\!\Big(0,1-\frac{|\alpha|}{\alpha_c}\Big),\qquad M_z=-t_pF_y+c_{tw}F_z\gamma,\qquad t_0=0.035\ \mathrm m,\ \alpha_c=0.20\ \mathrm{rad}.$$

7.5 Camber

Camber thrust. This is the motorcycle MF form (Pacejka 2012 §11.5; Sharp, Evangelou and Limebeer 2004). Camber and slip share one friction limit:

$$F_{y0}=D_y\sin\!\Big(\operatorname{clamp}\big[C_y\arctan(B_y\alpha-E_y(B_y\alpha-\arctan B_y\alpha))+C_\gamma\arctan(B_\gamma\gamma),\ \pm0.95\pi\big]\Big),\qquad B_\gamma=\frac{c_\gamma F_z}{C_\gamma D_y} .$$

This gives \(\partial F_y/\partial\gamma|_0=c_\gamma F_z\), which a test checks to 1 %.

Camber and peak grip (cars). A car tyre grips best at a small inclination into the turn. With \(\gamma_{\text{in}}=\gamma\tanh(\alpha/0.03)\), the camber measured toward the lateral force:

$$s_y\leftarrow s_y\max\!\big(0.5,\ 1-k_{\gamma y}(\gamma_{\text{in}}-\gamma_{\text{opt}})^2\big),\qquad s_x\leftarrow s_x\max\!\big(0.5,\ 1-k_{\gamma x}\gamma^2\big) .$$

The garage switches this model on with \(c_\gamma=0.8\), \(k_{\gamma y}=30\), \(k_{\gamma x}=11\) and \(\gamma_{\text{opt}}=2°\). That costs about 8 % of lateral grip 3° from the optimum, and about 3 % of braking grip at 3°. Stock definitions leave it off, so the golden benchmarks are unaffected. The measured effect: 100–0 km/h braking takes 39.0 m at 0° of camber and 42.6 m at −6°.

7.6 Surfaces

$$s_{\text{base}}=\max(0,f_s)\cdot\frac{1}{1+\max(0,c_{wsf}s_{aq})\,|v|}\cdot\big(1+W(g_{\text{wet}}-1)\big)\big(1+L(g_{\text{loose}}-1)\big)\cdot g_T$$

The terms are:

  • \(f_s\): the surface friction scale; dry asphalt is 1, and the demo's wet patches use 0.6.
  • \(c_{wsf}\): a crude speed fall-off for standing water, scaled by the compound's aquaplaning sensitivity \(s_{aq}\).
  • \(W\) and \(L\): wetness and looseness, each in [0, 1], weighting the compound's wet and loose-surface grip factors.
  • \(g_T\): the temperature factor of §7.7.

Surface roughness changes only the ground cache's sampling, not grip.

7.7 Tread temperature

Garage compounds carry a single thermal node. It heats from sliding power and rolling loss, and cools by convection that grows with speed:

$$C_{th}\dot T=\eta\big(|F_x(\omega r-v_x)|+|F_yv_y|\big)+0.5f_{rr}F_z|v_x|-(h_0+h_vv)(T-T_{\text{amb}}),\qquad T\in[-30,250]\ ^\circ\mathrm C$$

It is integrated explicitly with \(C_{th}=3000\) J/K, \(\eta=0.35\), \(h_0=5\) W/K and \(h_v=1\) W/(K·m/s). Grip follows a window around the optimum temperature:

$$\xi=\frac{T-T_{\text{opt}}}{\max(\Delta T_w,1)},\qquad g_T=\max\big(\,\xi\lt0\ ?\ 0.75:0.60,\ \ 1-k_T\xi^2\big) .$$

Tyre warmers start the tread at a chosen temperature. In the tests, cold slicks reach 0.74 g on the skidpad.

7.8 Compounds and pressure

Table 7.1. Compound multipliers and windows, as implemented. Values are representative, not data for any product.
CompoundμstiffnesswetaquaplanelooseTopt °Cwindow °CkTσy×
off-road0.850.700.950.801.3045500.081.3
all-season0.950.901.050.901.0545450.081.05
street1.001.001.001.001.0060450.101.0
sport1.081.100.951.100.9575350.120.95
semi-slick1.181.250.751.600.7085300.150.9
slick1.301.350.454.000.5895250.200.85
rain1.000.951.150.401.0050250.181.0

Pressure is a set of static multipliers around 2.2 bar, with \(\delta p=\operatorname{clamp}((p-2.2)/2.2,-0.5,0.6)\):

$$c_K\times\operatorname{clamp}(1+0.4\delta p,0.6,1.4),\quad k_t\times\operatorname{clamp}(1+0.8\delta p,0.5,1.6),\quad \sigma_y\times\operatorname{clamp}(1-0.3\delta p,0.7,1.3),\quad \mu\times(1-0.15\delta p^2-0.03\delta p),\quad f_{rr}\times\operatorname{clamp}(1-0.5\delta p,0.6,1.6).$$

On the reference sports car the compounds give the following peak lateral acceleration:

Compounddrywetgravel
off-road0.76 g0.40 g0.62 g
street0.83 g0.47 g0.50 g
slick0.94 g0.22 g0.37 g
rain0.79 g0.56 g0.50 g

7.9 Parameters from a tyre size

A generator turns a size string \(W/AR\,R\,D\) plus a category into a parameter set, using round textbook-range scalings (Pacejka 2012 ch. 3–4; Milliken and Milliken 1995) rather than a fit to any product. With \(w=W/1000\), \(f_w=W/225\) and \(f_p=55/AR\):

$$R_u=\tfrac{0.0254D}{2}+w\tfrac{AR}{100},\quad k_z=250\,000\,f_w^{0.7}f_p^{0.5},\quad c_K=16f_w^{0.4}f_p^{0.35}s_c,\quad k_x=18f_p^{0.2}s_c,\quad \sigma_y=1.8w\sqrt{AR/55},\quad \sigma_x=0.4\sigma_y,$$ $$t_0=0.15\sqrt{2R_u\delta},\quad m=18+0.9(D-15)+0.03(W-205),\quad I=0.6\,mR_u^2,\qquad \delta=F_{z0}/k_z .$$

7.10 Standing water and hydroplaning

tire.hpp/.cpp (hydroplaningSpeed, hydroplaneLift, waterDrag), vehicle.cpp

A surface can carry standing water of depth \(h\). The wedge of water in front of the patch carries a dynamic pressure \(\tfrac12\rho_w v^2C_L\); the tyre rides up onto it when that reaches the inflation pressure \(p\):

$$v_p=\sqrt{\frac{2p}{\rho_wC_L}},\qquad C_L=0.643\quad\Longleftrightarrow\quad v_p\,[\text{km/h}]=6.35\sqrt{p\,[\text{kPa}]}$$

which is Horne's NASA rule for water deeper than the tread clears (94 km/h at 220 kPa). The share of the patch on water ramps with depth past what the tread of depth \(d\) carries away and with speed past half of \(v_p\):

$$\lambda=\operatorname{clamp}\!\Big(\frac{h-h_0}{h_1-h_0}\Big)\,S\!\Big(\frac{v/v_p-0.5}{0.5}\Big),\quad h_0=0.5\,\text{mm}+0.1d,\ h_1=1\,\text{mm}+0.4d,\qquad \mu\leftarrow\mu\,(1-0.95\lambda)$$

with \(S\) the smoothstep. Pushing the water aside costs a displacement drag on the car at the patch, whatever the tyre's grip, and the lifted load, acting at the front of the patch where the wedge is, spins the wheel down:

$$F_w=\tfrac12\rho_wC_D\,w\,h\,v^2\ (C_D=0.75),\qquad \tau_w=-\lambda F_z\,a\,\operatorname{sgn}\omega .$$

Interpretation. In 10 mm of water the reference car still steers at 50 km/h (0.36 vs 0.37 rad/s dry) and doesn't at 130 km/h (0.007 rad/s), its front tyres spun down 33 m/s short of road speed. A 20 m puddle under one side at 100 km/h turns it 4.1° toward the water, hands off. The displacement drag is the method certification uses for contaminated runways (EASA AMC 25.1591).

Not modelled. MF shifts, ply-steer and conicity. Load dependence of \(C\) and \(E\). The κ-induced side force \(S_{Vy\kappa}\). A full MF \(M_z\), and overturning and rolling moments. Relaxation lengths that vary with load or slip. Rigid-ring belt dynamics. A two-node thermal model, wear, and the pressure–temperature coupling. A measured partial-hydroplaning curve and tread-pattern effects (§7.10 uses a smooth ramp). In the implicit wheel solve the longitudinal force is linear in κ about the start-of-step value, with its slope clipped at zero past the peak. This favours stability over exactness on the falling side of the curve.

8Wheel spin and the drivetrain

drivetrain.hpp/.cpp, linear_solve.hpp, vehicle.cpp (WheelSolveInput), aero.cpp (power correction)

Engine, clutch, gearbox, differentials, wheel spins and longitudinal slips are stiffly coupled. Integrating them separately at 240 Hz either oscillates or needs tiny steps. The core therefore assembles one linear system per step and solves it implicitly. Friction elements (clutch, brakes, limited-slip clutches) enter through a stick/slip active set.

8.1 Engine

Full-throttle torque \(T_{\text{wot}}(n)\) is piecewise-linear in a table of (rpm, N·m) points and held constant outside it. Throttle interpolates between the friction loss and full load:

$$L(\omega_e)=a+b\,\omega_e\ \ (\omega_e\gt0),\qquad T_e=\theta_{\text{eff}}\big[T_{\text{wot}}(n)+L\big]-L .$$

Defaults: \(a=18\) N·m and \(b=0.035\) N·m·s/rad. At closed throttle \(T_e=-(a+b\omega_e)\), which is the engine-braking model.

Idle governor (proportional, 250 rpm band, 35 % authority):

$$\theta_{\text{idle}}=0.35\operatorname{clamp}\!\Big(\frac{n_{\text{idle}}-n}{250},0,1\Big),\qquad \theta_{\text{eff}}=\max(\theta,\theta_{\text{idle}}) .$$

Rev limiter. Fuel is cut above \(n_{\text{lim}}\) and restored below \(n_{\text{lim}}-150\) rpm. Torque is evaluated at the start-of-step engine speed, and gearbox efficiency 0.93 multiplies positive torque in gear.

Altitude and temperature (naturally aspirated engines). Torque is scaled by the density-ratio core of SAE J1349:

$$k_P(h,T_C)=\frac{p(h)}{99\,000}\sqrt{\frac{298.15}{T_C+273.15}},\qquad T_{\text{wot}}\leftarrow T_{\text{wot}}\,\frac{k_P(h,T_C)}{k_P(0,15)} .$$

8.2 Unknowns and rows

The unknowns of one step are:

$$\mathbf x=\big[\underbrace{\omega_e,\ \omega_g,\ \omega_1\ldots\omega_W}_{\text{shaft speeds}},\ \underbrace{\kappa_1\ldots\kappa_W}_{\text{slips}},\ \underbrace{\lambda_G}_{\text{gear mesh}},\ \underbrace{\lambda_c}_{\text{stuck friction rows}}\big]$$

That is at most 33 unknowns, solved densely by Gaussian elimination with partial pivoting, with no heap allocation. The engine and gearbox-input shafts obey backward Euler:

$$\frac{I_k}{\Delta t}\omega_k-\sum_cj_{c,k}\lambda_c=\frac{I_k}{\Delta t}\omega_k^0+T_e\,\delta_{k,e}+\sum_{\text{slipping}}j_{s,k}f_s .$$

Each wheel row linearises its tyre force about the start-of-step slip \(\kappa_0\):

$$F_x\approx F_{x0}+K'(\kappa_1-\kappa_0)+c_d(r\omega_1-v_x),\qquad K'=\max\!\Big(0,\frac{\partial F_x}{\partial\kappa}\Big)\ \text{(central difference, }h=10^{-4})$$ $$\Big(\frac{I_w}{\Delta t}+r^2c_d\Big)\omega_1+rK'\kappa_1-\sum_cj_{c,i}\lambda_c=\frac{I_w}{\Delta t}\omega_0+T_{rr}-rF_{x0}+rK'\kappa_0+rc_dv_x+\sum j_{s,i}f_s$$

The rolling-resistance torque in that row has a smooth sign:

$$T_{rr}=-f_{rr}s_{rr}F_zr\tanh\!\Big(\frac{\omega r}{0.5}\Big),\qquad f_{rr}=0.012 .$$

Each slip row is the backward-Euler relaxation equation of §7.2:

$$\Big(\frac{\sigma_x}{\Delta t}+|v_x|\Big)\kappa_1-r\omega_1=\frac{\sigma_x}{\Delta t}\kappa_0-v_x .$$

The force the chassis receives is the linearised \(F_x\) evaluated at the solution. Wheel and chassis therefore see the same impulse.

8.3 Gearbox, differentials and the constraint block

Gear ratio \(G\) and per-axle final drive \(R_a\) with torque share \(s_a\) (\(\sum s_a=1\)) give one equality constraint whenever a gear is engaged:

$$\omega_g-\sum_a k_a(\omega_{a,L}+\omega_{a,R})=0,\qquad k_a=\tfrac12s_aGR_a .$$

Its multiplier \(\lambda_G\) applies \(+\lambda_G\) to the gearbox input and \(-k_a\lambda_G\) to each wheel of axle \(a\). That is exactly an open differential (equal left/right torque) and an open centre (split \(s_a\)). Locking and limiting are added as friction rows:

RowJacobian \(\mathbf j\)Capacity \(C\)
Clutch\(\omega_e-\omega_g\)\(e\,T_{c,\max}\), \(T_{c,\max}=600\) N·m
Brake \(i\)\(\omega_i\)\(T_{b,i}\) from the assist layer
Axle differential\(\omega_{a,L}-\omega_{a,R}\)open 0 · locked \(10^9\) · clutch LSD \(P_a+\rho\,|\lambda_G^{\text{prev}}GR_a|\,s_a\) with preload 80 N·m and ramps 0.45 (power) / 0.25 (coast)
Centre coupling (2 driven axles)\(\tfrac12(\omega_{FL}+\omega_{FR})-\tfrac12(\omega_{RL}+\omega_{RR})\)locked \(10^9\), or \(P_c+\rho_c|\lambda_G^{\text{prev}}G|\) with \(P_c=100\), \(\rho_c=0.3\)

Every active constraint enters with a tiny compliance \(\varepsilon=10^{-7}\) (rad/s)/(N·m), so redundant locks stay well-posed (for example, a locked differential with both brakes locked):

$$\begin{bmatrix}\mathbf M & -\mathbf J^{\top}\\ \mathbf J & -\varepsilon\mathbf I\end{bmatrix}\begin{bmatrix}\boldsymbol\omega\\ \boldsymbol\lambda\end{bmatrix}=\begin{bmatrix}\mathbf b\\ \mathbf 0\end{bmatrix}$$

Here \(\mathbf M\) includes the tyre-slip coupling, so it is not symmetric.

8.4 Stick and slip

Each friction row is either stuck (a constraint with multiplier \(\lambda\)) or slipping (a known torque \(f=-C\operatorname{sign}(v)\)). The active set is resolved per step:

  1. Initial state. A row whose relative speed \(|v_0|\lt10^{-3}\) rad/s starts stuck. Otherwise it keeps last step's state.
  2. Solve the system.
  3. Break loose. A stuck row with \(|\lambda|\gt C(1+10^{-9})\) starts slipping, with \(f=\operatorname{clamp}(\lambda,-C,C)\).
  4. Lock. A slipping row whose friction would reverse its motion (\(v_1f\gt0\)) becomes stuck.
  5. Repeat until nothing changes, at most 12 times.

Brakes therefore hold a car on a slope exactly, with no Coulomb chatter, and a clutch slips above its capacity and locks when the speeds match. Tests check these behaviours, the equal split of an open differential, and that engine work equals the rotational kinetic energy gained.

8.5 Top-speed limiter

An electronic limiter \(V\) fades the throttle over the last 2 %:

$$\theta\leftarrow\theta\Big[1-\operatorname{clamp}\Big(\frac{|v_x|-0.98V}{0.02V},0,1\Big)\Big] .$$

The real-car approximations use it at 250 km/h for the AMG S 63 and 210 km/h for the S 600 Guard.

Not modelled. Torsional compliance and backlash; torque converters; viscous couplings; torque vectoring; electric motors; turbo lag; stalling; humidity in the power correction. The limited-slip capacity lags one step.

9Brakes and ABS

assists.cpp (ABS stage), drivetrain.cpp (brake rows), setup.cpp (balance)

Each wheel's brake torque capacity is set by the pedal, a modulation factor \(p_w\in[0,1]\) and the handbrake:

$$T_{b,w}=b\,T_{\max,w}\,p_w+b_h\,T_{hb,w} .$$

It becomes a friction row on the wheel's spin (§8.4), so a locked wheel is a constraint \(\omega=0\), not an oscillating torque. Brake balance is the share of \(T_{\max}\) on the front axle; the garage sets \(\beta\in[0.2,0.85]\) and a pressure scale.

ABS. A slip-threshold controller with hysteresis. Slip is measured against the contact speed along the wheel heading, \(v_g\):

$$s=\frac{\omega r-v_g}{\max(|v_g|,1)},\qquad s^*=0.12$$
ConditionAction on \(p_w\)
pedal 0, wheel airborne, or \(v_g\lt2\) m/sapproach 1 at 10 /s
\(s\lt-s^*\)release at 8 /s
\(s\gt-0.6s^*\)re-apply at 4 /s
otherwisehold

The handbrake is never modulated. On the reference sports car, 100–0 km/h takes 37.96 m with ABS and 47.62 m locked (golden baseline). The ABS mean deceleration falls within 0.9–1.15 g.

Not modelled. Hydraulics, pad friction against temperature, and fade. ABS uses the true ground speed rather than an estimate.

10Aerodynamics and the atmosphere

aero.hpp/.cpp, vehicle.cpp (aero block), setup.cpp (weather)

10.1 Atmosphere

The atmosphere is the International Standard Atmosphere troposphere, with the actual air temperature used for density:

$$T_{\text{ISA}}=288.15-0.0065\min(h,11\,000),\qquad p=p_0\Big(\frac{T_{\text{ISA}}}{288.15}\Big)^{g_0/(R\cdot0.0065)},\qquad \rho=\frac{p}{R\,(T_C+273.15)},\qquad R=287.05\ \tfrac{\mathrm J}{\mathrm{kg\,K}} .$$

The exponent is about 5.256. Air is dry. Without a weather setting, \(\rho=1.225\) kg/m³.

10.2 Body forces

Airspeed is taken relative to a steady world wind \(\mathbf w\): \(\mathbf v_a=\mathbf v-\mathbf w\), with body components \(\mathbf v_b=R^{\top}\mathbf v_a\). From these:

$$\mathbf F_D=-\tfrac12\rho\,C_DA\,\lVert\mathbf v_a\rVert\,\mathbf v_a,\qquad \psi=\operatorname{atan2}(v_{b,y},v_{b,x}),\qquad q=\tfrac12\rho\max(0,v_{b,x})^2,\qquad F_{y,b}=-\tfrac12\rho\lVert\mathbf v_a\rVert^2A_s\sin\psi .$$

Drag and side force act at the CoM. The default is \(C_DA=0.70\) m². Downforce on each axle acts at the midpoint of that axle's hardpoints. It falls with aero yaw, and it rises as the floor gets closer to the ground until the floor stalls (Katz 1995):

$$F_{z,F/R}=q\,(C_LA)_{F/R}\cos^2\psi\;f_h(h),\qquad f_h=\min\!\Big(2.5,\ \Big(\frac{h_{\text{ref}}}{\max(h,0.005)}\Big)^{0.6}\Big[1-0.6\operatorname{smoothstep}\Big(\frac{h_{\text{stall}}-h}{0.015}\Big)\Big]\Big) .$$

Below the stall height the floor loses up to 60 % of its downforce over 15 mm. On the reference car at 180 km/h the floor gives:

  • 1457 N stock;
  • 1690 N lowered 40 mm;
  • 686 N once stalled.

10.3 A wing that stalls

The rear wing has span \(b\), chord \(c\) and aspect ratio \(AR=b/c\). Its angle of attack includes the body's pitch and heave motion:

$$\alpha=\alpha_{\text{set}}-\operatorname{atan2}\big(-v_{b,z},\max(v_{b,x},0.1)\big),\qquad a_{3D}=\frac{2\pi AR}{2+\sqrt{(AR/\kappa)^2+4}},\quad \kappa=\frac{a_{2D}}{2\pi}=0.95 .$$

The 3-D lift slope is the Helmbold/DATCOM form. Below stall the polar is linear lift with a quadratic drag bucket:

$$C_l=a_{3D}(\alpha-\alpha_0),\qquad C_d=C_{d\min}+k(C_l-C_l^*)^2 .$$

Past the stall angle \(\alpha_s=\alpha_0+C_{l\max}/a_{3D}\), lift and drag blend (over \(w=0.08\) rad, by smoothstep) into the Viterna–Corrigan post-stall model, anchored at the stall point with a 30 % lift drop:

$$C_l^{VC}=\tfrac{C_{d\max}}{2}\sin2\alpha+A_2\frac{\cos^2\alpha}{\sin\alpha},\qquad C_d^{VC}=C_{d\max}\sin^2\alpha+B_2\cos\alpha,$$ $$A_2=\frac{(C_{l,s}-C_{d\max}\sin\alpha_s\cos\alpha_s)\sin\alpha_s}{\cos^2\alpha_s},\qquad B_2=\frac{C_{d,s}-C_{d\max}\sin^2\alpha_s}{\cos\alpha_s} .$$

The section defaults are \(\alpha_0=-0.07\), \(C_{l\max}=1.9\), \(C_{l\min}=-0.8\), \(C_{d\min}=0.012\), \(k=0.008\), \(C_l^*=0.5\) and \(C_{d\max}=1.6\). With span efficiency \(e=0.85\), the wing's downforce and drag act at its aerodynamic centre:

$$C_{Di}=\frac{C_l^2}{\pi eAR},\qquad D_w=qSC_l\cos^2\psi,\qquad F_{D,w}=qS(C_d+C_{Di}) .$$

At 200 km/h the default garage wing (1.4 × 0.28 m) peaks at 1394 N at 24° and stalls to 920 N at 30°.

Not modelled. Pitch and roll sensitivity of the body coefficients beyond ride height. Aero yaw and pitch moments from drag and side force. Balance shift with yaw. Gusts, wakes and slipstream. Ground effect on the wing: a McCormick factor exists in the code but is not called. Humidity.

11Driver aids

assists.hpp/.cpp, presets.hpp

The aids are a layer between the driver and the car. They read the previous step's sensors and act only through the actuators a real car has: road-wheel angle, throttle, per-wheel brake torque, clutch and gear. Every preset drives the same physics; only the aids differ. Each step runs them in this order:

  1. steering (shaping, speed-sensitive range, countersteer, drift);
  2. a 0.3 s crossfade on preset changes;
  3. throttle rate limit;
  4. transmission and clutch;
  5. ABS;
  6. TCS;
  7. drift throttle trim;
  8. ESC.

11.1 Steering

The input is first shaped and rate-limited: \(u=\operatorname{sign}(s)|s|^{e}\), followed by an approach at the steering or return rate. In speed-sensitive mode (above 1 m/s) the stick's range is scaled, not clipped, to the lock that friction can use, plus a target front slip angle \(\alpha_T\):

$$R_{\min}=\frac{v^2}{\max(\hat\mu g,0.5)},\qquad \delta_{\text{lim}}=\min\!\Big(\delta_{\max},\ \arctan\frac{\ell}{R_{\min}}+\alpha_T\Big),\qquad \theta_f=\operatorname{atan2}(v_y+a\,r,\ v_x) .$$

The limit is asymmetric toward countersteer. The left and right limits are \(\max(\delta_{\text{lim}},\pm\theta_f+\alpha_T)\), clamped to \([0,\delta_{\max}]\). The countersteer aid (above 3 m/s) blends the angle toward \(\theta_f\), the direction the front axle is actually travelling, with weight \(c_{cs}\operatorname{smoothstep}((|\alpha_r|-0.06)/0.15)\). Here \(\alpha_r=\operatorname{atan2}(v_y-b\,r,v_x)\) is the rear slip angle.

11.2 Traction control

Full mode targets slip \(s_T=0.08\) and may cut all throttle; Sport targets 0.15 and cuts at most 80 %. Slip uses a 2 m/s floor on speed. TCS works in two ways:

  • Brake-based (diff-lock emulation). On each driven axle the faster wheel is braked by its excess slip:
    $$\epsilon=s_i-\max(s_{\text{least}},s_T),\qquad T^*=\min\!\Big(1,\frac{\epsilon}{0.3}\Big)\,0.35\,T_{b\max},$$
    approached at \(6T_{b\max}\) per second.
  • Engine cut. The cut grows by \(6\Delta t\,(s_{\max}-s_T)/s_T\) while slip exceeds the target and decays at 2 per second. The throttle becomes \(\theta(1-c)\).

11.3 Stability control

Above 5 m/s ESC compares the yaw rate with a linear single-track reference bounded by friction. The understeer gradient is fixed at \(K=0.002\ \mathrm{s^2/m}\):

$$r_{\text{ref}}=\operatorname{clamp}\!\Big(\frac{v\,\delta}{\ell+Kv^2},\ \pm\frac{0.85\,\hat\mu g}{v}\Big),\qquad \beta_{\text{ref}}=\frac{\arctan\!\big(\tfrac{b}{\ell}\tan\delta\big)}{1+(v/20)^2},\qquad \beta=\operatorname{atan2}(v_y,v)-\beta_{\text{ref}} .$$

From these it forms an oversteer measure \(O=\max\big(|r-r_{\text{ref}}|-d,\ 4(|\beta|-\beta_{\max})\big)\) (when the error is in the direction of the yaw) and an understeer measure \(U=|r_{\text{ref}}|-|r|-d\). The settings are:

  • Full: deadband \(d=0.05\) rad/s and \(\beta_{\max}=0.08\);
  • Sport: \(d=0.12\) rad/s and \(\beta_{\max}=0.20\).

When ESC intervenes:

  • Oversteer: it brakes the outer front wheel with \(\min(3000\,O,\ 0.6T_{b\max})\) N·m.
  • Understeer (above 10 m/s): it brakes the inner rear wheel with \(\min(2000\,U,\ 0.6T_{b\max})\).
  • In Full mode it also trims the throttle.

With ESC on, the reference car passes every amplitude of an FMVSS 126-style sine-with-dwell; with ESC off it fails at 7° and 9°.

Interpretation. \(K=0.002\ \mathrm{s^2/m}\) corresponds to an understeer gradient of about 1.1°/g. It is a fixed constant, not derived from the car.

11.4 Automatic gearbox and clutch

Upshift and downshift points move with the throttle pedal:

$$n_\uparrow=n_{\text{lim}}\operatorname{lerp}(0.55,0.985,\theta),\qquad n_\downarrow=n_{\text{lim}}\operatorname{lerp}(0.28,0.50,\theta) .$$

The rules around those points:

  • A braking downshift is allowed as soon as the lower gear fits under 88 % of the limiter.
  • Upshifts are held while the driven axle spins (slip above 0.3) or the car is drifting. The exception is a drift on the limiter, which upshifts if the next gear stays in the power band.
  • During a shift the auto clutch opens for the shift time (0.25 s), giving a torque gap. Under power it shifts clutch-to-clutch instead (engagement 0.55, throttle × 0.6). Downshifts blip to match revs.

The launch clutch engages with engine speed:

$$e=\operatorname{smoothstep}\!\Big(\frac{n-1.05n_{\text{idle}}}{\max(n_L-1.05n_{\text{idle}},100)}\Big),\qquad n_L=\max(2500,\ 1.5n_{\text{idle}}) .$$

11.5 Drift assist

This is an aid with no real-car equivalent: a cascade controller that holds a sideslip the driver chooses. The driver's steer sets the target angle and the throttle scales it, from half the angle at no throttle to all of it above 80 %:

$$\beta_T=-d\cdot\operatorname{lerp}\!\Big(0.5,1,\operatorname{clamp}\Big(\frac{\theta}{0.8},0,1\Big)\Big)\,\beta_{\max}\,\tau_u^{\,p},\qquad p=\frac{\ln(\beta_{1/2}/\beta_{\max})}{\ln0.5},\qquad \beta_{\max}=\min(1.0,\delta_{\max}) .$$

Here \(d\) is the drift direction and \(\tau_u\) is the steer input toward it. The cascade turns angle error into a wanted angle rate and then a wheel angle, with an integral trim:

$$\dot\beta^*=\operatorname{clamp}\big(-2.5(\beta-\beta_T),\ \pm\dot\beta_{\max}\big),\qquad \delta^*=\operatorname{clamp}\big(\theta_f+0.35(\dot\beta-\dot\beta^*)+I,\ \pm\delta_{\max}\big),\qquad I\in[-0.15,0.15] .$$

The rate limit \(\dot\beta_{\max}\) is:

  • 0.55 rad/s when straightening;
  • otherwise \(1.8(0.5+0.5P)\,\text{room}\), where \(P\) rises with throttle and "room" shrinks near the steering lock.

The output blends with the driver's steering by the engagement weight, with three exceptions:

  • it steps aside entirely for a donut, latched by full lock and throttle below 8.5 m/s;
  • it hands back 30 % of the steering while the handbrake is held;
  • it can only remove throttle, using a prediction 0.25 s ahead, capped at 60 % and scaled by the throttle.

Around the drift, the clutch helps:

  • The handbrake opens the auto clutch (on a driven wheel), so it locks the rear even with the throttle held.
  • A turn-in clutch kick (0.15 s, 2 s cooldown) breaks the rear loose from a keyboard input.
  • Revs are held at 88 % of the limiter while the clutch is open.

With the assist off, the same car simply spins.

Table 11.1. Presets.
FunSportDriftSimulation
Steeringspeed-sensitive, \(e\)=1.4, \(\alpha_T\)=0.10speed-sensitive, \(e\)=1.2, \(\alpha_T\)=0.14speed-sensitive, \(e\)=1.2, \(\alpha_T\)=0.14direct, linear
ABS / TCS / ESCon / Full / Fullon / Sport / offon / off / offoff / off / off
Countersteer (pad)0.60.2500
Drift assist001.00
Gearboxautoautoautomanual, auto clutch

Not modelled. State estimation: the aids read ground-truth speed. Gains are hand-set constants. ESC's understeer gradient is not derived from the car.

12Rollover

vehicle.cpp (hull construction, body contact, tilt fade), vehicle_def.hpp (BodyDef)

A car tipped onto its side used to be held up by tyre contacts found by casting along its own tilted down axis. It could never land on its side or roof. Two mechanisms fix this.

12.1 Tyre support fades with tilt

The tyre's support fades out by a smoothstep between about 53° and 70° of tilt, measured against the vertical (a kerb's face would otherwise trigger it) or, where the ground the wheel finds within its reach is itself steeper than about 25°, against that ground's mean normal \(\hat n_g\), whichever is better aligned: a car on a banking, a wall or inside a loop is on its wheels, not tipping over.

$$a=\max\big(\hat u_z,\ \hat u\cdot\hat n_g\big),\qquad t_c=\operatorname{clamp}\!\Big(\frac{a-0.34}{0.26},0,1\Big),\qquad \tau=t_c^2(3-2t_c) .$$

On a 70° face the tyres carry \(Mg\cos70^\circ\) and the body touches nothing (test). Hull points (§12.2) are probed straight down and, past 60° of tilt, also along the car's own \(-\hat u\), and the deeper of the two counts; a derived floor rises with the garage's ride height.

\(\tau\) multiplies every tyre sample force and the massless wheel's load.

12.2 The body hull

Each car has a hull of 17 points plus one per wheel, 21 for a car. Unset dimensions are derived from the wheels: 0.9 m overhangs, half-width = track/2 + 0.12 m, a floor 13 cm above the static ground, and a roof 1.15 m above the floor. The points are:

  • 12 box points: corners and side midpoints at the floor and at the belt line (55 % of the height);
  • 5 roof points: a narrower greenhouse at 80 % of the width and 30–65 % of the length, plus its centre;
  • the outer shoulder of each tyre, at \((x_{hp},\ y_{hp}\pm0.12,\ z_{wc}-0.7r)\), which is what a tipping car pivots on.

12.3 Contact

The hull is checked only when the car is tilted past about 31° (\(\hat u_z\lt0.86\)) or has no wheel on the ground, so normal driving neither pays for it nor queries it. Each point below the ground gets a penalty force:

$$k_{\text{pt}}=600M,\qquad c_{\text{pt}}=2(0.6)\sqrt{k_{\text{pt}}M/6},\qquad m_{\text{eff}}=\Big[\frac1M+(\mathbf r\times\hat n)\cdot I_w^{-1}(\mathbf r\times\hat n)\Big]^{-1}$$ $$k=\min\!\Big(k_{\text{pt}},\ m_{\text{eff}}\Big(\frac{0.5}{\Delta t}\Big)^2\Big),\qquad c=\min\!\Big(c_{\text{pt}},\ \frac{0.8\,m_{\text{eff}}}{\Delta t}\Big),\qquad f_n=\max\big(0,\ k\min(\delta,0.25)-c\,v_n\big)$$ $$\mathbf f=f_n\hat n-\mathbf v_t\frac{\mu f_n}{\lVert\mathbf v_t\rVert+0.3},\qquad \mu=0.5\cdot\text{frictionScale} .$$

The stiffness and damping bounds make the explicit contact stable for whatever mass and inertia a point sees: \(\sqrt{k/m_{\text{eff}}}\,\Delta t\le0.5\) is well inside the symplectic-Euler limit of 2.

Interpretation. With about six points carrying the car, the contact frequency is \(\omega=\sqrt{6k_{\text{pt}}/M}=\sqrt{3600}=60\) rad/s (about 9.5 Hz), and the static sinkage is \(g/3600\approx2.7\) mm.

Table 12.1. Rollover behaviour (tests and the browser smoke test).
CaseResult
Released on its roofsettles at \(\hat u_z=-1.00\), with about 5 hull points carrying its weight
Released at a static tiltsports car recovers at 65° and falls at 70°; S 600 Guard (tall, 4.2 t) falls at 65°; F1 car stays up at 65°
Sliding sideways into a 25 cm kerba bump at 15 km/h; over the roof at 45 km/h
Sliding sideways on flat asphalt at 80 km/hno roll
One-sided 0.9 m corkscrew rampsports car up at 50 km/h, over at 110 km/h; Guard over at 75 km/h; F1 car up at 120 km/h
Normal drivingthe hull never touches

Not modelled. Roof and pillar crush, and parts breaking off. Tyre sidewall forces (the fade stands in for them). Sharp ridges between hull points. Static friction of the body (sliding is regularised Coulomb). Injury from a rollover.

13Two-wheelers

single_track.hpp/.cpp, two_wheeler.hpp/.cpp, tests/test_single_track.cpp, tests/test_two_wheeler.cpp

A bicycle cannot be faked with a car model: it stays up because of steering geometry and gyroscopic and inertial coupling. So the two-wheeler is a separate constrained multibody model, derived from rigid bodies, joints and rolling contact, not from published linear matrices. The published matrices appear only in the tests, as an independent reference.

13.1 Bodies, joints and contact

The model has four rigid bodies in maximal coordinates (24 DOF):

  • the rear wheel \(R\);
  • the rear frame with a rigid rider, \(B\);
  • the front frame (fork and bars), \(H\);
  • the front wheel \(F\).

Three revolute joints connect them: the rear axle, the steer axis (tilted back by \(\lambda\)) and the front axle. Each joint is 5 constraint rows:

$$\text{point: }(\mathbf x_a+\mathbf r_a)-(\mathbf x_b+\mathbf r_b)=\mathbf 0,\qquad \text{axis: }\hat u_a\cdot\hat p_{b,j}=0\ \ (j=1,2) .$$

In the no-slip mode each wheel adds 3 rolling rows: the material contact point does not move. For a thin disc of radius \(R\) with axle \(\hat a\):

$$\mathbf g=-\hat z+\hat a\,a_z,\qquad \hat d=\mathbf g/\lVert\mathbf g\rVert,\qquad \mathbf v_i+\boldsymbol\omega_i\times(R\hat d)=\mathbf 0 .$$

Only the vertical row is holonomic. The constraint count is 15 + 6 = 21 rows on 24 DOF, which leaves the Whipple bicycle's three velocity degrees of freedom: forward speed, lean rate and steer rate.

13.2 Equations of motion and integration

The equations are constrained Newton–Euler at the acceleration level, with the velocity-product terms \(\boldsymbol\gamma\) of every constraint. They are solved densely:

$$\mathbf M\mathbf a=\mathbf F+\mathbf J^{\top}\boldsymbol\lambda,\qquad \mathbf J\mathbf a=-\boldsymbol\gamma\ \ \Rightarrow\ \ (\mathbf J\mathbf M^{-1}\mathbf J^{\top})\,\boldsymbol\lambda=-\boldsymbol\gamma-\mathbf J\mathbf M^{-1}\mathbf F .$$

The gyroscopic loads are \(-\boldsymbol\omega_i\times I_i^w\boldsymbol\omega_i\). Integration is classical RK4, with quaternions renormalised at every stage. Two mass-weighted projections then remove drift (Hairer, Lubich and Wanner, ch. IV.4):

$$\Delta\mathbf q=\mathbf M^{-1}\mathbf J_h^{\top}(\mathbf J_h\mathbf M^{-1}\mathbf J_h^{\top})^{-1}(-\mathbf C_h),\qquad \Delta\mathbf v=-\mathbf M^{-1}\mathbf J^{\top}(\mathbf J\mathbf M^{-1}\mathbf J^{\top})^{-1}\mathbf J\mathbf v .$$

The position projection runs up to 4 iterations, to \(|C|\lt10^{-14}\).

13.3 Validation against the bicycle benchmark

Meijaard, Papadopoulos, Ruina and Schwab (2007) give the linearised Whipple bicycle:

$$\mathbf M\ddot{\mathbf q}+v\,\mathbf C_1\dot{\mathbf q}+(g\mathbf K_0+v^2\mathbf K_2)\,\mathbf q=\mathbf f,\qquad \mathbf q=[\phi,\delta]^{\top} .$$

The test linearises the engine's nonlinear accelerations about upright running by central differences (\(h=10^{-6}\)). From that it recovers \(\mathbf M\), \(\mathbf C_1\), \(\mathbf K_0\) and \(\mathbf K_2\) and compares them with the published values. Critical speeds come from the characteristic quartic by Routh–Hurwitz:

  • weave: \(H_3=c_3c_2c_1-c_1^2-c_3^2c_0=0\);
  • capsize: \(c_0=0\).
Table 13.1. The engine against the published benchmark.
QuantityOpenRoad DynamicsPublishedDifference
Weave speed4.292382536339 m/s4.292382536341 m/s2.2·10⁻¹²
Capsize speed6.024262015383 m/s6.024262015388 m/s5.4·10⁻¹²
M, C₁, K₀, K₂ (worst entry, relative)——4.4·10⁻¹³
Static eigenvalues±3.131643248, ±5.530943718±3.131643248, ±5.5309437183.1·10⁻¹³ rel.
Eigenvalues at 0–8 m/s——≤ 2.3·10⁻¹²

In the time domain:

  • At 5 m/s (inside the self-stable band) a 0.05 rad lean decays, and the constraints hold to \(10^{-9}\).
  • At 3 m/s the bicycle weaves and falls.
  • With no drive, energy is conserved to \(10^{-10}\) J over 10 s.
  • A right steer torque first leans the bike left, which is counter-steer emerging from the physics.

13.4 Tyres for leaning wheels

The rideable vehicles replace rolling constraints with tyres. Each wheel has a toroidal crown of radius \(\rho\le0.9R\):

$$\hat d=\operatorname{normalize}\big(\hat a(\hat a\cdot\hat n)-\hat n\big),\qquad \mathbf r=(R-\rho)\hat d-\rho\hat n,\qquad p=-(\mathbf x_i+\mathbf r-\mathbf p_g)\cdot\hat n,\qquad F_z=\max(0,\ k_zp-c_z\,\mathbf v_P\cdot\hat n) .$$

The contact point therefore walks around the crown as the wheel leans. The tyre forces are the Magic Formula of chapter 7, with three differences:

  • Camber thrust is on. With camber, a leaning bicycle corners at a summed slip angle of 0.0011 rad instead of 0.0303 rad.
  • The relaxation states are updated once per step, before the RK4 stages (an operator split).
  • Rolling resistance acts as an axle moment.

With knife-edge tyres the model converges back to the no-slip benchmark.

13.5 The virtual rider

The rider acts only through handlebar torque, drive and brake torques, and a roll moment at walking pace. In lean mode the stick asks for a lean angle \(\phi^*\), limited by friction and by the tightest turn the lock allows:

$$\phi_{\max}=\min\!\Big(\phi_{\text{cfg}},\ \arctan(0.65\mu),\ \arctan\frac{0.65\,v^2\delta_{\text{lock}}\cos\lambda}{g\,w}\Big) .$$

An outer loop uses the point-mass lean equation \(\ddot\phi=(g/h)\phi-\tfrac{v^2}{hw}\delta\) to find the steer angle that produces a commanded lean acceleration \(-\omega_n^2(\phi-\phi^*)-2\zeta\omega_n\dot\phi\), with \(\omega_n=3\) rad/s and \(\zeta=0.9\):

$$\delta^*=\frac{w\big[g\tan\phi+h\big(\omega_n^2(\phi-\phi^*)+2\zeta\omega_n\dot\phi\big)\big]}{v^2\cos\lambda} .$$

An inner "arm" loop turns that into bar torque, relaxing its stiffness at speed:

$$T=k_{\text{arm}}\big[k_s(\delta^*-\delta)-c_s\dot\delta\big]+r\big[K_p(\phi-\phi^*)+K_d\dot\phi\big] .$$

The direct lean-error term has the counter-steer sign. To turn left at 20 m/s, the first bar torque steers right.

Around the rider sit the bike's own aids:

  • a power-limited motor;
  • a friction-circle ceiling on drive torque;
  • slip-based TCS and ABS, including a cornering limit;
  • wheelie and stoppie control;
  • a steering lock whose stiffness is bounded by step stability.

Measured results:

  • An ABS stop from 20 m/s takes 2.22 s, at 0.92 g.
  • Without stoppie control, a hard front brake at 11 m/s goes over the bars.
  • Without aids, full throttle on the motorcycle loops it.

Not modelled. Fork and swingarm suspension (the tyre's vertical stiffness stands in for it); frame compliance; rider body lean; contact between the ground and the foot, frame or bars; gearbox and clutch; fitted tyre data. The only external quantitative validation is of the no-slip model.

14Crash survivability

crash.hpp/.cpp, tests/test_crash.cpp

This is a game estimate built from published relations, not a validated crash simulation. The car's own collision response stays a rigid impulse; only the occupants see a crash pulse.

14.1 The crash pulse

An impact's change of velocity \(\Delta v\) in the body frame becomes a half-sine deceleration whose area is exactly \(\Delta v\):

$$a(t)=A\sin\big(\omega(t-t_0)\big),\quad 0\le\omega(t-t_0)\le\pi,\qquad A=\frac{\Delta v\,\omega}{2},\qquad T=\frac{\pi}{\omega} .$$

Each zone has its own pulse:

  • front: \(\omega=32\) rad/s, 98 ms, 0.9 m of crush space;
  • rear: \(\omega=28\) rad/s, 112 ms, 0.7 m;
  • side: \(\omega=45\) rad/s, 70 ms, 0.3 m.

If the crush needed, \(|\Delta v|\pi/(2\omega)\), exceeds the space, the pulse shortens to \(\omega'=\min(4\omega,\ \pi|\Delta v|/2x_{\max})\) and the excess becomes intrusion that closes the occupant's gaps.

14.2 The occupant

Each seat holds a torso and a head, each with a 2-D displacement relative to the seat. They are integrated by semi-implicit Euler at no more than 0.1 ms. Every restraint is a spring-damper per unit mass, \(s(\omega,\zeta)=-\omega^2x-2\zeta\omega\dot x\), engaging past its gap:

  • Torso, longitudinal:
    • muscle tone \(s(8,0.8)\);
    • seat back \(s(45,0.5)\);
    • belt after 3 cm of slack \(s(30,0.3)\);
    • front airbag past 15 cm \(s(26,0.5)\);
    • knee bolster (unbelted) \(s(30,0.2)\);
    • hard contact with the wheel or dash past the forward space \(s(180,0.2)\).
  • Torso, lateral:
    • belt hold;
    • door with side airbag \(s(70,0.4)\), or hard \(s(180,0.2)\) without one;
    • console or the other occupant \(s(60,0.4)\).
  • Head:
    • neck spring to the torso \(s(16,0.35)\), about 2.5 Hz;
    • head restraint;
    • front head airbag past 22 cm \(s(34,0.5)\), or hard contact;
    • sideways, a curtain airbag \(s(55,0.4)\).

14.3 Injury criteria and risk

$$\mathrm{HIC}_{15}=\max_{t_2-t_1\le15\,\text{ms}}(t_2-t_1)\Big[\frac{1}{t_2-t_1}\int_{t_1}^{t_2}a_{\text{head}}\,dt\Big]^{2.5}\qquad(a\ \text{in}\ g)$$ $$P_{\text{head AIS3+}}=\Phi\!\Big(\frac{\ln\mathrm{HIC}-7.45231}{0.73998}\Big),\qquad P_{\text{head AIS4+}}=\frac{1}{1+e^{\,5.02-0.00351\,\mathrm{HIC}}},\qquad P_{\text{chest AIS4+}}=\frac{1}{1+e^{\,5.55-0.0693\,A_{3\,\text{ms}}}}$$ $$P_{\text{life-threatening}}=1-(1-P_h)(1-P_c),\qquad P_{\text{fatal}}^{\text{Joksch}}=\min\!\Big(1,\Big(\frac{\Delta v_{\text{mph}}}{71}\Big)^4\Big)$$

The sources and limits:

  • The logistic curves are the NHTSA curves used before 2011.
  • The AIS3+ head curve is from NHTSA's 1999 report on improved injury criteria.
  • The Joksch (1993) statistic is a population average, reported beside the model and not combined with it.
  • The chest value is the highest 3 ms contiguous clip.
  • The reference limits are FMVSS 208: HIC₁₅ ≤ 700 and chest ≤ 60 g.
Table 14.1. Results (frontal barrier delta-V includes 10 % rebound).
CaseΔvchest 3 msHIC₁₅AIS4+verdict
30 km/h frontal, belted33 km/h19.8 g692.3 %walks away
56 km/h frontal, belted61.6 km/h40.9 g2167.5 %bruised
56 km/h, unbelted, no airbag61.6 km/h47.7 g4738100 %critical
80 km/h frontal, belted88 km/h66.0 g150568.4 %critical
30 km/h side, near, airbags30 km/h28.4 g1103.6 %bruised
30 km/h side, near, no airbags30 km/h52.0 g70318.8 %injured
Helmeted rider into a wall, 30 km/h30 km/h52.3 g44915.4 %injured

The model is calibrated only to the NCAP range at 56 km/h: chest 30–50 g and HIC 100–500. Everything else is a check that the rankings come out in the right order.

Not modelled. Neck, femur and tibia metrics. Rollover and vertical (spinal) injury. Submarining under the belt. Vehicle-specific structure (stiffness is per zone). The head's mass loading the torso.

15Level of detail and traffic

lod_manager.hpp/.cpp, traffic.hpp/.cpp

The engine runs three tiers of vehicle:

  • LOD0, the player's car: full fidelity.
  • LOD1, up to 16 nearby cars: the same Vehicle with massless wheels and one contact sample, at 120 Hz. Promoted within 150 m and demoted beyond 190 m.
  • LOD2, everything else: kinematic traffic at 30 Hz following the Intelligent Driver Model (Treiber, Hennecke and Helbing 2000).
$$a=a_{\max}\Big[1-\Big(\frac{v}{v_0}\Big)^4-\Big(\frac{s^*}{s}\Big)^2\Big],\qquad s^*=s_0+\max\!\Big(0,\ vT+\frac{v(v-v_l)}{2\sqrt{a_{\max}b}}\Big)$$

The parameters are \(T=1.4\) s, \(s_0=2.5\) m, \(a_{\max}=1.6\) m/s² and \(b=2.5\) m/s². The desired speed is limited by the lane's curvature ahead, measured as the Menger curvature of points 2 m apart:

$$v_0=\min\!\Big(v_{\text{des}},\ v_{\text{limit}},\ \sqrt{a_{\text{lat}}/\kappa_{\max}}\Big),\qquad a_{\text{lat}}=3.5\ \mathrm{m/s^2} .$$

A friction circle with \(\mu=0.9\) caps acceleration (not braking) in corners. LOD1 cars steer by pure pursuit, \(\delta=\arctan(2L\sin\eta/l_d)\) with \(l_d=\max(6,0.9v)\), and hold speed with a PI loop.

Promotion places the car analytically (§3.4) at the agent's speed and yaw rate. Measured on a 250 m curve at 70 km/h:

  • promotion changes speed and yaw rate by 0.000;
  • it causes at most 0.12 g of vertical jolt;
  • demotion moves the car by 0.25 m.

One player car, 16 LOD1 cars and 1000 LOD2 cars cost 0.7 ms per frame.

Not modelled. Lane changes and intersections in LOD2. Promotion of both cars on a collision. LOD3 (lane-graph agents without physics).

16Validation

tests/*.cpp (140 cases), benchmarks/baseline.csv, docs/benchmarks/

16.1 The golden baseline

Key results of the reference cars are stored in benchmarks/baseline.csv, and a test fails if any of them moves beyond its tolerance. A regression therefore cannot be hidden by quietly re-running benchmarks. A change to the baseline has to be an explicit, documented regeneration.

MetricValueTolerance
Sports RWD 0–100 km/h (Sport)4.554 s1 %
100–0 km/h with ABS / locked37.96 / 47.62 m1 %
Skidpad R400.9955 g1 %
Step steer at 80 km/h, yaw rate0.2629 rad/s1 %
Sine-with-dwell 9°, max sideslip0.5165 rad3 %
Kerb at 120 km/h (cached ground), max heave0.01085 m3 %
Cobbles at 40 km/h, RMS vertical0.02352 g2 %
Pothole at 60 km/h, RMS frame acceleration0.09393 g2 %
Heave / wheel-hop frequency1.72816 / 13.6891 Hz0.5 %
Hatch 0–100 km/h (Simulation) / skidpad8.625 s / 0.8613 g1 %
Drift, half lock / full lock, sideslip−16.41° / −31.67°5 %

16.2 Analytic and numerical checks

  • Heave and wheel hop against the analytic quarter car. Coast-down against \(v=v_0/(1+kv_0t/m)\). Free fall.
  • Understeer gradient within 20 % of the linear bicycle model built from the tyre's own cornering stiffness.
  • Drivetrain: equal open-differential split; engine work equal to the rotational energy gained; clutch slip above capacity.
  • Tyre: peak \(=\mu F_z\); combined slip inside the friction ellipse; camber slope \(=c_\gamma F_z\) to 1 %.
  • Time step: 120 Hz within 2 % of 1000 Hz for braking and yaw, and 3 % for 0–100 km/h.
  • Host coupling, determinism (bit-identical runs), no allocation after warm-up.
  • Fuzzing of inputs, vehicle definitions and corrupted ground: no NaN.
  • The bicycle benchmark to 12 digits (chapter 13).
  • The real-car approximations reproduce their published 0–100 km/h and top speeds within stated bands. For example: 911 Carrera S 3.8 s and 316 km/h; AMG S 63 3.2 s and 248 km/h (limited); F1 2.6 s.

16.3 What is not validated

The reference cars are fictional. Their plausibility envelopes (for example 0–100 km/h in 3.8–6.0 s, skidpad 0.85–1.12 g) guard against regressions; they are not claims about any real car. The real-car approximations use published specifications for the inputs, but the unpublished parameters are engineering estimates. Comparison with measured vehicle data (for example the BMW E90 data derived from SAE 2007-01-0818) is planned. The only external, independent quantitative validation today is the Meijaard bicycle benchmark, which covers the no-slip two-wheeler. The Unreal plugin has not been compiled against Unreal.

17Limitations

Gathered from the chapters above, these are the largest gaps between this model and a real vehicle, roughly in order of how much they matter to how a car feels:

  1. Rigid linkages, lagged couplings. The double-wishbone and MacPherson kinematics give camber and toe curves, roll centres, anti-dive and anti-squat, but the joints have no compliance (no compliance steer), there are no solid axles yet, and the traction's work on the suspension uses the previous step's force. The reference cars still use sliders.
  2. Reduced tyre model. There are no MF shifts or full aligning-moment model, and the thermal model has one node. Compound and generator values are representative, not fitted to data.
  3. No steering system. There is no column ratio, compliance, kingpin or trail, so force feedback would have to come from \(M_z\) alone.
  4. Explicit couplings. The body acceleration seen by the wheels lags one step. The anti-roll bar partner, limited-slip capacity and contact geometry are lagged, and the gyroscopic term is explicit. Convergence studies show these are small at 240–360 Hz, but they bound the usable step.
  5. Driver aids are game controllers reading ground truth, with hand-set gains, not models of production ECUs.
  6. Aero acts through ride-height factors only. There is no pitch or yaw sensitivity, wake or slipstream.
  7. Damage. With damage on, the body is a coarse node/beam structure (§19): about 110 nodes and one-dimensional beams, no panels, welds or material models, a rigid passenger cell, and no car-to-car contact. Parts break by simple rules read from it. Off (the default), rollover and crashes treat the body as rigid; crash survivability is an estimate either way.

18Showcases on the proving ground

web/ord_web.cpp (stunt park, weather, snapshots, shadow car, launches); the page's moose.js, crashlab.js, crumple.js, rewind.js

The browser demo puts the model through set pieces. Each is physics from the chapters above; the page only draws, drives a robot, or records.

18.1 Moose test (ISO 3888-2)

The lane is sized from the car's width \(W\): entry 12 m long and \(1.1W+0.25\) wide, a 13.5 m gap, an offset lane 11 m long and \(W+1\) wide whose right edge is 1 m left of the entry lane's left edge, a 12.5 m gap, and an exit lane \(\min(3,1.3W+0.25)\) wide. The body has to move across by at least \(1+W\approx2.8\) m within the gap. Doing that on the lane's centre line would need

$$a_y\approx\frac{4\,\Delta y\,v^2}{L^2}=\frac{4(2.8)(16.7)^2}{13.5^2}\approx17\ \text{m/s}^2\quad(1.7\,g\ \text{at 60 km/h}),$$

so a driver turns in while still inside the entry lane and crosses the gap yawed. The robot test driver follows such a line (cosine swings, tuned once in simulation) with the Stanley path-tracking law at the front axle, curvature feedforward a little ahead, and an inner loop that holds the road-wheel angle it asks for whatever the preset's steering shaping:

$$\delta=\arctan\!\big(l\,\kappa(s+0.08v)\,(1-0.001v^2)\big)+(\psi_r-\psi)+\arctan\frac{0.91\,e}{v+2}-0.069\,r .$$

It lifts off at the entry gate, as the standard asks. A cone touched or a rollover is a fail; the speed ladder adds 4 km/h a run.

18.2 The loop

To make the top a car needs \(v_t^2\ge gR_t\); energy then asks \(v_b^2\ge gR_t+2gH\) at the bottom, where the load is \(1+v_b^2/(gR_b)\). A circle (\(R_b=R_t=R\), \(H=2R\)) needs at least 6 g there, which bottoms any road suspension. The loop is a clothoid-entry teardrop: curvature rises linearly over 25 m, then follows the slope angle \(\theta\):

$$\rho(\theta)=R_b+(R_t-R_b)\frac{1-\cos\theta}{2},\qquad R_b=22\ \text{m},\ R_t=9\ \text{m},\qquad H=36.4\ \text{m}$$

and is the inside of a cylinder whose ribbon shifts 9 m sideways over its 136 m, so a car entering at \(\psi=\arctan(9/136)\) follows a straight line on the unrolled surface. On a concave curve the overhangs sink toward the surface by about \(x_f x_r/(2\rho)\) (2.75 m²/ρ for a 911), which is why small loops need high-riding cars. Every car in the demo makes it with lane keeping once fast enough (the 911 from ~80 km/h on full throttle, the 4.2 t Guard from ~125 km/h).

18.3 Rewind and the shadow car

The step is deterministic: a snapshot of the whole state (car, dummies, walls, latched inputs, the step remainder) plus the same frame times and inputs reproduces the state bit for bit (smoke test). Rewinding restores the last snapshot before the shown frame and replays to it. The shadow car is a second Vehicle fed the same inputs every step, with another setup or model, colliding with nothing.

18.4 Crash lab and dents

Tests put the car on a sled (full-width rigid barrier at 50, 56, 64 and 80 km/h; a pole at 32 km/h and 75°), record every 1/360 s step, and replay the impact at a tenth of real speed with the crush growing as the half-sine pulse's displacement \(d(t)=\tfrac12 d_{\max}(1-\cos\omega t)\), \(d_{\max}=0.85\min(\Delta v/\omega,\ \text{crush limit})\). The dent is drawn on the mesh: vertices behind the impact surface within the crush zone \(z=\max(0.35,2.2d)\) move in by

$$\Delta=d_{\max}\,e^{-r^2/R^2}\Big(1-\frac{s}{z}\Big)\quad(R=1.15\ \text{m wall},\ 0.8\ \text{side},\ 0.22\ \text{pole}),$$

plus buckling folds. It is a drawing of the crush model, not a soft-body simulation.

That depth was the first Realistic setting; Realistic is now the crash structure of §19, and the crash lab runs on it (its pulse is then measured, not assumed). The default, Cosmetic, is the game setting: a dent is \(d_c=0.08\,(1-e^{-d_{\max}/0.25})\) m over three quarters of the patch, the drawn displacement of any point is capped smoothly at \(0.08\tanh(|\Delta|/0.08)\) m so stacked hits flatten instead of folding the body in, there is no injury report, and a car left on its side or roof is set back on its wheels. The stored offsets stay exact, so switching modes redraws the same hits at the other depth. In Cosmetic the car drives the same afterwards.

18.5 Glass

Whether a storefront pane gives way is decided here (its fracture energy against the hit, §3); how it breaks is the Glass Dynamics engine's: the same engine and glazing library as the Glass Lab, run in a worker as the car approaches, firing a 1.5 t blunt impactor at the bumper's height and speed.

19Damage: crash structure and parts

src/core/include/ord/damage.hpp, src/core/src/damage.cpp, the hooks in vehicle.cpp; tests/test_damage.cpp; docs/architecture/damage.md

Off by default: without it the car is exactly the rigid body of the chapters above (the golden benchmarks do not move). With it on and nothing near, driving is bit-identical and makes no extra ground queries.

19.1 The structure

The body becomes a lattice built from the same box as the rollover hull (§12) and the crash structure's crush depths (§14): stations along the car (three cells in each crush zone, which reaches 0.3 m behind the front axle and 0.25 m ahead of the rear one; ~0.6 m cells along the cabin), four columns across (the outer skin and the cabin wall, the side crush depth inside it), floor and belt levels, and roof nodes over the greenhouse: about 110 nodes and 380 beams. The passenger cell is the rigid body itself (its nodes are anchored to it); the zones, doors, sills and roof are free nodes sharing 5% of the mass.

A beam of rest length \(\ell\) carries an elastic force until its yield force, then deforms plastically with linear hardening:

$$F=\frac{l-\ell}{\alpha},\qquad |F|\le F_y+H\,p\ \ \Rightarrow\ \ \text{else}\ \ \ell\leftarrow l-\operatorname{sgn}(F)\,\alpha\,(F_y+Hp),\quad p\mathrel{+}=|\Delta\ell|,$$

with \(\alpha\) its compliance (1% strain at full strength) and \(p\) its accumulated plastic deformation. Crushed to 15% of its length it is solid; stretched to 145% it tears. Strengths come from the crash structure: a zone of crush depth \(d\) and natural frequency \(\omega\) acts like a spring \(k=m\omega^2\) whose force reaches \(k\,d\) at full crush. Its eight rails take half of that, each yielding at 15% of its share and hardening linearly to it. The diagonals, cross members and verticals carry the rest as the zone folds. The roof's pillars yield at three times the car's weight in total, the FMVSS 216 requirement.

19.2 The solve

XPBD (extended position-based dynamics) solves the beams and contacts, and the rigid body takes part. At an anchored point \(r\) from the centre of mass, along \(n\), the body's generalised inverse mass is

$$w=\frac{1}{m}+(r\times n)^{\!\top} I^{-1}(r\times n),\qquad \Delta\lambda=\frac{-C-\tilde\alpha\lambda-\gamma\,\nabla C\cdot(x-x_0)}{(1+\gamma)\sum w+\tilde\alpha},\quad \tilde\alpha=\frac{\alpha}{h^2},\ \gamma=\frac{\tilde\alpha\beta}{h}$$

(Macklin, Müller and Chentanez 2016; Müller et al. 2020). The damping time \(\beta\) gives each beam ~30% of critical damping for an eighth of the car's mass, so a car resting on its structure does not rock. Each vehicle step, after the chassis is integrated, the body restarts from its start-of-step pose, with its own forces (tyres, aero, gravity) applied a share per substep. Then come 16 substeps of 2 iterations each; substeps, not iterations, converge a stiff structure (Macklin et al. 2019). The beam force for plasticity is its multiplier \(-\lambda/h^2\), not its leftover strain, which a finite solve overstates (the first attempt sprang back 11 m/s from a 56 km/h crash for that reason). Gauss-Seidel in a fixed order leaned a symmetric crash to one side, so beams and contacts are stored in mirror pairs and the sweeps alternate direction.

A cell node that reaches an obstacle means its zone is used up. Past the crush limit the structure stiffens: that contact gets the compliance of a zone at \(2.5\omega\), unloading 20 times stiffer than it loads (crushed metal does not push back). How far it goes in is the intrusion. The structure sleeps unless the host reports an obstacle near, the car is tilted or airborne, or a wheel is gone. Its nodes are then the car's collision hull, against the ground too.

Into a full-width rigid wall, coasting (reference saloon, 1,800 kg, \(\omega=32\) rad/s):

SpeedCrushPeakPulseEnergy into the structure
15 km/h0.08 m11 g58 ms~100%
30 km/h0.22 m16 g75 ms~100%
56 km/h0.51 m27 g92 ms100%
80 km/h0.91 m39 g119 ms89%

The linear-spring estimate at 56 km/h is \(\Delta v/\omega=0.49\) m over \(\pi/\omega=98\) ms. Rebound stays under 2 m/s. A 254 mm pole at 32 km/h pushes the door in 0.35 m with 5 cm of intrusion. Upside down from 0.3–2 m, the roof crushes 0.16–0.27 m and the car comes to rest carrying exactly its weight. The dummies (§14) then ride the structure's own pulse, the step's real acceleration, instead of a synthesised half sine.

19.3 Parts

Read from the deformed lattice whenever it changes: a Gaussian-weighted average of node displacements around a point, with \(\sigma=0.35\) m and the cell's nodes counting as zero. The loads come from the step.

  • Suspension. The mount moves with the lattice. Toe is the difference 0.3 m ahead and behind, \(\arctan\frac{\Delta y_f-\Delta y_r}{0.6}\), and camber the difference top to bottom. Past 0.35 m of mount travel, or 30 times its static load, the wheel comes off. At 15–30 times its static load the arm bends toe-out.
  • Tyres. More than 85 mm of deflection at speed pinches the tyre on the rim, and more than 60 kN on an obstacle at the wheel cuts it. Over 4 s the radius falls 18%, the vertical stiffness 85% and the grip 45%, and rolling resistance rises elevenfold.
  • Steering. The rack at the front axle moved sideways steers off-centre; pushed back, it loses lock.
  • Cooling and engine. Crush 12 cm behind the bumper destroys the radiator, and the coolant runs out in 45 s. The engine then heats with load, from the thermostat's 90 °C. It loses power from 115 °C, down to half at 130 °C, and seizes past 135 °C. A crushed engine bay costs up to 70% of the torque.
  • Aero. Crumpled panels add up to 75% drag, and a crushed tail stops the rear wing working.

Measured: a 35 km/h offset hit bends that corner, and the car no longer drives straight (18° of heading in 4 s, hands off). With a destroyed radiator at full throttle, power falls after ~30 s and the engine seizes after ~40 s. A 20 cm kerb at 70 km/h pinch-flats the left tyres, and the car pulls left. A 90 km/h offset hit tears the front wheel off, and the car still drives on three. Repair restores everything, and the next crash matches a new car's.

20Wind tunnel, airflow, telemetry and replay

web/ord_web.cpp (ord_telemetry, ord_aero_info, ord_tunnel), Vehicle::shiftPosition; the page's carflow_field.js, carflow.js, tunnel.js, telemetry.js, replay.js

20.1 The rolling road

The wind tunnel is a rolling road: each step, after the physics, the car is moved back to where the tunnel started (with its crash structure, §19) and its forward speed is restrained to the tunnel speed. Everything else is the full model of the chapters above: the tyres turn on the road, the suspension carries the downforce, and the aero model (§10) gives the forces with its ride height, floor stall and the wing's polar. A cross wind of \(V\tan\psi\) across the car sets the yaw \(\psi\). The panel shows the physics' own numbers: downforce front and rear and its balance, \(C_LA\) and \(C_DA\) from \(q=\tfrac12\rho V^2\), drag power and \(L/D\). A held car does exactly what a free one does on ground that is the same all along the road, scraping a wall included (a test checks it).

20.2 The airflow view

The streamlines and the smoke are drawn through a potential flow built from those forces, not computed by CFD. It is a picture consistent with the forces, not a prediction of them:

  • Body. Three sources across the nose and three sinks across the tail, with strength \(Q=VA\) for 82% of the car's frontal box, set back so the half-body's nose lands on the bumper. The air slows ahead of the nose (to ~0.6V) and speeds up over the roof and under the floor.
  • Downforce. Horseshoe vortices at the front and rear axle under the floor, and at the wing, each with circulation from Kutta–Joukowski, \(\Gamma=D/(\rho V b)\), with trailing legs 40 m long, drawn with Biot–Savart and a smoothed core. The upwash behind the wing and the tip vortices follow from them.
  • Ground. Every source and vortex has its mirror image below the road, so no air crosses it.
  • Wake. A Gaussian velocity deficit behind the tail, widening downstream (\(\sigma=0.42\,w/2+0.09s\)). Its amplitude makes its momentum deficit equal the drag: \(\rho V\!\int\!\Delta u\,dA=D\). It sways at a Strouhal number of 0.2.

Checked numerically: the momentum flux of the wake matches \(D/(\rho V)\) to 2%, and the vertical velocity at the road is zero.

20.3 Telemetry and slow motion

Every frame records an 80-number telemetry snapshot with the car's pose: per wheel, the load, slip ratio and angle, tyre forces and grip used, suspension compression and damper speed, tyre temperature and camber; for the body, the g-forces, yaw rate and sideslip, roll and pitch, downforce front, rear and from the wing, drag, floor clearance, the driver's inputs, and engine rpm, gear and torque. The panel's pages (suspension, tyres, aero, g-forces, drivetrain) draw them with a g-g diagram and 5-second traces. Slow motion (1 down to 1/20) slows the simulation clock itself, so the physics, the airflow and the smoke run slower while the camera and sound stay real time.

20.4 Replay

The replay plays back the rewind recorder's last ~25 s at a chosen speed, blending between recorded frames (positions linearly, orientations by normalised quaternion interpolation) so that 1/20 speed stays smooth, with the telemetry following along. Drive from here restores the simulation to that frame exactly (the step is deterministic) and hands the car back.

References

  1. H. B. Pacejka, Tire and Vehicle Dynamics, 3rd ed. Butterworth-Heinemann, 2012.
  2. E. Bakker, L. Nyborg, H. B. Pacejka, "Tyre modelling for use in vehicle dynamics studies," SAE 870421, 1987.
  3. R. S. Sharp, S. Evangelou, D. J. N. Limebeer, "Advances in the modelling of motorcycle dynamics," Multibody System Dynamics 12, 2004.
  4. J. P. Meijaard, J. M. Papadopoulos, A. Ruina, A. L. Schwab, "Linearized dynamics equations for the balance and steer of a bicycle: a benchmark and review," Proc. R. Soc. A 463, 2007.
  5. W. F. Milliken, D. L. Milliken, Race Car Vehicle Dynamics. SAE, 1995.
  6. J. Katz, Race Car Aerodynamics. Bentley, 1995.
  7. L. A. Viterna, R. D. Corrigan, "Fixed pitch rotor performance of large horizontal axis wind turbines," NASA, 1982.
  8. E. Hairer, C. Lubich, G. Wanner, Geometric Numerical Integration, 2nd ed. Springer, 2006.
  9. M. Treiber, A. Hennecke, D. Helbing, "Congested traffic states in empirical observations and microscopic simulations," Phys. Rev. E 62, 2000.
  10. H. C. Joksch, "Velocity change and fatality risk in a crash," Accident Analysis and Prevention 25(1), 1993.
  11. NHTSA, "Development of improved injury criteria for the assessment of advanced automotive restraint systems II," 1999; FMVSS 208 and FMVSS 126.
  12. SAE J1349, "Engine power test code: spark ignition and compression ignition."
  13. ISO 8855, "Road vehicles: vehicle dynamics and road-holding ability, vocabulary."
  14. W. B. Horne, R. C. Dreher, "Phenomena of pneumatic tire hydroplaning," NASA TN D-2056, 1963.
  15. EASA CS-25, AMC 25.1591, "Performance information for operations with contaminated runway surface conditions."
  16. ISO 3888-2:2011, "Passenger cars: test track for a severe lane-change manoeuvre, part 2: obstacle avoidance."
  17. S. Thrun et al., "Stanley: the robot that won the DARPA Grand Challenge," Journal of Field Robotics 23(9), 2006.
  18. M. Macklin, M. Müller, N. Chentanez, "XPBD: position-based simulation of compliant constrained dynamics," Motion in Games, 2016.
  19. M. Müller, M. Macklin, N. Chentanez, S. Jeschke, T.-Y. Kim, "Detailed rigid body simulation with extended position based dynamics," Computer Graphics Forum 39(8), 2020.
  20. M. Macklin, K. Storey, M. Lu, P. Terdiman, N. Chentanez, S. Jeschke, M. Müller, "Small steps in physics simulation," SCA, 2019.
  21. FMVSS 216a, "Roof crush resistance; upgraded standard," 49 CFR 571.216a.