edgeengine-aware 0.4.0__py3-none-any.whl

edgeengine_aware/__init__.py

@@ -0,0 +1,93 @@
+"""EdgeEngine AWARE - application- and energy-aware simulation environment
+for reinforcement learning in energy-harvesting Edge IoT systems.
+
+Quick start::
+
+    import gymnasium as gym
+    import edgeengine_aware  # registers "EdgeEngineAware-v0"
+
+    env = gym.make("EdgeEngineAware-v0")
+    obs, info = env.reset(seed=0)
+    obs, reward, terminated, truncated, info = env.step(env.action_space.sample())
+"""
+
+from __future__ import annotations
+
+__version__ = "0.4.0"
+
+from gymnasium.envs.registration import register
+
+from .actions import Action, decode_action, describe_action, encode_action, flatten_action, unflatten_action
+from .config import (
+    AgricultureConfig,
+    ApplicationConfig,
+    CommunicationConfig,
+    DomainRandomizationConfig,
+    EdgeEngineAwareConfig,
+    EnergyStorageConfig,
+    HarvestingConfig,
+    MCUConfig,
+    ObservationConfig,
+    RewardConfig,
+    SensingConfig,
+    TimeConfig,
+    default_config,
+)
+from .env import EdgeEngineAwareEnv
+from .interfaces import Policy
+from .metrics import EpisodeMetrics
+from .observation import OBSERVATION_FIELDS, NodeProfile, NodeState, ObservationBuilder
+from .policies import AlwaysOnPolicy, PeriodicPolicy, RandomPolicy, RuleBasedParams, RuleBasedPolicy, run_episode
+from .domains import DOMAINS, DOMAIN_NAMES, domain_config
+from .scenarios import SCENARIOS, get_scenario, scenario_names
+from .traces import Trace, TraceDrivenEnv
+
+register(
+    id="EdgeEngineAware-v0",
+    entry_point="edgeengine_aware.env:EdgeEngineAwareEnv",
+    max_episode_steps=None,  # the environment truncates itself at config.time.max_steps
+)
+
+__all__ = [
+    "__version__",
+    "EdgeEngineAwareEnv",
+    "EdgeEngineAwareConfig",
+    "default_config",
+    "TimeConfig",
+    "EnergyStorageConfig",
+    "MCUConfig",
+    "HarvestingConfig",
+    "SensingConfig",
+    "CommunicationConfig",
+    "AgricultureConfig",
+    "ApplicationConfig",
+    "RewardConfig",
+    "ObservationConfig",
+    "DomainRandomizationConfig",
+    "Policy",
+    "RuleBasedPolicy",
+    "RuleBasedParams",
+    "RandomPolicy",
+    "PeriodicPolicy",
+    "AlwaysOnPolicy",
+    "run_episode",
+    "SCENARIOS",
+    "get_scenario",
+    "scenario_names",
+    "DOMAINS",
+    "DOMAIN_NAMES",
+    "domain_config",
+    "Trace",
+    "TraceDrivenEnv",
+    "EpisodeMetrics",
+    "ObservationBuilder",
+    "OBSERVATION_FIELDS",
+    "NodeProfile",
+    "NodeState",
+    "Action",
+    "encode_action",
+    "decode_action",
+    "flatten_action",
+    "unflatten_action",
+    "describe_action",
+]

edgeengine_aware/actions.py

