edgeengine-aware 0.4.0__py3-none-any.whl

edgeengine_aware/reward.py

@@ -0,0 +1,92 @@
+"""Reward computation with explicit, separately reported components.
+
+    reward = application_utility
+             - sensing_cost - communication_cost
+             - staleness_penalty - battery_penalty - depletion_penalty
+             - rejection_penalty - waste_penalty
+
+Scales (defaults, 7-day episode = 672 steps): the tracking utility is worth up
+to 0.1 * criticality (1..3) per step, i.e. ~100-140 per episode for a policy
+that keeps the application well informed; one high-quality sample + uplink
+costs 0.12; the staleness penalty saturates at lambda_stale * w_priority
+(0.05 / 0.10 / 0.20 per step) after tau_stale_s = 6 h - a policy that never
+transmits loses ~120 per episode to it; the battery penalty grows
+quadratically below ``safe_soc`` up to lambda_battery (0.5) per step at
+SoC = 0, plus lambda_depletion (2.0) at every step in which the node actually
+browns out. Energy penalties alone (~20 per episode for hourly high-quality
+reporting in the standard mode: 168 x 0.12) do not dominate:
+what makes energy binding is the battery penalty, which an always-on policy
+pays to the tune of several hundred per episode.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+
+from .config import RewardConfig
+
+
+@dataclass
+class RewardComponents:
+    application_utility: float = 0.0
+    sensing_cost: float = 0.0
+    communication_cost: float = 0.0
+    staleness_penalty: float = 0.0
+    battery_penalty: float = 0.0
+    depletion_penalty: float = 0.0
+    rejection_penalty: float = 0.0
+    waste_penalty: float = 0.0
+
+    @property
+    def total(self) -> float:
+        return (
+            self.application_utility
+            - self.sensing_cost
+            - self.communication_cost
+            - self.staleness_penalty
+            - self.battery_penalty
+            - self.depletion_penalty
+            - self.rejection_penalty
+            - self.waste_penalty
+        )
+
+    def as_dict(self) -> dict[str, float]:
+        d = asdict(self)
+        d["total"] = self.total
+        return d
+
+
+class RewardCalculator:
+    def __init__(self, cfg: RewardConfig):
+        self.cfg = cfg
+
+    def compute(
+        self,
+        *,
+        utility: float,
+        sensing_energy_j: float,
+        communication_energy_j: float,
+        aoi_s: float,
+        priority: int,
+        soc_after: float,
+        depleted: bool,
+        n_rejected: int,
+        wasted_energy_j: float,
+    ) -> RewardComponents:
+        c = self.cfg
+        w_prio = c.priority_weights[int(priority)]
+        staleness = c.lambda_stale * w_prio * min(aoi_s / c.tau_stale_s, 1.0)
+        if soc_after < c.safe_soc:
+            risk = ((c.safe_soc - soc_after) / c.safe_soc) ** 2
+        else:
+            risk = 0.0
+        return RewardComponents(
+            application_utility=utility,
+            sensing_cost=c.lambda_sense * sensing_energy_j / c.energy_ref_j,
+            communication_cost=c.lambda_tx * communication_energy_j / c.energy_ref_j,
+            staleness_penalty=staleness,
+            battery_penalty=c.lambda_battery * risk,
+            depletion_penalty=c.lambda_depletion if depleted else 0.0,
+            rejection_penalty=c.lambda_reject * n_rejected,
+            waste_penalty=c.lambda_waste * wasted_energy_j / c.energy_ref_j,
+        )

edgeengine_aware/rl.py

@@ -0,0 +1,368 @@
+"""Helpers for training and evaluating RL agents on EdgeEngine AWARE.
+
+Nothing here depends on a specific RL library except :class:`SB3Policy`, which
+only needs an object with a ``predict(obs, deterministic=True)`` method (the
+Stable-Baselines3 convention). Import of Stable-Baselines3 itself is left to
+the caller, so the core package stays dependency-light.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Iterable, Mapping
+
+import gymnasium as gym
+import numpy as np
+from gymnasium import spaces
+
+from .actions import flatten_action, n_flat_actions, unflatten_action
+from .env import EdgeEngineAwareEnv
+from .interfaces import Policy
+from .observation import OBSERVATION_FIELDS
+from .policies import run_episode
+from .scenarios import get_scenario, scenario_names
+
+
+# ---------------------------------------------------------------------------
+# Wrappers
+# ---------------------------------------------------------------------------
+class FlatActionWrapper(gym.ActionWrapper):
+    """Expose the ``MultiDiscrete([3, 1 + n_modes])`` action as ``Discrete(3 * (1 + n_modes))``.
+
+    ``flat = sensing_level * (1 + n_modes) + transmit`` (see ``actions.py``).
+    Needed by value-based agents such as DQN; PPO/A2C work on the
+    MultiDiscrete space directly.
+    """
+
+    def __init__(self, env: gym.Env):
+        super().__init__(env)
+        self.n_modes = int(env.action_space.nvec[1]) - 1
+        self.action_space = spaces.Discrete(n_flat_actions(self.n_modes))
+
+    def action(self, action):
+        return unflatten_action(int(action), self.n_modes)
+
+
+class MixedScenarioEnv(EdgeEngineAwareEnv):
+    """EdgeEngine AWARE environment that draws a *scenario* at every reset.
+
+    Training on a mixture of scenarios (plus domain randomisation inside each)
+    is the simplest way to obtain a policy that is robust to weather, storage
+    size, link quality and application behaviour, instead of one tuned to the
+    nominal configuration. The scenario of the current episode is reported in
+    ``info["scenario"]``.
+    """
+
+    def __init__(self, scenarios: Iterable[str], *, randomize: bool = True, render_mode: str | None = None):
+        self.scenario_names = list(scenarios)
+        if not self.scenario_names:
+            raise ValueError("at least one scenario name is required")
+        self._configs = {n: get_scenario(n, randomize=randomize) for n in self.scenario_names}
+        self.current_scenario = self.scenario_names[0]
+        super().__init__(self._configs[self.current_scenario], render_mode=render_mode)
+
+    def reset(self, *, seed: int | None = None, options: dict[str, Any] | None = None):
+        if seed is not None:  # seed the scenario draw as well, for reproducibility
+            super().reset(seed=seed)
+        self.current_scenario = self.scenario_names[int(self.np_random.integers(len(self.scenario_names)))]
+        self.base_config = self._configs[self.current_scenario]
+        obs, info = super().reset(seed=None, options=options)
+        info["scenario"] = self.current_scenario
+        return obs, info
+
+    def step(self, action):
+        obs, reward, terminated, truncated, info = super().step(action)
+        info["scenario"] = self.current_scenario
+        return obs, reward, terminated, truncated, info
+
+
+def make_env(scenario: str | Iterable[str] = "default", *, randomize: bool = False, flat_actions: bool = False, seed: int | None = None, render_mode: str | None = None) -> gym.Env:
+    """Build an environment for a named scenario, or for a mixture of scenarios
+    (``"mixed"`` = all of them, or an explicit list of names), optionally with
+    domain randomisation and flat actions. ``seed`` seeds the first reset."""
+    if isinstance(scenario, str) and (scenario == "mixed" or scenario.startswith("mixed:") or scenario == "all"):
+        # "mixed" = all agricultural scenarios (historical default), "mixed:<domain>" = one
+        # domain's scenarios, "all" = every scenario of every domain
+        scenario = scenario_names("all" if scenario == "all" else ("agriculture" if scenario == "mixed" else scenario.split(":", 1)[1]))
+    if isinstance(scenario, str):
+        env: gym.Env = EdgeEngineAwareEnv(get_scenario(scenario, randomize=randomize), render_mode=render_mode)
+    else:
+        env = MixedScenarioEnv(scenario, randomize=randomize, render_mode=render_mode)
+    if flat_actions:
+        env = FlatActionWrapper(env)
+    if seed is not None:
+        env.reset(seed=seed)
+    return env
+
+
+def make_env_fn(scenario: str | Iterable[str] = "default", *, randomize: bool = True, flat_actions: bool = False, seed: int = 0) -> Callable[[], gym.Env]:
+    """Factory usable with SB3 ``DummyVecEnv`` / ``SubprocVecEnv``."""
+
+    def _init() -> gym.Env:
+        return make_env(scenario, randomize=randomize, flat_actions=flat_actions, seed=seed)
+
+    return _init
+
+
+# ---------------------------------------------------------------------------
+# Policy adapter
+# ---------------------------------------------------------------------------
+class SB3Policy:
+    """Wrap a trained Stable-Baselines3 model as an EdgeEngine AWARE ``Policy``.
+
+    The adapter always returns the MultiDiscrete action array, undoing the flat
+    encoding when the model was trained with :class:`FlatActionWrapper`.
+    """
+
+    def __init__(self, model: Any, flat_actions: bool = False, deterministic: bool = True):
+        self.model = model
+        self.flat_actions = flat_actions
+        self.deterministic = deterministic
+        # number of radio modes, recovered from the model's action space
+        space = model.action_space
+        self.n_modes = (int(space.n) // 3 - 1) if flat_actions else int(space.nvec[1]) - 1
+        self.reset()
+
+    def reset(self) -> None:
+        self._state = None  # hidden state of a recurrent policy (RecurrentPPO); None for feed-forward models
+
+    def act(self, observation) -> np.ndarray:
+        action, self._state = self.model.predict(np.asarray(observation, dtype=np.float32), state=self._state, deterministic=self.deterministic)
+        if self.flat_actions:
+            return unflatten_action(int(np.asarray(action).reshape(-1)[0]), self.n_modes)
+        return np.asarray(action, dtype=np.int64).reshape(-1)
+
+
+
+# ---------------------------------------------------------------------------
+# Evaluation protocol
+# ---------------------------------------------------------------------------
+@dataclass
+class EvalRow:
+    policy: str
+    scenario: str
+    seed: int
+    reward: float
+    utility: float
+    harvested_j: float
+    consumed_j: float
+    n_sensing: int
+    n_high_quality: int
+    n_tx: int
+    n_delivered: int
+    min_soc: float
+    low_battery_frac: float
+    depletions: int
+    aoi_h: float
+    max_aoi_h: float
+    components: dict[str, float] = field(default_factory=dict)
+
+    def as_dict(self) -> dict[str, Any]:
+        d = {k: v for k, v in self.__dict__.items() if k != "components"}
+        d.update({f"c_{k}": v for k, v in self.components.items()})
+        return d
+
+
+def evaluate(
+    policies: dict[str, Callable[[], Policy]],
+    scenarios: Iterable[str] = ("default",),
+    seeds: Iterable[int] = range(1000, 1010),
+    *,
+    randomize: bool = False,
+    progress: Callable[[str], None] | None = None,
+    envs: Mapping[str, gym.Env] | None = None,
+) -> list[EvalRow]:
+    """Run every policy on every scenario and seed; return one row per episode.
+
+    Policies are given as factories so that stateful policies start fresh.
+    Seeds default to a held-out range (1000+) that training never touches.
+    ``envs`` replaces the named scenarios by ready-made environments
+    (``{label: env}``), e.g. trace-driven ones; the label is reported as the
+    row's ``scenario``.
+    """
+    rows: list[EvalRow] = []
+    seeds = list(seeds)
+    if envs is not None:
+        targets: list[tuple[str, gym.Env, bool]] = [(k, v, False) for k, v in envs.items()]
+    else:
+        targets = [(str(s), make_env(s, randomize=randomize), True) for s in scenarios]
+    for scenario, env, owned in targets:
+        for name, factory in policies.items():
+            if progress:
+                progress(f"{scenario:22s} {name}")
+            for seed in seeds:
+                res = run_episode(env, factory(), seed=seed)
+                m = env.unwrapped.metrics
+                rows.append(
+                    EvalRow(
+                        policy=name,
+                        scenario=scenario,
+                        seed=seed,
+                        reward=res.total_reward,
+                        utility=m.total_application_utility,
+                        harvested_j=m.total_harvested_energy_j,
+                        consumed_j=m.total_consumed_energy_j,
+                        n_sensing=m.n_sensing,
+                        n_high_quality=m.n_high_quality_sensing,
+                        n_tx=m.n_transmissions,
+                        n_delivered=m.n_successful_transmissions,
+                        min_soc=m.min_battery_soc,
+                        low_battery_frac=m.fraction_low_battery,
+                        depletions=m.battery_depletion_events,
+                        aoi_h=m.average_aoi_s / 3600.0,
+                        max_aoi_h=m.max_aoi_s / 3600.0,
+                        components=dict(m.reward_components),
+                    )
+                )
+        if owned:
+            env.close()
+    return rows
+
+
+def summarize(rows: list[EvalRow], metric: str = "reward") -> dict[str, dict[str, tuple[float, float]]]:
+    """``{scenario: {policy: (mean, std)}}`` for one metric."""
+    out: dict[str, dict[str, tuple[float, float]]] = {}
+    for r in rows:
+        out.setdefault(r.scenario, {}).setdefault(r.policy, [])  # type: ignore[arg-type]
+        out[r.scenario][r.policy].append(getattr(r, metric))  # type: ignore[union-attr]
+    return {s: {p: (float(np.mean(v)), float(np.std(v))) for p, v in d.items()} for s, d in out.items()}
+
+
+__all__ = ["FlatActionWrapper", "MixedScenarioEnv", "make_env", "make_env_fn", "SB3Policy", "EvalRow", "evaluate", "summarize", "flatten_action"]
+
+
+# ---------------------------------------------------------------------------
+# Export of small MLP policies (SB3 -> plain numbers -> numpy runtime)
+# ---------------------------------------------------------------------------
+def export_sb3_mlp(model: Any) -> dict[str, Any]:
+    """Extract the actor of an SB3 ``PPO``/``A2C`` (MultiDiscrete) or ``DQN``
+    (flat Discrete) MlpPolicy as nested lists, ready for ``PolicyBundle.model``.
+
+    Returned dict::
+
+        {"type": "mlp", "input_dim": 18,
+         "layers": [{"W": [[...]], "b": [...], "activation": "tanh"|"relu"|"linear"}, ...],
+         "output": "multidiscrete_logits" | "flat_q_values",
+         "output_split": [3, 4],            # only for multidiscrete_logits
+         "n_modes": 3}
+    """
+    import torch  # local import: torch is only needed when exporting
+
+    policy = model.policy
+    layers: list[dict[str, Any]] = []
+
+    def add_sequential(seq, final_activation: str | None = None):
+        mods = [m for m in seq if not isinstance(m, torch.nn.Flatten)]
+        pending: dict | None = None
+        for m in mods:
+            if isinstance(m, torch.nn.Linear):
+                if pending is not None:
+                    pending["activation"] = "linear"
+                    layers.append(pending)
+                pending = {"W": m.weight.detach().cpu().numpy().tolist(), "b": m.bias.detach().cpu().numpy().tolist()}
+            elif isinstance(m, (torch.nn.Tanh, torch.nn.ReLU)):
+                assert pending is not None, "activation without a preceding Linear layer"
+                pending["activation"] = "tanh" if isinstance(m, torch.nn.Tanh) else "relu"
+                layers.append(pending)
+                pending = None
+            else:
+                raise TypeError(f"unsupported module in policy network: {type(m).__name__}")
+        if pending is not None:
+            pending["activation"] = final_activation or "linear"
+            layers.append(pending)
+
+    if hasattr(policy, "q_net"):  # DQN
+        add_sequential(policy.q_net.q_net, final_activation="linear")
+        output, split = "flat_q_values", None
+        n_modes = int(model.action_space.n) // 3 - 1
+    else:  # on-policy actor-critic
+        add_sequential(policy.mlp_extractor.policy_net)
+        add_sequential(torch.nn.Sequential(policy.action_net), final_activation="linear")
+        output = "multidiscrete_logits"
+        split = [int(n) for n in model.action_space.nvec]
+        n_modes = split[1] - 1
+    return {"type": "mlp", "input_dim": len(layers[0]["W"][0]), "layers": layers, "output": output, "output_split": split, "n_modes": n_modes}
+
+
+class NumpyMLPPolicy:
+    """Dependency-free runtime for an exported MLP (what a C port would do).
+
+    Runs the forward pass in float32 with numpy only and applies the argmax
+    decoding of the action encoding, so a bundle exported with
+    :func:`export_sb3_mlp` can be executed without torch or SB3 - and compared
+    action-by-action with the original model (see the RL notebook).
+    """
+
+    def __init__(self, model: dict[str, Any]):
+        self.layers = [(np.asarray(l["W"], dtype=np.float32), np.asarray(l["b"], dtype=np.float32), l["activation"]) for l in model["layers"]]
+        self.output = model["output"]
+        self.split = model.get("output_split")
+        self.n_modes = int(model.get("n_modes", (self.split[1] - 1) if self.split else 3))
+
+    def reset(self) -> None:
+        pass
+
+    def forward(self, observation) -> np.ndarray:
+        h = np.asarray(observation, dtype=np.float32).reshape(-1)
+        for W, b, act in self.layers:
+            h = W @ h + b
+            if act == "tanh":
+                h = np.tanh(h)
+            elif act == "relu":
+                h = np.maximum(h, 0.0)
+        return h
+
+    def act(self, observation) -> np.ndarray:
+        out = self.forward(observation)
+        if self.output == "flat_q_values":
+            return unflatten_action(int(np.argmax(out)), self.n_modes)
+        n1 = self.split[0]
+        return np.array([int(np.argmax(out[:n1])), int(np.argmax(out[n1:]))], dtype=np.int64)
+
+
+__all__ += ["export_sb3_mlp", "NumpyMLPPolicy"]
+
+
+# ---------------------------------------------------------------------------
+# Memory: frame stacking (mirrors stable_baselines3 VecFrameStack for 1-D obs)
+# ---------------------------------------------------------------------------
+class FrameStacker:
+    """Keep the last ``n_stack`` observations concatenated (oldest first).
+
+    Identical to SB3's ``VecFrameStack`` for 1-D observations: the buffer is
+    zero-filled at reset and shifted left at every step. On a microcontroller
+    this is a ring buffer of ``n_stack`` observation vectors.
+    """
+
+    def __init__(self, n_stack: int, obs_dim: int):
+        self.n_stack, self.obs_dim = int(n_stack), int(obs_dim)
+        self.reset()
+
+    def reset(self) -> None:
+        self._buf = np.zeros(self.n_stack * self.obs_dim, dtype=np.float32)
+
+    def push(self, observation) -> np.ndarray:
+        o = np.asarray(observation, dtype=np.float32).reshape(-1)
+        self._buf = np.concatenate([self._buf[self.obs_dim:], o])
+        return self._buf.copy()
+
+
+class StackedPolicy:
+    """Wrap any ``Policy`` that expects a stacked observation (e.g. an
+    :class:`SB3Policy` of a model trained with ``VecFrameStack``, or a
+    :class:`NumpyMLPPolicy` exported from it) so that it can be used where a
+    plain observation is provided (``run_episode``, ``evaluate``, the firmware loop)."""
+
+    def __init__(self, inner: Policy, n_stack: int, obs_dim: int = len(OBSERVATION_FIELDS)):
+        self.inner = inner
+        self.stacker = FrameStacker(n_stack, obs_dim)
+
+    def reset(self) -> None:
+        self.stacker.reset()
+        self.inner.reset()
+
+    def act(self, observation) -> np.ndarray:
+        return self.inner.act(self.stacker.push(observation))
+
+
+__all__ += ["FrameStacker", "StackedPolicy"]

edgeengine_aware/scenarios.py

@@ -0,0 +1,131 @@
+"""Named evaluation scenarios of the agriculture domain (and the lookup of
+every domain's scenarios by qualified name).
+
+A scenario is a function that returns a fully configured
+:class:`EdgeEngineAwareConfig`. The set below is the *benchmark protocol* of the
+project: policies are compared on every scenario, over a fixed set of seeds,
+with the same metrics. ``default`` is the training distribution; the others
+stress one aspect of the problem so that the value of an adaptive policy
+becomes visible where a fixed duty cycle cannot cope. The scenarios of the
+other domains live in ``domains.py`` and are addressed as ``"indoor_air:no_window"``
+or ``"industrial:degrading"`` (``scenario_names("all")`` lists everything).
+
+Scenario                what is stressed                            what a good policy does
+----------------------  ------------------------------------------  --------------------------------------------
+default                 nothing in particular (mixed weather)       report ~hourly, more near thresholds
+cloudy_week             harvesting ~55 % of default (30 J/day),     slow down early, keep a reserve, use cheap checks
+                        battery starts at 40 %
+tiny_battery            storage halved (150 J), small buffer        smooth consumption, avoid bursts at night
+lossy_link              +6 dB path loss, slower fading              choose the radio mode from the link estimate
+drought                 fast drying, almost no rain, slow           track the approach to the thresholds closely
+                        irrigation
+demanding_application   frequent elevated/urgent campaigns          follow the priority, save energy in between
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+
+from .config import HOUR_S, EdgeEngineAwareConfig, default_config
+
+
+def default() -> EdgeEngineAwareConfig:
+    return default_config()
+
+
+def cloudy_week() -> EdgeEngineAwareConfig:
+    cfg = default_config()
+    cfg.harvesting.clearness_mean = 0.35
+    cfg.harvesting.clearness_std = 0.15
+    cfg.harvesting.cloud_noise_std = 0.25
+    cfg.storage.initial_soc = 0.4
+    return cfg
+
+
+def tiny_battery() -> EdgeEngineAwareConfig:
+    cfg = default_config()
+    cfg.storage.capacity_j = 150.0
+    cfg.storage.initial_soc = 0.5
+    return cfg
+
+
+def lossy_link() -> EdgeEngineAwareConfig:
+    """Node far from the gateway: +6 dB path loss and slower fading (AR(1)
+    coefficient 0.98 instead of 0.97, i.e. bad phases last longer). Mean
+    margins become -8 / -2 / +6 dB for fast / standard / robust; averaged over
+    the fading, the standard mode delivers ~40 % and the robust mode ~85 % of
+    the uplinks at twice the energy; the fast mode only works in favourable
+    fading phases."""
+    cfg = default_config()
+    cfg.communication.path_loss_mean_db += 6.0
+    cfg.communication.slow_fading_autocorr = 0.98
+    return cfg
+
+
+def drought() -> EdgeEngineAwareConfig:
+    cfg = default_config()
+    cfg.agriculture.et_rate_per_day = 0.12
+    cfg.agriculture.rain_events_per_day = 0.02
+    cfg.agriculture.irrigation_delay_mean_s = 18.0 * HOUR_S
+    cfg.agriculture.initial_moisture_range = (0.40, 0.55)
+    return cfg
+
+
+def demanding_application() -> EdgeEngineAwareConfig:
+    cfg = default_config()
+    cfg.application.request_rate_per_day = 1.5
+    cfg.application.request_duration_range_s = (2.0 * HOUR_S, 8.0 * HOUR_S)
+    cfg.application.request_urgent_fraction = 0.5
+    cfg.application.aoi_elevated_s = 4.0 * HOUR_S
+    return cfg
+
+
+SCENARIOS: dict[str, Callable[[], EdgeEngineAwareConfig]] = {
+    "default": default,
+    "cloudy_week": cloudy_week,
+    "tiny_battery": tiny_battery,
+    "lossy_link": lossy_link,
+    "drought": drought,
+    "demanding_application": demanding_application,
+}
+
+
+def split_scenario_name(name: str) -> tuple[str, str]:
+    """``"indoor_air:no_window"`` -> ``("indoor_air", "no_window")``; a bare name is agricultural."""
+    if ":" in name:
+        domain, scen = name.split(":", 1)
+        return domain, scen
+    return "agriculture", name
+
+
+def scenario_names(domain: str = "agriculture") -> list[str]:
+    """Qualified names (``domain:scenario``) of the benchmark scenarios of ``domain``,
+    or of every domain with ``domain="all"``. Agricultural names are returned bare
+    for backwards compatibility."""
+    from .domains import DOMAIN_NAMES, domain_scenarios  # local import (domains.py imports SCENARIOS)
+
+    if domain == "all":
+        return [n for d in DOMAIN_NAMES for n in scenario_names(d)]
+    if domain == "agriculture":
+        return list(SCENARIOS)
+    return [f"{domain}:{s}" for s in domain_scenarios(domain)]
+
+
+def get_scenario(name: str, *, randomize: bool = False) -> EdgeEngineAwareConfig:
+    """Return a fresh configuration for ``name``.
+
+    ``name`` is an agricultural scenario (see :data:`SCENARIOS`) or a qualified
+    ``domain:scenario`` of another domain, e.g. ``"industrial:degrading"``
+    (see ``domains.DOMAINS``).
+    """
+    from .domains import DOMAIN_NAMES, domain_scenarios  # local import (domains.py imports SCENARIOS)
+
+    domain, scen = split_scenario_name(name)
+    if domain not in DOMAIN_NAMES:
+        raise KeyError(f"unknown domain {domain!r} in scenario {name!r}; available: {DOMAIN_NAMES}")
+    table = domain_scenarios(domain)
+    if scen not in table:
+        raise KeyError(f"unknown scenario {name!r}; available in {domain}: {sorted(table)}")
+    cfg = table[scen]()
+    cfg.randomization.enabled = randomize
+    return cfg

edgeengine_aware/sensing.py

@@ -0,0 +1,45 @@
+"""Simulated scalar sensor (soil moisture, CO2, temperature - any normalised quantity).
+
+The sensor reads the *true* field moisture and returns a noisy measurement
+whose noise level depends on the requested sensing level. A real driver would
+implement the same ``Sensor`` protocol on top of an ADC / I2C transaction.
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+
+import numpy as np
+
+from .config import SensingConfig
+from .interfaces import Measurement
+
+
+class SimulatedSoilMoistureSensor:
+    """``Sensor`` implementation backed by a ground-truth callable."""
+
+    def __init__(self, cfg: SensingConfig, true_value: Callable[[], float]):
+        self.cfg = cfg
+        self._true_value = true_value
+        self._rng = np.random.default_rng()
+
+    def reset(self, rng: np.random.Generator) -> None:
+        self._rng = rng
+
+    # -- Sensor protocol ----------------------------------------------------
+    def energy_cost_j(self, level: int) -> float:
+        return self.cfg.energy_j[level]
+
+    def noise_std(self, level: int) -> float:
+        return self.cfg.noise_std[level]
+
+    def read(self, level: int, now_s: float) -> Measurement:
+        if level < 1 or level >= self.cfg.n_levels:
+            raise ValueError(f"sensing level must be in [1, {self.cfg.n_levels}), got {level}")
+        truth = self._true_value()
+        noise = self._rng.normal(0.0, self.cfg.noise_std[level]) + self.cfg.bias[level]
+        value = float(np.clip(truth + noise, 0.0, 1.0))
+        return Measurement(value=value, timestamp_s=now_s, level=level, noise_std=self.cfg.noise_std[level])
+
+
+SimulatedScalarSensor = SimulatedSoilMoistureSensor  # domain-neutral name