Repository navigation
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)