Domain: electrical¶
1. Scope and release¶
DC power distribution on a robot: battery, bus, motor drives, loads, converters. Voltages and currents are simulated with averaged (cycle-mean) models that run in real time. Switching-level detail is exported to SPICE for offline study and is never simulated in the loop (CLAUDE.md §11.7). This domain is the project’s wedge. Release: v0.3 (a thin battery + DC-motor slice in v0.2 is proposed in open question Q3).
Sub-packages: network/ (builds the circuit graph from PortAPI/ElectricalBusAPI prims),
fmu_host/ (FMI 3.0 co-simulation), substitutes/.
2. Models per fidelity level¶
|
Battery |
Motor + drive |
Bus |
|---|---|---|---|
|
Ideal voltage source at nominal voltage; SoC by coulomb counting |
Torque = command, clipped by |
No dynamics |
|
ECM: |
dq-frame PMSM or DC model with PI current loops (FOC), voltage limit from bus voltage (field weakening not modelled at first), copper loss |
Bus capacitor node; regeneration raises voltage; brake resistor; under- and over-voltage trips (brownout) |
|
FMU if |
FMU if |
as |
Equations of the averaged PMSM model, per motor, integrated per step with the exact solution of each axis’s R-L equation for the voltages held over the step. That is unconditionally stable, like the backward-Euler update first planned, and exact for a voltage step, where backward Euler is 2.8 % off at 10 steps per time constant against the 0.1 % that §8 asks:
v_d = R·i_d + L_d·di_d/dt − ω_e·L_q·i_q
v_q = R·i_q + L_q·di_q/dt + ω_e·(L_d·i_d + λ)
τ = 1.5·p·(λ·i_q + (L_d − L_q)·i_d·i_q)
ω_e = p·N·ω_joint (p pole pairs, N gear ratio)
R = R_ref·(1 + α·(T − T_ref))
i_bus = (v_d·i_d + v_q·i_q)·1.5 / (η_inv·V_bus)
The flux linkage λ and the torque constant in the schema are related by Kt = 1.5·p·λ for the
peak-amplitude dq convention. The convention (peak vs RMS, line-line vs line-neutral) is the most
common source of factor errors in motor models; it is fixed in the schema documentation and
checked by a unit test that converts a datasheet example (risk R13).
Network solution: components connect to bus nodes. Each bus node has a capacitance, so node voltages are states and the network is solved explicitly per step as a set of current sums (nodal analysis with capacitor companion models). A bus without capacitance gets a small default (1 µF) with a warning.
3. Signals¶
// modules/electrical/network — declare()
for (auto& m : world.instancesOf("ElectricalMotorAPI_1")) {
auto j = jointOf(m); auto p = name(m);
d.input ({.name = fmt("joint/{}/torque_command", j), .type = SignalType::Scalar, .unit = units::N_m});
d.input ({.name = fmt("joint/{}/velocity", j), .type = SignalType::Scalar, .unit = units::rad_per_s,
.hold = Hold::LinearExtrapolate, .feedback = true});
d.input ({.name = fmt("joint/{}/effective_inertia", j), .type = SignalType::Scalar, .unit = units::kg_m2,
.optional = true, .defaultValue = 0.0, .feedback = true}); // enables speed prediction
d.input ({.name = fmt("thermal/{}/temperature", p), .type = SignalType::Scalar, .unit = units::K,
.optional = true, .defaultValue = 298.15, .feedback = true});
d.input ({.name = fmt("thermal/{}/derating", p), .type = SignalType::Scalar, .unit = units::one,
.optional = true, .defaultValue = 1.0, .feedback = true});
d.output({.name = fmt("joint/{}/torque", j), .type = SignalType::Scalar, .unit = units::N_m});
d.output({.name = fmt("motor/{}/current_d", p), .type = SignalType::Scalar, .unit = units::A});
d.output({.name = fmt("motor/{}/current_q", p), .type = SignalType::Scalar, .unit = units::A});
d.output({.name = fmt("motor/{}/voltage_d", p), .type = SignalType::Scalar, .unit = units::V});
d.output({.name = fmt("motor/{}/voltage_q", p), .type = SignalType::Scalar, .unit = units::V});
d.output({.name = fmt("motor/{}/bus_current", p), .type = SignalType::Scalar, .unit = units::A});
d.output({.name = fmt("motor/{}/loss_power", p), .type = SignalType::Scalar, .unit = units::W});
d.output({.name = fmt("motor/{}/fault", p), .type = SignalType::Int, .unit = units::one});
}
for (auto& b : world.instancesOf("BatteryAPI_1")) {
auto p = name(b);
d.input ({.name = fmt("thermal/{}/temperature", p), .type = SignalType::Scalar, .unit = units::K,
.optional = true, .defaultValue = 298.15, .feedback = true});
d.output({.name = fmt("battery/{}/soc", p), .type = SignalType::Scalar, .unit = units::one});
d.output({.name = fmt("battery/{}/terminal_voltage", p), .type = SignalType::Scalar, .unit = units::V});
d.output({.name = fmt("battery/{}/current", p), .type = SignalType::Scalar, .unit = units::A});
d.output({.name = fmt("battery/{}/loss_power", p), .type = SignalType::Scalar, .unit = units::W});
d.output({.name = fmt("battery/{}/power", p), .type = SignalType::Scalar, .unit = units::W}); // at its terminals
}
for (auto& bus : world.instancesOf("ElectricalBusAPI_1")) {
d.output({.name = fmt("bus/{}/voltage", name(bus)), .type = SignalType::Scalar, .unit = units::V});
d.output({.name = fmt("bus/{}/brownout", name(bus)), .type = SignalType::Bool, .unit = units::one});
}
for (auto& l : world.instancesOf("ElectricalLoadAPI_1")) {
d.input ({.name = fmt("load/{}/power_demand", name(l)), .type = SignalType::Scalar, .unit = units::W,
.optional = true}); // sensors and computers can modulate their draw
d.output({.name = fmt("load/{}/current", name(l)), .type = SignalType::Scalar, .unit = units::A});
d.output({.name = fmt("load/{}/powered", name(l)), .type = SignalType::Bool, .unit = units::one});
}
joint/{j}/torque_command is written by the ROS 2 control bridge, the MAVLink bridge or a
scripted controller. load/{}/powered lets a brownout switch off a sensor or the computer,
which is one of the effects this simulator can show and a pure-physics simulator cannot.
4. Step size¶
Default 100 µs. Range 10 µs to 1 ms. Guidance: at least 10 steps per electrical time constant
L/R of the fastest motor is not required for stability (the update is implicit) but is needed
for current-loop accuracy; the module warns when dt > 0.2 / currentLoopBandwidth.
5. Substitutes and contract¶
Contract: joint/{j}/torque for every joint driven by a motor prim (and, when the stage has no
motor prims at all, for every actuated joint with a torque_command).
Profile token |
Kind |
Behaviour |
|---|---|---|
|
ideal |
|
|
replay |
|
IdealTorqueSource::step keeps the body shown in CLAUDE.md §11.5, with torqueOut and
torqueCommand being SignalId values resolved in init().
It passes on the torque_command outputs of the modules declared before it, so the server adds
it after every controller (the multicopter controller and the MAVLink bridges come after the
rotors’ air). With no drive between the command and the joint, the built-in multicopter
controller (config ideal_motors) bounds each rotor’s command by the drive’s torque at the
rotor’s loaded top speed and lowers its rotor speed gain, so that its yaw-rate loop, which then
runs through the motors’ reaction on the frame within one step, does not ring. The MAVLink
bridges’ ESCs do the same for PX4 and ArduPilot (Px4Settings::idealMotors,
ArduPilotSettings::idealMotors, set by the server when no electrical network runs): each
rotor’s torque command is bounded by the drive’s torque at its loaded top speed (never below
what holding full output takes), and the speed gain is cut so that the speed loop’s gain per ESC
step, K·dt/J with J the rotor’s inertia about its axis, is at most 0.5 (Escs::kSpeedLoopGain;
the sample quadcopter’s 0.02 N·m per rad/s becomes 0.011 at PX4’s 250 Hz and stays at ArduPilot’s
1 kHz). test_escs checks that a throttle step then settles without overshoot within the bound,
and that with the electrical domain the commands are the same as before, bit for bit.
6. Placement¶
CPU on all tiers. One robot has tens of states; the cost is dominated by call overhead, so motors are stored SoA and updated in one loop. A batched GPU path for thousands of environments is a later RFC.
7. Offline export¶
Status (v0.3): lagrange export spice|modelica [PROFILE] [options] [--out FILE]
(Export.hpp in lagrange_electrical) rather than separate tools/ programs: the export needs
the loaded stage, overlays included, as the simulator sees it. The drives are averaged sinks of
their electrical power (a parameter to edit, or a waveform such as one recorded from a run); the
open-circuit voltage is held at the initial state of charge; charge limits, trips, brake
resistors and converters are not exported. The Modelica model uses the Modelica Standard
Library 4’s Electrical.Analog; it is checked for its structure only, as OpenModelica is not
part of the build.
tools/export_spice writes an ngspice netlist of the topology (battery ECM, bus capacitors,
ideal averaged drive sources or a three-phase inverter subcircuit per motor) for switching-level
study. tools/export_modelica writes a Modelica model with the same topology. Both are derived
from the same USD prims as the runtime network, so the schematic, the 3D view and the exports
agree.
8. Validation¶
Test |
Reference |
Tolerance |
|---|---|---|
RL step response of the d and q axes |
closed form |
0.1 % at 10 steps per time constant |
DC motor no-load speed, stall current, torque-speed line |
closed form from |
0.5 % |
Coupled motor + inertia step (coupling test) |
monolithic stiff ODE solution |
2 % RMS (architecture §8) |
Battery ECM pulse discharge |
published cell characterisation data with OCV and pulse tests: LG HG2 cell, Kollmeyer et al., doi:10.17632/b5mj79w5w9.2, CC BY 4.0 (HPPC and C/20 at 25 °C) |
terminal-voltage RMS error < 20 mV per cell |
Energy balance |
battery energy out = mechanical work + losses + stored |
closed to 0.5 % over a drive cycle |
Netlist round trip |
exported netlist run in ngspice (averaged sources) vs runtime |
bus voltage within 1 % |
Brownout scenario |
scripted stall of both AMR motors on a low battery |
bus trips, |
Sim-vs-real (v0.3) |
bench recording of a real BLDC drive: phase current, bus voltage, speed (to be recorded; Q16) |
within measurement uncertainty bands stated with the dataset |
9. Status (v0.3)¶
lagrange_electrical (modules/electrical/): ElectricalNetwork (network/, fidelity
averaged, default step 100 µs) and the IdealTorqueSource substitute. The models are in
Models.hpp so the tests can drive them without a scheduler. The server runs the network when
the robot has ElectricalMotorAPI_1 prims (from USD, or a URDF with an overlay file such as the
sample AMR’s) and the profile or --domain electrical=off does not switch it to the
substitute.
Choices made while implementing, beyond §2:
One flux linkage. The torque and the back-EMF come from λ = Kt / (1.5·p), so power is conserved by construction. An authored
backEmfConstantis a check: it must be within 3 % of Kt / 1.5 (dq) or Kt (brushed), or the motor is refused as a convention mix-up (risk R13).Voltage limit of a drive: Vbus/√3 peak phase voltage (sine-triangle with third harmonic or space-vector modulation, no overmodulation) for dq machines, Vbus for an H bridge. Saturation scales the voltage vector and holds the PI integrators.
Bus node solved with the capacitor’s backward-Euler companion against the batteries’ Thévenin sources; drives and loads draw at the previous step’s voltage (explicit), so a load notices a brownout one electrical step late.
Brownout latches each drive’s fault until the bus has recovered by 2 % and the torque command is back to zero; loads come back with the bus. Overvoltage switches in the brake resistor, or switches the drives off when there is none, with the same 2 % hysteresis.
Battery cut-off when the open-circuit voltage reaches
cutoffVoltage(empty), not on the terminal voltage under load: sag under load is the bus’s undervoltage trip’s job.Resistive loads take their resistance from
elec:load:powerat the bus’s starting voltage; the bus schema has no nominal voltage.Coupling with physics (architecture.md §8.1): speed prediction with the current and the rotor speed advanced together, the startup check on H/τm, and the rotor inertia added to the joint’s armature (
applyRotorInertia, called by the server).Current-loop bandwidth is capped at 1/dt with a warning: a discrete loop faster than its step diverges. (§4’s “warn when dt > 0.2 / bandwidth” would warn at the default 100 µs step for the default 1 kHz loop, which runs well; the cap is where it matters.)
Fidelity
fmu(formats.md §6 status): a motor withelec:behaviorModelis simulated by its FMU, the network feeding its bus;averagedignores the behaviour models.DC-DC converters (
ElectricalConverterAPI_1) are averaged regulators. On the output bus the converter is an ideal source atoutputVoltageinside the node equation, giving 0 tomaxOutputCurrent(no reverse flow); at the limit the bus sags and its loads drop at theirminVoltageor with its undervoltage trip. On the input bus it draws the output power overefficiency, one step late as loads do. It stops while its input bus is browned out. One converter per output bus. Signalsconverter/<c>/output_current,input_currentandloss_power;test_networkchecks regulation, the power drawn and the current limit.
elec:controlMode (as built): torque follows joint/<j>/torque_command; velocity follows
joint/<j>/velocity_command through a PI speed loop in the drive, critically damped on the joint’s
inertia (elec:velocityLoopBandwidth, illustrative), held by the current limit; voltage puts
joint/<j>/voltage_command on the winding, limited by the bus, with no current loop and so no current
limit. Those two commands are required: --joint-control writes them (Server::commandJoint, and
/joint_commands, whose effort field carries volts for a voltage motor), a plugin or --ros-topics
can too, and the built-in drive controllers and ros2_control, which write torques, stop the start with
MissingInput. On a prismatic joint the drive is linear: elec:gearRatio is motor radians per metre
(2π over a screw’s lead), and torque, speed and inertia at the joint are force, m/s and mass.
Checked against the closed forms: stall and no-load in voltage mode, steady speed under load in
velocity mode, on a hinge and a slide (server/test/test_motor_modes.cpp).
Not yet: battery FMUs and the rotor inertia in Jolt.
§8 check |
Status |
Test |
|---|---|---|
RL step response, d and q |
met (exact up to rounding) |
|
DC motor no-load speed, stall current, torque-speed line |
met, 0.5 % |
|
Coupled motor + inertia |
met, < 2 % RMS in speed and current against a monolithic 1 µs solution, inertias 6e-7 to 1e-2 kg·m², no growth; and (v0.4) the sample quadcopter’s dq drive with the network at 50 µs on 1e-5 and 9e-5 kg·m² rotors |
|
Battery ECM pulse |
closed form met exactly; against the LG HG2 HPPC pulses, one fitted parameter set: 5.4 to 6.2 mV RMS on held-out blocks from 46 to 89 % state of charge, 21.5 mV at 24 % (not met: r0 and the OCV slope rise below about 35 %; a state-of-charge-dependent r0 is the next step). 25 °C only |
|
Battery ECM drive cycles |
against the LG HG2 UDDS, US06 and LA92 cycles at 25 °C from full charge, r0 and RC pairs fitted to UDDS only: LA92 11.7 mV and US06 20.1 mV RMS above 35 % state of charge (unseen; US06 0.1 mV over the 20 mV, not met). The pulse fit gives 21.7 and 67.8 mV: its slow pair is not seen by 10 s pulses. At 40, 10 and 0 °C US06 reads 39, 61 and 145 mV: no temperature dependence but r0’s |
|
Energy balance over a drive cycle |
met, 0.5 % |
|
Netlist round trip |
met: with a drive cycle sagging a weak pack’s bus by 2.4 V, ngspice’s bus voltage is within 0.05 % of the network’s (sag within 0.16 % RMS) |
|
Brownout scenario |
met |
|
Sim-vs-real |
owed: needs the bench recording (Q16) |
— |
10. Parts between buses (RFC 0010)¶
ElectricalBranchAPI_1 joins two buses with a resistor, a fuse (open from the step ∫I²dt reaches its rating, until the run restarts), a switch (branch/<b>/command above 0.5 is closed) or a diode (a forward drop and a resistance, open backward). Buses joined this way are solved together each step, by nodal analysis with the capacitors’ backward-Euler companions, dense with partial pivoting, repeating while a diode, a battery at its charge limit or a converter changes state. A bus with no branch keeps the single-bus solve, so nothing changes for it. Signals: branch/<b>/current, /voltage, /state, /loss_power. A bus behind a part starts at what reaches it with nothing drawn.
11. Hand check¶
tools/ci/check_electrical.py draws simple circuits and works each out three ways, independently:
a closed-form formula, ngspice on a netlist written by the script (not lagrange export), and a
Lagrange run of a robot imported with lagrange_import --overlay, once from an overlay file and
once from the netlist (formats.md §9.1), and once from a URDF’s <lagrange> block (§9.2). Lagrange must stay within 0.5 %
of the formula and ngspice within 0.1 %. It covers a battery port’s harness (wireResistance, in the bus’s solution and between the
battery’s terminals and the bus; the batteries’ other ports and loads’ and drives’ do not count), a resistive load, a constant-power load, an RC
pair’s transient, two batteries in parallel, the charge drained, and a PMSM or brushed motor
turning a flywheel. It does not cover switching, thermal effects, a sloped voltage curve, trips,
regeneration or converters.