@@ -0,0 +1,194 @@
+"""Action encoding shared by the simulator and the deployment runtime.
+
+The action is a pair ``(sensing_level, transmit)``:
+
+============  =====  =========================================================
+component     value  meaning on the hardware
+============  =====  =========================================================
+sensing_level   0    keep the previous measurement (sensor stays powered off)
+                1    low-cost acquisition (single sample, short warm-up)
+                2    high-quality acquisition (averaging, longer warm-up)
+transmit        0    radio stays off
+                k    transmit the latest *stored* measurement with radio mode
+                     ``k - 1`` (k = 1..n_modes; default modes: 1 fast, 2 standard,
+                     3 robust)
+============  =====  =========================================================
+
+Gymnasium represents it as ``MultiDiscrete([3, 1 + n_modes])``; on a
+microcontroller it is two ``uint8`` values or a single flat index
+``sensing_level * (1 + n_modes) + transmit`` (see ``flatten_action``). With a
+single radio mode the encoding reduces to the binary ``MultiDiscrete([3, 2])``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+N_SENSING_LEVELS = 3
+DEFAULT_N_MODES = 3
+N_TRANSMIT_OPTIONS = 1 + DEFAULT_N_MODES
+N_FLAT_ACTIONS = N_SENSING_LEVELS * N_TRANSMIT_OPTIONS
+ACTION_NVEC = (N_SENSING_LEVELS, N_TRANSMIT_OPTIONS)
+
+SENSE_NONE, SENSE_LOW, SENSE_HIGH = 0, 1, 2
+TX_NO = 0
+TX_YES = 2
+"""Default transmit value used by the simple policies: the *standard* mode
+(mode index 1) of the default three-mode radio."""
+
+
+def action_nvec(n_modes: int = DEFAULT_N_MODES) -> tuple[int, int]:
+    """``MultiDiscrete`` sizes for a radio with ``n_modes`` transmission modes."""
+    return (N_SENSING_LEVELS, 1 + int(n_modes))
+
+
+def n_flat_actions(n_modes: int = DEFAULT_N_MODES) -> int:
+    return N_SENSING_LEVELS * (1 + int(n_modes))
+
+
+@dataclass(frozen=True)
+class Action:
+    """Decoded, validated action."""
+
+    sensing_level: int
+    transmit: int
+    """0 = no transmission, k >= 1 = transmit with radio mode k - 1."""
+
+    def __post_init__(self) -> None:
+        if not 0 <= self.sensing_level < N_SENSING_LEVELS:
+            raise ValueError(f"sensing_level must be in [0, {N_SENSING_LEVELS}), got {self.sensing_level}")
+        if self.transmit < 0:
+            raise ValueError(f"transmit must be >= 0, got {self.transmit}")
+
+    @property
+    def transmits(self) -> bool:
+        return self.transmit > 0
+
+    @property
+    def mode(self) -> int:
+        """Radio mode index (valid only when ``transmits``)."""
+        return self.transmit - 1
+
+    def to_array(self) -> np.ndarray:
+        return np.array([self.sensing_level, self.transmit], dtype=np.int64)
+
+
+def decode_action(action, n_modes: int | None = None) -> Action:
+    """Convert a MultiDiscrete array-like (or an ``Action``) into an ``Action``.
+    With ``n_modes`` the transmit component is range-checked."""
+    a = action if isinstance(action, Action) else None
+    if a is None:
+        arr = np.asarray(action).reshape(-1)
+        if arr.shape[0] != 2:
+            raise ValueError(f"expected an action with 2 components, got shape {arr.shape}")
+        a = Action(int(arr[0]), int(arr[1]))
+    if n_modes is not None and a.transmit > n_modes:
+        raise ValueError(f"transmit must be in [0, {n_modes}], got {a.transmit}")
+    return a
+
+
+def encode_action(sensing_level: int, transmit: int) -> np.ndarray:
+    """Build the MultiDiscrete array from its two components."""
+    return Action(sensing_level, transmit).to_array()
+
+
+def flatten_action(action, n_modes: int = DEFAULT_N_MODES) -> int:
+    """Map ``(sensing_level, transmit)`` to a single index:
+    ``index = sensing_level * (1 + n_modes) + transmit``."""
+    a = decode_action(action, n_modes)
+    return a.sensing_level * (1 + n_modes) + a.transmit
+
+
+def unflatten_action(index: int, n_modes: int = DEFAULT_N_MODES) -> np.ndarray:
+    """Inverse of :func:`flatten_action`."""
+    n_tx = 1 + n_modes
+    if not 0 <= index < N_SENSING_LEVELS * n_tx:
+        raise ValueError(f"flat action index must be in [0, {N_SENSING_LEVELS * n_tx}), got {index}")
+    return encode_action(index // n_tx, index % n_tx)
+
+
+def describe_action(action, mode_names: tuple[str, ...] | None = None) -> str:
+    a = decode_action(action)
+    sense = ("no sensing", "low-cost sensing", "high-quality sensing")[a.sensing_level]
+    if not a.transmits:
+        tx = "no transmission"
+    elif mode_names is not None and a.mode < len(mode_names):
+        tx = f"transmit ({mode_names[a.mode]})"
+    else:
+        tx = f"transmit (mode {a.mode})"
+    return f"{sense} / {tx}"
+
+
+# ---------------------------------------------------------------------------
+# Energy-feasibility rule (shared by simulator and firmware loop)
+# ---------------------------------------------------------------------------
+@dataclass(frozen=True)
+class ExecutionPlan:
+    """Which parts of a requested action the node will actually execute."""
+
+    sensing_level: int
+    """Executed sensing level (0 if rejected or not requested)."""
+
+    transmit: bool
+    """Whether a transmission will be executed."""
+
+    mode: int
+    """Radio mode of the transmission (-1 when none)."""
+
+    sensing_energy_j: float
+    tx_energy_j: float
+    rejected: tuple[str, ...]
+    """Reasons of rejected sub-actions, e.g. 'sensing:insufficient_energy'."""
+
+
+def plan_execution(
+    action,
+    *,
+    stored_energy_j: float,
+    baseline_energy_j: float,
+    reserve_energy_j: float,
+    sensing_energy_j: tuple[float, ...],
+    tx_energy_j: tuple[float, ...] | float,
+    has_measurement: bool,
+) -> ExecutionPlan:
+    """Apply the 'execute the feasible subset' rule.
+
+    The node first sets aside the baseline consumption of the coming interval
+    and the brown-out reserve; sensing is served first, then transmission.
+    A transmission with nothing to send (no stored measurement and no sensing
+    in this step) is rejected without spending energy. ``tx_energy_j`` is the
+    energy per radio mode (a scalar is treated as a single-mode radio).
+    """
+    tx_energies = (float(tx_energy_j),) if np.isscalar(tx_energy_j) else tuple(tx_energy_j)
+    a = decode_action(action, n_modes=len(tx_energies))
+    available = stored_energy_j - baseline_energy_j - reserve_energy_j
+    rejected: list[str] = []
+
+    level = a.sensing_level
+    sense_j = 0.0
+    if level != SENSE_NONE:
+        cost = sensing_energy_j[level]
+        if cost <= available:
+            sense_j = cost
+            available -= cost
+        else:
+            rejected.append("sensing:insufficient_energy")
+            level = SENSE_NONE
+
+    transmit = False
+    tx_j = 0.0
+    mode = -1
+    if a.transmits:
+        cost = tx_energies[a.mode]
+        if not has_measurement and level == SENSE_NONE:
+            rejected.append("transmit:no_measurement")
+        elif cost <= available:
+            transmit = True
+            tx_j = cost
+            mode = a.mode
+        else:
+            rejected.append("transmit:insufficient_energy")
+
+    return ExecutionPlan(level, transmit, mode, sense_j, tx_j, tuple(rejected))

edgeengine_aware/agriculture.py

@@ -0,0 +1,191 @@
+"""Hidden ground-truth model of the agricultural field.
+
+Everything in this module is *simulator-only*. The node never reads these
+variables directly; it can only sample them through a ``Sensor`` (which adds
+noise) and the reward/renderer use them for evaluation.
+
+Soil moisture ``theta`` is dimensionless (1 = field capacity). Its dynamics
+per step of length ``dt`` are
+
+    theta(t+1) = clip(theta(t) - ET(t) * dt + rain(t) + irrigation(t) + noise, 0, max)
+
+    ET(t) = et_rate_per_day / 86400 * (1 + et_temp_coeff * (T(t) - T_mean))
+            * ((1 - a) + a * (pi/2) * (24 / daylight_hours) * daylight_factor(t))
+                                                          with a = et_diurnal_amplitude
+
+(the factor (pi/2) * (24 / daylight_hours) makes the 24-hour mean of the
+modulation equal to 1, so ``et_rate_per_day`` is the actual mean daily ET at
+the reference temperature; with 12 h of daylight the factor is pi)
+
+Rain events follow a Poisson process; irrigation is applied by an external
+actor (the farmer's system) some random time after the *true* moisture drops
+below ``irrigation_trigger``. Temperature follows a daily cosine with AR(1)
+noise, and humidity is linearly anti-correlated with the temperature anomaly.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+import numpy as np
+
+from .config import AgricultureConfig
+
+DAY_S = 86400.0
+
+
+@dataclass
+class FieldState:
+    """Snapshot of the ground truth (privileged information)."""
+
+    soil_moisture: float
+    air_temperature_c: float
+    relative_humidity: float
+    last_step_change: float
+    """Change of soil moisture during the last step (positive after rain)."""
+    event_occurred: bool
+    """True if a rain/irrigation event or threshold crossing happened in the last step."""
+    zone: int
+    """0 = normal, 1 = warning (below warning_threshold), 2 = critical."""
+    rain_events: int = 0
+    irrigation_events: int = 0
+
+    # -- ProcessState-compatible view (see process.py) -------------------------
+    @property
+    def value(self) -> float:
+        return self.soil_moisture
+
+    @property
+    def aux(self) -> dict:
+        return {
+            "air_temperature_c": self.air_temperature_c,
+            "relative_humidity": self.relative_humidity,
+            "rain_events": self.rain_events,
+            "irrigation_events": self.irrigation_events,
+        }
+
+
+class FieldEnvironment:
+    """Stochastic soil / atmosphere simulator."""
+
+    def __init__(self, cfg: AgricultureConfig, timestep_s: float):
+        self.cfg = cfg
+        self.dt = timestep_s
+        self._rng = np.random.default_rng()
+        self.reset(self._rng, start_time_s=0.0)
+
+    # -- lifecycle ----------------------------------------------------------
+    def reset(self, rng: np.random.Generator, start_time_s: float) -> None:
+        c = self.cfg
+        self._rng = rng
+        if c.initial_moisture_range is not None:
+            self.moisture = float(rng.uniform(*c.initial_moisture_range))
+        else:
+            self.moisture = c.initial_moisture
+        self._temp_dev = 0.0
+        self.temperature = self._temperature_base(start_time_s)
+        self.humidity = c.humidity_mean
+        self.last_change = 0.0
+        self.event_occurred = False
+        self.irrigation_pending_s: float | None = None
+        self.rain_events = 0
+        self.irrigation_events = 0
+        self.total_rain = 0.0
+        self.total_irrigation = 0.0
+
+    # -- helpers ------------------------------------------------------------
+    def _temperature_base(self, time_s: float) -> float:
+        c = self.cfg
+        h = (time_s % DAY_S) / 3600.0
+        return c.temp_mean_c + c.temp_amplitude_c * math.cos(2 * math.pi * (h - c.temp_peak_hour) / 24.0)
+
+    def _daylight_factor(self, time_s: float) -> float:
+        """Half-sine daylight shape in [0, 1] (0 at night)."""
+        c = self.cfg
+        h = (time_s % DAY_S) / 3600.0
+        if not c.sunrise_hour < h < c.sunset_hour:
+            return 0.0
+        return math.sin(math.pi * (h - c.sunrise_hour) / (c.sunset_hour - c.sunrise_hour))
+
+    @property
+    def value(self) -> float:
+        """Normalised monitored value (the process interface of ``process.py``)."""
+        return self.moisture
+
+    def zone(self, moisture: float | None = None) -> int:
+        m = self.moisture if moisture is None else moisture
+        if m < self.cfg.critical_threshold:
+            return 2
+        if m < self.cfg.warning_threshold:
+            return 1
+        return 0
+
+    # -- dynamics -----------------------------------------------------------
+    def step(self, time_s: float) -> FieldState:
+        """Advance the field by one timestep starting at ``time_s``."""
+        c, rng, dt = self.cfg, self._rng, self.dt
+        prev = self.moisture
+        prev_zone = self.zone(prev)
+
+        # atmosphere
+        self._temp_dev = c.temp_autocorr * self._temp_dev + math.sqrt(max(0.0, 1 - c.temp_autocorr**2)) * rng.normal(
+            0.0, c.temp_noise_std
+        )
+        self.temperature = self._temperature_base(time_s) + self._temp_dev
+        self.humidity = float(
+            np.clip(
+                c.humidity_mean + c.humidity_temp_coeff * (self.temperature - c.temp_mean_c) + rng.normal(0.0, c.humidity_noise_std),
+                0.05,
+                1.0,
+            )
+        )
+
+        # evapotranspiration
+        et_per_s = c.et_rate_per_day / DAY_S * max(0.0, 1.0 + c.et_temp_coeff * (self.temperature - c.temp_mean_c))
+        # 24 h mean of daylight_factor = (daylight_h / 24) * (2 / pi); the prefactor
+        # below normalises the modulation to a mean of exactly 1 over the day.
+        daylight_h = c.sunset_hour - c.sunrise_hour
+        modulation = (math.pi / 2.0) * (24.0 / daylight_h) * self._daylight_factor(time_s)
+        et_per_s *= (1.0 - c.et_diurnal_amplitude) + c.et_diurnal_amplitude * modulation
+        delta = -et_per_s * dt
+
+        # rain (Poisson process)
+        n_rain = rng.poisson(c.rain_events_per_day * dt / DAY_S)
+        if n_rain > 0:
+            amount = float(sum(rng.uniform(*c.rain_amount_range) for _ in range(n_rain)))
+            delta += amount
+            self.rain_events += int(n_rain)
+            self.total_rain += amount
+
+        # external irrigation reacting to the true moisture with a random delay
+        if c.irrigation_enabled:
+            if self.irrigation_pending_s is None and prev < c.irrigation_trigger:
+                self.irrigation_pending_s = float(rng.exponential(c.irrigation_delay_mean_s))
+            if self.irrigation_pending_s is not None:
+                self.irrigation_pending_s -= dt
+                if self.irrigation_pending_s <= 0.0:
+                    delta += c.irrigation_amount
+                    self.irrigation_events += 1
+                    self.total_irrigation += c.irrigation_amount
+                    self.irrigation_pending_s = None
+
+        delta += rng.normal(0.0, c.process_noise_std)
+        self.moisture = float(np.clip(prev + delta, 0.0, c.max_moisture))
+        self.last_change = self.moisture - prev
+
+        crossed = self.zone(self.moisture) != prev_zone
+        self.event_occurred = abs(self.last_change) >= c.event_change_threshold or crossed
+        return self.state()
+
+    def state(self) -> FieldState:
+        return FieldState(
+            soil_moisture=self.moisture,
+            air_temperature_c=self.temperature,
+            relative_humidity=self.humidity,
+            last_step_change=self.last_change,
+            event_occurred=self.event_occurred,
+            zone=self.zone(),
+            rain_events=self.rain_events,
+            irrigation_events=self.irrigation_events,
+        )