Domain: vehicle dynamics¶
1. Scope and release¶
Tyres, suspension, powertrain, brakes and steering for wheeled road vehicles. The chassis and wheels remain rigid bodies in the rigid-body backend; this module computes the forces that a generic contact solver models poorly (tyre slip forces) and the drivetrain that turns pedal commands into wheel torques. Release: v0.6.
PhysX ships a vehicle SDK. The plan is to implement tyre and drivetrain models in this module on top of wheel-ground ray or sweep queries, so that the same model runs on every backend. Using the PhysX vehicle SDK directly is the fallback if this costs too much (open question Q10).
2. Models per fidelity level¶
Part |
Level |
Content |
|---|---|---|
Tyre |
|
Longitudinal and lateral force proportional to slip ratio and slip angle, saturated by a friction ellipse at |
Tyre |
|
Magic Formula |
Suspension |
|
Per wheel: vertical spring, damper, bump stops, anti-roll bar coupling across an axle; wheel travel along a fixed axis |
Suspension |
|
Camber and toe change with travel from lookup tables |
Powertrain |
|
Motor torque from the electrical domain (or its substitute) through a fixed reduction and an open differential |
Powertrain |
|
Engine torque map (speed × throttle), torque converter or clutch, geared transmission with a shift schedule, differential |
Brakes |
|
Brake torque proportional to pedal pressure per axle with a bias; ABS as a slip-limiting controller (optional) |
Steering |
|
Road-wheel angles from the steering-wheel angle with Ackermann geometry, rate limit and a first-order lag |
Friction μ at each contact patch = surface material friction × env/friction_scale ×
the material’s wet scale.
3. Signals¶
// modules/vehicle_dynamics — declare()
for (auto& veh : vehicles(world)) { // VehicleAPI_1 (schema added with v0.6)
auto v = name(veh);
d.input ({.name = fmt("vehicle/{}/throttle", v), .type = SignalType::Scalar, .unit = units::one});
d.input ({.name = fmt("vehicle/{}/brake", v), .type = SignalType::Scalar, .unit = units::one});
d.input ({.name = fmt("vehicle/{}/steering_angle", v), .type = SignalType::Scalar, .unit = units::rad});
d.input ({.name = fmt("vehicle/{}/gear", v), .type = SignalType::Int, .unit = units::one, .optional = true});
d.input ({.name = fmt("body/{}/pose", chassisOf(veh)), .type = SignalType::Pose, .unit = units::m, .feedback = true});
d.input ({.name = fmt("body/{}/twist", chassisOf(veh)), .type = SignalType::Wrench, .unit = units::m_per_s, .feedback = true});
d.output({.name = fmt("vehicle/{}/wrench", v), .type = SignalType::Wrench, .unit = units::N, .frame = "world_local"});
d.output({.name = fmt("vehicle/{}/speed", v), .type = SignalType::Scalar, .unit = units::m_per_s});
d.output({.name = fmt("vehicle/{}/engine_speed", v), .type = SignalType::Scalar, .unit = units::rad_per_s});
for (auto& w : wheelsOf(veh)) {
auto j = jointOf(w);
d.input ({.name = fmt("joint/{}/velocity", j), .type = SignalType::Scalar, .unit = units::rad_per_s, .feedback = true});
d.output({.name = fmt("joint/{}/load_torque", j), .type = SignalType::Scalar, .unit = units::N_m}); // tyre reaction + brake
d.output({.name = fmt("wheel/{}/slip_ratio", j), .type = SignalType::Scalar, .unit = units::one});
d.output({.name = fmt("wheel/{}/slip_angle", j), .type = SignalType::Scalar, .unit = units::rad});
d.output({.name = fmt("wheel/{}/normal_force", j), .type = SignalType::Scalar, .unit = units::N});
d.output({.name = fmt("wheel/{}/steer_angle", j), .type = SignalType::Scalar, .unit = units::rad});
}
}
d.input({.name = "env/friction_scale", .type = SignalType::Scalar, .unit = units::one, .optional = true, .defaultValue = 1.0});
For an electric powertrain, drive torque comes from the electrical domain as
joint/{j}/torque like any other motor. For ice_map, this module writes
joint/{j}/torque_command and the electrical substitute passes it through.
4. Step size¶
Default 1 ms, equal to the physics step. Tyre relaxation dynamics and ABS need 1–2 ms.
5. Substitutes and contract¶
Contract: vehicle/{v}/wrench, joint/{j}/load_torque, vehicle/{v}/speed.
Profile token |
Kind |
Behaviour |
|---|---|---|
|
ideal |
Kinematic bicycle model: the chassis follows the commanded speed and steering exactly (written as a wrench that enforces it, or as a kinematic body override when rigid body is also substituted). For planner tests |
|
replay |
From MCAP |
When the stage contains no vehicle prims the domain is absent from the wiring, and the profile may omit it (it is not in the schema’s required list).
6. Placement¶
CPU on all tiers. Wheel-ground queries use the rigid-body backend’s scene query interface, which
is exposed to modules through a core service (core/world/SceneQuery) so that this module does
not link the backend (invariant 1).
7. Validation¶
Test |
Reference |
Tolerance |
|---|---|---|
Tyre force curves |
curves regenerated from a published Magic Formula parameter set (for example the parameter tables in Pacejka’s Tire and Vehicle Dynamics; cite edition and table) |
0.5 % |
Steady-state cornering |
understeer gradient from the linear bicycle model |
3 % in the linear range |
Standard manoeuvres |
ISO 4138 steady-state circle, ISO 3888-2 obstacle avoidance, ISO 7401 step steer, run as scripted scenarios |
qualitative agreement plus metrics compared with an open reference vehicle model (candidate: published results for a documented reference vehicle; to be chosen) |
Braking distance, dry and wet |
|
5 % |
Energy |
drivetrain power balance |
1 % |
Sim-vs-real |
a public vehicle-dynamics dataset with IMU, wheel speeds and steering (to be selected; license check) |
reported per manoeuvre |
8. Status (v0.6)¶
lagrange_vehicle_dynamics (modules/vehicle_dynamics/): VehicleDynamics at 1 ms, a raycast
vehicle on top of any rigid-body backend, and its ideal substitute (kinematic bicycle). Q10
is settled for now: the model is our own, with no PhysX vehicle SDK.
Wheels and suspension. Each
WheelAPI_1wheel is a spin joint under the chassis, possibly through a steering knuckle. A ray down the chassis’s up axis from its suspension mount finds the ground throughservices::SceneQuery, and the spring, damper and bump stop act along it.The model’s wheel positions are the ride height: each spring is preloaded with its static share of the weight, by the centre of mass between the axles.
Each ray returns the surface’s outward normal where it meets the ground (
services::RayHit::normal, fromsensors::ShapeCaster::ray), and the tyre works in the contact frame: z along that normal, x where the wheel plane meets the road plane, y = z × x (the TYDEX W-axis system; ISO 8855 with z up; Pacejka, Tire and Vehicle Dynamics, TODO(verify) the section). The normal load acts along the normal and the MF-Tyre longitudinal and lateral forces lie in the road plane, so slopes and banks are felt as they are. A hit whose normal is more than about 84° from the chassis’s up (a wall) is taken as level ground, as is a query that gives no normal. The rays stand on whatever collides, so a car drives on raised and banked OpenDRIVE roads, whose lanes become convex slabs (formats.md §3.11). On the sampleassets/worlds/banked_ring(a 5 m ring 1.5 m up, 5° of bank) the sedan’s demo circle keeps its base within 2.2 cm of its ride height above the banked surface and its roll within 0.018 rad of the bank over 14 s at 3 m/s (test_serverBankedRing); the normal loads the tyres report are within 0.8 % of the weight of m·(g cos β + a sin β) on average there (1.3 % with the forces in the level plane).Parked with its brakes on a 10° slope, the test saloon stands still and its tyres carry m·g·sin θ along the road and m·g·cos θ across it to 1e-7 of each (
test_vehicle_dynamicsParkedOnASlope; with the forces in the level plane the loads read m·g / cos θ, 3 % over, and it crept at 13 cm/s).Anti-roll bars move load across an axle in proportion to the travel difference.
Tyres (
Tyre.hpp).pacejka(default): MF-Tyre 5.2 pure slip with load dependence and its combined-slip weighting, from.tirfiles. Camber, shifts, conicity, ply steer, the aligning moment and turn slip are not applied; the curves are made odd so the forces oppose the slip.linear: slip stiffnesses on a friction ellipse.Slip comes from first-order relaxation states integrated exactly over the step, with damping blended in below 3 m/s.
μ = the tyre’s × the ground shape’s friction ×
env/friction_scale.
Brakes. Torque per wheel by the axle bias, as stick-slip friction (Karnopp): the torque that stops the wheel within the step against the tyre’s, up to what the brake gives, so a held brake holds the car on a slope and never reverses the wheel; optional slip-limiting ABS.
Steering. Ackermann road-wheel angles from the bicycle angle (rate limit, first-order lag). The steering joints are turned by a PD at 15 Hz; they are visual, since the tyre forces use the computed angles.
Powertrain.
electric: throttle ×vehicle:maxDriveTorque, split equally (an open differential), astorque_commandto the driven wheels’ motors or the electrical substitute.ice_map: full-throttle torque map, a clutch that slips below idle, an automatic gearbox with shift speeds, final drive and efficiency; reverse is first gear backwards.
Validation (
test_vehicle_dynamics, on MuJoCo):ride height and static loads;
braking distance from 20 m/s within 5 % of v²/(2μg) (3.2 % long);
steady-state yaw rate within 3 % of the linear bicycle model with its understeer gradient (1.4 %);
gear shifting;
the ideal substitute.
The Magic Formula’s peak, slope and asymptote are exact (
test_tyre).
Owed:
a comparison with a published MF parameter set (no openly licensed
.tirwas found; the sampleassets/tyres/generic_205_55R16.tiris illustrative);the ISO manoeuvres as scenarios;
the kinematic suspension.