Skip to content

Lagrange v1.1.0: easier to use, checked against measurements

Choose a tag to compare

@Danendra10 Danendra10 released this 07 Nov 03:30
· 163 commits to dev since this release
36a4526

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

  • lagrange runs the server and the viewer together, the way gazebo does
    (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 spawn and lagrange 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=5 and 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 check says which joints cannot hold the robot. lagrange bake splits 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.envs offers 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_tof time-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 foam writes 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 local colcon build and colcon 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: dev merged into main, tagged v1.1.0, release/1.x brought up to it
  • Packages published and signed (maintainers, packaging/README.md)