ebus-panel-sim 0.3.0__py3-none-any.whl

ebus_panel_sim/native_devices/bess.py

@@ -0,0 +1,185 @@
+"""Native BESS device — configured-and-self-driving.
+
+Configuration is supplied at construction (via ``Emitter(bess_configs=...)``) and
+mutable mid-run via ``Emitter.update_bess_config``. Per-tick context — grid
+state, instantaneous load demand, instantaneous PV available, current_time —
+is pushed by the producer via ``Emitter.publish_tick``; the emitter calls
+``BESSDevice.tick`` and writes the resulting ``EbusBatterySnapshot`` into the
+internal snapshot.
+
+Subclassable for vendor-variant behaviour (Powerwall vs Enphase IQ etc.)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+from ebus_panel_sim.native_devices.protocol import NativeTickContext
+from ebus_panel_sim.snapshot import EbusBatterySnapshot
+
+ChargeMode = Literal["self-consumption", "backup-only"]
+DispatchState = Literal["charging", "discharging", "idle"]
+
+
+@dataclass(slots=True)
+class BESSConfig:
+    """BESS device configuration. Producer supplies at construction; mutation through
+    ``BESSDevice.update_config`` takes effect on the next tick."""
+
+    instance_id: str
+    nameplate_capacity_kwh: float
+    max_charge_w: float
+    max_discharge_w: float
+    charge_efficiency: float = 0.95
+    discharge_efficiency: float = 0.95
+    backup_reserve_pct: float = 20.0
+    charge_mode: ChargeMode = "self-consumption"
+    charge_hours: tuple[int, ...] = ()
+    discharge_hours: tuple[int, ...] = ()
+    initial_soc_pct: float = 50.0
+
+
+@dataclass(slots=True)
+class BESSDevice:
+    """Per-tick BESS state machine. State (SOC/SOE) accumulates across ticks; config
+    can be replaced live without restart."""
+
+    config: BESSConfig
+    _soc_pct: float = field(init=False)
+    _soe_kwh: float = field(init=False)
+    _last_tick_time: float | None = field(init=False, default=None)
+    _state: DispatchState = field(init=False, default="idle")
+
+    def __post_init__(self) -> None:
+        self._soc_pct = self.config.initial_soc_pct
+        self._soe_kwh = self.config.nameplate_capacity_kwh * (self.config.initial_soc_pct / 100.0)
+
+    @property
+    def instance_id(self) -> str:
+        """Stable identifier for this device — delegates to ``config.instance_id``.
+
+        Exposed as a property so ``BESSDevice`` structurally satisfies the
+        ``NativeDevice[EbusBatterySnapshot]`` Protocol."""
+        return self.config.instance_id
+
+    def update_config(self, config: BESSConfig) -> None:
+        """Replace configuration; SOC/SOE persist."""
+        self.config = config
+
+    def set_soe(self, soe_kwh: float) -> None:
+        """Overwrite stored SOE/SOC. Used by ``Emitter.seed_bess_soe`` to restore
+        battery state across emitter restarts."""
+        capped = max(0.0, min(self.config.nameplate_capacity_kwh, soe_kwh))
+        self._soe_kwh = capped
+        if self.config.nameplate_capacity_kwh > 0:
+            self._soc_pct = (capped / self.config.nameplate_capacity_kwh) * 100.0
+        else:
+            self._soc_pct = 0.0
+
+    def tick(self, ctx: NativeTickContext) -> EbusBatterySnapshot:
+        """Run one dispatch step and return a fresh ``EbusBatterySnapshot``.
+
+        Given the current grid state, instantaneous load demand, and PV
+        availability for this tick, decide whether to charge, discharge, or
+        idle; integrate energy in/out of the cell since the previous tick;
+        update internal SOC/SOE; and return a snapshot describing the result.
+        Pure with respect to the panel snapshot — does not read or mutate it."""
+        dispatch_w = self._decide_dispatch(
+            current_time=ctx.current_time,
+            grid_online=ctx.grid_online,
+            load_demand_w=ctx.load_demand_w,
+            pv_available_w=ctx.pv_available_w,
+        )
+
+        if self._last_tick_time is not None:
+            dt_seconds = max(0.0, ctx.current_time - self._last_tick_time)
+            dt_hours = dt_seconds / 3600.0
+            if dispatch_w > 0:
+                self._soe_kwh -= (
+                    dispatch_w * dt_hours / 1000.0
+                ) / self.config.discharge_efficiency
+            elif dispatch_w < 0:
+                self._soe_kwh += (
+                    abs(dispatch_w) * dt_hours / 1000.0
+                ) * self.config.charge_efficiency
+            self._soe_kwh = max(0.0, min(self.config.nameplate_capacity_kwh, self._soe_kwh))
+            self._soc_pct = (self._soe_kwh / self.config.nameplate_capacity_kwh) * 100.0
+        self._last_tick_time = ctx.current_time
+
+        if dispatch_w > 0:
+            self._state = "discharging"
+        elif dispatch_w < 0:
+            self._state = "charging"
+        else:
+            self._state = "idle"
+
+        return EbusBatterySnapshot(
+            soe_percentage=self._soc_pct,
+            soe_kwh=self._soe_kwh,
+            active_power_w=dispatch_w,
+            nameplate_capacity_kwh=self.config.nameplate_capacity_kwh,
+            communication="OK",
+        )
+
+    @property
+    def state(self) -> DispatchState:
+        return self._state
+
+    def _decide_dispatch(
+        self,
+        *,
+        current_time: float,
+        grid_online: bool,
+        load_demand_w: float,
+        pv_available_w: float,
+    ) -> float:
+        """Return signed dispatch power in watts. Positive = discharge, negative = charge."""
+        # Reserve floor: do not discharge below backup reserve when grid is online.
+        backup_floor_kwh = (
+            self.config.nameplate_capacity_kwh * self.config.backup_reserve_pct / 100.0
+        )
+
+        if not grid_online:
+            # Off-grid: discharge to meet load demand minus PV (down to empty).
+            deficit_w = max(0.0, load_demand_w - pv_available_w)
+            if self._soe_kwh <= 0:
+                return 0.0
+            return min(deficit_w, self.config.max_discharge_w)
+
+        # Grid online — apply mode-specific behavior.
+        pv_surplus_w = max(0.0, pv_available_w - load_demand_w)
+        if self.config.charge_mode == "backup-only":
+            # Keep reserve while on-grid. Charge only from PV surplus; never
+            # charge from utility grid and never discharge in backup-only mode.
+            if pv_surplus_w > 0 and self._soe_kwh < self.config.nameplate_capacity_kwh:
+                return -min(
+                    self.config.max_charge_w,
+                    pv_surplus_w,
+                    (self.config.nameplate_capacity_kwh - self._soe_kwh) * 1000.0,
+                )
+            return 0.0
+
+        # self-consumption mode — always reactive: charge from PV surplus,
+        # discharge to cover load deficit. Hour-of-day windows are NOT applied
+        # (those belong to a TOU/custom dispatch mode, not modelled here).
+        # ``backup_floor_kwh`` still gates discharge so the reserve isn't
+        # consumed during normal operation.
+        del current_time  # not used in self-consumption
+        load_deficit_w = max(0.0, load_demand_w - pv_available_w)
+
+        if pv_surplus_w > 0 and self._soe_kwh < self.config.nameplate_capacity_kwh:
+            return -min(
+                self.config.max_charge_w,
+                pv_surplus_w,
+                (self.config.nameplate_capacity_kwh - self._soe_kwh) * 1000.0,
+            )
+
+        if load_deficit_w > 0 and self._soe_kwh > backup_floor_kwh:
+            available_kwh = self._soe_kwh - backup_floor_kwh
+            return min(
+                load_deficit_w,
+                self.config.max_discharge_w,
+                available_kwh * 1000.0,
+            )
+
+        return 0.0

ebus_panel_sim/native_devices/load_shedding.py

@@ -0,0 +1,60 @@
+"""Native load-shedding controller.
+
+When the grid goes offline, circuits with shedding priorities below the active
+SOC threshold are forcibly opened. The shedding decisions are emitter-domain
+because they're a deterministic configured response: given (grid_state, BESS
+SOC, per-circuit priority), the shed set is computable without producer
+intervention.
+
+``decide_shed`` is a pure function used by ``Emitter.publish_tick`` to drive
+``RelayResolver``. When the operator has a /set override on a sheddable
+circuit, the ``RelayResolver`` honors operator intent (per the v0.3.0
+precedence rule: always-on > /set > load-shed > default-CLOSED). Load-shed
+only takes effect when there's no operator override."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+
+@dataclass(slots=True)
+class LoadSheddingConfig:
+    """When grid is offline, circuits with these priorities are shed in order:
+    first OFF_GRID, then SOC_THRESHOLD when BESS SOC drops below soc_threshold_pct.
+    NEVER-priority circuits are never shed."""
+
+    soc_threshold_pct: float = 20.0
+
+
+@dataclass(slots=True)
+class LoadSheddingDevice:
+    """Per-tick load-shedding policy."""
+
+    config: LoadSheddingConfig
+
+    def update_config(self, config: LoadSheddingConfig) -> None:
+        self.config = config
+
+    def decide_shed(
+        self,
+        *,
+        grid_online: bool,
+        bess_soc_pct: float | None,
+        priorities: Mapping[str, str],
+    ) -> set[str]:
+        """Return the set of circuit instance_ids the policy wants OPEN.
+
+        - On-grid: always empty (nothing is shed when grid is up).
+        - Off-grid: ``OFF_GRID`` priority always shed; ``SOC_THRESHOLD`` shed
+          when BESS SOC is below ``soc_threshold_pct`` (or when no BESS exists).
+        - ``NEVER`` priority is never shed."""
+        if grid_online:
+            return set()
+        soc_low = bess_soc_pct is None or bess_soc_pct < self.config.soc_threshold_pct
+        shed: set[str] = set()
+        for cid, priority in priorities.items():
+            p = (priority or "").upper()
+            if p == "OFF_GRID" or (p == "SOC_THRESHOLD" and soc_low):
+                shed.add(cid)
+        return shed

