Formats¶
Status: draft for review. Schema details are decided in rfcs/0002-usd-schemas.md; the profile
format in rfcs/0005-sim-profile-format.md. This document expands CLAUDE.md §4, §11.1 and §11.3.
1. One home per kind of data¶
Data |
Format |
Written by |
Read by |
Notes |
|---|---|---|---|---|
Robot, world, component placement |
OpenUSD ( |
importers, users, viewer (session layer) |
|
Never read in |
Rigid bodies, joints, colliders |
UsdPhysics schemas |
importers |
|
Standard schema, not ours |
Electrical topology, thermal, aero, EMI, radiation, sensor materials |
Custom applied API schemas ( |
importers, users |
|
Versioned (section 3) |
Component behaviour |
FMU, FMI 3.0 co-simulation |
|
|
Referenced by |
Volumetric fields |
OpenVDB on disk, NanoVDB at runtime |
offline tools ( |
field-sampling kernels |
Referenced by |
Simulation profile |
YAML, validated by |
users, viewer domain panel |
server, mock server |
Section 5 |
Recordings |
MCAP, Protobuf-encoded messages |
|
replay substitutes, mock server, viewer |
Section 7 |
Mesh import |
glTF 2.0, OBJ, STL, DAE |
— |
|
Never loaded at runtime |
Materials |
UsdPreviewSurface (baseline); MaterialX (optional, later) |
importers |
viewer renderer, camera sensor |
Section 8 |
Collision geometry |
Convex hulls in USD ( |
|
rigid-body backends, sensors |
Never the render mesh |
UI↔server protocol |
Protobuf (proto3) |
server, mock server |
viewer |
|
Robot description import |
URDF/xacro, SDFormat, MJCF |
— |
|
Section 9 |
Roads, scenarios |
OpenDRIVE, OpenSCENARIO |
— |
|
v0.6 |
Geospatial |
OGC 3D Tiles, GeoTIFF/DEM, OSM |
— |
|
v0.7 |
2. Schema conventions¶
Applied API schemas only. Our schemas add properties to existing prims (
Xform, joints,Mesh,Material). No new concrete prim types, so files stay readable in any USD tool.Namespaces.
elec:,thermal:,aero:,emi:,rad:,sensmat:,sensor:. One namespace per schema library.Units. Every attribute is SI. Every attribute definition carries
lagrangeUnit = "<unit>", a metadata field registered by thelagrange_schemasplugin (SdfMetadatain itsplugInfo.json).core/stage/parses that string into alagrange::Unit(lagrange::parseUnit) and exposes it to modules, so the schema is the single source of unit truth.customDatacannot carry it:usdGenSchemadeletes property customData and the schema registry refuses it as a fallback (OpenUSD spike,docs/plan/spikes/0.2-B1-openusd.md).Types. Physical parameters are
double. The reference example in CLAUDE.md §11.3 usesfloat; see open question F4 for the reason to change.No hidden site constants. Attributes whose value depends on the site (mains frequency, ambient temperature, latitude) have no fallback value. A missing value is a load error. This implements the CLAUDE.md §10 rule on scenario parameters.
Versioning. Each schema is a family with an integer version suffix. This document writes
ElectricalMotorAPI_1. CLAUDE.md writesElectricalMotorAPI_v1. OpenUSD v26.08 parsesElectricalMotorAPI_1as familyElectricalMotorAPI, version 1 (Usd.SchemaRegistry.ParseSchemaFamilyAndVersionFromIdentifier, verified in the OpenUSD spike);_v1is not recognised as a version. Open question F3 recommends the USD convention.Codeless schemas. Schemas are registered with
skipCodeGeneration = true.core/stage/reads attributes by name into SoA pools, so generated C++ classes are not needed. This removesschemas/generated/C++ from the build (open question Q7).Topology lives on the 3D prims. Electrical ports and connections are relationships on the component prims, so the schematic view and the 3D view are two projections of the same data (CLAUDE.md §11.3).
Library header used by every schema.usda below (shown once):
#usda 1.0
(
subLayers = [ @usd/schema.usda@ ]
)
over "GLOBAL" (
customData = {
string libraryName = "lagrangeElectrical" # lagrangeThermal, lagrangeAero, ...
string libraryPath = "."
bool skipCodeGeneration = true
}
)
{
}
3. Draft schemas¶
Attribute tables give name, type, unit and fallback. “—” in the fallback column means the
attribute is required when the schema is applied. .usda text follows each table.
3.1 schemas/electrical/schema.usda¶
PortAPI_1 (multiple-apply, instance name = port name, e.g. elec:port:dc_in). An
electrical terminal pair on a component.
Attribute |
Type |
Unit |
Fallback |
Meaning |
|---|---|---|---|---|
|
token |
— |
|
|
|
double |
V |
— |
Rated voltage, used for sanity checks |
|
double |
A |
— |
Continuous rating |
|
rel |
— |
— |
Target port(s) or bus prim. Defines the net |
|
double |
ohm |
|
Lumped harness resistance to the net |
|
double |
H |
|
Lumped harness inductance |
BatteryAPI_1 (single-apply). Equivalent-circuit model: open-circuit voltage curve, series
resistance, two RC pairs, thermal dependence.
Attribute |
Type |
Unit |
Fallback |
Meaning |
|---|---|---|---|---|
|
token |
— |
|
|
|
int |
1 |
— |
Cells in series |
|
int |
1 |
|
Cells in parallel |
|
double |
C |
— |
Rated charge of the pack (1 Ah = 3600 C) |
|
double |
1 |
|
0…1 |
|
double[] |
1 |
— |
SoC breakpoints, ascending |
|
double[] |
V |
— |
Cell open-circuit voltage at each breakpoint |
|
double |
ohm |
— |
Cell series resistance at |
|
double |
ohm, F |
|
First RC pair (per cell) |
|
double |
ohm, F |
|
Second RC pair (per cell) |
|
double |
K |
|
Temperature at which |
|
double |
1/K |
|
Fractional change of |
|
double |
V |
— |
Pack under-voltage cut-off |
|
double |
A |
— |
Regeneration limit; excess raises bus voltage |
|
asset |
— |
none |
Optional FMU that replaces the built-in ECM |
ElectricalMotorAPI_1 (single-apply, on the prim that represents the motor; elec:joint
points at the driven joint).
Attribute |
Type |
Unit |
Fallback |
Meaning |
|---|---|---|---|---|
|
token |
— |
|
|
|
double |
ohm |
— |
Phase (or armature) resistance at |
|
double |
H |
— |
d-axis (or armature) inductance |
|
double |
H |
= |
q-axis inductance (salient machines) |
|
double |
N·m/A |
— |
Torque per q-axis ampere (peak) |
|
double |
V·s/rad |
= |
Line-neutral peak per mechanical rad/s; an authored value must agree within 3 % |
|
int |
1 |
|
|
|
double |
kg·m² |
|
Added to the joint’s armature inertia |
|
double |
1 |
|
Motor revolutions per joint revolution |
|
double |
1 |
|
0…1 |
|
double |
A |
— |
Drive current limit (peak) |
|
double |
K |
|
|
|
double |
1/K |
|
Copper, per kelvin (source: standard value for annealed copper at 20 °C; cite in code) |
|
token |
— |
|
|
|
double |
rad/s |
|
FOC current-loop bandwidth (1 kHz) |
|
double |
Hz |
|
Used for ripple estimate and EMI source spectrum |
|
token |
— |
|
|
|
asset |
— |
none |
Optional FMU that replaces the built-in model |
|
rel |
— |
— |
Driven joint prim |
|
rel |
— |
— |
Port or bus the drive draws from |
class "PortAPI_1" (
inherits = </APISchemaBase>
customData = {
token apiSchemaType = "multipleApply"
token propertyNamespacePrefix = "elec:port"
}
doc = "An electrical terminal pair on a component. Instance name is the port name."
)
{
uniform token kind = "dc" ( allowedTokens = ["dc", "ac1", "ac3", "signal"] )
double nominalVoltage ( lagrangeUnit = "V" )
double maxCurrent ( lagrangeUnit = "A" )
rel connectedTo ( doc = "Ports or bus prims on the same net." )
double wireResistance = 0.0 ( lagrangeUnit = "ohm" )
double wireInductance = 0.0 ( lagrangeUnit = "H" )
}
class "BatteryAPI_1" (
inherits = </APISchemaBase>
customData = { token apiSchemaType = "singleApply" }
doc = "Battery pack, equivalent-circuit model with two RC pairs."
)
{
uniform token elec:battery:chemistry = "li_ion_nmc" (
allowedTokens = ["li_ion_nmc", "lfp", "lead_acid", "custom"] )
int elec:battery:seriesCells
int elec:battery:parallelCells = 1
double elec:battery:capacity ( lagrangeUnit = "C" )
double elec:battery:initialSoc = 1.0 ( lagrangeUnit = "1" )
double[] elec:battery:ocvSoc ( lagrangeUnit = "1" )
double[] elec:battery:ocvVoltage ( lagrangeUnit = "V" )
double elec:battery:r0 ( lagrangeUnit = "ohm" )
double elec:battery:r1 = 0.0 ( lagrangeUnit = "ohm" )
double elec:battery:c1 = 0.0 ( lagrangeUnit = "F" )
double elec:battery:r2 = 0.0 ( lagrangeUnit = "ohm" )
double elec:battery:c2 = 0.0 ( lagrangeUnit = "F" )
double elec:battery:referenceTemperature = 298.15 ( lagrangeUnit = "K" )
double elec:battery:r0TempCoeff = 0.0 ( lagrangeUnit = "1/K" )
double elec:battery:cutoffVoltage ( lagrangeUnit = "V" )
double elec:battery:maxChargeCurrent ( lagrangeUnit = "A" )
asset elec:battery:behaviorModel
}
class "ElectricalMotorAPI_1" (
inherits = </APISchemaBase>
customData = { token apiSchemaType = "singleApply" }
doc = "Electric motor with its drive (inverter + current control), averaged model."
)
{
uniform token elec:motorType = "pmsm" ( allowedTokens = ["pmsm", "bldc", "dc_brushed"] )
double elec:windingResistance ( lagrangeUnit = "ohm" )
double elec:inductance ( lagrangeUnit = "H" )
double elec:inductanceQ ( lagrangeUnit = "H" )
double elec:torqueConstant ( lagrangeUnit = "N.m/A" )
double elec:backEmfConstant ( lagrangeUnit = "V.s/rad" )
int elec:polePairs = 1
double elec:rotorInertia = 0.0 ( lagrangeUnit = "kg.m2" )
double elec:gearRatio = 1.0 ( lagrangeUnit = "1" )
double elec:gearEfficiency = 1.0 ( lagrangeUnit = "1" )
double elec:maxCurrent ( lagrangeUnit = "A" )
double elec:referenceTemperature = 298.15 ( lagrangeUnit = "K" )
double elec:resistanceTempCoeff = 0.00393 ( lagrangeUnit = "1/K" )
uniform token elec:controlMode = "torque" ( allowedTokens = ["torque", "velocity", "voltage"] )
double elec:currentLoopBandwidth = 6283.0 ( lagrangeUnit = "rad/s" )
double elec:pwmFrequency = 20000.0 ( lagrangeUnit = "Hz" )
uniform token elec:rotorIntegration = "mechanical" ( allowedTokens = ["mechanical", "electrical"] )
asset elec:behaviorModel
rel elec:joint
rel elec:powerPort
}
Proposed additions, not in the CLAUDE.md list, needed to describe a real DC bus (RFC 0002, unresolved question 1):
Schema |
Purpose |
Key attributes |
|---|---|---|
|
A named net with capacitance; brownout thresholds |
|
|
Constant-power or resistive load (computer, lidar, heater) |
|
|
DC-DC converter between two ports |
|
Implemented in schemas/electrical/schema.usda (v0.3); schemas/CHANGELOG.md lists the
differences from these drafts.
3.2 schemas/thermal/schema.usda¶
ThermalAPI_1 (single-apply): one lumped thermal node.
Attribute |
Type |
Unit |
Fallback |
Meaning |
|---|---|---|---|---|
|
double |
J/K |
— |
Lumped capacity of the node |
|
double |
K |
none |
If absent, the profile’s ambient temperature |
|
double |
m² |
|
Area exchanging with air |
|
double |
W/(m²·K) |
|
Still-air natural convection; forced convection scales with airspeed |
|
double |
1 |
|
|
|
double |
1 |
|
For radiative exchange with sky/ambient |
|
double |
m² |
|
|
|
double |
1 |
|
Fraction of irradiance absorbed |
|
double |
m² |
|
Projected area for irradiance |
|
double |
K |
none |
Fault / shutdown threshold |
|
double |
K |
none |
Above this, the owning component derates linearly to zero at |
ThermalLinkAPI_1 (multiple-apply, proposed addition): a conductance to another node.
Attribute |
Type |
Unit |
Fallback |
|---|---|---|---|
|
double |
W/K |
— |
|
rel |
— |
— |
class "ThermalAPI_1" (
inherits = </APISchemaBase>
customData = { token apiSchemaType = "singleApply" }
doc = "One lumped thermal node."
)
{
double thermal:heatCapacity ( lagrangeUnit = "J/K" )
double thermal:initialTemperature ( lagrangeUnit = "K" )
double thermal:convectionArea = 0.0 ( lagrangeUnit = "m2" )
double thermal:convectionCoeff = 10.0 ( lagrangeUnit = "W/(m2.K)" )
double thermal:forcedConvectionExponent = 0.8 ( lagrangeUnit = "1" )
double thermal:emissivity = 0.9 ( lagrangeUnit = "1" )
double thermal:radiativeArea = 0.0 ( lagrangeUnit = "m2" )
double thermal:solarAbsorptivity = 0.7 ( lagrangeUnit = "1" )
double thermal:solarArea = 0.0 ( lagrangeUnit = "m2" )
double thermal:maxTemperature ( lagrangeUnit = "K" )
double thermal:deratingStart ( lagrangeUnit = "K" )
}
class "ThermalLinkAPI_1" (
inherits = </APISchemaBase>
customData = {
token apiSchemaType = "multipleApply"
token propertyNamespacePrefix = "thermal:link"
}
)
{
double conductance ( lagrangeUnit = "W/K" )
rel target
}
3.3 schemas/aero/schema.usda¶
AeroAPI_1 (single-apply, on a rigid-body link).
Attribute |
Type |
Unit |
Fallback |
Meaning |
|---|---|---|---|---|
|
token |
— |
|
|
|
double[3] |
m² |
— |
Projected areas along body x, y, z |
|
double[3] |
1 |
|
Per-axis drag coefficient |
|
double[3] |
m |
|
In body frame |
|
double |
1/rad |
|
For |
|
asset |
— |
none |
CSV: angle of attack (rad), CL, CD, CM |
|
double[3] |
N·m·s/rad |
|
RotorAPI_1 (on the rotor joint prim; used by modules/rotor_aero/). Defined in
schemas/aero since v0.4, with aero:rotor:direction meaning the sense in which the motor
turns the rotor, seen from the front (from where the thrust points). With a propeller file the
propeller’s own hand decides what that rotation does: a propeller of the other hand turns the
wrong way and gives little thrust, as on a real vehicle.
Attribute |
Type |
Unit |
Fallback |
|---|---|---|---|
|
double |
m |
— |
|
int |
1 |
— |
|
double |
1 |
— ( |
|
double |
1 |
— |
|
token |
— |
— ( |
|
asset |
— |
none (propeller file, §3.3.1; required for the |
|
token |
— |
|
class "AeroAPI_1" (
inherits = </APISchemaBase>
customData = { token apiSchemaType = "singleApply" }
)
{
uniform token aero:model = "drag_box" ( allowedTokens = ["drag_box", "drag_lift_table", "none"] )
double3 aero:referenceArea ( lagrangeUnit = "m2" )
double3 aero:dragCoeff = (1.0, 1.0, 1.0) ( lagrangeUnit = "1" )
double3 aero:centerOfPressure = (0, 0, 0) ( lagrangeUnit = "m" )
double aero:liftSlope = 0.0 ( lagrangeUnit = "1/rad" )
asset aero:coeffTable
double3 aero:angularDamping = (0, 0, 0) ( lagrangeUnit = "N.m.s/rad" )
}
class "RotorAPI_1" (
inherits = </APISchemaBase>
customData = { token apiSchemaType = "singleApply" }
)
{
double aero:rotor:radius ( lagrangeUnit = "m" )
int aero:rotor:bladeCount
double aero:rotor:thrustCoeff ( lagrangeUnit = "1" )
double aero:rotor:powerCoeff ( lagrangeUnit = "1" )
uniform token aero:rotor:direction ( allowedTokens = ["cw", "ccw"] )
asset aero:rotor:propeller
uniform token aero:rotor:mount = "puller" ( allowedTokens = ["puller", "pusher"] )
}
3.3.1 Propeller files¶
A propeller as built, for the bem fidelity of rotor_aero and for drawing its blades:
YAML, *.prop.yaml, format: lagrange-propeller-1. Samples are in assets/propellers/.
Key |
Unit |
Meaning |
|---|---|---|
|
— |
What it is, for people |
|
m |
Tip diameter |
|
1 |
Number of blades |
|
— |
|
|
— |
Section data: |
|
— |
Blade stations from root to tip: |
| folding | — | Optional, folding blades: hinge (r/R of the hinges), blade_mass (kg, one blade outboard of its hinge), limit (deg, the hinge’s stop either way; fallback 85) |
Every file says where its numbers come from in comments at its top; a propeller made up for a sample says so.
3.4 schemas/weather/schema.usda¶
Defined in v0.5 as drafted, plus weather:roughnessLength (m, fallback 0.03, open terrain) for
the logarithmic wind profile that the aerodynamics domain already uses.
Weather is authored on one environment prim (the environment: file of a profile).
WeatherAPI_1 (single-apply, proposed; CLAUDE.md lists the weather/ directory but no
schema name).
Attribute |
Type |
Unit |
Fallback |
Meaning |
|---|---|---|---|---|
|
double |
K |
— |
Site parameter, no fallback |
|
double |
Pa |
— |
Site parameter |
|
double |
1 |
— |
0…1 |
|
double3 |
m/s |
|
ENU, at |
|
double |
m |
|
|
|
token |
— |
|
|
|
double |
1 |
|
σ / mean wind |
|
asset |
— |
none |
NanoVDB vector grid (m/s), overrides |
|
double |
m |
none |
Meteorological optical range; sets fog extinction through Koschmieder ( |
|
asset |
— |
none |
NanoVDB scalar grid of extinction (1/m) |
|
double |
m/s |
|
Rain intensity (1 mm/h = 2.778e-7 m/s) |
|
double |
kg/m³ |
|
|
|
double |
m |
|
|
|
double |
W/m² |
|
Direct normal |
|
double3 |
1 |
|
Unit vector to the sun, ENU |
|
double |
K |
none |
For radiative exchange; defaults to ambient |
class "WeatherAPI_1" (
inherits = </APISchemaBase>
customData = { token apiSchemaType = "singleApply" }
)
{
double weather:ambientTemperature ( lagrangeUnit = "K" )
double weather:pressure ( lagrangeUnit = "Pa" )
double weather:relativeHumidity ( lagrangeUnit = "1" )
double3 weather:meanWind = (0, 0, 0) ( lagrangeUnit = "m/s" )
double weather:windReferenceHeight = 10.0 ( lagrangeUnit = "m" )
uniform token weather:turbulenceModel = "none" ( allowedTokens = ["none", "dryden", "von_karman"] )
double weather:turbulenceIntensity = 0.0 ( lagrangeUnit = "1" )
asset weather:windField
double weather:visibility ( lagrangeUnit = "m" )
asset weather:fogField
double weather:rainRate = 0.0 ( lagrangeUnit = "m/s" )
double weather:dustConcentration = 0.0 ( lagrangeUnit = "kg/m3" )
double weather:dustMedianDiameter = 0.00001 ( lagrangeUnit = "m" )
double weather:solarIrradiance = 0.0 ( lagrangeUnit = "W/m2" )
double3 weather:sunDirection = (0, 0, 1) ( lagrangeUnit = "1" )
double weather:skyTemperature ( lagrangeUnit = "K" )
}
3.5 schemas/emi/schema.usda¶
Defined in v0.5, with three changes to the draft below: emi:direction (the conductor’s
direction or the dipole axis, in the prim’s frame) and emi:dipoleMomentPerAmpere (m², for
motor drives and welders) added, which the analytic models need; emi:adcNoisePerField split
into emi:accelNoisePerField ((m/s²)/(V/m)) and emi:gyroNoisePerField ((rad/s)/(V/m)), since
the two channels have different units.
EmiSourceAPI_1 (single-apply).
Attribute |
Type |
Unit |
Fallback |
Meaning |
|---|---|---|---|---|
|
token |
— |
— |
|
|
double |
Hz |
— |
Fundamental. No fallback (site parameter: 50 or 60 Hz mains) |
|
double |
A |
none |
RMS current for |
|
double |
W |
none |
For |
|
double[] |
1 |
|
Relative amplitude of harmonics 2, 3, … |
|
double |
1 |
|
For intermittent sources (welders) |
|
double |
Hz |
|
Occupied bandwidth for |
|
asset |
— |
none |
NanoVDB vector grid of B (T) or E (V/m), at |
|
token |
— |
|
|
|
rel |
— |
none |
Signal-producing prim (a motor) whose current scales the source at runtime |
|
double[] |
m |
|
For |
|
double3 |
m |
|
For |
|
token |
— |
|
A signal (A) that sets the current every step, signed for a direct current; over |
wire (RFC 0013) was appended to emi:sourceType’s tokens: a conductor along emi:path, its
field the Biot–Savart sum over its straight segments.
EmiSusceptibilityAPI_1 (single-apply, on a sensor, bus or radio prim). These are the
per-robot calibration parameters.
Attribute |
Type |
Unit |
Fallback |
Meaning |
|---|---|---|---|---|
|
token |
— |
— |
|
|
double |
1 |
|
Magnetometer: fraction of ambient AC field that appears in the reading |
|
double |
V/(V/m) |
|
IMU/ADC: added noise RMS per unit E-field |
|
double |
V/m |
none |
Field level at which the glitch probability is 50 % per edge |
|
double |
V/m |
none |
Field level at which the bit-error rate reaches |
|
double |
1 |
|
|
|
double |
1 |
|
Radio: linear noise figure |
|
double |
m² |
|
Effective loop area of the harness for induced voltage |
|
double |
1 |
|
Linear field attenuation factor ≥ 1 |
class "EmiSourceAPI_1" (
inherits = </APISchemaBase>
customData = { token apiSchemaType = "singleApply" }
)
{
uniform token emi:sourceType (
allowedTokens = ["power_line", "motor_drive", "transmitter", "welder", "custom"] )
double emi:frequency ( lagrangeUnit = "Hz"
doc = "Site parameter. No fallback: 50 Hz and 60 Hz grids both exist." )
double emi:current ( lagrangeUnit = "A" )
double emi:radiatedPower ( lagrangeUnit = "W" )
double[] emi:harmonics = [] ( lagrangeUnit = "1" )
double emi:dutyCycle = 1.0 ( lagrangeUnit = "1" )
double emi:bandwidth = 0.0 ( lagrangeUnit = "Hz" )
asset emi:fieldMap
uniform token emi:fieldMapQuantity = "B" ( allowedTokens = ["B", "E"] )
rel emi:drivenBy
}
class "EmiSusceptibilityAPI_1" (
inherits = </APISchemaBase>
customData = { token apiSchemaType = "singleApply" }
)
{
uniform token emi:victimType (
allowedTokens = ["magnetometer", "imu_adc", "encoder", "can_bus", "radio"] )
double emi:magneticGain = 1.0 ( lagrangeUnit = "1" )
double emi:adcNoisePerField = 0.0 ( lagrangeUnit = "V/(V/m)" )
double emi:encoderGlitchField ( lagrangeUnit = "V/m" )
double emi:canErrorField ( lagrangeUnit = "V/m" )
double emi:canErrorRateAtField = 0.00001 ( lagrangeUnit = "1" )
double emi:receiverNoiseFigure = 1.0 ( lagrangeUnit = "1" )
double emi:couplingLoopArea = 0.0 ( lagrangeUnit = "m2" )
double emi:shieldingEffectiveness = 1.0 ( lagrangeUnit = "1" )
}
3.6 schemas/radiation/schema.usda¶
RadiationAPI_1 (single-apply). One schema with a rad:role token, because the same prim is
rarely both a source and a victim and the attribute sets are small.
Attribute |
Type |
Unit |
Fallback |
Meaning |
|---|---|---|---|---|
|
token |
— |
— |
|
|
token |
— |
none |
|
|
double |
Bq |
none |
Point source activity |
|
double |
J |
none |
Mean photon energy (1 MeV = 1.602e-13 J) |
|
double |
Gy/s |
none |
Alternative to activity + energy |
|
asset |
— |
none |
NanoVDB scalar grid of dose rate (Gy/s), e.g. from Geant4 offline |
|
double |
1/m |
none |
Shield: linear attenuation at the source energy |
|
double |
1 |
|
Shield: simple build-up correction |
|
double |
Gy |
none |
Victim: failure threshold |
|
double |
m² |
|
Victim: single-event-upset cross-section per bit |
|
int |
1 |
|
Victim: number of bits exposed to SEU |
|
double |
Gy·m² |
none |
Victim: conversion used for SEU rate from dose rate |
class "RadiationAPI_1" (
inherits = </APISchemaBase>
customData = { token apiSchemaType = "singleApply" }
)
{
uniform token rad:role ( allowedTokens = ["source", "victim", "shield"] )
uniform token rad:sourceType ( allowedTokens = ["point_gamma", "field_map"] )
double rad:activity ( lagrangeUnit = "Bq" )
double rad:gammaEnergy ( lagrangeUnit = "J" )
double rad:doseRateAt1m ( lagrangeUnit = "Gy/s" )
asset rad:doseField
double rad:attenuationCoeff ( lagrangeUnit = "1/m" )
double rad:buildupFactor = 1.0 ( lagrangeUnit = "1" )
double rad:totalDoseLimit ( lagrangeUnit = "Gy" )
double rad:seuCrossSection = 0.0 ( lagrangeUnit = "m2" )
int rad:sensitiveBits = 0
double rad:fluenceToDose ( lagrangeUnit = "Gy.m2" )
}
3.7 schemas/sensor_material/schema.usda¶
SensorMaterialAPI_1 (single-apply, on a Material prim). Non-visual surface properties.
Attribute |
Type |
Unit |
Fallback |
Meaning |
|---|---|---|---|---|
|
double |
1 |
|
Diffuse reflectivity at 905 nm |
|
double |
1 |
|
Diffuse reflectivity at 1550 nm |
|
bool |
— |
|
Road signs, safety vests |
|
double |
1 |
|
Fraction of return that is specular |
|
double |
1 |
|
Glass: fraction transmitted |
|
double |
1 |
|
RCS per unit projected area (m²/m²) at 77 GHz |
|
double |
m |
|
RMS surface roughness |
|
double |
1 |
|
|
|
double |
S/m |
|
Electrical conductivity |
|
double |
1 |
|
Magnetic permeability relative to vacuum |
|
double |
1 |
|
Long-wave IR emissivity (thermal cameras) |
|
double |
1 |
|
Multiplier on friction when wet (weather coupling) |
class "SensorMaterialAPI_1" (
inherits = </APISchemaBase>
customData = { token apiSchemaType = "singleApply" }
)
{
double sensmat:reflectivity905 = 0.5 ( lagrangeUnit = "1" )
double sensmat:reflectivity1550 = 0.5 ( lagrangeUnit = "1" )
bool sensmat:retroreflective = false
double sensmat:specularFraction905 = 0.0 ( lagrangeUnit = "1" )
double sensmat:transmission905 = 0.0 ( lagrangeUnit = "1" )
double sensmat:radarCrossSectionDensity = 0.1 ( lagrangeUnit = "1" )
double sensmat:radarRoughness = 0.001 ( lagrangeUnit = "m" )
double sensmat:relativePermittivity = 1.0 ( lagrangeUnit = "1" )
double sensmat:conductivity = 0.0 ( lagrangeUnit = "S/m" )
double sensmat:relativePermeability = 1.0 ( lagrangeUnit = "1" )
double sensmat:thermalEmissivity = 0.9 ( lagrangeUnit = "1" )
double sensmat:frictionWetScale = 0.7 ( lagrangeUnit = "1" )
}
The fallback values above are placeholders so that untagged assets still produce returns. They
are not measured data. Realistic values per material class ship in a library file
assets/materials/sensor_materials.usda, each entry with its source (risk R12).
3.8 schemas/sensor/schema.usda (proposed addition)¶
Sensors need schemas that CLAUDE.md does not list. USD has UsdGeomCamera for camera intrinsics;
the rest is ours. Draft attribute sets (full .usda text is written in RFC 0002 once the list is
agreed):
Schema |
Attributes (unit, fallback) |
|---|---|
|
|
|
|
|
on a |
|
|
|
v0.2 implements per-sample white noise, |
|
|
|
|
|
(RFC 0008 §3) |
Lidar scan patterns and fisheye lenses (RFC 0015, as built). scanPattern = "flash" is a
focal-plane array (every beam at once, the beams evenly spaced on the image plane, outer angles
within ±π/2, motionDistortion not used); "rosette" is two Risley prisms with
horizontalSamples points per scan and one channel, read from the five rosette:* attributes
(unauthored: the loader’s values in sensors.md, with a note; no schema fallback, so unmeasured
prism speeds are not frozen for 1.x). rotating, solid_state and custom stay the even grid.
A non-empty channelElevations gives the rings (sorted from the lowest) instead of
verticalFov; an authored channels must equal its length. lensType = "equidistant" makes the
camera a fisheye (Kannala–Brandt; k1..k4 from distortionModel = "equidistant" and
distortionCoeffs, or "none" for all zero; "plumb_bob" is refused): its angle across the
width is 2 θ_d⁻¹(horizontalAperture / (2 focalLength)) through the lens’s own mapping, so a
200° fisheye has a positive focal length; cutoffAngle (at most π) defaults to the larger of
half that angle and π/2, and may be below half that angle (the pixels beyond it are black, as from
URDF). UsdGeomCamera.projection stays perspective (the only other token
OpenUSD allows is orthographic). The stage writer writes all of it, so URDF → lagrange_import
→ USD → run gives the same beams bit for bit and the same lens (to the float precision of
focalLength). A file using them, opened by Lagrange 1.2 or older, runs as a grid lidar and a
pinhole camera.
3.9 schemas/comms/schema.usda¶
Defined in v0.5 (domains/comms.md). Powers and ratios are linear SI values; only the
shadowing spread is given in decibels, as path-loss models state it.
RadioLinkAPI_1 (single-apply, on the receiving radio’s prim).
Attribute |
Type |
Unit |
Fallback |
Meaning |
|---|---|---|---|---|
|
rel |
— |
— |
The transmitting radio’s prim. Required |
|
double |
Hz |
— |
Carrier. Required |
|
double |
Hz |
— |
Channel bandwidth. Required |
|
double |
W |
— |
Transmit power. Required |
|
double |
1 |
|
Linear gains |
|
double |
1 |
|
Log-distance exponent |
|
double |
m |
|
d0, where free-space loss holds |
|
double |
1 |
|
Linear loss per wall crossed |
|
double |
1 |
|
Log-normal shadowing, dB |
|
double |
m |
|
0: independent each step |
|
double |
1 |
|
Linear |
|
token |
— |
|
|
|
int |
1 |
|
1500 bytes |
|
int |
1 |
|
Retransmissions before a packet is lost |
CanBusAPI_1 (single-apply, on a bus prim): can:bitRate (double, 1/s, required) and
can:frameBits (int, fallback 108: an 11-bit identifier and 8 data bytes, before stuffing).
3.10 schemas/vehicle/schema.usda¶
Defined in v0.6 (domains/vehicle_dynamics.md). A road vehicle is a chassis body with wheels
on revolute spin joints; the module finds the ground under each wheel by a ray and models the
suspension and tyres itself, so wheel bodies carry no collision shapes.
VehicleAPI_1 (single-apply, on the chassis body).
Attribute |
Type |
Unit |
Fallback |
Meaning |
|---|---|---|---|---|
|
token |
— |
|
|
|
double |
N·m |
— |
electric: total at the driven wheels at full throttle |
|
double |
rad |
— |
Inner road wheel. Required with a steered wheel |
|
double |
rad/s |
|
Rate limit |
|
double |
s |
|
First-order lag |
|
double |
N·m |
— |
Total at full pedal. Required |
|
double |
1 |
|
Front fraction |
|
bool |
— |
|
Slip-limiting anti-lock braking |
|
double[] |
rad/s, N·m |
— |
ice_map: full-throttle curve |
|
double |
rad/s |
|
ice_map |
|
double[] |
1 |
— |
ice_map: forward gears |
|
double |
1 |
|
ice_map |
|
double |
rad/s |
|
ice_map: automatic shifts |
|
double |
1 |
|
ice_map |
|
double |
N/m |
|
Per metre of travel difference across the axle |
WheelAPI_1 (single-apply, on a wheel’s spin joint).
Attribute |
Type |
Unit |
Fallback |
Meaning |
|---|---|---|---|---|
|
double |
m |
— |
Loaded rolling radius. Required |
|
double |
m |
|
|
|
token |
— |
— |
|
|
bool |
— |
|
|
|
rel |
— |
— |
A steered wheel’s steering joint |
|
asset |
— |
— |
|
|
double |
N |
— |
linear fidelity, per unit slip ratio |
|
double |
N/rad |
— |
linear fidelity |
|
double |
1 |
|
Peak μ on the reference surface |
|
double |
m |
|
Lateral transient |
|
double |
m |
— |
Mount to wheel centre at ride height (the model’s wheel position; the spring is preloaded with its static load there). Required |
|
double |
m |
— |
From ride height to the bump stop. Required |
|
double |
N/m |
— |
Required |
|
double |
N·s/m |
— |
Required |
3.11 schemas/road/schema.usda¶
Defined in v0.6 and written by the OpenDRIVE importer (io/opendrive/, lagrange_opendrive_import).
RoadLaneAPI_1 (single-apply, on an Xform per lane and lane section).
Attribute |
Type |
Unit |
Fallback |
Meaning |
|---|---|---|---|---|
|
double[] |
m |
— |
x y z of each centre-line point, in the direction of travel. Required |
|
double[] |
m |
— |
Width at each point |
|
token |
— |
|
|
|
double |
m/s |
|
0: none given |
|
int |
1 |
|
OpenDRIVE road and lane ids |
|
double |
m |
|
The lane section’s range along its road (OpenDRIVE s) |
|
bool |
— |
|
A junction’s connecting road |
|
rel |
— |
— |
Lanes it continues into, and those leading into it |
OpenDRIVE import (v0.6). An own reader covers the subset that carries geometry and lanes:
Reference lines: line, arc, spiral (clothoid, by Gauss–Legendre integration), poly3 and paramPoly3 (both by arc length).
Roads: elevation, superelevation (
<lateralProfile><superelevation>, after 1.x), lane offset, lane sections with width polynomials, lane heights (<height>) and@level, road marks.Links: lane, road and junction links.
Cross section. Superelevation is the roll of the cross section about the reference line, a
cubic in s (rad), positive falling to the right (ASAM OpenDRIVE 1.8 §10.5.2). t is measured
along the banked t axis: a point at t lies t·cos φ to the side of the reference line and
t·sin φ above its elevation, so a lane keeps its width and its projected width shrinks. A lane’s
<height> raises its surface along h, the banked cross section’s normal (§11.6.3), linear from
inner at its inner border to outer at its outer one (the standard gives only the two border
values); a sidewalk with inner="0.15" outer="0.15" is a kerb, its face drawn where it meets
the lane inside it. A lane with @level="true" (and every lane outside it, as the standard
requires) stays level at the height of the first level lane’s inner border. Road surfaces, kerb
faces, road marks and the lanes’ lane:centreLine (its z) all follow the cross section, and the
meshes’ normals are the surface’s.
Objects and signals are not read yet. Road surfaces become meshes per lane type, road marks
become thin meshes (broken marks are 3 m on and 6 m off, illustrative), and every driving,
biking, parking or sidewalk lane becomes a RoadLaneAPI_1 prim with its links. A road on the
ground (no elevation, superelevation or lane height) has no colliders: its surfaces lie 1 cm
above the ground plane that the loader adds, and its import is unchanged. A raised road (any of
those) also collides: each drawn lane gets a convex slab every 2 m along s, its top the drawn
surface and 0.3 m thick (ConvertOptions::colliderStep, colliderDepth), written under
/<root>/colliders, so cars stand on banked curves, ramps and bridges and traffic sees a ramp
in its lanes’ heights. A raised road below z = 0 is under the ground plane, which is hit first:
lift such a network with its elevation. Sample: assets/worlds/banked_ring (a 5 m ring 1.5 m
up, 5° of bank falling to the inside, a 0.15 m kerb).
3.12 schemas/tether/schema.usda¶
Added in 1.x by RFC 0011 and simulated by the tether domain (modules/tether/).
TetherAPI_1 (single-apply). The prim’s origin is the anchor, such as a ground station’s winch
outlet. It can sit on the world, a fixed body or a moving body.
Attribute |
Type |
Unit |
Fallback |
Meaning |
|---|---|---|---|---|
|
double3 |
m |
|
The anchor in the prim’s frame; on the world, a world position |
|
rel |
— |
— |
The body (link) the far end is tied to. Required |
|
double3 |
m |
|
Where on that body, in its frame |
|
double |
m |
|
Length paid out at the start. Required, over 0 |
|
double |
m |
|
For contact, drag and drawing |
|
double |
kg/m |
|
Mass per metre |
|
double |
N |
|
EA |
|
double |
1 |
|
Axial damping, a share of critical per segment |
|
double |
N·m² |
|
EI |
|
double |
1 |
|
Coulomb, on scenery, bodies and itself |
|
double |
1 |
|
Normal; tangential is 1/50 of it |
|
double |
m |
|
Spacing of the point masses |
|
token |
— |
|
|
|
double |
N |
|
Set point of |
|
double |
m/s |
|
Most it pays out or reels in |
|
double |
m |
|
The drum’s end; |
|
double |
ohm/m |
|
Both conductors, round trip; not simulated yet |
An overlay applies it like any other schema. A new prim has no pose, so anchorPoint places the
station:
apply:
- create: ground_station
schemas:
TetherAPI_1:
tether:anchorPoint: [2.0, 0.0, 0.3]
tether:attach: base_link
tether:length: 5.0
tether:diameter: 0.006
tether:linearDensity: 0.03
tether:winch: tension
3.13 Thermal materials and heat sources (schemas/thermal/schema.usda)¶
Added in 1.x by RFC 0012, for the thermal domain’s conduction fidelity
(docs/physics/heat-conduction.md).
ThermalMaterialAPI_1 (single-apply), on a link’s prim or a material bound to it. A preset
gives every number; an authored number overrides it.
Attribute |
Type |
Unit |
Fallback |
Meaning |
|---|---|---|---|---|
|
token |
— |
|
A row of the cited preset table, e.g. |
|
double |
W/(m·K) |
— |
|
|
double |
kg/m³ |
— |
|
|
double |
J/(kg·K) |
— |
|
|
double |
1 |
— |
Of its surfaces, 0 to 1 |
|
double |
W/(m·K) |
— |
Along |
|
double3 |
1 |
|
In the link’s frame |
|
double |
W/(m²·K) |
— |
Where it touches its parent link; unauthored: no conduction across |
|
double |
K |
— |
Unauthored: the ambient |
|
double |
K |
— |
Over it anywhere: |
HeatSourceAPI_1 (multiple-apply, thermal:source:<name>:), on a link’s prim. Its heat,
(1 − efficiency) · power, is shared over the link’s cells inside the box.
Attribute |
Type |
Unit |
Fallback |
Meaning |
|---|---|---|---|---|
|
double |
W |
|
Electrical input power |
|
token |
— |
|
Or a signal in W, read each step; overrides |
|
double |
1 |
|
Share leaving as light |
|
double3 |
m |
|
Centre of the box, link frame |
|
double3 |
m |
|
Full size of the box |
apply:
- prim: led_board
schemas:
ThermalMaterialAPI_1:
thermal:material:preset: fr4
thermal:material:contactConductance: 3000.0
HeatSourceAPI_1:led_1:
thermal:source:led_1:power: 3.0
thermal:source:led_1:efficiency: 0.35
thermal:source:led_1:position: [0.01, 0.0, 0.0016]
thermal:source:led_1:size: [0.003, 0.003, 0.001]
In a URDF, on the link (read by the server and lagrange_import, which writes the schemas):
<gazebo reference="led_board">
<thermal_material preset="fr4" conductivity="20" conductivity_along="0.3" axis="0 0 1" contact_conductance="3000"/>
<heat_source name="led_1" power="3.0" efficiency="0.35" xyz="0.01 0 0.0016" size="0.003 0.003 0.001"/>
<heat_source name="driver" power_signal="motor/left/loss_power"/>
</gazebo>
<thermal_material> takes preset, conductivity, density, specific_heat, emissivity,
conductivity_along, axis, contact_conductance, initial_temperature, max_temperature;
<heat_source> takes name (required), power, power_signal, efficiency, xyz, size.
4. Sample robot: differential-drive AMR¶
assets/robots/amr_diffdrive/amr_diffdrive.usda. Geometry is primitive shapes so that the file
stays tiny and has no external meshes.
#usda 1.0
(
defaultPrim = "amr"
metersPerUnit = 1
upAxis = "Z"
kilogramsPerUnit = 1
doc = "Sample differential-drive AMR for lagrange. Parameters are illustrative, not a real product."
)
def Xform "amr" (
prepend apiSchemas = ["PhysicsArticulationRootAPI"]
kind = "component"
)
{
def Xform "base_link" (
prepend apiSchemas = ["PhysicsRigidBodyAPI", "PhysicsMassAPI", "AeroAPI_1", "ThermalAPI_1"]
)
{
float physics:mass = 38.0 # kg
point3f physics:centerOfMass = (0, 0, 0.12) # m
double3 aero:referenceArea = (0.18, 0.24, 0.30) # m², faces along x, y, z
double3 aero:dragCoeff = (1.05, 1.05, 1.05)
double thermal:heatCapacity = 9000.0 # J/K, chassis
double thermal:convectionArea = 0.9 # m²
double3 xformOp:translate = (0, 0, 0.10)
uniform token[] xformOpOrder = ["xformOp:translate"]
def Cube "visual" { double size = 1 float3 xformOp:scale = (0.60, 0.44, 0.20)
uniform token[] xformOpOrder = ["xformOp:scale"]
rel material:binding = </amr/materials/painted_steel> }
def Cube "collision" ( prepend apiSchemas = ["PhysicsCollisionAPI"] )
{
double size = 1
float3 xformOp:scale = (0.60, 0.44, 0.20)
uniform token[] xformOpOrder = ["xformOp:scale"]
uniform token purpose = "guide"
}
}
def Xform "left_wheel" ( prepend apiSchemas = ["PhysicsRigidBodyAPI", "PhysicsMassAPI"] )
{
float physics:mass = 1.4
double3 xformOp:translate = (0, 0.25, 0.08)
uniform token[] xformOpOrder = ["xformOp:translate"]
def Cylinder "collision" ( prepend apiSchemas = ["PhysicsCollisionAPI"] )
{ double radius = 0.08 double height = 0.04 uniform token axis = "Y"
rel material:binding:physics = </amr/materials/rubber> }
}
def Xform "right_wheel" ( prepend apiSchemas = ["PhysicsRigidBodyAPI", "PhysicsMassAPI"] )
{
float physics:mass = 1.4
double3 xformOp:translate = (0, -0.25, 0.08)
uniform token[] xformOpOrder = ["xformOp:translate"]
def Cylinder "collision" ( prepend apiSchemas = ["PhysicsCollisionAPI"] )
{ double radius = 0.08 double height = 0.04 uniform token axis = "Y"
rel material:binding:physics = </amr/materials/rubber> }
}
def Xform "caster" ( prepend apiSchemas = ["PhysicsRigidBodyAPI", "PhysicsMassAPI"] )
{
float physics:mass = 0.3
double3 xformOp:translate = (-0.24, 0, 0.03)
uniform token[] xformOpOrder = ["xformOp:translate"]
def Sphere "collision" ( prepend apiSchemas = ["PhysicsCollisionAPI"] )
{ double radius = 0.03 rel material:binding:physics = </amr/materials/low_friction> }
}
def Scope "joints"
{
def PhysicsRevoluteJoint "left_wheel_joint" ( prepend apiSchemas = ["PhysicsDriveAPI:angular"] )
{
rel physics:body0 = </amr/base_link>
rel physics:body1 = </amr/left_wheel>
uniform token physics:axis = "Y"
point3f physics:localPos0 = (0, 0.25, -0.02)
}
def PhysicsRevoluteJoint "right_wheel_joint" ( prepend apiSchemas = ["PhysicsDriveAPI:angular"] )
{
rel physics:body0 = </amr/base_link>
rel physics:body1 = </amr/right_wheel>
uniform token physics:axis = "Y"
point3f physics:localPos0 = (0, -0.25, -0.02)
}
def PhysicsSphericalJoint "caster_joint"
{
rel physics:body0 = </amr/base_link>
rel physics:body1 = </amr/caster>
point3f physics:localPos0 = (-0.24, 0, -0.07)
}
}
def Scope "power"
{
def Xform "battery" (
prepend apiSchemas = ["BatteryAPI_1", "ThermalAPI_1", "PortAPI_1:dc_out"]
)
{
uniform token elec:battery:chemistry = "lfp"
int elec:battery:seriesCells = 16
int elec:battery:parallelCells = 2
double elec:battery:capacity = 144000.0 # C (40 Ah)
double[] elec:battery:ocvSoc = [0.0, 0.1, 0.5, 0.9, 1.0]
double[] elec:battery:ocvVoltage = [2.80, 3.20, 3.28, 3.33, 3.45] # V per cell
double elec:battery:r0 = 0.0015 # ohm per cell
double elec:battery:r1 = 0.0008
double elec:battery:c1 = 12000.0
double elec:battery:cutoffVoltage = 44.8 # V
double elec:battery:maxChargeCurrent = 20.0 # A
double thermal:heatCapacity = 14000.0 # J/K
double elec:port:dc_out:nominalVoltage = 51.2 # V
double elec:port:dc_out:maxCurrent = 80.0 # A
rel elec:port:dc_out:connectedTo = </amr/power/dc_48v>
rel thermal:link:chassis:target = </amr/base_link>
double thermal:link:chassis:conductance = 2.5 # W/K
}
def Xform "dc_48v" ( prepend apiSchemas = ["ElectricalBusAPI_1"] )
{
double elec:bus:capacitance = 0.0047 # F
double elec:bus:undervoltageTrip = 42.0 # V
double elec:bus:overvoltageTrip = 60.0 # V
}
def Xform "computer" ( prepend apiSchemas = ["ElectricalLoadAPI_1"] )
{
uniform token elec:load:model = "constant_power"
double elec:load:power = 45.0 # W
double elec:load:minVoltage = 36.0 # V
rel elec:powerPort = </amr/power/dc_48v>
}
}
def Xform "left_drive_motor" (
prepend apiSchemas = ["ElectricalMotorAPI_1", "ThermalAPI_1", "EmiSusceptibilityAPI_1", "EmiSourceAPI_1"]
)
{
double elec:windingResistance = 0.12 # ohm @ 25 °C
double elec:torqueConstant = 0.085 # N·m/A
double elec:inductance = 0.00031 # H
int elec:polePairs = 4
double elec:rotorInertia = 0.00012 # kg·m²
double elec:gearRatio = 20.0
double elec:gearEfficiency = 0.92
double elec:maxCurrent = 30.0 # A
rel elec:joint = </amr/joints/left_wheel_joint>
rel elec:powerPort = </amr/power/dc_48v>
double thermal:heatCapacity = 450.0 # J/K
double thermal:convectionArea = 0.03 # m²
double thermal:deratingStart = 373.15 # K
double thermal:maxTemperature = 403.15 # K
uniform token emi:victimType = "encoder"
double emi:encoderGlitchField = 200.0 # V/m
uniform token emi:sourceType = "motor_drive"
double emi:frequency = 20000.0 # Hz, the drive's PWM frequency (a component property)
rel emi:drivenBy = </amr/left_drive_motor>
}
def Xform "right_drive_motor" (
prepend apiSchemas = ["ElectricalMotorAPI_1", "ThermalAPI_1", "EmiSusceptibilityAPI_1"]
)
{
double elec:windingResistance = 0.12
double elec:torqueConstant = 0.085
double elec:inductance = 0.00031
int elec:polePairs = 4
double elec:rotorInertia = 0.00012
double elec:gearRatio = 20.0
double elec:gearEfficiency = 0.92
double elec:maxCurrent = 30.0
rel elec:joint = </amr/joints/right_wheel_joint>
rel elec:powerPort = </amr/power/dc_48v>
double thermal:heatCapacity = 450.0
double thermal:convectionArea = 0.03
uniform token emi:victimType = "encoder"
double emi:encoderGlitchField = 200.0
}
def Scope "sensors"
{
def Xform "front_lidar" ( prepend apiSchemas = ["SensorAPI_1", "LidarAPI_1"] )
{
double3 xformOp:translate = (0.25, 0, 0.28)
uniform token[] xformOpOrder = ["xformOp:translate"]
double sensor:rate = 15.0 # Hz
int sensor:lidar:channels = 1
int sensor:lidar:horizontalSamples = 1440
double2 sensor:lidar:verticalFov = (0, 0)
double sensor:lidar:rangeMin = 0.05 # m
double sensor:lidar:rangeMax = 25.0 # m
}
def Xform "imu" ( prepend apiSchemas = ["SensorAPI_1", "ImuAPI_1", "EmiSusceptibilityAPI_1"] )
{
double sensor:rate = 200.0
double sensor:imu:accelNoiseDensity = 0.002 # m/s²/√Hz
double sensor:imu:accelBiasInstability = 0.0004 # m/s²
double sensor:imu:accelRandomWalk = 0.00006
double sensor:imu:gyroNoiseDensity = 0.00017 # rad/s/√Hz
double sensor:imu:gyroBiasInstability = 0.00002
double sensor:imu:gyroRandomWalk = 0.000002
double sensor:imu:accelRange = 156.9 # m/s² (16 g)
double sensor:imu:gyroRange = 34.9 # rad/s (2000 °/s)
uniform token emi:victimType = "imu_adc"
}
}
def Scope "materials"
{
def Material "painted_steel" ( prepend apiSchemas = ["SensorMaterialAPI_1"] )
{
double sensmat:reflectivity905 = 0.45
double sensmat:conductivity = 6.0e6 # S/m, order of magnitude for steel
double sensmat:relativePermeability = 100.0
}
def Material "rubber" ( prepend apiSchemas = ["PhysicsMaterialAPI", "SensorMaterialAPI_1"] )
{
float physics:staticFriction = 0.9
float physics:dynamicFriction = 0.8
double sensmat:reflectivity905 = 0.05
double sensmat:frictionWetScale = 0.65
}
def Material "low_friction" ( prepend apiSchemas = ["PhysicsMaterialAPI"] )
{ float physics:staticFriction = 0.05 float physics:dynamicFriction = 0.05 }
}
}
All numeric values in this sample are illustrative. They are chosen to be plausible, not taken
from a datasheet, and the file says so in its doc string.
5. Simulation profiles¶
5.1 Changes to the reference example¶
The examples in CLAUDE.md §11.1 stay valid under the schema below. Four fields are added (open question F5):
schema_version(required): letstools/migrate_profileupgrade old files.seed,deterministic,tier: needed for reproducible runs and tier forcing.time: real-time factor target and optional end time.substituteaccepts either the short token used in CLAUDE.md (zero,clear,ground_truth,replay, …) or an object{kind, preset, source}.
dt stays a number in seconds, as in the reference. The loader parses its decimal text exactly
and requires a whole number of nanoseconds (architecture §2).
5.2 profiles/schema.json (draft)¶
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://lagrange.example/schemas/profile/1/schema.json",
"title": "lagrange simulation profile",
"type": "object",
"additionalProperties": false,
"required": ["schema_version", "stage", "domains"],
"properties": {
"schema_version": { "const": 1 },
"stage": { "type": "string", "minLength": 1, "description": "USD file with the robot(s) and world." },
"environment": { "type": "string", "description": "USD file with a WeatherAPI prim and environment sources." },
"seed": { "type": "integer", "minimum": 0, "default": 0 },
"deterministic": { "type": "boolean", "default": false },
"tier": { "enum": ["auto", 0, 1, 2], "default": "auto" },
"batch": { "type": "integer", "minimum": 1, "default": 1, "description": "Parallel environments." },
"time": {
"type": "object",
"additionalProperties": false,
"properties": {
"real_time_factor": { "type": "number", "minimum": 0, "default": 1.0, "description": "0 = as fast as possible." },
"end": { "type": "number", "exclusiveMinimum": 0, "description": "Stop after this many simulated seconds." }
}
},
"domains": {
"type": "object",
"additionalProperties": false,
"required": ["rigid_body", "electrical", "thermal", "aerodynamics", "weather", "emi", "radiation", "sensors"],
"properties": {
"rigid_body": { "$ref": "#/$defs/rigid_body" },
"electrical": { "$ref": "#/$defs/electrical" },
"thermal": { "$ref": "#/$defs/thermal" },
"aerodynamics": { "$ref": "#/$defs/aerodynamics" },
"weather": { "$ref": "#/$defs/weather" },
"emi": { "$ref": "#/$defs/emi" },
"radiation": { "$ref": "#/$defs/radiation" },
"sensors": { "$ref": "#/$defs/sensors" },
"vehicle_dynamics": { "$ref": "#/$defs/vehicle_dynamics" },
"rotor_aero": { "$ref": "#/$defs/rotor_aero" },
"hydrodynamics": { "$ref": "#/$defs/generic_domain" },
"traffic": { "$ref": "#/$defs/traffic" },
"comms": { "$ref": "#/$defs/generic_domain" }
}
},
"world": {
"type": "object",
"additionalProperties": false,
"properties": {
"geo_origin": {
"type": "object",
"additionalProperties": false,
"required": ["latitude", "longitude", "height"],
"properties": {
"latitude": { "type": "number", "minimum": -90, "maximum": 90, "description": "degrees, WGS84" },
"longitude": { "type": "number", "minimum": -180, "maximum": 180, "description": "degrees, WGS84" },
"height": { "type": "number", "description": "metres above the WGS84 ellipsoid" }
}
},
"streaming": {
"type": "object",
"additionalProperties": false,
"properties": {
"enabled": { "type": "boolean", "default": false },
"load_radius": { "type": "number", "exclusiveMinimum": 0, "description": "m" },
"unload_radius": { "type": "number", "exclusiveMinimum": 0, "description": "m" },
"collision_radius": { "type": "number", "exclusiveMinimum": 0, "description": "m: tiles with colliders load only this near a robot (default 300)" },
"active_region_radius": { "type": "number", "exclusiveMinimum": 0, "description": "m" },
"rebase_distance": { "type": "number", "exclusiveMinimum": 0, "default": 1000, "description": "m" }
}
}
}
},
"bridges": {
"type": "object",
"additionalProperties": false,
"properties": {
"ros2": {
"type": "object",
"additionalProperties": false,
"properties": {
"enabled": { "type": "boolean", "default": true },
"namespace": { "type": "string", "default": "" },
"use_sim_time": { "type": "boolean", "default": true },
"gpu_buffers": { "type": "boolean", "default": false, "description": "Publish images/point clouds through rosidl::Buffer." }
}
},
"ros2_control": { "type": "object", "additionalProperties": false,
"properties": { "enabled": { "type": "boolean", "default": false } } },
"mavlink": {
"type": "object",
"additionalProperties": false,
"properties": {
"enabled": { "type": "boolean", "default": false },
"autopilot": { "enum": ["px4", "ardupilot"] },
"lockstep": { "type": "boolean", "default": true },
"endpoint": { "type": "string", "description": "e.g. tcp://127.0.0.1:4560" }
}
},
"autoware": { "type": "object", "additionalProperties": false,
"properties": { "enabled": { "type": "boolean", "default": false } } }
}
},
"scenario": {
"type": "object",
"additionalProperties": false,
"properties": {
"opendrive": { "type": "string" },
"openscenario": { "type": "string" }
}
},
"views": {
"type": "array",
"uniqueItems": true,
"items": { "enum": ["physics_3d", "electrical_schematic", "waveforms", "thermal", "fields", "sensors"] }
},
"record": {
"type": "object",
"additionalProperties": false,
"required": ["format", "path"],
"properties": {
"format": { "const": "mcap" },
"path": { "type": "string", "minLength": 1 },
"signals": { "type": "array", "items": { "type": "string" }, "description": "Glob patterns; default all." },
"compression": { "enum": ["none", "zstd", "lz4"], "default": "zstd" }
}
}
},
"$defs": {
"dt": { "type": "number", "exclusiveMinimum": 0, "maximum": 10, "description": "seconds; must be a whole number of nanoseconds" },
"substitute": {
"oneOf": [
{ "enum": ["ideal", "zero", "clear", "ambient", "ground_truth", "fixed", "load_profile", "replay"] },
{
"type": "object",
"additionalProperties": false,
"required": ["kind"],
"properties": {
"kind": { "enum": ["ideal", "constant", "replay"] },
"preset": { "type": "string" },
"source": { "type": "string" },
"value": { "type": "number" }
}
}
]
},
"enabled_or_substituted": {
"description": "A disabled domain must name a substitute; a replay substitute must name a source.",
"allOf": [
{ "if": { "properties": { "enabled": { "const": false } } },
"then": { "required": ["substitute"] } },
{ "if": { "properties": { "substitute": { "const": "replay" } }, "required": ["substitute"] },
"then": { "required": ["source"] } }
]
},
"common": {
"type": "object",
"required": ["enabled"],
"properties": {
"enabled": { "type": "boolean" },
"dt": { "$ref": "#/$defs/dt" },
"substitute": { "$ref": "#/$defs/substitute" },
"source": { "type": "string", "description": "MCAP file for a replay substitute." }
}
},
"generic_domain": {
"allOf": [ { "$ref": "#/$defs/common" }, { "$ref": "#/$defs/enabled_or_substituted" } ],
"unevaluatedProperties": false
},
"rigid_body": {
"allOf": [ { "$ref": "#/$defs/common" }, { "$ref": "#/$defs/enabled_or_substituted" } ],
"properties": {
"backend": { "enum": ["physx", "mujoco", "jolt"] },
"solver_iterations": { "type": "integer", "minimum": 1 },
"substeps": { "type": "integer", "minimum": 1, "maximum": 64, "default": 1, "description": "Jolt steps per rigid-body step: each divides Jolt's joint energy loss and multiplies its cost (rigid_body.md §8.1)." },
"noslip_iterations": { "type": "integer", "minimum": 0, "maximum": 100, "default": 0, "description": "MuJoCo's noslip post-solver iterations (mjOption.noslip_iterations); 0 is off. Stops soft contacts creeping on slopes at more cost per step and changes transients where feet must slip (docs/plan/spikes/legged-contact.md §6). Other backends ignore it." },
"gpu": { "type": "boolean", "default": false },
"load_profile": { "type": "string", "description": "CSV torque-vs-speed table for the load_profile substitute." }
},
"unevaluatedProperties": false
},
"electrical": {
"allOf": [ { "$ref": "#/$defs/common" }, { "$ref": "#/$defs/enabled_or_substituted" } ],
"properties": {
"fidelity": { "enum": ["ideal_bus", "averaged", "fmu"], "default": "averaged" },
"speed_prediction": { "type": "boolean", "default": true }
},
"unevaluatedProperties": false
},
"thermal": {
"allOf": [ { "$ref": "#/$defs/common" }, { "$ref": "#/$defs/enabled_or_substituted" } ],
"properties": {
"ambient_temperature": { "type": "number", "exclusiveMinimum": 0, "description": "K; required for the ambient substitute when no environment file is given" }
},
"unevaluatedProperties": false
},
"aerodynamics": {
"allOf": [ { "$ref": "#/$defs/common" }, { "$ref": "#/$defs/enabled_or_substituted" } ],
"properties": {
"fidelity": { "enum": ["drag", "drag_plus_field", "lbm"], "default": "drag" }
},
"unevaluatedProperties": false
},
"weather": {
"allOf": [ { "$ref": "#/$defs/common" }, { "$ref": "#/$defs/enabled_or_substituted" } ],
"properties": {
"effects": { "type": "array", "uniqueItems": true,
"items": { "enum": ["fog", "rain", "dust", "wet_friction", "lens_contamination"] } }
},
"unevaluatedProperties": false
},
"emi": {
"allOf": [ { "$ref": "#/$defs/common" }, { "$ref": "#/$defs/enabled_or_substituted" } ],
"properties": {
"coupling": { "type": "array", "uniqueItems": true,
"items": { "enum": ["magnetometer", "imu", "encoder", "can_bus", "wifi"] } }
},
"unevaluatedProperties": false
},
"radiation": {
"allOf": [ { "$ref": "#/$defs/common" }, { "$ref": "#/$defs/enabled_or_substituted" } ],
"properties": {
"seu_injection": { "type": "boolean", "default": false }
},
"unevaluatedProperties": false
},
"sensors": {
"allOf": [ { "$ref": "#/$defs/common" }, { "$ref": "#/$defs/enabled_or_substituted" } ],
"properties": {
"only": { "type": "array", "items": { "type": "string" }, "description": "Sensor prim names to simulate; others get ground truth." }
},
"unevaluatedProperties": false
},
"vehicle_dynamics": {
"allOf": [ { "$ref": "#/$defs/common" }, { "$ref": "#/$defs/enabled_or_substituted" } ],
"properties": {
"tire_model": { "enum": ["linear", "pacejka"], "default": "pacejka" }
},
"unevaluatedProperties": false
},
"rotor_aero": {
"allOf": [ { "$ref": "#/$defs/common" }, { "$ref": "#/$defs/enabled_or_substituted" } ],
"properties": {
"fidelity": { "enum": ["coefficients", "bem"], "default": "coefficients" },
"ground_effect": { "type": "boolean", "default": true }
},
"unevaluatedProperties": false
},
"traffic": {
"allOf": [ { "$ref": "#/$defs/common" }, { "$ref": "#/$defs/enabled_or_substituted" } ],
"properties": {
"backend": { "enum": ["builtin", "sumo"], "default": "builtin" },
"sumo_config": { "type": "string" }
},
"unevaluatedProperties": false
}
}
}
Checks that JSON Schema cannot express and that the loader performs: every dt is a whole number
of nanoseconds; steps are commensurate (architecture §6); referenced files exist; a replay
source contains the channels the domain contract needs; emi.coupling entries have matching
EmiSusceptibilityAPI prims; the requested tier is available.
CI validates every file in profiles/examples/ with check-jsonschema (TODO(verify) version)
and then loads it with the mock server in --validate-only mode.
5.3 Example profiles, one per robot class¶
The two profiles from CLAUDE.md §11.1 remain in profiles/examples/ with schema_version: 1
added. The six below are new.
# profiles/examples/amr_warehouse_nav2.yaml — AMR, ros2_control + Nav2, electrical on
schema_version: 1
stage: worlds/warehouse_small.usda
environment: environments/indoor_20c.usda
seed: 1
domains:
rigid_body: { enabled: true, backend: mujoco, dt: 0.001 }
electrical: { enabled: true, fidelity: averaged, dt: 0.0001 }
thermal: { enabled: true, dt: 0.1 }
aerodynamics: { enabled: false, substitute: zero }
weather: { enabled: false, substitute: clear }
emi: { enabled: false, substitute: zero }
radiation: { enabled: false, substitute: zero }
sensors: { enabled: true, dt: 0.005 }
bridges:
ros2: { enabled: true, use_sim_time: true }
ros2_control: { enabled: true }
views: [physics_3d, waveforms, sensors]
record: { format: mcap, path: runs/amr_warehouse_001.mcap }
# profiles/examples/arm_pick_place_moveit.yaml — 6-DoF arm, MoveIt 2, electrical + thermal
schema_version: 1
stage: worlds/workcell_arm6.usda
environment: environments/indoor_20c.usda
domains:
rigid_body: { enabled: true, backend: mujoco, dt: 0.001 }
electrical: { enabled: true, fidelity: averaged, dt: 0.0001 }
thermal: { enabled: true, dt: 0.1 }
aerodynamics: { enabled: false, substitute: zero }
weather: { enabled: false, substitute: clear }
emi: { enabled: true, coupling: [encoder], dt: 0.001 }
radiation: { enabled: false, substitute: zero }
sensors: { enabled: true, dt: 0.01, only: [wrist_camera] }
bridges:
ros2: { enabled: true }
ros2_control: { enabled: true }
views: [physics_3d, electrical_schematic, waveforms, thermal]
record: { format: mcap, path: runs/arm_pick_place_001.mcap }
# profiles/examples/quad_px4_gusty.yaml — quadcopter, PX4 SITL lockstep, wind gusts
schema_version: 1
stage: worlds/open_field_quad.usda
environment: environments/gusty_8ms_dryden.usda
deterministic: false
domains:
rigid_body: { enabled: true, backend: mujoco, dt: 0.001 }
electrical: { enabled: true, fidelity: averaged, dt: 0.00005 }
thermal: { enabled: true, dt: 0.1 }
aerodynamics: { enabled: true, fidelity: drag_plus_field, dt: 0.001 }
rotor_aero: { enabled: true, fidelity: coefficients, ground_effect: true, dt: 0.001 }
weather: { enabled: true, dt: 0.01 }
emi: { enabled: true, coupling: [magnetometer], dt: 0.001 }
radiation: { enabled: false, substitute: zero }
sensors: { enabled: true, dt: 0.001 }
bridges:
ros2: { enabled: true }
mavlink: { enabled: true, autopilot: px4, lockstep: true, endpoint: "tcp://127.0.0.1:4560" }
views: [physics_3d, waveforms, fields]
record: { format: mcap, path: runs/quad_gusty_001.mcap }
# profiles/examples/car_skidpad_wet.yaml — passenger car, vehicle dynamics on a wet skid pad
schema_version: 1
stage: worlds/skidpad_sedan.usda
environment: environments/rain_10mmh_day.usda
domains:
rigid_body: { enabled: true, backend: physx, dt: 0.001 }
vehicle_dynamics: { enabled: true, tire_model: pacejka, dt: 0.001 }
electrical: { enabled: false, substitute: ideal }
thermal: { enabled: false, substitute: ambient }
aerodynamics: { enabled: true, fidelity: drag, dt: 0.01 }
weather: { enabled: true, effects: [rain, wet_friction], dt: 0.05 }
emi: { enabled: false, substitute: zero }
radiation: { enabled: false, substitute: zero }
sensors: { enabled: false, substitute: ground_truth }
bridges:
ros2: { enabled: true }
views: [physics_3d, waveforms]
record: { format: mcap, path: runs/car_skidpad_001.mcap }
# profiles/examples/av_urban_autoware.yaml — autonomous car, sensors + traffic + scenario
schema_version: 1
stage: worlds/city_block_av.usda
environment: environments/fog_150m_dusk.usda
tier: 2
domains:
rigid_body: { enabled: true, backend: physx, dt: 0.002 }
vehicle_dynamics: { enabled: true, tire_model: pacejka, dt: 0.002 }
electrical: { enabled: false, substitute: ideal }
thermal: { enabled: false, substitute: ambient }
aerodynamics: { enabled: true, fidelity: drag, dt: 0.01 }
weather: { enabled: true, effects: [fog, lens_contamination], dt: 0.05 }
emi: { enabled: false, substitute: zero }
radiation: { enabled: false, substitute: zero }
sensors: { enabled: true, dt: 0.002 }
traffic: { enabled: true, backend: sumo, sumo_config: scenarios/city_block.sumocfg, dt: 0.1 }
comms: { enabled: false, substitute: ideal }
scenario:
opendrive: scenarios/city_block.xodr
openscenario: scenarios/cut_in_fog.xosc
bridges:
ros2: { enabled: true, gpu_buffers: true }
autoware: { enabled: true }
views: [physics_3d, sensors, fields]
record: { format: mcap, path: runs/av_urban_001.mcap, signals: ["body/*", "sensor/*/meta", "traffic/*"] }
# profiles/examples/huge_world_survey.yaml — drone survey over a 40 km geospatial tile set
schema_version: 1
stage: worlds/coastal_survey_root.usda # root layer; terrain tiles are USD payloads
environment: environments/clear_day.usda
world:
geo_origin: { latitude: 33.5902, longitude: 130.4017, height: 20.0 } # scenario parameter
streaming:
enabled: true
load_radius: 3000
unload_radius: 3500
active_region_radius: 500
rebase_distance: 1000
domains:
rigid_body: { enabled: true, backend: mujoco, dt: 0.002 }
electrical: { enabled: true, fidelity: averaged, dt: 0.0001 }
thermal: { enabled: false, substitute: ambient, ambient_temperature: 293.15 }
aerodynamics: { enabled: true, fidelity: drag_plus_field, dt: 0.002 }
rotor_aero: { enabled: true, fidelity: coefficients, dt: 0.002 }
weather: { enabled: false, substitute: clear }
emi: { enabled: false, substitute: zero }
radiation: { enabled: false, substitute: zero }
sensors: { enabled: true, dt: 0.01, only: [gnss, imu, nadir_camera] }
bridges:
ros2: { enabled: true }
mavlink: { enabled: true, autopilot: ardupilot, lockstep: true }
views: [physics_3d, sensors]
record: { format: mcap, path: runs/coastal_survey_001.mcap }
In quad_px4_gusty.yaml the electrical step is 50 µs and physics is 1 ms; the base tick is 50 µs
and the hyperperiod is 100 ms. In amr_warehouse_nav2.yaml the sensors step of 5 ms is the
scheduling period of the sensor module; each sensor’s own rate comes from sensor:rate.
6. FMU usage¶
Standard: FMI 3.0 co-simulation. Model exchange is not hosted.
An FMU is referenced from USD with an
assetattribute (elec:behaviorModel). Its variables are mapped to signals by name through a sidecar file next to the FMU:
# models/bldc_drive.fmu.map.yaml
fmu: bldc_drive.fmu
fmi_version: "3.0"
step: 0.0001 # s, communication step; must divide the electrical module dt
inputs:
- { variable: omega_mech, signal: "joint/{joint}/velocity", unit: rad/s }
- { variable: tau_cmd, signal: "joint/{joint}/torque_command", unit: N.m }
- { variable: v_bus, signal: "bus/{bus}/voltage", unit: V }
- { variable: T_winding, signal: "thermal/{prim}/temperature", unit: K }
outputs:
- { variable: tau_shaft, signal: "joint/{joint}/torque", unit: N.m }
- { variable: i_bus, signal: "motor/{prim}/bus_current", unit: A }
- { variable: p_loss, signal: "motor/{prim}/loss_power", unit: W }
parameters:
- { variable: R_s, attribute: "elec:windingResistance" }
- { variable: L_d, attribute: "elec:inductance" }
- { variable: K_t, attribute: "elec:torqueConstant" }
The FMU host checks each mapped variable’s declared FMI unit against the signal unit. FMI units are converted to a
lagrange::Unitfrom theBaseUnitexponents inmodelDescription.xml; a mismatch is a wiring error.FMUs must be source FMUs or carry a
linux64(amd64) andaarch64-linuxbinary. Binary-only FMUs for one architecture make the profile fail on the other with a clear message.Determinism: an FMU is treated as deterministic only if it declares
canGetAndSetFMUStateand passes a save/restore round-trip test at load.Built-in C++ models are the default for the battery ECM and the dq motor. FMUs are the extension path. See open question Q8 for why the plan does not depend on FMUs for v0.3.
Status (v0.3). FmuComponent (modules/electrical/fmu_host/, on FMI Library 3.0.4 through
fmilibrary3_vendor) hosts FMI 3.0 co-simulation FMUs as above: the map, unit checks from the
BaseUnit exponents (SI units only: a factor or offset is refused), parameters from the
component’s attributes, one fmi3DoStep per module step at the map’s step, and determinism and
save/restore through fmi3GetFMUState and serialization when the FMU declares both. Additions to
the sketch above: an input may say optional: <value>, read while its signal is not written (a
winding temperature without the thermal domain); every input is read as a feedback input, so an
FMU and the network can read each other’s outputs. At electrical fidelity fmu the network leaves
a motor with elec:behaviorModel to its FMU and takes its motor/<m>/bus_current into the bus;
battery FMUs are not hosted yet. The reference FMU is lagrange_models’ dc_drive (a brushed DC
drive, hand-written in C, Apache-2.0), which matches the built-in brushed model step for step.
7. Recordings (MCAP)¶
One file per run. Chunked, zstd by default, with the summary section and index.
Message encoding: Protobuf, schemas from
proto/lagrange/record/v1/. The sameSignalBlockmessage as the live protocol is used, so replay is a file-backed protocol source.Channels:
Channel topic |
Message |
Content |
|---|---|---|
|
|
profile (YAML text), stage path and hash, schema versions, seed, tier, git describe |
|
|
every signal’s name, type, unit, writer |
|
|
one at start and every 10 s (seek points) |
|
|
transform and attribute changes |
|
|
signals grouped by writer step size, e.g. |
|
|
determinism check values |
|
|
the region frame from that time on, at each rebase of the floating origin (v0.7); positions recorded after it are in the new frame |
|
|
console messages |
ROS topics (optional) |
CDR, as rosbag2 writes them |
when |
Implementation (v0.2,
lagrange_server --record): every bus signal at its native rate from t = 0 (a sample written late is NaN, so runs stay contiguous), signals with more than--record-max-componentscomponents (default 1024, e.g. a 3D lidar’s ranges) left out, and onescene<prim path>/posesignal at 50 Hz per moving prim, bound to its prim inRunMeta.pose_bindingsso that a replay moves visuals and sensors too.RunMetais written at the start and again at the end with the duration; readers keep the last. Scene deltas, log records and sensor frames are not recorded yet. The sample AMR records about 1.5 MB per simulated second without its power system and about 2.8 MB with it (the 10 kHz electrical signals; zstd does little for noisy doubles).Replay (v0.3,
lagrange_recording):Recording::openloads a file’s signals into memory, andReplaySubstitute(domain, file)writes every signal a module of that domain wrote, at its recorded rate and unit, committing the sample for its step’s end time as a live writer does. Bench mode replaysrigid_body(--bench, or the profile’sreplaysubstitute with asource). Physics stepping at the end of its window (architecture.md §8.1) made the same sample visible one step later, so a bench run matches the original closely, not bit for bit.Units are stored in the catalog. A replay substitute refuses a channel whose recorded unit differs from the contract.
Compatibility: files written by rosbag2 with the MCAP storage plugin can be opened by the mock server for ROS-topic display (pose, joint states, images). They do not contain our signal catalog, so scopes show only numeric fields that the viewer can extract from known message types. This is the “MCAP compatibility” item in the v0.1 scope.
8. Materials and meshes¶
Render materials:
UsdPreviewSurfaceis the baseline that every importer writes and the viewer renders. MaterialX (UsdMtlx) is read when present and falls back to itsUsdPreviewSurfaceapproximation; a MaterialX-to-Slang path is a later RFC.Importers convert glTF PBR metallic-roughness, OBJ MTL and DAE Phong/Lambert to
UsdPreviewSurface. Textures are copied next to the USD file; files over 1 MB are not committed to the main repo (CLAUDE.md §9).Collision:
tools/collision_bakeruns CoACD (default) or V-HACD on each render mesh marked for collision and writes explicit convex hullMeshprims withpurpose = "guide"under acollisionscope. Backends load only those hulls and primitive shapes. A stage whose collider references a render mesh directly produces a load warning and an automatic single convex hull.
9. Importers¶
All importers are command-line tools and library functions under io/importers/, and produce a
USD layer plus a report of what was dropped. The viewer’s “Open URDF…” action runs the importer
in the server (or mock server) and receives the result through the protocol.
Source |
Library |
Covered |
Not covered at first |
|---|---|---|---|
URDF / xacro |
|
links, joints (all standard types), inertials, visual/collision geometry (primitives + meshes via Assimp), materials, mimic joints, limits including URDF 1.2 acceleration/jerk, |
|
SDFormat |
|
models, links, joints, sensors (lidar, camera, imu, gps/navsat, magnetometer), lights, nested models, |
Gazebo system plugins (reported, not converted), Fuel URIs without a local cache, heightmaps (v0.7) |
MJCF |
MuJoCo’s own parser ( |
bodies, joints, geoms, actuators (motor, position, velocity), sensors that have an equivalent, tendons (fixed) |
spatial tendons, flex/deformables, plugin-defined elements |
glTF 2.0 / OBJ / STL / DAE |
Assimp 6.0.4 (apt) |
meshes, node hierarchy, PBR/Phong materials, textures (baked into colours, below) |
animations, skins, morph targets |
Meshes in v0.2: lagrange_meshes (io/meshes/) reads glTF, OBJ, STL and Collada through
Assimp into triangles grouped by material, with the node hierarchy baked in, Collada units
applied and Collada’s <up_axis> ignored (the geometry keeps its authored axes, as ROS tools
expect). package://, file:// and relative references resolve through the ament index. The
URDF loader uses it for visual meshes: one prim per material, coloured by the URDF material when
there is one and by the file’s otherwise. Textures are not imported yet (a note says so), and
collision meshes collide as their convex hull (concave ones on fixed links are skipped; collision_bake splits them).
Status in v0.2. lagrange_importers reads SDFormat and MJCF into the same world tables and
scene as the URDF loader, and lagrange_import writes any of the three as USD
(io/importers/include/lagrange/importers/Importers.hpp lists the rules). Not yet: mesh visuals in SDFormat
and MJCF (the URDF loader reads them through lagrange_meshes), cameras and other
sensors without a Lagrange model, URDF planar joints, and MJCF
tendons, flex, servo actuators (their joints take torque commands instead) and equalities other than one joint copying another. Each is listed in
the import report. An MJCF hinge’s or slide’s armature (with a joint actuator’s armature
times its gear squared) is the joint’s armature in the world tables, as the motors’ rotor
inertia is (§3.1), but USD has no joint attribute for it yet, so lagrange_import drops it (a
joint:armature on JointDynamicsAPI_1 would need the owner, RFC 0007). MJCF has no lidar; lidars on an MJCF robot come from an overlay (0.2-G2).
Electrical, thermal and EMI data do not exist in URDF/SDF/MJCF. Importers accept an optional overlay file that applies our API schemas by link or joint name:
# amr_diffdrive.overlay.yaml (excerpt; the full file is in assets/robots/amr_diffdrive/)
schema_version: 1
apply:
- prim: left_wheel_joint # a link, joint or sensor by name, or a prim path
create_child: left_drive_motor # a new prim, under a joint's parent link
schemas:
ElectricalMotorAPI_1:
elec:windingResistance: 0.12
elec:inductance: 0.00031
elec:torqueConstant: 0.085
elec:maxCurrent: 8.0
elec:joint: left_wheel_joint # relationships: names or paths
elec:powerPort: power/dc_48v
- create: power/dc_48v # a new prim at this path under the robot's top prim
schemas:
ElectricalBusAPI_1: { elec:bus:undervoltageTrip: 42.0, elec:bus:overvoltageTrip: 60.0 }
Status (v0.3). lagrange_stage::applyOverlay implements this format (rules on its
declaration in io/stage/include/lagrange/stage/Stage.hpp); lagrange_server --overlay and
lagrange_import --overlay use it, and the stage writer writes the instances, so an imported
robot keeps them in USD. Values are checked as the stage loader checks a stage, and every
problem is reported together. Overlays add schema instances, and a create_child prim with
SensorAPI_1 and one of ImuAPI_1, GnssAPI_1, MagnetometerAPI_1, BarometerAPI_1 or
RadarAPI_1 becomes a simulated sensor on that link, read as the stage reader reads it in USD
(the schema’s fallbacks; sensor:rate and the radar’s rangeMax, azimuthFov, elevationFov,
txPower and noiseFloor required and positive; at the link’s origin, an overlay has no mount
pose). These are the catalog’s overlay_only sensors, which the robot builder writes into
<robot>.overlay.yaml:
- prim: base_link
create_child: front_radar
schemas:
SensorAPI_1: { sensor:rate: 20 }
RadarAPI_1:
sensor:radar:rangeMax: 60 # m
sensor:radar:azimuthFov: 1.2 # rad
sensor:radar:elevationFov: 0.2 # rad
sensor:radar:txPower: 0.01 # W
sensor:radar:noiseFloor: 1.0e-13 # W
Any other sensor type (a camera or a lidar) is refused with a message naming the prim, never
dropped: it belongs in the robot file’s own <sensor> or its USD, so lidars on an MJCF robot
still need USD for now.
9.1 A SPICE netlist as an overlay¶
--overlay also takes a netlist (.cir, .sp, .spice, .net, .ckt, io/stage/src/Netlist.cpp), so one file is the circuit for ngspice and the power system of a run. It becomes the same schemas an overlay file makes, at load. A netlist from KiCad comes through kicad-cli sch export netlist --format spice.
In the netlist |
In the run |
|---|---|
|
|
The node a chain reaches, with the |
|
|
|
|
|
|
what SPICE cannot say about a battery; required. A curve is for the whole pack and must give the source’s voltage at its |
|
|
|
a |
|
a |
|
|
|
the bus’s trips; required |
|
|
The first line is the title, as in SPICE; analysis commands and .control blocks are ignored. Everything else is refused with its line, every problem together, and nothing is left out in silence: transistors, inductors, subcircuits, SPICE switches, controlled and current sources, .param, .include, sources other than DC, a diode with no *lagrange diode, and a capacitor between two buses. So is a drive of lagrange export spice (V(p_drive)), so an exported netlist does not read back yet. tools/ci/check_electrical.py runs every circuit through this route and through an overlay.
9.2 A URDF that names its power system¶
A <lagrange> block in a URDF (under <robot>), or an SDFormat file (under <model>), gives the robot its power system with no --overlay; URDF readers such as urdfdom skip the unknown element, so the file stays valid for other tools:
<lagrange>
<schematic file="power/arm.cir"/> <!-- relative to the URDF, or package:// -->
<battery source="V_pack" capacity="72000" cutoff="44.8" max_charge="10"/>
<bus node="dc" undervoltage="42" overvoltage="60"/>
<motor joint="shoulder" node="dc" r="0.12" l="0.00031" kt="0.085" imax="8" gear="20"/>
</lagrange>
The attributes are the keys of §9.1’s *lagrange lines, which the netlist may hold instead; a mistake stops the load with its message. lagrange_import keeps the result in the USD it writes. Adding --overlay to a robot with a block is refused for anything it applies twice. Names and values cannot hold spaces. MJCF has no such block: its parser refuses elements it does not know, so use --overlay.
Meshes too large for the repository (no file over 1 MB, CLAUDE.md §9) are fetched, not committed:
assets/external_assets.yaml lists each file with its upstream repository, pinned commit,
SHA-256 and licence, and ros2 run lagrange_assets fetch_assets [ID...] downloads them into
$LAGRANGE_ASSET_DIR (default ~/.local/share/lagrange/assets/<id>/) with the licence and a
NOTICE. Robot files name them lagrange-asset://<id>/<file>; an asset that is not fetched is a
note, and the link shows a magenta box in its place. Textures are not drawn: the importer
bakes a textured part into parts of one colour each (each triangle takes the texture’s colour
under it, PNG or JPEG, embedded or a file next to the mesh; the triangles are grouped into 16
colours at most by k-means), which keeps the viewer protocol unchanged.
Without an overlay, an imported robot runs with the electrical domain substituted by the ideal torque source. The viewer’s domain panel shows why the electrical toggle is unavailable (“no ElectricalMotorAPI prims in stage”).
9.3 Lagrange’s own elements in SDFormat¶
What SDFormat has no element for, Lagrange reads from custom elements prefixed lagrange:
(RFC 0015 §4). The namespace URI for xmlns:lagrange is the documentation site,
https://open-physical-systems.github.io/Lagrange; libsdformat does not require the
declaration, keeps prefixed elements without a warning, and Gazebo ignores them. The plain
(unprefixed) names the URDF <gazebo> form uses are read too, so one <sensor> block pastes
between the two formats; libsdformat warns that it copies them.
Lagrange |
SDFormat |
|---|---|
fisheye lens |
|
cutoff |
|
field of view |
|
k1..k4 |
|
scan pattern |
|
channel table |
|
rosette |
|
<sdf version="1.12" xmlns:lagrange="https://open-physical-systems.github.io/Lagrange">
...
<sensor name="livox" type="gpu_lidar"><update_rate>10</update_rate><lidar>
<lagrange:pattern>rosette</lagrange:pattern>
<scan><horizontal><samples>10000</samples></horizontal></scan>
<range><min>0.1</min><max>260</max></range>
<lagrange:rosette><fov>0.670206</fov><point_rate>100000</point_rate></lagrange:rosette>
</lidar></sensor>
10. Versioning and migration¶
Artefact |
Version carrier |
Compatibility rule |
Migration tool |
|---|---|---|---|
USD schemas |
family + integer suffix ( |
Within a version: only additions with fallbacks. Renames, unit changes, removed attributes, changed fallbacks → new version |
|
Profiles |
|
Same as above |
|
Protocol |
package |
|
none; old clients are refused at handshake with a readable message |
Recordings |
|
Readers accept all older versions of the same major; new channels and fields only within 1.x |
|
Plugin ABI |
|
append only within a major (RFC 0007): |
none |
FMU map files |
|
as profiles |
|
Saved states |
scheduler state version after the magic |
1.x reads every saved state of 1.1 and later into a run of the same robot, world and profile |
none: read in place |
Loader behaviour: core/stage/ supports the current and the previous version of each schema
family. An older version loads with a warning that names the migration command. Two versions of
the same family applied to one prim is an error.
Every schema change needs: an RFC or a PR note (CLAUDE.md §9), a migration function with a test
that round-trips a sample file, an entry in schemas/CHANGELOG.md, and two approvals including a
core maintainer.
From v1.0 the schemas, the plugin ABI, the protocol, profiles and recordings are frozen for the
1.x line (RFC 0007): they change only by addition, and schemas/test/frozen_1_0.json lists every
schema attribute as it was at 1.0. tools/migrate/test/test_old_releases.py takes every sample
stage and example profile of v0.5.0 and later from the git tags and checks that this release’s
tools read, migrate and validate them. Before v1.0 all schemas were version 1 and could change
without a migration. The migration machinery is built in v0.3 and exercised with a synthetic _0 → _1
migration so that it is proven before it is needed: the family ExampleMotorAPI, which no real
file uses (tools/migrate/test/test_schema.py). The stage loader notes a prim that applies an
older version of a registered family with the command that migrates it, and refuses two versions
of one family on one prim.
11. Saved states¶
Server::saveState (Python save_state()) returns the run’s state as bytes for
restoreState (restore_state()) in the same build of the same run: the robot, world and
profile it was saved from. Within 1.x they also restore in later releases (RFC 0007).
Layout: the site (Server.cpp, saveSite: gravity, ambient temperature, air density, the
aerodynamics and weather settings, the local gravity vector), then the scheduler’s state
(Scheduler.cpp): the magic LGST, a format version, time, tick, each module’s state as
(label, step index, length, bytes) in execution order, then the signal bus.
Format |
Written by |
What it holds |
|---|---|---|
1 |
1.1, 1.2 |
site, modules, bus values, handles and timing |
2 |
1.3 and later |
format 1, then the bus’s published buffers (each image’s sequence and bytes) |
1.0 had no saveState in its API, so no 1.0 state exists to read.
A format 1 state restores as follows: no buffers, so the restored run reads no image until each
sensor’s next frame (as it did in 1.2); each handle slot numbers on from the newest handle the
state holds, the last its saved run published, so the run continues with the saved run’s handles,
and once the bus’s four kept buffers have been replaced, its state_hash() equals the saved run’s
(test_scheduler RestoresAFormatOneStateWithoutItsImages).
A module’s own state grows only by appending, and a module reads the shorter layouts of earlier releases, filling what they lacked with what they implied:
Module |
Appended in |
An older state means |
|---|---|---|
multicopter controller |
1.2: stand height, set point ramp, leash |
no surface known (it stands at its start’s height), the ramp at rest, the leash free |
car controller ( |
after 1.3: backing away when held up |
driving, never held up or backing away |
demo drive command ( |
after 1.3: the figure eight |
the eight starts afresh where the robot stands |
A later release may also add a module to the same run: aerodynamics’ zero substitute (after 1.3)
joins every run whose aerodynamics is off while the site’s air density is given, and with it the
wind and drag signals and the sums of them that core/wrench_sum writes. A state from before has
neither, and its bus holds no place for them. Server::restoreState then asks the scheduler which
of the run’s modules the state lacks (Scheduler::addedSince); when every one keeps no state, it
builds the run again without them (Scheduler::leaveOut), which is the saved run’s composition,
logs that the run goes on without them, and restores. The run goes on as the saved one did (the
zero substitute’s outputs are the defaults its readers read without it). It stays without them
until a state that has them is restored; a module that keeps state and is missing from the state
is refused by name, since it cannot start in the middle of a run.
The bus is stored in the order the modules declare their signals, which is the order the server adds them. The electrical ideal substitute stays where 1.1 to 1.3 added it, after the robot’s controllers, unless the robot has rotors: then it comes after every module, so that it sees the multicopter controller’s torque commands (the layout of those runs changed after 1.3, see below).
A module may also read more than it did (after 1.3 the demo drive reads the robot’s pose to drive
its eight). The saved run’s outputs, their timing and every module’s state are then restored
exactly, and the inputs are read again from the outputs at each reader’s next step; what is lost
is a window average’s partial window at the moment of the save, which starts again from its
writer’s last value, so the run goes on within that difference of the saved one, and the same on
every restore (test_scheduler RestoresAStateFromBeforeAModuleReadMore).
python/test/test_lagrange.py restores a state the released 1.2.0 packages saved
(python/test/data/quad_x500_hover_1.2.0.state, the sample quadcopter hovering at 3 s) and
checks the run goes on deterministically and that it saved again in format 2 continues the same.
Checked by hand against the 1.2.0 packages (localhost/lagrange:1.2.0): the sample AMR (no
world, CPU lidar, saved at 1 s) and the sample sedan restore and run on deterministically; the
AMR’s state (740 kB, mostly lidar ranges on the bus) is too large to commit as a fixture.
What does not restore, with the reason in the message: a state of a different run (a module
that keeps state is missing from it, or the module count or a label differs: saved state does not match: ...: a state restores into a run of the same robot, world and profile), one a module
cannot read, or one whose run’s modules now write other signals than they did (signal bus layout): among the samples, a 1.1 to 1.3 state of a multicopter with the electrical domain off
(the run in which it could not fly, fixed after 1.3 by moving the ideal substitute); for a format 1 state the message adds that it was
written by 1.1 or 1.2 and points here. Every module state that changed after 1.1 is in the table
above (the layouts that changed between 1.0 and 1.1, in electrical, Jolt, lidar, traffic and
weather, never reached a saved state, since 1.0 could not save one). A bare scheduler state
(Scheduler::saveState, starting with LGST) given to Server::restoreState is refused as one
without its site.