edgeengine-aware 0.4.0__py3-none-any.whl

edgeengine_aware/application.py

@@ -0,0 +1,222 @@
+"""Remote monitoring application: information utility and priority.
+
+The application is the *consumer* of the data. It has two faces:
+
+1. **What it knows** - only the packets that were delivered. From them (and
+   from the age of the last one) it derives the *priority* it sends back to
+   the node. This is the realistic part: a real back-end would do exactly the
+   same and push the priority through a downlink.
+
+2. **How valuable the information is** - the *utility*. Utility is an
+   evaluation quantity, so the simulator is allowed to compare what the
+   application believes with the hidden ground truth. This is used for the
+   reward only and never enters the policy observation.
+
+Utility has two parts.
+
+**Tracking utility (every step)** - the value of the application holding an
+accurate picture of the field *right now*::
+
+    u_track(t) = tracking_weight * criticality(true_t) * exp(-|v_app - true_t| / error_scale)
+
+where ``v_app`` is the last delivered value (0 utility before the first
+packet). Stale information drifts away from the truth, noisy low-cost
+readings sit further from it, and a rain event makes the old value suddenly
+wrong: all three reduce ``u_track`` until a fresh accurate report arrives. A
+report identical to the previous one changes nothing, so redundant
+transmissions earn nothing and only cost energy.
+
+**Packet bonus (on delivery)** - a shaping term that credits the packet that
+fixes the picture, so the agent gets an immediate signal::
+
+    u_packet = criticality(true) * freshness * ( w_gain * tanh(gain / gain_scale)
+                                                 + w_event * event * accuracy )
+    gain      = |v_app_before - true| - |v_reported - true|   (signed! a worse report is penalised)
+    freshness = exp(-measurement_age_at_tx / tau_freshness_s)
+    event     = 1 if an environmental event happened since the last delivered packet
+    accuracy  = exp(-|v_reported - true| / error_scale)
+
+Both parts share::
+
+    criticality = 1 + criticality_gain * exp(-dist(true, nearest threshold) / criticality_scale)
+                  (saturates at 1 + criticality_gain below the critical threshold)
+
+so information is worth more when the crop is close to water stress.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import asdict, dataclass
+
+import numpy as np
+
+from .config import AgricultureConfig, ApplicationConfig, QuantityConfig
+from .process import ProcessState
+from .interfaces import Packet
+from .observation import PRIORITY_ELEVATED, PRIORITY_ROUTINE, PRIORITY_URGENT
+
+
+@dataclass
+class UtilityBreakdown:
+    """Details of the packet bonus (for ``info`` and debugging)."""
+
+    total: float
+    accuracy: float
+    freshness: float
+    gain: float
+    event: float
+    criticality: float
+
+    def as_dict(self) -> dict[str, float]:
+        return asdict(self)
+
+
+@dataclass
+class TrackingStatus:
+    """Per-step evaluation of the application's picture of the field."""
+
+    utility: float
+    error: float | None
+    """|believed - true| (None before the first delivered packet)."""
+    accuracy: float
+    criticality: float
+
+    def as_dict(self) -> dict[str, float | None]:
+        return asdict(self)
+
+
+class RemoteMonitoringApplication:
+    """Monitoring back-end: tracks one normalised quantity with two stress
+    thresholds (``QuantityConfig``: soil moisture, CO2, a bearing temperature...).
+
+    ``quantity`` may also be an ``AgricultureConfig`` (its thresholds are then
+    read directly), for backwards compatibility.
+    """
+
+    def __init__(self, cfg: ApplicationConfig, quantity: QuantityConfig | AgricultureConfig, timestep_s: float):
+        self.cfg = cfg
+        self.q: QuantityConfig = quantity.quantity() if isinstance(quantity, AgricultureConfig) else quantity
+        self.agri = self.q  # legacy name
+        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:
+        self._rng = rng
+        self._now = start_time_s
+        self._episode_start = start_time_s
+        self.last_packet: Packet | None = None
+        self.last_received_at_s: float | None = None
+        self._request_until_s: float | None = None
+        self._request_level = PRIORITY_ROUTINE
+        self._unreported_event_time_s: float | None = None
+        self._priority = PRIORITY_ROUTINE
+        self.packets_received = 0
+
+    # -- knowledge of the application -------------------------------------
+    @property
+    def believed_value(self) -> float | None:
+        return None if self.last_packet is None else self.last_packet.measurement.value
+
+    def age_of_information_s(self, now_s: float | None = None) -> float:
+        """Age of the freshest information available at the application.
+
+        Before the first packet, AoI counts from the start of the episode
+        (the application has *no* information yet)."""
+        now = self._now if now_s is None else now_s
+        if self.last_packet is None or self.last_received_at_s is None:
+            return now - self._episode_start
+        return (now - self.last_received_at_s) + self.last_packet.measurement_age_s
+
+    def priority(self) -> int:
+        return self._priority
+
+    def _compute_priority(self, now_s: float) -> int:
+        c = self.cfg
+        prio = PRIORITY_ROUTINE
+        aoi = self.age_of_information_s(now_s)
+        v = self.believed_value
+        if v is not None:
+            zone = self.q.zone(v)  # direction-aware (QuantityConfig.critical_is_upper)
+            if zone == 2:
+                prio = PRIORITY_URGENT
+            elif zone == 1:
+                prio = PRIORITY_ELEVATED
+        if aoi > c.aoi_urgent_s:
+            prio = PRIORITY_URGENT
+        elif aoi > c.aoi_elevated_s:
+            prio = max(prio, PRIORITY_ELEVATED)
+        if self._request_until_s is not None and now_s < self._request_until_s:
+            prio = max(prio, self._request_level)
+        return prio
+
+    # -- dynamics -----------------------------------------------------------
+    def step(self, now_s: float, field_state: ProcessState) -> None:
+        """Advance the application clock; register external requests and
+        ground-truth events (the latter only for utility evaluation)."""
+        c = self.cfg
+        self._now = now_s
+        # external monitoring campaigns requested e.g. by an agronomist
+        if self._request_until_s is not None and now_s >= self._request_until_s:
+            self._request_until_s = None
+        if self._request_until_s is None and self._rng.random() < c.request_rate_per_day * self.dt / 86400.0:
+            dur = self._rng.uniform(*c.request_duration_range_s)
+            self._request_until_s = now_s + dur
+            self._request_level = PRIORITY_URGENT if self._rng.random() < c.request_urgent_fraction else PRIORITY_ELEVATED
+        # environmental events worth reporting (privileged bookkeeping)
+        if field_state.event_occurred:
+            self._unreported_event_time_s = now_s
+        if self._unreported_event_time_s is not None and now_s - self._unreported_event_time_s > c.event_memory_s:
+            self._unreported_event_time_s = None
+        self._priority = self._compute_priority(now_s)
+
+    @property
+    def has_unreported_event(self) -> bool:
+        return self._unreported_event_time_s is not None
+
+    @property
+    def external_request_active(self) -> bool:
+        return self._request_until_s is not None
+
+    # -- utility (privileged) -----------------------------------------------
+    def criticality(self, true_value: float) -> float:
+        q, c = self.q, self.cfg
+        if q.beyond_critical(true_value):
+            return 1.0 + c.criticality_gain
+        dist = min(abs(true_value - q.warning_threshold), abs(true_value - q.critical_threshold))
+        return 1.0 + c.criticality_gain * math.exp(-dist / c.criticality_scale)
+
+    def tracking(self, field_state: ProcessState) -> TrackingStatus:
+        """Per-step tracking utility of the application's current belief."""
+        crit = self.criticality(field_state.value)
+        v = self.believed_value
+        if v is None:
+            return TrackingStatus(0.0, None, 0.0, crit)
+        err = abs(v - field_state.value)
+        acc = math.exp(-err / self.cfg.error_scale)
+        return TrackingStatus(self.cfg.tracking_weight * crit * acc, err, acc, crit)
+
+    def receive(self, packet: Packet, now_s: float, field_state: ProcessState) -> UtilityBreakdown:
+        """Register a delivered packet and return its bonus utility."""
+        c = self.cfg
+        m = packet.measurement
+        truth = field_state.value
+
+        err_after = abs(m.value - truth)
+        err_before = abs(self.believed_value - truth) if self.believed_value is not None else c.error_scale * 3.0
+        gain = err_before - err_after
+        accuracy = math.exp(-err_after / c.error_scale)
+        freshness = math.exp(-max(0.0, packet.measurement_age_s) / c.tau_freshness_s)
+        event = 1.0 if self._unreported_event_time_s is not None else 0.0
+        crit = self.criticality(truth)
+        total = crit * freshness * (c.w_gain * math.tanh(gain / c.gain_scale) + c.w_event * event * accuracy)
+
+        # update knowledge
+        self.last_packet = packet
+        self.last_received_at_s = now_s
+        self.packets_received += 1
+        self._unreported_event_time_s = None
+        self._priority = self._compute_priority(now_s)
+        return UtilityBreakdown(total, accuracy, freshness, gain, event, crit)