ebus_panel_sim/native_devices/protocol.py

@@ -0,0 +1,38 @@
+"""Native-device tick contract — shared by BESS and future natives.
+
+Future natives include MID and vendor-specific BESS variants."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol, TypeVar, runtime_checkable
+
+
+@dataclass(frozen=True, slots=True)
+class NativeTickContext:
+    """Per-tick driving signal handed to a native device's ``tick()``.
+
+    All natives consume the same primitive signals; per-device behaviour lives
+    in the device implementation, not in the context shape."""
+
+    current_time: float
+    grid_online: bool
+    load_demand_w: float
+    pv_available_w: float
+
+
+SnapT = TypeVar("SnapT", covariant=True)
+
+
+@runtime_checkable
+class NativeDevice(Protocol[SnapT]):
+    """Common contract for emitter-resident, configured-and-self-driving devices.
+
+    Today: ``BESSDevice``. Future: ``MidDevice`` (when MID becomes a separate
+    device per the upcoming eBus migration), vendor-specific BESS variants
+    (Powerwall vs Enphase IQ specifics)."""
+
+    @property
+    def instance_id(self) -> str: ...
+
+    def tick(self, ctx: NativeTickContext) -> SnapT: ...

ebus_panel_sim/panel_meter.py

@@ -0,0 +1,216 @@
+"""Panel-level aggregator. Pure function: takes resolved per-circuit gated powers
++ battery dispatch + grid online + manifest physics, returns the panel-level
+fields that go into ``EbusPanelSnapshot``.
+
+Stateless — all integration / accumulation lives in ``EnergyIntegrator``. This
+module is just arithmetic over the current tick's inputs.
+
+Sign conventions (consistent across the emitter):
+- Per-circuit ``power_w``: positive = consume, negative = produce (PV/V2G).
+- ``battery_w``: positive = discharging (battery → panel), negative = charging.
+- ``instant_grid_power_w``: positive = importing from grid, negative = exporting.
+- ``upstream_active_power_w``: net power through the panel-side upstream lugs,
+  before any upstream BESS contribution is removed.
+- ``feedthrough_power_w``: net power flowing through the lugs to downstream
+  loads (panel-side meter perspective).
+
+Off-grid: when ``grid_online`` is False, ``instant_grid_power_w`` is 0 by
+definition (grid is electrically disconnected); battery and PV cover load."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from ebus_panel_sim.conventions.tab_legs import Leg
+
+if TYPE_CHECKING:
+    from ebus_panel_sim.manifest_physics import CircuitPhysics, PanelPhysics
+
+
+# ---------------------------------------------------------------------------
+# Per-tick output bundle
+# ---------------------------------------------------------------------------
+
+
+@dataclass(slots=True)
+class PanelMeterReading:
+    """Resolved panel-level values for a single tick."""
+
+    instant_grid_power_w: float
+    upstream_active_power_w: float
+    feedthrough_power_w: float
+    upstream_l1_current_a: float
+    upstream_l2_current_a: float
+    downstream_l1_current_a: float
+    downstream_l2_current_a: float
+    line_voltage_v: float
+    main_relay_state: str  # "OPEN" | "CLOSED"
+    grid_state: str | None  # "ON_GRID" | "OFF_GRID"
+    dsm_state: str
+    current_run_config: str
+    dominant_power_source: str | None  # "GRID" | "BATTERY" | None
+    power_flow_pv: float
+    power_flow_battery: float
+    power_flow_grid: float
+    power_flow_site: float
+
+
+# ---------------------------------------------------------------------------
+# Per-circuit derived current — published per circuit, also folded into panel
+# upstream/downstream legs.
+# ---------------------------------------------------------------------------
+
+
+def circuit_current_a(power_w: float, dipole: bool, line_voltage_v: float) -> float:
+    """Magnitude of current draw. Dipole circuits use line-to-line voltage
+    (2 * line_voltage_v); single-tab circuits use line-to-neutral."""
+    if line_voltage_v <= 0:
+        return 0.0
+    voltage = 2 * line_voltage_v if dipole else line_voltage_v
+    return abs(power_w) / voltage
+
+
+# ---------------------------------------------------------------------------
+# Panel state strings — derived from grid + battery presence
+# ---------------------------------------------------------------------------
+
+
+_DSM_ON = "DSM_ON_GRID"
+_DSM_OFF = "DSM_OFF_GRID"
+_RUN_ON = "PANEL_ON_GRID"
+_RUN_OFF = "PANEL_OFF_GRID"
+
+
+# ---------------------------------------------------------------------------
+# Resolver
+# ---------------------------------------------------------------------------
+
+
+def resolve(
+    *,
+    panel: PanelPhysics,
+    circuits: dict[str, CircuitPhysics],
+    gated_powers: dict[str, float],  # circuit_id -> post-relay-gate signed power
+    battery_w: float,  # signed; positive = discharging
+    grid_online: bool,
+    has_battery: bool,
+) -> PanelMeterReading:
+    """Build the panel-level reading from per-circuit gated powers + battery + grid."""
+
+    load_demand_w = sum(p for p in gated_powers.values() if p > 0)
+    pv_available_w = -sum(p for p in gated_powers.values() if p < 0)  # positive magnitude
+
+    upstream_active_w = load_demand_w - pv_available_w
+
+    if grid_online:
+        # Upstream lugs see the panel-side net flow. Utility grid flow is on the
+        # other side of an upstream BESS, so subtract BESS discharge. Charging is
+        # limited to PV surplus; a BESS must not turn load into extra grid import.
+        grid_w = _grid_power_from_lugs_and_bess(upstream_active_w, battery_w)
+        grid_state: str | None = "ON_GRID"
+        dsm_state = _DSM_ON
+        current_run_config = _RUN_ON
+        main_relay_state = "CLOSED"
+        line_voltage_v = panel.line_voltage_v
+        dominant_power_source: str | None = "GRID"
+    else:
+        grid_w = 0.0
+        grid_state = "OFF_GRID"
+        dsm_state = _DSM_OFF
+        current_run_config = _RUN_OFF
+        main_relay_state = "OPEN"
+        line_voltage_v = panel.line_voltage_v if has_battery else 0.0
+        dominant_power_source = "BATTERY" if has_battery else None
+
+    # Per-leg upstream current = panel-side current routed through the lugs.
+    # With an upstream BESS, this can differ from utility grid current.
+    if line_voltage_v > 0:
+        upstream_l1_a, upstream_l2_a = _per_leg_current(
+            gated_powers,
+            circuits,
+            line_voltage_v=line_voltage_v,
+        )
+    else:
+        upstream_l1_a = upstream_l2_a = 0.0
+
+    # Feedthrough = signed power across downstream-of-lugs circuits only.
+    feedthrough_w = sum(
+        p for cid, p in gated_powers.items() if circuits[cid].placement == "downstream-of-lugs"
+    )
+    if line_voltage_v > 0:
+        downstream_l1_a, downstream_l2_a = _per_leg_current(
+            {
+                cid: p
+                for cid, p in gated_powers.items()
+                if circuits[cid].placement == "downstream-of-lugs"
+            },
+            circuits,
+            line_voltage_v=line_voltage_v,
+        )
+    else:
+        downstream_l1_a = downstream_l2_a = 0.0
+
+    return PanelMeterReading(
+        instant_grid_power_w=grid_w,
+        upstream_active_power_w=upstream_active_w if grid_online else 0.0,
+        feedthrough_power_w=feedthrough_w,
+        upstream_l1_current_a=upstream_l1_a,
+        upstream_l2_current_a=upstream_l2_a,
+        downstream_l1_current_a=downstream_l1_a,
+        downstream_l2_current_a=downstream_l2_a,
+        line_voltage_v=line_voltage_v,
+        main_relay_state=main_relay_state,
+        grid_state=grid_state,
+        dsm_state=dsm_state,
+        current_run_config=current_run_config,
+        dominant_power_source=dominant_power_source,
+        power_flow_pv=pv_available_w,
+        power_flow_battery=battery_w,
+        power_flow_grid=grid_w,
+        power_flow_site=load_demand_w,
+    )
+
+
+def _grid_power_from_lugs_and_bess(upstream_active_w: float, battery_w: float) -> float:
+    """Return utility-side grid power from panel-side lugs and BESS power.
+
+    BESS sign convention is positive=discharging, negative=charging. Charging is
+    only credited against PV surplus visible at the lugs; it never creates extra
+    grid import.
+    """
+    if battery_w >= 0:
+        return upstream_active_w - battery_w
+    pv_surplus_w = max(0.0, -upstream_active_w)
+    pv_charge_w = min(abs(battery_w), pv_surplus_w)
+    return upstream_active_w + pv_charge_w
+
+
+def _per_leg_current(
+    powers: dict[str, float],
+    circuits: dict[str, CircuitPhysics],
+    *,
+    line_voltage_v: float,
+) -> tuple[float, float]:
+    """Sum per-circuit current contribution onto L1 and L2.
+
+    Single-tab circuit on tab N → all current to legs_for_tabs((N,))[0].
+    Dipole circuit (one tab per leg) → equal current on both legs at line-to-line
+    voltage (2 * line_voltage_v)."""
+    l1_a = 0.0
+    l2_a = 0.0
+    for cid, power in powers.items():
+        cphys = circuits[cid]
+        if cphys.dipole:
+            i = abs(power) / (2 * line_voltage_v)
+            # Dipole spans both legs — same current on each leg.
+            l1_a += i
+            l2_a += i
+        else:
+            i = abs(power) / line_voltage_v
+            leg = cphys.legs[0]
+            if leg == Leg.L1:
+                l1_a += i
+            else:
+                l2_a += i
+    return l1_a, l2_a

