+ Schedule derived from rate plan — {{ tou_rate_month }}. + Dispatch adapts automatically each month. +
+ {% endif %} + {% endif %} diff --git a/src/span_panel_simulator/energy/components.py b/src/span_panel_simulator/energy/components.py index d9ac382..bd10d4a 100644 --- a/src/span_panel_simulator/energy/components.py +++ b/src/span_panel_simulator/energy/components.py @@ -9,6 +9,7 @@ from __future__ import annotations from datetime import datetime +from typing import Any from zoneinfo import ZoneInfo from span_panel_simulator.const import DEFAULT_FIRMWARE_VERSION @@ -110,6 +111,7 @@ def __init__( discharge_hours: tuple[int, ...] = (), panel_timezone: ZoneInfo | None = None, charge_mode: str = "self-consumption", + rate_record: dict[str, Any] | None = None, ) -> None: self.nameplate_capacity_kwh = nameplate_capacity_kwh self.max_charge_w = max_charge_w @@ -131,6 +133,7 @@ def __init__( self._charge_hours = charge_hours self._discharge_hours = discharge_hours self._panel_timezone: ZoneInfo = panel_timezone or ZoneInfo("America/Los_Angeles") + self._rate_record: dict[str, Any] | None = rate_record # Output — set by resolve() self.effective_power_w: float = 0.0 diff --git a/src/span_panel_simulator/energy/system.py b/src/span_panel_simulator/energy/system.py index 2d2ea22..1c31fc2 100644 --- a/src/span_panel_simulator/energy/system.py +++ b/src/span_panel_simulator/energy/system.py @@ -11,6 +11,7 @@ from span_panel_simulator.energy.bus import PanelBus from span_panel_simulator.energy.components import BESSUnit, GridMeter, LoadGroup, PVSource +from span_panel_simulator.energy.tou import resolve_tou_dispatch from span_panel_simulator.energy.types import ( EnergySystemConfig, PowerInputs, @@ -86,6 +87,7 @@ def from_config(config: EnergySystemConfig) -> EnergySystem: discharge_hours=bc.discharge_hours, panel_timezone=ZoneInfo(bc.panel_timezone), charge_mode=bc.charge_mode, + rate_record=bc.rate_record, ) total_demand = sum(lc.demand_w for lc in config.loads) @@ -151,19 +153,37 @@ def tick(self, ts: float, inputs: PowerInputs) -> SystemState: self.bess.requested_power_w = 0.0 else: # custom (TOU): resolve from BESS schedule config + timestamp - # Only force discharge for non-hybrid off-grid — hybrid systems - # can follow their TOU schedule while islanded. The non-hybrid - # islanding override below (line ~165) handles the non-hybrid case. - self.bess.scheduled_state = self.bess.resolve_scheduled_state( - ts, - forced_offline=not inputs.grid_connected and not self.bess.hybrid, - ) - if self.bess.scheduled_state == "discharging": - self.bess.requested_power_w = self.bess.max_discharge_w - elif self.bess.scheduled_state == "charging": - self.bess.requested_power_w = self.bess.max_charge_w + if self.bess._rate_record is not None: + # Rate-aware dispatch — consult URDB record directly + preliminary_deficit = inputs.load_demand_w - inputs.pv_available_w + pv_excess = max(0.0, -preliminary_deficit) + load_deficit = max(0.0, preliminary_deficit) + + dispatch = resolve_tou_dispatch( + ts=ts, + tz=self.bess._panel_timezone, + rate_record=self.bess._rate_record, + soe_pct=self.bess.soe_percentage, + backup_reserve_pct=self.bess.backup_reserve_pct, + max_charge_w=self.bess.max_charge_w, + max_discharge_w=self.bess.max_discharge_w, + pv_excess_w=pv_excess, + load_deficit_w=load_deficit, + ) + self.bess.scheduled_state = dispatch.state + self.bess.requested_power_w = dispatch.requested_power_w else: - self.bess.requested_power_w = 0.0 + # Fallback: static hour-list schedule (no rate record) + self.bess.scheduled_state = self.bess.resolve_scheduled_state( + ts, + forced_offline=not inputs.grid_connected and not self.bess.hybrid, + ) + if self.bess.scheduled_state == "discharging": + self.bess.requested_power_w = self.bess.max_discharge_w + elif self.bess.scheduled_state == "charging": + self.bess.requested_power_w = self.bess.max_charge_w + else: + self.bess.requested_power_w = 0.0 # Non-hybrid islanding override (applies to ALL modes): # if grid disconnected and PV is offline, BESS must discharge diff --git a/src/span_panel_simulator/energy/tou.py b/src/span_panel_simulator/energy/tou.py new file mode 100644 index 0000000..3fb2817 --- /dev/null +++ b/src/span_panel_simulator/energy/tou.py @@ -0,0 +1,181 @@ +"""Rate-aware TOU dispatch resolution for BESS. + +Resolves charge/discharge/idle state at each tick by consulting the +URDB rate record directly. Replaces the static hour-list approach +with real-time rate-period classification. + +Classification rules (mirrors real BESS TOU behaviour): +- **Off-peak** (current rate == day's minimum): charge from grid/PV +- **Peak** (current rate == day's maximum): discharge to cover load +- **Partial-peak** (between min and max): self-consumption only +- **Flat rate** (single period): self-consumption fallback +""" + +from __future__ import annotations + +from dataclasses import dataclass +from datetime import datetime +from typing import TYPE_CHECKING, Any + +if TYPE_CHECKING: + from zoneinfo import ZoneInfo + + +@dataclass(frozen=True) +class TouDispatch: + """Dispatch decision for a single simulation tick.""" + + state: str # "charging", "discharging", "idle" + requested_power_w: float + reason: str + + +def resolve_tou_dispatch( + ts: float, + tz: ZoneInfo, + rate_record: dict[str, Any], + soe_pct: float, + backup_reserve_pct: float, + max_charge_w: float, + max_discharge_w: float, + pv_excess_w: float, + load_deficit_w: float, +) -> TouDispatch: + """Resolve BESS dispatch from the rate schedule at timestamp *ts*.""" + dt = datetime.fromtimestamp(ts, tz=tz) + current_rate = _rate_at(dt, rate_record) + day_rates = _all_rates_for_day(dt, rate_record) + + if not day_rates: + return TouDispatch("idle", 0.0, "no_rate_data") + + min_rate = min(day_rates.values()) + max_rate = max(day_rates.values()) + + if min_rate == max_rate: + # Flat rate — no TOU arbitrage value, fall back to self-consumption + return _self_consumption_dispatch( + pv_excess_w, + load_deficit_w, + soe_pct, + backup_reserve_pct, + max_charge_w, + max_discharge_w, + ) + + if current_rate <= min_rate: + return _off_peak_dispatch(pv_excess_w, soe_pct, max_charge_w) + + if current_rate >= max_rate: + return _peak_dispatch(load_deficit_w, soe_pct, backup_reserve_pct, max_discharge_w) + + # Partial-peak — self-consumption only (no grid charge, no grid export) + return _self_consumption_dispatch( + pv_excess_w, + load_deficit_w, + soe_pct, + backup_reserve_pct, + max_charge_w, + max_discharge_w, + ) + + +# ------------------------------------------------------------------ +# Rate lookup helpers +# ------------------------------------------------------------------ + + +def _rate_at(dt: datetime, record: dict[str, Any]) -> float: + """Look up the energy rate for a specific datetime.""" + month_idx = dt.month - 1 + hour = dt.hour + is_weekend = dt.weekday() >= 5 + + schedule = record.get("energyweekendschedule" if is_weekend else "energyweekdayschedule", []) + if not schedule or month_idx >= len(schedule): + return 0.0 + + row = schedule[month_idx] + period_idx = row[hour] if hour < len(row) else 0 + + rate_structure = record.get("energyratestructure", []) + if not rate_structure or period_idx >= len(rate_structure): + return 0.0 + + tiers = rate_structure[period_idx] + return float(tiers[0].get("rate", 0.0)) if tiers else 0.0 + + +def _all_rates_for_day(dt: datetime, record: dict[str, Any]) -> dict[int, float]: + """Return {hour: rate} for every hour of the given day-type and month.""" + month_idx = dt.month - 1 + is_weekend = dt.weekday() >= 5 + + schedule = record.get("energyweekendschedule" if is_weekend else "energyweekdayschedule", []) + if not schedule or month_idx >= len(schedule): + return {} + + row = schedule[month_idx] + rate_structure = record.get("energyratestructure", []) + if not rate_structure: + return {} + + rates: dict[int, float] = {} + for hour in range(24): + period_idx = row[hour] if hour < len(row) else 0 + if period_idx < len(rate_structure): + tiers = rate_structure[period_idx] + rates[hour] = float(tiers[0].get("rate", 0.0)) if tiers else 0.0 + else: + rates[hour] = 0.0 + return rates + + +# ------------------------------------------------------------------ +# Dispatch strategy functions +# ------------------------------------------------------------------ + + +def _off_peak_dispatch( + pv_excess_w: float, + soe_pct: float, + max_charge_w: float, +) -> TouDispatch: + """Off-peak: charge from PV excess first, then grid.""" + if soe_pct >= 100.0: + return TouDispatch("idle", 0.0, "offpeak_full") + if pv_excess_w > 0: + power = min(pv_excess_w, max_charge_w) + return TouDispatch("charging", power, "offpeak_solar_charge") + return TouDispatch("charging", max_charge_w, "offpeak_grid_charge") + + +def _peak_dispatch( + load_deficit_w: float, + soe_pct: float, + backup_reserve_pct: float, + max_discharge_w: float, +) -> TouDispatch: + """Peak: discharge to cover load (GFE limits actual output on bus).""" + if soe_pct <= backup_reserve_pct: + return TouDispatch("idle", 0.0, "peak_reserve_hold") + if load_deficit_w <= 0: + return TouDispatch("idle", 0.0, "peak_no_deficit") + return TouDispatch("discharging", max_discharge_w, "peak_discharge") + + +def _self_consumption_dispatch( + pv_excess_w: float, + load_deficit_w: float, + soe_pct: float, + backup_reserve_pct: float, + max_charge_w: float, + max_discharge_w: float, +) -> TouDispatch: + """Self-consumption: discharge for deficit, charge from PV excess.""" + if load_deficit_w > 0 and soe_pct > backup_reserve_pct: + return TouDispatch("discharging", max_discharge_w, "selfcon_discharge") + if pv_excess_w > 0 and soe_pct < 100.0: + power = min(pv_excess_w, max_charge_w) + return TouDispatch("charging", power, "selfcon_solar_charge") + return TouDispatch("idle", 0.0, "selfcon_idle") diff --git a/src/span_panel_simulator/energy/types.py b/src/span_panel_simulator/energy/types.py index 4317c02..8362406 100644 --- a/src/span_panel_simulator/energy/types.py +++ b/src/span_panel_simulator/energy/types.py @@ -4,6 +4,7 @@ from dataclasses import dataclass, field from enum import IntEnum +from typing import Any class ComponentRole(IntEnum): @@ -108,6 +109,7 @@ class BESSConfig: discharge_hours: tuple[int, ...] = () panel_timezone: str = "America/Los_Angeles" charge_mode: str = "self-consumption" + rate_record: dict[str, Any] | None = None @dataclass(frozen=True) diff --git a/src/span_panel_simulator/engine.py b/src/span_panel_simulator/engine.py index 9e763ba..8589d09 100644 --- a/src/span_panel_simulator/engine.py +++ b/src/span_panel_simulator/engine.py @@ -37,6 +37,7 @@ SystemState, ) from span_panel_simulator.exceptions import SimulationConfigurationError +from span_panel_simulator.rates.cache import RateCache if TYPE_CHECKING: from span_panel_simulator.config_types import ( @@ -1567,6 +1568,23 @@ def _build_baseline_config(self) -> dict[str, Any] | None: return baseline + def _resolve_rate_record(self, rate_label: str) -> dict[str, Any] | None: + """Load a URDB rate record from the simulator rate cache. + + Returns the raw URDB dict if the label exists in the cache, + or ``None`` if the cache file is missing or the label is absent. + """ + if self._config_path is None: + return None + cache_path = self._config_path.parent / "rates" / "rates_cache.yaml" + if not cache_path.exists(): + return None + cache = RateCache(cache_path) + entry = cache.get_cached_rate(rate_label) + if entry is None: + return None + return dict(entry.record) + def _build_energy_system( self, *, @@ -1630,6 +1648,10 @@ def _build_energy_system( else RealisticBehaviorEngine._DEFAULT_TZ ) charge_mode = str(bess_yaml.get("charge_mode", "self-consumption")) + rate_label = bess_yaml.get("rate_label") + rate_record: dict[str, Any] | None = None + if isinstance(rate_label, str) and rate_label: + rate_record = self._resolve_rate_record(rate_label) bess_config = BESSConfig( nameplate_kwh=nameplate, max_charge_w=abs(float(bess_yaml.get("max_charge_w", 3500.0))), @@ -1648,6 +1670,7 @@ def _build_energy_system( discharge_hours=tuple(discharge_hours_raw), panel_timezone=panel_tz, charge_mode=charge_mode, + rate_record=rate_record, ) loads = [LoadConfig() for c in included.values() if c.energy_mode == "consumer"] diff --git a/src/span_panel_simulator/rates/resolver.py b/src/span_panel_simulator/rates/resolver.py index e60499d..7c3619b 100644 --- a/src/span_panel_simulator/rates/resolver.py +++ b/src/span_panel_simulator/rates/resolver.py @@ -14,74 +14,6 @@ from zoneinfo import ZoneInfo -def derive_bess_tou_schedule( - record: dict[str, Any], - month: int = 6, -) -> dict[int, str]: - """Derive a 24-hour BESS schedule from URDB rate periods. - - Examines the weekday energy schedule for the given month to find - which hours are cheapest (charge) and most expensive (discharge). - Hours at intermediate rates are set to idle. - - Parameters - ---------- - record: - URDB record dict containing energyratestructure and schedule matrices. - month: - 1-based month to derive the schedule for (default: June). - - Returns - ------- - dict mapping hour (0-23) to ``"charge"``, ``"discharge"``, or ``"idle"``. - """ - month_idx = month - 1 - schedule = record.get("energyweekdayschedule", []) - rate_structure = record.get("energyratestructure", []) - - if not schedule or not rate_structure: - return {h: "idle" for h in range(24)} - - if month_idx >= len(schedule): - month_idx = 0 - - # Resolve the rate for each hour - hour_rates: dict[int, float] = {} - for hour in range(24): - period_idx = schedule[month_idx][hour] if hour < len(schedule[month_idx]) else 0 - rate = 0.0 - if period_idx < len(rate_structure): - tiers = rate_structure[period_idx] - if tiers: - rate = tiers[0].get("rate", 0.0) - hour_rates[hour] = rate - - if not hour_rates: - return {h: "idle" for h in range(24)} - - # Identify distinct rate levels - distinct_rates = sorted(set(hour_rates.values())) - - if len(distinct_rates) <= 1: - # Flat rate — no TOU benefit - return {h: "idle" for h in range(24)} - - min_rate = distinct_rates[0] - max_rate = distinct_rates[-1] - - result: dict[int, str] = {} - for hour in range(24): - rate = hour_rates[hour] - if rate == min_rate: - result[hour] = "charge" - elif rate == max_rate: - result[hour] = "discharge" - else: - result[hour] = "idle" - - return result - - def resolve_rate( timestamp: int, tz: str, diff --git a/tests/test_energy/test_tou.py b/tests/test_energy/test_tou.py new file mode 100644 index 0000000..eea8b2a --- /dev/null +++ b/tests/test_energy/test_tou.py @@ -0,0 +1,420 @@ +"""Unit tests for the rate-aware TOU dispatch module.""" + +from __future__ import annotations + +from datetime import datetime +from zoneinfo import ZoneInfo + +from span_panel_simulator.energy.tou import resolve_tou_dispatch + +_TZ = ZoneInfo("America/Los_Angeles") + + +def _ts(year: int, month: int, day: int, hour: int) -> float: + """Build a UNIX timestamp for a specific local time in America/Los_Angeles.""" + dt = datetime(year, month, day, hour, tzinfo=_TZ) + return dt.timestamp() + + +# -- Minimal PG&E E-ELEC-like rate fixture with seasonal variation ------ +# +# Summer (Jun-Sep): +# Off-peak P2 = $0.397 hours 00-14 +# Part-peak P1 = $0.454 hours 15, 21-23 +# Peak P0 = $0.616 hours 16-20 +# +# Winter (Oct-May): +# Off-peak P5 = $0.348 hours 00-14 +# Part-peak P4 = $0.362 hours 15, 21-23 +# Peak P3 = $0.384 hours 16-20 + +_SUMMER_ROW = [2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 1, 0, 0, 0, 0, 0, 1, 1, 1] +_WINTER_ROW = [5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 4, 3, 3, 3, 3, 3, 4, 4, 4] + +_RATE_STRUCTURE = [ + [{"rate": 0.61578, "unit": "kWh"}], # P0 - summer peak + [{"rate": 0.45390, "unit": "kWh"}], # P1 - summer partial-peak + [{"rate": 0.39722, "unit": "kWh"}], # P2 - summer off-peak + [{"rate": 0.38426, "unit": "kWh"}], # P3 - winter peak + [{"rate": 0.36217, "unit": "kWh"}], # P4 - winter partial-peak + [{"rate": 0.34831, "unit": "kWh"}], # P5 - winter off-peak +] + + +def _build_rate_record( + weekday_schedule: list[list[int]] | None = None, + weekend_schedule: list[list[int]] | None = None, +) -> dict: + """Build a URDB-like rate record. Defaults to PG&E E-ELEC structure.""" + if weekday_schedule is None: + # 12 months: Jan-May winter, Jun-Sep summer, Oct-Dec winter + weekday_schedule = [ + _WINTER_ROW, # Jan + _WINTER_ROW, # Feb + _WINTER_ROW, # Mar + _WINTER_ROW, # Apr + _WINTER_ROW, # May + _SUMMER_ROW, # Jun + _SUMMER_ROW, # Jul + _SUMMER_ROW, # Aug + _SUMMER_ROW, # Sep + _WINTER_ROW, # Oct + _WINTER_ROW, # Nov + _WINTER_ROW, # Dec + ] + if weekend_schedule is None: + weekend_schedule = weekday_schedule + + return { + "energyratestructure": _RATE_STRUCTURE, + "energyweekdayschedule": weekday_schedule, + "energyweekendschedule": weekend_schedule, + } + + +_DEFAULT_RECORD = _build_rate_record() + + +class TestOffPeakDispatch: + """Off-peak hours should charge.""" + + def test_summer_midnight_charges_from_grid(self) -> None: + ts = _ts(2026, 7, 15, 0) # July, midnight, Wednesday + result = resolve_tou_dispatch( + ts, + _TZ, + _DEFAULT_RECORD, + soe_pct=50.0, + backup_reserve_pct=20.0, + max_charge_w=3500.0, + max_discharge_w=3500.0, + pv_excess_w=0.0, + load_deficit_w=0.0, + ) + assert result.state == "charging" + assert result.reason == "offpeak_grid_charge" + assert result.requested_power_w == 3500.0 + + def test_offpeak_with_pv_excess_charges_from_solar(self) -> None: + ts = _ts(2026, 7, 15, 10) # July, 10 AM (off-peak, solar available) + result = resolve_tou_dispatch( + ts, + _TZ, + _DEFAULT_RECORD, + soe_pct=50.0, + backup_reserve_pct=20.0, + max_charge_w=3500.0, + max_discharge_w=3500.0, + pv_excess_w=2000.0, + load_deficit_w=0.0, + ) + assert result.state == "charging" + assert result.reason == "offpeak_solar_charge" + assert result.requested_power_w == 2000.0 + + def test_offpeak_full_battery_idles(self) -> None: + ts = _ts(2026, 7, 15, 2) + result = resolve_tou_dispatch( + ts, + _TZ, + _DEFAULT_RECORD, + soe_pct=100.0, + backup_reserve_pct=20.0, + max_charge_w=3500.0, + max_discharge_w=3500.0, + pv_excess_w=0.0, + load_deficit_w=0.0, + ) + assert result.state == "idle" + assert result.reason == "offpeak_full" + + def test_winter_offpeak_charges(self) -> None: + ts = _ts(2026, 1, 15, 2) # January, 2 AM + result = resolve_tou_dispatch( + ts, + _TZ, + _DEFAULT_RECORD, + soe_pct=40.0, + backup_reserve_pct=20.0, + max_charge_w=3500.0, + max_discharge_w=3500.0, + pv_excess_w=0.0, + load_deficit_w=0.0, + ) + assert result.state == "charging" + assert result.reason == "offpeak_grid_charge" + + +class TestPeakDispatch: + """Peak hours should discharge to cover load.""" + + def test_summer_peak_discharges(self) -> None: + ts = _ts(2026, 7, 15, 17) # July, 5 PM (peak) + result = resolve_tou_dispatch( + ts, + _TZ, + _DEFAULT_RECORD, + soe_pct=80.0, + backup_reserve_pct=20.0, + max_charge_w=3500.0, + max_discharge_w=3500.0, + pv_excess_w=0.0, + load_deficit_w=2000.0, + ) + assert result.state == "discharging" + assert result.reason == "peak_discharge" + + def test_peak_no_deficit_idles(self) -> None: + ts = _ts(2026, 7, 15, 17) + result = resolve_tou_dispatch( + ts, + _TZ, + _DEFAULT_RECORD, + soe_pct=80.0, + backup_reserve_pct=20.0, + max_charge_w=3500.0, + max_discharge_w=3500.0, + pv_excess_w=500.0, + load_deficit_w=0.0, + ) + assert result.state == "idle" + assert result.reason == "peak_no_deficit" + + def test_peak_at_reserve_holds(self) -> None: + ts = _ts(2026, 7, 15, 18) + result = resolve_tou_dispatch( + ts, + _TZ, + _DEFAULT_RECORD, + soe_pct=20.0, + backup_reserve_pct=20.0, + max_charge_w=3500.0, + max_discharge_w=3500.0, + pv_excess_w=0.0, + load_deficit_w=3000.0, + ) + assert result.state == "idle" + assert result.reason == "peak_reserve_hold" + + def test_winter_peak_discharges(self) -> None: + ts = _ts(2026, 1, 15, 17) # January, 5 PM (winter peak) + result = resolve_tou_dispatch( + ts, + _TZ, + _DEFAULT_RECORD, + soe_pct=60.0, + backup_reserve_pct=20.0, + max_charge_w=3500.0, + max_discharge_w=3500.0, + pv_excess_w=0.0, + load_deficit_w=1500.0, + ) + assert result.state == "discharging" + assert result.reason == "peak_discharge" + + +class TestPartialPeakDispatch: + """Partial-peak hours use self-consumption (no grid interaction).""" + + def test_partial_peak_with_deficit_discharges(self) -> None: + ts = _ts(2026, 7, 15, 15) # July, 3 PM (partial-peak) + result = resolve_tou_dispatch( + ts, + _TZ, + _DEFAULT_RECORD, + soe_pct=70.0, + backup_reserve_pct=20.0, + max_charge_w=3500.0, + max_discharge_w=3500.0, + pv_excess_w=0.0, + load_deficit_w=1000.0, + ) + assert result.state == "discharging" + assert result.reason == "selfcon_discharge" + + def test_partial_peak_with_pv_excess_charges_solar(self) -> None: + ts = _ts(2026, 7, 15, 15) + result = resolve_tou_dispatch( + ts, + _TZ, + _DEFAULT_RECORD, + soe_pct=70.0, + backup_reserve_pct=20.0, + max_charge_w=3500.0, + max_discharge_w=3500.0, + pv_excess_w=800.0, + load_deficit_w=0.0, + ) + assert result.state == "charging" + assert result.reason == "selfcon_solar_charge" + assert result.requested_power_w == 800.0 + + def test_partial_peak_balanced_idles(self) -> None: + ts = _ts(2026, 7, 15, 22) # July, 10 PM (partial-peak) + result = resolve_tou_dispatch( + ts, + _TZ, + _DEFAULT_RECORD, + soe_pct=50.0, + backup_reserve_pct=20.0, + max_charge_w=3500.0, + max_discharge_w=3500.0, + pv_excess_w=0.0, + load_deficit_w=0.0, + ) + assert result.state == "idle" + assert result.reason == "selfcon_idle" + + +class TestSeasonalVariation: + """Same hour produces different dispatch in different months.""" + + def test_hour_17_summer_is_peak(self) -> None: + ts = _ts(2026, 7, 15, 17) + result = resolve_tou_dispatch( + ts, + _TZ, + _DEFAULT_RECORD, + soe_pct=60.0, + backup_reserve_pct=20.0, + max_charge_w=3500.0, + max_discharge_w=3500.0, + pv_excess_w=0.0, + load_deficit_w=2000.0, + ) + assert result.reason == "peak_discharge" + + def test_hour_17_winter_is_also_peak(self) -> None: + """Winter period 3 ($0.384) is the max for winter — still peak.""" + ts = _ts(2026, 1, 15, 17) + result = resolve_tou_dispatch( + ts, + _TZ, + _DEFAULT_RECORD, + soe_pct=60.0, + backup_reserve_pct=20.0, + max_charge_w=3500.0, + max_discharge_w=3500.0, + pv_excess_w=0.0, + load_deficit_w=2000.0, + ) + assert result.reason == "peak_discharge" + + +class TestWeekdayWeekend: + """Weekday vs weekend uses the correct schedule matrix.""" + + def test_different_schedule_on_weekend(self) -> None: + """Use a record where weekend has flat rates (all same period).""" + flat_weekend_row = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0] + record = _build_rate_record( + weekend_schedule=[flat_weekend_row] * 12, + ) + # Saturday, July 18 2026 = Saturday + ts = _ts(2026, 7, 18, 17) # Would be peak on weekday + result = resolve_tou_dispatch( + ts, + _TZ, + record, + soe_pct=60.0, + backup_reserve_pct=20.0, + max_charge_w=3500.0, + max_discharge_w=3500.0, + pv_excess_w=0.0, + load_deficit_w=2000.0, + ) + # Flat rate → self-consumption fallback + assert result.reason == "selfcon_discharge" + + def test_weekday_uses_weekday_schedule(self) -> None: + # Wednesday, July 15 2026 + ts = _ts(2026, 7, 15, 17) + result = resolve_tou_dispatch( + ts, + _TZ, + _DEFAULT_RECORD, + soe_pct=60.0, + backup_reserve_pct=20.0, + max_charge_w=3500.0, + max_discharge_w=3500.0, + pv_excess_w=0.0, + load_deficit_w=2000.0, + ) + assert result.reason == "peak_discharge" + + +class TestFlatRate: + """Flat rate (single period) falls back to self-consumption.""" + + def test_flat_rate_with_deficit_discharges(self) -> None: + flat_row = [0] * 24 + record = { + "energyratestructure": [[{"rate": 0.30, "unit": "kWh"}]], + "energyweekdayschedule": [flat_row] * 12, + "energyweekendschedule": [flat_row] * 12, + } + ts = _ts(2026, 7, 15, 17) + result = resolve_tou_dispatch( + ts, + _TZ, + record, + soe_pct=60.0, + backup_reserve_pct=20.0, + max_charge_w=3500.0, + max_discharge_w=3500.0, + pv_excess_w=0.0, + load_deficit_w=2000.0, + ) + assert result.state == "discharging" + assert result.reason == "selfcon_discharge" + + +class TestEdgeCases: + """Empty/missing data and boundary conditions.""" + + def test_empty_rate_record_idles(self) -> None: + result = resolve_tou_dispatch( + _ts(2026, 7, 15, 12), + _TZ, + {}, + soe_pct=50.0, + backup_reserve_pct=20.0, + max_charge_w=3500.0, + max_discharge_w=3500.0, + pv_excess_w=0.0, + load_deficit_w=0.0, + ) + assert result.state == "idle" + assert result.reason == "no_rate_data" + + def test_missing_schedule_idles(self) -> None: + record = {"energyratestructure": _RATE_STRUCTURE} + result = resolve_tou_dispatch( + _ts(2026, 7, 15, 12), + _TZ, + record, + soe_pct=50.0, + backup_reserve_pct=20.0, + max_charge_w=3500.0, + max_discharge_w=3500.0, + pv_excess_w=0.0, + load_deficit_w=0.0, + ) + assert result.state == "idle" + assert result.reason == "no_rate_data" + + def test_pv_excess_clamped_to_max_charge(self) -> None: + ts = _ts(2026, 7, 15, 10) # off-peak + result = resolve_tou_dispatch( + ts, + _TZ, + _DEFAULT_RECORD, + soe_pct=50.0, + backup_reserve_pct=20.0, + max_charge_w=3500.0, + max_discharge_w=3500.0, + pv_excess_w=5000.0, + load_deficit_w=0.0, + ) + assert result.state == "charging" + assert result.requested_power_w == 3500.0 diff --git a/tests/test_energy/test_tou_integration.py b/tests/test_energy/test_tou_integration.py new file mode 100644 index 0000000..6c97884 --- /dev/null +++ b/tests/test_energy/test_tou_integration.py @@ -0,0 +1,313 @@ +"""Integration tests: EnergySystem + TOU rate-aware dispatch.""" + +from __future__ import annotations + +from datetime import datetime +from typing import Any +from zoneinfo import ZoneInfo + +from span_panel_simulator.energy.system import EnergySystem +from span_panel_simulator.energy.types import ( + BESSConfig, + EnergySystemConfig, + GridConfig, + LoadConfig, + PowerInputs, + PVConfig, +) + +_TZ = ZoneInfo("America/Los_Angeles") +_TZ_STR = "America/Los_Angeles" + + +def _ts(year: int, month: int, day: int, hour: int) -> float: + return datetime(year, month, day, hour, tzinfo=_TZ).timestamp() + + +# -- PG&E E-ELEC-like rate fixture (same as unit tests) ------------------ + +_SUMMER_ROW = [2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 1, 0, 0, 0, 0, 0, 1, 1, 1] +_WINTER_ROW = [5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 4, 3, 3, 3, 3, 3, 4, 4, 4] + +_RATE_STRUCTURE: list[list[dict[str, Any]]] = [ + [{"rate": 0.61578, "unit": "kWh"}], # P0 - summer peak + [{"rate": 0.45390, "unit": "kWh"}], # P1 - summer partial-peak + [{"rate": 0.39722, "unit": "kWh"}], # P2 - summer off-peak + [{"rate": 0.38426, "unit": "kWh"}], # P3 - winter peak + [{"rate": 0.36217, "unit": "kWh"}], # P4 - winter partial-peak + [{"rate": 0.34831, "unit": "kWh"}], # P5 - winter off-peak +] + +_WEEKDAY_SCHEDULE = [ + _WINTER_ROW, # Jan + _WINTER_ROW, # Feb + _WINTER_ROW, # Mar + _WINTER_ROW, # Apr + _WINTER_ROW, # May + _SUMMER_ROW, # Jun + _SUMMER_ROW, # Jul + _SUMMER_ROW, # Aug + _SUMMER_ROW, # Sep + _WINTER_ROW, # Oct + _WINTER_ROW, # Nov + _WINTER_ROW, # Dec +] + +_DEFAULT_RECORD: dict[str, Any] = { + "energyratestructure": _RATE_STRUCTURE, + "energyweekdayschedule": _WEEKDAY_SCHEDULE, + "energyweekendschedule": _WEEKDAY_SCHEDULE, +} + + +def _build_system( + rate_record: dict[str, Any] | None = None, + charge_hours: tuple[int, ...] = (), + discharge_hours: tuple[int, ...] = (), + charge_mode: str = "custom", + initial_soe_kwh: float = 8.0, +) -> EnergySystem: + bess = BESSConfig( + nameplate_kwh=13.5, + max_charge_w=3500.0, + max_discharge_w=3500.0, + backup_reserve_pct=20.0, + panel_timezone=_TZ_STR, + charge_mode=charge_mode, + charge_hours=charge_hours, + discharge_hours=discharge_hours, + rate_record=rate_record, + initial_soe_kwh=initial_soe_kwh, + ) + config = EnergySystemConfig( + grid=GridConfig(connected=True), + pv=PVConfig(nameplate_w=6000.0), + bess=bess, + loads=[LoadConfig()], + ) + return EnergySystem.from_config(config) + + +# -- Task 6 Step 1: Seasonal dispatch changes ---------------------------- + + +class TestSeasonalDispatch: + """Verify dispatch adapts to summer vs winter rate schedules.""" + + def test_summer_peak_discharges(self) -> None: + sys = _build_system(rate_record=_DEFAULT_RECORD) + ts = _ts(2026, 7, 15, 17) # July 5 PM — summer peak + inputs = PowerInputs( + pv_available_w=1000.0, + load_demand_w=4000.0, + grid_connected=True, + ) + sys.tick(ts, inputs) + assert sys.bess is not None + assert sys.bess.scheduled_state == "discharging" + + def test_summer_midnight_charges(self) -> None: + sys = _build_system(rate_record=_DEFAULT_RECORD) + ts = _ts(2026, 7, 15, 0) # July midnight — summer off-peak + inputs = PowerInputs( + pv_available_w=0.0, + load_demand_w=500.0, + grid_connected=True, + ) + sys.tick(ts, inputs) + assert sys.bess is not None + assert sys.bess.scheduled_state == "charging" + + def test_winter_peak_discharges(self) -> None: + sys = _build_system(rate_record=_DEFAULT_RECORD) + ts = _ts(2026, 1, 15, 17) # January 5 PM — winter peak + inputs = PowerInputs( + pv_available_w=0.0, + load_demand_w=3000.0, + grid_connected=True, + ) + sys.tick(ts, inputs) + assert sys.bess is not None + assert sys.bess.scheduled_state == "discharging" + + def test_winter_midnight_charges(self) -> None: + sys = _build_system(rate_record=_DEFAULT_RECORD) + ts = _ts(2026, 1, 15, 0) # January midnight — winter off-peak + inputs = PowerInputs( + pv_available_w=0.0, + load_demand_w=500.0, + grid_connected=True, + ) + sys.tick(ts, inputs) + assert sys.bess is not None + assert sys.bess.scheduled_state == "charging" + + +# -- Task 6 Step 2: Weekday vs weekend ----------------------------------- + + +class TestWeekdayWeekendDispatch: + """Verify dispatch uses the correct schedule matrix by day-type.""" + + def test_weekday_peak_discharges(self) -> None: + """Wednesday July 15, 2026 at 5 PM — weekday peak.""" + sys = _build_system(rate_record=_DEFAULT_RECORD) + ts = _ts(2026, 7, 15, 17) + inputs = PowerInputs( + pv_available_w=0.0, + load_demand_w=3000.0, + grid_connected=True, + ) + sys.tick(ts, inputs) + assert sys.bess is not None + assert sys.bess.scheduled_state == "discharging" + + def test_weekend_with_different_schedule(self) -> None: + """Weekend schedule is flat → self-consumption fallback.""" + flat_row = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0] + record: dict[str, Any] = { + "energyratestructure": _RATE_STRUCTURE, + "energyweekdayschedule": _WEEKDAY_SCHEDULE, + "energyweekendschedule": [flat_row] * 12, + } + sys = _build_system(rate_record=record) + # Saturday July 18, 2026 + ts = _ts(2026, 7, 18, 17) + inputs = PowerInputs( + pv_available_w=0.0, + load_demand_w=3000.0, + grid_connected=True, + ) + sys.tick(ts, inputs) + assert sys.bess is not None + # Flat rate on weekend → self-consumption discharge (not peak_discharge) + assert sys.bess.scheduled_state == "discharging" + + +# -- Task 6 Step 3: Partial-peak self-consumption ------------------------ + + +class TestPartialPeakSelfConsumption: + """Partial-peak hours should provide self-consumption, not idle.""" + + def test_partial_peak_with_deficit_discharges(self) -> None: + sys = _build_system(rate_record=_DEFAULT_RECORD) + ts = _ts(2026, 7, 15, 15) # 3 PM summer partial-peak + inputs = PowerInputs( + pv_available_w=500.0, + load_demand_w=3000.0, + grid_connected=True, + ) + sys.tick(ts, inputs) + assert sys.bess is not None + assert sys.bess.scheduled_state == "discharging" + + def test_partial_peak_with_pv_excess_charges_solar_only(self) -> None: + sys = _build_system(rate_record=_DEFAULT_RECORD) + ts = _ts(2026, 7, 15, 15) # 3 PM partial-peak + inputs = PowerInputs( + pv_available_w=5000.0, + load_demand_w=2000.0, + grid_connected=True, + ) + sys.tick(ts, inputs) + assert sys.bess is not None + assert sys.bess.scheduled_state == "charging" + # Should charge from PV excess (3000 W), clamped to max_charge + assert sys.bess.requested_power_w <= 3500.0 + + def test_partial_peak_balanced_idles(self) -> None: + sys = _build_system(rate_record=_DEFAULT_RECORD) + ts = _ts(2026, 7, 15, 22) # 10 PM partial-peak + inputs = PowerInputs( + pv_available_w=0.0, + load_demand_w=0.0, + grid_connected=True, + ) + sys.tick(ts, inputs) + assert sys.bess is not None + assert sys.bess.scheduled_state == "idle" + + +# -- Task 6 Step 4: Flat-rate fallback ----------------------------------- + + +class TestFlatRateFallback: + """Flat-rate plan should fall back to self-consumption.""" + + def test_flat_rate_self_consumption(self) -> None: + flat_row = [0] * 24 + record: dict[str, Any] = { + "energyratestructure": [[{"rate": 0.30, "unit": "kWh"}]], + "energyweekdayschedule": [flat_row] * 12, + "energyweekendschedule": [flat_row] * 12, + } + sys = _build_system(rate_record=record) + ts = _ts(2026, 7, 15, 17) + inputs = PowerInputs( + pv_available_w=0.0, + load_demand_w=3000.0, + grid_connected=True, + ) + sys.tick(ts, inputs) + assert sys.bess is not None + # Flat rate: self-consumption discharge + assert sys.bess.scheduled_state == "discharging" + + +# -- Task 6 Step 5: Backward compat — no rate record, static hours ------- + + +class TestStaticHoursFallback: + """With rate_record=None, the old static-schedule behaviour is preserved.""" + + def test_static_discharge_hours(self) -> None: + sys = _build_system( + rate_record=None, + charge_hours=(0, 1, 2, 3), + discharge_hours=(16, 17, 18, 19), + ) + # Hour 17 is in discharge_hours + ts = _ts(2026, 7, 15, 17) + inputs = PowerInputs( + pv_available_w=0.0, + load_demand_w=3000.0, + grid_connected=True, + ) + sys.tick(ts, inputs) + assert sys.bess is not None + assert sys.bess.scheduled_state == "discharging" + + def test_static_charge_hours(self) -> None: + sys = _build_system( + rate_record=None, + charge_hours=(0, 1, 2, 3), + discharge_hours=(16, 17, 18, 19), + ) + # Hour 2 is in charge_hours + ts = _ts(2026, 7, 15, 2) + inputs = PowerInputs( + pv_available_w=0.0, + load_demand_w=500.0, + grid_connected=True, + ) + sys.tick(ts, inputs) + assert sys.bess is not None + assert sys.bess.scheduled_state == "charging" + + def test_static_idle_hours(self) -> None: + sys = _build_system( + rate_record=None, + charge_hours=(0, 1, 2, 3), + discharge_hours=(16, 17, 18, 19), + ) + # Hour 10 is neither charge nor discharge + ts = _ts(2026, 7, 15, 10) + inputs = PowerInputs( + pv_available_w=0.0, + load_demand_w=500.0, + grid_connected=True, + ) + sys.tick(ts, inputs) + assert sys.bess is not None + assert sys.bess.scheduled_state == "idle" From d4d2d495f61cb27a826e9f1a4331c1401af92d48 Mon Sep 17 00:00:00 2001 From: cayossarian <23534755+cayossarian@users.noreply.github.com> Date: Thu, 2 Apr 2026 16:03:44 -0700 Subject: [PATCH 30/35] Fix savings sign convention in modeling cost comparison MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Positive savings (After cheaper than Before) now shows +$X, negative savings (After more expensive) shows −$X. Previously the sign was inverted — a real savings of $203 displayed as −$203. --- .../dashboard/templates/partials/modeling_view.html | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/span_panel_simulator/dashboard/templates/partials/modeling_view.html b/src/span_panel_simulator/dashboard/templates/partials/modeling_view.html index 65f1409..fcf3211 100644 --- a/src/span_panel_simulator/dashboard/templates/partials/modeling_view.html +++ b/src/span_panel_simulator/dashboard/templates/partials/modeling_view.html @@ -613,11 +613,11 @@