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