ebus_panel_sim/relay_resolver.py

@@ -0,0 +1,113 @@
+"""Per-circuit relay state, with strict precedence over commands from multiple sources.
+
+The emitter now owns relay state across ticks. Commands arrive from three sources:
+
+1. **Manifest declaration** — ``relay-behavior == "always-on"`` or ``always-on=true``
+   metadata. Absolute: the relay can never be opened, regardless of /set or
+   load-shedding decisions.
+2. **/set commands** — operator-driven via Homie ``circuit/.../switch/relay/set``
+   topic. Authoritative for non-always-on circuits, no debounce.
+3. **Load shedding** — emitter's ``LoadSheddingDevice`` decisions. Applies only
+   when there's no /set override.
+
+Precedence (highest wins):
+
+    always-on > /set override > load-shed > default-CLOSED
+
+``relay_requester`` reflects the source of the active decision, using the
+canonical eBus ``switch/relay-requester`` domain:
+- ``CONFIGURATION`` for always-on (commissioned; the relay cannot open)
+- ``USER`` for /set
+- ``LOAD_SHED`` for load-shed
+- ``NONE`` for the default-CLOSED state
+
+The producer never sees /set commands. ``Emitter`` registers internal handlers
+for ``circuit.switch/relay`` and ``circuit.load-shed/priority``; those handlers
+call ``RelayResolver.set_user_override`` (and the priority equivalent on a
+sibling state map)."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class RelayState(StrEnum):
+    OPEN = "OPEN"
+    CLOSED = "CLOSED"
+
+
+class RelayRequester(StrEnum):
+    # Canonical eBus ``switch/relay-requester`` domain.
+    CONFIGURATION = "CONFIGURATION"  # always-on circuit; commissioned, cannot open
+    USER = "USER"  # /set override active
+    LOAD_SHED = "LOAD_SHED"  # load-shed in effect
+    NONE = "NONE"  # default-CLOSED, no active requester
+    UNKNOWN = "UNKNOWN"  # unregistered / indeterminate
+
+
+class RelayResolver:
+    """Maintains relay state per circuit instance.
+
+    Construct empty, register each circuit with its always-on flag, then update
+    overrides and shed decisions; query ``state()`` for the resolved final
+    state."""
+
+    def __init__(self) -> None:
+        # always_on map: instance_id -> bool (manifest declaration; immutable post-register)
+        self._always_on: dict[str, bool] = {}
+        # /set override map: instance_id -> RelayState | None (None = no override)
+        self._user_overrides: dict[str, RelayState | None] = {}
+        # load-shed decision map: instance_id -> bool (True = wants OPEN)
+        self._shed: dict[str, bool] = {}
+
+    def register(self, instance_id: str, *, always_on: bool) -> None:
+        """Idempotent — re-registering with a different always_on value updates
+        the manifest declaration (typical use: emitter restart with edited manifest)."""
+        self._always_on[instance_id] = always_on
+        self._user_overrides.setdefault(instance_id, None)
+        self._shed.setdefault(instance_id, False)
+
+    def set_user_override(self, instance_id: str, state: RelayState | None) -> None:
+        """Operator /set or explicit clear. ``state=None`` clears the override
+        and lets load-shed (or default-CLOSED) take effect.
+
+        Always-on circuits silently drop the override — operator cannot open them."""
+        if instance_id not in self._always_on:
+            raise KeyError(f"set_user_override for unregistered instance_id={instance_id!r}")
+        if self._always_on[instance_id]:
+            return  # absolute: always-on ignores /set
+        self._user_overrides[instance_id] = state
+
+    def clear_user_override(self, instance_id: str) -> None:
+        self.set_user_override(instance_id, None)
+
+    def set_shed(self, instance_id: str, *, open_relay: bool) -> None:
+        """Load-shedding decision. ``open_relay=True`` means the load-shedding
+        policy wants this circuit OPEN.
+
+        Always-on circuits silently drop the request."""
+        if instance_id not in self._always_on:
+            raise KeyError(f"set_shed for unregistered instance_id={instance_id!r}")
+        if self._always_on[instance_id]:
+            return
+        self._shed[instance_id] = open_relay
+
+    def clear_all_shed(self) -> None:
+        """Reset every shed decision to False. Called by the emitter at the
+        start of each tick before re-running ``LoadSheddingDevice``."""
+        for k in self._shed:
+            self._shed[k] = False
+
+    def state(self, instance_id: str) -> tuple[RelayState, RelayRequester]:
+        """Resolve the final state for ``instance_id``."""
+        if self._always_on.get(instance_id, False):
+            return RelayState.CLOSED, RelayRequester.CONFIGURATION
+        override = self._user_overrides.get(instance_id)
+        if override is not None:
+            return override, RelayRequester.USER
+        if self._shed.get(instance_id, False):
+            return RelayState.OPEN, RelayRequester.LOAD_SHED
+        return RelayState.CLOSED, RelayRequester.NONE
+
+    def known(self, instance_id: str) -> bool:
+        return instance_id in self._always_on