Skip to content

Releases

Lagrange v1.4.0: build a robot in the viewer

Choose a tag to compare

@Danendra10 Danendra10 released this 16 Nov 15:36
73d0995

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 amr

The 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_iterations profile 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 world assets/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.ParallelEnvs over shared memory (no pickling per step); environments take
    profile=, overlay= and world=.
  • command_joint returns a JointCommand saying 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_entity follows allow_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's ROS_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_joint returns a lagrange.JointCommand instead of a bool: if, not,
    == True and == False behave as before; is True and JSON serialisation do not. Targets
    beyond the robot file's limits are clamped (Python and the viewer; ROS /joint_commands is
    not).
  • /spawn_entity renames on a clash only with allow_renaming: true; otherwise a taken name
    fails with NAME_NOT_UNIQUE, text naming no robot with NAME_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

Choose a tag to compare

@Danendra10 Danendra10 released this 14 Nov 12:45
155bc43

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 amr

Sensors

  • 37 built-in sensor kinds (a URDF <sensor type="KIND"> or USD CustomSensorAPI_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;
    example lagrange_example_sensors.
  • On ROS 2 by default on standard messages (Range, LaserScan, Odometry, BatteryState,
    WrenchStamped, vision_msgs Detection2D/3DArray, ...), images with camera_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 huge Step freezing 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 on restore_state, NaN accepted from the command
    line and Python.

Upgrading from 1.2.x

  • Saved states (Server::saveState, Python save_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

Choose a tag to compare

@Danendra10 Danendra10 released this 10 Nov 22:19
c9331ef

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.
    The tether domain 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 conduction fidelity 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_probe adds a contact thermistor and an infrared spot
      thermometer.
    • Thermal cameras read each part with its material's emissivity.
  • New commands:
    • lagrange heat ROBOT --ambient-temperature K gives 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_1 gains wire sources, 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_error and interference, 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 FRACTION caps 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_heat and lagrange_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);
  • --tether or TetherAPI_1;
  • --emi-motor-leads or wire sources;
  • --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_core passes, Autoware's tests
    included with its message underlay.
  • Docs and examples: tools/docs/build.sh --check passes; tools/ci/check_examples.py runs
    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

Choose a tag to compare

@Danendra10 Danendra10 released this 07 Nov 03:30
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)

Lagrange v1.0.0: stable

Choose a tag to compare

@Danendra10 Danendra10 released this 28 Oct 21:01
20bf50f

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.json lists all 27 schemas and 240 properties, and the
      schema test compares against it;
    • plugin ABI: struct layouts are pinned by test_abi_layout.c, and tools/ci/abi_check.sh
      runs abidiff when libabigail is installed;
    • protocol: buf breaking uses the FILE rules;
    • profiles and recordings: every sample file since v0.5.0 is migrated in a test.
  • Plugin ABI 1.0 adds shift_origin, so a plugin that keeps world positions follows the
    floating origin.
  • Migrations. migrate_recording joins migrate_schema and migrate_profile.
    test_old_releases.py checks 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.
  • 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.md and 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: dev merged into main, tagged v1.0.0, and release/1.x branched

Lagrange v0.7.0: huge worlds

Choose a tag to compare

@Danendra10 Danendra10 released this 28 Oct 18:49
6c7fd3f

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 sample AMR in the 40 km Zurich world: terrain, buildings and roads streamed around it
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 /odom and TF stay continuous, and
      recordings store each new frame.
  • Tile streaming (§2.1).
    • WorldTileAPI_1 (new world schema 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_radius and collision_radius.
    • Sample: assets/worlds/tiled_town.
  • Active regions (§3.1).
    • --add-robot NAME=FILE@X,Y puts more robots in a run.
    • server::RegionHost runs 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_world builds 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.sh builds the 40 km Zurich sample from the Copernicus DEM
      and OpenStreetMap.
  • Height field terrain.
    • New ShapeType::HeightField: MuJoCo hfield, Jolt HeightFieldShape, 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.
  • 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).
  • 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 (world schemas, LocalFrame.region_enu, SetCameraInterest)
  • GitHub Actions re-enabled and green on dev
  • Released: dev merged into main and tagged v0.7.0 on 2026-10-29

Lagrange v0.6.0: cars and autonomous cars

Choose a tag to compare

@Danendra10 Danendra10 released this 25 Oct 10:15
10bb861

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 .tir files (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 ideal substitute, 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_import writes road surfaces, road marks and RoadLaneAPI_1 lanes.
  • 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; the zero substitute.
  • 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 --world is given.
  • 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_info carries the lens.
  • 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_msgs has no
      Lyrical binary.
  • Schemas.
    • New libraries: vehicle (VehicleAPI_1, WheelAPI_1) and road (RoadLaneAPI_1).
    • New: RadarAPI_1.
    • CameraSensorAPI_1 gains electronRate and vignetting.
    • Robots are named by their top prim, and kinematic bodies are part of the world tables.
  • 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 scenario cut_in.xosc, and the profile
      sedan_city.yaml.
  • Docs.
    • The cars tutorial (docs/guide/tutorial-cars.md, run by tools/ci/tutorial_cars.sh).
    • The Autoware guide.

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 above lagrange_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: dev merged into main and tagged v0.6.0 on 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

Choose a tag to compare

@Danendra10 Danendra10 released this 25 Oct 07:32
5fb79d0

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,
      --weather or a WeatherAPI_1 prim.
    • 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 clear substitute.
  • 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_vdb turns 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 zero substitute.
  • 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-topics makes the ROS 2 bridge lose and delay mapped topics, /cmd_vel included.
    • The ideal substitute.
  • 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.
  • Command line. --weather, --link-topics, and --domain weather|emi|comms=off. Units
    s and bit/s.
  • Samples.
    • Profiles: amr_fog.yaml, quad_x500_power_line.yaml.
    • Robots: quad_x500_emi.usda, amr_diffdrive_wifi.usda with its link map.
    • World: power_line.usda.
    • Fields: assets/fields/*.nvdb.
  • 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_1 is 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_DIR or ~/.local/nanovdb).
  • Start-up warnings. The Python API and lagrange validate build 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 above lagrange_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: dev merged into main and tagged v0.5.0 on 2026-10-25 at the owner's request
    (release-please could not run with GitHub Actions disabled)

Lagrange v0.4.0: drones

Choose a tag to compare

@Danendra10 Danendra10 released this 25 Oct 05:00
dc3d4eb

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_1 on 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 coefficients fidelity: thrust and torque from measured CT and CP, inflow lag,
      Cheeseman–Bennett ground effect.
    • The bem fidelity: 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 as NavSatFix, MagneticField,
    FluidPressure and Temperature.
  • 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; the open_field world; 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 by tools/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 validate and 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: dev merged into main and tagged v0.4.0 on 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

Choose a tag to compare

@Danendra10 Danendra10 released this 25 Oct 00:32
086ac31

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).
  • 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.
  • 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.mcap replaces physics by a recorded run; electrical, thermal and
    sensors run live, at 10 kHz electrical, about 59× real time.
  • Replay. lagrange_server --replay run.mcap replays a recording to the viewer, with
    seeking. The Python mock server is now a test tool (Q15).
  • Arm. The sample 6-DoF arm arm6 in a workcell; MoveIt 2 pick-and-place through
    joint_trajectory_controller at 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 ROS Image and CameraInfo and 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_bake makes them from render meshes with CoACD.
  • Schemas and profiles. migrate_schema and migrate_profile bring 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: dev merged into main and tagged v0.3.0 on 2026-10-25 at the owner's request
    (release-please could not run with GitHub Actions disabled)