Domain: weather¶
1. Scope and release¶
The state of the atmosphere and its effect on sensors and surfaces: air temperature, pressure,
humidity, mean wind, fog, rain, dust, sun. The weather module owns the environment signals
(env/*) that thermal, aerodynamics, sensors and rigid body read. Release: v0.5. A minimal
version that only publishes constant env/* values from WeatherAPI ships with v0.3 because
thermal needs air temperature.
2. Models per fidelity level¶
The module has effects switches (profile key) instead of a single fidelity ladder.
Effect |
Model |
Consumed by |
|---|---|---|
Atmosphere state |
Values from |
thermal, aerodynamics |
|
Extinction coefficient |
sensors |
|
Drop size distribution Marshall–Palmer |
sensors, rigid body |
|
Mie-regime extinction from mass concentration and median diameter using tabulated extinction efficiency; lens accumulation; a slow ingress counter per |
sensors |
|
|
rigid body, vehicle dynamics |
|
Per-sensor contamination state (0…1) that blurs and attenuates the image or the lidar window |
sensors |
The Marshall–Palmer parameters are in mixed units in the original paper. The implementation converts them to SI once, with the source cited in a comment and a unit test on the integrated rain rate.
3. Signals¶
// modules/weather — declare()
d.output({.name = "env/air_temperature", .type = SignalType::Scalar, .unit = units::K});
d.output({.name = "env/sky_temperature", .type = SignalType::Scalar, .unit = units::K});
d.output({.name = "env/pressure", .type = SignalType::Scalar, .unit = units::Pa});
d.output({.name = "env/relative_humidity", .type = SignalType::Scalar, .unit = units::one});
d.output({.name = "env/air_density", .type = SignalType::Scalar, .unit = units::kg_per_m3});
d.output({.name = "env/wind/mean", .type = SignalType::Vec3, .unit = units::m_per_s, .frame = "world_local"});
d.output({.name = "env/wind/velocity_field", .type = SignalType::Field3D, .unit = units::m_per_s});
d.output({.name = "env/solar_irradiance", .type = SignalType::Scalar, .unit = units::W_per_m2});
d.output({.name = "env/sun_direction", .type = SignalType::Vec3, .unit = units::one, .frame = "world_local"});
d.output({.name = "env/extinction/visible", .type = SignalType::Scalar, .unit = units::per_m});
d.output({.name = "env/extinction/nir_905", .type = SignalType::Scalar, .unit = units::per_m});
d.output({.name = "env/extinction/nir_1550", .type = SignalType::Scalar, .unit = units::per_m});
d.output({.name = "env/extinction/field", .type = SignalType::Field3D, .unit = units::per_m}); // fog/dust grid
d.output({.name = "env/rain_rate", .type = SignalType::Scalar, .unit = units::m_per_s});
d.output({.name = "env/radar_attenuation_77ghz", .type = SignalType::Scalar, .unit = units::per_m});
d.output({.name = "env/friction_scale", .type = SignalType::Scalar, .unit = units::one});
d.output({.name = "env/dust/concentration", .type = SignalType::Scalar, .unit = units::kg_per_m3}); // the air's own dust (particle_sensor)
d.output({.name = "env/dust/median_diameter", .type = SignalType::Scalar, .unit = units::m});
for (auto& s : world.instancesOf("SensorAPI_1"))
d.output({.name = fmt("sensor/{}/contamination", name(s)), .type = SignalType::Scalar, .unit = units::one});
The weather module has no inputs from other domains in v0.5. Wiper and washer actuators would be inputs later.
4. Step size¶
Default 50 ms. Environment values change slowly; sensor kernels sample the latest values.
5. Substitutes and contract¶
Contract: all env/* outputs above and sensor/{s}/contamination.
Profile token |
Kind |
Behaviour |
|---|---|---|
|
constant |
Temperature, pressure and humidity from the environment file if present, otherwise from the profile; a profile with neither fails validation. Zero wind, zero extinction, zero rain, |
|
replay |
From MCAP |
6. Placement¶
Feature |
Tier 0 |
Tier 1 |
Tier 2 |
|---|---|---|---|
State and scalar extinction |
CPU |
CPU |
CPU |
Per-ray attenuation and backscatter |
inside the CPU lidar path |
|
same kernel on ray-query results |
Camera fog and rain streaks |
CPU post-process at low resolution |
fragment/compute pass |
same |
NanoVDB extinction grid marching |
CPU, coarse steps |
GPU |
GPU |
7. Validation¶
Test |
Reference |
Tolerance |
|---|---|---|
Koschmieder and Beer–Lambert |
closed form |
exact to rounding |
Rain rate from the drop distribution |
integrate |
5 % |
Lidar range reduction in fog |
published lidar-in-fog chamber measurements (candidate: results from the European DENSE project and related papers; obtain data and check licenses) |
maximum detection range within 20 % for stated visibilities |
Lidar false returns in rain |
published rain-chamber statistics for 905 nm sensors |
return-rate order of magnitude and its trend with rain rate |
Camera contrast in fog |
contrast of a black/white target at distance vs Koschmieder |
5 % |
Wet friction |
tyre–road friction ranges from the literature for dry and wet asphalt |
within the published range; this is a range check, not a point validation |
Weather effects on sensors are statistical. Each validation states the quantity compared (detection range, return rate), not image similarity.
8. Status (v0.5)¶
lagrange_weather (modules/weather/): Weather and its clear substitute (Weather(true)).
The site (air temperature, pressure, relative humidity) has no defaults: from
--weather, aWeatherAPI_1prim or the profile’sweatherkeys (the profile wins; the temperature falls back to thermal’s ambient one). Without it the module does not run.Moist air density from Alduchov and Eskridge’s saturation vapour pressure (1996): the ICAO sea-level density within 5e-4 for dry air.
Fog: Koschmieder at 550 nm, the Kim model’s wavelength exponent for 905 and 1550 nm (TODO(verify) the q table against Kim, McArthur and Korevaar 2001).
Rain: Marshall–Palmer, extinction
π·N0/Λ³for drops much larger than the wavelength (checked against the integral). The distribution with Atlas’s fall speeds carries 5 to 18 % more rain than it was built from, the known looseness of the fit; the design’s 5 % target for that check is not met and the test states the measured spread.Dust: quartz spheres at the median diameter.
Wet friction and lens contamination: behavioural, time constants in
Weather.hpp.Sensors (
lagrange_sensors,WeatherEffects.hpp), when the weather runs:Lidar range by the lidar equation,
r·exp(σr) = R·(1 − c)at its wavelength (905 nm, or 1550 nm with thewavelengthsetting), R the clear-air max range against its reference target, c the window’s contamination.Fog clutter: the fog’s backscatter (lidar ratio 18.8 sr of water droplets at 905 nm, O’Connor et al. 2004, 5 ns pulse) seen through the receiver’s overlap, with a log-normal detection spread and a gain set so that half the beams of a 30 m lidar see clutter at 60 m visibility. Uncalibrated, TODO(verify) against fog-chamber data (DENSE); clutter sits about 2 m out.
Rain clutter: Marshall–Palmer’s drops of 0.5 mm and more within 2 m in a 5 mm beam: about 1 % of beams at 2 mm/h, 5 % at 25 mm/h.
Camera: Koschmieder’s veil from the depth image (sky all air light) and a haze for the lens.
Applied per beam on the CPU on every tier, after the cast: it is a few operations per beam, so the GPU kernel the placement table plans (
attenuate.slang) is not needed yet.
Fields (
lagrange_fields, NanoVDB): a fog grid (fog_field,weather:fogField: extinction, 1/m) adds its optical depth along each lidar beam up to the hit and each camera pixel’s ray (once per 8×8 pixels), and its value at the sensor to the clutter; a wind grid (wind_field,weather:windField: m/s) is the mean wind inside its bounds for link drag and, throughenv/wind/velocity, the rotors. The weather publishes them as Field3D buffers (env/extinction/field,env/wind/velocity_field). Samples:assets/fields/(synthetic, bylagrange_make_fields): a 10 m-visibility bank across the warehouse aisle hides the far wall from 109 of the front lidar’s 720 beams.Snow and ice (
snow_rate,snow_cover;lagrange --season winter): extinction 1/m per mm/h of 3.912e-3, illustrative (1 km at 1 mm/h; Rasmussen et al. 1999 find 3 to 10 times the spread between storms), lidar false returns as 3 times that rate of rain (illustrative), lens contamination, andenv/friction_scaleto 0.3 of dry on snow and 0.13 on ice (wet below freezing). Range-checked intest_weatheragainst table values, 0.20 to 0.35 for packed snow and about 0.10 for ice; not point validated. Tyres, MuJoCo and Jolt take it throughenv/friction_scale; traffic agents, being kinematic, drive and brake more gently and never skid. Lidar returns off a snow-covered surface keep the surface’s reflectivity.Not yet: radar attenuation, a weather time series, rain streaks in the camera. (Wet friction is applied by MuJoCo and Jolt through
env/friction_scale, and the viewer shows the field overlays, since v0.5.)Offline CFD:
lagrange_foam_to_vdbturns an OpenFOAM case’s cell velocities (ASCIIU, and the cell centresCfrompostProcess -func writeCellCentres) into a wind grid: the mean of the cells in each voxel (voxel k covers [k·h, (k + 1)·h) after--offset, so cells of size h aligned with the origin map one to one). It reads OpenFOAM’s files only; OpenFOAM is not a dependency.