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.