Domain: rigid body and articulations¶
1. Scope and release¶
Rigid bodies, articulated joints, contacts and friction. Implemented by wrapping existing engines (invariant 12). First release: v0.2 with one backend; a second backend before v0.3 to prove the abstraction.
Backend order proposed (open question Q9):
Backend |
Role |
License |
Source on Resolute |
GPU |
|---|---|---|---|---|
MuJoCo |
v0.2 default and deterministic CPU reference |
Apache-2.0 |
|
CPU (MuJoCo Warp is Python/Warp, not linked) |
Jolt |
second CPU backend; large scenes with many free bodies |
MIT |
|
CPU |
PhysX 5 |
not built, by the owner’s v0.6 decision; planned for vehicles and GPU batches (Tier 2) |
BSD-3-Clause |
none |
CUDA only |
MuJoCo is first because it is packaged for Lyrical, has no GPU or CUDA build requirement, and its MJCF parser is also needed by the importer.
2. Models per fidelity level¶
Level |
Content |
Backend support |
|---|---|---|
|
Joint positions follow commands; no dynamics. Used by the replay and fixed substitutes |
built-in |
|
Reduced-coordinate articulations, convex contacts, Coulomb friction, joint limits, armature inertia |
all three |
|
Same model, batched over environments |
PhysX GPU (Tier 2) |
Soft bodies, cloth and fluids are out of scope before 1.0.
3. Signals¶
// modules/rigid_body/<backend>/ — declare()
for (JointId j : world.joints().actuated()) {
d.input ({.name = fmt("joint/{}/torque", j), .type = SignalType::Scalar, .unit = units::N_m,
.hold = Hold::WindowAverage}); // from electrical or its substitute
d.input ({.name = fmt("joint/{}/load_torque", j), .type = SignalType::Scalar, .unit = units::N_m,
.hold = Hold::WindowAverage, .optional = true}); // rotor reaction etc., via wrench_sum
d.output({.name = fmt("joint/{}/position", j), .type = SignalType::Scalar, .unit = units::rad});
d.output({.name = fmt("joint/{}/velocity", j), .type = SignalType::Scalar, .unit = units::rad_per_s});
d.output({.name = fmt("joint/{}/acceleration", j), .type = SignalType::Scalar, .unit = units::rad_per_s2});
d.output({.name = fmt("joint/{}/effective_inertia", j), .type = SignalType::Scalar, .unit = units::kg_m2});
d.output({.name = fmt("joint/{}/constraint_torque", j), .type = SignalType::Scalar, .unit = units::N_m});
}
// Prismatic joints use the same names with units N, m, m/s, m/s², kg.
for (BodyId b : world.bodies().dynamic()) {
d.input ({.name = fmt("body/{}/external_wrench", b), .type = SignalType::Wrench, .unit = units::N,
.frame = "world_local", .hold = Hold::WindowAverage, .optional = true}); // aero, rotor, hydro
d.output({.name = fmt("body/{}/pose", b), .type = SignalType::Pose, .unit = units::m,
.frame = "world_local"});
d.output({.name = fmt("body/{}/twist", b), .type = SignalType::Wrench, .unit = units::m_per_s,
.frame = "world_local"}); // linear (m/s) then angular (rad/s)
d.output({.name = fmt("body/{}/acceleration", b), .type = SignalType::Wrench, .unit = units::m_per_s2,
.frame = "body"}); // proper acceleration, for the IMU
}
d.input ({.name = "env/friction_scale", .type = SignalType::Scalar, .unit = units::one,
.optional = true, .defaultValue = 1.0}); // from weather (wet surfaces)
d.output({.name = "contact/points", .type = SignalType::Bytes, .unit = units::one}); // packed list for the viewer
A Wrench- or Pose-typed signal holds two physical quantities; its unit names the first
(force, linear velocity, position) and the type fixes the second (torque in N·m, angular velocity
in rad/s, unit quaternion). This rule is stated in RFC 0001.
4. Step size¶
Default 1 ms. Allowed 0.1 ms to 10 ms. Vehicles at 1–2 ms; large free-body scenes at 2–4 ms with more solver iterations. The backend’s own substeps are internal and do not appear to the scheduler.
5. Substitutes and contract¶
Contract: joint/{j}/position, joint/{j}/velocity, joint/{j}/effective_inertia for every
actuated joint; body/{b}/pose, body/{b}/twist, body/{b}/acceleration for every dynamic body.
Profile token |
Kind |
Behaviour |
|---|---|---|
|
constant |
All joints at their initial position, zero velocity; |
|
ideal |
Per actuated joint, a one-degree-of-freedom rotor: |
|
replay |
Joint and body states from an MCAP file; |
6. Placement¶
Tier |
Placement |
|---|---|
0 |
CPU, single thread in deterministic mode |
1 |
CPU; broad-phase and island solving on the worker pool |
2 |
CPU for one environment; PhysX GPU when |
7. Validation¶
Test |
Reference |
Tolerance |
|---|---|---|
Free fall, pendulum, double pendulum energy drift |
closed-form or high-order integration |
energy drift < 0.1 % over 10 s at 1 ms |
Sliding block on an incline |
closed-form (Coulomb) |
stick/slip angle within 1° |
Backend agreement |
same scene in MuJoCo, Jolt, PhysX |
joint trajectories within a stated envelope; differences reported, not hidden. MuJoCo and Jolt (v0.3, |
|
analytic two-link arm inertia matrix diagonal |
1e-9 relative |
Determinism |
two runs, same seed |
bit-identical state hash (MuJoCo backend) |
AMR drive test (v0.2) |
sim-vs-real: recorded wheel odometry of a real differential-drive robot driving a square. Dataset to be recorded or sourced (open question Q16) |
position error after 10 m within the spread of repeated real runs |
Pushing against measurement (2026-11-03)¶
APushedBlockMovesAsTheMcubeMeasurements repeats the repeated-push experiment of Yu, Bauza, Fazeli
and Rodriguez (“More than a Million Ways to Be Pushed”, IROS 2016, §VII, Table IV): their
stainless-steel square rect1 (0.837 kg, 90 mm, 13 mm thick) pushed 15 cm at 20 mm/s by a 9.5 mm
rod, normal to a face, halfway between its centre and edge, on four surfaces whose friction they
measured (abs 0.13, delrin 0.12, plywood 0.24, polyurethane 0.28; rod 0.25). Final (Δx, Δy, Δθ):
abs |
delrin |
plywood |
pu |
|
|---|---|---|---|---|
Measured, mean of 2000 |
(40.1, −67.6, 74.7) |
(38.8, −50.7, 78.5) |
(36.4, −93.6, 70.2) |
(40.2, −85.0, 69.3) |
Quasi-static model (Lynch et al. 1992, run by Yu et al.) |
(41.0, −98.1, 66.3) |
|||
MuJoCo |
(38.7, −91.1, 61.8) |
(38.6, −91.3, 61.7) |
(39.4, −92.3, 59.9) |
(39.6, −93.2, 59.0) |
Jolt |
(6.0, −148.8, 1.9) |
(8.5, −148.4, 2.6) |
(0.2, −149.6, 0.3) |
(0.6, −149.4, 0.7) |
MuJoCo is the quasi-static theory’s answer: within 6 mm of Lynch et al.’s model, turning 4 to 7° less (a box on a plane rests on its four corners there, where the model spreads the pressure evenly). Uniform Coulomb friction makes the path independent of the support’s friction, so it gives one answer for all four surfaces. Against the measurements it is 3 to 8 mm off on plywood and polyurethane but 24 and 41 mm off on abs and delrin, and 10 to 17° short on all: as the theory itself is (8 to 12° short, 6 to 48 mm off). What the surfaces do differently (uneven pressure, anisotropy, friction that changes with speed and place, their §V) is not in the model.
Jolt holds the sliding block straight. Jolt 5.6 keeps linear friction, at the centre of the contact points, and friction about the contact normal on separate budgets (μ·Σλ and μ·Σ dᵢ·λᵢ,
ContactConstraintManager), so a block already sliding at full friction still resists turning at full strength: it is carried 149 mm in front of the rod, turning 2°. Coulomb friction couples the two (the limit surface, which Yu et al. measured). A known limitation of the engine, reported, not asserted; use MuJoCo for pushing and manipulation.A bug found on the way. Jolt gave a body whose colliders have no friction its default of 0.5 (
settings.mFriction = friction > 0 ? friction : 0.5); a frictionless body now stays frictionless (AFrictionlessBoxSlidesAtGSinTheta, all backends).
8. Backends as plugins: the contract and the conformance suite (RFC 0008 §5)¶
A plugin module with domain = "rigid_body" is a backend, picked by --physics NAME or a
profile’s rigid_body: {backend: NAME}. Its contract is §3 and §5, binding:
Outputs, per hinge and slide joint:
joint/<j>/position,velocity; for actuated joints alsoacceleration,effective_inertia,constraint_torque. Per moving body (its joint to the world, or one of its ancestors’, is not fixed):body/<b>/pose,twist(world_local),acceleration(proper acceleration, body frame: what an IMU feels).Inputs:
joint/<j>/torqueandload_torque(window average, optional);body/<b>/external_wrench(world_local, at the body origin, optional);body/<b>/pose_commandfor kinematic bodies (optional: without one the body stays);env/friction_scale(optional, default 1).Behaviour: free root bodies; every
ShapeType, or a refusal indeclarethat names the shape; no collisions between bodies of one kinematic tree, and collisions between separate trees (a world file’s loose objects share a robot index but not a tree); joint limits; armature;World::Joints::initialPosition(or a warning that it starts at zero);shift_origin; and, for a backend that says it is deterministic,save_stateandrestore_statethat restore a run bit for bit.Friction is per collider: a contact takes the larger of its two colliders’ coefficients (MuJoCo’s rule for geoms of equal priority), times
env/friction_scale. Jolt keeps each collider’s coefficient on its sub-shape of the body’s compound shape (the shape’s user data) and combines per contact manifold (SetCombineFrictionwith the sub-shape IDs); it turns off manifold reduction on a body whose colliders differ, which would otherwise merge the contacts of e.g. feet and body under one sub-shape. Through v1.3.0 Jolt took the largest coefficient of a body’s colliders for all of them (the legged spike,docs/plan/spikes/legged-contact.md§5).
MuJoCo and kinematic bodies (since 1.2.x): MuJoCo makes no contact between two bodies without
degrees of freedom (a kinematic body and the scenery, or two kinematic bodies), but its broad
phase still sorts and pairs them, which for the town’s 650 traffic and people bodies was about
half of a step. Before each collision pass the backend clears the collision masks of the kinematic
bodies that no moving body can reach (a sphere about each, against a box about each moving
tree’s colliders at their last place, widened by 0.5 m and 200 m/s for a step) and puts them back
as one comes near (MujocoBackend::cullKinematicContacts). The contacts are the same: the test
CullingFarKinematicBodiesLeavesTheRunUnchanged runs a pusher into a box with and without it
and compares the state hash at every step. With a moving plane in the world it stays off.
A world with no degree of freedom at all (scenery and kinematic bodies only, as the town
without a robot) skips MuJoCo’s step: it advances the time as mj_step2 does and places the
kinematic bodies (mj_kinematics); the state is the same bit for bit (checked on the town’s
state hash over 20 s). The backend writes a kinematic body’s pose, twist and contact force only
when they change (a body’s pose changes when its command does, every 10 ms for the traffic and
the people), and its acceleration, always zero, once: the bus keeps a value until its writer
writes another. Everything is written again after a restore and an origin shift.
The conformance suite, ros2 run lagrange_server lagrange_physics_conformance
(server/test/physics_conformance.cpp), checks a backend against it. It runs the backends in
LAGRANGE_CONFORMANCE (NAME or NAME@PLUGIN, comma-separated; default
mujoco,jolt,jolt_abi@lagrange_jolt); a third-party engine runs it as
LAGRANGE_CONFORMANCE=my_engine@libmy_engine.so:
Test |
Requirement |
|---|---|
Free fall |
speed after 2 s within 0.1 % of 2 g: nothing damps it |
A falling box |
dropped from 1 m, rests at its half height within 5 mm after 3 s |
A pendulum |
period of the physical pendulum, |
A pendulum’s energy |
from 1 rad, 60 s at 1 ms: period of the first five swings within 0.25 % of the exact |
A box on a slope |
friction 1: holds at 30° (moves < 1 cm in 1.4 s), slides at 60° (> 0.3 m) |
Friction per collider |
a body box of friction 1 on four feet of 0.3 (the ramp 0.3): holds at 10°, slides at 25° at |
A stack of three boxes |
stands for 10 s: the top box within 1 cm of its place |
The sample AMR’s loop |
over 10 s, the distance driven within 5 % of MuJoCo’s, the end within 10 % of it |
Determinism and state |
two runs bit-identical; a saved state restored runs on bit-identically |
MuJoCo, Jolt and jolt_abi (the same Jolt engine as a plugin through the C ABI,
modules/rigid_body/jolt_backend/src/jolt_plugin.cpp, --plugin lagrange_jolt) pass it; Jolt and
jolt_abi give identical numbers. On Jolt the AMR’s loop ends 5.3 % of its 5.4 m from MuJoCo’s
end (heading drift; not from friction, since each of the AMR’s bodies has one friction on all
its colliders: the run is bit for bit the same with Jolt’s friction per body or per collider).
Writing the suite found two Jolt bugs, both
fixed (a third, Jolt’s default body damping, came up later and is fixed too): loose objects of one world file passed through each other (collisions were filtered by
robot index instead of by tree), and a restored state lost its contacts with the static scenery.
Restored contacts now include the scenery whenever it is unchanged; it changes between a save
and a restore only when streamed tiles come or go.
8.1 Energy on Jolt: joints as constraints, and sub-steps¶
A free pendulum (1 kg, 1 m, from 1 rad, 1 ms) keeps its energy within 0.07 % over 60 s on
MuJoCo, and loses 16.4 % on Jolt (docs/validation/comparison.md). The loss is Jolt’s method,
not a setting of Lagrange’s:
Lagrange gives Jolt no damping: body linear and angular damping are zero (
mLinearDamping,mAngularDamping, whose defaults are 0.05), the hinge has no friction (mMaxFrictionTorqueis the joint’s, 0 here) and no motor, and the body never sleeps. Jolt’s solver settings change nothing measurable: no position steps, Baumgarte 0 or 1, 30 velocity steps, warm start off all give 16.3–16.4 %.MuJoCo, DART and Bullet’s multibody solve a robot in joint coordinates. Jolt keeps every body free and holds a joint by projecting the velocities at each step (sequential impulses). Over a step the body turns by ω Δt, so that share of its velocity is radial at the next step, and the projection takes it off: (ω Δt)² of the kinetic energy per step, O(Δt) per second. The same scheme in double precision on a point mass (semi-implicit Euler, velocity projection, position projection) loses 16.35 % of this pendulum’s energy in 60 s; Jolt loses 16.38 %.
The period is not hurt: within 0.02 ppm of the exact one at 0.05 rad. A pendulum swinging freely for a minute is the worst case; a driven joint gets its energy back from the motor.
domains.rigid_body.substeps: N (profile, 1 to 64, default 1; Jolt only, MuJoCo has nothing to
divide) runs N Jolt steps of Δt/N per scheduler step, collision detection included, so it costs
about N times as much. Joint reactions, limit torques and the contact force left over from them
are the constraint impulses averaged over the N sub-steps, over Δt/N (Jolt’s total lambdas
start afresh each sub-step, so a step listener adds each one up before the next solve; the last
sub-step alone left part of a swinging pendulum’s pull to “contact”, 4 % of m·g at 4 sub-steps;
SubstepsKeepTheReactionAndInventNoContact and SubstepsInventNoContactOnASwingingPendulum in
test_jolt). Measured on the pendulum and the comparison’s scenes (one core):
substeps |
energy after 60 s |
200 boxes, real-time factor |
AMR in the warehouse, real-time factor |
|---|---|---|---|
1 |
−16.4 % |
2.35 |
68.6 |
2 |
−9.0 % |
1.29 |
41.6 |
4 |
−5.3 % |
0.66 |
23.8 |
16 |
−2.3 % |
In single precision the gain falls off beyond a few sub-steps (the double-precision model gives
−4.65 % at 4). Use MuJoCo, the default and the deterministic reference, where energy over long
free motion matters. Jolt.APendulumLosesEnergyAsJointsAsConstraintsDoAndSubstepsDivideIt holds
the loss to the model and sub-steps to it; Conformance.APendulumKeepsItsPeriodAndEnergy holds
every backend to the bound in the table above.
Jolt is built with DOUBLE_PRECISION=OFF (vendor/jolt_vendor). Its free fall after 1 s is
−4.898 mm against the closed form instead of semi-implicit Euler’s −4.905 mm. Float32 velocity
and position reproduce it to the last digit (−4.898281 mm). Float32 velocity with double
positions gives −4.900 mm. Jolt’s double precision covers positions only, so turning it on would
remove 2 of the 7 µm.
8.2 MuJoCo’s creep on slopes: noslip and armature¶
MuJoCo’s soft contacts let a body that friction should hold creep down a slope: the comparison’s box on 10° at 0.44 mm/s, a quadruped standing on impedance-held legs at 5.7 mm/s on 10° and 11.6 mm/s on 20° (docs/plan/spikes/legged-contact.md §5, §6). Two opt-in levers:
domains.rigid_body.noslip_iterations: N(profile, 0 to 100, default 0 = off): MuJoCo’s noslip post-solver (mjOption.noslip_iterations). 5 stops the steady creep on 10° (to under 1 µm/s on the rigid robot), halves it near the friction limit, costs 30–60 % more per step, and changes transients where feet must slip (the legged robot standing up on 20° falls over with it). Jolt has none and needs none (its contacts do not creep); other backends ignore the key, with a profile warning.MujocoBackend.NoslipIterationsStopTheCreepOnASlope.Joint armature (
World::Joints::armature): a motor’selec:rotorInertia · elec:gearRatio²(electrical::applyRotorInertia, always) and an MJCF joint’sarmatureplus its actuators’armature · gear². MuJoCo takes it asdof_armature, Jolt as armature torques (above). Creep falls in proportion to the foot’s inverse weight. URDF and SDFormat have no such element.
Contact force¶
body/<b>/contact_force (N, in the world frame) is the sum of what touches a moving body pushes it with, read from each step’s contacts, for force sensing and foot contact. On a robot at rest the bodies’ forces add up to its weight (test_contact_forces_on_a_robot_at_rest_carry_its_weight). Jolt’s contact listener gives no impulses per step, so on Jolt it is what is left of a group’s momentum change: m·Δv/Δt − m·g less its external forces and its joints’ forces (below), by Newton’s second law; a group of bodies fixed together (one Jolt body) gets it on its root body. contact/points above is still MuJoCo only.
joint/<j>/reaction (Wrench, world frame, linear then angular) is what the parent does to the child at the joint, including what its motor applies, as a force-torque sensor there reads it. Checked on a hinge holding a known weight (test_a_joints_reaction_is_what_it_carries). On Jolt it is the joint constraint’s impulses over the step (GetTotalLambda*: the point, rotation, limit and motor parts, + on the child, − on the parent, the hinge’s rotation part in the basis Jolt builds, b2 = a2⊥, c2 = a2 × b2) plus the effort applied through the joint. The conformance suite checks both engines: a box at rest is held up by its weight, a still pendulum’s pivot carries it with no moment, and a swinging one’s carries m·g + m·d·ω² at the bottom within 1% (11.349 N on MuJoCo, 11.348 N on Jolt).