Repository navigation
v1.4.0 is a feature release on the stable 1.x line. The schemas, plugin ABI, protocol, profiles
and recordings changed only by addition (RFC 0007); the behaviour changes are listed under
"Upgrading from 1.3.x" below.
Status: released on 2026-11-15 as v1.4.0, on the owner's request. Documentation:
https://open-physical-systems.github.io/Lagrange/.
Install
curl -fsSL https://raw.githubusercontent.com/Open-Physical-Systems/Lagrange/main/packaging/install.sh | bash
source /opt/ros/lyrical/setup.bash
lagrange amrThe robot builder (RFC 0016)
Press Ctrl B in the viewer (or the Launcher's Build tile) to make or edit a robot without
writing a file by hand. Guide: docs/guide/builder.md.
- Start from a template, a URDF or a xacro file. Add links, joints and shapes; move and turn
them with gizmos; mass and inertia come from the shape and a material's density. - Meshes as parts (STL, OBJ, DAE, glTF), with a collision choice per link: the mesh's convex
hull, convex parts split by CoACD, template shapes fitted to the mesh, or shapes you draw. - Sensors from the catalog, placed on the part, with each parameter's range checked.
- Power: motors, battery, bus, converters and fuses, written as an overlay.
- Live validation (Problems), undo and redo, autosave, and a prompt before unsaved work is lost.
- Test runs the robot on a server of its own, in an empty world, a sample world or a world
file, at a start pose you pick; joint sliders drive it; Back returns to editing. - Saves a URDF and its overlay; exports USD.
Viewer
- Every workspace has its designed tabs: Domains (modules, coupling, diff, schema), Electrical,
Environment, Signals, Replay (compare, sim vs real, validation), ROS 2, Performance (KPI
cards, threads, GPU passes, memory), World and Scene; a new Launcher; the command palette
(Ctrl K); the 4D radar point cloud drawn. - Text at the design's size (1.3× larger than 1.3.0), cut with "…" and a tooltip where it does
not fit, no overlapping labels, down to 1024 × 640.
Physics and worlds
- Jolt: sub-steps with joint reactions and contact forces averaged over the sub-steps;
friction per collider. - MuJoCo:
noslip_iterationsprofile key, joint armature from MJCF, static scenery as world
geometry (faster). - One ground per run: Lagrange's plane only when no file brings a floor.
- Tethers: the rotors' downwash blows the cable (
tether/<n>/downwash); RFC 0011 complete. - OpenDRIVE: superelevation (banked roads), lane heights (kerbs, sidewalks), level lanes, and
raised roads vehicles drive on; sample worldassets/worlds/banked_ring. - Cars: tyre forces in the road plane with the normal load along the road normal; the brake
holds a car on a slope; traffic vehicles keep clear of the robot and wait at a junction it is
crossing.
Python and learning
lagrange.envs.ParallelEnvsover shared memory (no pickling per step); environments take
profile=,overlay=andworld=.command_jointreturns aJointCommandsaying whether the joint took the command, why not,
and what was clamped.
Quality
- Four QA rounds, two code reviews and an ASan/UBSan/TSan pass; every finding fixed or written
down. Replays of robots with cameras run;/spawn_entityfollowsallow_renaming; states
saved by 1.1 to 1.3 restore again. - Tests and CI scripts run side by side (a private temporary folder per test, ROS tests on the
caller'sROS_DOMAIN_ID).
Upgrading from 1.3.x
The full list is in CHANGELOG.md under 1.4.0, "Breaking or behaviour changes". The ones most
likely to matter:
- Python
command_jointreturns alagrange.JointCommandinstead of abool:if,not,
== Trueand== Falsebehave as before;is Trueand JSON serialisation do not. Targets
beyond the robot file's limits are clamped (Python and the viewer; ROS/joint_commandsis
not). /spawn_entityrenames on a clash only withallow_renaming: true; otherwise a taken name
fails withNAME_NOT_UNIQUE, text naming no robot withNAME_INVALID.- Kind parameters outside the catalog's range refuse the run instead of being clamped.
- One ground per run: a world or robot file with its own floor no longer gets Lagrange's
plane on top of it. - State hashes change for MuJoCo runs with static scenery, Jolt runs, cars (tyre contact
frame, brake) and traffic; runs stay deterministic. - Viewer text is 1.3× larger; headless screenshot scripts with fixed click coordinates may
need new ones. - The quadruped example's robot moved to
assets/robots/quadruped/quadruped.urdf.
Checked
Whole workspace (66 packages) built and tested on Ubuntu 26.04 / ROS 2 Lyrical at dev #423:
2506 tests, 0 failures after #424 (a builder test that clicked a sample world by position
when banked_ring joined the list); lagrange determinism identical for the AMR, sedan,
quadcopter and quadruped profiles; every example and tutorial passed at #408, and the
sanitizers (ASan, UBSan, TSan) found nothing left in Lagrange code.