edgeengine-aware 0.4.0__py3-none-any.whl

edgeengine_aware/indoor.py

@@ -0,0 +1,186 @@
+"""Domain *indoor air quality*: CO2 in a classroom or office, powered by an
+indoor photovoltaic cell.
+
+The hidden world is driven by one weekly **activity schedule** (people in the
+room). It raises the CO2 concentration through breathing and, at the same
+time, switches the lights on - which is where the node's energy comes from.
+Energy and information relevance therefore coincide: nights and weekends
+bring neither. This is the mirror image of the agricultural node (energy from
+the sun, information relevance from a slow soil process) and a good test of
+whether a policy has learned *energy-information trade-offs* rather than the
+solar day.
+
+Numbers are for a small sensor node with a low-power NDIR CO2 sensor: a
+cheap reading is a short single-shot measurement (~20 mJ), an accurate one a
+longer averaged acquisition (~150 mJ); the radio is BLE-like (sub-millijoule
+uplinks); the always-on consumption is 20 uW; the storage is a 60 J
+supercapacitor / small cell; the cell delivers ~140 uW under 500 lux.
+"""
+
+from __future__ import annotations
+
+import math
+
+import numpy as np
+
+from .config import IndoorAirConfig, IndoorLightConfig, QuantityConfig
+from .process import DAY_S, HOUR_S, ActivitySchedule, ProcessState
+
+
+class IndoorAirProcess:
+    """CO2 mass balance of a room driven by the occupancy schedule."""
+
+    def __init__(self, cfg: IndoorAirConfig, timestep_s: float, schedule: ActivitySchedule):
+        self.cfg = cfg
+        self.q: QuantityConfig = cfg.quantity()
+        self.dt = timestep_s
+        self.schedule = schedule
+        self._rng = np.random.default_rng()
+        self.ppm = cfg.outdoor_ppm
+        self.occupancy = 0.0
+        self.ach = cfg.ach_base
+        self.window_until_s: float | None = None
+        self.last_change = 0.0
+        self.event_occurred = False
+        self.window_events = 0
+
+    # -- lifecycle ----------------------------------------------------------------
+    def reset(self, rng: np.random.Generator, start_time_s: float) -> None:
+        c = self.cfg
+        self._rng = rng
+        self.ppm = float(rng.uniform(*c.initial_ppm_range))
+        self.occupancy = self.schedule.level(start_time_s)
+        self.ach = c.ach_hvac if self.occupancy > 0 else c.ach_base
+        self.window_until_s = None
+        self.last_change = 0.0
+        self.event_occurred = False
+        self.window_events = 0
+
+    # -- accessors ----------------------------------------------------------------
+    @property
+    def value(self) -> float:
+        return float(np.clip(self.q.to_normalised(self.ppm), 0.0, 1.0))
+
+    def zone(self, value: float | None = None) -> int:
+        return self.q.zone(self.value if value is None else value)
+
+    # -- dynamics -----------------------------------------------------------------
+    def step(self, time_s: float) -> ProcessState:
+        """Advance over [time_s, time_s + dt] (occupancy read at the start of the step)."""
+        c, rng, dt = self.cfg, self._rng, self.dt
+        prev_value = self.value
+        prev_zone = self.q.zone(prev_value)
+        occ = self.schedule.level(time_s)
+        self.occupancy = occ
+
+        # ventilation: HVAC follows the activity window; window openings are random
+        ach = c.ach_hvac if occ > 0.0 else c.ach_base
+        if self.window_until_s is not None and time_s >= self.window_until_s:
+            self.window_until_s = None
+        if occ > 0.0 and self.window_until_s is None and rng.random() < c.window_events_per_day * dt / (10.0 * HOUR_S):
+            self.window_until_s = time_s + c.window_duration_s
+            self.window_events += 1
+        if self.window_until_s is not None:
+            ach = max(ach, c.ach_window)
+        self.ach = ach
+
+        # exact solution of dC/dt = S - lambda (C - C_out) over the step
+        lam = ach / HOUR_S  # 1/s
+        source_ppm_s = c.co2_per_person_l_h * c.max_occupants * occ / (c.room_volume_m3 * 1000.0) * 1e6 / HOUR_S
+        steady = c.outdoor_ppm + source_ppm_s / lam
+        self.ppm = steady + (self.ppm - steady) * math.exp(-lam * dt)
+        self.ppm += rng.normal(0.0, c.process_noise_ppm)
+        self.ppm = max(c.outdoor_ppm * 0.95, self.ppm)
+
+        self.last_change = self.value - prev_value
+        crossed = self.q.zone(self.value) != prev_zone
+        self.event_occurred = abs(self.last_change) >= self.q.event_change_threshold or crossed
+        return self.state()
+
+    def state(self) -> ProcessState:
+        return ProcessState(
+            value=self.value,
+            last_step_change=self.last_change,
+            event_occurred=self.event_occurred,
+            zone=self.zone(),
+            aux={
+                "co2_ppm": self.ppm,
+                "occupancy": self.occupancy,
+                "air_changes_per_hour": self.ach,
+                "window_open": self.window_until_s is not None,
+                "window_events": self.window_events,
+            },
+        )
+
+
+class IndoorLightSource:
+    """Indoor PV harvesting: artificial light when the room is active plus
+    daylight through a window (0 for a windowless room).
+
+    Same interface as ``energy.SolarEnergySource``: ``reset``, ``update(t)``,
+    ``measured_power_w`` (noisy, node side), ``true_power_w``,
+    ``harvested_energy_j`` and ``daily_clearness`` (here: today's daylight factor).
+    """
+
+    def __init__(self, cfg: IndoorLightConfig, timestep_s: float, schedule: ActivitySchedule):
+        self.cfg = cfg
+        self.dt = timestep_s
+        self.schedule = schedule
+        self._rng = np.random.default_rng()
+        self._weather = 1.0
+        self._power_w = 0.0
+        self._measured_w = 0.0
+        self._lux = 0.0
+        self._day = -1
+        self._day_factor = 1.0
+
+    def reset(self, rng: np.random.Generator, start_time_s: float) -> None:
+        self._rng = rng
+        self._weather = 0.0
+        self._day = -1
+        self._day_factor = float(np.clip(rng.uniform(0.4, 1.0), 0.0, 1.0))
+        self.update(start_time_s)
+
+    def _daylight_shape(self, time_s: float) -> float:
+        c = self.cfg
+        h = (time_s % DAY_S) / HOUR_S
+        if h <= c.sunrise_hour or h >= c.sunset_hour:
+            return 0.0
+        return math.sin(math.pi * (h - c.sunrise_hour) / (c.sunset_hour - c.sunrise_hour))
+
+    def update(self, time_s: float) -> None:
+        c = self.cfg
+        day = int(time_s // DAY_S)
+        if day != self._day:  # a new day: draw its overall brightness
+            self._day_factor = float(np.clip(self._rng.uniform(0.4, 1.0), 0.0, 1.0))
+            self._day = day
+        rho = c.daylight_autocorr
+        self._weather = rho * self._weather + math.sqrt(max(0.0, 1 - rho**2)) * self._rng.normal(0.0, c.daylight_noise_std)
+        daylight = c.daylight_lux * self._daylight_shape(time_s) * float(np.clip(self._day_factor + self._weather, 0.0, 1.0))
+        lights = c.artificial_lux if self.schedule.level(time_s) > c.lights_threshold else 0.0
+        self._lux = lights + daylight
+        self._power_w = c.cell_power_w_at_ref * self._lux / c.reference_lux * c.efficiency
+        noise = 1.0 + self._rng.normal(0.0, c.measurement_noise_std)
+        self._measured_w = max(0.0, self._power_w * noise)
+
+    # -- EnergySource protocol ------------------------------------------------------
+    def measured_power_w(self) -> float:
+        return self._measured_w
+
+    # -- simulator-only ---------------------------------------------------------------
+    def true_power_w(self) -> float:
+        return self._power_w
+
+    def harvested_energy_j(self) -> float:
+        return self._power_w * self.dt
+
+    @property
+    def illuminance_lux(self) -> float:
+        return self._lux
+
+    @property
+    def daily_clearness(self) -> float:
+        return self._day_factor
+
+
+__all__ = ["IndoorAirProcess", "IndoorLightSource"]

edgeengine_aware/industrial.py

@@ -0,0 +1,192 @@
+"""Domain *industrial condition monitoring*: the bearing temperature of a
+motor, powered by a thermoelectric generator (TEG) on the warm casing.
+
+The hidden world is driven by the **shift schedule** (machine load). Running
+heats the bearing - which is what the TEG harvests - and wears it; a random
+*fault onset* accelerates the wear, the temperature drifts towards the alarm
+thresholds, and maintenance eventually restores the bearing. Energy and
+information are coupled through the same physical variable: the node harvests
+most exactly when the machine runs hot, and a fault makes it run hotter still,
+but with the thermal inertia of the casing (tens of minutes) and nothing at
+all over a cold weekend.
+
+Numbers: a 45 K steady-state rise at full load, a 45-minute thermal time
+constant, a 30x30 mm TEG module giving ~1.2 mW electrical at 30 K before the
+converter (~1.6 mW after it at full-load temperature), a 120 J storage, a
+LoRa-like radio; sensing is a cheap temperature reading (50 mJ) or a vibration burst
+with on-board FFT (0.5 J).
+"""
+
+from __future__ import annotations
+
+import math
+
+import numpy as np
+
+from .config import IndustrialConfig, QuantityConfig, ThermoelectricConfig
+from .process import DAY_S, HOUR_S, ActivitySchedule, ProcessState
+
+
+class BearingProcess:
+    """Thermal model of a motor bearing with slow wear, fault onsets and maintenance."""
+
+    def __init__(self, cfg: IndustrialConfig, timestep_s: float, schedule: ActivitySchedule):
+        self.cfg = cfg
+        self.q: QuantityConfig = cfg.quantity()
+        self.dt = timestep_s
+        self.schedule = schedule
+        self._rng = np.random.default_rng()
+        self.temperature_c = cfg.ambient_c
+        self.ambient_c = cfg.ambient_c
+        self.load = 0.0
+        self.health = 1.0
+        self.fault_active = False
+        self.maintenance_due_s: float | None = None
+        self.last_change = 0.0
+        self.event_occurred = False
+        self.fault_onsets = 0
+        self.maintenance_events = 0
+
+    # -- lifecycle ----------------------------------------------------------------
+    def reset(self, rng: np.random.Generator, start_time_s: float) -> None:
+        c = self.cfg
+        self._rng = rng
+        self.health = float(rng.uniform(*c.initial_health_range))
+        self.fault_active = False
+        self.maintenance_due_s = None
+        self.load = self.schedule.level(start_time_s)
+        self.ambient_c = self._ambient(start_time_s)
+        # start at the steady state of the current load (a node installed on a running or idle machine)
+        self.temperature_c = self.ambient_c + self._rise_c(self.load)
+        self.last_change = 0.0
+        self.event_occurred = False
+        self.fault_onsets = 0
+        self.maintenance_events = 0
+
+    # -- helpers ------------------------------------------------------------------
+    def _ambient(self, time_s: float) -> float:
+        c = self.cfg
+        h = (time_s % DAY_S) / HOUR_S
+        return c.ambient_c + c.ambient_amplitude_c * math.cos(2 * math.pi * (h - 15.0) / 24.0)
+
+    def _rise_c(self, load: float) -> float:
+        c = self.cfg
+        return c.temp_rise_full_load_c * load * (1.0 + c.fault_heat_gain * (1.0 - self.health))
+
+    @property
+    def value(self) -> float:
+        return float(np.clip(self.q.to_normalised(self.temperature_c), 0.0, 1.0))
+
+    def zone(self, value: float | None = None) -> int:
+        return self.q.zone(self.value if value is None else value)
+
+    # -- dynamics -----------------------------------------------------------------
+    def step(self, time_s: float) -> ProcessState:
+        c, rng, dt = self.cfg, self._rng, self.dt
+        prev_value = self.value
+        prev_zone = self.q.zone(prev_value)
+        prev_load = self.load
+        load = self.schedule.level(time_s)
+        self.load = load
+        t_next = time_s + dt
+
+        # wear and faults happen only while running
+        if load > 0.0:
+            hours = dt / HOUR_S * load
+            wear = (c.fault_wear_per_hour if self.fault_active else c.wear_per_hour) * hours
+            self.health = max(0.0, self.health - wear)
+            if not self.fault_active and rng.random() < c.fault_onsets_per_day * dt / (16.0 * HOUR_S):
+                self.fault_active = True
+                self.fault_onsets += 1
+
+        # maintenance: scheduled some time after the temperature exceeds the critical threshold
+        if self.maintenance_due_s is None and self.q.beyond_critical(prev_value):
+            self.maintenance_due_s = time_s + float(rng.exponential(c.maintenance_delay_mean_s))
+        maintenance = False
+        if self.maintenance_due_s is not None and t_next >= self.maintenance_due_s:
+            self.health = 1.0
+            self.fault_active = False
+            self.maintenance_due_s = None
+            self.maintenance_events += 1
+            maintenance = True
+
+        # first-order thermal response towards the steady state of the current load
+        self.ambient_c = self._ambient(t_next)
+        target = self.ambient_c + self._rise_c(load)
+        alpha = 1.0 - math.exp(-dt / c.thermal_time_constant_s)
+        self.temperature_c += alpha * (target - self.temperature_c) + rng.normal(0.0, c.process_noise_c)
+
+        self.last_change = self.value - prev_value
+        crossed = self.q.zone(self.value) != prev_zone
+        started_or_stopped = (prev_load == 0.0) != (load == 0.0)
+        self.event_occurred = abs(self.last_change) >= self.q.event_change_threshold or crossed or started_or_stopped or maintenance
+        return self.state()
+
+    def state(self) -> ProcessState:
+        return ProcessState(
+            value=self.value,
+            last_step_change=self.last_change,
+            event_occurred=self.event_occurred,
+            zone=self.zone(),
+            aux={
+                "temperature_c": self.temperature_c,
+                "ambient_c": self.ambient_c,
+                "load": self.load,
+                "health": self.health,
+                "fault_active": self.fault_active,
+                "fault_onsets": self.fault_onsets,
+                "maintenance_events": self.maintenance_events,
+            },
+        )
+
+
+class ThermoelectricSource:
+    """TEG harvesting from the casing-to-ambient temperature difference of a
+    :class:`BearingProcess`. Same interface as ``energy.SolarEnergySource``."""
+
+    def __init__(self, cfg: ThermoelectricConfig, timestep_s: float, process: BearingProcess):
+        self.cfg = cfg
+        self.dt = timestep_s
+        self.process = process
+        self._rng = np.random.default_rng()
+        self._power_w = 0.0
+        self._measured_w = 0.0
+        self._dt_c = 0.0
+
+    def reset(self, rng: np.random.Generator, start_time_s: float) -> None:
+        self._rng = rng
+        self.update(start_time_s)
+
+    def update(self, time_s: float) -> None:
+        c = self.cfg
+        dt_c = max(0.0, self.process.temperature_c - self.process.ambient_c)
+        self._dt_c = dt_c
+        if dt_c < c.min_dt_c:
+            self._power_w = 0.0
+        else:
+            self._power_w = c.power_w_at_ref_dt * (dt_c / c.reference_dt_c) ** 2 * c.efficiency
+        noise = 1.0 + self._rng.normal(0.0, c.measurement_noise_std)
+        self._measured_w = max(0.0, self._power_w * noise)
+
+    # -- EnergySource protocol ------------------------------------------------------
+    def measured_power_w(self) -> float:
+        return self._measured_w
+
+    # -- simulator-only ---------------------------------------------------------------
+    def true_power_w(self) -> float:
+        return self._power_w
+
+    def harvested_energy_j(self) -> float:
+        return self._power_w * self.dt
+
+    @property
+    def temperature_difference_c(self) -> float:
+        return self._dt_c
+
+    @property
+    def daily_clearness(self) -> float:
+        """Stand-in for the solar clearness: the machine load of the current step."""
+        return float(self.process.load)
+
+
+__all__ = ["BearingProcess", "ThermoelectricSource"]

edgeengine_aware/interfaces.py

@@ -0,0 +1,171 @@
+"""Hardware abstraction layer of EdgeEngine AWARE.
+
+The policy never talks to these objects directly; the *node controller*
+(simulated by ``env.py``, or a real firmware loop as sketched in
+``deployment.py``) does. Each protocol is deliberately tiny so that it can be
+implemented by
+
+* a stochastic model (this package: ``energy.py``, ``sensing.py``, ...),
+* a driver on a microcontroller (ADC, fuel gauge, sensor driver, radio stack),
+* a replay of recorded traces (``traces.py``: irradiance and field traces;
+  a trace-driven ``Sensor`` / ``Radio`` would follow the same pattern).
+
+Only *measurable* quantities cross these interfaces. Hidden ground truth
+(true soil moisture, future irradiance, ...) stays inside the simulated
+implementations and is only exposed through explicit ``ground_truth()`` style
+accessors used for reward, evaluation and rendering.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Protocol, runtime_checkable
+
+
+# ---------------------------------------------------------------------------
+# Data records exchanged between subsystems
+# ---------------------------------------------------------------------------
+@dataclass(frozen=True)
+class Measurement:
+    """A value acquired by the node from a sensor."""
+
+    value: float
+    """Measured quantity (moisture units, normalised to field capacity)."""
+
+    timestamp_s: float
+    """Node clock time at which the measurement was taken [s]."""
+
+    level: int
+    """Sensing level that produced it (1 = low-cost, 2 = high-quality)."""
+
+    noise_std: float
+    """Nominal standard deviation of the measurement error (from the sensor
+    datasheet / hardware profile). Used as a *quality tag*, it is not the
+    realised error."""
+
+
+@dataclass(frozen=True)
+class Packet:
+    """Payload of one uplink: the latest measurement plus its age."""
+
+    measurement: Measurement
+    sent_at_s: float
+
+    @property
+    def measurement_age_s(self) -> float:
+        return self.sent_at_s - self.measurement.timestamp_s
+
+
+@dataclass(frozen=True)
+class TxResult:
+    """Outcome of one uplink attempt as seen by the node."""
+
+    acked: bool
+    """Whether an acknowledgement was received."""
+
+    margin_db: float | None = None
+    """Link margin of the *used mode* as measured from the ACK (SNR above the
+    demodulation floor), or None when there was no ACK. A LoRaWAN node gets
+    this from the downlink SNR/RSSI or from a LinkCheckAns."""
+
+
+# ---------------------------------------------------------------------------
+# Hardware-facing protocols
+# ---------------------------------------------------------------------------
+@runtime_checkable
+class Clock(Protocol):
+    """Time source of the node (RTC or monotonic timer)."""
+
+    def now_s(self) -> float: ...
+
+    def time_of_day_s(self) -> float:
+        """Seconds since local midnight, in [0, 86400)."""
+        ...
+
+
+@runtime_checkable
+class EnergyStorage(Protocol):
+    """Battery / supercapacitor with a fuel gauge."""
+
+    def capacity_j(self) -> float: ...
+
+    def energy_j(self) -> float:
+        """Currently stored energy [J] as reported by the gauge."""
+        ...
+
+
+@runtime_checkable
+class EnergySource(Protocol):
+    """Harvesting subsystem with a power/current monitor."""
+
+    def measured_power_w(self) -> float:
+        """Average harvesting power over the interval that just elapsed [W],
+        i.e. the energy integrated by the harvester monitor since the
+        previous wake-up divided by the interval. Never a forecast."""
+        ...
+
+
+@runtime_checkable
+class Sensor(Protocol):
+    """Environmental sensor with selectable acquisition modes."""
+
+    def read(self, level: int, now_s: float) -> Measurement:
+        """Acquire a measurement at the requested level (>= 1)."""
+        ...
+
+    def energy_cost_j(self, level: int) -> float:
+        """Nominal energy of an acquisition at ``level`` [J]."""
+        ...
+
+    def noise_std(self, level: int) -> float:
+        """Nominal measurement noise at ``level`` (quality tag)."""
+        ...
+
+
+@runtime_checkable
+class Radio(Protocol):
+    """Low-power long-range uplink with selectable modes (spreading factor / power)."""
+
+    def transmit(self, packet: Packet, mode: int) -> TxResult:
+        """Send a packet with ``modes[mode]``. Energy is consumed regardless of
+        the outcome. On a link without confirmations ``acked`` is meaningless
+        and the controller ignores it (``NodeProfile.ack_available``)."""
+        ...
+
+    def tx_energy_j(self, mode: int) -> float:
+        """Nominal energy of one transmission attempt in ``mode`` [J]."""
+        ...
+
+    def n_modes(self) -> int: ...
+
+
+@runtime_checkable
+class RemoteApplication(Protocol):
+    """Application-side endpoint as seen from the node.
+
+    On a real system the node only sees the *priority* the application sends
+    back (downlink). Delivery of data happens through the ``Radio``."""
+
+    def priority(self) -> int:
+        """Current information priority requested by the application:
+        0 = routine, 1 = elevated, 2 = urgent."""
+        ...
+
+
+# ---------------------------------------------------------------------------
+# Policy protocol (independent from Gymnasium)
+# ---------------------------------------------------------------------------
+@runtime_checkable
+class Policy(Protocol):
+    """Anything that maps a policy observation to an action.
+
+    ``observation`` is the float32 vector produced by
+    ``observation.ObservationBuilder``; the returned action is the
+    ``(sensing_level, transmit)`` pair encoded as in ``actions.py``.
+    """
+
+    def act(self, observation: Any) -> Any: ...
+
+    def reset(self) -> None:
+        """Clear any internal state at the start of an episode."""
+        ...

edgeengine_aware/metrics.py

@@ -0,0 +1,131 @@
+"""Episode-level metrics and a lightweight step logger.
+
+``EpisodeMetrics`` is updated by the environment at every step and returned
+in ``info["metrics"]`` (as a dict) on every step, so it is always available -
+also when an episode is cut short. ``EpisodeLog`` stores per-step arrays for
+plotting (used by the renderer and the notebook).
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+
+
+@dataclass
+class EpisodeMetrics:
+    steps: int = 0
+    total_harvested_energy_j: float = 0.0
+    total_consumed_energy_j: float = 0.0
+    baseline_energy_j: float = 0.0
+    sensing_energy_j: float = 0.0
+    communication_energy_j: float = 0.0
+    wasted_harvest_energy_j: float = 0.0
+    n_sensing: int = 0
+    n_high_quality_sensing: int = 0
+    n_transmissions: int = 0
+    n_successful_transmissions: int = 0
+    transmissions_per_mode: dict[int, int] = field(default_factory=dict)
+    deliveries_per_mode: dict[int, int] = field(default_factory=dict)
+    n_rejected_actions: int = 0
+    battery_depletion_events: int = 0
+    steps_low_battery: int = 0
+    _soc_sum: float = 0.0
+    min_battery_soc: float = 1.0
+    _aoi_sum_s: float = 0.0
+    max_aoi_s: float = 0.0
+    total_application_utility: float = 0.0
+    total_reward: float = 0.0
+    reward_components: dict[str, float] = field(default_factory=dict)
+
+    # -- derived --------------------------------------------------------------
+    @property
+    def average_battery_soc(self) -> float:
+        return self._soc_sum / self.steps if self.steps else 0.0
+
+    @property
+    def average_aoi_s(self) -> float:
+        return self._aoi_sum_s / self.steps if self.steps else 0.0
+
+    @property
+    def fraction_low_battery(self) -> float:
+        return self.steps_low_battery / self.steps if self.steps else 0.0
+
+    @property
+    def delivery_ratio(self) -> float:
+        return self.n_successful_transmissions / self.n_transmissions if self.n_transmissions else 0.0
+
+    def as_dict(self) -> dict:
+        d = {k: v for k, v in asdict(self).items() if not k.startswith("_")}
+        d.update(
+            average_battery_soc=self.average_battery_soc,
+            average_aoi_s=self.average_aoi_s,
+            average_aoi_h=self.average_aoi_s / 3600.0,
+            max_aoi_h=self.max_aoi_s / 3600.0,
+            fraction_low_battery=self.fraction_low_battery,
+            delivery_ratio=self.delivery_ratio,
+        )
+        return d
+
+    def summary(self) -> str:
+        d = self.as_dict()
+        keys = [
+            ("total_reward", "{:.2f}"),
+            ("total_application_utility", "{:.2f}"),
+            ("total_harvested_energy_j", "{:.1f} J"),
+            ("total_consumed_energy_j", "{:.1f} J"),
+            ("baseline_energy_j", "{:.1f} J"),
+            ("sensing_energy_j", "{:.1f} J"),
+            ("communication_energy_j", "{:.1f} J"),
+            ("wasted_harvest_energy_j", "{:.1f} J"),
+            ("n_sensing", "{}"),
+            ("n_high_quality_sensing", "{}"),
+            ("n_transmissions", "{}"),
+            ("n_successful_transmissions", "{}"),
+            ("transmissions_per_mode", "{}"),
+            ("delivery_ratio", "{:.2f}"),
+            ("n_rejected_actions", "{}"),
+            ("average_battery_soc", "{:.3f}"),
+            ("min_battery_soc", "{:.3f}"),
+            ("fraction_low_battery", "{:.3f}"),
+            ("battery_depletion_events", "{}"),
+            ("average_aoi_h", "{:.2f} h"),
+            ("max_aoi_h", "{:.2f} h"),
+        ]
+        width = max(len(k) for k, _ in keys)
+        return "\n".join(f"{k:<{width}} : {fmt.format(d[k])}" for k, fmt in keys)
+
+
+@dataclass
+class EpisodeLog:
+    """Per-step history for plotting."""
+
+    time_s: list[float] = field(default_factory=list)
+    soc: list[float] = field(default_factory=list)
+    harvest_power_w: list[float] = field(default_factory=list)
+    harvested_energy_j: list[float] = field(default_factory=list)
+    true_moisture: list[float] = field(default_factory=list)  # normalised monitored quantity (any domain)
+    measured_moisture: list[float] = field(default_factory=list)  # nan when no measurement stored
+    app_moisture: list[float] = field(default_factory=list)  # nan when nothing received yet
+    sensing_level: list[int] = field(default_factory=list)
+    tx_attempt: list[int] = field(default_factory=list)
+    tx_mode: list[int] = field(default_factory=list)  # -1 when no transmission
+    tx_success: list[int] = field(default_factory=list)
+    path_loss_db: list[float] = field(default_factory=list)
+    aoi_s: list[float] = field(default_factory=list)
+    priority: list[int] = field(default_factory=list)
+    reward: list[float] = field(default_factory=list)
+    utility: list[float] = field(default_factory=list)
+    temperature_c: list[float] = field(default_factory=list)  # domain extra (air / bearing temperature)
+    humidity: list[float] = field(default_factory=list)  # domain extra (humidity / occupancy / load)
+
+    def append(self, **kwargs) -> None:
+        for k, v in kwargs.items():
+            getattr(self, k).append(v)
+
+    @property
+    def true_value(self) -> list[float]:
+        """Normalised monitored quantity (``true_moisture`` is the historical name)."""
+        return self.true_moisture
+
+    def __len__(self) -> int:
+        return len(self.time_s)