Repository navigation
Releases
Lagrange v1.4.0: build a robot in the viewer
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.
Lagrange v1.3.0: 37 new sensors, a faster simulator, hardened protocol
v1.3.0 is a feature release on the stable 1.x line. Everything is an addition (RFC 0007):
existing robots, worlds, profiles, plugins and recordings run as before.
Status: released on 2026-11-14 as v1.3.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 amrSensors
- 37 built-in sensor kinds (a URDF
<sensor type="KIND">or USDCustomSensorAPI_1, no
plugin): power (battery monitor, INA226/ACS712 current and voltage, ESC telemetry, tether
load cell), environment and drones (anemometer, airspeed, rangefinder, light, sun, rain,
humidity, visibility, optical flow, particles, ADS-B), AMR and arms (bumper, cliff, wheel
odometry with real slip, safety scanner with protective and warning fields, force/torque,
joint torque, proximity, gripper, line sensor, RFID/QR tags, UWB, Wi-Fi), cars (vehicle CAN,
TPMS, V2X), underwater (sonar), cameras (event camera, stereo/RGB-D, detections with 2D/3D
boxes and semantic segmentation, landing target), and a 4D imaging radar. Each cites its
datasheet or reference; every default was checked against its source
(docs/plan/sensor-defaults-verification-2026-11-12.md). Guide:docs/guide/sensors.md;
examplelagrange_example_sensors. - On ROS 2 by default on standard messages (Range, LaserScan, Odometry, BatteryState,
WrenchStamped, vision_msgs Detection2D/3DArray, ...), images withcamera_info. - Sensor faults for every sensor: dropout, stuck, bias, drift, noise, disconnect
(--sensor-fault, run file, profile, Python). - Lidar scan patterns (Velodyne channel table, flash, Livox rosette) and fisheye cameras
up to 360°, in URDF, SDFormat and USD (RFC 0015). - Python
sim.image()returns any image signal as a numpy array.
Speed
| Run (real-time factor, headless) | v1.2.1 | v1.3.0 |
|---|---|---|
| Sedan in the town | 0.8 | 3.7 |
| Town, no robot | 3.7 | about 22 |
| Sedan, city block | 1.1 | 12.9 |
| Quadcopter | 14.5 | about 60 |
| AMR, warehouse | 7.3 | 31.8 |
The camera model and the thermal camera run on the GPU, the camera render overlaps the rest
of the step, the radar runs in parallel (and on the GPU with --lidar gpu), MuJoCo skips far
kinematic bodies, ROS messages are built only for subscribers, and the viewer draws only what
changed (loading a scene 1.85 s → 37 ms). Start-up and spawning are faster too. Measured on a
shared laptop, ±30 %: docs/design/benchmarks.md §4–§5.
Security and fixes
- Protocol limits before the handshake (RFC 0014): 64 KiB frames until the client is
greeted, connection limits, a handshake timeout (--max-connections,--max-pending,
--handshake-timeout,--peer-rate). Before, any client could make the server hold 64 MiB
per connection, with no limit on connections. - Two QA passes (
docs/plan/qa-2026-11-12.md,docs/plan/qa-sensors-2026-11-12.md) fixed about
56 problems, among them a hugeStepfreezing the server, 15 and 30 Hz lidars and IMUs
refused at start, spawned robots' sensors reading the first robot's parts, a second
multicopter grounding the first, images lost onrestore_state, NaN accepted from the command
line and Python.
Upgrading from 1.2.x
- Saved states (
Server::saveState, Pythonsave_state()) now use format 2 and keep camera
images; a state saved by 1.2.x is refused. Recordings are not affected. - IMU
<dynamic_bias_stddev>is now read as Gazebo reads it (the driving noise of the bias). - Some sensor noise defaults changed to their datasheet values (SHT40, WindSonic, BH1750,
VL53L0X, SPS30). - A server now refuses more than 32 connections (16 not yet greeted) by default.
- The quadcopter run is 3–5 % slower than before the third perf round (owed).
Checked
Whole workspace (66 packages) built and tested on Ubuntu 26.04 / ROS 2 Lyrical: 1799 tests,
0 failures; lagrange determinism identical for the AMR, sedan and quadcopter profiles.
Lagrange v1.2.0: cables, heat in the parts, a robot's own interference
Lagrange v1.2.0: cables, heat in the parts, a robot's own interference (release notes)
v1.2 is the second feature release on the stable 1.x line. It adds three kinds of physics that a
robot does to itself or drags behind it: tethers that sag, snag and tangle, heat inside
every part worked out from its material, and the magnetic field of its own wiring. Each comes
with a viewer, tests against closed forms or published references, an example and a tutorial.
Multicopters fly more like real ones, and the documentation site has a new front page.
Everything frozen by RFC 0007 changed only by addition. The new schemas are TetherAPI_1,
ThermalMaterialAPI_1 and HeatSourceAPI_1. EmiSourceAPI_1 gained a wire type and three
attributes. The protocol gained FieldVolume.prim_path. All of these are checked by the
frozen-surface tests, and v1.0 and v1.1 files, plugins, profiles and recordings still load.
Status: released on 2026-11-11 as v1.2.0, on the owner's request. Documentation:
https://open-physical-systems.github.io/Lagrange/.
Highlights
Tethers and cables (RFC 0011)
TetherAPI_1(or--tether X,Y,Z,LINK[,LENGTH]) ties a cable from an anchor to a body.
Thetetherdomain solves it by small-step XPBD at 1 ms.- The cable sags and drags in the wind.
- It touches every collider with friction, catches on edges, tangles on itself and pushes and
pulls the bodies it meets. - A winch can hold its length, hold a tension, or run free.
- Checked against the catenary, a taut string and the capstan equation.
- The viewer draws every cable.
- Docs: docs/physics/tether.md.
Heat inside every part (RFC 0012)
- Materials and heat sources come straight from a URDF:
<thermal_material preset="fr4" ...>and
<heat_source power= efficiency= xyz= size=>, or the same in an overlay or USD. There are 14
presets, each with its source. - The thermal domain's
conductionfidelity cuts each link into cells. It works out:- conduction, orthotropic where a material needs it;
- contact conductance to the parent link;
- natural and forced convection;
- radiation in the share of the surroundings each face sees.
A motor's losses heat the link that holds its stator.
- Checked against the lumped limit, the fin with a convecting tip, the semi-infinite solid
and a two-block contact, from 0.01 % to 2 %. On a sample LED heat sink it is also compared with
OpenFOAM: on a 2.5-million-cell mesh, OpenFOAM's sink sits where Lagrange's correlations put
it. How close the LED's own hot spot comes is still open (docs/physics/heat-conduction.md). - The viewer's Thermal shading colours every part cell by cell, and the inspector shows each
link's mean, max and min. - Thermal sensors:
- The sample plugin
lagrange_thermal_probeadds a contact thermistor and an infrared spot
thermometer. - Thermal cameras read each part with its material's emissivity.
- The sample plugin
- New commands:
lagrange heat ROBOT --ambient-temperature Kgives the steady temperatures in seconds.lagrange foam-cht ROBOT --ambient K [--radiation]writes and runs the same robot as an
OpenFOAM conjugate heat transfer case, then reads its temperatures back.
A robot's own interference (RFC 0013)
- Wire sources.
EmiSourceAPI_1gainswiresources, the exact Biot–Savart sum over a
route with its return conductor, driven by any current signal. - Motor leads.
--emi-motor-leads SPACING[,X,Y,Z]lays a lead from the battery to each motor
carrying its bus current. - What the compass reads. Every magnetometer reports
heading_errorandinterference, the
ratio ArduPilot's compassmot reports. The sample quadcopter's 13.7 A in hover puts its heading
0.09° off, 1.1 % of the Earth's field. - The viewer slices |B| upright through the robot on a log scale. Its Overlays panel lists
the effects on compasses, CAN buses and radio links under Coupled into.
Multicopters
- Full throttle under PX4 and ArduPilot is each rotor's loaded top speed, from its motor and
battery. --thrust-limit FRACTIONcaps every rotor at a share of its full thrust.- The built-in controller:
- ramps its velocity like PX4;
- keeps its set point on a leash, so a ceiling neither flips nor holds a drone;
- takes the surface under it as the ground, so it can fly off a bridge or a roof.
- Motor constants. The samples' motors take KV against the bus voltage,
Ke = 60/(2π·KV·√3).
Viewer
- Reset restarts a live run.
- Record (or Ctrl+R) records a live run on the server.
- New drawing: tethers, the heat in each part, and the |B| field around the robot.
Examples, tutorials, site
- New examples:
lagrange_example_heatandlagrange_example_compass. - New tutorial: docs/guide/tutorial-heat-and-emi.md, run headless by
tools/ci/tutorial_heat_and_emi.sh. - New example profile:
profiles/examples/led_heatsink.yaml. - The documentation site's front page: a gallery, the domains and a quick start.
Upgrading from 1.1
Nothing to migrate: files, plugins, profiles and recordings of 1.0 and 1.1 load as they are.
The new behaviour is opt-in:
- a link's thermal material (with the site's ambient temperature);
--tetherorTetherAPI_1;--emi-motor-leadsorwiresources;--thrust-limit.
Two behaviours change for every run:
- Full throttle under PX4 and ArduPilot. It is each rotor's loaded top speed, where it used
to be 850 rad/s. The sample's PX4 airframe and ArduPilot parameters were re-tuned to match. - The samples' motor constants. They use the √3 above, so the sample quadcopters spin
slightly faster for the same voltage.
Checked
- Full local run:
colcon test --packages-above lagrange_corepasses, Autoware's tests
included with its message underlay. - Docs and examples:
tools/docs/build.sh --checkpasses;tools/ci/check_examples.pyruns
the two new examples; the new tutorial passes headless. - The full list: CHANGELOG.md, 1.2.0.
Lagrange v1.1.0: easier to use, checked against measurements
v1.1 is the first feature release on the stable 1.x line. It makes Lagrange easier to start and
to drive: one lagrange command, one run file, robots added while it runs. It adds plugins,
walking people, real robot models, water, a wind tunnel and rotor downwash, a realistic viewport,
and many new sensors. Several models are now compared with measured data. The documentation is
published as a site with a physics reference for every model.
Everything frozen by RFC 0007 changed only by addition. The plugin ABI went from 1.0 to 1.1 by
appending, and new schemas were added (CustomSensorAPI_1, HumanAPI_1, WaterAPI_1,
ThermalCameraAPI_1, JointDynamicsAPI_1, ElectricalBranchAPI_1 and others), all checked by
the frozen-surface tests. v1.0 files, plugins, profiles and recordings still load.
Status: released on 2026-11-07 as v1.1.0, on the owner's request. Documentation:
https://open-physical-systems.github.io/Lagrange/.
Highlights
Easier to run
lagrangeruns the server and the viewer together, the waygazebodoes
(lagrange amr,lagrange quad,lagrange sedan,lagrange swerve,lagrange town, or
lagrange ROBOT [WORLD]). It also runs a profile with the viewer (lagrange PROFILE.yaml).- The run file (
docs/guide/run-file.md) holds a whole run in one YAML file: robot, world,
what to simulate and the site. Your own robot starts still on an empty ground. - Spawning. Start without a robot, then add and remove robots and people while it runs: with
lagrange spawnandlagrange delete, File → Add robot in the viewer, or ROS 2
simulation_interfaces. - Joint control. Any robot can be driven joint by joint with no controller, over
/joint_commands. - Site changes while running.
lagrange set gravity=1.62 wind_speed=5and the viewer's
Environment panel change the site as it runs: gravity, wind, temperature, rain, fog, pressure
and humidity. The panel also has weather presets. lagrange checksays which joints cannot hold the robot.lagrange bakesplits a
URDF's concave collision meshes into convex parts.- Examples (
examples/): one ROS 2 package per use, each run by a launch file. They cover
your own robot, an arm, a power system, a lidar, fog, the quadcopter, the Holybro X500 V2 by
teleop, a car, spawning, ros2_control, a C plugin, learning, a trotting quadruped, a camera and
the wind tunnel. - Python.
lagrange.envsoffers Gymnasium's interface over a simulation, with environments
running in parallel. - A TX16S-style remote on screen (
utils/lagrange_tx16s). Fly it from a real RadioMaster
TX16S over USB or from the keyboard.
Plugins and people
-
Plugins in the server (RFC 0008). Plugins are loaded with
--plugin, through plugin ABI
1.1. A plugin can:- see the world and the scene (rays, overlaps);
- simulate custom sensors (the sample
lagrange_toftime-of-flight and ultrasonic sensor); - map signals to and from ROS topics (
--ros-topics); - replace the physics engine, which a conformance suite then checks.
Start from the plugin template.
-
Walking humans (RFC 0009). People are 14 kinematic capsule segments. They walk with their
stance foot planted and steer round robots and each other. Add them as crowds (--humans N),
one by one (lagrange spawn) or as SDFormat actors. A thermal camera sees them at skin
temperature.
Robots and worlds
- Real models, fetched with checksums (
fetch_assets):- the Lexus RX 450h (Autoware's sample vehicle);
- the Holybro X500 V2 (PX4's frame);
- the AMR_FMS swerve AMR in its 60 m × 40 m warehouse.
- Real places built from open data, Zurich and Nishi-Shinjuku in Tokyo.
- The town. Working lights, zebra crossings whose buttons people press, vans and buses,
lane changes, and four seasons with snow and ice. - Water (
WaterAPI_1,--water): buoyancy, drag, added mass, currents and linear waves.
Fossen's model takes a vehicle's identified coefficients, and the BlueROV2 Heavy's are
included. - A trotting quadruped example.
Physics
- Rotor downwash. The jet under a drone, its outwash on the ground, and the wake against walls
and roofs, felt by other robots and checked against OpenFOAM hover cases. A live
lattice Boltzmann air box can run round the drone on the GPU (downwash_model: lbm), and
the wind blows through it. - Rotors: the vortex-ring state from NeuroBEM's fit, the ceiling effect, and the air's torque
turning the propeller so a multirotor yaws. - The wind tunnel (
lagrange tunnel): lattice Boltzmann on the collision shapes, on the
GPU or the deterministic CPU reference, with a grid study.lagrange foamwrites and runs
the same case in OpenFOAM. - The weather reaches the drone. Rotors, drag and the controller fly in the weather's air
density, and rain and snow push links. - Electrical:
- velocity and voltage motor modes, and motors on sliding joints;
- a SPICE netlist or a URDF
<lagrange>block as the power system; - resistors, fuses, switches and diodes between buses (RFC 0010).
- Rigid body:
- joint damping, friction and mimic joints from every robot format;
- each body's contact force, and a force-torque reading at each joint, in MuJoCo and Jolt;
- mesh colliders as convex hulls;
- gravity changed while it runs.
Sensors
- Lidar intensity from surface materials, incidence angle and range.
- Lidar motion distortion on both tiers.
- Sensor latency and jitter, applied the same way for ROS, plugins, recordings, Python and the
viewer. - A thermal camera (
ThermalCameraAPI_1): Planck band radiance, with a Swinbank clear sky. - Each camera's instance image on ROS 2.
- Camera sensors drawn with the viewport's realistic renderer.
The viewer
- Realistic shading, the default on a GPU: sky, sun shadows, physically based materials, real
water, photo textures, and falling rain and snow. - The Electrical workspace gains Circuit, Netlist and 3D overlay tabs, and Auto-layout.
- A battery's State cards and OCV plot.
- The Signals list gains a unit filter and drag onto the scope.
- The Environment panel gains live site entry and weather presets.
- An angle flight mode for multicopters. Airspeed and tilt are shown beside the ground speed.
Checked against measurements
tools/ci/realism.sh runs these checks (docs/validation/report.md):
| Check | Reference | Result |
|---|---|---|
| Battery | LG HG2 cell (Kollmeyer et al.): pulses and drive cycles | 5.4–6.2 mV RMS from 46 to 89 % SoC. 21.5 mV at 24 % misses the 20 mV target. Unseen LA92 11.7 mV, US06 20.1 mV (just over). No temperature dependence |
| Planar pushing | MCube (Yu et al. 2016) | MuJoCo within 6 mm and 4–7° of the quasi-static model. Jolt does not turn the block |
| Rotors in flight | NeuroBEM flights (Bauersfeld et al. 2021) | coefficients 1.46 N RMS (their fit 1.49). bem 1.12 N (their BEM 0.98) |
| Drone under a drone | Kiran et al. 2025 | 76 % of thrust kept at 4 l against 65 % measured (11 points over) |
| Underwater vehicle | BlueROV2 Heavy (von Benzon et al. 2022) | Top speeds 0.729 / 0.626 / 0.713 m/s against 0.72 / 0.63 / 0.71 |
| Wind tunnel | Ahmed body (SAE 840300) | Over four times too much drag. Wall friction 3.1 times too high |
Documentation
- A documentation site (Sphinx, published to GitHub Pages from
main). It has diagrams,
videos and highlighted code. - An installation guide, from ROS 2 Lyrical to a first run.
- A physics reference for every model: what it computes, its equations, how it is solved,
and how far to trust it. - A Robots and worlds page showing each sample running, with its command.
- New tutorials: your own drone step by step, a power system from a schematic, people around
your robot. There are also feature videos of real runs.
Known issues
- The misses in the table above, and everything listed as owed in the validation report. There is
still no sim-vs-real recording of a real robot (the owner has no hardware to record). - Not run while GitHub Actions are disabled: the sanitizer builds and the nightly jobs. The
release was checked by a localcolcon buildandcolcon test --packages-above lagrange_core. - Radiation stays a zero substitute.
Release checklist
- Release notes
- Full local build and test
- Documentation site built with warnings as errors, and published
- Released:
devmerged intomain, taggedv1.1.0,release/1.xbrought up to it - Packages published and signed (maintainers,
packaging/README.md)
Lagrange v1.0.0: stable
Lagrange v1.0.0: stable (release notes)
v1.0 is the first stable release. Nothing new is simulated: the files, binaries and connections
users depend on are frozen for the whole 1.x line, the viewer protocol can be used safely over
a network, the packages build as Debian packages and install on a clean machine, and every
domain's validation is written down. Release 1.x is supported until ROS 2 Lyrical's end of
life, May 2031.
Status: released on 2026-10-29 as v1.0.0, under the owner's standing request to release
each version when its work is done. Publishing the packages (ROS buildfarm or an apt
repository, the container registry, Sigstore signatures) is the maintainers' step
(packaging/README.md).
Highlights
- The 1.x freeze (RFC 0007,
GOVERNANCE.md). The USD schemas, the plugin C ABI (major 1),
the viewer protocol (v1), profiles (schema_version: 1) and recordings
(format_version: 1) change only by addition within 1.x. Each surface has a check:- schemas:
schemas/test/frozen_1_0.jsonlists all 27 schemas and 240 properties, and the
schema test compares against it; - plugin ABI: struct layouts are pinned by
test_abi_layout.c, andtools/ci/abi_check.sh
runsabidiffwhen libabigail is installed; - protocol:
buf breakinguses theFILErules; - profiles and recordings: every sample file since v0.5.0 is migrated in a test.
- schemas:
- Plugin ABI 1.0 adds
shift_origin, so a plugin that keeps world positions follows the
floating origin. - Migrations.
migrate_recordingjoinsmigrate_schemaandmigrate_profile.
test_old_releases.pychecks the sample stages and example profiles of v0.5.0, v0.6.0 and
v0.7.0 against this release's tools. - Security (
docs/design/security.md).tls://endpoints carry the viewer protocol over TLS 1.2+ with certificate and host
verification.- A token (
--auth-token-file) is compared in constant time, and is required to listen
beyond loopback. - Unix sockets stay mode 0600.
- The scene builder has a fuzz harness (libFuzzer, plus a mutation test of 54 000 frames in
every build). - The threat model and dependency review are in
security.md.
- Binary packages, built locally (
packaging/README.md).- Every package as a
ros-lyrical-lagrange-*.deb, built by bloom in a clean container. - A release image from the debs alone, which is also the clean-machine install test.
- A Python wheel and an SPDX 2.3 SBOM.
- Every package as a
- Validation report (
docs/validation/report.md): per domain, what each model is checked
against, the tolerance, the result and the test, and where sim-vs-real data is still owed.
Assets
lagrange-sedan-city.mp4: 20 s of the whole viewer with the sample sedan in the city block
(the README's clip, attached to the GitHub release because the repository keeps files under
1 MB).- The debs, the release image, the wheel and the SBOM are built with
packaging/and not
attached: publishing them is the maintainers' step.
Acceptance (roadmap §9)
| Epic | Acceptance | Status | Evidence |
|---|---|---|---|
| Freeze | Freeze RFC accepted | met | RFC 0007, accepted under the owner's 2026-10-29 pre-approval; the checks above. buf and libabigail are not installed on the development machine, so buf breaking and abidiff did not run; the layout test and the frozen schema list run in every build |
| Migration tools | Old sample files migrate in CI | met, locally | test_old_releases.py over v0.5.0–v0.7.0 (GitHub Actions are disabled) |
| Binary releases | Clean-machine install test | met, locally | All 46 packages built as .debs by bloom in a clean ros:lyrical-ros-base-resolute container; packaging/test_install.sh installed them alone into a fresh image and ran the CLI, a headless run from Python, the determinism check, a streamed world, the migration tools and the world builder (Tier 0, llvmpipe). Built from the release candidate before the version bump, so those debs say 0.7.0; rebuild from the v1.0.0 tag for publishing |
| Documentation | All tutorials run in CI | met, locally | tools/ci/tutorial_{amr,drone,environment,cars,huge_worlds}.sh and arm_scenario.sh |
| Validation report | Published with the release | met | docs/validation/report.md. Sim-vs-real against measured data exists for the battery only; the rest waits for open question Q16 |
| LTS policy | Documented in GOVERNANCE.md |
met | release/1.x until May 2031, backport rules |
| Security review | Review issues closed | met, with open items | docs/design/security.md §5: an advisory scan of the vendored packages and long fuzzing campaigns are owed |
Known issues
- Not run while GitHub Actions are disabled: the sanitizer builds, the nightly jobs,
buf breaking,abidiff, long fuzzing campaigns. - Owed from earlier releases: everything listed as owed in
docs/plan/progress.mdand in the
validation report (sim-vs-real data, ISO manoeuvres, ASAM scenarios, renderer scale for huge
worlds, moving robots between regions while running). - Radiation stays a zero substitute (post-1.0, the owner's decision).
Release checklist
- Every v1.0 epic done or with its open items listed
- Release notes
- Gated changes listed for the owner's review (
progress.md: RFC 0007, the frozen schemas
and ABI,ClientHello.auth_token) - Owner review of those merges
- GitHub Actions re-enabled and green on
dev - Packages published and signed (maintainers,
packaging/README.md) - Released:
devmerged intomain, taggedv1.0.0, andrelease/1.xbranched
Lagrange v0.7.0: huge worlds
Lagrange v0.7.0: huge worlds (release notes)
v0.6 put cars on a city block. v0.7 makes the world large: a world streamed in tiles around
the robot, a floating origin that follows the robot as it drives, robots kilometres apart in
regions of their own, and worlds built from open data (an elevation model, OpenStreetMap, 3D
Tiles), with terrain as height fields.
Status: released on 2026-10-29 as v0.7.0, under the owner's standing request to release
each version when its work is done.
The 40 km sample around Zurich. Terrain produced using Copernicus WorldDEM-30 © DLR e.V.
2010-2014 and © Airbus Defence and Space GmbH 2014-2018 provided under COPERNICUS by the
European Union and ESA; all rights reserved. Buildings and roads © OpenStreetMap contributors
(ODbL).
Highlights
- Floating origin during the run (huge-worlds.md §1.4).
- Past 1000 m from the region origin, the server moves the origin to the robot's whole-metre
position between two steps. - The world tables are shifted, the run is rebuilt, and its state is carried over through
IModule::shiftOrigin(MuJoCo, Jolt, the multicopter controller, ArduPilot). - Fields load into the region frame.
- The viewer keeps its camera on the same place, ROS
/odomand TF stay continuous, and
recordings store each new frame.
- Past 1000 m from the region origin, the server moves the origin to the robot's whole-metre
- Tile streaming (§2.1).
WorldTileAPI_1(newworldschema library) marks a prim as a tile whose payload holds
its content.- Tiles are selected by level of detail, with collision tiles near the robot, coarse tiles
kept until their replacements are loaded, hysteresis, deterministic mode and memory
budgets. - Tiles load on worker threads. The robot never drives where physics has no ground yet.
- Profile keys:
world.streaming.load_radius,unload_radiusandcollision_radius. - Sample:
assets/worlds/tiled_town.
- Active regions (§3.1).
--add-robot NAME=FILE@X,Yputs more robots in a run.server::RegionHostruns robots far apart in separate runs, each with its own origin,
physics and tiles.
- Worlds from open data (§4.1, new package
lagrange_geospatial).lagrange_build_worldbuilds terrain from elevation rasters through GDAL and PROJ. The
vertical datum must be given, never guessed.- Buildings and roads come from OpenStreetMap, and 3D Tiles can be added for show.
- Each world gets an
ATTRIBUTION.md. tools/ci/build_sample_world.shbuilds the 40 km Zurich sample from the Copernicus DEM
and OpenStreetMap.
- Height field terrain.
- New
ShapeType::HeightField: MuJoCohfield, JoltHeightFieldShape, exact CPU lidar and
radar casts, the viewer's collision shading, and USD. - The Zurich sample loads in 1.4 s, against 57 s with terrain as prisms.
- New
- World workspace.
- Shows the loaded tiles by level of detail, the floating origin, the georeference and the
streaming statistics. - The viewer's camera is a streaming hint (
SetCameraInterest).
- Shows the loaded tiles by level of detail, the floating origin, the georeference and the
- Python:
spawn=,region_origin(),colliders(),sample_tiled_town(). - Docs: the huge-worlds tutorial (
docs/guide/tutorial-huge-worlds.md, run by
tools/ci/tutorial_huge_worlds.sh).
Acceptance (roadmap §8)
| Epic | Acceptance | Status | Evidence |
|---|---|---|---|
| Tile streaming | huge-worlds.md §6 |
partly met | The 40 km sample streams (1700 tiles, 1.4 s load); a robot never enters a tile not in physics (TileSelector.ARobotMayNotEnterATileThatIsNotLoaded, the server's hold); deterministic tile selection (Streaming.TheTilesAroundTheRobotAreLoadedAndTheRunIsDeterministic: equal state hashes). Memory budgets are in the selector (TheBudgetKeepsTheTilesARobotNeeds) but no profile key sets them yet; the viewer's frame time while tiles load was not measured |
| Active regions | Multi-robot test with robots 10 km apart | met (static regions) | Regions.RobotsTenKilometresApartRunInTheirOwnRegions: the robot 10 km out drives exactly as one alone at the origin. Owed: moving robots between regions while running, agent levels of detail |
| Geospatial pipeline | Sample 40 km world built by CI from open data | met, locally | tools/ci/build_sample_world.sh (Copernicus DEM GLO-30 and OpenStreetMap; licences read and recorded in dependencies.md); GitHub Actions are disabled, so it ran locally |
| Renderer scale | Frame budget during streaming | not done | The viewer receives each tile change as a full snapshot; per-tile acceleration structures and instancing are owed. The GPU lidar does not see height fields yet |
| Protocol additions | No protocol major change | met | LocalFrame.region_enu, SetCameraInterest, the recordings' /lagrange/scene/frame channel; the protocol stays v1. Incremental tile deltas in SceneDelta are owed |
Known issues
- A tile change rebuilds the run. That takes about a second for the Zurich sample, and the
run waits meanwhile. MuJoCo's spec API names meshes in quadratic time, so worlds with many
hull colliders near the robot load slowly. - Not followed or not read:
- external 3D Tiles tilesets;
- OSM multipolygon relations;
- OSM PBF (libosmium is not used yet).
- Third-party plugins (C ABI) are not told about a rebase.
- Radiation stays a zero substitute (post-1.0, the owner's decision of 2026-10-29).
- From earlier releases: Jolt's drive-wheel slip, Nav2's occasional start-up discovery
failure, rotor strobing in the viewer. - Not run while GitHub Actions are disabled: the sanitizer builds and the nightly jobs.
Everything else was verified locally with colcon: 996 tests, 0 failures, and the four
tutorial scripts and the sample-world script pass.
Release checklist
- Every v0.7 epic done, partly done or owed, with evidence above
- Release notes
- Gated changes merged under the v0.7 mandate and listed for review (
progress.md) - Owner review of those merges (
worldschemas,LocalFrame.region_enu,SetCameraInterest) - GitHub Actions re-enabled and green on
dev - Released:
devmerged intomainand taggedv0.7.0on 2026-10-29
Lagrange v0.6.0: cars and autonomous cars
Lagrange v0.6.0: cars and autonomous cars (release notes)
v0.5 added the world around the robot. v0.6 adds road vehicles and the world they drive in:
- cars with tyres, suspension, brakes, steering and a powertrain;
- road networks from OpenDRIVE, with traffic and pedestrians on them;
- OpenSCENARIO scenarios;
- the sensors of an automated car: radar and a camera sensor model;
- interfaces for autonomy stacks, Autoware's included.
Status: released on 2026-10-25 as v0.6.0, at the owner's request.
Highlights
- Vehicle dynamics (
lagrange_vehicle_dynamics, domains/vehicle_dynamics.md §8).- A raycast vehicle on top of either physics backend, at 1 ms.
- Suspension preloaded at the ride height, with anti-roll bars.
- MF-Tyre 5.2 tyres from
.tirfiles (pure and combined slip), or linear tyres, with
relaxation lengths. - Brakes with bias and ABS. Ackermann steering with a rate limit and lag.
- Electric or engine-map powertrains with an automatic gearbox.
- The
idealsubstitute, a kinematic bicycle.
- Road networks (
lagrange_opendrive, formats.md §3.11).- Its own OpenDRIVE reader: lines, arcs, spirals, cubic polynomials, elevation, lane sections
and offsets, marks, links and junctions. lagrange_opendrive_importwrites road surfaces, road marks andRoadLaneAPI_1lanes.
- Its own OpenDRIVE reader: lines, arcs, spirals, cubic polynomials, elevation, lane sections
- Traffic (
lagrange_traffic, domains/traffic.md §8).- Kinematic agents, moved by MuJoCo as mocap bodies and by Jolt as kinematic bodies.
- IDM cars on the lanes, fixed-cycle lights, first-come right of way at junctions.
- Social-force pedestrians on the sidewalks.
--traffic vehicles=N,pedestrians=M,seed=S; thezerosubstitute.
- Scenarios (
lagrange_openscenario, traffic.md §8.1).- Its own runner for a subset of OpenSCENARIO 1.x: parameters, entities, Init, speed and
lane-change actions, and time, position, distance, speed and travelled conditions. --scenario FILE.xosc: the scenario's roads are the world unless--worldis given.
- Its own runner for a subset of OpenSCENARIO 1.x: parameters, entities, Init, speed and
- Sensors (domains/sensors.md §2).
- Radar by ray launching (
RadarAPI_1): echoes from the bodies' radar cross-section density,
one detection per object and range cell, Doppler, SNR by the radar equation. - The camera's sensor model: lens distortion (plumb_bob, equidistant), vignetting, a
rotational rolling shutter, exposure with shot and read noise, and auto exposure.
camera_infocarries the lens.
- Radar by ray launching (
- Driving a car over ROS 2.
/ackermann_cmd(steering angle and speed) for any road
vehicle, beside/cmd_vel. - Autoware (
lagrange_autoware, docs/guide/autoware.md).- A vehicle interface: Autoware's control, gear and indicator commands and its control-mode
request in; velocity, steering, gear and control-mode reports and a ground-truth kinematic
state out. - It builds only when the Autoware messages are found, since
autoware_vehicle_msgshas no
Lyrical binary.
- A vehicle interface: Autoware's control, gear and indicator commands and its control-mode
- Schemas.
- New libraries:
vehicle(VehicleAPI_1,WheelAPI_1) androad(RoadLaneAPI_1). - New:
RadarAPI_1. CameraSensorAPI_1gainselectronRateandvignetting.- Robots are named by their top prim, and kinematic bodies are part of the world tables.
- New libraries:
- Samples.
- The sedan: a URDF, with a USD layer for its vehicle schemas, radar and camera model.
- The city block: buildings, and OpenDRIVE roads written by
city_block_xodr.py. - The tyre file
generic_205_55R16.tir, the scenariocut_in.xosc, and the profile
sedan_city.yaml.
- Docs.
- The cars tutorial (
docs/guide/tutorial-cars.md, run bytools/ci/tutorial_cars.sh). - The Autoware guide.
- The cars tutorial (
Acceptance (roadmap §7)
| Epic | Acceptance | Status | Evidence |
|---|---|---|---|
| Vehicle dynamics | domains/vehicle_dynamics.md §7 |
partly met | Braking from 20 m/s within 5 % of v²/(2μg) (3.2 %), steady-state yaw rate within 3 % of the linear bicycle model (1.4 %), gear shifting, ride height (test_vehicle_dynamics); the Magic Formula's peak, slope and asymptote exact (test_tyre). Owed: a published MF parameter set (no openly licensed one found), the ISO manoeuvres, sloped ground, sim-vs-real |
| PhysX backend | Backend-agreement tests | not done | Left out by the owner's v0.6 decision (no new external engines). Vehicles run on MuJoCo and Jolt |
| OpenDRIVE | Alignment tests | met | Geometry of each road type against closed forms, lanes meeting end to start through links and junctions (test_opendrive). Owed: superelevation, lane heights, objects and signals |
| OpenSCENARIO | Conformance subset | partly met | The sample cut-in runs to its stop trigger with its events at the times and places its triggers say (test_openscenario, and in the server). Not built: esmini (the owner's decision), catalogs, the ASAM example scenarios |
| Traffic | domains/traffic.md §7 |
partly met | IDM equilibrium, light cycle, flowing traffic with no entry on red, pedestrians on their sidewalks, same seed same tracks (test_traffic). Not built: SUMO (the owner's decision). Owed: the pedestrian fundamental diagram |
| Tier 2 sensors | Tier-agreement and camera tests; RTF metric | partly met | Radar: a plate's RCS within 3 %, Doppler, the detection range by the radar equation (test_radar). Camera model: OpenCV's lens formulas, the photon-transfer variance within 3 % (EMVA 1288), cos⁴θ, rolling-shutter skew, auto exposure (test_camera_model). Both run on the CPU on every tier; hardware ray-query versions and an RTF metric are owed |
| Zero-copy ROS output | Copy-count measurement | not done | Owed |
| Autoware bridge | Demo or documented fallback | met (fallback) | The interface tested against a stand-in for Autoware and the simulator (test_autoware_interface); the documented fallback in docs/guide/autoware.md. Autoware itself is not released for Lyrical and was not run |
| Sample sedan, city block, tutorials | Tutorials run in CI where no external stack is needed | met, locally | tools/ci/tutorial_cars.sh runs every step; it passes locally (GitHub Actions are disabled) |
Known issues
- Not built, by the owner's v0.6 decision: the PhysX backend, SUMO co-simulation and esmini.
- Traffic: the lights are not drawn, pedestrians do not cross roads, no lane changes or
priority rules. - Radar: no rain attenuation, multipath or ghosts. Ground-plane echoes are dropped as
clutter. - Camera: no motion blur, no absolute light level (the scene's brightness is the camera's
electronRate), no colour filter array. SDFormat's<distortion>and<noise>are not
imported. - Autoware: the
/sensing/...remaps in the launch file follow Autoware's sample sensor kit
and need checking against the kit in use. - Scenarios: editing the scene after a scenario has ended logs its end a second time.
- From earlier releases: Jolt's drive-wheel slip, Nav2's occasional start-up discovery failure,
rotor strobing in the viewer. - Not run while GitHub Actions are disabled: the sanitizer builds and the nightly jobs.
Everything else was verified locally with colcon: 882 tests abovelagrange_core(with the
Autoware messages underlay), 0 failures.
Release checklist
- Every v0.6 epic done, partly done or left out by the owner's decision, with evidence above
- Release notes drafted
- Gated changes merged under the v0.6 mandate listed for review (
progress.md) - Owner review of those merges (the vehicle, road, radar and camera schema changes)
- GitHub Actions re-enabled and green on
dev - Released:
devmerged intomainand taggedv0.6.0on 2026-10-25 at the owner's request
(release-please could not run with GitHub Actions disabled)
Lagrange v0.5.0: weather, interference and radio links
Lagrange v0.5.0: weather, interference and radio links (release notes)
v0.4 added drones. v0.5 adds the world around the robot:
- the site's atmosphere, with fog, rain and dust that blind lidars and cameras and wet the floor;
- volumetric fields of fog and wind, including wind imported from OpenFOAM;
- electromagnetic interference from power lines, drives, welders and transmitters;
- radio links and CAN buses whose losses reach the robot's ROS 2 topics.
Status: released on 2026-10-25 as v0.5.0, at the owner's request.
Highlights
- Weather (
lagrange_weather, domains/weather.md §8).- The site has no defaults. Temperature, pressure and humidity come from the profile,
--weatheror aWeatherAPI_1prim. - Moist air density.
- Fog: Koschmieder at 550 nm, Kim's wavelength exponent for 905 and 1550 nm.
- Rain: Marshall–Palmer. Dust: quartz spheres.
- Behavioural wet friction (applied by both physics backends) and lens contamination.
- The
clearsubstitute.
- The site has no defaults. Temperature, pressure and humidity come from the profile,
- Sensors in weather.
- The lidar's range follows the lidar equation through the extinction and a dirty window.
- False returns from fog backscatter and from raindrops, on their own random stream.
- The camera's Koschmieder veil.
- All per beam on the CPU, on every tier.
- Fields (
lagrange_fields, NanoVDB 10.0.1, MPL-2.0).- Fog and wind grids, compressed to a few kB.
- The lidar integrates fog along each beam, the camera per block of pixels, and link drag and
rotors fly in the wind grid. - The viewer's Environment workspace gets the real weather and slices of fog, wind and |B|.
- Samples: a fog bank in the warehouse and a sheared wind with a wake over the open field.
- Wind from CFD.
lagrange_foam_to_vdbturns an OpenFOAM case's ASCII cell centres and
velocities into a wind grid. OpenFOAM is not a dependency. - EMI (
lagrange_emi, domains/emi.md §8).- Sources:
- power lines, as straight conductors with harmonics;
- motor drives, as dipoles driven by their motor's current;
- welders;
- transmitters, by their far field;
- field maps.
- Victims: magnetometers add the field at their own rate, so a 60 Hz line aliases, and IMUs
add noise. - Encoder glitches (applied to ros2_control's encoders), CAN bit-error rate, radio
interference power and harness voltage. - Grid frequencies are site parameters. The
zerosubstitute.
- Sources:
- Comms (
lagrange_comms, domains/comms.md §8).- Radio links: log-distance path loss, walls of the fixed scenery, correlated shadowing, noise
plus EMI interference, AWGN bit errors for BPSK to 64-QAM, and retries. - CAN fault confinement by ISO 11898-1.
--link-topicsmakes the ROS 2 bridge lose and delay mapped topics,/cmd_velincluded.- The
idealsubstitute.
- Radio links: log-distance path loss, walls of the fixed scenery, correlated shadowing, noise
- Schemas.
- New:
WeatherAPI_1,EmiSourceAPI_1,EmiSusceptibilityAPI_1,SensorMaterialAPI_1,
RadioLinkAPI_1,CanBusAPI_1. - The loader places every prim on its body, so sources, victims and radios move with the
robot.
- New:
- Command line.
--weather,--link-topics, and--domain weather|emi|comms=off. Units
sandbit/s. - Samples.
- Profiles:
amr_fog.yaml,quad_x500_power_line.yaml. - Robots:
quad_x500_emi.usda,amr_diffdrive_wifi.usdawith its link map. - World:
power_line.usda. - Fields:
assets/fields/*.nvdb.
- Profiles:
- Docs. The environment tutorial (
docs/guide/tutorial-environment.md, run by
tools/ci/tutorial_environment.sh).
Acceptance (roadmap §6)
| Epic | Acceptance | Status | Evidence |
|---|---|---|---|
| Weather module | domains/weather.md §7 |
partly met | Koschmieder and Beer–Lambert exact, dust, moist air (test_weather). Rain rate recovered within 20 %, not 5 %: Marshall–Palmer with Atlas's fall speeds is that loose, and the test states it. Wet friction applied by MuJoCo and Jolt; the literature range check is owed |
| Sensor weather effects | Detection-range validation | partly met | The lidar equation, clutter trends and Koschmieder's veil are tested (test_weather_effects), and end to end in the server. Calibration against fog- and rain-chamber data (DENSE) is owed; the fog clutter gain is uncalibrated. GPU kernels were not needed (per-beam CPU on every tier) |
| Fields infrastructure | Analytic-field tests; NanoVDB version (R10) | met, with owed items | test_fields (trilinear exactness, optical depth, vector shear); NanoVDB 10.0.1 chosen. GPU sampling is not needed yet. The viewer shows 2D slices, not 3D volumes |
| EMI module | domains/emi.md §7 |
partly met | Conductor, dipole and far-field closed forms at 1e-6; the 60 → 40 Hz alias exact (test_emi); the quadcopter's magnetometer reads 8.08 µT RMS at 9.9 m from 400 A, as μ0·I/(2πd) gives. Owed: published field measurements near lines; the end-to-end recording (Q16) |
| Comms module | domains/comms.md §7 |
partly met | Friis, k·T·B, the BPSK 1e-5 point, exact CAN transitions, wall counting and the shadowing spread (test_comms); topics lost and delayed in the ROS 2 bridge. Owed: ITU-R P.1238 parameters, the RSSI recording (Q16), the MAVLink bridge |
| Offline CFD import | Round trip of an analytic field | met | test_fields' Foam tests: a linear wind through OpenFOAM-format files within 1e-5; coarser voxels average to the voxel centre. A real case's files are not checked yet (no OpenFOAM install) |
| Schemas | RFC 0002 amendments accepted | waiting for the owner | Merged under the v0.5 mandate (progress.md); the owner's review is open |
Known issues
- Not applied yet: CAN errors on any bus traffic but the modelled node's, and the MAVLink
bridge's telemetry over a link.
SensorMaterialAPI_1is defined but no sensor reads it. - Uncalibrated: the lidar's fog clutter gain, and the indoor radio parameters of the samples.
- NanoVDB is header-only (
libnanovdb-dev). Until it is installed on a machine, the build
uses a local copy of the headers (NANOVDB_INCLUDE_DIRor~/.local/nanovdb). - Start-up warnings. The Python API and
lagrange validatebuild a run before they apply a
profile, so they still log the missing site parameters that the profile then gives. - From earlier releases: Jolt's drive-wheel slip, Nav2's occasional start-up discovery failure,
rotor strobing in the viewer. - Not run while GitHub Actions are disabled: the sanitizer builds and the nightly jobs.
Everything else was verified locally with colcon: 811 tests abovelagrange_core, 0
failures.
Release checklist
- Every v0.5 epic done or partly done, with evidence above
- Release notes drafted
- Gated changes merged under the v0.5 mandate listed for review (
progress.md) - Owner review of those merges (the weather, EMI, sensor-material and comms schemas)
- GitHub Actions re-enabled and green on
dev - Released:
devmerged intomainand taggedv0.5.0on 2026-10-25 at the owner's request
(release-please could not run with GitHub Actions disabled)
Lagrange v0.4.0: drones
Lagrange v0.4.0: drones (release notes)
v0.3 added arms and the electrical and thermal domains. v0.4 adds drones: rotors built from
their propellers' blades, wind and turbulence, GNSS, magnetometer and barometer, a sample
quadcopter that flies on its own power system, and PX4 and ArduPilot flying it in lockstep.
Status: released on 2026-10-25 as v0.4.0, at the owner's request.
Highlights
- Rotors.
RotorAPI_1on rotor joints, with the propeller's hand, its mount (puller or pusher) and
its propeller file (*.prop.yaml: blade chord, twist and sections from root to tip).- The
coefficientsfidelity: thrust and torque from measured CT and CP, inflow lag,
Cheeseman–Bennett ground effect. - The
bemfidelity: blade-element momentum on the propeller's geometry, in climb, descent,
forward flight and wind; turning the wrong way or mounted back to front, a propeller gives
what a real one gives. Checked against NACA Report 640's full-scale propeller, with nothing
fitted. Each propeller is tabulated once at load, so a step is a lookup. - Folding blades that hang folded when stopped and open as they spin up.
- Rotors are drawn as their blades in the viewer, spinning and folding.
- Aerodynamics and wind. Link drag (
AeroAPI_1) against a logarithmic mean wind with
Dryden turbulence; the wind reaches the rotors (env/wind/velocity). - Sensors. GNSS, magnetometer (World Magnetic Model 2025) and barometer (ICAO standard
atmosphere) on the site's geo origin, published on ROS 2 asNavSatFix,MagneticField,
FluidPressureandTemperature. - Autopilots. PX4 v1.17.0 SITL through its simulator MAVLink interface, and ArduPilot
Copter-4.7.2 through its JSON interface, both in lockstep (--mavlink px4|ardupilot). Both fly
a square mission, calm and in 8 m/s of gusty wind. - Electrical. Small fast motors at 50 µs; a low battery sags the bus and costs thrust.
- Samples.
quad_x500(URDF, overlay, USD) with generic 10-inch propellers matched to the
measured APC 10x4.7 SF; variants with folding blades and with motors under the arms
(pushers); two- and three-blade propellers; theopen_fieldworld; profiles for hover, gusty
wind and the blade-element fidelity. - Docs. The drone tutorial, from the quadcopter's files to a PX4 mission
(docs/guide/tutorial-drone.md, run bytools/ci/tutorial_drone.sh).
Acceptance (roadmap §5)
| Epic | Acceptance | Status | Evidence |
|---|---|---|---|
| Rotor aero | domains/aerodynamics.md §7 |
met, with owed items | test_rotor_aero (closed forms, ground effect, lag), test_bem: NACA Report 640 propeller 5868-9 within 8 % CT and 6 % CP over the attached-flow range, momentum theory, the classical H-force within 1 %; owed: small-propeller test data (the UIUC database states no licence), measured ground effect, stall delay |
| Aerodynamics and wind | Spectra and field tests | partly met | Dryden variances and correlation time (test_aerodynamics; the periodogram check of the spectrum is not done); field sampling (VDB) moves to v0.5 with the fields infrastructure |
| MAVLink bridge | Mission scenario in robot-classes.md §5 |
met | tools/ci/px4_mission.sh [--wind], tools/ci/ardupilot_mission.sh [--wind]: take-off, 10 m square at 5 m, landing; test_px4_lockstep, test_ardupilot_json |
| Sensors | Sensor tests | met | test_wmm (100 NOAA test points, worst 7e-4 nT), test_geo_sensors |
| ESC and battery at 50 µs | Coupling tests at J = 1e-5 kg·m² | met | test_coupling's DroneCoupling: within 2 % RMS of a 1 µs reference |
| Sample quadcopter and tutorial | Tutorial runs in CI with SITL in a container | partly met | The tutorial runs headless with both SITL steps on the development machine, and in the container image without them (podman run --rm lagrange:dev tools/ci/tutorial_drone.sh: hover, gusty wind and the site checked; PX4 and ArduPilot are not in the image, so their steps are left out) |
| Rebase in flight | huge-worlds.md §6 |
deferred | Needs the runtime rebase (C5), which the owner deferred to v0.7 |
Known issues
- Blade-element limits. No wake skew or blade flapping beyond the hub moment; no stall
delay, so a highly pitched propeller's thrust near static is under-predicted
(aerodynamics.md §7.1). - Dryden turbulence. MIL-HDBK-1797 equation numbers are marked TODO(verify) in the code.
- Viewer. Rotors at hundreds of rad/s are drawn at the frame rate, so the blades strobe.
- Start-up warnings.
lagrange validateand the Python API build a run before they apply a
profile, so they log that rotors and geo sensors need their site parameters even when the
profile gives them. - From v0.3: Jolt's drive-wheel slip, Nav2's occasional start-up discovery failure.
- Not run while GitHub Actions are disabled: the sanitizer builds and the nightly jobs.
Everything else was verified locally with colcon.
Release checklist
- Every v0.4 epic done or moved, with evidence above
- Release notes drafted
- Gated changes merged under the v0.4 mandate listed for review (
progress.md) - Owner review of those merges (the aerodynamics and geo sensor schemas,
RotorAPI_1's
propeller and mount) - GitHub Actions re-enabled and green on
dev - Released:
devmerged intomainand taggedv0.4.0on 2026-10-25 at the owner's request
(release-please could not run with GitHub Actions disabled)
Lagrange v0.3.0: arms, electrical and thermal
Lagrange v0.3.0: arms, electrical and thermal (release notes)
v0.2 was the simulation core and the AMR. v0.3 adds the electrical and thermal domains, a robot
arm with MoveIt 2, a raster camera, a second physics engine, and replay in the C++ server. The
AMR now drives on its own power system: a battery, a DC bus and two motor drives at 100 µs.
Status: released on 2026-10-25 as v0.3.0, at the owner's request, after v0.2.0.
Highlights
- Electrical.
- Six USD schemas (
ElectricalMotorAPI_1,BatteryAPI_1,PortAPI_1, bus, load,
converter), with ports on the same prims as the 3D parts. - A network module: DC bus with capacitor, battery equivalent circuit, averaged dq motor
drives with current loops, regeneration, brake resistor and trips, DC-DC converters
between buses. - Controllers command torque; the electrical domain delivers it, or its ideal substitute does.
- Overlay files give an imported robot motors, a battery and a bus without editing its URDF.
- Export to an ngspice netlist or a Modelica model (
lagrange export). - An FMI 3.0 co-simulation host, with a reference FMU (
lagrange_models/dc_drive).
- Six USD schemas (
- Thermal.
- Lumped thermal networks (
ThermalAPI_1,ThermalLinkAPI_1) heated by the electrical
losses, with derating. - The network runs when the site's ambient temperature is given.
- Lumped thermal networks (
- Coupling. Stability checks across the electrical, thermal and physics rates at start-up;
physics reports each joint's effective inertia for the motor models. - Bench mode.
--bench run.mcapreplaces physics by a recorded run; electrical, thermal and
sensors run live, at 10 kHz electrical, about 59× real time. - Replay.
lagrange_server --replay run.mcapreplays a recording to the viewer, with
seeking. The Python mock server is now a test tool (Q15). - Arm. The sample 6-DoF arm
arm6in a workcell; MoveIt 2 pick-and-place through
joint_trajectory_controllerat 1 kHz; a wrist camera. - Camera. A raster camera sensor (colour, depth, instance ids) on the same mesh pipeline as
the viewer's viewport, published as ROSImageandCameraInfoand shown in the viewer. - Physics.
- Jolt Physics 5.6 as a complete second backend (
--physics jolt, or the profile's
rigid_body.backend), checked against MuJoCo by an agreement suite. - Convex hull colliders in the world, in USD, in both backends and in the lidar (CPU and
GPU). collision_bakemakes them from render meshes with CoACD.
- Jolt Physics 5.6 as a complete second backend (
- Schemas and profiles.
migrate_schemaandmigrate_profilebring old files up to date;
the stage loader names the command when it meets an older schema version. - Viewer.
- Scene editing: schema values change in a running simulation from the inspector.
- The Electrical workspace runs on the simulator's power system.
- Thermal false-colour and unlit shading in the viewport.
- The camera view in the Sensors workspace.
Acceptance (roadmap §4)
| Epic | Acceptance | Status | Evidence |
|---|---|---|---|
| Electrical network | domains/electrical.md §8 tests |
met, with owed items | test_models, test_network, test_battery_dataset (LG HG2 cell data, CC BY 4.0: 5.4 to 6.2 mV RMS from 46 to 89 % state of charge, 21.5 mV at 24 %); owed: below 35 % state of charge, sim-vs-real (Q16), the drive-design review of the motor constants (RFC 0002 resolution 2) |
| Coupling stability | architecture.md §8 tolerances |
met | test_coupling; architecture.md §8.1; the scheduler steps flow readers at their window's end |
| Thermal | domains/thermal.md §7 tests |
met, with owed items | test_lumped, test_thermal_network, test_thermal_coupling; owed: a published or recorded motor heat run (Q16) |
| FMU host | A reference FMU runs in place of the built-in motor model; Q8 closed | met; Q8 partly open | test_fmu_host with lagrange_models/dc_drive; on fmilibrary3_vendor, since Lyrical's fmilibrary_vendor is FMI 2.0 only. Accepting FMI 2.0 FMUs is still open in Q8 |
| Bench mode | bench_electrical_replay.yaml runs at 10 kHz in real time on a laptop CPU |
met | About 59× real time on the development laptop |
| Arm integration | Scenario in robot-classes.md §4 |
met | tools/ci/arm_scenario.sh (derating scenario, about ten minutes) |
| Camera sensor (raster) | Projection tests; the viewer shows the sensor view | met | OpenCV finds checkerboard corners within 0.066 px mean of the pinhole model; calibration recovers fx, fy, cx, cy with RMS 0.07 px; Sensors workspace camera view |
| Schema migration tooling | Round-trip tests | met | tools/migrate/test (synthetic ExampleMotorAPI_0 → _1; profiles version 0 → 1, comments kept) |
| Exports | Netlist runs in ngspice | met | test_export: round trip in ngspice within 0.05 %; Modelica checked for structure only (no OpenModelica on the machine) |
| Second rigid-body backend | Backend-agreement tests | met, with a known issue | server/test/test_backends.cpp; Jolt wheel slip below |
| Viewer additions | Golden images | met | test_headless.py: Electrical workspace on the schematic colours, thermal shading against the simulator (lit vs thermal) |
v0.2 items that moved here are done: G2 overlay files, B8 collision bake, E6 scene editing, E8
replay in the C++ server. H7 (a thin electrical slice) was replaced by the full domain. C5
(runtime rebase) stays deferred to v0.7.
Known issues
- Jolt: drive wheels slip while ramping up. On Jolt's rigid contacts the sample AMR's
casters take most of the load; after the 6 s demo drive Jolt is about 0.4 m behind MuJoCo.
MuJoCo stays the default. - Nav2 start-up (from v0.2): some launches have one ROS process never discover another's
endpoint. Mitigated by retries; root cause not found. - Not run while GitHub Actions are disabled: the sanitizer builds of the USD packages and
the nightly jobs. Everything else was verified locally with colcon.
Release checklist
- Every v0.3 epic done, with evidence above
- Release notes drafted
- Gated changes merged under the autonomous mandate listed for review (
progress.md) - Owner review of those merges (the electrical, thermal and camera schemas, the C ABI)
- The v0.2.0 release published first (2026-10-25)
- GitHub Actions re-enabled and green on
dev - Released:
devmerged intomainand taggedv0.3.0on 2026-10-25 at the owner's request
(release-please could not run with GitHub Actions disabled)