edgeengine_aware/communication.py

@@ -0,0 +1,99 @@
+"""Abstract low-power long-range link (LoRa-like) with selectable modes.
+
+Modelled at the level of *one uplink attempt* in a given *mode* (a spreading
+factor / power setting): it costs ``modes[k].energy_j`` and is delivered with a
+probability given by the link budget
+
+    margin_k(t) = tx_power_k - path_loss(t) - sensitivity_k          [dB]
+    p_k(t)      = 1 / (1 + exp(-margin_k(t) / margin_scale_db))
+    path_loss(t) = path_loss_mean_db + slow_fading(t) + fast_fading
+
+where ``slow_fading`` is an AR(1) process (shadowing by vegetation, humidity,
+gateway load) and ``fast_fading`` is redrawn at every attempt. On a delivered
+packet the node measures the margin of the used mode from the ACK (with noise)
+and can convert it into a *path-loss estimate* that is valid for every mode:
+this is how it learns which mode is currently affordable.
+
+Duty-cycle limits, collisions and multi-gateway reception are not modelled;
+this class is where they belong.
+"""
+
+from __future__ import annotations
+
+import math
+
+import numpy as np
+
+from .config import CommunicationConfig
+from .interfaces import Packet, TxResult
+
+
+class SimulatedLoRaRadio:
+    """``Radio`` implementation with a link-budget channel."""
+
+    def __init__(self, cfg: CommunicationConfig):
+        self.cfg = cfg
+        self._rng = np.random.default_rng()
+        self.reset(self._rng)
+
+    def reset(self, rng: np.random.Generator) -> None:
+        self._rng = rng
+        self._slow_db = 0.0
+        self.last_result: TxResult | None = None
+        self.last_mode: int | None = None
+        self.last_packet: Packet | None = None
+        self.attempts = 0
+        self.successes = 0
+        self.attempts_per_mode = [0] * self.cfg.n_modes
+        self.successes_per_mode = [0] * self.cfg.n_modes
+
+    def update_channel(self) -> None:
+        """Advance the slow-fading process by one timestep (called by the env)."""
+        c = self.cfg
+        rho = c.slow_fading_autocorr
+        self._slow_db = rho * self._slow_db + math.sqrt(max(0.0, 1 - rho**2)) * self._rng.normal(0.0, c.slow_fading_std_db)
+
+    # -- simulator-only ground truth ----------------------------------------
+    def path_loss_db(self) -> float:
+        """Current path loss without the per-attempt fast fading [dB]."""
+        return self.cfg.path_loss_mean_db + self._slow_db
+
+    def margin_db(self, mode: int) -> float:
+        m = self.cfg.modes[mode]
+        return m.tx_power_dbm - self.path_loss_db() - m.sensitivity_dbm
+
+    def success_probability(self, mode: int | None = None) -> float:
+        """Delivery probability of ``mode`` (default: the reference mode) given
+        the current slow fading, averaged over the fast fading."""
+        if mode is None:
+            mode = self.cfg.reference_mode
+        margin = self.margin_db(mode)
+        # logistic in margin, fast fading adds variance: average over a few points
+        z = margin + self.cfg.fast_fading_std_db * np.array([-1.5, -0.5, 0.0, 0.5, 1.5])
+        w = np.array([0.1, 0.25, 0.3, 0.25, 0.1])
+        return float(np.sum(w / (1.0 + np.exp(-z / self.cfg.margin_scale_db))))
+
+    # -- Radio protocol -----------------------------------------------------
+    def n_modes(self) -> int:
+        return self.cfg.n_modes
+
+    def tx_energy_j(self, mode: int) -> float:
+        return self.cfg.modes[mode].energy_j
+
+    def transmit(self, packet: Packet, mode: int) -> TxResult:
+        if not 0 <= mode < self.cfg.n_modes:
+            raise ValueError(f"radio mode must be in [0, {self.cfg.n_modes}), got {mode}")
+        c = self.cfg
+        self.attempts += 1
+        self.attempts_per_mode[mode] += 1
+        margin = self.margin_db(mode) + self._rng.normal(0.0, c.fast_fading_std_db)
+        z = float(np.clip(-margin / c.margin_scale_db, -60.0, 60.0))
+        p = 1.0 / (1.0 + math.exp(z))
+        ok = bool(self._rng.random() < p)
+        measured = (margin + self._rng.normal(0.0, c.ack_margin_noise_db)) if ok else None
+        result = TxResult(acked=ok, margin_db=measured)
+        self.last_result, self.last_mode, self.last_packet = result, mode, packet
+        if ok:
+            self.successes += 1
+            self.successes_per_mode[mode] += 1
+        return result