Domain: thermal¶
1. Scope and release¶
Component temperatures from lumped thermal networks: heating from electrical losses, cooling by convection and radiation, solar load, and derating fed back to the electrical domain. Release: v0.3 together with electrical.
2. Models per fidelity level¶
Level |
Content |
|---|---|
|
One node per |
Stefan–Boltzmann constant σ = 5.670374419e-8 W·m⁻²·K⁻⁴ (CODATA 2018 exact value), named and
cited in code.
Integration: backward Euler on the linearised network (radiation linearised around the current temperature each step), solved as a small dense or sparse linear system. Unconditionally stable, so a 100 ms step is safe even for small nodes.
Derating: for a node with thermal:deratingStart (T1) and thermal:maxTemperature (T2),
derating = clamp((T2 − T) / (T2 − T1), 0, 1). At T ≥ T2 a fault flag is raised.
3. Signals¶
// modules/thermal/lumped — declare()
for (auto& n : world.instancesOf("ThermalAPI_1")) {
auto p = name(n);
// Heat sources: every loss_power signal whose prim is this node, discovered at wiring.
for (auto& src : lossSignalsOn(n)) // e.g. "motor/{p}/loss_power", "battery/{p}/loss_power"
d.input({.name = src, .type = SignalType::Scalar, .unit = units::W, .hold = Hold::WindowAverage});
d.output({.name = fmt("thermal/{}/temperature", p), .type = SignalType::Scalar, .unit = units::K});
d.output({.name = fmt("thermal/{}/derating", p), .type = SignalType::Scalar, .unit = units::one});
d.output({.name = fmt("thermal/{}/overtemp", p), .type = SignalType::Bool, .unit = units::one});
d.output({.name = fmt("thermal/{}/heat_flow_out", p), .type = SignalType::Scalar, .unit = units::W});
}
d.input({.name = "env/air_temperature", .type = SignalType::Scalar, .unit = units::K}); // weather
d.input({.name = "env/sky_temperature", .type = SignalType::Scalar, .unit = units::K, .optional = true});
d.input({.name = "env/solar_irradiance", .type = SignalType::Scalar, .unit = units::W_per_m2,
.optional = true, .defaultValue = 0.0});
d.input({.name = "env/sun_direction", .type = SignalType::Vec3, .unit = units::one, .optional = true});
for (BodyId b : bodiesWithThermalNodes())
d.input({.name = fmt("body/{}/airspeed", b), .type = SignalType::Scalar, .unit = units::m_per_s,
.optional = true, .defaultValue = 0.0}); // aerodynamics
4. Step size¶
Default 100 ms. Range 1 ms to 10 s.
5. Substitutes and contract¶
Contract: thermal/{p}/temperature and thermal/{p}/derating for every ThermalAPI prim.
Profile token |
Kind |
Behaviour |
|---|---|---|
|
constant |
Every node at the environment’s air temperature (or the profile’s |
|
replay |
Temperatures from MCAP |
The ambient temperature has no code default: with neither an environment file nor
ambient_temperature, profile loading fails (site parameter rule).
6. Placement¶
CPU on all tiers. The viewer’s thermal false-colour view maps node temperatures onto the prims that own them; that is a viewer shader, not a module.
7. Validation¶
Test |
Reference |
Tolerance |
|---|---|---|
Single node cooling |
closed-form exponential |
0.1 % |
Two-node network step |
closed-form two-pole response |
0.5 % |
Radiative equilibrium of a plate in sunlight |
closed form |
0.5 K |
Energy conservation |
sum of stored energy and flows |
0.1 % |
Motor heat run (with electrical) |
published motor thermal test with winding temperature rise at constant load, or a recorded bench test (Q16) |
within 3 K at steady state |
8. Status (v0.3)¶
lagrange_thermal (modules/thermal/): ThermalNetwork (lumped/, default step 100 ms) with
the network solver in Lumped.hpp, and the AmbientTemperature substitute. The schemas are in
schemas/thermal (ThermalAPI_1, ThermalLinkAPI_1). The sample AMR’s overlay gives the
motors, the battery and the chassis thermal nodes, with links to the chassis.
The server runs thermal when the robot has ThermalAPI_1 prims and the site’s ambient
temperature is known: the profile’s thermal.ambient_temperature or --ambient-temperature K.
Without one nothing stands in, and the electrical network uses its components’ reference
temperatures; the domain panel says why. --domain thermal=on without it is an error.
Choices made while implementing, beyond §2–§3:
Heat sources are found by name: every
<class>/<node>/loss_powerdeclared before the module, read withHold::WindowAverageso a 100 ms step sees the mean of the electrical network’s 100 µs losses.env/air_temperatureandenv/sky_temperatureare optional inputs whose default is the ambient temperature; a weather module will write them.env/solar_irradiancedefaults to 0.heat_flow_outis the node’s convection and radiation to the air and the sky (links and the sun not included), computed with the same linearisation as the step, so energy balances exactly.Not yet: airspeed (forced convection, with the aerodynamics domain) and the sun’s direction (the sun-facing area is taken as facing it).
§7 check |
Status |
Test |
|---|---|---|
Single node cooling |
met, 0.1 % |
|
Two-node network step |
met, 0.5 % |
|
Radiative equilibrium of a plate in sunlight |
met, 0.5 K |
|
Energy conservation |
met, every step to 1e-9 |
|
Motor heat run |
the closed-form steady state of a motor linked to the chassis is met ( |
— |