diff --git a/addon/suncore/DOCS.md b/addon/suncore/DOCS.md index 3a5ad2e..bcc3048 100644 --- a/addon/suncore/DOCS.md +++ b/addon/suncore/DOCS.md @@ -105,6 +105,19 @@ run against real hardware yet; the guide lists what is unverified. Change options on the app's **Configuration** tab and restart the app. +## Expert settings (environment variables) + +Some timing and budget settings of the price service and the planner are not app options +(keep the Configuration tab simple). Experts can set them as environment variables of the container: + +| Variable | Default | Description | +|---|---|---| +| `SUNCORE_TARIFF_REFRESH_INTERVAL_S` | `3600` | Spacing of the regular price refresh in seconds (60–86400). | +| `SUNCORE_TARIFF_TOMORROW_AFTER` | `13:00` | Local time from which tomorrow's day-ahead prices are expected. | +| `SUNCORE_TARIFF_TOMORROW_POLL_S` | `900` | Spacing of the asks between that time and the arrival of tomorrow's prices. | +| `SUNCORE_PLANNER_BUDGET_S` | `8` | Time budget of one planner run in seconds (0.5–120); the rule-based plan covers a miss. | +| `SUNCORE_PLANNER_MIP_GAP` | `0.01` | Accepted distance from the optimum of the planner's solver (0–0.5). | + ## Demo mode With `demo_mode` switched on, SunCore does not read your entities. A diff --git a/addon/suncore_beta/DOCS.md b/addon/suncore_beta/DOCS.md index 36975b2..76c640b 100644 --- a/addon/suncore_beta/DOCS.md +++ b/addon/suncore_beta/DOCS.md @@ -108,6 +108,19 @@ run against real hardware yet; the guide lists what is unverified. Change options on the app's **Configuration** tab and restart the app. +## Expert settings (environment variables) + +Some timing and budget settings of the price service and the planner are not app options +(keep the Configuration tab simple). Experts can set them as environment variables of the container: + +| Variable | Default | Description | +|---|---|---| +| `SUNCORE_TARIFF_REFRESH_INTERVAL_S` | `3600` | Spacing of the regular price refresh in seconds (60–86400). | +| `SUNCORE_TARIFF_TOMORROW_AFTER` | `13:00` | Local time from which tomorrow's day-ahead prices are expected. | +| `SUNCORE_TARIFF_TOMORROW_POLL_S` | `900` | Spacing of the asks between that time and the arrival of tomorrow's prices. | +| `SUNCORE_PLANNER_BUDGET_S` | `8` | Time budget of one planner run in seconds (0.5–120); the rule-based plan covers a miss. | +| `SUNCORE_PLANNER_MIP_GAP` | `0.01` | Accepted distance from the optimum of the planner's solver (0–0.5). | + ## Demo mode With `demo_mode` switched on, SunCore does not read your entities. A diff --git a/docs/STATUS.md b/docs/STATUS.md index c19975d..de6bca3 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -3,10 +3,12 @@ Read this first in every session, then `CLAUDE.md` (once it exists) and the ADRs relevant to your task. Keep it short; history lives in git. -**Last update:** 2026-10-22 · **Phase:** 4 in progress – PR 4-A contracts, PR 4-B storage, PR 4-D PV -forecast, PR 4-E load forecast and risk model; Phase 3 (3-A `phase-3/a-safety`, 3-B -`phase-3/b-controller`, 3-C `phase-3/c-ui`) implemented, waiting for the maintainer's shadow test · -**Branch:** `phase-4/e-load-risk` (stacked on `phase-4/d-pv-forecast`) +**Last update:** 2026-10-24 · **Phase:** 4 in progress – PR 4-A contracts, 4-B storage, 4-C +tariffs, 4-D PV forecast, 4-E load forecast and risk model, 4-F planner and runtime (WP8, WP9; +battery control WP10 next); Phase 3 (3-A +`phase-3/a-safety`, 3-B `phase-3/b-controller`, 3-C `phase-3/c-ui`) implemented, waiting for the +maintainer's shadow test · **Branch:** `phase-4/f-planner` (stacked on `phase-4/e-load-risk`, merged +with `phase-4/c-tariff`) ## Done @@ -97,6 +99,93 @@ forecast, PR 4-E load forecast and risk model; Phase 3 (3-A `phase-3/a-safety`, - Follow-ups: the weights come from the *uncalibrated* sources' MAE (a calibrated source is under-weighted until a calibrated accuracy is scored); no UI yet (4-H). +- **Phase 4 – PR 4-F, part WP8 planner (branch `phase-4/f-planner`, on 4-E merged with 4-C)**: + - `suncore/planner/` (depends on `core` only; boundary test extended; `mypy --strict`): + `inputs.py` (`build_inputs`: pure snapshot on the 15-minute grid now → +48 h from the + tariff, PV and base-load forecasts, the risk model's morning buffer and evening target, + `goals.battery_target` as a timed goal on every day, devices with window masks; `spot_only` + prices without a formula are refused → `price_mode = flat` + `planner.fallback.spot_without_formula`; + missing prices filled with the median and reported), `model.py` (sparse LP for HiGHS behind + the `SolverBackend` protocol, `HighsBackend`; PV serves the base load first, devices draw only + PV surplus - "no import for devices" holds structurally; soft targets with penalties; no + binaries in Phase 4), `heuristic.py` (rule-based fallback on the same flows), `explain.py` + (reasons per interval from binding targets and price comparisons), `run.py` (`plan()`/`run()`: + heuristic first as fallback and yardstick, solver within the budget, warm start from the + previous plan, fallback chain timeout/infeasible/error/invalid/solver missing → heuristic). + `highspy` 1.15.1 (+ NumPy 2.5.4) are runtime dependencies now. + - Plan v2, additive: `BatteryBand.grid_charge_max_w` / `discharge_lock` (ADR-0013; set by the + planner, the controller still ignores them until 4-G - tested), `IntervalFlows.devices_w` / + `curtail_w` (so the expected flows balance). + - Device budget: before every evening/user target devices may only take what a battery-first + day on P50 could spare plus the PV overflow it cannot absorb (review D4). + - Tests: hypothesis properties (balance, SoC corridor, bounds, grid charging only inside the + policy, no export at a negative export price, devices ≤ PV surplus, objective LP ≤ heuristic + under one cost function, missed targets only when infeasible - checked by a max-SoC LP, every + interval has catalogued reasons), scenarios `sunny_day`, `mixed_clouds`, `two_poor_days`, + `forecast_too_optimistic` (rolling replay), `negative_prices`, `price_spike`, + `grid_charge_price_level`, `prefer_full`, `reference_house` (`suncore/sim/planner_scenarios.py`), + fallback chain with fake backends; planner coverage 95 %. + - Benchmark `scripts/bench_planner.py` (reference house: 17 kWp east-west, 29.6 kWh/10 kW, + 13.5 kW export limit, Tibber-like 48 h, blended EEG, two climate devices; 193 slots, 2318 + variables, 413 rows, 0 binaries): session container amd64 (CPython 3.13) median of 7 runs - + HiGHS solve 4 ms cold (244 simplex iterations) / 4 ms warm (141), heuristic 1 ms, whole + `run()` incl. explanations 29 ms, inputs incl. risk targets 14 ms. After the review fixes + (2026-10-24): solve 3.8 ms cold (284 iterations) / 4.0 ms warm (207), heuristic 0.9 ms, + `run()` 24 ms, inputs 10 ms. Slow test: < 3 s on CI. aarch64 not measured yet (`UNVERIFIED`). + - Review fixes (2026-10-24, lead decisions D1-D4 and the reviewer/`control-safety` findings, + plan §"Deviations" "PR 4-F review"): target floor under a plan in the controller, no grid + charging without a known price, curtailment in negative-rule slots, device budget on P50 plus + overflow, early-charge tie-breaker, full evening target at the evening deficit, buffer reason + and priority bounded to the buffer's day, flat 500 W without a load forecast, + `IntervalPrices.estimated`, optional `PlanInterval.battery`, band hysteresis, 409 for + `GET /plan` and `/plan/status`, plan age from the hand-over, flapping-band and shadow tests, + GIL test, flaky 0.1 s timeout test fixed, NumPy declared. + - The runtime, scheduler and API followed in WP9 (next entry). + +- **Phase 4 – PR 4-F, part WP9 planner runtime (branch `phase-4/f-planner`)**: + - `suncore/app/planning.py` `PlanningService` (time injected twice: `clock`, `sleep`; polled every + 5 s): first run once prices and forecasts exist (or `first_run_grace_s` = 300 s after the first + connection, the gaps are plan reasons; without the battery SoC no plan at all), then every + quarter hour + 20 s, and on events - new prices (tariff listener), forecast update (new + listeners on the PV and load services), configuration change (`site`, `region`, `tariff`, + `forecast`, `battery`, `goals`, `devices`), user override, manual replan, **deviation**: live + SoC differs from the plan's SoC at `now` (linear inside the interval) by > 10 %-points, or the + grid power differs from the planned net power by > 1500 W for 30 min (10-minute exponential + average, so a cloud does not count; a new plan restarts the count). Event runs are debounced + (>= 60 s between starts, merged into one run), single flight, the solve runs in a **daemon + thread** with budget 8 s (`SUNCORE_PLANNER_BUDGET_S`, `SUNCORE_PLANNER_MIP_GAP`), warm start + from the previous plan, a run is abandoned after budget + 30 s (no second thread starts while + the first lives). Inputs: `Runtime._collect_planning` -> `build_inputs` (tariff prices, blended + PV, base-load forecast, `RiskView` buffer/target/`evening_at`, battery section, live SoC from + the flows, `export_limit_w(site)`, `grid.import_limit_w`, devices). A plan snapshot is stored + per run (`PlanSnapshotStore`). + - Hand-over: `ControlStack(plan_provider=planning.active_plan)` (`set_plan` for static use), + read once per tick; the provider survives stack rebuilds. A failed or skipped run keeps the last + good plan; **after 2 h it is stale** (flagged in the API) **and the controller gets + `Plan.default()`**, as it does when every interval is in the past. + - Controller (for the `control-safety` review): `battery_share_available` judges + `BatteryBand.priority_until_soc_pct` against the live SoC every tick (battery first while the + SoC is below it or unknown, before `charge_from_surplus`); a band applies only while a plan + interval covers `now` (before: a non-default plan outside its intervals used the empty default + band). Nothing else changed: device bands only restrict (`allowed`, `max_power_w`), + `preference` is ignored, no `BatteryAction` is ever proposed and the gate still rejects it. + Tests: `tests/controller/test_plan_handover.py` (hypothesis: bands never raise a device above + the plan-less controller, below the priority no more surplus for consumers), + `tests/sim/test_planner_shadow.py` (scenario `planner_in_shadow`: plan every quarter hour, bands + followed, nothing written, gate rejects `BatteryAction` with a plan present). + - API: `GET /api/v1/plan?hours=` (`PlanView`: plan, `stale`, `expired`, `in_use`, `fallback`), + `GET /api/v1/plan/status` (`PlanStatusView`), `POST /api/v1/plan/replan` (202, `ReplanAck`, + 409 `api.error.planning_unavailable`), live message `{type: "plan"}` (summary only). New + catalogue keys `planner.status.*` and `api.error.planning_unavailable` (en/de); OpenAPI and + frontend types regenerated, no UI (4-H). + - Runtime: created in `prepare()`, started after the stack, cancelled with the storage tasks and + awaited **after** `stack.shutdown()` (a hanging planner never delays the release - tested). + Demo: the planner runs on the simulated Tibber prices, Solcast/Open-Meteo/Forecast.Solar and the + cold-start load profile (`/api/v1/plan` shows a real plan; the same inputs give the same plan). + - Not done / follow-ups: the stored snapshots are not read back at start (the first run after a + restart plans cold); device `max_w` comes from the configuration, not the learned power models; + `UNVERIFIED`: planner run time on aarch64 and under the full demo load. + - **Phase 4 – PR 4-E (WP6 load forecast, WP7 risk model; branch `phase-4/e-load-risk`, stacked on 4-D)**: - WP6 `suncore/forecast/load.py` + `load_service.py`: base load = `site.house_w` minus every @@ -424,9 +513,37 @@ forecast, PR 4-E load forecast and risk model; Phase 3 (3-A `phase-3/a-safety`, (WP3) → 4-C tariffs (WP4) and 4-D PV forecast (WP5) → 4-E load + risk (WP6, WP7) → 4-F planner and runtime (WP8, WP9) → 4-G battery control (WP10) → 4-H frontend + docs (WP11, WP13); 4-I ML load (WP12, optional, after 4-E). Merge only after the Phase 3 acceptance. -- **ADR-0013 must be accepted before WP10** (4-G). Its contract changes (`BatteryAction` `None` = - baseline, `BatteryBand.grid_charge_max_w`/`discharge_lock`, `effective_reserve_pct`, - `battery_identity`) land at the start of 4-G, after the maintainer accepted it. +- **ADR-0013 must be accepted before WP10** (4-G). Its contract changes `BatteryBand.grid_charge_max_w` + / `discharge_lock` landed with WP8 (additive, planner-only, the controller ignores them); + `BatteryAction` `None` = baseline and `battery_identity` land at the start of 4-G. +- **WP9 done** (4-F, see Done); next: 4-G battery control (WP10, ADR-0013 first). +- **PR 4-C (WP4, branch `phase-4/c-tariff`)**: `suncore/tariff/` - a template-driven price adapter + (`engine.py`: action or attribute source, list or mapping shape, per-MWh conversion, native grid + from `end - start` or the timestamp spacing, 15/60-minute mixes as segments, gaps `None`, DST + safe; a kWh/MWh unit mismatch between sensor and template is refused), fixed and HT/NT sources, + `PriceFormula` on spot-only sources only, export fixed/tiered/none, the region's + `no_remuneration` rule (export price 0 in slots with a negative spot price; for all-in sources the + import end price is the proxy), `TariffService` (refresh hourly, on entity change for attribute + sources, every 15 min from 13:00 local until tomorrow's prices arrive, back-off after failures, + throttled calls are not failures, good data is never replaced by an empty or failed fetch, + prices stored in `timeseries.db`) and `GET /api/v1/prices?hours=48`. Templates `tibber.price` + (updated), `nordpool.price`, `entsoe.price` (+`_mwh`), `epex_spot.total_price`/`market_price`, + `octopus_energy.rates`, `generic.price_list`; schema changes are additive (templates README + changelog). Wiring in `suncore/app/adapters.py`; demo and simulator: the fake answers + `tibber.get_prices` through the same template path, scenario `negative_prices`. + `PriceFormula.end_price` is the 4-A `apply` under a name the actuator boundary test does not + reserve. `UNVERIFIED`: see the price rows in the table below. + Review fixes: a failing attribute source backs off; a fetch without a known price fails and keeps + the old data (unknown slots are carried over, `quality.carried_slots`); the old tail never overlaps + new data; Nord Pool `date` is the CET delivery day (`date_tz`, research note in + `research/integrations.md`) and "tomorrow covered" ends at the market's day end; a source in + another currency than the region is refused; `segments_from_points` (4-A) treats a multiple-step + hole at the list end as a gap. A spot-only price without a formula is a system-check warning and + `GET /api/v1/prices` says `formula_missing: true` with the top-level `price_includes`. + **For 4-F: the planner must refuse `spot_only` import prices without a formula (it must not + plan with bare market prices).** Known: the error argument `available` of + `tariff.error.ambiguous_series` carries the home names/areas of the response (shown to the user, + they are needed to choose one). - Maintainer questions from 4-A: plan §6 "Offene Fragen aus PR 4-A" (grid-charge schedule precedence, VAT on negative spot prices, export tiers, grid charging on the Kostal). @@ -622,6 +739,7 @@ forecast, PR 4-E load forecast and risk model; Phase 3 (3-A `phase-3/a-safety`, | Supervisor proxy forwards `recorder/statistics_during_period` (the 4-B rebuild logs a warning and retries) | `suncore/ha/statistics.py` | first run on HA OS | | `change`/`sum` rows of real energy counters (the rebuild reads them as verified from source, not tested against live counters); `backup_exclude` accepts the glob `timeseries.db.corrupt*` | `suncore/ha/statistics.py`, `addon/*/config.yaml` | maintainer's HA with an energy counter; a backup on HA OS | | Publication time of next-day prices (Tibber, Nord Pool, ENTSO-E, EPEX) | `research/integrations.md` | observe on the maintainer's HA | +| Nord Pool `config_entry` id source, sensor translation keys, publication time; Octopus/ENTSO-E/EPEX entity matchers (platform and unit only, no translation keys); `start`/`end` sent to `tibber.get_prices` as ISO with offset; negative-price rule proxy for all-in sources | `templates/tariff/*.yaml`, `suncore/tariff/pricing.py` | live check on a system with the integration | | VAT applied to negative spot prices | `suncore/core/tariff.py` | maintainer's bill / supplier terms | | KNN load model performance on aarch64 | plan WP12 | CI arm runner benchmark | | Energy colour variable names (`--energy-*`) | `frontend/src/app.css` | read HA frontend source | @@ -642,7 +760,9 @@ forecast, PR 4-E load forecast and risk model; Phase 3 (3-A `phase-3/a-safety`, | Forecast.Solar `wh_hours`/`watt_hours_period` keys read as period *start* (vendor API unreachable) | `templates/forecast/forecast_solar.pv.yaml`, `suncore/forecast/pv/parsing.py` | live comparison with the integration's sensors | | Supervisor proxy forwards `energy/solar_forecast` | `suncore/ha/` (`fetch_solar_forecast`) | first run on HA OS | | PV calibration constants (classes kt 0.3/0.65, shrink k = 16, decay 0.98, factor 0.5–1.5) and the clipping thresholds (plateau ±0.3 % for ≥ 1 h on ≥ 2 days; export within max(3 %, 50 W)) are reasoned, not fitted to real data | `suncore/forecast/pv/` | 30+ days of the maintainer's data | -| Solve times on Raspberry Pi 4 | ADR-0003 | Phase 4 benchmark | +| Planner solve times on aarch64 (Raspberry Pi 4, HA Green); amd64: 4 ms solve, 24 ms whole run for the reference house; HiGHS releasing the GIL on aarch64 (measured on amd64) | ADR-0003, `scripts/bench_planner.py`, `tests/planner/test_gil.py` | run the benchmark and the slow tests on a Pi / the CI arm runner | +| Negative-price rule slots in the planner use a proxy (export price ≤ 0 and import price < 0); a spot-only source with a formula whose end price stays positive is not detected | `suncore/planner/inputs.py` | tariff service exposes the rule's slots (Phase 5) | +| Planner weights and rules: target penalties (10 × max price + 1, buffer 2 × + 0.5), terminal value (median import × discharge efficiency − degradation/2), device budget on P50 plus overflow (a day far below P50 can miss the evening target, review D4), flat 500 W base load without a load forecast, automatic device value export + 0.01 | `suncore/planner/model.py`, `inputs.py` | shadow plans on the maintainer's system | | `weather.get_forecasts` `hourly` support of the maintainer's weather integration (the `temperature_unit` attribute and the conversion of the forecast to it are verified from source, `research/ha-websocket-api.md`) | `suncore/app/adapters.py` (`HaLoadReader`) | maintainer's HA | | `workday.check_date` over the Supervisor proxy and with the maintainer's Workday configuration (the `days_offset` handling is verified from source; a changed country/holiday list is not visible in the attributes, so the day-type cache only resets on a changed entity, `workdays`, `excludes` or offset) | `suncore/app/adapters.py`, `suncore/forecast/load_service.py` | maintainer maps a Workday sensor | | Load and risk constants (half-life 21 days, outlier z 3, shrink 3 days, 7 clean days, degree-day bases 15/22 °C, coverage 75 %/90 %, 20 h temperature days, anchors sunrise + 1 h / sunset − 1 h, sunrise threshold 2 %/20 W) and the default PV bands per weather class (clear 0.85/1.10, mixed 0.55/1.35, overcast 0.35/1.70) are reasoned, not fitted | `suncore/forecast/load.py`, `suncore/forecast/risk.py`, `risk_learning.py` | 30+ days of the maintainer's data | diff --git a/docs/architecture.md b/docs/architecture.md index 77c9332..36db97f 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -68,9 +68,7 @@ flowchart TB api --> storage ha --> core forecast --> ha - tariff --> ha - planner --> forecast - planner --> tariff + tariff --> templates planner --> core controller --> core controller --> devices @@ -87,6 +85,7 @@ flowchart TB sched --> planner sched --> controller sched --> forecast + sched --> tariff ``` Dependency rule: arrows point inward to `core/`; `core/` imports nothing @@ -101,7 +100,7 @@ Package map (ADR-0001): | `suncore/core` | Domain model: `Site`, `Asset` (grid, pv, battery, device), `Signal` (typed time series with unit and quality), `Capability`, `Plan`, `Intent`, `Decision`, `Reason`, units and sign conventions | stdlib, pydantic | | `suncore/ha` | `HAConnection` (Supervisor or Direct transport), entity subscription with staleness tracking, service calls with read-back, write rate limiter, registry queries, MQTT discovery publisher | core, aiohttp | | `suncore/forecast` | Adapter protocol + Solcast, Forecast.Solar, Open-Meteo, generic-attribute, built-in model; blending by measured skill; bias calibration; load profiles | core, ha, templates | -| `suncore/tariff` | Import/export price sources (Tibber, Nord Pool, ENTSO-E/EPEX via HACS, fixed, HT/NT), price formula, region profiles, negative-price rules | core, ha, templates | +| `suncore/tariff` | Import/export price sources (Tibber, Nord Pool, ENTSO-E/EPEX via HACS, fixed, HT/NT), price formula, region profiles, negative-price rules (Home Assistant reaches it through an injected action caller and entity reader wired in `suncore/app/adapters.py`) | core, templates | | `suncore/planner` | Model builder, HiGHS solver worker, heuristic fallback, plan explanation, what-if | core, highspy, numpy | | `suncore/controller` | Surplus computation, priority allocation, hysteresis state machines, peak shaving, export limiting, §14a limit | core | | `suncore/safety` | Invariant checks, operating modes, override detection, watchdogs, fail-safe transitions; the only caller of actuators | core, devices | @@ -143,7 +142,11 @@ convert at the boundary (e.g. Kostal reports battery positive = discharging). ## 4. Planner, controller, safety in time The planner arrives in Phase 4; until then the controller consumes `Plan.default()`, which allows -everything. The control layer (Phase 3) is composed in one place, `suncore/app/control.py` +everything. Phase 4 WP8 added `suncore/planner` (`inputs.py` → `model.py` LP for HiGHS behind a +`SolverBackend` protocol → `run.py` with the heuristic fallback and `explain.py` reasons); it +depends on `core` only: the scheduler (WP9) collects prices, forecasts and the risk targets and +hands them over through `build_inputs`, and runs `run()` in a worker thread. +The control layer (Phase 3) is composed in one place, `suncore/app/control.py` (`ControlStack`): entity cache, one driver and one power model per device, the controller (`suncore/controller`), the safety gate with its watchdog (`suncore/safety`) and the connection life cycle. The runtime, the demo and the simulator all use this same stack; only the connection diff --git a/docs/plans/phase-4.md b/docs/plans/phase-4.md index 74a9db8..0d5ac99 100644 --- a/docs/plans/phase-4.md +++ b/docs/plans/phase-4.md @@ -394,6 +394,39 @@ shadow and assisted run is the acceptance test. nicht ausführbar. Reicht das, oder soll eine generische „Zwangsladen“-Entität bzw. später ein eigener §3.4-ADR kommen? +### Offene Fragen aus PR 4-C (an den Maintainer) + +1. **Zusätzliche Tarif-Einstellungen:** Damit Nord Pool (`config_entry`, `areas`), Octopus (zwei + Ereignis-Entitäten), mehrere Tibber-Häuser und ENTSO-E mit eigener Preisformel funktionieren, + bekommt `tariff.import` vier optionale Felder: `role_entities`, `action_params`, `series_key`, + `price_includes` (Aussage des Nutzers, ob die Quelle schon Steuern/Netzentgelte enthält). + Alte Dokumente bleiben gültig. Einverstanden? +2. **Nord Pool `config_entry`:** Die ID des Konfigurationseintrags muss der Nutzer eintragen + (Entwicklerwerkzeuge → Aktionen zeigt sie). Ob SunCore sie aus der Entity-Registry lesen kann, + ist nicht verifiziert (`UNVERIFIED`). Reicht die manuelle Eingabe für Phase 4? +3. **Negativpreis-Regel bei All-in-Quellen (Tibber):** Der Spotpreis ist nicht bekannt; als Ersatz + gilt der Endpreis (Import) < 0. Das markiert weniger Viertelstunden als die echten + Negativ-Spot-Stunden, die Einspeisung wird dann dort noch vergütet gerechnet (`UNVERIFIED` + gegen die Praxis). Alternative: zusätzlich die Spot-Quelle (z. B. EPEX Spot Marktpreis) als + Referenz konfigurieren (Phase 5). Einverstanden mit dem Ersatzwert? +4. **`curtailment_required`:** ändert in Phase 4 keinen Preis (Abregelung ist Sache von + Planer/Regler, nicht des Preises). Nur `no_remuneration` setzt den Einspeisepreis auf 0. +5. **Dynamische Einspeisepreise:** keine der verifizierten Quellen liefert welche; der Einspeisepreis + kommt aus `tariff.export` (fest, gestaffelt, keiner). Octopus-Export-Entitäten sind nicht + angebunden. +6. **HT/NT-Preis:** pro Viertelstunde zum Beginn der Viertelstunde; Fensterkanten, die nicht auf + :00/:15/:30/:45 liegen, wirken ab der nächsten Viertelstunde. +7. **Veröffentlichung der Preise für morgen:** Standard 13:00 Ortszeit, danach alle 15 min bis die + Preise da sind (`UNVERIFIED`; Experten-Umgebungsvariablen `SUNCORE_TARIFF_TOMORROW_AFTER`, + `SUNCORE_TARIFF_TOMORROW_POLL_S`, `SUNCORE_TARIFF_REFRESH_INTERVAL_S`, keine App-Optionen, + dokumentiert in beiden `DOCS.md`). Bitte an deinem System beobachten. +8. **§51 EEG und Inbetriebnahmedatum:** Ob bei negativen Preisen vergütet wird, hängt vom + Inbetriebnahmedatum der Anlage ab. Die Regel kommt heute nur aus dem Regionsprofil (`de`: + `no_remuneration`). Soll es später (Phase 5) pro Anlage eine Abschaltmöglichkeit geben + („diese Anlage wird auch bei negativen Preisen vergütet“)? +9. **Namensabgrenzung:** `PriceFormula.apply` heißt für Aufrufer jetzt `end_price` (der Grenztest + reserviert `.apply(` für den Geräteschreibpfad); `apply` bleibt als Alias. + ## Deviations during implementation - Phase 4 is split into the stacked PRs 4-A…4-I (§3) instead of one PR. @@ -451,6 +484,87 @@ shadow and assisted run is the acceptance test. sensors (`mean`, W); quarter hours with an unmeasured device are left out of a day type's profile once it has 7 fully measured days, before that they are kept and flagged. - The temperature term shifts a forecast day only with ≥ 20 hours of temperatures (m5). +- PR 4-F, WP8 (planner): + - **Flows**: PV serves the base load first; devices draw only the PV surplus over the base + load and the battery discharges only for the base load (never for export, which ADR-0013 + limits cannot express). "SunCore never imports for a device" therefore holds structurally in + the LP, not through a price cap; the automatic device value is the export price + 0.01, an + explicit value is capped at `max(import price, export price + 0.01)`. + - **No binaries** in Phase 4: with that flow split and free curtailment, simultaneous charge + and discharge cannot gain at negative prices; `SolverStats.n_binaries = 0`, the backend + accepts integer columns for Phase 6 device models. + - **Morning buffer**: a soft SoC target at the earliest time a battery-first day reaches it on + P50 (or, when PV cannot, the highest SoC such a day reaches before the coming sunset), plus + "battery first" before that time (surplus beyond the battery's charge limit may go elsewhere, + more costs the buffer penalty). It never makes the plan hold energy or buy it from the grid by + itself. `priority_until_soc_pct` = the buffer until the plan reaches it, at most until the + buffer's goal slot. + - **Device budget**: before each evening/user target the devices may only take what a + battery-first day **on P50** could spare above the target, plus the PV surplus such a day + cannot absorb (charge-power and SoC limits) up to the target. The first version used PV at + the risk quantile; the PR review replaced it (lead decision D4, plan §0: caution enters only + through the WP7 targets). Consequence, measured with a rolling hourly replay of + `forecast_too_optimistic` (P10 = 0.25 × P50): the evening target is met when PV comes in at + ≥ 0.5 × P50 all day; at 0.4 × P50 it is missed by about 5 %-points, because the WP7 morning + buffer's margin does not count the consumers (open question for WP7/the maintainer). + - **Targets** are soft (penalty per kWh of shortfall: buffer `2m + 0.5`, evening/user `10m + 1`, + `m` = largest absolute price), so the model is always feasible and a shortfall is explained + (`planner.battery.target_shortfall`); "relaxed targets" in the fallback chain are therefore + built in. A live SoC below the reserve or above max SoC gets a penalised slack instead of an + infeasible model. + - **Terminal value** of stored energy: `median(import) × discharge efficiency − degradation/2`; + degradation is charged half on charge, half on discharge (= the configured cost per charged + kWh over a cycle). + - **Prices**: missing prices (tomorrow before publication) are filled with the median and + reported; grid charging needs a known price; `spot_only` without a formula and no prices at + all plan in `flat` mode (self-sufficiency only, nominal import price 1, export from the tariff + configuration). On a tariff whose price varies, grid charging needs the spread rule against the + best known later price; on a flat tariff the policy alone decides and the LP charges only when + a target needs it. + - **Inputs are frozen dataclasses**, not Pydantic models (ADR-0003 says "typed Pydantic + inputs"): built once per run by a pure function, validated in `__post_init__`; the outputs are + the Pydantic plan contracts. + - **Plan v2 additions** (additive): `BatteryBand.grid_charge_max_w` / `discharge_lock` + (ADR-0013, moved from 4-G to WP8; the controller ignores them until 4-G) and + `IntervalFlows.devices_w` / `curtail_w`. + - `charge_from_surplus = False` only where the plan gives devices the surplus while no battery + target binds; the Phase 3 controller already reads this flag once a plan is wired (WP9). +- PR 4-F review (2026-10-24), lead decisions by the plan's defaults: + - **D1** `goals.battery_target` stays a floor in the controller under a plan: + `battery_share_available` keeps the battery first while the live SoC is unknown or below the + target, after the band's priority check (property: below `max(priority, target)` a plan never + gives consumers more than Phase 3). + - **D2** no grid charging without a known price: flat mode and unpublished prices give an + allowance of 0, also under a schedule-only policy. + - **D3** where the region's negative-price rule zeroed the export price (proxy: export price + ≤ 0 while the known import price is negative), export costs 0.001/kWh more than curtailment, + so the plan curtails (informational until Phase 6); `planner.export.negative_price_avoided` + only where export is ≈ 0 or at most half the surplus. + - **D4** device budget on P50 plus overflow (above). + - Further: an early-charge tie-breaker (0.0001/kWh falling over the horizon) removes the + late-charging degeneracy; an evening target at max SoC is due at the start of the evening + deficit; the morning-buffer reason names the reachable SoC and `priority_until_soc_pct` ends + with the buffer's goal slot; without a load forecast the plan uses a flat 500 W (or a recent + mean passed by the runtime) and plans no consumers; median-filled prices are flagged + (`IntervalPrices.estimated`, additive) and never cited as "later price"; `violations()` + checks the flow split and the import limit; a slot the previous plan throttled stays tight + within 3 %-points / 100 Wh (band hysteresis); without a planner battery + `PlanInterval.battery` is `None` (contract: now optional) and the goal rules stay in charge; + `GET /api/v1/plan` and `/plan/status` answer 409 without a planner; a plan's age counts from + its hand-over; HiGHS releases the GIL while solving (measured: the event loop's largest gap + stays far below the solve time, slow test), `UNVERIFIED` on aarch64. +- WP4: ENTSO-E and EPEX Spot get two templates each where the unit or the price content differs + (`entsoe.price`/`_mwh`, `epex_spot.total_price`/`market_price`): a template holds one value unit + and one `price_includes`. Octopus is included (its source was verified in 4-A). +- WP9: the solve runs in a daemon thread (`run_in_daemon_thread`), not `asyncio.to_thread`: an + abandoned or hanging solver call must not keep the default executor (and with it the process + shutdown) waiting; a hung thread is never joined and blocks only further planner runs. +- WP9: a plan older than 2 h is *stale* and the controller gets `Plan.default()` from then on + (instead of following it until its intervals run out after up to 48 h): stale or missing plan = + Phase 3 behaviour. The API still serves it, flagged. Deviation thresholds (10 %-points SoC, + 1500 W for 30 min) are the documented first values, not tuned. +- WP9: the controller applies a plan's battery band only while an interval covers `now`, and judges + `priority_until_soc_pct` against the live SoC. ## 7. Out of scope for Phase 4 diff --git a/docs/research/integrations.md b/docs/research/integrations.md index c03ad92..a127b89 100644 --- a/docs/research/integrations.md +++ b/docs/research/integrations.md @@ -266,6 +266,15 @@ exists but is undocumented on the page. The action returns the undivided MWh value; the adapter divides by 1000. The values are the day-ahead market price per area; VAT, grid fees and levies are not part of them (no such field in the source). +- **Meaning of `date` (zone)**: the action passes `date` as `YYYY-MM-DD` to the library + (`home-assistant/core@5cfe9aad7cb428c2c2ebb449719ae81976780de1` + `homeassistant/components/nordpool/services.py:112-125`: `datetime.combine(asked_date, + dt_util.utcnow().time())`), which only formats it with `strftime("%Y-%m-%d")` as the `date` + query parameter of Nord Pool's `DayAheadPrices` (`pynordpool 0.4.0` `__init__.py:106-127`) and + keys the raw response by `deliveryDateCET` (`__init__.py:102`). So `date` is read as the **CET + delivery day** (Central European rules, i.e. `Europe/Berlin`), not the Home Assistant day; the + template sets `date_tz: Europe/Berlin`. Read from source only, the query semantics of the + Nord Pool API itself were not seen live (`UNVERIFIED`). - **Resolution**: slot length = `end - start` per entry (the sensors compute `resolution = entry.end - entry.start`, `sensor.py:58`), 15 or 60 minutes; a coordinator tick every 15 minutes (`coordinator.py:57-73`). The adapter must not diff --git a/docs/user/compatibility.md b/docs/user/compatibility.md index a8c49f4..9105793 100644 --- a/docs/user/compatibility.md +++ b/docs/user/compatibility.md @@ -30,7 +30,14 @@ a template only tested in the simulator has never run against real hardware. | Id | Kind | Name | Integration / platforms | Capabilities | Tested with | Unverified | |---|---|---|---|---|---|---| -| `tibber.price` | tariff | Tibber dynamic price | `tibber` | `price_curve`, `price_now` | not tested on hardware | 4 | +| `entsoe.price` | tariff | ENTSO-E day-ahead price (kWh) | `entsoe` | `price_curve`, `price_now` | not tested on hardware | 4 | +| `entsoe.price_mwh` | tariff | ENTSO-E day-ahead price (MWh scale) | `entsoe` | `price_curve`, `price_now` | not tested on hardware | 4 | +| `epex_spot.market_price` | tariff | EPEX Spot market price | `epex_spot` | `price_curve`, `price_now` | not tested on hardware | 4 | +| `epex_spot.total_price` | tariff | EPEX Spot total price | `epex_spot` | `price_curve`, `price_now` | not tested on hardware | 4 | +| `generic.price_list` | tariff | Generic price list (sensor attribute) | any | `price_curve`, `price_now` | not tested on hardware | 3 | +| `nordpool.price` | tariff | Nord Pool day-ahead price | `nordpool` | `price_curve`, `price_now` | not tested on hardware | 6 | +| `octopus_energy.rates` | tariff | Octopus Energy rates | `octopus_energy` | `price_curve`, `price_now` | not tested on hardware | 4 | +| `tibber.price` | tariff | Tibber dynamic price | `tibber` | `price_curve`, `price_now` | not tested on hardware | 6 | ## PV forecasts diff --git a/frontend/src/lib/api/openapi.json b/frontend/src/lib/api/openapi.json index 2df094b..50f1ed2 100644 --- a/frontend/src/lib/api/openapi.json +++ b/frontend/src/lib/api/openapi.json @@ -88,10 +88,64 @@ "title": "AccuracySourceView", "type": "object" }, + "ActionParam": { + "additionalProperties": false, + "description": "A field of the action's request that the user's tariff configuration supplies.\n\nThe value comes from ``tariff.import.action_params[name]`` (Phase 4 WP4), e.g. the\nNord Pool ``config_entry`` id or ``areas``. SunCore never invents such a value.", + "properties": { + "description": { + "maxLength": 120, + "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+$", + "title": "Description", + "type": "string" + }, + "name": { + "maxLength": 200, + "minLength": 1, + "title": "Name", + "type": "string" + }, + "required": { + "default": true, + "title": "Required", + "type": "boolean" + } + }, + "required": [ + "name", + "description" + ], + "title": "ActionParam", + "type": "object" + }, "ActionSeries": { "additionalProperties": false, "description": "Series returned by a read-only action (``return_response`` is implied).", "properties": { + "date_field": { + "anyOf": [ + { + "maxLength": 200, + "minLength": 1, + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Date Field" + }, + "date_tz": { + "anyOf": [ + { + "pattern": "^[A-Za-z_]+(/[A-Za-z_+\\-0-9]+){1,2}$", + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Date Tz" + }, "domain": { "maxLength": 48, "pattern": "^[a-z][a-z0-9_]*$", @@ -120,9 +174,18 @@ "title": "Max Horizon H", "type": "integer" }, + "params": { + "default": [], + "items": { + "$ref": "#/components/schemas/ActionParam" + }, + "maxItems": 8, + "title": "Params", + "type": "array" + }, "response_path": { "maxLength": 200, - "pattern": "^[A-Za-z0-9_]+(\\.([A-Za-z0-9_]+|\\*))*$", + "pattern": "^(\\*|[A-Za-z0-9_]+)(\\.([A-Za-z0-9_]+|\\*))*$", "title": "Response Path", "type": "string" }, @@ -222,6 +285,16 @@ "title": "AttributeSeries", "type": "object" }, + "BandPreference": { + "description": "What the plan would like the controller to do inside an allowed band.", + "enum": [ + "neutral", + "prefer_on", + "prefer_off" + ], + "title": "BandPreference", + "type": "string" + }, "BatteryAction": { "additionalProperties": false, "description": "Battery limits for the gate (Phase 4 WP2; reviewed by ``control-safety`` in WP10).\n\nEvery field is optional, at least one must be set; a missing field leaves that limit\nas it is. Powers are magnitudes in W (battery + = charging, so ``grid_charge_w`` is a\ncharging power drawn from the grid): ``max_charge_w`` / ``max_discharge_w`` cap the\ninverter's own control, ``min_soc_pct`` is the discharge floor (discharge lock when at\nor above the current SoC), ``grid_charge_w > 0`` asks for forced charging from the\ngrid. ``grid_charge_w`` never exceeds ``max_charge_w`` when both are set (forced\ncharging cannot be above the charge cap, and a cap of 0 forbids it). Until the battery\npath exists the gate rejects this action (``safety.battery_not_supported``); nothing is\nwritten.", @@ -288,6 +361,97 @@ "title": "BatteryAction", "type": "object" }, + "BatteryBand": { + "additionalProperties": false, + "description": "Battery corridor per interval (Phase 4 writes it; Phase 3 reads only ``reserve``).", + "properties": { + "charge_from_surplus": { + "default": true, + "title": "Charge From Surplus", + "type": "boolean" + }, + "discharge_lock": { + "default": false, + "title": "Discharge Lock", + "type": "boolean" + }, + "grid_charge_max_w": { + "anyOf": [ + { + "minimum": 0.0, + "type": "number" + }, + { + "type": "null" + } + ], + "title": "Grid Charge Max W" + }, + "max_power_w": { + "anyOf": [ + { + "type": "number" + }, + { + "type": "null" + } + ], + "title": "Max Power W" + }, + "max_soc_pct": { + "anyOf": [ + { + "maximum": 100.0, + "minimum": 0.0, + "type": "number" + }, + { + "type": "null" + } + ], + "title": "Max Soc Pct" + }, + "min_power_w": { + "anyOf": [ + { + "type": "number" + }, + { + "type": "null" + } + ], + "title": "Min Power W" + }, + "min_soc_pct": { + "anyOf": [ + { + "maximum": 100.0, + "minimum": 0.0, + "type": "number" + }, + { + "type": "null" + } + ], + "title": "Min Soc Pct" + }, + "priority_until_soc_pct": { + "anyOf": [ + { + "maximum": 100.0, + "minimum": 0.0, + "type": "number" + }, + { + "type": "null" + } + ], + "title": "Priority Until Soc Pct" + } + }, + "title": "BatteryBand", + "type": "object" + }, "BatteryConfig": { "additionalProperties": false, "description": "Battery: power (+ = charging), state of charge in percent, limits.\n\n``control`` is ``observe`` only: SunCore reads the battery; adapters that write\nset-points come in a later phase.", @@ -1535,6 +1699,35 @@ "title": "DecisionsMessage", "type": "object" }, + "DeviceBand": { + "additionalProperties": false, + "description": "Per interval and device: what the controller may do and what the planner prefers.", + "properties": { + "allowed": { + "default": true, + "title": "Allowed", + "type": "boolean" + }, + "max_power_w": { + "anyOf": [ + { + "minimum": 0.0, + "type": "number" + }, + { + "type": "null" + } + ], + "title": "Max Power W" + }, + "preference": { + "$ref": "#/components/schemas/BandPreference", + "default": "neutral" + } + }, + "title": "DeviceBand", + "type": "object" + }, "DeviceConfig": { "additionalProperties": false, "description": "One configured device (instance of a template).\n\n``max_switches_per_hour`` / hysteresis / ``settle_s`` ``None`` mean \"safety/controller\ndefault\", never \"unlimited\" or \"none\" (ADR-0012 item 6).\n\nPhase 3 additions (all with defaults, old documents stay valid): ``allow_switch_on``\nand ``switch_on_hvac_mode`` (climate only: SunCore may switch the unit on through the\nHVAC mode; a set-point write while the unit is off also switches it on, see\nresearch/device-integrations.md), ``override_policy``.", @@ -3610,6 +3803,33 @@ "additionalProperties": false, "description": "How the price of imported energy is obtained.\n\n* ``fixed``: one ``fixed_price``.\n* ``dynamic``: a price source (``template_id`` and/or ``price_entity``); ``formula``\n turns a spot-only price into the end price (tariff v3; ``None`` = the source's price\n is used as it is, e.g. Tibber's all-in price).\n* ``tou``: fixed time-of-use prices (HT/NT, seasonal) in ``tou`` (tariff v3).", "properties": { + "action_params": { + "additionalProperties": { + "anyOf": [ + { + "maxLength": 200, + "minLength": 1, + "type": "string" + }, + { + "items": { + "maxLength": 64, + "minLength": 1, + "type": "string" + }, + "maxItems": 16, + "minItems": 1, + "type": "array" + } + ] + }, + "propertyNames": { + "maxLength": 64, + "minLength": 1 + }, + "title": "Action Params", + "type": "object" + }, "fixed_price": { "anyOf": [ { @@ -3652,6 +3872,43 @@ } ] }, + "price_includes": { + "anyOf": [ + { + "enum": [ + "spot_only", + "all_in" + ], + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Price Includes" + }, + "role_entities": { + "patternProperties": { + "^[a-z][a-z0-9_]{0,31}$": { + "$ref": "#/components/schemas/EntityRef" + } + }, + "title": "Role Entities", + "type": "object" + }, + "series_key": { + "anyOf": [ + { + "maxLength": 120, + "minLength": 1, + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Series Key" + }, "template_id": { "anyOf": [ { @@ -3790,57 +4047,198 @@ "title": "Intent", "type": "object" }, - "LearningSettings": { + "IntervalFlows": { "additionalProperties": false, - "description": "What SunCore may learn from history (forecast calibration, load model).\n\nKept in the ``forecast`` section because it governs how forecasts are produced. Before\n``min_history_days`` of history exist, calibration and the ML load model only collect\nstatistics and change nothing. ``load_ml_mode``: ``off``; ``shadow`` (default) = the\noptional ML load model runs in parallel and is only scored and shown for comparison;\n``auto`` = it is used when it beats the profile forecast in the accuracy statistics -\nit never replaces the profiles otherwise.", + "description": "Plan v2: the flows the planner expects in an interval (mean power, W).\n\nSigns per ``core/units.py``: import/export are magnitudes, battery + = charging.\n``pv_p10_w``/``pv_p50_w``/``pv_p90_w`` are the PV forecast's quantiles as forecast data\n(shown in the UI; ``None`` = the source has no quantiles); the objective uses P50.\nBattery targets are *not* planned on P10 PV (plan §0): they use the risk quantile of\nthe learnt **net** energy error distribution (PV minus load) per weather class.\n``net_risk_quantile`` is that quantile (``RiskLevel.quantile``, e.g. 0.1 = cautious)\nand ``net_risk_w`` the net power PV - load at that quantile the target constraints\nused (may be negative; ``None`` = no target constraint in this interval).\n``soc_pct`` is the planned state of charge at the *end* of the interval (``None`` = no\nbattery). ``devices_w`` is the planned draw of the controllable devices (not part of\n``load_w``, the base load) and ``curtail_w`` the PV the plan does not use (export limit\nor negative export price; informational until the export-limit chain, Phase 6), so\n``pv_p50_w + import_w + max(-battery_w, 0) = load_w + devices_w + max(battery_w, 0) +\nexport_w + curtail_w`` (both additive in plan v2, default 0).", "properties": { - "load_ml_mode": { - "default": "shadow", - "enum": [ - "off", - "shadow", - "auto" - ], - "title": "Load Ml Mode", - "type": "string" - }, - "min_history_days": { - "default": 30, - "maximum": 365.0, - "minimum": 1.0, - "title": "Min History Days", - "type": "integer" - } - }, - "title": "LearningSettings", - "type": "object" - }, - "LiveMessage": { - "discriminator": { - "mapping": { - "control": "#/components/schemas/ControlMessage", - "decisions": "#/components/schemas/DecisionsMessage", - "flows": "#/components/schemas/FlowsMessage", - "health": "#/components/schemas/HealthMessage", - "snapshot": "#/components/schemas/SnapshotMessage" + "battery_w": { + "default": 0.0, + "title": "Battery W", + "type": "number" }, - "propertyName": "type" - }, - "oneOf": [ - { - "$ref": "#/components/schemas/SnapshotMessage" + "curtail_w": { + "default": 0.0, + "minimum": 0.0, + "title": "Curtail W", + "type": "number" }, - { - "$ref": "#/components/schemas/FlowsMessage" + "devices_w": { + "default": 0.0, + "minimum": 0.0, + "title": "Devices W", + "type": "number" }, - { - "$ref": "#/components/schemas/HealthMessage" + "export_w": { + "minimum": 0.0, + "title": "Export W", + "type": "number" }, - { - "$ref": "#/components/schemas/DecisionsMessage" + "import_w": { + "minimum": 0.0, + "title": "Import W", + "type": "number" + }, + "load_w": { + "minimum": 0.0, + "title": "Load W", + "type": "number" + }, + "net_risk_quantile": { + "anyOf": [ + { + "exclusiveMaximum": 1.0, + "exclusiveMinimum": 0.0, + "type": "number" + }, + { + "type": "null" + } + ], + "title": "Net Risk Quantile" + }, + "net_risk_w": { + "anyOf": [ + { + "type": "number" + }, + { + "type": "null" + } + ], + "title": "Net Risk W" + }, + "pv_p10_w": { + "anyOf": [ + { + "minimum": 0.0, + "type": "number" + }, + { + "type": "null" + } + ], + "title": "Pv P10 W" + }, + "pv_p50_w": { + "minimum": 0.0, + "title": "Pv P50 W", + "type": "number" + }, + "pv_p90_w": { + "anyOf": [ + { + "minimum": 0.0, + "type": "number" + }, + { + "type": "null" + } + ], + "title": "Pv P90 W" + }, + "soc_pct": { + "anyOf": [ + { + "maximum": 100.0, + "minimum": 0.0, + "type": "number" + }, + { + "type": "null" + } + ], + "title": "Soc Pct" + } + }, + "required": [ + "pv_p50_w", + "load_w", + "import_w", + "export_w" + ], + "title": "IntervalFlows", + "type": "object" + }, + "IntervalPrices": { + "additionalProperties": false, + "description": "Plan v2: end prices (currency/kWh) the planner used; may be negative.", + "properties": { + "estimated": { + "default": false, + "title": "Estimated", + "type": "boolean" + }, + "export_price": { + "title": "Export Price", + "type": "number" + }, + "import_price": { + "title": "Import Price", + "type": "number" + } + }, + "required": [ + "import_price", + "export_price" + ], + "title": "IntervalPrices", + "type": "object" + }, + "LearningSettings": { + "additionalProperties": false, + "description": "What SunCore may learn from history (forecast calibration, load model).\n\nKept in the ``forecast`` section because it governs how forecasts are produced. Before\n``min_history_days`` of history exist, calibration and the ML load model only collect\nstatistics and change nothing. ``load_ml_mode``: ``off``; ``shadow`` (default) = the\noptional ML load model runs in parallel and is only scored and shown for comparison;\n``auto`` = it is used when it beats the profile forecast in the accuracy statistics -\nit never replaces the profiles otherwise.", + "properties": { + "load_ml_mode": { + "default": "shadow", + "enum": [ + "off", + "shadow", + "auto" + ], + "title": "Load Ml Mode", + "type": "string" + }, + "min_history_days": { + "default": 30, + "maximum": 365.0, + "minimum": 1.0, + "title": "Min History Days", + "type": "integer" + } + }, + "title": "LearningSettings", + "type": "object" + }, + "LiveMessage": { + "discriminator": { + "mapping": { + "control": "#/components/schemas/ControlMessage", + "decisions": "#/components/schemas/DecisionsMessage", + "flows": "#/components/schemas/FlowsMessage", + "health": "#/components/schemas/HealthMessage", + "plan": "#/components/schemas/PlanMessage", + "snapshot": "#/components/schemas/SnapshotMessage" + }, + "propertyName": "type" + }, + "oneOf": [ + { + "$ref": "#/components/schemas/SnapshotMessage" + }, + { + "$ref": "#/components/schemas/FlowsMessage" + }, + { + "$ref": "#/components/schemas/HealthMessage" + }, + { + "$ref": "#/components/schemas/DecisionsMessage" }, { "$ref": "#/components/schemas/ControlMessage" + }, + { + "$ref": "#/components/schemas/PlanMessage" } ] }, @@ -4448,101 +4846,597 @@ "title": "OverridePolicy", "type": "object" }, - "PowerEstimate": { + "Plan": { "additionalProperties": false, - "description": "A device's power with its uncertainty (BRIEF §4.5: both power paths are equivalent).\n\n``value_w ± uncertainty_w`` is the band the controller and the grid invariant work\nwith; ``quality`` is the worst quality of the inputs; ``age_s`` is the age of the\nnewest input that produced the estimate.", + "description": "The planner's output as the controller consumes it (ADR-0011).\n\nPhase 3 only ever uses :meth:`Plan.default`, which has no intervals and therefore\nallows everything; the Phase 4 planner fills ``intervals`` without changing the\ncontroller. Intervals must not overlap and are kept in start order.\n\nSchema v2 (Phase 4 WP2, additive): ``source``, ``stats`` and per interval\n``expected``/``prices``/``reasons``. A v1 payload loads unchanged (it keeps\n``schema_version`` 1, ``source = \"default\"``); :func:`plan_from_payload` stamps v2.", "properties": { - "age_s": { - "default": 0.0, - "minimum": 0.0, - "title": "Age S", - "type": "number" + "assumptions": { + "additionalProperties": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "integer" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + }, + "title": "Assumptions", + "type": "object" }, - "quality": { - "$ref": "#/components/schemas/Quality", - "default": "ok" + "created_at": { + "anyOf": [ + { + "format": "date-time", + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Created At" }, - "uncertainty_w": { - "minimum": 0.0, - "title": "Uncertainty W", - "type": "number" + "intervals": { + "default": [], + "items": { + "$ref": "#/components/schemas/PlanInterval" + }, + "title": "Intervals", + "type": "array" }, - "value_w": { - "minimum": 0.0, - "title": "Value W", - "type": "number" + "reasons": { + "default": [], + "items": { + "$ref": "#/components/schemas/Reason" + }, + "title": "Reasons", + "type": "array" + }, + "schema_version": { + "default": 2, + "maximum": 2.0, + "minimum": 1.0, + "title": "Schema Version", + "type": "integer" + }, + "source": { + "default": "default", + "enum": [ + "solver", + "heuristic", + "default" + ], + "title": "Source", + "type": "string" + }, + "stats": { + "anyOf": [ + { + "$ref": "#/components/schemas/SolverStats" + }, + { + "type": "null" + } + ] } }, - "required": [ - "value_w", - "uncertainty_w" - ], - "title": "PowerEstimate", + "title": "Plan", "type": "object" }, - "PowerModel": { + "PlanInterval": { "additionalProperties": false, - "description": "Power source of a device; refers to roles of :attr:`DeviceConfig.entities`.\n\n* ``measured``: needs ``power_role`` (a power sensor).\n* ``counter_derived``: needs ``energy_role``; the average power is derived from counter\n deltas (latency and quantisation apply, ``counter_update_s`` is the latency floor).\n* ``learned``: needs ``nominal_w`` as prior; ``power_role``/``energy_role`` train it.\n* ``nominal``: needs ``nominal_w``.\n\nThe unit of the counter is read from the live state (like ``core/balance.py``); a\nnon-energy unit yields quality ``invalid`` at runtime.", + "description": "One planning interval (15 min grid in Phase 4; any length is accepted).\n\n``expected``, ``prices`` and ``reasons`` are the plan v2 additions for the UI's\n\"Why?\"; the controller reads only the bands and the import limit.", "properties": { - "counter_update_s": { + "battery": { "anyOf": [ { - "maximum": 86400.0, - "minimum": 1.0, - "type": "integer" + "$ref": "#/components/schemas/BatteryBand" }, { "type": "null" } ], - "title": "Counter Update S" + "default": { + "charge_from_surplus": true, + "discharge_lock": false + } }, - "energy_role": { + "devices": { + "additionalProperties": { + "$ref": "#/components/schemas/DeviceBand" + }, + "title": "Devices", + "type": "object" + }, + "end": { + "format": "date-time", + "title": "End", + "type": "string" + }, + "expected": { "anyOf": [ { - "pattern": "^[a-z][a-z0-9_]{0,31}$", - "type": "string" + "$ref": "#/components/schemas/IntervalFlows" }, { "type": "null" } - ], - "title": "Energy Role" - }, - "kind": { - "$ref": "#/components/schemas/PowerModelKind" + ] }, - "nominal_w": { + "grid_import_limit_w": { "anyOf": [ { - "exclusiveMinimum": 0.0, - "maximum": 1000000.0, + "minimum": 0.0, "type": "number" }, { "type": "null" } ], - "title": "Nominal W" + "title": "Grid Import Limit W" }, - "power_role": { + "prices": { "anyOf": [ { - "pattern": "^[a-z][a-z0-9_]{0,31}$", - "type": "string" + "$ref": "#/components/schemas/IntervalPrices" }, { "type": "null" } - ], - "title": "Power Role" + ] }, - "power_update_s": { - "anyOf": [ - { - "maximum": 86400.0, - "minimum": 1.0, - "type": "integer" + "reasons": { + "default": [], + "items": { + "$ref": "#/components/schemas/Reason" + }, + "title": "Reasons", + "type": "array" + }, + "start": { + "format": "date-time", + "title": "Start", + "type": "string" + } + }, + "required": [ + "start", + "end" + ], + "title": "PlanInterval", + "type": "object" + }, + "PlanMessage": { + "additionalProperties": false, + "description": "A new plan was computed (summary only; fetch ``GET /api/v1/plan`` for the intervals).", + "properties": { + "plan": { + "$ref": "#/components/schemas/PlanSummary" + }, + "type": { + "const": "plan", + "default": "plan", + "title": "Type", + "type": "string" + } + }, + "required": [ + "plan" + ], + "title": "PlanMessage", + "type": "object" + }, + "PlanStatusView": { + "additionalProperties": false, + "description": "``GET /api/v1/plan/status``: the scheduler's bookkeeping.", + "properties": { + "consecutive_failures": { + "title": "Consecutive Failures", + "type": "integer" + }, + "earliest_event_run_at": { + "anyOf": [ + { + "format": "date-time", + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Earliest Event Run At" + }, + "generated_at": { + "format": "date-time", + "title": "Generated At", + "type": "string" + }, + "last_duration_s": { + "anyOf": [ + { + "type": "number" + }, + { + "type": "null" + } + ], + "title": "Last Duration S" + }, + "last_finished_at": { + "anyOf": [ + { + "format": "date-time", + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Last Finished At" + }, + "last_ok_at": { + "anyOf": [ + { + "format": "date-time", + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Last Ok At" + }, + "last_outcome": { + "anyOf": [ + { + "enum": [ + "ok", + "failed", + "skipped" + ], + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Last Outcome" + }, + "last_started_at": { + "anyOf": [ + { + "format": "date-time", + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Last Started At" + }, + "last_trigger": { + "anyOf": [ + { + "enum": [ + "start", + "schedule", + "prices", + "forecast", + "deviation", + "config", + "override", + "manual" + ], + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Last Trigger" + }, + "next_scheduled_at": { + "anyOf": [ + { + "format": "date-time", + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Next Scheduled At" + }, + "pending": { + "items": { + "enum": [ + "start", + "schedule", + "prices", + "forecast", + "deviation", + "config", + "override", + "manual" + ], + "type": "string" + }, + "title": "Pending", + "type": "array" + }, + "plan": { + "$ref": "#/components/schemas/PlanSummary" + }, + "reason": { + "anyOf": [ + { + "$ref": "#/components/schemas/Reason" + }, + { + "type": "null" + } + ] + }, + "running": { + "title": "Running", + "type": "boolean" + } + }, + "required": [ + "generated_at", + "running", + "last_trigger", + "last_started_at", + "last_finished_at", + "last_duration_s", + "last_outcome", + "last_ok_at", + "consecutive_failures", + "next_scheduled_at", + "earliest_event_run_at", + "plan" + ], + "title": "PlanStatusView", + "type": "object" + }, + "PlanSummary": { + "additionalProperties": false, + "description": "The live feed's ``plan`` message and the status' short form: no intervals.", + "properties": { + "created_at": { + "anyOf": [ + { + "format": "date-time", + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Created At" + }, + "horizon_end": { + "anyOf": [ + { + "format": "date-time", + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Horizon End" + }, + "in_use": { + "title": "In Use", + "type": "boolean" + }, + "intervals": { + "title": "Intervals", + "type": "integer" + }, + "reasons": { + "items": { + "$ref": "#/components/schemas/Reason" + }, + "title": "Reasons", + "type": "array" + }, + "solve_time_s": { + "anyOf": [ + { + "type": "number" + }, + { + "type": "null" + } + ], + "title": "Solve Time S" + }, + "source": { + "enum": [ + "solver", + "heuristic", + "default" + ], + "title": "Source", + "type": "string" + }, + "stale": { + "title": "Stale", + "type": "boolean" + }, + "status": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Status" + } + }, + "required": [ + "created_at", + "source", + "status", + "solve_time_s", + "intervals", + "horizon_end", + "stale", + "in_use" + ], + "title": "PlanSummary", + "type": "object" + }, + "PlanView": { + "additionalProperties": false, + "description": "``GET /api/v1/plan``: the current plan and whether the controller follows it.\n\n``plan`` is :meth:`Plan.default` (no intervals, ``source = \"default\"``) until the first\nplan exists. ``in_use`` is ``False`` when the plan is stale or has run out: the controller\nthen runs on Phase 3 rules only (``fallback`` says why, as a catalogue reason).", + "properties": { + "expired": { + "title": "Expired", + "type": "boolean" + }, + "fallback": { + "anyOf": [ + { + "$ref": "#/components/schemas/Reason" + }, + { + "type": "null" + } + ] + }, + "generated_at": { + "format": "date-time", + "title": "Generated At", + "type": "string" + }, + "in_use": { + "title": "In Use", + "type": "boolean" + }, + "plan": { + "$ref": "#/components/schemas/Plan" + }, + "stale": { + "title": "Stale", + "type": "boolean" + } + }, + "required": [ + "generated_at", + "plan", + "stale", + "expired", + "in_use" + ], + "title": "PlanView", + "type": "object" + }, + "PowerEstimate": { + "additionalProperties": false, + "description": "A device's power with its uncertainty (BRIEF §4.5: both power paths are equivalent).\n\n``value_w ± uncertainty_w`` is the band the controller and the grid invariant work\nwith; ``quality`` is the worst quality of the inputs; ``age_s`` is the age of the\nnewest input that produced the estimate.", + "properties": { + "age_s": { + "default": 0.0, + "minimum": 0.0, + "title": "Age S", + "type": "number" + }, + "quality": { + "$ref": "#/components/schemas/Quality", + "default": "ok" + }, + "uncertainty_w": { + "minimum": 0.0, + "title": "Uncertainty W", + "type": "number" + }, + "value_w": { + "minimum": 0.0, + "title": "Value W", + "type": "number" + } + }, + "required": [ + "value_w", + "uncertainty_w" + ], + "title": "PowerEstimate", + "type": "object" + }, + "PowerModel": { + "additionalProperties": false, + "description": "Power source of a device; refers to roles of :attr:`DeviceConfig.entities`.\n\n* ``measured``: needs ``power_role`` (a power sensor).\n* ``counter_derived``: needs ``energy_role``; the average power is derived from counter\n deltas (latency and quantisation apply, ``counter_update_s`` is the latency floor).\n* ``learned``: needs ``nominal_w`` as prior; ``power_role``/``energy_role`` train it.\n* ``nominal``: needs ``nominal_w``.\n\nThe unit of the counter is read from the live state (like ``core/balance.py``); a\nnon-energy unit yields quality ``invalid`` at runtime.", + "properties": { + "counter_update_s": { + "anyOf": [ + { + "maximum": 86400.0, + "minimum": 1.0, + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Counter Update S" + }, + "energy_role": { + "anyOf": [ + { + "pattern": "^[a-z][a-z0-9_]{0,31}$", + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Energy Role" + }, + "kind": { + "$ref": "#/components/schemas/PowerModelKind" + }, + "nominal_w": { + "anyOf": [ + { + "exclusiveMinimum": 0.0, + "maximum": 1000000.0, + "type": "number" + }, + { + "type": "null" + } + ], + "title": "Nominal W" + }, + "power_role": { + "anyOf": [ + { + "pattern": "^[a-z][a-z0-9_]{0,31}$", + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Power Role" + }, + "power_update_s": { + "anyOf": [ + { + "maximum": 86400.0, + "minimum": 1.0, + "type": "integer" }, { "type": "null" @@ -4782,6 +5676,44 @@ "title": "PreviewOut", "type": "object" }, + "PriceErrorOut": { + "additionalProperties": false, + "description": "Why the last refresh failed, as a catalogue key.", + "properties": { + "args": { + "additionalProperties": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "integer" + }, + { + "items": { + "type": "string" + }, + "type": "array" + } + ] + }, + "title": "Args", + "type": "object" + }, + "key": { + "title": "Key", + "type": "string" + } + }, + "required": [ + "key" + ], + "title": "PriceErrorOut", + "type": "object" + }, "PriceFormula": { "additionalProperties": false, "description": "Spot price -> end price (BRIEF §4.4).\n\n``end = (spot * spot_multiplier + grid_fee(at) + levies + margin) * (1 + vat_pct/100)``\n\n``grid_fee(at)`` is the fee of the first ``grid_fee_windows`` entry containing ``at``,\nelse ``grid_fee``. VAT is applied to the whole sum, as on a German bill; a negative\nspot price can make the end price negative. Only for ``price_includes = spot_only``\nsources - an all-in price never gets the formula on top.", @@ -4802,36 +5734,342 @@ "title": "Grid Fee Windows", "type": "array" }, - "levies": { - "default": 0.0, - "maximum": 100.0, - "minimum": 0.0, - "title": "Levies", - "type": "number" + "levies": { + "default": 0.0, + "maximum": 100.0, + "minimum": 0.0, + "title": "Levies", + "type": "number" + }, + "margin": { + "default": 0.0, + "maximum": 100.0, + "minimum": 0.0, + "title": "Margin", + "type": "number" + }, + "spot_multiplier": { + "default": 1.0, + "exclusiveMinimum": 0.0, + "maximum": 10.0, + "title": "Spot Multiplier", + "type": "number" + }, + "vat_pct": { + "default": 0.0, + "maximum": 100.0, + "minimum": 0.0, + "title": "Vat Pct", + "type": "number" + } + }, + "title": "PriceFormula", + "type": "object" + }, + "PriceFreshness": { + "additionalProperties": false, + "properties": { + "age_s": { + "anyOf": [ + { + "type": "number" + }, + { + "type": "null" + } + ], + "title": "Age S" + }, + "fetched_at": { + "anyOf": [ + { + "format": "date-time", + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Fetched At" + }, + "known_until": { + "anyOf": [ + { + "format": "date-time", + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Known Until" + }, + "last_error": { + "anyOf": [ + { + "$ref": "#/components/schemas/PriceErrorOut" + }, + { + "type": "null" + } + ] + }, + "next_refresh_at": { + "anyOf": [ + { + "format": "date-time", + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Next Refresh At" + }, + "status": { + "enum": [ + "fresh", + "stale", + "missing", + "static" + ], + "title": "Status", + "type": "string" + } + }, + "required": [ + "status", + "fetched_at", + "age_s", + "known_until", + "next_refresh_at", + "last_error" + ], + "title": "PriceFreshness", + "type": "object" + }, + "PriceQuality": { + "additionalProperties": false, + "properties": { + "carried_slots": { + "default": 0, + "minimum": 0.0, + "title": "Carried Slots", + "type": "integer" + }, + "dropped_points": { + "minimum": 0.0, + "title": "Dropped Points", + "type": "integer" + }, + "has_tomorrow": { + "title": "Has Tomorrow", + "type": "boolean" + }, + "known_slots": { + "minimum": 0.0, + "title": "Known Slots", + "type": "integer" + }, + "slots": { + "minimum": 0.0, + "title": "Slots", + "type": "integer" + } + }, + "required": [ + "slots", + "known_slots", + "has_tomorrow", + "dropped_points" + ], + "title": "PriceQuality", + "type": "object" + }, + "PriceReport": { + "additionalProperties": false, + "properties": { + "formula_missing": { + "title": "Formula Missing", + "type": "boolean" + }, + "freshness": { + "$ref": "#/components/schemas/PriceFreshness" + }, + "price_includes": { + "enum": [ + "spot_only", + "all_in" + ], + "title": "Price Includes", + "type": "string" + }, + "quality": { + "$ref": "#/components/schemas/PriceQuality" + }, + "slots": { + "items": { + "$ref": "#/components/schemas/PriceSlot" + }, + "title": "Slots", + "type": "array" + }, + "source": { + "$ref": "#/components/schemas/PriceSourceInfo" + }, + "start": { + "format": "date-time", + "title": "Start", + "type": "string" + }, + "step_min": { + "const": 15, + "default": 15, + "title": "Step Min", + "type": "integer" + }, + "unit": { + "const": "currency/kWh", + "default": "currency/kWh", + "title": "Unit", + "type": "string" + } + }, + "required": [ + "price_includes", + "formula_missing", + "start", + "slots", + "source", + "freshness", + "quality" + ], + "title": "PriceReport", + "type": "object" + }, + "PriceSlot": { + "additionalProperties": false, + "description": "One 15-minute interval; a price is ``null`` where no source value covers it.", + "properties": { + "export_price": { + "anyOf": [ + { + "type": "number" + }, + { + "type": "null" + } + ], + "title": "Export Price" + }, + "import_price": { + "anyOf": [ + { + "type": "number" + }, + { + "type": "null" + } + ], + "title": "Import Price" + }, + "start": { + "format": "date-time", + "title": "Start", + "type": "string" + } + }, + "required": [ + "start", + "import_price", + "export_price" + ], + "title": "PriceSlot", + "type": "object" + }, + "PriceSourceInfo": { + "additionalProperties": false, + "properties": { + "currency": { + "title": "Currency", + "type": "string" + }, + "export_kind": { + "enum": [ + "fixed", + "tiered", + "none" + ], + "title": "Export Kind", + "type": "string" + }, + "export_zeroed_slots": { + "minimum": 0.0, + "title": "Export Zeroed Slots", + "type": "integer" + }, + "formula_applied": { + "title": "Formula Applied", + "type": "boolean" + }, + "import_kind": { + "enum": [ + "dynamic", + "fixed", + "tou" + ], + "title": "Import Kind", + "type": "string" + }, + "import_source_id": { + "title": "Import Source Id", + "type": "string" }, - "margin": { - "default": 0.0, - "maximum": 100.0, - "minimum": 0.0, - "title": "Margin", - "type": "number" + "native_step_min": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Native Step Min" }, - "spot_multiplier": { - "default": 1.0, - "exclusiveMinimum": 0.0, - "maximum": 10.0, - "title": "Spot Multiplier", - "type": "number" + "negative_price_rule": { + "title": "Negative Price Rule", + "type": "string" }, - "vat_pct": { - "default": 0.0, - "maximum": 100.0, - "minimum": 0.0, - "title": "Vat Pct", - "type": "number" + "price_includes": { + "enum": [ + "spot_only", + "all_in" + ], + "title": "Price Includes", + "type": "string" + }, + "source_price_includes": { + "enum": [ + "spot_only", + "all_in" + ], + "title": "Source Price Includes", + "type": "string" } }, - "title": "PriceFormula", + "required": [ + "import_source_id", + "import_kind", + "source_price_includes", + "price_includes", + "formula_applied", + "export_kind", + "negative_price_rule", + "export_zeroed_slots", + "native_step_min", + "currency" + ], + "title": "PriceSourceInfo", "type": "object" }, "PvArray": { @@ -5375,6 +6613,27 @@ "title": "ReleaseAction", "type": "object" }, + "ReplanAck": { + "additionalProperties": false, + "description": "``POST /api/v1/plan/replan`` (202): the request is queued, not done.", + "properties": { + "accepted": { + "default": true, + "title": "Accepted", + "type": "boolean" + }, + "earliest_start_at": { + "format": "date-time", + "title": "Earliest Start At", + "type": "string" + } + }, + "required": [ + "earliest_start_at" + ], + "title": "ReplanAck", + "type": "object" + }, "RiskLevel": { "description": "How sure the plan must be that a battery target is met (forecast/buffer concept).\n\nThe planner plans the target on a quantile of the net energy forecast (PV minus load):\n``cautious`` meets it with probability 0.9 (10 % quantile), ``balanced`` 0.75 (25 %),\n``bold`` 0.5 (median).", "enum": [ @@ -5663,6 +6922,19 @@ "additionalProperties": false, "description": "Names of the fields of one series point and the unit of its values.\n\n``timestamp_field`` and ``value_field`` are required for a list of point objects\n(``action`` series, ``attribute`` series of shape ``list``) and absent for an\n``attribute`` series of shape ``mapping``, whose keys are the timestamps and whose\nvalues are the values.", "properties": { + "end_field": { + "anyOf": [ + { + "maxLength": 200, + "minLength": 1, + "type": "string" + }, + { + "type": "null" + } + ], + "title": "End Field" + }, "p10_field": { "anyOf": [ { @@ -5983,6 +7255,64 @@ "title": "SnapshotMessage", "type": "object" }, + "SolverStats": { + "additionalProperties": false, + "description": "Plan v2: how the plan was computed (the UI explains long solves with it).", + "properties": { + "mip_gap": { + "anyOf": [ + { + "minimum": 0.0, + "type": "number" + }, + { + "type": "null" + } + ], + "title": "Mip Gap" + }, + "n_binaries": { + "default": 0, + "minimum": 0.0, + "title": "N Binaries", + "type": "integer" + }, + "n_vars": { + "default": 0, + "minimum": 0.0, + "title": "N Vars", + "type": "integer" + }, + "objective": { + "anyOf": [ + { + "type": "number" + }, + { + "type": "null" + } + ], + "title": "Objective" + }, + "solve_time_s": { + "minimum": 0.0, + "title": "Solve Time S", + "type": "number" + }, + "status": { + "maxLength": 48, + "pattern": "^[a-z][a-z0-9_]*$", + "title": "Status", + "type": "string" + } + }, + "required": [ + "solve_time_s", + "status" + ], + "title": "SolverStats", + "type": "object" + }, "SourceRef": { "additionalProperties": false, "description": "Documentation a template (or one of its facts) is based on.", @@ -8284,6 +9614,117 @@ "summary": "Set Global Mode" } }, + "/api/v1/plan": { + "get": { + "description": "The current plan from now to ``hours`` ahead: per 15-minute interval the expected\nflows, prices, battery and device bands and the reasons; who made it (``solver``,\n``heuristic`` or ``default`` = none yet), the solver statistics, ``stale`` and whether\nthe controller follows it (``in_use``; else ``fallback`` says why).", + "operationId": "get_plan", + "parameters": [ + { + "in": "query", + "name": "hours", + "required": false, + "schema": { + "default": 48, + "maximum": 48, + "minimum": 1, + "title": "Hours", + "type": "integer" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PlanView" + } + } + }, + "description": "Successful Response" + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorOut" + } + } + }, + "description": "The planner is not running" + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ValidationErrorOut" + } + } + }, + "description": "Validation error" + } + }, + "summary": "Plan" + } + }, + "/api/v1/plan/replan": { + "post": { + "description": "Ask for a new plan. Debounced (at most one event-triggered run per minute) and\nanswered at once with the earliest start; the new plan arrives as a ``plan`` message\non the live feed.", + "operationId": "replan", + "responses": { + "202": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReplanAck" + } + } + }, + "description": "Successful Response" + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorOut" + } + } + }, + "description": "The planner is not running" + } + }, + "summary": "Replan" + } + }, + "/api/v1/plan/status": { + "get": { + "description": "Last run (time, duration, outcome and reason), pending events and the next run.", + "operationId": "plan_status", + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PlanStatusView" + } + } + }, + "description": "Successful Response" + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorOut" + } + } + }, + "description": "The planner is not running" + } + }, + "summary": "Plan Status" + } + }, "/api/v1/preview": { "post": { "description": "Live values of every entity in an unsaved SiteConfig or DeviceConfig fragment.", @@ -8335,6 +9776,59 @@ "summary": "Preview" } }, + "/api/v1/prices": { + "get": { + "description": "Import and export prices on the 15-minute grid from now to the end of the known\nprices (at least 24 h where the tariff allows, at most ``hours``), with the source\nand its freshness. A price is ``null`` where no source value covers the interval.", + "operationId": "get_prices", + "parameters": [ + { + "in": "query", + "name": "hours", + "required": false, + "schema": { + "default": 48, + "maximum": 72, + "minimum": 1, + "title": "Hours", + "type": "integer" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PriceReport" + } + } + }, + "description": "Successful Response" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorOut" + } + } + }, + "description": "No usable tariff is configured" + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ValidationErrorOut" + } + } + }, + "description": "Validation error" + } + }, + "summary": "Prices" + } + }, "/api/v1/proposals": { "get": { "description": "Open assisted-mode proposals, oldest first (valid until ``expires_at``).", diff --git a/frontend/src/lib/api/schema.d.ts b/frontend/src/lib/api/schema.d.ts index b34605e..12b7b29 100644 --- a/frontend/src/lib/api/schema.d.ts +++ b/frontend/src/lib/api/schema.d.ts @@ -526,6 +526,71 @@ export interface paths { patch?: never; trace?: never; }; + "/api/v1/plan": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Plan + * @description The current plan from now to ``hours`` ahead: per 15-minute interval the expected + * flows, prices, battery and device bands and the reasons; who made it (``solver``, + * ``heuristic`` or ``default`` = none yet), the solver statistics, ``stale`` and whether + * the controller follows it (``in_use``; else ``fallback`` says why). + */ + get: operations["get_plan"]; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + "/api/v1/plan/replan": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + get?: never; + put?: never; + /** + * Replan + * @description Ask for a new plan. Debounced (at most one event-triggered run per minute) and + * answered at once with the earliest start; the new plan arrives as a ``plan`` message + * on the live feed. + */ + post: operations["replan"]; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + "/api/v1/plan/status": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Plan Status + * @description Last run (time, duration, outcome and reason), pending events and the next run. + */ + get: operations["plan_status"]; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; "/api/v1/preview": { parameters: { query?: never; @@ -546,6 +611,28 @@ export interface paths { patch?: never; trace?: never; }; + "/api/v1/prices": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Prices + * @description Import and export prices on the 15-minute grid from now to the end of the known + * prices (at least 24 h where the tariff allows, at most ``hours``), with the source + * and its freshness. A price is ``null`` where no source value covers the interval. + */ + get: operations["get_prices"]; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; "/api/v1/proposals": { parameters: { query?: never; @@ -739,11 +826,33 @@ export interface components { /** Window Days */ window_days: number | null; }; + /** + * ActionParam + * @description A field of the action's request that the user's tariff configuration supplies. + * + * The value comes from ``tariff.import.action_params[name]`` (Phase 4 WP4), e.g. the + * Nord Pool ``config_entry`` id or ``areas``. SunCore never invents such a value. + */ + ActionParam: { + /** Description */ + description: string; + /** Name */ + name: string; + /** + * Required + * @default true + */ + required: boolean; + }; /** * ActionSeries * @description Series returned by a read-only action (``return_response`` is implied). */ ActionSeries: { + /** Date Field */ + date_field?: string | null; + /** Date Tz */ + date_tz?: string | null; /** Domain */ domain: string; /** End Field */ @@ -751,6 +860,11 @@ export interface components { fields: components["schemas"]["SeriesFields"]; /** Max Horizon H */ max_horizon_h: number; + /** + * Params + * @default [] + */ + params: components["schemas"]["ActionParam"][]; /** Response Path */ response_path: string; /** Service */ @@ -799,6 +913,12 @@ export interface components { */ source: "attribute"; }; + /** + * BandPreference + * @description What the plan would like the controller to do inside an allowed band. + * @enum {string} + */ + BandPreference: "neutral" | "prefer_on" | "prefer_off"; /** * BatteryAction * @description Battery limits for the gate (Phase 4 WP2; reviewed by ``control-safety`` in WP10). @@ -828,6 +948,34 @@ export interface components { /** Min Soc Pct */ min_soc_pct?: number | null; }; + /** + * BatteryBand + * @description Battery corridor per interval (Phase 4 writes it; Phase 3 reads only ``reserve``). + */ + BatteryBand: { + /** + * Charge From Surplus + * @default true + */ + charge_from_surplus: boolean; + /** + * Discharge Lock + * @default false + */ + discharge_lock: boolean; + /** Grid Charge Max W */ + grid_charge_max_w?: number | null; + /** Max Power W */ + max_power_w?: number | null; + /** Max Soc Pct */ + max_soc_pct?: number | null; + /** Min Power W */ + min_power_w?: number | null; + /** Min Soc Pct */ + min_soc_pct?: number | null; + /** Priority Until Soc Pct */ + priority_until_soc_pct?: number | null; + }; /** * BatteryConfig * @description Battery: power (+ = charging), state of charge in percent, limits. @@ -1332,6 +1480,21 @@ export interface components { */ type: "decisions"; }; + /** + * DeviceBand + * @description Per interval and device: what the controller may do and what the planner prefers. + */ + DeviceBand: { + /** + * Allowed + * @default true + */ + allowed: boolean; + /** Max Power W */ + max_power_w?: number | null; + /** @default neutral */ + preference: components["schemas"]["BandPreference"]; + }; /** * DeviceConfig * @description One configured device (instance of a template). @@ -2076,6 +2239,10 @@ export interface components { * * ``tou``: fixed time-of-use prices (HT/NT, seasonal) in ``tou`` (tariff v3). */ ImportTariff: { + /** Action Params */ + action_params?: { + [key: string]: string | string[]; + }; /** Fixed Price */ fixed_price?: number | null; formula?: components["schemas"]["PriceFormula"] | null; @@ -2085,6 +2252,14 @@ export interface components { */ kind: "fixed" | "dynamic" | "tou"; price_entity?: components["schemas"]["EntityRef"] | null; + /** Price Includes */ + price_includes?: ("spot_only" | "all_in") | null; + /** Role Entities */ + role_entities?: { + [key: string]: components["schemas"]["EntityRef"]; + }; + /** Series Key */ + series_key?: string | null; /** Template Id */ template_id?: string | null; tou?: components["schemas"]["TouTariff"] | null; @@ -2124,6 +2299,75 @@ export interface components { */ ts: string; }; + /** + * IntervalFlows + * @description Plan v2: the flows the planner expects in an interval (mean power, W). + * + * Signs per ``core/units.py``: import/export are magnitudes, battery + = charging. + * ``pv_p10_w``/``pv_p50_w``/``pv_p90_w`` are the PV forecast's quantiles as forecast data + * (shown in the UI; ``None`` = the source has no quantiles); the objective uses P50. + * Battery targets are *not* planned on P10 PV (plan §0): they use the risk quantile of + * the learnt **net** energy error distribution (PV minus load) per weather class. + * ``net_risk_quantile`` is that quantile (``RiskLevel.quantile``, e.g. 0.1 = cautious) + * and ``net_risk_w`` the net power PV - load at that quantile the target constraints + * used (may be negative; ``None`` = no target constraint in this interval). + * ``soc_pct`` is the planned state of charge at the *end* of the interval (``None`` = no + * battery). ``devices_w`` is the planned draw of the controllable devices (not part of + * ``load_w``, the base load) and ``curtail_w`` the PV the plan does not use (export limit + * or negative export price; informational until the export-limit chain, Phase 6), so + * ``pv_p50_w + import_w + max(-battery_w, 0) = load_w + devices_w + max(battery_w, 0) + + * export_w + curtail_w`` (both additive in plan v2, default 0). + */ + IntervalFlows: { + /** + * Battery W + * @default 0 + */ + battery_w: number; + /** + * Curtail W + * @default 0 + */ + curtail_w: number; + /** + * Devices W + * @default 0 + */ + devices_w: number; + /** Export W */ + export_w: number; + /** Import W */ + import_w: number; + /** Load W */ + load_w: number; + /** Net Risk Quantile */ + net_risk_quantile?: number | null; + /** Net Risk W */ + net_risk_w?: number | null; + /** Pv P10 W */ + pv_p10_w?: number | null; + /** Pv P50 W */ + pv_p50_w: number; + /** Pv P90 W */ + pv_p90_w?: number | null; + /** Soc Pct */ + soc_pct?: number | null; + }; + /** + * IntervalPrices + * @description Plan v2: end prices (currency/kWh) the planner used; may be negative. + */ + IntervalPrices: { + /** + * Estimated + * @default false + */ + estimated: boolean; + /** Export Price */ + export_price: number; + /** Import Price */ + import_price: number; + }; /** * LearningSettings * @description What SunCore may learn from history (forecast calibration, load model). @@ -2148,7 +2392,7 @@ export interface components { */ min_history_days: number; }; - LiveMessage: components["schemas"]["SnapshotMessage"] | components["schemas"]["FlowsMessage"] | components["schemas"]["HealthMessage"] | components["schemas"]["DecisionsMessage"] | components["schemas"]["ControlMessage"]; + LiveMessage: components["schemas"]["SnapshotMessage"] | components["schemas"]["FlowsMessage"] | components["schemas"]["HealthMessage"] | components["schemas"]["DecisionsMessage"] | components["schemas"]["ControlMessage"] | components["schemas"]["PlanMessage"]; /** * LoadDayView * @description The day type (and forecast mean temperature) of one local date of the forecast. @@ -2433,6 +2677,184 @@ export interface components { */ resume_time: string; }; + /** + * Plan + * @description The planner's output as the controller consumes it (ADR-0011). + * + * Phase 3 only ever uses :meth:`Plan.default`, which has no intervals and therefore + * allows everything; the Phase 4 planner fills ``intervals`` without changing the + * controller. Intervals must not overlap and are kept in start order. + * + * Schema v2 (Phase 4 WP2, additive): ``source``, ``stats`` and per interval + * ``expected``/``prices``/``reasons``. A v1 payload loads unchanged (it keeps + * ``schema_version`` 1, ``source = "default"``); :func:`plan_from_payload` stamps v2. + */ + Plan: { + /** Assumptions */ + assumptions?: { + [key: string]: string | number | boolean; + }; + /** Created At */ + created_at?: string | null; + /** + * Intervals + * @default [] + */ + intervals: components["schemas"]["PlanInterval"][]; + /** + * Reasons + * @default [] + */ + reasons: components["schemas"]["Reason"][]; + /** + * Schema Version + * @default 2 + */ + schema_version: number; + /** + * Source + * @default default + * @enum {string} + */ + source: "solver" | "heuristic" | "default"; + stats?: components["schemas"]["SolverStats"] | null; + }; + /** + * PlanInterval + * @description One planning interval (15 min grid in Phase 4; any length is accepted). + * + * ``expected``, ``prices`` and ``reasons`` are the plan v2 additions for the UI's + * "Why?"; the controller reads only the bands and the import limit. + */ + PlanInterval: { + /** + * @default { + * "charge_from_surplus": true, + * "discharge_lock": false + * } + */ + battery: components["schemas"]["BatteryBand"] | null; + /** Devices */ + devices?: { + [key: string]: components["schemas"]["DeviceBand"]; + }; + /** + * End + * Format: date-time + */ + end: string; + expected?: components["schemas"]["IntervalFlows"] | null; + /** Grid Import Limit W */ + grid_import_limit_w?: number | null; + prices?: components["schemas"]["IntervalPrices"] | null; + /** + * Reasons + * @default [] + */ + reasons: components["schemas"]["Reason"][]; + /** + * Start + * Format: date-time + */ + start: string; + }; + /** + * PlanMessage + * @description A new plan was computed (summary only; fetch ``GET /api/v1/plan`` for the intervals). + */ + PlanMessage: { + plan: components["schemas"]["PlanSummary"]; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + type: "plan"; + }; + /** + * PlanStatusView + * @description ``GET /api/v1/plan/status``: the scheduler's bookkeeping. + */ + PlanStatusView: { + /** Consecutive Failures */ + consecutive_failures: number; + /** Earliest Event Run At */ + earliest_event_run_at: string | null; + /** + * Generated At + * Format: date-time + */ + generated_at: string; + /** Last Duration S */ + last_duration_s: number | null; + /** Last Finished At */ + last_finished_at: string | null; + /** Last Ok At */ + last_ok_at: string | null; + /** Last Outcome */ + last_outcome: ("ok" | "failed" | "skipped") | null; + /** Last Started At */ + last_started_at: string | null; + /** Last Trigger */ + last_trigger: ("start" | "schedule" | "prices" | "forecast" | "deviation" | "config" | "override" | "manual") | null; + /** Next Scheduled At */ + next_scheduled_at: string | null; + /** Pending */ + pending?: ("start" | "schedule" | "prices" | "forecast" | "deviation" | "config" | "override" | "manual")[]; + plan: components["schemas"]["PlanSummary"]; + reason?: components["schemas"]["Reason"] | null; + /** Running */ + running: boolean; + }; + /** + * PlanSummary + * @description The live feed's ``plan`` message and the status' short form: no intervals. + */ + PlanSummary: { + /** Created At */ + created_at: string | null; + /** Horizon End */ + horizon_end: string | null; + /** In Use */ + in_use: boolean; + /** Intervals */ + intervals: number; + /** Reasons */ + reasons?: components["schemas"]["Reason"][]; + /** Solve Time S */ + solve_time_s: number | null; + /** + * Source + * @enum {string} + */ + source: "solver" | "heuristic" | "default"; + /** Stale */ + stale: boolean; + /** Status */ + status: string | null; + }; + /** + * PlanView + * @description ``GET /api/v1/plan``: the current plan and whether the controller follows it. + * + * ``plan`` is :meth:`Plan.default` (no intervals, ``source = "default"``) until the first + * plan exists. ``in_use`` is ``False`` when the plan is stale or has run out: the controller + * then runs on Phase 3 rules only (``fallback`` says why, as a catalogue reason). + */ + PlanView: { + /** Expired */ + expired: boolean; + fallback?: components["schemas"]["Reason"] | null; + /** + * Generated At + * Format: date-time + */ + generated_at: string; + /** In Use */ + in_use: boolean; + plan: components["schemas"]["Plan"]; + /** Stale */ + stale: boolean; + }; /** * PowerEstimate * @description A device's power with its uncertainty (BRIEF §4.5: both power paths are equivalent). @@ -2548,6 +2970,18 @@ export interface components { /** Items */ items: components["schemas"]["PreviewItemOut"][]; }; + /** + * PriceErrorOut + * @description Why the last refresh failed, as a catalogue key. + */ + PriceErrorOut: { + /** Args */ + args?: { + [key: string]: string | number | string[]; + }; + /** Key */ + key: string; + }; /** * PriceFormula * @description Spot price -> end price (BRIEF §4.4). @@ -2591,6 +3025,121 @@ export interface components { */ vat_pct: number; }; + /** PriceFreshness */ + PriceFreshness: { + /** Age S */ + age_s: number | null; + /** Fetched At */ + fetched_at: string | null; + /** Known Until */ + known_until: string | null; + last_error: components["schemas"]["PriceErrorOut"] | null; + /** Next Refresh At */ + next_refresh_at: string | null; + /** + * Status + * @enum {string} + */ + status: "fresh" | "stale" | "missing" | "static"; + }; + /** PriceQuality */ + PriceQuality: { + /** + * Carried Slots + * @default 0 + */ + carried_slots: number; + /** Dropped Points */ + dropped_points: number; + /** Has Tomorrow */ + has_tomorrow: boolean; + /** Known Slots */ + known_slots: number; + /** Slots */ + slots: number; + }; + /** PriceReport */ + PriceReport: { + /** Formula Missing */ + formula_missing: boolean; + freshness: components["schemas"]["PriceFreshness"]; + /** + * Price Includes + * @enum {string} + */ + price_includes: "spot_only" | "all_in"; + quality: components["schemas"]["PriceQuality"]; + /** Slots */ + slots: components["schemas"]["PriceSlot"][]; + source: components["schemas"]["PriceSourceInfo"]; + /** + * Start + * Format: date-time + */ + start: string; + /** + * Step Min + * @default 15 + * @constant + */ + step_min: 15; + /** + * Unit + * @default currency/kWh + * @constant + */ + unit: "currency/kWh"; + }; + /** + * PriceSlot + * @description One 15-minute interval; a price is ``null`` where no source value covers it. + */ + PriceSlot: { + /** Export Price */ + export_price: number | null; + /** Import Price */ + import_price: number | null; + /** + * Start + * Format: date-time + */ + start: string; + }; + /** PriceSourceInfo */ + PriceSourceInfo: { + /** Currency */ + currency: string; + /** + * Export Kind + * @enum {string} + */ + export_kind: "fixed" | "tiered" | "none"; + /** Export Zeroed Slots */ + export_zeroed_slots: number; + /** Formula Applied */ + formula_applied: boolean; + /** + * Import Kind + * @enum {string} + */ + import_kind: "dynamic" | "fixed" | "tou"; + /** Import Source Id */ + import_source_id: string; + /** Native Step Min */ + native_step_min: number | null; + /** Negative Price Rule */ + negative_price_rule: string; + /** + * Price Includes + * @enum {string} + */ + price_includes: "spot_only" | "all_in"; + /** + * Source Price Includes + * @enum {string} + */ + source_price_includes: "spot_only" | "all_in"; + }; /** * PvArray * @description One PV array (roof plane / inverter input). Everything but ``name`` is optional. @@ -2782,6 +3331,22 @@ export interface components { */ kind: "release"; }; + /** + * ReplanAck + * @description ``POST /api/v1/plan/replan`` (202): the request is queued, not done. + */ + ReplanAck: { + /** + * Accepted + * @default true + */ + accepted: boolean; + /** + * Earliest Start At + * Format: date-time + */ + earliest_start_at: string; + }; /** * RiskLevel * @description How sure the plan must be that a battery target is met (forecast/buffer concept). @@ -2922,6 +3487,8 @@ export interface components { * values are the values. */ SeriesFields: { + /** End Field */ + end_field?: string | null; /** P10 Field */ p10_field?: string | null; /** P90 Field */ @@ -3026,6 +3593,30 @@ export interface components { */ type: "snapshot"; }; + /** + * SolverStats + * @description Plan v2: how the plan was computed (the UI explains long solves with it). + */ + SolverStats: { + /** Mip Gap */ + mip_gap?: number | null; + /** + * N Binaries + * @default 0 + */ + n_binaries: number; + /** + * N Vars + * @default 0 + */ + n_vars: number; + /** Objective */ + objective?: number | null; + /** Solve Time S */ + solve_time_s: number; + /** Status */ + status: string; + }; /** * SourceRef * @description Documentation a template (or one of its facts) is based on. @@ -4520,6 +5111,104 @@ export interface operations { }; }; }; + get_plan: { + parameters: { + query?: { + hours?: number; + }; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["PlanView"]; + }; + }; + /** @description The planner is not running */ + 409: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["ErrorOut"]; + }; + }; + /** @description Validation error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["ValidationErrorOut"]; + }; + }; + }; + }; + replan: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 202: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["ReplanAck"]; + }; + }; + /** @description The planner is not running */ + 409: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["ErrorOut"]; + }; + }; + }; + }; + plan_status: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["PlanStatusView"]; + }; + }; + /** @description The planner is not running */ + 409: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["ErrorOut"]; + }; + }; + }; + }; preview_api_v1_preview_post: { parameters: { query?: never; @@ -4564,6 +5253,46 @@ export interface operations { }; }; }; + get_prices: { + parameters: { + query?: { + hours?: number; + }; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["PriceReport"]; + }; + }; + /** @description No usable tariff is configured */ + 404: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["ErrorOut"]; + }; + }; + /** @description Validation error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["ValidationErrorOut"]; + }; + }; + }; + }; proposals_api_v1_proposals_get: { parameters: { query?: never; diff --git a/frontend/src/lib/i18n/locales/de.json b/frontend/src/lib/i18n/locales/de.json index 38d31b2..2ec9411 100644 --- a/frontend/src/lib/i18n/locales/de.json +++ b/frontend/src/lib/i18n/locales/de.json @@ -39,6 +39,7 @@ "api.error.not_found": "Nicht gefunden.", "api.error.preview_too_large": "Die Vorschau nennt zu viele Entitäten.", "api.error.role_required": "Für eine Vorlage ist eine Rolle erforderlich.", + "api.error.tariff_not_configured": "Es ist noch kein Tarif eingerichtet. Wähle deinen Tarif in den Einstellungen.", "api.error.unknown": "Ein unerwarteter Fehler ist aufgetreten.", "api.error.unknown_role": "Diese Rolle existiert nicht.", "api.error.unknown_section": "Dieser Konfigurationsbereich existiert nicht.", @@ -701,6 +702,21 @@ "summary.severity.warn": "Warnung:", "tariff.dynamic_source": "Quelle des dynamischen Preises", "tariff.error.incomplete": "Gib Bezugspreis und Einspeisevergütung ein oder überspringe diesen Schritt.", + "tariff.error.source_unavailable": "Die Preisquelle ist gerade nicht verfügbar. SunCore behält die letzten Preise.", + "tariff.error.malformed_payload": "Die Preisquelle hat Daten in einem unerwarteten Format geliefert. SunCore behält die letzten Preise.", + "tariff.error.ambiguous_series": "Die Preisquelle hat mehrere Preislisten geliefert ({available}). Wähle in den Tarif-Einstellungen eine aus.", + "tariff.error.missing_param": "Die Preisquelle braucht die Einstellung „{field}“. Trage sie in den Tarif-Einstellungen ein.", + "tariff.error.missing_entity": "Die Preisquelle braucht eine Entität für „{role}“. Wähle sie in den Tarif-Einstellungen.", + "tariff.error.throttled": "Die Preisquelle wurde zu oft abgefragt und übersprungen; SunCore fragt in {retry_after_s, number} s erneut an.", + "tariff.error.action_failed": "Home Assistant konnte die Preise nicht liefern. SunCore behält die letzten Preise und versucht es erneut.", + "tariff.error.unit_mismatch": "Der Sensor meldet Preise in „{sensor_unit}“, die Vorlage erwartet „{template_unit}“. Wähle die passende Vorlage.", + "tariff.error.currency_mismatch": "Die Preise sind in {source_currency}, deine Region nutzt {region_currency}. Wähle eine Quelle in {region_currency}.", + "tariff.error.export_needs_kwp": "Die gestaffelte Einspeisevergütung braucht die Größe jeder Solaranlage (kWp) und Stufen, die die ganze Anlage abdecken.", + "tariff.error.export_tiers": "Die Einspeisestufen decken die ganze Anlage mit {kwp} kWp nicht ab. Trage einen Satz für den Teil über der letzten Stufe ein.", + "tariff.status.fresh": "Die Preise sind aktuell.", + "tariff.status.stale": "Die Preise sind veraltet; SunCore behält die letzten bekannten Werte.", + "tariff.status.missing": "Noch keine Preise.", + "tariff.status.static": "Feste Preise.", "tariff.export": "Einspeisevergütung", "tariff.export.fixed": "Fester Preis", "tariff.export.none": "Keine Vergütung", @@ -753,6 +769,25 @@ "template.lg.thinq_climate.role.energy_today": "Energie heute (Wh-Zähler desselben Geräts, stündlich aktualisiert)", "template.lg.thinq_climate.role.energy_yesterday": "Energie gestern (Wh, selbes Gerät, optional)", "template.lg.thinq_climate.role.power": "Leistungssensor (optional, z. B. Zwischenstecker oder smartthinq_sensors „Energy current“)", + "template.entsoe.price.name": "ENTSO-E Day-Ahead-Preis (kWh)", + "template.entsoe.price.role.price": "Sensor „Average electricity price“ der ENTSO-E-Integration (er trägt die Preisliste)", + "template.entsoe.price_mwh.name": "ENTSO-E Day-Ahead-Preis (MWh-Skala)", + "template.entsoe.price_mwh.role.price": "Sensor „Average electricity price“ der ENTSO-E-Integration mit MWh-Skala", + "template.epex_spot.market_price.name": "EPEX-Spot-Marktpreis", + "template.epex_spot.market_price.role.price": "Sensor „Market Price“ der EPEX-Spot-Integration (reiner Marktpreis)", + "template.epex_spot.total_price.name": "EPEX-Spot-Gesamtpreis", + "template.epex_spot.total_price.role.price": "Sensor „Total Price“ der EPEX-Spot-Integration (Marktpreis plus deine Aufschläge und Mehrwertsteuer)", + "template.generic.price_list.name": "Allgemeine Preisliste (Sensor-Attribut)", + "template.generic.price_list.role.price": "Sensor mit dem Attribut „prices“: Liste aus Startzeit und Preis pro kWh", + "template.nordpool.price.name": "Nord-Pool-Day-Ahead-Preis", + "template.nordpool.price.role.price": "Aktueller Preissensor der Nord-Pool-Integration (Währung pro kWh)", + "template.nordpool.price.param.config_entry": "ID des Nord-Pool-Konfigurationseintrags in Home Assistant", + "template.nordpool.price.param.areas": "Preisgebiet, zum Beispiel SE3 (leer: das in der Integration eingerichtete Gebiet)", + "template.nordpool.price.param.currency": "Währung der Preise (leer: die in der Integration eingerichtete Währung)", + "template.octopus_energy.rates.name": "Octopus-Energy-Tarife", + "template.octopus_energy.rates.role.price": "Sensor des aktuellen Bezugstarifs von Octopus Energy (GBP pro kWh)", + "template.octopus_energy.rates.role.current_day_rates": "Ereignis-Entität „Current day rates“ (Bezug) von Octopus Energy", + "template.octopus_energy.rates.role.next_day_rates": "Ereignis-Entität „Next day rates“ (Bezug) von Octopus Energy (optional)", "template.solcast.pv.name": "Solcast-PV-Prognose", "template.solcast.pv.role.forecast_today": "Solcast-Sensor für die Prognose von heute (kWh)", "template.solcast.pv.role.forecast_tomorrow": "Solcast-Sensor für die Prognose von morgen (kWh)", @@ -783,6 +818,7 @@ "wizard.check.battery_sign_soc": "Die Batterie lädt mit {battery_w} W, obwohl sie bei {soc_pct} % steht (oder entlädt im leeren Zustand). Das Vorzeichen könnte vertauscht sein.", "wizard.check.entities_fresh": "{count, plural, one {# Sensor liefert} other {# Sensoren liefern}} aktuelle Werte.", "wizard.check.duplicate_unit": "„{device_a}“ und „{device_b}“ steuern dasselbe Gerät „{unit_name}“ (zwei Integrationen oder dieselbe Entity doppelt). Steuere ein Gerät nur einmal.", + "wizard.check.tariff_spot_without_formula": "Der Tarif liefert reine Börsenpreise und es ist keine Preisformel gesetzt. Trage Netzentgelt, Abgaben und Mehrwertsteuer ein, sonst sind die Preise zu niedrig zum Planen.", "wizard.check.entity_invalid": "{entity_id} liefert keine Zahl.", "wizard.check.entity_missing": "{entity_id} existiert in Home Assistant nicht.", "wizard.check.entity_stale": "{entity_id} wurde seit einiger Zeit nicht aktualisiert.", @@ -845,6 +881,9 @@ "api.validation.forecast_manual_weight": "Eine manuelle Gewichtung braucht ein Gewicht.", "api.validation.grid_charge_needs_limit": "Laden aus dem Netz braucht eine Preisgrenze oder einen Zeitplan.", "api.validation.import_formula_dynamic_only": "Eine Preisformel gilt nur für einen dynamischen Tarif.", + "api.validation.import_param_missing": "Der Tarif {template_id} braucht die Einstellung „{field}“.", + "api.validation.import_role_price": "Der Preissensor wird über „Preissensor“ gesetzt, nicht als zusätzliche Entität.", + "api.validation.import_source_dynamic_only": "Sensoren, Abfrage-Einstellungen und eine Preisangabe gelten nur für einen dynamischen Tarif.", "api.validation.import_tou_extra": "Ein zeitvariabler Tarif (HT/NT) hat keinen Festpreis, keine Vorlage und keinen Preissensor.", "api.validation.import_tou_needs_periods": "Ein zeitvariabler Tarif (HT/NT) braucht seine Zeitfenster und Preise.", "api.validation.import_tou_only": "Zeitfenster mit Preisen brauchen einen zeitvariablen Tarif (HT/NT).", @@ -864,5 +903,48 @@ "api.validation.forecast_workday_domain": "{entity_id} ist kein Binärsensor. Wähle den Binärsensor der Workday-Integration.", "api.validation.forecast_weather_domain": "{entity_id} ist keine Wetter-Entität.", "planner.battery.morning_buffer": "Akku zuerst bis {soc_pct, number, ::.0} %: {cause, select, prefer_full {du willst den Akku so voll wie möglich} forecast_poor {bei der Risikostufe {risk, select, cautious {vorsichtig} balanced {ausgewogen} other {mutig}} deckt die Solarprognose heute und die Nacht nicht mit Reserve} forecast_uncertain {die Solarprognose ist unsicher} manual_floor {dein Mindest-Morgenpuffer} other {die Solarprognose lässt reichlich Überschuss}} (übrig nach heute und der Nacht bei dieser Risikostufe: {surplus_kwh, number, ::.0} kWh).", - "planner.battery.evening_target": "Abendziel {soc_pct, number, ::.0} % (Risikostufe {risk, select, cautious {vorsichtig} balanced {ausgewogen} other {mutig}}): {cause, select, prefer_full {du willst den Akku so voll wie möglich} next_day_deficit {die Nacht ({night_kwh, number, ::.0} kWh) und ein schwacher nächster Tag ({deficit_kwh, number, ::.0} kWh mehr) brauchen es} user_target {dein Ziel-Ladestand} max_soc {begrenzt auf den maximalen Ladestand} other {die Nacht braucht {night_kwh, number, ::.0} kWh}}." + "planner.battery.evening_target": "Abendziel {soc_pct, number, ::.0} % (Risikostufe {risk, select, cautious {vorsichtig} balanced {ausgewogen} other {mutig}}): {cause, select, prefer_full {du willst den Akku so voll wie möglich} next_day_deficit {die Nacht ({night_kwh, number, ::.0} kWh) und ein schwacher nächster Tag ({deficit_kwh, number, ::.0} kWh mehr) brauchen es} user_target {dein Ziel-Ladestand} max_soc {begrenzt auf den maximalen Ladestand} other {die Nacht braucht {night_kwh, number, ::.0} kWh}}.", + "planner.solver.optimal": "Optimierter Plan (berechnet in {solve_time_s, number, ::.00} s).", + "planner.solver.incumbent": "Bester Plan innerhalb des Zeitbudgets ({solve_time_s, number, ::.00} s); nicht als optimal bewiesen.", + "planner.heuristic.rules": "Regelbasierter Plan: Akku zuerst bis zum Morgenpuffer, dann Verbraucher mit Überschuss, solange das Abendziel erreichbar bleibt; Netzladen nur, um ein Ziel zu erreichen.", + "planner.fallback.timeout": "Der Optimierer hat in {budget_s, number, ::.0} s keinen Plan gefunden; der regelbasierte Plan gilt.", + "planner.fallback.infeasible": "Der Optimierer konnte das Modell nicht lösen; der regelbasierte Plan gilt.", + "planner.fallback.error": "Der Optimierer ist fehlgeschlagen ({error}); der regelbasierte Plan gilt.", + "planner.fallback.solver_unavailable": "Der Optimierer (HiGHS) ist nicht verfügbar; der regelbasierte Plan gilt.", + "planner.fallback.invalid_solution": "Der Plan des Optimierers hat die Zulässigkeitsprüfung nicht bestanden ({violations} Verletzungen); der regelbasierte Plan gilt.", + "planner.fallback.heuristic_better": "Der regelbasierte Plan ist günstiger als das Zwischenergebnis des Optimierers ({status}) und gilt.", + "planner.fallback.no_prices": "Keine Strompreise: Planung nur auf Autarkie, ohne Preisoptimierung.", + "planner.fallback.spot_without_formula": "{source} liefert reine Börsenpreise und es ist keine Preisformel eingerichtet: Planung ohne Preisoptimierung, bis die Formel gesetzt ist.", + "planner.input.prices_partial": "Preise sind bis {known_until} bekannt; {filled_slots} spätere Viertelstunden werden mit dem Medianpreis geplant.", + "planner.input.no_pv_forecast": "Keine Solarprognose: Der Plan rechnet ohne Solarstrom.", + "planner.input.no_load_forecast": "Noch keine Lastprognose: Der Plan rechnet mit einer flachen Grundlast von {load_w, number, ::0} W und plant keine Verbraucher.", + "planner.input.no_battery_soc": "Der Ladestand des Akkus ist unbekannt: Der Akku bleibt aus dem Plan.", + "planner.input.device_power_unknown": "Die Leistung von {device} ist unbekannt: Das Gerät bleibt aus dem Plan.", + "planner.battery.grid_charge": "Aus dem Netz laden von {from, number, ::.0} % auf {to, number, ::.0} % zu {price, number, ::.000}/kWh: später steigt der Preis auf {later_price, number, ::.000}/kWh ({later_time}).", + "planner.battery.charge_surplus": "{power_w, number, ::0} W Solarüberschuss speichern (Akku {soc_pct, number, ::.0} %).", + "planner.battery.discharge_house": "Der Akku versorgt das Haus mit {power_w, number, ::0} W (Akku {soc_pct, number, ::.0} %).", + "planner.battery.hold_for_evening": "Akku halten: Er soll um {time} bei {soc_pct, number, ::.0} % sein; das Haus bezieht so lange aus dem Netz.", + "planner.battery.hold_for_price": "Akku halten bei {price, number, ::.000}/kWh: Seine Energie ist um {later_time} mehr wert ({later_price, number, ::.000}/kWh).", + "planner.battery.at_reserve": "Der Akku ist an seiner Reserve ({soc_pct, number, ::.0} %): Das Haus bezieht aus dem Netz.", + "planner.battery.full": "Der Akku ist voll ({soc_pct, number, ::.0} %).", + "planner.battery.prefer_full": "Akku zuerst bis {soc_pct, number, ::.0} %: Du willst den Akku so voll wie möglich.", + "planner.battery.user_target": "Dein Ziel: {soc_pct, number, ::.0} % um {time}.", + "planner.battery.target_shortfall": "{goal, select, morning_buffer {Der Morgenpuffer} prefer_full {Voller Akku} user_target {Dein Ziel} other {Das Abendziel}} von {target_pct, number, ::.0} % um {time} ist nicht erreichbar: Der Plan erwartet {planned_pct, number, ::.0} %.", + "planner.device.surplus": "{device} läuft mit Solarüberschuss ({power_w, number, ::0} W).", + "planner.device.throttled": "{device} wartet: Der Akku braucht den Überschuss, um bis {time} {soc_pct, number, ::.0} % zu erreichen.", + "planner.export.negative_price_avoided": "Einspeisen bringt gerade nichts ({price, number, ::.000}/kWh): Der Überschuss geht stattdessen in den Akku und die Verbraucher.", + "planner.export.limit": "Die Einspeisegrenze ({limit_w, number, ::0} W) ist erreicht: Der restliche Solarstrom würde abgeregelt.", + "planner.export.surplus": "{power_w, number, ::0} W einspeisen zu {price, number, ::.000}/kWh.", + "planner.grid.import": "Das Haus bezieht {power_w, number, ::0} W aus dem Netz zu {price, number, ::.000}/kWh.", + "planner.interval.balanced": "Nichts zu planen: Solarstrom und Verbrauch gleichen sich aus.", + "planner.status.waiting_for_inputs": "Warte auf Preise und Prognosen für den ersten Plan; der Plan startet spätestens {grace_s, number, ::0} s nach der ersten Verbindung.", + "planner.status.no_inputs": "Noch nichts zu planen: Die Anlage ist nicht eingerichtet oder Home Assistant ist nicht verbunden.", + "planner.status.run_failed": "Der letzte Planungslauf ist fehlgeschlagen ({error}); der bisherige Plan bleibt in Gebrauch.", + "planner.status.run_timeout": "Der Planungslauf wurde in {limit_s, number, ::0} s nicht fertig; der bisherige Plan bleibt in Gebrauch.", + "planner.status.run_stuck": "Ein früherer Planungslauf läuft noch; es wurde kein neuer gestartet.", + "planner.status.stale": "Der Plan ist älter als {age_h, number, ::.0} h: SunCore regelt ohne ihn (nur Überschussregeln), bis ein neuer Plan vorliegt.", + "planner.status.expired": "Der Plan ist abgelaufen: SunCore regelt ohne ihn (nur Überschussregeln), bis ein neuer Plan vorliegt.", + "planner.status.no_plan": "Es gibt noch keinen Plan: SunCore regelt nur nach den Überschussregeln.", + "api.error.planning_unavailable": "Der Planer läuft nicht (keine Anlage eingerichtet).", + "planner.status.waiting_for_soc": "Warte auf den Ladestand der Batterie, bevor geplant wird." } diff --git a/frontend/src/lib/i18n/locales/en.json b/frontend/src/lib/i18n/locales/en.json index 0a81b1d..6d813ce 100644 --- a/frontend/src/lib/i18n/locales/en.json +++ b/frontend/src/lib/i18n/locales/en.json @@ -39,6 +39,7 @@ "api.error.not_found": "Not found.", "api.error.preview_too_large": "The preview names too many entities.", "api.error.role_required": "A role is required for a template.", + "api.error.tariff_not_configured": "No tariff is set up yet. Choose your tariff in the settings.", "api.error.unknown": "An unexpected error occurred.", "api.error.unknown_role": "This role does not exist.", "api.error.unknown_section": "This configuration section does not exist.", @@ -701,6 +702,21 @@ "summary.severity.warn": "Warning:", "tariff.dynamic_source": "Source of the dynamic price", "tariff.error.incomplete": "Enter the import price and the feed-in remuneration, or skip this step.", + "tariff.error.source_unavailable": "The price source is not available right now. SunCore keeps the last prices.", + "tariff.error.malformed_payload": "The price source delivered data in an unexpected format. SunCore keeps the last prices.", + "tariff.error.ambiguous_series": "The price source returned several price lists ({available}). Choose one in the tariff settings.", + "tariff.error.missing_param": "The price source needs the setting “{field}”. Enter it in the tariff settings.", + "tariff.error.missing_entity": "The price source needs an entity for “{role}”. Choose it in the tariff settings.", + "tariff.error.throttled": "The price source was asked too often and skipped; SunCore asks again in {retry_after_s, number} s.", + "tariff.error.action_failed": "Home Assistant could not deliver the prices. SunCore keeps the last prices and tries again.", + "tariff.error.unit_mismatch": "The sensor reports prices in “{sensor_unit}” but the template expects “{template_unit}”. Choose the matching template.", + "tariff.error.currency_mismatch": "The prices are in {source_currency} but your region uses {region_currency}. Choose a source in {region_currency}.", + "tariff.error.export_needs_kwp": "The tiered feed-in remuneration needs the size of every solar array (kWp) and tiers that cover the whole plant.", + "tariff.error.export_tiers": "The feed-in tiers do not cover the whole plant of {kwp} kWp. Enter a rate for the part above the last tier.", + "tariff.status.fresh": "Prices are up to date.", + "tariff.status.stale": "Prices are outdated; SunCore keeps the last known values.", + "tariff.status.missing": "No prices yet.", + "tariff.status.static": "Fixed prices.", "tariff.export": "Feed-in remuneration", "tariff.export.fixed": "Fixed price", "tariff.export.none": "No remuneration", @@ -753,6 +769,25 @@ "template.lg.thinq_climate.role.energy_today": "Energy used today (Wh counter of the same device, updated hourly)", "template.lg.thinq_climate.role.energy_yesterday": "Energy used yesterday (Wh, same device, optional)", "template.lg.thinq_climate.role.power": "Power sensor (optional, e.g. smart plug or smartthinq_sensors “Energy current”)", + "template.entsoe.price.name": "ENTSO-E day-ahead price (kWh)", + "template.entsoe.price.role.price": "“Average electricity price” sensor of the ENTSO-E integration (it carries the price list)", + "template.entsoe.price_mwh.name": "ENTSO-E day-ahead price (MWh scale)", + "template.entsoe.price_mwh.role.price": "“Average electricity price” sensor of the ENTSO-E integration set to the MWh scale", + "template.epex_spot.market_price.name": "EPEX Spot market price", + "template.epex_spot.market_price.role.price": "“Market Price” sensor of the EPEX Spot integration (bare market price)", + "template.epex_spot.total_price.name": "EPEX Spot total price", + "template.epex_spot.total_price.role.price": "“Total Price” sensor of the EPEX Spot integration (market price plus your surcharges and VAT)", + "template.generic.price_list.name": "Generic price list (sensor attribute)", + "template.generic.price_list.role.price": "Sensor with an attribute “prices”: a list of start time and price per kWh", + "template.nordpool.price.name": "Nord Pool day-ahead price", + "template.nordpool.price.role.price": "Current price sensor of the Nord Pool integration (currency per kWh)", + "template.nordpool.price.param.config_entry": "ID of the Nord Pool configuration entry in Home Assistant", + "template.nordpool.price.param.areas": "Price area, for example SE3 (empty: the area set up in the integration)", + "template.nordpool.price.param.currency": "Currency of the prices (empty: the currency set up in the integration)", + "template.octopus_energy.rates.name": "Octopus Energy rates", + "template.octopus_energy.rates.role.price": "Current import rate sensor of Octopus Energy (GBP per kWh)", + "template.octopus_energy.rates.role.current_day_rates": "Event entity “Current day rates” (import) of Octopus Energy", + "template.octopus_energy.rates.role.next_day_rates": "Event entity “Next day rates” (import) of Octopus Energy (optional)", "template.solcast.pv.name": "Solcast PV forecast", "template.solcast.pv.role.forecast_today": "Solcast sensor for today's forecast (kWh)", "template.solcast.pv.role.forecast_tomorrow": "Solcast sensor for tomorrow's forecast (kWh)", @@ -783,6 +818,7 @@ "wizard.check.battery_sign_soc": "The battery charges at {battery_w} W although it is at {soc_pct} % (or discharges while empty). The sign may be inverted.", "wizard.check.entities_fresh": "All {count, plural, one {# sensor delivers} other {# sensors deliver}} current values.", "wizard.check.duplicate_unit": "“{device_a}” and “{device_b}” control the same unit “{unit_name}” (two integrations or the same entity twice). Control a unit only once.", + "wizard.check.tariff_spot_without_formula": "The tariff delivers bare market prices and no price formula is set. Add your grid fee, levies and VAT, otherwise the prices are too low to plan with.", "wizard.check.entity_invalid": "{entity_id} does not deliver a number.", "wizard.check.entity_missing": "{entity_id} does not exist in Home Assistant.", "wizard.check.entity_stale": "{entity_id} has not updated for a while.", @@ -845,6 +881,9 @@ "api.validation.forecast_manual_weight": "A manual weighting needs a weight.", "api.validation.grid_charge_needs_limit": "Grid charging needs a price level or a schedule.", "api.validation.import_formula_dynamic_only": "A price formula only applies to a dynamic tariff.", + "api.validation.import_param_missing": "The tariff {template_id} needs the setting “{field}”.", + "api.validation.import_role_price": "The price sensor is set with “price sensor”, not as an additional entity.", + "api.validation.import_source_dynamic_only": "Sensors, request settings and a price statement only apply to a dynamic tariff.", "api.validation.import_tou_extra": "A time-of-use tariff takes no fixed price, template or price sensor.", "api.validation.import_tou_needs_periods": "A time-of-use tariff needs its time windows and prices.", "api.validation.import_tou_only": "Time windows with prices need the time-of-use tariff.", @@ -864,5 +903,48 @@ "api.validation.forecast_workday_domain": "{entity_id} is not a binary sensor. Choose the binary sensor of the Workday integration.", "api.validation.forecast_weather_domain": "{entity_id} is not a weather entity.", "planner.battery.morning_buffer": "Battery first until {soc_pct, number, ::.0} %: {cause, select, prefer_full {you want the battery as full as possible} forecast_poor {at the {risk, select, cautious {cautious} balanced {balanced} other {bold}} risk level the solar forecast does not cover today and the night with a margin} forecast_uncertain {the solar forecast is uncertain} manual_floor {your minimum morning buffer} other {the solar forecast leaves plenty of surplus}} (left after today and the night at that risk level: {surplus_kwh, number, ::.0} kWh).", - "planner.battery.evening_target": "Evening target {soc_pct, number, ::.0} % ({risk, select, cautious {cautious} balanced {balanced} other {bold}} risk level): {cause, select, prefer_full {you want the battery as full as possible} next_day_deficit {the night ({night_kwh, number, ::.0} kWh) and a weak next day ({deficit_kwh, number, ::.0} kWh more) need it} user_target {your target state of charge} max_soc {capped at the maximum state of charge} other {the night needs {night_kwh, number, ::.0} kWh}}." + "planner.battery.evening_target": "Evening target {soc_pct, number, ::.0} % ({risk, select, cautious {cautious} balanced {balanced} other {bold}} risk level): {cause, select, prefer_full {you want the battery as full as possible} next_day_deficit {the night ({night_kwh, number, ::.0} kWh) and a weak next day ({deficit_kwh, number, ::.0} kWh more) need it} user_target {your target state of charge} max_soc {capped at the maximum state of charge} other {the night needs {night_kwh, number, ::.0} kWh}}.", + "planner.solver.optimal": "Optimised plan (computed in {solve_time_s, number, ::.00} s).", + "planner.solver.incumbent": "Best plan found within the time budget ({solve_time_s, number, ::.00} s); not proven optimal.", + "planner.heuristic.rules": "Rule-based plan: battery first up to the morning buffer, then consumers on surplus while the evening target stays reachable; grid charging only to reach a target.", + "planner.fallback.timeout": "The optimiser found no plan within {budget_s, number, ::.0} s; the rule-based plan is used.", + "planner.fallback.infeasible": "The optimiser could not solve the model; the rule-based plan is used.", + "planner.fallback.error": "The optimiser failed ({error}); the rule-based plan is used.", + "planner.fallback.solver_unavailable": "The optimiser (HiGHS) is not available; the rule-based plan is used.", + "planner.fallback.invalid_solution": "The optimiser's plan failed the feasibility check ({violations} violations); the rule-based plan is used.", + "planner.fallback.heuristic_better": "The rule-based plan is cheaper than the optimiser's interim result ({status}) and is used.", + "planner.fallback.no_prices": "No electricity prices: planning for self-sufficiency only, without price optimisation.", + "planner.fallback.spot_without_formula": "{source} delivers bare spot prices and no price formula is configured: planning without price optimisation until the formula is set.", + "planner.input.prices_partial": "Prices are known until {known_until}; {filled_slots} later quarter hours are planned with the median price.", + "planner.input.no_pv_forecast": "No solar forecast: the plan assumes no solar power.", + "planner.input.no_load_forecast": "No load forecast yet: the plan assumes a flat base load of {load_w, number, ::0} W and plans no consumers.", + "planner.input.no_battery_soc": "The battery's state of charge is unknown: the battery is left out of the plan.", + "planner.input.device_power_unknown": "The power of {device} is unknown: it is left out of the plan.", + "planner.battery.grid_charge": "Charge from the grid from {from, number, ::.0} % to {to, number, ::.0} % at {price, number, ::.000}/kWh: later the price reaches {later_price, number, ::.000}/kWh ({later_time}).", + "planner.battery.charge_surplus": "Store {power_w, number, ::0} W of solar surplus (battery {soc_pct, number, ::.0} %).", + "planner.battery.discharge_house": "The battery supplies the house with {power_w, number, ::0} W (battery {soc_pct, number, ::.0} %).", + "planner.battery.hold_for_evening": "Hold the battery: it should be at {soc_pct, number, ::.0} % at {time}; the house draws from the grid meanwhile.", + "planner.battery.hold_for_price": "Hold the battery at {price, number, ::.000}/kWh: its energy is worth more at {later_time} ({later_price, number, ::.000}/kWh).", + "planner.battery.at_reserve": "The battery is at its reserve ({soc_pct, number, ::.0} %): the house draws from the grid.", + "planner.battery.full": "The battery is full ({soc_pct, number, ::.0} %).", + "planner.battery.prefer_full": "Battery first until {soc_pct, number, ::.0} %: you want the battery as full as possible.", + "planner.battery.user_target": "Your target: {soc_pct, number, ::.0} % at {time}.", + "planner.battery.target_shortfall": "{goal, select, morning_buffer {The morning buffer} prefer_full {Full battery} user_target {Your target} other {The evening target}} of {target_pct, number, ::.0} % at {time} cannot be reached: the plan expects {planned_pct, number, ::.0} %.", + "planner.device.surplus": "{device} runs on solar surplus ({power_w, number, ::0} W).", + "planner.device.throttled": "{device} waits: the battery needs the surplus to reach {soc_pct, number, ::.0} % by {time}.", + "planner.export.negative_price_avoided": "Export pays nothing now ({price, number, ::.000}/kWh): the surplus goes into the battery and consumers instead.", + "planner.export.limit": "The export limit ({limit_w, number, ::0} W) is reached: the rest of the solar power would be curtailed.", + "planner.export.surplus": "Export {power_w, number, ::0} W at {price, number, ::.000}/kWh.", + "planner.grid.import": "The house draws {power_w, number, ::0} W from the grid at {price, number, ::.000}/kWh.", + "planner.interval.balanced": "Nothing to plan: solar power and consumption balance.", + "planner.status.waiting_for_inputs": "Waiting for prices and forecasts before the first plan; the plan starts at the latest {grace_s, number, ::0} s after the first connection.", + "planner.status.no_inputs": "Nothing to plan yet: the site is not set up or Home Assistant is not connected.", + "planner.status.run_failed": "The last planning run failed ({error}); the previous plan stays in use.", + "planner.status.run_timeout": "The planning run did not finish within {limit_s, number, ::0} s; the previous plan stays in use.", + "planner.status.run_stuck": "An earlier planning run is still running; no new run was started.", + "planner.status.stale": "The plan is older than {age_h, number, ::.0} h: SunCore controls without it (surplus rules only) until a new plan arrives.", + "planner.status.expired": "The plan has run out: SunCore controls without it (surplus rules only) until a new plan arrives.", + "planner.status.no_plan": "There is no plan yet: SunCore controls on surplus rules only.", + "api.error.planning_unavailable": "The planner is not running (no site is set up).", + "planner.status.waiting_for_soc": "Waiting for the battery's state of charge before planning." } diff --git a/pyproject.toml b/pyproject.toml index b52e439..4a0a5e6 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -23,6 +23,8 @@ dependencies = [ "aiohttp>=3.14.5", "aiosqlite>=0.22.1", "fastapi>=0.143.0", + "highspy>=1.11", + "numpy>=2.3", "pydantic>=2.11,<3", "pydantic-settings>=2.15.0", "pyyaml>=6.0.3", diff --git a/scripts/bench_planner.py b/scripts/bench_planner.py new file mode 100755 index 0000000..2ac8a11 --- /dev/null +++ b/scripts/bench_planner.py @@ -0,0 +1,90 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: Apache-2.0 +"""Benchmark of the planner on the maintainer's reference house (Phase 4 WP8, risk R3). + +17 kWp east-west, 29.6 kWh battery (10 kW), Tibber-like 15-minute prices for 48 h, export limit +13.5 kW, tiered EEG export price blended by kWp share, two climate devices with a value +(``suncore.sim.planner_scenarios.reference_situation``). Prints the median of ``--runs`` runs: +building the inputs (incl. the risk model's targets), the HiGHS solve cold and warm-started from +the previous plan, the heuristic, and the model size. The budget (ADR-0003, BRIEF §2) is 10 s on +a Raspberry Pi 4; CI checks < 3 s on x86 (``tests/planner/test_bench.py``). + +Usage: ``uv run python scripts/bench_planner.py [--runs 5] [--json]``. +""" + +from __future__ import annotations + +import argparse +import json +import platform +import statistics +import sys +import time + +from suncore.planner.heuristic import heuristic_schedule +from suncore.planner.run import run +from suncore.sim.planner_scenarios import reference_situation, situation_inputs + + +def bench(runs: int) -> dict[str, float | int | str]: + situation = reference_situation() + build, cold, warm, heuristic, total = [], [], [], [], [] + stats: dict[str, float | int | str] = {} + for _ in range(runs): + started = time.perf_counter() + inputs = situation_inputs(situation) + build.append(time.perf_counter() - started) + started = time.perf_counter() + first = run(inputs) + total.append(time.perf_counter() - started) + second = run(inputs, warm_start=first.plan) + assert first.solver is not None + assert second.solver is not None + cold.append(first.solver.solve_time_s) + warm.append(second.solver.solve_time_s) + started = time.perf_counter() + heuristic_schedule(inputs) + heuristic.append(time.perf_counter() - started) + plan_stats = first.plan.stats + assert plan_stats is not None + stats = { + "source": first.source, + "status": plan_stats.status, + "slots": inputs.n, + "vars": first.n_vars, + "rows": first.n_rows, + "binaries": plan_stats.n_binaries, + "iterations_cold": first.solver.iterations, + "iterations_warm": second.solver.iterations, + "objective": round(first.objective, 4), + "heuristic_objective": round(first.heuristic_objective, 4), + } + return { + "machine": f"{platform.machine()} {platform.python_implementation()} " + f"{platform.python_version()}", + "runs": runs, + "build_inputs_s": round(statistics.median(build), 4), + "solve_cold_s": round(statistics.median(cold), 4), + "solve_warm_s": round(statistics.median(warm), 4), + "heuristic_s": round(statistics.median(heuristic), 4), + "plan_total_s": round(statistics.median(total), 4), + **stats, + } + + +def main() -> int: + parser = argparse.ArgumentParser(description=__doc__.splitlines()[0]) + parser.add_argument("--runs", type=int, default=5) + parser.add_argument("--json", action="store_true") + args = parser.parse_args() + result = bench(max(1, args.runs)) + if args.json: + print(json.dumps(result)) + else: + for key, value in result.items(): + print(f"{key:20s} {value}") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/scripts/check_reasons.py b/scripts/check_reasons.py index 0bbf5cc..61f149f 100644 --- a/scripts/check_reasons.py +++ b/scripts/check_reasons.py @@ -8,9 +8,10 @@ * string constants starting with ``api.error.`` (the error ``detail`` keys of the API) or ``api.validation.`` in ``suncore/api`` (validation issue keys), * string constants that are exactly one key with the prefix ``wizard.`` (check and import - reasons built from a variable), ``detect.criterion.`` or ``ha.error.`` anywhere - in ``suncore/``, and ``controller.`` in ``suncore/controller/reasons.py`` (the - controller's key constants). + reasons built from a variable), ``detect.criterion.``, ``ha.error.`` or ``tariff.error.`` + (the tariff adapters' error keys) anywhere in ``suncore/``, and ``controller.`` in + ``suncore/controller/reasons.py`` (the controller's key constants) and ``planner.`` in + ``suncore/planner/reasons.py`` (the planner's). Each key must be present in ``frontend/src/lib/i18n/locales/en.json`` and ``de.json``. Run via ``uv run python scripts/check_reasons.py``; exit code 1 lists the gaps. @@ -28,10 +29,12 @@ SOURCE = ROOT / "suncore" LOCALES = ROOT / "frontend" / "src" / "lib" / "i18n" / "locales" ERROR_PREFIXES = ("api.error.", "api.validation.") -KEY_PREFIXES = ("wizard.", "detect.criterion.", "ha.error.") +KEY_PREFIXES = ("wizard.", "detect.criterion.", "ha.error.", "tariff.error.") CONTROLLER_KEYS = Path("controller") / "reasons.py" """The controller defines its keys as constants in one module (log event names elsewhere may share the ``controller.`` prefix).""" +PLANNER_KEYS = Path("planner") / "reasons.py" +"""The planner's keys, also constants in one module (Phase 4 WP8).""" KEY_RE = re.compile(r"^[a-z][a-z0-9_]*(\.[a-z0-9_]+)+$") @@ -77,6 +80,8 @@ def collect_keys(source: Path = SOURCE) -> dict[str, list[str]]: prefixes = KEY_PREFIXES if path == source / CONTROLLER_KEYS: prefixes = (*KEY_PREFIXES, "controller.") + elif path == source / PLANNER_KEYS: + prefixes = (*KEY_PREFIXES, "planner.") for node in ast.walk(tree): keys: list[str] = [] if isinstance(node, ast.Call) and _is_reason_call(node): diff --git a/suncore/api/__init__.py b/suncore/api/__init__.py index 172ac52..8d6ab3e 100644 --- a/suncore/api/__init__.py +++ b/suncore/api/__init__.py @@ -9,6 +9,7 @@ HealthReport, PeerPolicy, Services, + TariffNotConfiguredError, UnknownRoleError, UnknownTemplateError, ) @@ -20,6 +21,7 @@ "HealthReport", "PeerPolicy", "Services", + "TariffNotConfiguredError", "UnknownRoleError", "UnknownTemplateError", "create_app", diff --git a/suncore/api/app.py b/suncore/api/app.py index ff32019..7a7055c 100644 --- a/suncore/api/app.py +++ b/suncore/api/app.py @@ -25,6 +25,7 @@ from fastapi.exceptions import RequestValidationError from fastapi.responses import FileResponse, JSONResponse, Response from pydantic import BaseModel, TypeAdapter +from pydantic_core import PydanticCustomError from starlette.websockets import WebSocketState from suncore.api.limits import BodyLimitMiddleware @@ -48,6 +49,7 @@ InfoOut, LiveMessage, ModeRequest, + PlanMessage, PreviewItemOut, PreviewOut, SnapshotMessage, @@ -62,6 +64,7 @@ EntityQuery, HAUnavailableError, Services, + TariffNotConfiguredError, UnknownRoleError, UnknownTemplateError, ) @@ -71,6 +74,7 @@ OperationConfig, TariffConfig, formula_on_all_in_source, + missing_action_params, ) from suncore.core.controlstate import ( ControlState, @@ -93,19 +97,23 @@ PvForecastView, RiskView, ) +from suncore.planner.views import PlanStatusView, PlanView, ReplanAck from suncore.storage.errors import ( ConfigCorruptError, HistoryEntryNotFoundError, ImportRejectedError, UnknownSectionError, ) +from suncore.tariff.report import PriceReport from suncore.templates import TemplateCatalog -from suncore.templates.models import TariffTemplate, TemplateKind +from suncore.templates.models import ActionSeries, TariffTemplate, TemplateKind log = logging.getLogger(__name__) API_PREFIX: Final = "/api/v1" DECISIONS_MAX: Final = 1000 +PRICES_MAX_HOURS: Final = 72 +PLAN_MAX_HOURS: Final = 48 # Stable error keys for ``detail``; the SPA renders them through the message catalogue. ERR_HA_UNAVAILABLE: Final = "api.error.ha_unavailable" @@ -126,6 +134,8 @@ ERR_UNKNOWN_PROPOSAL: Final = "api.error.unknown_proposal" ERR_DEVICE_IDENTITY_CHANGED: Final = "api.error.device_identity_changed" ERR_MODE_RAISE_REJECTED: Final = "api.error.mode_raise_rejected" +ERR_TARIFF_NOT_CONFIGURED: Final = "api.error.tariff_not_configured" +ERR_PLANNING_UNAVAILABLE: Final = "api.error.planning_unavailable" BODY_MAX_BYTES: Final = 64 * 1024 """Limit of the small JSON bodies of the wizard endpoints (check, preview).""" SECTION_MAX_BYTES: Final = 256 * 1024 @@ -155,6 +165,8 @@ def create_app( app.add_middleware(PeerCheckMiddleware, policy=services.peer_policy) app.add_exception_handler(RequestValidationError, validation_exception_handler) _register_http(app, services) + _register_prices(app, services) + _register_plan(app, services) _register_live(app, services, live_min_interval_s, live_health_interval_s) _mount_spa(app, services) app.openapi = lambda: _openapi(app) # type: ignore[method-assign] @@ -323,6 +335,74 @@ async def forecast_risk() -> RiskView: return await services.forecast_risk() +def _register_prices(app: FastAPI, services: Services) -> None: + @app.get( + f"{API_PREFIX}/prices", + response_model=PriceReport, + responses={404: {"model": ErrorOut, "description": "No usable tariff is configured"}}, + operation_id="get_prices", + ) + async def prices( + hours: int = Query(default=48, ge=1, le=PRICES_MAX_HOURS), + ) -> PriceReport: + """Import and export prices on the 15-minute grid from now to the end of the known + prices (at least 24 h where the tariff allows, at most ``hours``), with the source + and its freshness. A price is ``null`` where no source value covers the interval.""" + try: + return await services.prices(hours) + except TariffNotConfiguredError as exc: + raise HTTPException(status_code=404, detail=ERR_TARIFF_NOT_CONFIGURED) from exc + + +def _register_plan(app: FastAPI, services: Services) -> None: + """The planner: current plan, scheduler status and a manual replan (Phase 4 WP9).""" + + @app.get( + f"{API_PREFIX}/plan", + response_model=PlanView, + operation_id="get_plan", + responses={409: {"model": ErrorOut, "description": "The planner is not running"}}, + ) + async def plan(hours: int = Query(default=PLAN_MAX_HOURS, ge=1, le=PLAN_MAX_HOURS)) -> PlanView: + """The current plan from now to ``hours`` ahead: per 15-minute interval the expected + flows, prices, battery and device bands and the reasons; who made it (``solver``, + ``heuristic`` or ``default`` = none yet), the solver statistics, ``stale`` and whether + the controller follows it (``in_use``; else ``fallback`` says why).""" + try: + return await services.plan_view(hours) + except RuntimeError as exc: + raise HTTPException(status_code=409, detail=ERR_PLANNING_UNAVAILABLE) from exc + + @app.get( + f"{API_PREFIX}/plan/status", + response_model=PlanStatusView, + operation_id="plan_status", + responses={409: {"model": ErrorOut, "description": "The planner is not running"}}, + ) + async def plan_status() -> PlanStatusView: + """Last run (time, duration, outcome and reason), pending events and the next run.""" + try: + return await services.plan_status() + except RuntimeError as exc: + raise HTTPException(status_code=409, detail=ERR_PLANNING_UNAVAILABLE) from exc + + @app.post( + f"{API_PREFIX}/plan/replan", + response_model=ReplanAck, + status_code=202, + operation_id="replan", + responses={409: {"model": ErrorOut, "description": "The planner is not running"}}, + ) + async def replan() -> ReplanAck: + """Ask for a new plan. Debounced (at most one event-triggered run per minute) and + answered at once with the earliest start; the new plan arrives as a ``plan`` message + on the live feed.""" + try: + return await services.replan() + except RuntimeError as exc: + raise HTTPException(status_code=409, detail=ERR_PLANNING_UNAVAILABLE) from exc + + def _register_control(app: FastAPI, services: Services) -> None: """Control state, emergency stop, overrides, proposals and operating modes (WP9).""" @@ -484,16 +564,22 @@ def _check_tariff_against_catalog(tariff: TariffConfig, catalog: TemplateCatalog template_id = tariff.import_.template_id template = catalog.get(template_id) if template_id is not None else None includes = template.price_includes if isinstance(template, TariffTemplate) else None + includes = tariff.import_.price_includes or includes # the user's statement wins + problems: list[tuple[tuple[str, ...], PydanticCustomError]] = [] error = formula_on_all_in_source(tariff, includes) if error is not None: + problems.append((("body", "import", "formula"), error)) + if isinstance(template, TariffTemplate) and isinstance(template.price_series, ActionSeries): + required = [p.name for p in template.price_series.params if p.required] + problems.extend( + (("body", "import", "action_params", name), error) + for name, error in missing_action_params(tariff, template.id, required) + ) + if problems: raise RequestValidationError( [ - { - "type": error.type, - "loc": ("body", "import", "formula"), - "msg": error.message(), - "ctx": error.context or {}, - } + {"type": e.type, "loc": loc, "msg": e.message(), "ctx": e.context or {}} + for loc, e in problems ] ) @@ -614,6 +700,7 @@ async def live(ws: WebSocket) -> None: services.add_change_listener(wake.flows), services.add_health_listener(wake.health), services.add_control_listener(wake.control), + services.add_plan_listener(wake.plan), ) pump = asyncio.create_task( _pump(ws, services, wake, live_min_interval_s, live_health_interval_s) @@ -641,6 +728,7 @@ def __init__(self) -> None: self.flows_changed = False self.health_changed = False self.control_changed = False + self.plan_changed = False def flows(self) -> None: self.flows_changed = True @@ -654,9 +742,14 @@ def control(self) -> None: self.control_changed = True self.event.set() - def take(self) -> tuple[bool, bool, bool]: - taken = (self.flows_changed, self.health_changed, self.control_changed) + def plan(self) -> None: + self.plan_changed = True + self.event.set() + + def take(self) -> tuple[bool, bool, bool, bool]: + taken = (self.flows_changed, self.health_changed, self.control_changed, self.plan_changed) self.flows_changed = self.health_changed = self.control_changed = False + self.plan_changed = False self.event.clear() return taken @@ -721,10 +814,13 @@ async def _pump( await asyncio.wait_for( wake.event.wait(), timeout=max(0.0, next_health - loop.time()) ) - flows_changed, state_changed, control_changed = wake.take() + flows_changed, state_changed, control_changed, plan_changed = wake.take() if flows_changed: msg = FlowsMessage(flows=_flows_out(services)) await ws.send_json(msg.model_dump(mode="json")) + if plan_changed: + pmsg = PlanMessage(plan=services.plan_summary()) + await ws.send_json(pmsg.model_dump(mode="json")) if control_changed: cmsg = ControlMessage(control=services.control_state()) await ws.send_json(cmsg.model_dump(mode="json")) diff --git a/suncore/api/models.py b/suncore/api/models.py index 08edd9a..f482978 100644 --- a/suncore/api/models.py +++ b/suncore/api/models.py @@ -20,6 +20,7 @@ from suncore.core.detection import DetectedEntity, EnergySuggestions from suncore.core.site import SiteConfig from suncore.core.wizard import CheckItem, PreviewItem, worst_severity +from suncore.planner.views import PlanSummary from suncore.storage import HistoryEntry from suncore.templates import ( DeviceTemplate, @@ -425,8 +426,20 @@ class ControlMessage(_Model): control: ControlState +class PlanMessage(_Model): + """A new plan was computed (summary only; fetch ``GET /api/v1/plan`` for the intervals).""" + + type: Literal["plan"] = "plan" + plan: PlanSummary + + LiveMessage = Annotated[ - SnapshotMessage | FlowsMessage | HealthMessage | DecisionsMessage | ControlMessage, + SnapshotMessage + | FlowsMessage + | HealthMessage + | DecisionsMessage + | ControlMessage + | PlanMessage, Field(discriminator="type"), ] """Everything the server sends on ``/api/v1/live`` (discriminated by ``type``).""" @@ -453,6 +466,7 @@ class ControlMessage(_Model): "InfoOut", "LiveMessage", "ModeRequest", + "PlanMessage", "PreviewItemOut", "PreviewOut", "SnapshotMessage", diff --git a/suncore/api/services.py b/suncore/api/services.py index 405ac2a..0400d80 100644 --- a/suncore/api/services.py +++ b/suncore/api/services.py @@ -28,7 +28,9 @@ PvForecastView, RiskView, ) +from suncore.planner.views import PlanStatusView, PlanSummary, PlanView, ReplanAck from suncore.storage import HistoryEntry +from suncore.tariff.report import PriceReport from suncore.templates import TemplateCatalog FATAL_HA_STATES: Final = frozenset({"auth_failed", "closed"}) @@ -240,6 +242,36 @@ def add_control_listener(self, listener: Callable[[], None]) -> Callable[[], Non """Call ``listener`` whenever the control state may have changed (tick, decision, mode).""" ... + async def prices(self, hours: int) -> PriceReport: + """The planning prices (15-minute grid) with source and freshness. + + Raises :class:`TariffNotConfiguredError` while no usable tariff exists. + """ + ... + + # --- planner (Phase 4 WP9) ----------------------------------------------------------- + + async def plan_view(self, hours: int) -> PlanView: + """The current plan (intervals from now to ``hours`` ahead) and whether the controller + follows it; ``Plan.default()`` before the first plan.""" + ... + + async def plan_status(self) -> PlanStatusView: + """Last run (time, duration, outcome), pending events and the next scheduled run.""" + ... + + async def replan(self) -> ReplanAck: + """Queue a planner run (debounced); returns at once.""" + ... + + def plan_summary(self) -> PlanSummary: + """The short form of the current plan for the live feed.""" + ... + + def add_plan_listener(self, listener: Callable[[], None]) -> Callable[[], None]: + """Call ``listener`` whenever a new plan was handed over.""" + ... + async def export_config(self) -> dict[str, Any]: ... async def import_config(self, data: object) -> list[str]: @@ -269,3 +301,7 @@ class UnknownRoleError(LookupError): class UnknownTemplateError(LookupError): """No template with the requested id is loaded.""" + + +class TariffNotConfiguredError(LookupError): + """No usable tariff (none stored, no region, or its template is missing).""" diff --git a/suncore/api/validation.py b/suncore/api/validation.py index 5eacd41..a29acaa 100644 --- a/suncore/api/validation.py +++ b/suncore/api/validation.py @@ -118,6 +118,9 @@ "suncore.forecast_workday_domain": "api.validation.forecast_workday_domain", "suncore.grid_charge_needs_limit": "api.validation.grid_charge_needs_limit", "suncore.import_formula_dynamic_only": "api.validation.import_formula_dynamic_only", + "suncore.import_param_missing": "api.validation.import_param_missing", + "suncore.import_role_price": "api.validation.import_role_price", + "suncore.import_source_dynamic_only": "api.validation.import_source_dynamic_only", "suncore.import_tou_extra": "api.validation.import_tou_extra", "suncore.import_tou_needs_periods": "api.validation.import_tou_needs_periods", "suncore.import_tou_only": "api.validation.import_tou_only", diff --git a/suncore/app/adapters.py b/suncore/app/adapters.py index 661bf28..67bce42 100644 --- a/suncore/app/adapters.py +++ b/suncore/app/adapters.py @@ -5,8 +5,10 @@ the Home Assistant connection. It is the only module of ``suncore.app`` that may call ``HAConnection.call_action_response`` (``tests/safety/test_boundary.py``, rule 7): the call is a read-only action with ``return_response`` and is rate limited per ``(domain, service)`` by the -connection (``ActionRateLimiter``). An adapter passes the polling interval of its template as -``min_interval_s`` and treats ``ActionRateLimitedError`` as "use the last value". +connection (``ActionRateLimiter``). The tariff engine passes ``DEFAULT_MIN_INTERVAL_S`` (30 s, +the limiter's floor) as ``min_interval_s``; how often the service asks is its own refresh +logic. A throttled call means "use the last value" +(:class:`~suncore.tariff.errors.SourceThrottledError`). The PV forecast sources read through :class:`HaPvDataReader`: attributes of the entity cache (no extra Home Assistant call), the Energy dashboard's ``energy/solar_forecast`` through @@ -16,15 +18,24 @@ The load forecast reads through :class:`HaLoadReader`: the ``workday`` binary sensor's state and the weather entity's ``temperature`` attribute from the entity cache, and the read-only actions ``workday.check_date`` (per date) and ``weather.get_forecasts`` (``type: hourly``). + +The tariff side provides: + +* :class:`ConnectionActionCaller` - the ``ActionCaller`` of the tariff engine; +* :func:`cache_reader` - the ``EntityReader`` on top of the entity cache; +* :func:`build_tariff_plan` / :func:`build_tariff_service` - configuration -> service. """ from __future__ import annotations from collections.abc import Awaitable, Callable, Mapping -from datetime import date, datetime, tzinfo +from datetime import date, datetime, time, tzinfo from typing import Any -from suncore.core.config import ForecastConfig +import structlog + +from suncore.core.config import ForecastConfig, RegionConfig, TariffConfig +from suncore.core.site import SiteConfig from suncore.forecast.accuracy import LearnedParams from suncore.forecast.load import ( WorkdayState, @@ -41,9 +52,29 @@ PvForecastService, SourceSettings, ) -from suncore.ha import EntityCache, HAConnection, fetch_solar_forecast +from suncore.ha import EntityCache, HAConnection, HAError, fetch_solar_forecast from suncore.ha.cache import UNAVAILABLE_STATES -from suncore.templates import TemplateCatalog +from suncore.ha.connection import ActionRateLimitedError +from suncore.tariff import ( + CurrentPriceSource, + EntityReader, + EntityReading, + FixedPriceSource, + PriceStore, + SegmentSource, + ServiceSettings, + SourceBinding, + SourceFailedError, + SourceThrottledError, + TariffPlan, + TariffService, + TemplatePriceSource, + TouPriceSource, +) +from suncore.templates import RegionTemplate, TariffTemplate, TemplateCatalog +from suncore.templates.models import NegativePriceRule + +log = structlog.get_logger(__name__) class HaPvDataReader: @@ -194,9 +225,181 @@ def build_load_forecast_service( ) +class ConnectionActionCaller: + """``ActionCaller`` on a Home Assistant connection (read-only actions only). + + A call the rate limiter skips becomes :class:`SourceThrottledError` (not a failure: the + service keeps the last prices); anything else Home Assistant answers wrong becomes + :class:`SourceFailedError`. + """ + + def __init__(self, connection: HAConnection) -> None: + self._connection = connection + + async def __call__( + self, + domain: str, + service: str, + data: Mapping[str, Any], + *, + min_interval_s: float, + max_wait_s: float, + ) -> Mapping[str, Any]: + try: + return await self._connection.call_action_response( + domain, service, data, min_interval_s=min_interval_s, max_wait_s=max_wait_s + ) + except ActionRateLimitedError as exc: + raise SourceThrottledError(exc.retry_after_s) from exc + except (HAError, TimeoutError) as exc: + raise SourceFailedError(f"{type(exc).__name__}: {exc}") from exc + + +def cache_reader(cache: EntityCache) -> EntityReader: + """Entity readings from the cache; ``unavailable`` and absent entities read as ``None``. + + ``unknown`` is returned as is: an event entity is ``unknown`` until its first event while + its attributes may already be restored. + """ + + def read(entity_id: str) -> EntityReading | None: + entry = cache.get(entity_id) + if entry is None or entry.state.state == "unavailable": + return None + return EntityReading(entry.state.state, entry.state.attributes) + + return read + + +def negative_price_rule(catalog: TemplateCatalog, region: RegionConfig) -> NegativePriceRule: + """The region template's rule (``none`` for an unknown or user-defined region).""" + template = catalog.get(region.region_id) + return ( + template.negative_price_rule + if isinstance(template, RegionTemplate) + else NegativePriceRule.NONE + ) + + +def _import_source( + tariff: TariffConfig, + region: RegionConfig, + tz: tzinfo, + catalog: TemplateCatalog, + *, + connection: HAConnection, + cache: EntityCache, + clock: Callable[[], datetime], +) -> SegmentSource | None: + imp = tariff.import_ + if imp.kind == "fixed": + assert imp.fixed_price is not None + return FixedPriceSource(price=imp.fixed_price) + if imp.kind == "tou": + assert imp.tou is not None + return TouPriceSource(tou=imp.tou, tz=tz) + reader = cache_reader(cache) + template = catalog.get(imp.template_id) if imp.template_id is not None else None + if not isinstance(template, TariffTemplate) or template.price_series is None: + if imp.template_id is not None: + log.warning("tariff.template_unusable", template_id=imp.template_id) + return None + assert imp.price_entity is not None + return CurrentPriceSource( + imp.price_entity.entity_id, + reader, + price_includes=imp.price_includes or "all_in", + clock=clock, + ) + entities = {role: ref.entity_id for role, ref in imp.role_entities.items()} + if imp.price_entity is not None: + entities["price"] = imp.price_entity.entity_id + binding = SourceBinding( + tz=tz, + entities=entities, + action_params=imp.action_params, + series_key=imp.series_key, + price_includes=imp.price_includes, + currency=region.currency, + ) + return TemplatePriceSource( + template, + binding, + action=ConnectionActionCaller(connection), + attributes=reader, + clock=clock, + ) + + +def build_tariff_plan( + tariff: TariffConfig, + region: RegionConfig, + site: SiteConfig | None, + tz: tzinfo, + catalog: TemplateCatalog, + *, + connection: HAConnection, + cache: EntityCache, + clock: Callable[[], datetime], +) -> TariffPlan | None: + """The resolved tariff, ``None`` when its template is missing or not a price curve.""" + source = _import_source( + tariff, region, tz, catalog, connection=connection, cache=cache, clock=clock + ) + if source is None: + return None + return TariffPlan( + source=source, + export_tariff=tariff.export, + negative_rule=negative_price_rule(catalog, region), + tz=tz, + currency=region.currency, + formula=tariff.import_.formula, + total_kwp=None if site is None else site.total_kwp, + ) + + +def build_tariff_service( + tariff: TariffConfig, + region: RegionConfig, + site: SiteConfig | None, + tz: tzinfo, + catalog: TemplateCatalog, + *, + connection: HAConnection, + cache: EntityCache, + clock: Callable[[], datetime], + store: PriceStore | None, + refresh_interval_s: float = 3600.0, + tomorrow_after: time = time(13, 0), + tomorrow_poll_s: float = 900.0, +) -> TariffService | None: + """A :class:`TariffService` for the stored tariff, ``None`` if it cannot be built. + + Raises :class:`~suncore.tariff.errors.ExportConfigError` for a tiered export that the + site's size does not allow (the caller logs it and runs without prices). + """ + plan = build_tariff_plan( + tariff, region, site, tz, catalog, connection=connection, cache=cache, clock=clock + ) + if plan is None: + return None + settings = ServiceSettings( + refresh_interval_s=refresh_interval_s, + tomorrow_after=tomorrow_after, + tomorrow_poll_s=tomorrow_poll_s, + ) + return TariffService(plan, clock=clock, store=store, settings=settings) + + __all__ = [ + "ConnectionActionCaller", "HaLoadReader", "HaPvDataReader", "build_load_forecast_service", "build_pv_forecast_service", + "build_tariff_plan", + "build_tariff_service", + "cache_reader", + "negative_price_rule", ] diff --git a/suncore/app/control.py b/suncore/app/control.py index 79f7164..c350a98 100644 --- a/suncore/app/control.py +++ b/suncore/app/control.py @@ -55,6 +55,7 @@ TEMPERATURE_ROLE, ControlSettings, DeviceState, + Plan, PowerEstimate, has_heat_limit, ) @@ -109,6 +110,8 @@ """What ``create_driver`` returns, structurally: the gate's actuator plus ``device_state``.""" StateChangeListener = Callable[[], None] +PlanProvider = Callable[[datetime], Plan] +"""``now -> plan`` for the tick (the planner runtime's ``active_plan``).""" MeasurementSink = Callable[[datetime, Mapping[str, float | None]], None] """Receives ``(tick time, {measurement key: value or None})`` after every tick.""" @@ -183,6 +186,8 @@ class ControlStack: measurements of that tick (``suncore.core.measurements`` keys; ``None`` = no valid value). Synchronous and cheap by contract; an exception is logged and swallowed - recording can never disturb the control loop. + plan_provider: ``now -> Plan`` read once per tick (``PlanningService.active_plan``); without + it the plan given to :meth:`set_plan` (default ``Plan.default()``) is used. defer_recover: wait for :meth:`allow_recover` before ``gate.recover()`` (the runtime first learns Home Assistant's time zone, whose change would rebuild the stack in the middle of the recovery). @@ -213,9 +218,12 @@ def __init__( # noqa: PLR0915 - the composition root of the control layer after_handover: bool = False, predecessor: SafetyGate | None = None, defer_recover: bool = False, + plan_provider: PlanProvider | None = None, on_measurements: MeasurementSink | None = None, ) -> None: self._connection = connection + self._plan_provider = plan_provider + self._plan = Plan.default() self._on_measurements = on_measurements self._recover_allowed = not defer_recover self._after_handover = after_handover @@ -386,6 +394,25 @@ def ready(self) -> bool: def set_goals(self, goals: GoalsConfig) -> None: self._goals = goals + def set_plan(self, plan: Plan) -> None: + """Hand a plan to the controller (one reference assignment, read once per tick). + + Ignored while a ``plan_provider`` is installed (the provider decides then). + """ + self._plan = plan + + def current_plan(self, now: datetime) -> Plan: + """The plan for this tick: the provider's, else the one set; ``Plan.default()`` if the + provider fails (the Phase 3 behaviour is the safe fallback).""" + provider = self._plan_provider + if provider is None: + return self._plan + try: + return provider(now) + except Exception: + log.exception("control.plan_provider_failed") + return Plan.default() + def add_listener(self, listener: StateChangeListener) -> Unsubscribe: """Call ``listener`` whenever the control state may have changed (tick, decision).""" self._listeners.append(listener) @@ -700,6 +727,7 @@ async def tick(self) -> TickResult | None: import_limit_w=self._import_limit_w, reserve_soc_pct=self._reserve_soc_pct, goals=self._goals, + plan=self.current_plan(now), ) self.estimates = estimates self.states = states diff --git a/suncore/app/openapi_stub.py b/suncore/app/openapi_stub.py index aa8dec1..fa1c828 100644 --- a/suncore/app/openapi_stub.py +++ b/suncore/app/openapi_stub.py @@ -11,7 +11,8 @@ from pydantic import BaseModel from suncore import __version__ -from suncore.api.services import EntityQuery, HealthReport, PeerPolicy +from suncore.api.services import EntityQuery, HealthReport, PeerPolicy, TariffNotConfiguredError +from suncore.app.planning import LiveReading, PlanningService, PlanningSnapshot from suncore.core.balance import FlowSnapshot from suncore.core.battery import BatterySettings from suncore.core.config import OperationConfig @@ -25,7 +26,9 @@ from suncore.forecast.risk import ErrorModel from suncore.forecast.risk_learning import risk_view from suncore.forecast.views import ForecastAccuracyView, LoadForecastView, PvForecastView, RiskView +from suncore.planner.views import PlanStatusView, PlanSummary, PlanView, ReplanAck from suncore.storage import HistoryEntry +from suncore.tariff.report import PriceReport from suncore.templates import TemplateCatalog @@ -150,6 +153,30 @@ async def set_device_mode( def add_control_listener(self, listener: Callable[[], None]) -> Callable[[], None]: # noqa: ARG002 return lambda: None + async def prices(self, hours: int) -> PriceReport: # noqa: ARG002 + raise TariffNotConfiguredError + + def _planning(self) -> PlanningService: + async def nothing(now: datetime, previous: object) -> PlanningSnapshot: # noqa: ARG001 + return PlanningSnapshot(None) + + return PlanningService(nothing, LiveReading, clock=lambda: datetime.now(UTC)) + + async def plan_view(self, hours: int) -> PlanView: + return self._planning().view(hours) + + async def plan_status(self) -> PlanStatusView: + return self._planning().status() + + async def replan(self) -> ReplanAck: + return self._planning().request("manual") + + def plan_summary(self) -> PlanSummary: + return self._planning().summary() + + def add_plan_listener(self, listener: Callable[[], None]) -> Callable[[], None]: # noqa: ARG002 + return lambda: None + async def export_config(self) -> dict[str, Any]: return {} diff --git a/suncore/app/planning.py b/suncore/app/planning.py new file mode 100644 index 0000000..0d78d8f --- /dev/null +++ b/suncore/app/planning.py @@ -0,0 +1,641 @@ +# SPDX-License-Identifier: Apache-2.0 +"""The planner runtime (Phase 4 WP9): when to plan, with what, and what the controller gets. + +:class:`PlanningService` runs :func:`suncore.planner.run` (HiGHS plus the heuristic fallback) in a +worker thread and hands the resulting :class:`~suncore.core.control.Plan` to the control layer. +Time is injected twice (``clock`` = the now, ``sleep`` = the poll period), like the other +services, so tests and the accelerated demo run it in simulated time. + +**When it runs** (:meth:`PlanningService.tick`, polled every ``poll_s``): + +* *first run* once the inputs exist (prices and forecasts available, or ``first_run_grace_s`` + after the first connection with the missing ones reported by the plan's reasons); +* *every 15 minutes*, aligned to the quarter hour plus ``offset_s`` (so the price and forecast + refreshes of the same quarter land first); +* *on events* (:meth:`request`): new prices, a forecast update, a deviation, a configuration + change, a user override and a manual replan. Event runs are debounced: at most one per + ``min_event_gap_s`` (60 s); events that arrive meanwhile are merged into one run. A run starts + only when no other run is active (single flight) - events during a run wait for its end. + +**Deviation** (documented thresholds, all in :class:`PlanningSettings`): the live SoC differs from +the plan's SoC at ``now`` (linear between the interval boundaries) by more than +``soc_deviation_pct`` (10 %-points), or the actual grid power differs from the planned net power +(import - export) by more than ``net_deviation_w`` (1500 W) for ``net_deviation_s`` (30 min) - +judged on a 10-minute exponential average of the difference so a short cloud does not count. + +**Hand-over**: the new plan replaces ``self._plan`` (one reference assignment on the event loop); +the control stack reads :meth:`active_plan` once per tick. The solve runs in a daemon thread +(``run_in_daemon_thread``), never on the event loop; a run that hangs is abandoned after +``run_timeout_s`` (the thread cannot be killed; it is a daemon thread, no new run starts while it +lives, and it never delays shutdown). + +**Failure**: a failed or skipped run keeps the last good plan. After ``stale_after_s`` (2 h) the +plan is *stale*: still served by the API, flagged, but :meth:`active_plan` returns +``Plan.default()`` (the Phase 3 behaviour) - as it does once every interval lies in the past. +Nothing here writes to a device; the plan's bands can only restrict devices and move the +surplus share (``suncore.controller``). +""" + +from __future__ import annotations + +import asyncio +import contextlib +import math +import threading +import time +from collections.abc import Awaitable, Callable +from dataclasses import dataclass +from datetime import UTC, datetime, timedelta +from typing import Final + +import structlog + +from suncore.core.control import Plan +from suncore.core.decisions import Reason +from suncore.planner import reasons as rk +from suncore.planner.inputs import DEFAULT_BUDGET_S, DEFAULT_MIP_GAP, PlannerInputs +from suncore.planner.run import PlannerRun +from suncore.planner.run import run as run_planner +from suncore.planner.views import ( + PlanStatusView, + PlanSummary, + PlanView, + ReplanAck, + RunOutcome, + Trigger, +) +from suncore.storage import PlanSnapshotStore + +log = structlog.get_logger(__name__) + +QUARTER: Final = timedelta(minutes=15) +EVENT_PRIORITY: Final[tuple[Trigger, ...]] = ( + "manual", + "config", + "override", + "deviation", + "prices", + "forecast", +) +"""The trigger a merged event run reports: the first of these that is pending.""" +SOC_START_KEY: Final = "soc_start_pct" +"""``Plan.assumptions`` entry: the live SoC the run started from (deviation check).""" +NET_EMA_S: Final = 600.0 + + +@dataclass(frozen=True, slots=True) +class PlanningSettings: + """Cadence, thresholds and budget of the planner runtime.""" + + budget_s: float = DEFAULT_BUDGET_S + """Solver time budget of a run (ADR-0003).""" + mip_gap: float = DEFAULT_MIP_GAP + offset_s: float = 20.0 + """The scheduled run starts this long after the quarter hour.""" + min_event_gap_s: float = 60.0 + """Debounce: at most one event-triggered run per this many seconds.""" + stale_after_s: float = 7200.0 + """Age after which a plan is stale: flagged, and no longer handed to the controller.""" + soc_deviation_pct: float = 10.0 + net_deviation_w: float = 1500.0 + net_deviation_s: float = 1800.0 + first_run_grace_s: float = 300.0 + """How long the first plan waits for prices and forecasts after the first connection.""" + poll_s: float = 5.0 + retry_skipped_s: float = 15.0 + """Re-check of a skipped (not ready) run.""" + run_timeout_margin_s: float = 30.0 + """A run is abandoned ``budget_s`` plus this long after it started.""" + + @property + def run_timeout_s(self) -> float: + return self.budget_s + self.run_timeout_margin_s + + +@dataclass(frozen=True, slots=True) +class PlanningSnapshot: + """What the collector found: the inputs, or why there are none.""" + + inputs: PlannerInputs | None + complete: bool = True + """Prices and every configured forecast are there (the first plan waits for them).""" + reason: Reason | None = None + """Why ``inputs`` is ``None``.""" + + +@dataclass(frozen=True, slots=True) +class LiveReading: + """The two live values the deviation check compares with the plan.""" + + soc_pct: float | None = None + grid_w: float | None = None + """Grid power, + = import.""" + + +Collector = Callable[[datetime, Plan | None], Awaitable[PlanningSnapshot]] +"""``(now, previous plan) -> snapshot``: the runtime reads its services, calls ``build_inputs``.""" +Solver = Callable[[PlannerInputs, float, float, Plan | None], PlannerRun] +type ThreadRunner[T] = Callable[[Callable[[], T]], Awaitable[T]] +PlanListener = Callable[[], None] + + +def default_solver( + inputs: PlannerInputs, budget_s: float, mip_gap: float, previous: Plan | None +) -> PlannerRun: + return run_planner(inputs, budget_s=budget_s, mip_gap=mip_gap, warm_start=previous) + + +async def run_in_daemon_thread[T](fn: Callable[[], T]) -> T: + """Run ``fn`` in a daemon thread and await its result without ever blocking the loop. + + Unlike ``asyncio.to_thread`` (default executor, joined at shutdown) an abandoned call cannot + keep the process or the loop's shutdown waiting: the awaiting task can be cancelled at any + time and the daemon thread just finishes (or hangs) unobserved. + """ + loop = asyncio.get_running_loop() + future: asyncio.Future[T] = loop.create_future() + + def deliver(result: T | None, error: BaseException | None) -> None: + if future.done(): + return + if error is not None: + future.set_exception(error) + else: + future.set_result(result) # type: ignore[arg-type] + + def work() -> None: + result: T | None = None + error: BaseException | None = None + try: + result = fn() + except BaseException as exc: + error = exc + with contextlib.suppress(RuntimeError): # the loop is closed: nobody is waiting + loop.call_soon_threadsafe(deliver, result, error) + + threading.Thread(target=work, name="suncore-planner", daemon=True).start() + return await future + + +# --- pure helpers --------------------------------------------------------------------------- + + +def floor_quarter(moment: datetime) -> datetime: + """The quarter hour (UTC) containing ``moment``.""" + utc = moment.astimezone(UTC) + return utc.replace(minute=utc.minute - utc.minute % 15, second=0, microsecond=0) + + +def planned_soc_at(plan: Plan, now: datetime) -> float | None: + """The plan's SoC at ``now``: linear between the interval's start and end SoC. + + The start SoC of the first interval is the live SoC the run started from + (``assumptions[soc_start_pct]``), of the later ones the previous interval's end SoC. + ``None`` when the plan does not cover ``now`` or has no battery. + """ + ordered = plan.intervals + for index, interval in enumerate(ordered): + if not interval.covers(now): + continue + end = None if interval.expected is None else interval.expected.soc_pct + if end is None: + return None + if index == 0: + raw = plan.assumptions.get(SOC_START_KEY) + start = ( + float(raw) if isinstance(raw, int | float) and not isinstance(raw, bool) else end + ) + else: + previous = ordered[index - 1].expected + start = end if previous is None or previous.soc_pct is None else previous.soc_pct + span = (interval.end - interval.start).total_seconds() + share = 0.0 if span <= 0 else (now - interval.start).total_seconds() / span + return start + (end - start) * min(1.0, max(0.0, share)) + return None + + +def planned_net_w(plan: Plan, now: datetime) -> float | None: + """The planned grid power at ``now`` (+ = import); ``None`` outside the plan.""" + interval = plan.interval_at(now) + if interval is None or interval.expected is None: + return None + return interval.expected.import_w - interval.expected.export_w + + +def plan_ends_at(plan: Plan) -> datetime | None: + return plan.intervals[-1].end if plan.intervals else None + + +# --- the service ---------------------------------------------------------------------------- + + +class PlanningService: + """Schedules the planner, runs it off the event loop and owns the current plan.""" + + def __init__( + self, + collect: Collector, + live: Callable[[], LiveReading], + *, + clock: Callable[[], datetime], + sleep: Callable[[float], Awaitable[None]] = asyncio.sleep, + settings: PlanningSettings | None = None, + store: PlanSnapshotStore | None = None, + solve: Solver = default_solver, + thread: ThreadRunner[PlannerRun] = run_in_daemon_thread, + ) -> None: + self._collect = collect + self._live = live + self._clock = clock + self._sleep = sleep + self._settings = settings or PlanningSettings() + self._store = store + self._solve = solve + self._thread = thread + self._plan: Plan | None = None + self._plan_stamp: datetime | None = None + self._pending: dict[Trigger, datetime] = {} + self._running = False + self._thread_busy = False + self._last_trigger: Trigger | None = None + self._last_started: datetime | None = None + self._last_finished: datetime | None = None + self._last_duration_s: float | None = None + self._last_outcome: RunOutcome | None = None + self._last_ok: datetime | None = None + self._last_reason: Reason | None = None + self._failures = 0 + self._last_slot: datetime | None = None + self._retry_at: datetime | None = None + self._first_input_at: datetime | None = None + self._net_ema: float | None = None + self._net_ema_at: datetime | None = None + self._net_over_since: datetime | None = None + self._listeners: list[PlanListener] = [] + + # --- configuration ------------------------------------------------------------------- + + @property + def settings(self) -> PlanningSettings: + return self._settings + + # --- events -------------------------------------------------------------------------- + + def request(self, trigger: Trigger) -> ReplanAck: + """Ask for a run because of an event; merged and debounced (module doc).""" + now = self._clock() + self._pending.setdefault(trigger, now) + return ReplanAck(earliest_start_at=self._earliest_event_run(now)) + + def _earliest_event_run(self, now: datetime) -> datetime: + if self._last_started is None or self._plan is None: + return now + return max(now, self._last_started + timedelta(seconds=self._settings.min_event_gap_s)) + + def add_listener(self, listener: PlanListener) -> Callable[[], None]: + """Call ``listener`` after every new plan; returns the remover.""" + self._listeners.append(listener) + + def remove() -> None: + with contextlib.suppress(ValueError): + self._listeners.remove(listener) + + return remove + + def _notify(self) -> None: + for listener in list(self._listeners): + try: + listener() + except Exception: + log.exception("planning.listener_failed") + + # --- the plan the controller follows --------------------------------------------------- + + def fallback_reason(self, now: datetime | None = None) -> Reason | None: + """Why the controller does not follow a plan right now (``None`` = it does).""" + moment = self._clock() if now is None else now + plan = self._plan + if plan is None or not plan.intervals: + return Reason(key=rk.STATUS_NO_PLAN) + # Age from the hand-over (review n3); a restored plan without a stamp counts from its + # creation, and a plan with neither is stale. + created = self._plan_stamp or plan.created_at + if created is None: + return Reason(key=rk.STATUS_STALE, args={"age_h": 0.0}) + age_s = (moment - created).total_seconds() + if age_s > self._settings.stale_after_s: + return Reason(key=rk.STATUS_STALE, args={"age_h": round(age_s / 3600.0, 1)}) + end = plan_ends_at(plan) + if end is not None and moment >= end: + return Reason(key=rk.STATUS_EXPIRED) + return None + + def active_plan(self, now: datetime | None = None) -> Plan: + """The plan for the controller's tick: the current one, or ``Plan.default()`` when there + is none, it is stale or every interval is in the past. One reference read, no locks.""" + plan = self._plan + if plan is None or self.fallback_reason(now) is not None: + return Plan.default() + return plan + + @property + def plan(self) -> Plan | None: + """The newest good plan, however old.""" + return self._plan + + # --- read models ----------------------------------------------------------------------- + + def summary(self, now: datetime | None = None) -> PlanSummary: + moment = self._clock() if now is None else now + plan = self._plan + fallback = self.fallback_reason(moment) + stale = fallback is not None and fallback.key == rk.STATUS_STALE + if plan is None: + return PlanSummary( + created_at=None, + source="default", + status=None, + solve_time_s=None, + intervals=0, + horizon_end=None, + stale=False, + in_use=False, + ) + return PlanSummary( + created_at=plan.created_at, + source=plan.source, + status=None if plan.stats is None else plan.stats.status, + solve_time_s=None if plan.stats is None else plan.stats.solve_time_s, + intervals=len(plan.intervals), + horizon_end=plan_ends_at(plan), + stale=stale, + in_use=fallback is None, + reasons=list(plan.reasons), + ) + + def view(self, hours: int = 48, now: datetime | None = None) -> PlanView: + moment = self._clock() if now is None else now + plan = self._plan + fallback = self.fallback_reason(moment) + if plan is None: + return PlanView( + generated_at=moment, + plan=Plan.default(), + stale=False, + expired=False, + in_use=False, + fallback=fallback, + ) + horizon = moment + timedelta(hours=hours) + kept = tuple(i for i in plan.intervals if i.end > moment and i.start < horizon) + return PlanView( + generated_at=moment, + plan=plan.model_copy(update={"intervals": kept}), + stale=fallback is not None and fallback.key == rk.STATUS_STALE, + expired=fallback is not None and fallback.key == rk.STATUS_EXPIRED, + in_use=fallback is None, + fallback=fallback, + ) + + def next_scheduled_at(self, now: datetime | None = None) -> datetime: + moment = self._clock() if now is None else now + offset = timedelta(seconds=self._settings.offset_s) + slot = floor_quarter(moment - offset) + if self._last_slot is None or slot > self._last_slot: + return moment + return self._last_slot + QUARTER + offset + + def status(self, now: datetime | None = None) -> PlanStatusView: + moment = self._clock() if now is None else now + pending = [t for t in EVENT_PRIORITY if t in self._pending] + return PlanStatusView( + generated_at=moment, + running=self._running, + last_trigger=self._last_trigger, + last_started_at=self._last_started, + last_finished_at=self._last_finished, + last_duration_s=self._last_duration_s, + last_outcome=self._last_outcome, + last_ok_at=self._last_ok, + consecutive_failures=self._failures, + reason=self._last_reason, + next_scheduled_at=self.next_scheduled_at(moment), + pending=pending, + earliest_event_run_at=self._earliest_event_run(moment) if pending else None, + plan=self.summary(moment), + ) + + # --- scheduling ------------------------------------------------------------------------ + + def _due(self, now: datetime) -> Trigger | None: + """The trigger of the run that should start now, if any (no run is active).""" + pending = [t for t in EVENT_PRIORITY if t in self._pending] + if pending and now >= self._earliest_event_run(now): + return pending[0] + if self._retry_at is not None and now < self._retry_at: + return None + offset = timedelta(seconds=self._settings.offset_s) + slot = floor_quarter(now - offset) + if self._last_slot is None: + return "start" if self._plan is None else "schedule" + return "schedule" if slot > self._last_slot else None + + async def tick(self) -> bool: + """One scheduler step: deviation check, then at most one run; ``True`` if a run ran.""" + if self._running: + return False + now = self._clock() + self._check_deviation(now) + trigger = self._due(now) + if trigger is None: + return False + await self._run(now, trigger) + return True + + async def run(self) -> None: + """Poll :meth:`tick` every ``poll_s`` until cancelled; never raises.""" + while True: + try: + await self.tick() + except asyncio.CancelledError: + raise + except Exception: + log.exception("planning.tick_crashed") + await self._sleep(self._settings.poll_s) + + # --- deviation ------------------------------------------------------------------------- + + def _check_deviation(self, now: datetime) -> None: + plan = self._plan + if plan is None or self.fallback_reason(now) is not None: + self._net_over_since = None + return + reading = self._live() + if reading.soc_pct is not None: + planned = planned_soc_at(plan, now) + if planned is not None and abs(reading.soc_pct - planned) > ( + self._settings.soc_deviation_pct + ): + self.request("deviation") + net = planned_net_w(plan, now) + if net is None or reading.grid_w is None: + self._net_over_since = None + return + self._update_net_deviation(now, reading.grid_w - net) + + def _update_net_deviation(self, now: datetime, difference_w: float) -> None: + last = self._net_ema_at + if self._net_ema is None or last is None or now <= last: + self._net_ema = difference_w + else: + alpha = 1.0 - math.exp(-(now - last).total_seconds() / NET_EMA_S) + self._net_ema += alpha * (difference_w - self._net_ema) + self._net_ema_at = now + if abs(self._net_ema) <= self._settings.net_deviation_w: + self._net_over_since = None + return + if self._net_over_since is None: + self._net_over_since = now + elif (now - self._net_over_since).total_seconds() >= self._settings.net_deviation_s: + self._net_over_since = now # re-arm: the next event comes after another period + self.request("deviation") + + # --- one run --------------------------------------------------------------------------- + + def _waiting(self, now: datetime) -> bool: + """The first plan is still within its grace period for prices and forecasts.""" + first = self._first_input_at + return ( + first is not None and (now - first).total_seconds() < self._settings.first_run_grace_s + ) + + async def _run(self, now: datetime, trigger: Trigger) -> None: # noqa: PLR0912, PLR0915 + s = self._settings + self._running = True + self._pending.clear() # this run's inputs include everything requested so far + self._last_started = now + self._last_trigger = trigger + began = time.perf_counter() + outcome: RunOutcome = "failed" + reason: Reason | None = None + new_plan: Plan | None = None + try: + warm = self._plan if self.fallback_reason(now) is None else None + snapshot = await self._collect(now, warm) + inputs = snapshot.inputs + if inputs is None: + outcome = "skipped" + reason = snapshot.reason or Reason(key=rk.STATUS_NO_INPUTS) + else: + if self._first_input_at is None: + self._first_input_at = now + if not snapshot.complete and self._plan is None and self._waiting(now): + outcome = "skipped" + reason = Reason(key=rk.STATUS_WAITING, args={"grace_s": s.first_run_grace_s}) + elif self._thread_busy: + outcome = "skipped" + reason = Reason(key=rk.STATUS_RUN_STUCK) + else: + new_plan = await self._solve_in_thread(inputs, warm) + outcome = "ok" + except asyncio.CancelledError: + raise + except TimeoutError: + reason = Reason(key=rk.STATUS_RUN_TIMEOUT, args={"limit_s": s.run_timeout_s}) + log.error("planning.run_timeout", limit_s=s.run_timeout_s) + except Exception as exc: + reason = Reason( + key=rk.STATUS_RUN_FAILED, args={"error": f"{type(exc).__name__}: {exc}"[:160]} + ) + log.exception("planning.run_failed") + finally: + self._running = False + self._last_duration_s = round(time.perf_counter() - began, 3) + finished = self._clock() + self._last_finished = finished + self._last_outcome = outcome + self._last_reason = reason + if outcome == "ok": + assert new_plan is not None + self._failures = 0 + self._retry_at = None + self._last_ok = finished + self._last_slot = floor_quarter(now) + self._plan = new_plan # the atomic hand-over: the controller reads this reference + self._plan_stamp = finished + self._net_ema = None + self._net_over_since = None + self._notify() + await self._save(new_plan) + elif outcome == "skipped": + self._retry_at = finished + timedelta(seconds=s.retry_skipped_s) + else: + self._failures += 1 + backoff = min(900.0, 60.0 * 2 ** (self._failures - 1)) + self._retry_at = finished + timedelta(seconds=backoff) + # A failed cadence run is not retried before the back-off, but the quarter is spent. + self._last_slot = floor_quarter(now) + + async def _solve_in_thread(self, inputs: PlannerInputs, warm: Plan | None) -> Plan: + s = self._settings + self._thread_busy = True + + def work() -> PlannerRun: + try: + return self._solve(inputs, s.budget_s, s.mip_gap, warm) + finally: + with contextlib.suppress(RuntimeError): + loop.call_soon_threadsafe(self._thread_done) + + loop = asyncio.get_running_loop() + try: + result = await asyncio.wait_for(self._thread(work), timeout=s.run_timeout_s) + except asyncio.CancelledError: + # The thread (if any) clears the flag itself when it ends. + raise + built = result.plan + if not built.intervals: + msg = "the planner returned no intervals" + raise ValueError(msg) + soc = None if inputs.battery is None else round(inputs.battery.soc_pct, 2) + assumptions = dict(built.assumptions) + if soc is not None: + assumptions[SOC_START_KEY] = soc + assumptions["trigger"] = self._last_trigger or "schedule" + return built.model_copy(update={"assumptions": assumptions}) + + def _thread_done(self) -> None: + self._thread_busy = False + + async def _save(self, plan: Plan) -> None: + if self._store is None: + return + try: + await self._store.save( + plan.model_dump(mode="json"), + source=plan.source, + schema_version=plan.schema_version, + created_at=plan.created_at, + ) + except asyncio.CancelledError: + raise + except Exception: + log.exception("planning.snapshot_failed") + + +__all__ = [ + "EVENT_PRIORITY", + "Collector", + "LiveReading", + "PlanListener", + "PlanningService", + "PlanningSettings", + "PlanningSnapshot", + "Solver", + "default_solver", + "floor_quarter", + "plan_ends_at", + "planned_net_w", + "planned_soc_at", + "run_in_daemon_thread", +] diff --git a/suncore/app/runtime.py b/suncore/app/runtime.py index c45d134..97e05d8 100644 --- a/suncore/app/runtime.py +++ b/suncore/app/runtime.py @@ -23,14 +23,25 @@ HAUnavailableError, HealthReport, PeerPolicy, + TariffNotConfiguredError, UnknownRoleError, UnknownTemplateError, ) -from suncore.app.adapters import build_load_forecast_service, build_pv_forecast_service +from suncore.app.adapters import ( + build_load_forecast_service, + build_pv_forecast_service, + build_tariff_service, +) from suncore.app.cadence import device_cadences, merge_cadences from suncore.app.control import ControlStack from suncore.app.history import rebuild_history from suncore.app.modes import ConfigModes +from suncore.app.planning import ( + LiveReading, + PlanningService, + PlanningSettings, + PlanningSnapshot, +) from suncore.app.recorder import FLUSH_INTERVAL_S, MeasurementRecorder from suncore.app.settings import SUPERVISOR_INGRESS_PEER, Settings from suncore.core.balance import FlowSnapshot, compute_flows @@ -41,8 +52,9 @@ GoalsConfig, OperationConfig, RegionConfig, + TariffConfig, ) -from suncore.core.control import ControlSettings +from suncore.core.control import ControlSettings, Plan from suncore.core.controlstate import ( ControlState, DeviceControlState, @@ -53,13 +65,21 @@ UnknownDeviceError, UnknownProposalError, ) -from suncore.core.decisions import Decision, DecisionKind, OperatingMode, Origin +from suncore.core.decisions import Decision, DecisionKind, OperatingMode, Origin, Reason from suncore.core.detection import DetectedEntity, EnergySuggestions from suncore.core.devices import DeviceConfig from suncore.core.identity import identity_token -from suncore.core.signals import Sample +from suncore.core.series import QuantileSeries +from suncore.core.signals import Quality, Sample from suncore.core.site import SiteConfig -from suncore.core.wizard import CheckItem, PreviewItem, collect_refs, preview, run_system_check +from suncore.core.wizard import ( + CheckItem, + PreviewItem, + check_tariff, + collect_refs, + preview, + run_system_check, +) from suncore.forecast.accuracy import accuracy_view, load_accuracy from suncore.forecast.load import LOAD_SOURCE_ID from suncore.forecast.load_service import LoadForecastService @@ -91,6 +111,9 @@ legacy_entities, suggest_from_prefs, ) +from suncore.planner import build_inputs +from suncore.planner import reasons as planner_reasons +from suncore.planner.views import PlanStatusView, PlanSummary, PlanView, ReplanAck, Trigger from suncore.safety.gate import REASON_OVERRIDE_HELD, Clock, SafetyGate from suncore.storage import ( ConfigStore, @@ -104,8 +127,14 @@ TimeseriesStore, ) from suncore.storage.timeseries import META_HISTORY_REBUILT -from suncore.templates import TemplateCatalog +from suncore.tariff import ExportConfigError, TariffService +from suncore.tariff.report import PriceReport +from suncore.templates import TariffTemplate, TemplateCatalog +PLANNING_SECTIONS = frozenset( + {"site", "region", "tariff", "forecast", "battery", "goals", "devices"} +) +"""Configuration sections whose change asks for a new plan.""" LOOPBACK_PEERS: tuple[str, ...] = ("127.0.0.1", "::1") log = structlog.get_logger(__name__) @@ -161,6 +190,9 @@ class Runtime: """Quarter hours the last PV nightly job flagged as clipped (risk learning skips them).""" risk_model: ErrorModel = field(default_factory=ErrorModel) """The learnt net energy errors (WP7), loaded at start and after the nightly job.""" + tariff_config: TariffConfig | None = None + tariff: TariffService | None = None + """Keeps the prices fresh (``None``: no tariff, no region or an unusable template).""" timeseries_db: Database | None = None """``timeseries.db``; ``None`` = unavailable (too new, unopenable): control is unaffected.""" timeseries: TimeseriesStore | None = None @@ -196,6 +228,11 @@ class Runtime: _pv_task: asyncio.Task[None] | None = None _load_task: asyncio.Task[None] | None = None _accuracy_task: asyncio.Future[None] | None = None + _tariff_task: asyncio.Task[None] | None = None + planning: PlanningService | None = None + """The planner runtime (built in :meth:`prepare`; the control stack reads its plan).""" + _planning_task: asyncio.Task[None] | None = None + _plan_unsubscribers: list[Callable[[], None]] = field(default_factory=list) _history_done: bool = False """The statistics rebuild ran (or was not needed) in this process.""" _stack_lock: asyncio.Lock = field(default_factory=asyncio.Lock) @@ -224,11 +261,13 @@ async def prepare(self) -> None: Called by ``build_runtime`` so that the gate exists before :meth:`start`. """ await self._load_live_sections() + self.planning = self._new_planning() self.stack = self._new_stack() self.pv_service = self._new_pv_service() await self._load_pv_learning() self.load_service = self._new_load_service() await self._load_risk_model() + self._build_tariff() async def start(self) -> None: """Wire the control stack and the connection and start connecting in the background. @@ -252,6 +291,8 @@ async def start(self) -> None: self._prune_task = asyncio.create_task(self._prune_loop(), name="suncore-prune") self._start_pv_task() self._start_load_task() + self._start_tariff() + self._start_planning() if self.timeseries is not None: self._flush_task = asyncio.create_task(self._flush_loop(), name="suncore-ts-flush") self._maintenance_task = asyncio.create_task( @@ -272,6 +313,9 @@ async def _load_live_sections(self) -> None: forecast = await self.config.get("forecast") assert forecast is None or isinstance(forecast, ForecastConfig) self.forecast = forecast + tariff = await self.config.get("tariff") + assert tariff is None or isinstance(tariff, TariffConfig) + self.tariff_config = tariff await self._load_modes() async def _load_modes(self) -> None: @@ -291,6 +335,163 @@ def _timezone(self) -> tzinfo: log.warning("control.timezone_unknown_using_utc") return UTC + # --- planner runtime (Phase 4 WP9) --------------------------------------------------------- + + def _new_planning(self) -> PlanningService: + return PlanningService( + self._collect_planning, + self._live_reading, + clock=self.clock, + sleep=self.control_sleep, + settings=PlanningSettings( + budget_s=self.settings.planner_budget_s, mip_gap=self.settings.planner_mip_gap + ), + store=self.plans, + ) + + def _start_planning(self) -> None: + if self.planning is not None and self._started and self._planning_task is None: + self._planning_task = asyncio.create_task(self.planning.run(), name="suncore-planner") + + def _planning_event(self, trigger: Trigger) -> None: + if self.planning is not None: + self.planning.request(trigger) + + def _live_reading(self) -> LiveReading: + flows = self.flows() + if flows is None: + return LiveReading() + soc, grid = flows.battery_soc_pct, flows.grid_w + return LiveReading( + soc_pct=soc.value if soc.quality is Quality.OK else None, + grid_w=grid.value if grid.quality is Quality.OK else None, + ) + + async def _collect_planning(self, now: datetime, previous: Plan | None) -> PlanningSnapshot: + """The planner's inputs from the services as they are now (``build_inputs``).""" + site = self.site + if site is None or self.connection.state is not ConnectionState.CONNECTED: + return PlanningSnapshot(None, reason=Reason(key=planner_reasons.STATUS_NO_INPUTS)) + battery = await self._battery_settings() + soc = self._live_reading().soc_pct + if battery.model is not None and soc is None: + return PlanningSnapshot(None, reason=Reason(key=planner_reasons.STATUS_WAITING_SOC)) + prices = None if self.tariff is None else self.tariff.prices(48.0, now) + blended = None if self.pv_service is None else self.pv_service.blended(now) + pv = None if blended is None else blended.series + load = None if self.load_service is None else self.load_service.forecast(now) + risk = self._risk(now, battery, pv, load) + devices = [] if self.devices is None else list(self.devices.devices) + inputs = build_inputs( + now, + tz=self._blend_tz(), + load=load, + pv=pv, + prices=prices, + battery=battery, + soc_pct=soc, + goals=self.goals, + site_battery=site.battery, + morning_buffer=risk.morning_buffer, + evening_target=risk.evening_target, + evening_at=risk.evening_at, + devices=devices, + import_limit_w=site.grid.import_limit_w, + export_limit_w=export_limit_w(site), + previous=previous, + ) + complete = ( + (prices is None or any(v is not None for v in prices.import_price.values)) + and (self.pv_service is None or pv is not None) + and (self.load_service is None or load is not None) + ) + return PlanningSnapshot(inputs, complete=complete) + + async def plan_view(self, hours: int) -> PlanView: + if self.planning is None: + msg = "the planner runtime is not built" + raise RuntimeError(msg) + return self.planning.view(hours) + + async def plan_status(self) -> PlanStatusView: + if self.planning is None: + msg = "the planner runtime is not built" + raise RuntimeError(msg) + return self.planning.status() + + async def replan(self) -> ReplanAck: + if self.planning is None: + msg = "the planner runtime is not built" + raise RuntimeError(msg) + return self.planning.request("manual") + + def plan_summary(self) -> PlanSummary: + assert self.planning is not None + return self.planning.summary() + + def add_plan_listener(self, listener: Callable[[], None]) -> Callable[[], None]: + assert self.planning is not None + return self.planning.add_listener(listener) + + # --- tariff (prices) -------------------------------------------------------- + + def _build_tariff(self) -> None: + """(Re)build the price service from the stored tariff, region and site. + + Without a tariff or a region there is nothing to build; an unusable tariff (missing + template, tiered export without the plant size) is logged and leaves the service off. + """ + self.tariff = None + tariff, region = self.tariff_config, self.region + if tariff is None or region is None: + return + try: + self.tariff = build_tariff_service( + tariff, + region, + self.site, + self._timezone(), + self.template_catalog, + connection=self.connection, + cache=self.cache, + clock=self.clock, + store=self.timeseries, + refresh_interval_s=float(self.settings.tariff_refresh_interval_s), + tomorrow_after=self.settings.tariff_tomorrow_after, + tomorrow_poll_s=float(self.settings.tariff_tomorrow_poll_s), + ) + except ExportConfigError as exc: + log.warning("tariff.export_unusable", error=exc.key, detail=exc.detail) + if self.tariff is not None: + self.tariff.add_listener(lambda: self._planning_event("prices")) + if self.tariff is None: + log.warning("tariff.service_not_built") + + def _start_tariff(self) -> None: + if self.tariff is not None and self._started and self._tariff_task is None: + self._tariff_task = asyncio.create_task( + self.tariff.run(self.control_sleep), name="suncore-tariff" + ) + + async def _stop_tariff(self) -> None: + task, self._tariff_task = self._tariff_task, None + if task is not None: + task.cancel() + with contextlib.suppress(asyncio.CancelledError, Exception): + await task + + async def _rebuild_tariff(self) -> None: + """Replace the price service after a ``tariff``, ``region`` or ``site`` change.""" + await self._stop_tariff() + self._build_tariff() + self._start_tariff() + self._notify() + + async def prices(self, hours: int) -> PriceReport: + if self.tariff is None: + raise TariffNotConfiguredError + return self.tariff.report(hours=float(hours)) + def _new_stack( self, *, after_handover: bool = False, predecessor: SafetyGate | None = None ) -> ControlStack: @@ -322,6 +523,7 @@ def _new_stack( after_handover=after_handover, predecessor=predecessor, defer_recover=not self._time_zone_settled(), + plan_provider=None if self.planning is None else self.planning.active_plan, ) stack.add_listener(self._notify_control) return stack @@ -463,18 +665,23 @@ async def _load_risk_model(self) -> None: except Exception: log.exception("forecast.risk.load_failed") - async def forecast_risk(self) -> RiskView: - """Morning buffer, evening target and their windows as the planner would get them.""" - now = self.clock() + async def _battery_settings(self) -> BatterySettings: stored = await self.config.get("battery") - settings = stored if isinstance(stored, BatterySettings) else BatterySettings() + return stored if isinstance(stored, BatterySettings) else BatterySettings() + + def _risk( + self, + now: datetime, + settings: BatterySettings, + pv: QuantileSeries | None, + load: QuantileSeries | None, + ) -> RiskView: target = None if self.goals is None else self.goals.battery_target - blended = None if self.pv_service is None else self.pv_service.blended(now) context = self._blend_context() return risk_view( now, - pv=None if blended is None else blended.series, - load=None if self.load_service is None else self.load_service.forecast(now), + pv=pv, + load=load, settings=settings, user_target_pct=None if target is None else target.soc_pct, site_battery=None if self.site is None else self.site.battery, @@ -486,6 +693,17 @@ async def forecast_risk(self) -> RiskView: plant=context.plant, ) + async def forecast_risk(self) -> RiskView: + """Morning buffer, evening target and their windows as the planner would get them.""" + now = self.clock() + blended = None if self.pv_service is None else self.pv_service.blended(now) + return self._risk( + now, + await self._battery_settings(), + None if blended is None else blended.series, + None if self.load_service is None else self.load_service.forecast(now), + ) + async def _update_pv_learning(self) -> None: if self.timeseries is None or self.learned is None or self.pv_service is None: return @@ -513,6 +731,12 @@ async def _update_pv_learning(self) -> None: # --- PV forecast (Phase 4 WP5) --------------------------------------------------- def _new_pv_service(self) -> PvForecastService | None: + service = self._build_pv_service() + if service is not None: + service.add_listener(lambda: self._planning_event("forecast")) + return service + + def _build_pv_service(self) -> PvForecastService | None: return build_pv_forecast_service( self.forecast, catalog=self.template_catalog, @@ -572,6 +796,12 @@ async def _load_pv_learning(self) -> None: # --- load forecast (Phase 4 WP6) ------------------------------------------------ def _new_load_service(self) -> LoadForecastService | None: + service = self._build_load_service() + if service is not None: + service.add_listener(lambda: self._planning_event("forecast")) + return service + + def _build_load_service(self) -> LoadForecastService | None: device_ids = () if self.devices is None else tuple(d.id for d in self.devices.devices) return build_load_forecast_service( self.forecast, @@ -789,6 +1019,8 @@ async def stop(self) -> None: self._pv_task, self._load_task, self._accuracy_task, + self._tariff_task, + self._planning_task, ) for task in (*control_tasks, *storage_tasks): if task is not None: @@ -800,6 +1032,8 @@ async def stop(self) -> None: self._connect_task = self._prune_task = self._tz_task = None self._flush_task = self._maintenance_task = self._history_task = None self._pv_task = self._load_task = None + self._tariff_task = None + self._planning_task = None # Hardware release comes first: a running downsample or retention statement keeps the # (shielded) rollback of its cancelled task waiting, and a Pi can need seconds for it. # The storage tasks are awaited only after the devices are released. @@ -848,11 +1082,15 @@ def _on_entities(self, update: EntityUpdate) -> None: self.pv_service.on_entities(update.changed) if self.stack is not None: self.stack.on_update(update) + if self.tariff is not None and not self.tariff.watched_entities_isdisjoint(update.changed): + self.tariff.notify_changed() self._notify() def _on_state(self, state: ConnectionState) -> None: if self.stack is not None: self.stack.on_state(state) + if state is ConnectionState.CONNECTED and self.tariff is not None: + self.tariff.reset_backoff() # the failures were the missing connection if ( state is ConnectionState.CONNECTED and self._started @@ -875,6 +1113,8 @@ async def _resubscribe(self) -> None: refs.extend(self.devices.entity_refs()) if self.forecast is not None: refs.extend(self.forecast.entity_refs()) + if self.tariff_config is not None: + refs.extend(self.tariff_config.entity_refs()) ids = list(dict.fromkeys(r.entity_id for r in refs)) try: await self.connection.subscribe_entities(ids) @@ -959,6 +1199,8 @@ async def put_section(self, name: str, model: BaseModel) -> BaseModel: stored = await self._put_section(name, model) else: stored = await self._put_section(name, model) + if name in PLANNING_SECTIONS: + self._planning_event("config") self._notify() return stored @@ -975,6 +1217,14 @@ async def _put_section(self, name: str, model: BaseModel) -> BaseModel: await self._apply_stored(name, stored, before) return stored + def _store_planning_input(self, name: str, stored: BaseModel) -> None: + if name == "forecast": + assert isinstance(stored, ForecastConfig) + self.forecast = stored + elif name == "tariff": + assert isinstance(stored, TariffConfig) + self.tariff_config = stored + async def _apply_stored( self, name: str, @@ -996,11 +1246,12 @@ async def _apply_stored( self.goals = stored if self.stack is not None: self.stack.set_goals(stored) - elif name == "forecast": - assert isinstance(stored, ForecastConfig) - self.forecast = stored - if name in ("site", "devices", "forecast"): + else: + self._store_planning_input(name, stored) + if name in ("site", "devices", "forecast", "tariff"): await self._resubscribe() + if name == "tariff" or (self.site, self.region) != before[::2]: + await self._rebuild_tariff() if (self.site, self.devices, self.region) != before: await self._rebuild_stack() if name == "forecast": @@ -1125,6 +1376,7 @@ async def override_device(self, device_id: str, command: OverrideCommand) -> Dev ) else: await stack.gate.resume(device_id) + self._planning_event("override") self._notify_control() state = stack.control_state() return next(d for d in state.devices if d.device_id == device_id) @@ -1235,9 +1487,16 @@ async def system_check(self, site: SiteConfig | None) -> list[CheckItem]: ids = [r.entity_id for r in site.entity_refs()] if site is not None else [] await self._browse_if_needed(ids) present = await self.config.stored_sections() - return run_system_check( + items = run_system_check( site, self._samples(ids), present, self.devices, self._unit_of_entity ) + template = ( + self.template_catalog.get(self.tariff_config.import_.template_id) + if self.tariff_config is not None and self.tariff_config.import_.template_id + else None + ) + includes = template.price_includes if isinstance(template, TariffTemplate) else None + return [*items, *check_tariff(self.tariff_config, includes)] async def preview(self, fragment: Mapping[str, Any]) -> list[PreviewItem]: ids = list(dict.fromkeys(entity_id for _, entity_id, _ in collect_refs(fragment))) @@ -1273,9 +1532,12 @@ async def _reload_live_sections(self, *, resubscribe: bool) -> None: before = (self.site, self.devices, self.region) forecast_before = self.forecast devices_before = self.devices + tariff_before = self.tariff_config await self._load_live_sections() if resubscribe: await self._resubscribe() + if self.tariff_config != tariff_before or (self.site, self.region) != before[::2]: + await self._rebuild_tariff() if (self.site, self.devices, self.region) != before: await self._rebuild_stack() elif self.stack is not None and self.goals is not None: @@ -1285,6 +1547,7 @@ async def _reload_live_sections(self, *, resubscribe: bool) -> None: if self.forecast != forecast_before or self.devices != devices_before: await self._rebuild_load_service() await self._sync_modes() + self._planning_event("config") def add_change_listener(self, listener: Callable[[], None]) -> Callable[[], None]: self._listeners.append(listener) diff --git a/suncore/app/settings.py b/suncore/app/settings.py index 1845194..9301472 100644 --- a/suncore/app/settings.py +++ b/suncore/app/settings.py @@ -72,6 +72,17 @@ class Settings(BaseSettings): templates_dir: Path = Field(default_factory=default_templates_dir) """Built-in templates; user templates are read from ``/templates`` (not in demo).""" + tariff_refresh_interval_s: int = Field(default=3600, ge=60, le=86_400) + """Spacing of the regular price refresh (Tibber, Nord Pool: once per hour).""" + tariff_tomorrow_after: time = time(13, 0) + """Local time from which tomorrow's day-ahead prices are expected (UNVERIFIED).""" + tariff_tomorrow_poll_s: int = Field(default=900, ge=60, le=86_400) + """Spacing of the asks between that time and the arrival of tomorrow's prices.""" + + planner_budget_s: float = Field(default=8.0, ge=0.5, le=120.0) + """Time budget of one planner run (ADR-0003); the heuristic plan covers a miss.""" + planner_mip_gap: float = Field(default=0.01, ge=0.0, le=0.5) + _options_path: ClassVar[Path] = DEFAULT_OPTIONS_PATH @classmethod diff --git a/suncore/controller/loop.py b/suncore/controller/loop.py index e6a34f7..cd96068 100644 --- a/suncore/controller/loop.py +++ b/suncore/controller/loop.py @@ -20,7 +20,10 @@ * ``blocked``: every device the gate holds (override), has a release pending for, or whose scope the watchdog paused - id -> the gate's reason; * ``reserve_soc_pct``, ``import_limit_w`` from the site/battery config, ``goals``, - ``plan`` (``Plan.default()`` in Phase 3); + ``plan`` (``Plan.default()`` until the planner's first plan, afterwards the current plan + read **once** for the tick - ``ControlStack.tick``; a plan can only restrict the devices + and move the surplus between battery and consumers, ``BatteryBand`` limits are not + acted on before WP10); 3. ``result = await loop.tick(now, ControllerInputs(...))``. Inside, in this order: ``controller.step`` (surplus, allocation, back-off) -> ``loop.gate_inputs`` is the @@ -155,7 +158,10 @@ def step(self, now: datetime, inputs: ControllerInputs) -> TickResult: if now.tzinfo is None or now.utcoffset() is None: msg = "Controller.step needs a timezone-aware now" raise ValueError(msg) - band = None if inputs.plan.is_default else inputs.plan.battery_band_at(now) + # A band applies only while a plan interval covers ``now``: a plan that ran out (or a + # default plan) leaves the Phase 3 goal rules in charge, never the empty default band. + interval = inputs.plan.interval_at(now) + band = None if interval is None else interval.battery allocation = AllocationInputs( states=inputs.states, estimates=inputs.estimates, diff --git a/suncore/controller/surplus.py b/suncore/controller/surplus.py index 86804c5..d8a2092 100644 --- a/suncore/controller/surplus.py +++ b/suncore/controller/surplus.py @@ -115,7 +115,13 @@ def battery_share_available( In this order: - * a plan band (Phase 4) decides with ``charge_from_surplus`` when given; + * a plan band (Phase 4) decides: first its ``priority_until_soc_pct`` against the *live* + SoC - battery first (not available) while the SoC is below it or unknown, whatever else + the band says - then ``charge_from_surplus``. A band can therefore only move the surplus + between battery and consumers; below its priority the consumers never get more than + without a plan whose priority is unset (``tests/controller/test_surplus.py``); + ``goals.battery_target`` stays a floor under a plan too (review D1): below it, or with + an unknown SoC, the battery charges first whatever the band says; * a ``battery_target`` the SoC has not reached: the battery charges first - not available (an unknown SoC counts as not reached); the target's time of day is left to the planner (Phase 4), so the target counts all day; @@ -127,9 +133,14 @@ def battery_share_available( Returns ``(available, blocking target in %)``. """ + target = goals.battery_target if band is not None: + priority = band.priority_until_soc_pct + if priority is not None and (soc_pct is None or soc_pct < priority): + return False, priority + if target is not None and (soc_pct is None or soc_pct < target.soc_pct): + return False, target.soc_pct return (not band.charge_from_surplus, None) - target = goals.battery_target if target is not None and (soc_pct is None or soc_pct < target.soc_pct): return False, target.soc_pct if goals.climate_before_export or target is not None: diff --git a/suncore/core/actions.py b/suncore/core/actions.py index bcb952f..f36b43e 100644 --- a/suncore/core/actions.py +++ b/suncore/core/actions.py @@ -14,6 +14,7 @@ READ_ONLY_ACTIONS: Final[frozenset[str]] = frozenset( { "tibber.get_prices", + "nordpool.get_prices_for_date", "solcast_solar.query_forecast_data", "weather.get_forecasts", "workday.check_date", diff --git a/suncore/core/config.py b/suncore/core/config.py index fe0bc96..6ca5f4f 100644 --- a/suncore/core/config.py +++ b/suncore/core/config.py @@ -8,7 +8,7 @@ from __future__ import annotations import itertools -from collections.abc import Mapping +from collections.abc import Collection, Mapping from typing import Annotated, Any, Final, Literal, Self from zoneinfo import ZoneInfo, ZoneInfoNotFoundError @@ -37,6 +37,15 @@ Price = Annotated[float, Field(ge=0, le=100)] """Currency per kWh.""" +ActionParamName = Annotated[str, StringConstraints(min_length=1, max_length=64)] +ActionParamValue = ( + Annotated[str, StringConstraints(min_length=1, max_length=200)] + | Annotated[ + list[Annotated[str, StringConstraints(min_length=1, max_length=64)]], + Field(min_length=1, max_length=16), + ] +) +"""A request field value of a tariff template's action: text, or a list of texts.""" class _Frozen(BaseModel): @@ -89,6 +98,35 @@ class ImportTariff(_Frozen): fixed_price: Price | None = None formula: PriceFormula | None = None tou: TouTariff | None = None + role_entities: dict[RoleName, EntityRef] = Field(default_factory=dict) + """Entities of the template's roles besides the main one (``price_entity`` is the role + ``price``), e.g. Octopus ``current_day_rates`` and ``next_day_rates`` (Phase 4 WP4).""" + action_params: dict[ActionParamName, ActionParamValue] = Field(default_factory=dict) + """Values for the request fields the template's action asks the user for (Nord Pool + ``config_entry``, ``areas``, ``currency``); the template names which are required.""" + series_key: Annotated[str, StringConstraints(min_length=1, max_length=120)] | None = None + """Which entry of a multi-entry action response to read (Tibber home name, Nord Pool + area) when the response holds more than one; ``None`` = the only one.""" + price_includes: PriceIncludes | None = None + """The user's statement about a source whose content depends on their setup (ENTSO-E + with a modifier template): overrides the template's ``price_includes``.""" + + @model_validator(mode="after") + def _source_settings(self) -> Self: + if self.kind != "dynamic" and ( + self.role_entities + or self.action_params + or self.series_key is not None + or self.price_includes is not None + ): + raise invalid( + "import_source_dynamic_only", + "tariff.import: source settings (`role_entities`, `action_params`, " + "`series_key`, `price_includes`) need kind `dynamic`", + ) + if "price" in self.role_entities: + raise invalid("import_role_price", "tariff.import: the role `price` is `price_entity`") + return self @model_validator(mode="after") def _consistent(self) -> Self: @@ -194,7 +232,8 @@ class TariffConfig(_Frozen): export: ExportTariff def entity_refs(self) -> list[EntityRef]: - return [self.import_.price_entity] if self.import_.price_entity is not None else [] + refs = [self.import_.price_entity] if self.import_.price_entity is not None else [] + return [*refs, *self.import_.role_entities.values()] # --- forecast ----------------------------------------------------------------- @@ -360,6 +399,29 @@ def formula_on_all_in_source( ) +def missing_action_params( + tariff: TariffConfig, template_id: str, required: Collection[str] +) -> list[tuple[str, PydanticCustomError]]: + """The request fields a template's action needs that ``tariff.import.action_params`` lacks. + + ``required`` are the names the template marks as required (the catalogue knows them, the + model does not - the API passes them in, like for :func:`formula_on_all_in_source`). + """ + return [ + ( + name, + invalid( + "import_param_missing", + "tariff.import: template {template_id} needs the setting {field}", + template_id=template_id, + field=name, + ), + ) + for name in required + if name not in tariff.import_.action_params + ] + + def migrate_tariff_v2_to_v3(body: dict[str, Any]) -> dict[str, Any]: """Tariff v3 only adds optional fields (``formula``, kind ``tou``): unchanged body.""" return body diff --git a/suncore/core/control.py b/suncore/core/control.py index 0f7bfcd..2bab40f 100644 --- a/suncore/core/control.py +++ b/suncore/core/control.py @@ -191,8 +191,19 @@ class BatteryBand(_Frozen): priority_until_soc_pct: Annotated[float, Field(ge=0, le=100)] | None = None """Plan v2: battery first until the *live* SoC reaches this value, then surplus may go to consumers. Evaluated by the controller against the measured SoC every tick (robust - against plan deviation); ``None`` = no such rule. Accepted and stored now, the - controller wiring follows in Phase 4 WP10 (until then the controller ignores it).""" + against plan deviation; an unknown SoC counts as not reached); ``None`` = no such rule. + It only takes surplus away from the consumers (``controller.surplus``).""" + grid_charge_max_w: float | None = Field(default=None, allow_inf_nan=False, ge=0) + """ADR-0013 decision 4: the most the battery may charge **from the grid** in this + interval (W); ``None`` = no grid charging planned. Set by the planner only where the + effective grid-charge policy (price level, schedule) and the spread rule allow it. The + gate bounds a ``grid_charge_w`` by it (invariant B2/B3, Phase 4 WP10); until then the + controller ignores it.""" + discharge_lock: bool = False + """ADR-0013 decision 4: the plan holds the battery's energy in this interval although + the house draws from the grid (hold for the evening target or a later price peak). + Only a plan interval with this flag allows a discharge lock (invariant B4, WP10); + until then the controller ignores it.""" @model_validator(mode="after") def _ordered(self) -> Self: @@ -217,7 +228,11 @@ class IntervalFlows(_Frozen): and ``net_risk_w`` the net power PV - load at that quantile the target constraints used (may be negative; ``None`` = no target constraint in this interval). ``soc_pct`` is the planned state of charge at the *end* of the interval (``None`` = no - battery). + battery). ``devices_w`` is the planned draw of the controllable devices (not part of + ``load_w``, the base load) and ``curtail_w`` the PV the plan does not use (export limit + or negative export price; informational until the export-limit chain, Phase 6), so + ``pv_p50_w + import_w + max(-battery_w, 0) = load_w + devices_w + max(battery_w, 0) + + export_w + curtail_w`` (both additive in plan v2, default 0). """ pv_p10_w: float | None = Field(default=None, ge=0, allow_inf_nan=False) @@ -230,6 +245,8 @@ class IntervalFlows(_Frozen): soc_pct: Annotated[float, Field(ge=0, le=100)] | None = None net_risk_quantile: Annotated[float, Field(gt=0, lt=1)] | None = None net_risk_w: float | None = Field(default=None, allow_inf_nan=False) + devices_w: float = Field(default=0.0, ge=0, allow_inf_nan=False) + curtail_w: float = Field(default=0.0, ge=0, allow_inf_nan=False) @model_validator(mode="after") def _quantiles(self) -> Self: @@ -250,6 +267,9 @@ class IntervalPrices(_Frozen): import_price: float = Field(allow_inf_nan=False) export_price: float = Field(allow_inf_nan=False) + estimated: bool = False + """The source had no price for this interval; the planner used a stand-in (the median of + the known prices). Additive in plan v2 (review m5).""" class PlanInterval(_Frozen): @@ -263,7 +283,9 @@ class PlanInterval(_Frozen): end: AwareDatetime devices: dict[str, DeviceBand] = Field(default_factory=dict) """Device id -> band; a missing device gets :data:`DEFAULT_BAND`.""" - battery: BatteryBand = BatteryBand() + battery: BatteryBand | None = BatteryBand() + """``None`` = the plan has no battery (no model or no live SoC): the controller keeps the + Phase 3 goal rules for the battery share (control-safety review m6).""" grid_import_limit_w: float | None = Field(default=None, allow_inf_nan=False, ge=0) expected: IntervalFlows | None = None prices: IntervalPrices | None = None @@ -360,7 +382,9 @@ def band_for(self, device_id: str, at: datetime) -> DeviceBand: def battery_band_at(self, at: datetime) -> BatteryBand: interval = self.interval_at(at) - return DEFAULT_BATTERY_BAND if interval is None else interval.battery + if interval is None or interval.battery is None: + return DEFAULT_BATTERY_BAND + return interval.battery def plan_from_payload(payload: Mapping[str, Any]) -> Plan: diff --git a/suncore/core/series.py b/suncore/core/series.py index e08fbfb..1716c74 100644 --- a/suncore/core/series.py +++ b/suncore/core/series.py @@ -465,8 +465,9 @@ def segments_from_points( * ``d == cur``: the segment continues; * ``d`` is an accepted step (expected or other) and either not a multiple of ``cur`` - or the next distance is ``d`` again (or the point is the last but one): a - **resolution change** - a new segment with step ``d`` starts at this point; + or the next distance is ``d`` again: a **resolution change** - a new segment with step + ``d`` starts at this point. The next distance has to confirm the rhythm, so at the end of + the list a multiple of ``cur`` is a gap, not a change; * ``d`` is a multiple of ``cur``: a **gap** - the point lasts ``cur`` and the missing slots become ``None`` (a gap is never filled with a neighbour's value); * anything else raises ``ValueError`` (irregular timestamps; SunCore never guesses). @@ -502,7 +503,7 @@ def close() -> None: if d == cur: values.append(value) continue - steady = i + 1 >= len(distances) or distances[i + 1] == d + steady = i + 1 < len(distances) and distances[i + 1] == d if d in accepted and (d % cur != timedelta(0) or steady): close() cur, begin, values = d, stamps[i], [value] diff --git a/suncore/core/tariff.py b/suncore/core/tariff.py index 3605ad7..c669721 100644 --- a/suncore/core/tariff.py +++ b/suncore/core/tariff.py @@ -175,11 +175,19 @@ def grid_fee_at(self, at: datetime | None, tz: tzinfo) -> float: return entry.fee return self.grid_fee - def apply(self, spot: float, at: datetime | None, tz: tzinfo) -> float: - """End price for ``spot`` at ``at`` (``None``: the base grid fee is used).""" + def end_price(self, spot: float, at: datetime | None, tz: tzinfo) -> float: + """End price for ``spot`` at ``at`` (``None``: the base grid fee is used). + + Callers outside ``core`` use this name: ``.apply(`` is reserved by the architecture + boundary test for the actuator write path (``tests/safety/test_boundary.py``, rule 1). + """ net = spot * self.spot_multiplier + self.grid_fee_at(at, tz) + self.levies + self.margin return net * (1 + self.vat_pct / 100) + def apply(self, spot: float, at: datetime | None, tz: tzinfo) -> float: + """Deprecated alias of :meth:`end_price` (the 4-A name); new code calls ``end_price``.""" + return self.end_price(spot, at, tz) + # --- HT/NT (time of use) --------------------------------------------------------------- diff --git a/suncore/core/wizard.py b/suncore/core/wizard.py index d4fe082..9d30e4f 100644 --- a/suncore/core/wizard.py +++ b/suncore/core/wizard.py @@ -22,9 +22,10 @@ from typing import Any, Final, Literal from suncore.core.balance import FlowSnapshot, compute_flows -from suncore.core.config import DevicesConfig +from suncore.core.config import DevicesConfig, TariffConfig from suncore.core.decisions import Reason from suncore.core.devices import DeviceConfig, DeviceKind +from suncore.core.series import PriceIncludes from suncore.core.signals import Quality, Sample from suncore.core.site import ENTITY_ID_PATTERN, EntityRef, SiteConfig from suncore.core.units import Dimension, apply_invert, to_base @@ -335,6 +336,23 @@ def _check_duplicate_units( return items +def check_tariff( + tariff: TariffConfig | None, template_includes: PriceIncludes | None +) -> list[CheckItem]: + """Findings about the tariff: a spot-only import price without a price formula. + + ``template_includes`` is the template's ``price_includes`` (``None`` = no template); the + user's own statement in the tariff wins. A bare spot price is neither what the household + pays nor something the planner may optimise against (Phase 4 plan, 4-F refuses it). + """ + if tariff is None or tariff.import_.kind != "dynamic" or tariff.import_.formula is not None: + return [] + includes = tariff.import_.price_includes or template_includes + if includes != "spot_only": + return [] + return [_item("warn", "wizard.check.tariff_spot_without_formula", "tariff")] + + def run_system_check( site: SiteConfig | None, samples: Mapping[str, Sample], diff --git a/suncore/forecast/load_service.py b/suncore/forecast/load_service.py index eaeb938..c649837 100644 --- a/suncore/forecast/load_service.py +++ b/suncore/forecast/load_service.py @@ -190,6 +190,7 @@ def __init__( """Today's recorded outside temperatures (from the fit's read plus every refresh).""" self._last_stored_at: datetime | None = None self._lock = asyncio.Lock() + self._listeners: list[Callable[[], None]] = [] # --- inputs --------------------------------------------------------------------- @@ -474,7 +475,26 @@ async def refresh(self) -> QuantileSeries | None: except Exception: log.exception("forecast.load.refresh_failed") return None - return forecast + if forecast is not None: + self._notify() + return forecast + + def add_listener(self, listener: Callable[[], None]) -> Callable[[], None]: + """Call ``listener`` after every successful refresh (the forecast was recomputed).""" + self._listeners.append(listener) + + def remove() -> None: + if listener in self._listeners: + self._listeners.remove(listener) + + return remove + + def _notify(self) -> None: + for listener in list(self._listeners): + try: + listener() + except Exception: + log.exception("forecast.load.listener_failed") async def _maybe_store(self, forecast: QuantileSeries, now: datetime) -> None: if self._data is None: diff --git a/suncore/forecast/pv/service.py b/suncore/forecast/pv/service.py index 01a071e..be16bf0 100644 --- a/suncore/forecast/pv/service.py +++ b/suncore/forecast/pv/service.py @@ -279,6 +279,7 @@ def __init__( self._state = {s.source_id: SourceSnapshot(s.source_id) for s in self._sources} self._watched = frozenset().union(*(s.watched_entities for s in self._sources)) self._woken = False + self._listeners: list[Callable[[], None]] = [] self._sleeper: asyncio.Future[None] | None = None self._lock = asyncio.Lock() self._last_refresh_at: datetime | None = None @@ -318,8 +319,26 @@ async def refresh(self) -> list[SourceSnapshot]: for source in self._sources: await self._refresh_one(source, window, now) await self._store_blend(now) + self._notify() return list(self._state.values()) + def add_listener(self, listener: Callable[[], None]) -> Callable[[], None]: + """Call ``listener`` after every refresh pass (forecast data may have changed).""" + self._listeners.append(listener) + + def remove() -> None: + if listener in self._listeners: + self._listeners.remove(listener) + + return remove + + def _notify(self) -> None: + for listener in list(self._listeners): + try: + listener() + except Exception: + log.exception("forecast.pv.listener_failed") + async def _store_blend(self, now: datetime) -> None: try: blended = self.blended(now) diff --git a/suncore/planner/__init__.py b/suncore/planner/__init__.py index eea1b30..c84c24f 100644 --- a/suncore/planner/__init__.py +++ b/suncore/planner/__init__.py @@ -1,2 +1,15 @@ # SPDX-License-Identifier: Apache-2.0 -"""SunCore planner package (Phase 0 placeholder, see docs/architecture.md).""" +"""SunCore planner (Phase 4 WP8, ADR-0003): 48 h in 15-minute steps, HiGHS LP + heuristic. + +Entry point for the runtime (WP9): build a :class:`~suncore.planner.inputs.PlannerInputs` +with :func:`~suncore.planner.inputs.build_inputs` from the services' outputs, then call +:func:`~suncore.planner.run.plan` (or :func:`~suncore.planner.run.run` for the details) in a +worker thread. Depends on ``suncore.core`` only (plus ``highspy``/NumPy in the model); no I/O. +""" + +from __future__ import annotations + +from suncore.planner.inputs import PlannerInputs, PlannerWeights, build_inputs +from suncore.planner.run import PlannerRun, plan, run + +__all__ = ["PlannerInputs", "PlannerRun", "PlannerWeights", "build_inputs", "plan", "run"] diff --git a/suncore/planner/explain.py b/suncore/planner/explain.py new file mode 100644 index 0000000..2ddb8d2 --- /dev/null +++ b/suncore/planner/explain.py @@ -0,0 +1,342 @@ +# SPDX-License-Identifier: Apache-2.0 +"""Why the plan does what it does, per interval (Phase 4 WP8): structured reasons only. + +The reasons come from the *binding* parts of the plan and from price comparisons, never from +free text (keys in :mod:`suncore.planner.reasons`, all in the en/de catalogues): + +* a target at this slot: the risk model's own reason (``planner.battery.morning_buffer``, + ``planner.battery.evening_target``) or ``planner.battery.user_target``; a shortfall adds + ``planner.battery.target_shortfall`` (the soft target could not be met); +* grid charging: ``planner.battery.grid_charge`` with the SoC from/to, the price paid and the + best known later price and its time (the spread the rule compared); +* a held battery while the house imports (``discharge_lock``): ``hold_for_evening`` when a + later evening/user target is binding, else ``hold_for_price`` with the later, higher import + price the energy is kept for; +* devices: ``planner.device.surplus`` (planned on PV surplus) or ``planner.device.throttled`` + (a binding battery target takes the surplus first); +* export: ``planner.export.negative_price_avoided`` (export price <= 0 and surplus kept in + the battery/devices or curtailed), ``planner.export.limit``, ``planner.export.surplus``; +* otherwise the flow that dominates (``charge_surplus``, ``discharge_house``, ``at_reserve``, + ``full``, ``planner.grid.import``) or ``planner.interval.balanced``. + +Times in reason arguments are local ``HH:MM`` of the inputs' zone. +""" + +from __future__ import annotations + +from dataclasses import dataclass +from datetime import datetime, tzinfo +from typing import Final + +from suncore.core.decisions import Reason +from suncore.planner import reasons as rk +from suncore.planner.inputs import PlannerInputs, SocGoal +from suncore.planner.model import BUFFER_KINDS, Economics, Schedule, goal_shortfall_wh + +EPS_W: Final = 1.0 +"""Flows below this (W) count as zero in the explanation and the bands.""" +TIGHT_PCT: Final = 1.0 +"""A target counts as binding when the planned SoC is within this many percent of it.""" +TIGHT_HOLD_PCT: Final = 3.0 +"""Hysteresis (control-safety review m2): a slot the previous plan throttled devices in stays +tight while the target is within this many percent (and the device budget within +:data:`TIGHT_HOLD_WH`), so consecutive plans do not flip a band allowed/throttled.""" +TIGHT_HOLD_WH: Final = 100.0 +HOLD_KINDS: Final = ("evening_target", "user_target") + + +def _hhmm(at: datetime, tz: tzinfo) -> str: + return at.astimezone(tz).strftime("%H:%M") + + +def _pct(inputs: PlannerInputs, wh: float) -> float: + battery = inputs.battery + return 0.0 if battery is None else round(battery.model.wh_to_soc(wh), 1) + + +@dataclass(frozen=True, slots=True) +class SlotFacts: + """Per slot: what the bands and the reasons both need.""" + + discharge_lock: bool + tight: bool + """A pending battery target binds: surplus goes to the battery before devices.""" + hold_goal: SocGoal | None + """The binding evening/user target a lock holds energy for (``None`` = price).""" + priority_until_pct: float | None + + +def _binding( + inputs: PlannerInputs, econ: Economics, schedule: Schedule, margin_pct: float +) -> list[bool]: + battery = inputs.battery + out = [] + for goal, slot in zip(inputs.goals, econ.goal_slots, strict=True): + if battery is None or slot is None: + out.append(False) + continue + planned = battery.model.wh_to_soc(schedule.soc_wh[slot]) + out.append(planned <= goal.soc_pct + margin_pct) + return out + + +def previously_throttled(inputs: PlannerInputs) -> set[datetime]: + """Interval starts in which the previous plan blocked or throttled a device.""" + previous = inputs.previous + if previous is None: + return set() + return { + interval.start + for interval in previous.intervals + if any( + not band.allowed or band.max_power_w is not None for band in interval.devices.values() + ) + } + + +def slot_facts(inputs: PlannerInputs, econ: Economics, schedule: Schedule) -> list[SlotFacts]: + """Discharge locks, binding targets and the battery-first rule per slot.""" + battery = inputs.battery + binding = _binding(inputs, econ, schedule, TIGHT_PCT) + holding = _binding(inputs, econ, schedule, TIGHT_HOLD_PCT) + throttled_before = previously_throttled(inputs) + out: list[SlotFacts] = [] + # Battery first only until the buffer's goal slot (its day), not over the horizon (m3). + buffer_goal = next( + ( + (goal.soc_pct, slot) + for goal, slot in zip(inputs.goals, econ.goal_slots, strict=True) + if slot is not None and goal.kind in BUFFER_KINDS + ), + None, + ) + buffer_open = buffer_goal is not None and battery is not None + used = { + slot: sum(schedule.device_total_w(t) for t in range(slot + 1)) * inputs.dt_h + for slot, _ in econ.device_budget + } + for t in range(inputs.n): + prev = battery.soc_wh if battery is not None and t == 0 else schedule.soc_wh[t - 1] + sticky = inputs.starts[t] in throttled_before + pending = [ + (goal, b) + for goal, slot, b in zip( + inputs.goals, econ.goal_slots, holding if sticky else binding, strict=True + ) + if slot is not None and slot >= t + ] + slack_wh = TIGHT_HOLD_WH if sticky else 1.0 + budget_bound = any( + slot >= t and used[slot] >= budget - slack_wh for slot, budget in econ.device_budget + ) + tight = (any(b for _, b in pending) or budget_bound) and schedule.pv_charge_w[t] > EPS_W + deficit = econ.deficit_w[t] + lock = False + hold: SocGoal | None = None + if battery is not None and deficit > EPS_W: + floor = min(battery.reserve_wh, battery.soc_wh) + room_w = (prev - floor) * battery.model.discharge_efficiency / inputs.dt_h + possible = min(deficit, battery.max_discharge_w, room_w) + lock = schedule.battery_load_w[t] < possible - EPS_W + if lock: + hold = next((g for g, b in pending if b and g.kind in HOLD_KINDS), None) + priority: float | None = None + if buffer_open and battery is not None and buffer_goal is not None: + if t > buffer_goal[1]: + buffer_open = False + else: + priority = buffer_goal[0] + if battery.model.wh_to_soc(schedule.soc_wh[t]) >= buffer_goal[0] - 0.05: + buffer_open = False + out.append(SlotFacts(lock, tight, hold, priority)) + return out + + +def _best_later(inputs: PlannerInputs, t: int) -> tuple[float, int] | None: + best: tuple[float, int] | None = None + for tau in range(t + 1, inputs.n): + price = inputs.import_known[tau] + if price is not None and (best is None or price > best[0]): + best = (price, tau) + return best + + +def _later_use(inputs: PlannerInputs, schedule: Schedule, t: int) -> tuple[float, int] | None: + """The most expensive later slot in which the battery serves the house.""" + best: tuple[float, int] | None = None + for tau in range(t + 1, inputs.n): + price = inputs.import_known[tau] + # Only real prices are cited, never a median stand-in (review m5). + used = schedule.battery_load_w[tau] > EPS_W and price is not None + if used and price is not None and (best is None or price > best[0]): + best = (price, tau) + return best + + +def interval_reasons( # noqa: PLR0912, PLR0915 - one branch per rule of the module doc + inputs: PlannerInputs, + econ: Economics, + schedule: Schedule, + facts: list[SlotFacts], + t: int, +) -> tuple[Reason, ...]: + """The reasons of slot ``t`` (at least one).""" + out: list[Reason] = [] + tz = inputs.tz + battery = inputs.battery + fact = facts[t] + shortfalls = goal_shortfall_wh(inputs, econ, schedule) + for goal, slot, short in zip(inputs.goals, econ.goal_slots, shortfalls, strict=True): + if slot != t: + continue + out.append(goal.reason) + if short > 1.0: + out.append( + Reason( + key=rk.TARGET_SHORTFALL, + args={ + "goal": goal.kind, + "target_pct": round(goal.soc_pct, 1), + "planned_pct": _pct(inputs, schedule.soc_wh[t]), + "time": _hhmm(goal.at, tz), + }, + ) + ) + prev = battery.soc_wh if battery is not None and t == 0 else schedule.soc_wh[max(0, t - 1)] + if schedule.grid_charge_w[t] > EPS_W: + later = _best_later(inputs, t) + price = inputs.import_price[t] + out.append( + Reason( + key=rk.GRID_CHARGE, + args={ + "from": _pct(inputs, prev), + "to": _pct(inputs, schedule.soc_wh[t]), + "price": round(price, 4), + "later_price": round(price if later is None else later[0], 4), + "later_time": _hhmm(inputs.starts[t if later is None else later[1]], tz), + }, + ) + ) + if fact.discharge_lock: + if fact.hold_goal is not None: + out.append( + Reason( + key=rk.HOLD_FOR_EVENING, + args={ + "soc_pct": round(fact.hold_goal.soc_pct, 1), + "time": _hhmm(fact.hold_goal.at, tz), + }, + ) + ) + else: + use = _later_use(inputs, schedule, t) + price = inputs.import_price[t] + out.append( + Reason( + key=rk.HOLD_FOR_PRICE, + args={ + "price": round(price, 4), + "later_price": round(price if use is None else use[0], 4), + "later_time": _hhmm(inputs.starts[t if use is None else use[1]], tz), + }, + ) + ) + elif schedule.battery_load_w[t] > EPS_W: + out.append( + Reason( + key=rk.DISCHARGE_HOUSE, + args={ + "power_w": round(schedule.battery_load_w[t]), + "soc_pct": _pct(inputs, schedule.soc_wh[t]), + }, + ) + ) + elif battery is not None and econ.deficit_w[t] > EPS_W: + out.append(Reason(key=rk.AT_RESERVE, args={"soc_pct": _pct(inputs, prev)})) + if schedule.pv_charge_w[t] > EPS_W: + out.append( + Reason( + key=rk.CHARGE_SURPLUS, + args={ + "power_w": round(schedule.pv_charge_w[t]), + "soc_pct": _pct(inputs, schedule.soc_wh[t]), + }, + ) + ) + for j, device in enumerate(inputs.devices): + power = schedule.devices_w[j][t] + if power > EPS_W: + out.append( + Reason( + key=rk.DEVICE_SURPLUS, + args={"device": device.device_id, "power_w": round(power)}, + ) + ) + elif fact.tight and device.allowed[t]: + upcoming = next( + ( + g + for g, s in zip(inputs.goals, econ.goal_slots, strict=True) + if s is not None and s >= t + ), + None, + ) + if upcoming is not None: + out.append( + Reason( + key=rk.DEVICE_THROTTLED, + args={ + "device": device.device_id, + "soc_pct": round(upcoming.soc_pct, 1), + "time": _hhmm(upcoming.at, tz), + }, + ) + ) + surplus = econ.surplus_w[t] + export_price = inputs.export_price[t] + if surplus > EPS_W: + avoided = schedule.export_w[t] <= EPS_W or schedule.export_w[t] <= 0.5 * surplus + if export_price <= 0 and avoided: + out.append( + Reason( + key=rk.EXPORT_NEGATIVE_PRICE_AVOIDED, + args={ + "price": round(export_price, 4), + "import_price": round(inputs.import_price[t], 4), + }, + ) + ) + elif ( + inputs.export_limit_w is not None + and schedule.curtail_w[t] > EPS_W + and schedule.export_w[t] >= inputs.export_limit_w - EPS_W + ): + out.append(Reason(key=rk.EXPORT_LIMIT, args={"limit_w": round(inputs.export_limit_w)})) + elif schedule.export_w[t] > EPS_W: + if battery is not None and schedule.soc_wh[t] >= battery.max_wh - 1.0: + out.append( + Reason(key=rk.BATTERY_FULL, args={"soc_pct": _pct(inputs, schedule.soc_wh[t])}) + ) + out.append( + Reason( + key=rk.EXPORT_SURPLUS, + args={"power_w": round(schedule.export_w[t]), "price": round(export_price, 4)}, + ) + ) + if not out and schedule.grid_load_w[t] > EPS_W: + out.append( + Reason( + key=rk.GRID_IMPORT, + args={ + "power_w": round(schedule.grid_load_w[t]), + "price": round(inputs.import_price[t], 4), + }, + ) + ) + if not out: + out.append(Reason(key=rk.BALANCED)) + return tuple(out) + + +__all__ = ["SlotFacts", "interval_reasons", "slot_facts"] diff --git a/suncore/planner/heuristic.py b/suncore/planner/heuristic.py new file mode 100644 index 0000000..9c60122 --- /dev/null +++ b/suncore/planner/heuristic.py @@ -0,0 +1,210 @@ +# SPDX-License-Identifier: Apache-2.0 +"""Rule-based fallback planner (Phase 4 WP8, ADR-0003): always available, no solver. + +It produces the same :class:`~suncore.planner.model.Schedule` as the LP, on the same flows +(PV serves the base load first; devices only from the PV surplus; the battery discharges only +for the base load), so :func:`suncore.planner.model.objective` costs both alike. Rules, slot +by slot on the P50 forecast: + +1. **Battery first** while the SoC is below the morning buffer (``priority_until``). +2. Then **devices by value** (highest first), as far as every pending evening/user target is + still reachable: a projection of the SoC at each target (all later surplus to the battery, + later deficits drawn from it) must stay above the target after the device's energy. +3. The battery takes the rest up to its charge limit and max SoC; the remainder is exported + up to the export limit (curtailed when the export price is negative or above the limit). +4. A deficit is covered by the battery down to the reserve - unless a pending evening/user + target is projected to be missed, then the battery holds (discharge lock) and the house + imports. +5. **Grid charging** only when a target is still missed after rules 1-4: in the cheapest + slots before the target whose allowance (policy, schedule and spread rule) is positive, + just enough to close the gap. +""" + +from __future__ import annotations + +from dataclasses import dataclass +from typing import Final + +from suncore.planner.inputs import PlannerInputs +from suncore.planner.model import ( + Economics, + Schedule, + economics, + goal_shortfall_wh, +) + +EPS_W: Final = 1e-6 +HOLD_KINDS: Final = ("evening_target", "user_target") + + +@dataclass(frozen=True, slots=True) +class _Goal: + slot: int + target_wh: float + holds: bool + """An evening or user target (a deficit may be held for it).""" + + +def _goals(inputs: PlannerInputs, econ: Economics) -> list[_Goal]: + battery = inputs.battery + if battery is None: + return [] + out = [] + for goal, slot in zip(inputs.goals, econ.goal_slots, strict=True): + if slot is not None: + out.append(_Goal(slot, battery.model.soc_to_wh(goal.soc_pct), goal.kind in HOLD_KINDS)) + return out + + +def _simulate( # noqa: PLR0912, PLR0915 - one pass over the rules of the module doc + inputs: PlannerInputs, econ: Economics, extra_grid_w: list[float] +) -> Schedule: + n, dt = inputs.n, inputs.dt_h + battery = inputs.battery + goals = _goals(inputs, econ) + order = sorted( + range(len(inputs.devices)), + key=lambda j: (-max(econ.device_value[j]), inputs.devices[j].priority), + ) + gl = [0.0] * n + bl = [0.0] * n + pc = [0.0] * n + gc = [0.0] * n + ex = [0.0] * n + cu = [0.0] * n + soc = [0.0] * n + dev = [[0.0] * n for _ in inputs.devices] + eta_c = battery.model.charge_efficiency if battery else 1.0 + eta_d = battery.model.discharge_efficiency if battery else 1.0 + max_ch = battery.max_charge_w if battery else 0.0 + max_dis = battery.max_discharge_w if battery else 0.0 + e = battery.soc_wh if battery else 0.0 + floor = min(battery.reserve_wh, e) if battery else 0.0 + ceiling = max(battery.max_wh, e) if battery else 0.0 + buffer_wh = ( + battery.model.soc_to_wh(inputs.morning_buffer_pct) + if battery is not None and inputs.morning_buffer_pct is not None + else None + ) + # Net battery energy each slot would add if all surplus went to it and deficits drew from it. + gain = [ + min(econ.surplus_w[t], max_ch) * dt * eta_c - min(econ.deficit_w[t], max_dis) * dt / eta_d + for t in range(n) + ] + budget_left = dict(econ.device_budget) + for t in range(n): + s, d = econ.surplus_w[t], econ.deficit_w[t] + pending = [g for g in goals if g.slot >= t] + # Projected margin over every pending target if this slot's surplus went to the battery. + margin = min( + ( + min( + ceiling, + e + sum(gain[t : g.slot + 1]) + _extra(extra_grid_w, t, g.slot, dt, eta_c), + ) + - g.target_wh + for g in pending + if g.holds + ), + default=float("inf"), + ) + rest = s + # Same rule as the LP's FIRST slack (review n2): strictly before the buffer's slot. + battery_first = buffer_wh is not None and e < buffer_wh - 1e-6 and t < econ.first_until + if battery is not None and battery_first: + first = min(rest, max_ch, max(0.0, ceiling - e) / (dt * eta_c)) + pc[t] = first + rest -= first + budget_w = float("inf") if margin == float("inf") else max(0.0, margin) / (dt * eta_c) + for slot, left in budget_left.items(): + if slot >= t: + budget_w = min(budget_w, max(0.0, left) / dt) + for j in order: + device = inputs.devices[j] + if not device.allowed[t] or rest <= EPS_W: + continue + take = min(rest, device.max_w, budget_w) + if take <= EPS_W: + continue + dev[j][t] = take + rest -= take + budget_w -= take + for slot in budget_left: + if slot >= t: + budget_left[slot] -= take * dt + if battery is not None: + room = max(0.0, ceiling - e) / (dt * eta_c) - pc[t] + more = max(0.0, min(rest, max_ch - pc[t], room)) + pc[t] += more + rest -= more + room -= more + gc[t] = max(0.0, min(extra_grid_w[t], inputs.grid_charge_at(t), max_ch - pc[t], room)) + if rest > EPS_W: + if inputs.export_price[t] < 0 or inputs.discouraged(t): + cu[t] = rest + else: + cap = rest if inputs.export_limit_w is None else min(rest, inputs.export_limit_w) + ex[t] = cap + cu[t] = rest - cap + if d > 0: + hold = margin < 0 and any(g.holds for g in pending) + if battery is not None and not hold: + bl[t] = max(0.0, min(d, max_dis, (e - floor) * eta_d / dt)) + gl[t] = d - bl[t] + if battery is not None: + e = e + dt * (eta_c * (pc[t] + gc[t]) - bl[t] / eta_d) + soc[t] = e + return Schedule( + grid_load_w=tuple(gl), + battery_load_w=tuple(bl), + pv_charge_w=tuple(pc), + grid_charge_w=tuple(gc), + export_w=tuple(ex), + curtail_w=tuple(cu), + soc_wh=tuple(soc), + devices_w=tuple(tuple(d) for d in dev), + ) + + +def _extra(extra_grid_w: list[float], start: int, end: int, dt: float, eta_c: float) -> float: + return sum(extra_grid_w[start : end + 1]) * dt * eta_c + + +def heuristic_schedule(inputs: PlannerInputs, econ: Economics | None = None) -> Schedule: + """The rule-based schedule of the module doc.""" + econ = econ or economics(inputs) + extra = [0.0] * inputs.n + schedule = _simulate(inputs, econ, extra) + battery = inputs.battery + if battery is None or not any(w > 0 for w in inputs.grid_charge_w): + return schedule + dt, eta_c = inputs.dt_h, battery.model.charge_efficiency + for _ in range(len(inputs.goals) + 1): + shortfalls = goal_shortfall_wh(inputs, econ, schedule) + missing = [ + (slot, short) + for goal, slot, short in zip(inputs.goals, econ.goal_slots, shortfalls, strict=True) + if slot is not None and short > 1.0 and goal.kind in HOLD_KINDS + ] + if not missing: + break + slot, short = missing[0] + candidates = sorted( + (t for t in range(slot + 1) if inputs.grid_charge_at(t) > extra[t] + EPS_W), + key=lambda t: (inputs.import_price[t], t), + ) + if not candidates: + break + need = short + for t in candidates: + if need <= 0: + break + free = min(inputs.grid_charge_at(t), battery.max_charge_w) - extra[t] + add = min(free, need / (dt * eta_c)) + extra[t] += add + need -= add * dt * eta_c + schedule = _simulate(inputs, econ, extra) + return schedule + + +__all__ = ["heuristic_schedule"] diff --git a/suncore/planner/inputs.py b/suncore/planner/inputs.py new file mode 100644 index 0000000..a7b5e23 --- /dev/null +++ b/suncore/planner/inputs.py @@ -0,0 +1,837 @@ +# SPDX-License-Identifier: Apache-2.0 +"""What the planner plans with (Phase 4 WP8): one immutable snapshot, built by a pure function. + +:func:`build_inputs` turns the services' outputs into :class:`PlannerInputs` on the 15-minute +planning grid from the quarter hour containing ``now`` to ``now + 48 h``. It does no I/O; the +runtime (WP9) collects the arguments: + +* ``prices``: :meth:`suncore.tariff.TariffService.prices` (end prices, export already 0 where + the region's negative-price rule applies). A ``spot_only`` series (no price formula + configured) is **refused**: the planner then plans without price optimisation + (:attr:`PriceMode.FLAT`) and says why (``planner.fallback.spot_without_formula``) - a bare + spot price is not what the user pays and would plan grid charging on the wrong numbers. +* ``pv``: the blended PV :class:`~suncore.core.series.QuantileSeries`; ``load``: the base-load + forecast (house minus controlled devices). +* ``morning_buffer`` / ``evening_target``: the risk model's results (WP7; anything with + ``soc_pct`` and ``reason``, e.g. ``SocTarget`` or ``RiskTargetView``) and ``evening_at`` + (``RiskView.evening_at``). Caution enters **only** through these targets (plan §0: no P10 + constraints; the device budget before each target, ``model.Economics.device_budget``, is + computed on P50, review D4). An evening target at max SoC is placed at the start of the + evening's deficit, so the plan never holds a full battery while the house imports (review + m2). +* ``goals.battery_target``: a timed soft target at every occurrence of its local time in the + horizon (maintainer 2026-10-22: its time belongs to the planner). + +Prices missing at the end of the horizon (tomorrow's prices before ~13:00) are filled with the +median of the known prices of the same kind and counted (``prices_filled_slots``); grid +charging is never planned in a slot without a known price. + +Times are UTC, powers W (mean over the slot), energies Wh, prices currency/kWh; battery ++ = charging (``core/units.py``). +""" + +from __future__ import annotations + +import math +import statistics +from collections.abc import Mapping, Sequence +from dataclasses import dataclass, field +from datetime import date, datetime, time, timedelta, tzinfo +from enum import StrEnum, unique +from typing import Final, Literal, Protocol + +from suncore.core.battery import ( + BatteryModel, + BatterySettings, + BatteryStrategy, + GridChargePolicy, + effective_reserve_pct, +) +from suncore.core.config import GoalsConfig, effective_grid_charge_policy +from suncore.core.control import Plan +from suncore.core.decisions import Reason +from suncore.core.devices import ( + ContinuousControl, + DeviceConfig, + ModeControl, + RelaysControl, + StepsControl, + TimeWindow, +) +from suncore.core.series import ( + PLANNING_STEP, + Grid, + PriceSeries, + QuantileSeries, + planning_grid, + resample_prices, + resample_quantiles, +) +from suncore.core.site import BatteryConfig +from suncore.planner import reasons as rk + +PLANNER_HORIZON: Final = timedelta(hours=48) +DEFAULT_BUDGET_S: Final = 8.0 +"""ADR-0003: solver time budget.""" +DEFAULT_MIP_GAP: Final = 0.01 +DEFAULT_BASE_LOAD_W: Final = 500.0 +"""Base load assumed without a load forecast (review m4): a little above a typical +household's night load, so the battery is not planned as if the house used nothing.""" +MIN_BASE_LOAD_W: Final = 100.0 +FLAT_IMPORT_PRICE: Final = 1.0 +"""Nominal import price of :attr:`PriceMode.FLAT` (no price optimisation): every imported kWh +counts the same, so the plan maximises self-sufficiency; the objective is then not money.""" +DEVICE_VALUE_MARGIN: Final = 0.01 +"""Automatic device value above the export price (currency/kWh): consumption beats export.""" +DAYLIGHT_SHARE: Final = 0.02 +FALLBACK_SUNSET: Final = time(19, 0) + +ScalarArg = str | int | float | bool + + +@unique +class PriceMode(StrEnum): + """Whether the plan optimises cost on real prices or only self-sufficiency.""" + + MARKET = "market" + FLAT = "flat" + + +GoalKind = Literal["morning_buffer", "evening_target", "user_target", "prefer_full"] + + +class TargetLike(Protocol): + """A computed SoC with its reason (``forecast.risk.SocTarget``, ``RiskTargetView``).""" + + @property + def soc_pct(self) -> float: ... + + @property + def reason(self) -> Reason: ... + + +@dataclass(frozen=True, slots=True) +class SocGoal: + """A soft lower bound on the SoC at the end of the slot that contains ``at``.""" + + kind: GoalKind + soc_pct: float + at: datetime + reason: Reason + + +@dataclass(frozen=True, slots=True) +class PlannerDevice: + """A controllable consumer as flexible energy (Phase 4: no thermal model, no binaries). + + ``min_w`` is informational: the LP plans ``[0, max_w]`` (a semi-continuous minimum + needs a binary; Phase 6). ``allowed[t]`` = the device's time windows admit slot ``t``. + """ + + device_id: str + max_w: float + allowed: tuple[bool, ...] + value_per_kwh: float | None = None + """Configured utility; ``None`` = automatic (just above the export price).""" + min_w: float = 0.0 + priority: int = 0 + + +@dataclass(frozen=True, slots=True) +class PlannerBattery: + """The battery as the plan sees it (effective limits, live SoC).""" + + model: BatteryModel + soc_pct: float + reserve_pct: float + """``core.battery.effective_reserve_pct`` (ADR-0013 decision 3), below ``max_soc_pct``.""" + max_soc_pct: float + max_charge_w: float + max_discharge_w: float + strategy: BatteryStrategy = BatteryStrategy.SELF_CONSUMPTION + + @property + def capacity_wh(self) -> float: + return self.model.capacity_wh + + @property + def soc_wh(self) -> float: + return self.model.soc_to_wh(self.soc_pct) + + @property + def reserve_wh(self) -> float: + return self.model.soc_to_wh(self.reserve_pct) + + @property + def max_wh(self) -> float: + return self.model.soc_to_wh(self.max_soc_pct) + + +@dataclass(frozen=True, slots=True) +class PlannerWeights: + """Expert weights of the objective (BRIEF §4.12); ``None`` = derived from the prices. + + Defaults (module ``model`` documents the derivation): self-sufficiency 0.01/kWh (plan + §0), curtailment 0.0001/kWh (a tie-breaker: export at price 0 beats curtailment), + morning buffer ``2 * max|price| + 0.5``, evening and user targets ``10 * max|price| + 1``, + reserve ``100 * max|price| + 10`` (all per kWh of shortfall), terminal value + ``median(import) * discharge efficiency - degradation / 2``. + """ + + autarky_per_kwh: float = 0.01 + curtail_per_kwh: float = 1e-4 + buffer_penalty_per_kwh: float | None = None + target_penalty_per_kwh: float | None = None + reserve_penalty_per_kwh: float | None = None + terminal_value_per_kwh: float | None = None + + +@dataclass(frozen=True, slots=True) +class PlannerInputs: + """Everything one planner run needs, on one grid (all tuples have ``len(starts)`` items).""" + + now: datetime + starts: tuple[datetime, ...] + step: timedelta + tz: tzinfo + import_price: tuple[float, ...] + """Price used by the objective (filled; :data:`FLAT_IMPORT_PRICE` in flat mode).""" + export_price: tuple[float, ...] + import_known: tuple[float | None, ...] + """The source's import price (``None`` = unknown); grid charging needs a known one.""" + price_mode: PriceMode + pv_p10: tuple[float, ...] + pv_p50: tuple[float, ...] + pv_p90: tuple[float, ...] + load_p10: tuple[float, ...] + load_p50: tuple[float, ...] + load_p90: tuple[float, ...] + battery: PlannerBattery | None = None + grid_charge_w: tuple[float, ...] = () + """Most the battery may charge from the grid per slot (0 = policy or spread rule says no).""" + grid_charge_policy: GridChargePolicy = field(default_factory=GridChargePolicy) + goals: tuple[SocGoal, ...] = () + morning_buffer_pct: float | None = None + """"Battery first until X %" for the coming daytime (``priority_until_soc_pct``).""" + export_discouraged: tuple[bool, ...] = () + """Slots where the region's negative-price rule zeroed the export price (proxy: export + price <= 0 while the known import price is negative): exporting there costs a small + penalty above curtailment (review D3; curtailment is informational until Phase 6).""" + import_limit_w: float | None = None + export_limit_w: float | None = None + devices: tuple[PlannerDevice, ...] = () + previous: Plan | None = None + weights: PlannerWeights = field(default_factory=PlannerWeights) + reasons: tuple[Reason, ...] = () + """Plan-level reasons about the inputs (no prices, missing forecasts).""" + assumptions: Mapping[str, ScalarArg] = field(default_factory=dict) + + def __post_init__(self) -> None: + n = len(self.starts) + if n == 0: + msg = "planner inputs: empty grid" + raise ValueError(msg) + series = ( + self.import_price, + self.export_price, + self.import_known, + self.pv_p10, + self.pv_p50, + self.pv_p90, + self.load_p10, + self.load_p50, + self.load_p90, + ) + if any(len(s) != n for s in series): + msg = "planner inputs: every series needs one value per slot" + raise ValueError(msg) + if self.export_discouraged and len(self.export_discouraged) != n: + msg = "planner inputs: export_discouraged needs one value per slot" + raise ValueError(msg) + if self.grid_charge_w and len(self.grid_charge_w) != n: + msg = "planner inputs: grid_charge_w needs one value per slot" + raise ValueError(msg) + if any(len(d.allowed) != n for d in self.devices): + msg = "planner inputs: device windows need one value per slot" + raise ValueError(msg) + floats = (*series[:2], *series[3:]) + if any(not math.isfinite(v) for s in floats for v in s): + msg = "planner inputs: values must be finite" + raise ValueError(msg) + + @property + def n(self) -> int: + return len(self.starts) + + @property + def dt_h(self) -> float: + return self.step / timedelta(hours=1) + + @property + def end(self) -> datetime: + return self.starts[-1] + self.step + + def discouraged(self, t: int) -> bool: + return bool(self.export_discouraged) and self.export_discouraged[t] + + def price_estimated(self, t: int) -> bool: + """The import price of slot ``t`` is a stand-in (median fill or flat mode).""" + return self.import_known[t] is None + + def grid_charge_at(self, t: int) -> float: + return self.grid_charge_w[t] if self.grid_charge_w else 0.0 + + def slot_of(self, at: datetime) -> int | None: + """Index of the slot whose *end* is the first at or after ``at`` (``None`` = outside).""" + if at <= self.starts[0] or at > self.end: + return None + index = math.ceil((at - self.starts[0]) / self.step) - 1 + return max(0, min(self.n - 1, index)) + + +# --- builder ------------------------------------------------------------------------------ + + +def _inside(window: TimeWindow, local: datetime) -> bool: + """Same rule as the controller's window check (``controller.allocation``).""" + day = local.weekday() + t = local.time().replace(tzinfo=None) + if window.start < window.end: + return day in window.days and window.start <= t < window.end + previous = (day - 1) % 7 + return (day in window.days and t >= window.start) or ( + previous in window.days and t < window.end + ) + + +def window_allows(windows: Sequence[TimeWindow], local: datetime) -> bool: + allows = [w for w in windows if w.mode == "allow"] + if any(_inside(w, local) for w in windows if w.mode == "block"): + return False + return not allows or any(_inside(w, local) for w in allows) + + +def device_max_power_w(device: DeviceConfig) -> float | None: + """The power a device draws when fully on (mirrors the controller's nominal power).""" + nominal = device.power_model.nominal_w + if nominal is not None: + return nominal + control = device.control + if isinstance(control, StepsControl | RelaysControl): + return control.steps[-1].power_w + if isinstance(control, ModeControl): + return max(m.power_w for m in control.modes) + if isinstance(control, ContinuousControl): + if control.unit == "W": + return control.max + if control.unit == "A": + return control.max * control.voltage_v * control.phases + return None + + +def _device_min_w(device: DeviceConfig) -> float: + control = device.control + if isinstance(control, ContinuousControl) and control.unit == "W": + return control.min + return 0.0 + + +def _quantiles( + series: QuantileSeries | None, grid: Grid, fill: float | None +) -> tuple[list[float], list[float], list[float], int]: + """P10/P50/P90 on ``grid`` (W, never negative); a missing P50 becomes ``fill`` (``None`` = + the mean of the known values), a missing outer quantile the P50.""" + if series is None: + zero = [0.0 if fill is None else fill] * grid.count + return zero, list(zero), list(zero), grid.count + q = resample_quantiles(series, grid) + known = [v for v in q.p50.values if v is not None] + default = fill if fill is not None else (statistics.fmean(known) if known else 0.0) + p10: list[float] = [] + p50: list[float] = [] + p90: list[float] = [] + for lo, mid, hi in zip(q.p10.values, q.p50.values, q.p90.values, strict=True): + m = default if mid is None else max(0.0, mid) + p50.append(m) + p10.append(m if lo is None else min(m, max(0.0, lo))) + p90.append(m if hi is None else max(m, hi)) + return p10, p50, p90, grid.count - len(known) + + +def _median(values: Sequence[float]) -> float: + return statistics.median(values) if values else 0.0 + + +@dataclass(frozen=True, slots=True) +class _Prices: + mode: PriceMode + import_price: list[float] + export_price: list[float] + known: list[float | None] + filled: int + reasons: list[Reason] + + +def _prices(prices: PriceSeries | None, grid: Grid, tz: tzinfo) -> _Prices: + if prices is None: + return _Prices( + PriceMode.FLAT, + [FLAT_IMPORT_PRICE] * grid.count, + [0.0] * grid.count, + [None] * grid.count, + 0, + [Reason(key=rk.FALLBACK_NO_PRICES)], + ) + on_grid = resample_prices(prices, grid) + raw_import = list(on_grid.import_price.values) + raw_export: list[float | None] = ( + [None] * grid.count if on_grid.export_price is None else list(on_grid.export_price.values) + ) + known_export = [v for v in raw_export if v is not None] + export_fill = _median(known_export) + export = [export_fill if v is None else v for v in raw_export] + known_import = [v for v in raw_import if v is not None] + if on_grid.price_includes == "spot_only": + return _Prices( + PriceMode.FLAT, + [FLAT_IMPORT_PRICE] * grid.count, + export, + [None] * grid.count, + 0, + [Reason(key=rk.FALLBACK_SPOT_WITHOUT_FORMULA, args={"source": prices.source_id})], + ) + if not known_import: + return _Prices( + PriceMode.FLAT, + [FLAT_IMPORT_PRICE] * grid.count, + export, + [None] * grid.count, + 0, + [Reason(key=rk.FALLBACK_NO_PRICES)], + ) + fill = _median(known_import) + filled = sum(1 for v in raw_import if v is None) + found: list[Reason] = [] + if filled: + last = max(i for i, v in enumerate(raw_import) if v is not None) + found.append( + Reason( + key=rk.INPUT_PRICES_PARTIAL, + args={ + "known_until": (grid.start + grid.step * (last + 1)) + .astimezone(tz) + .strftime("%Y-%m-%d %H:%M"), + "filled_slots": filled, + }, + ) + ) + return _Prices( + PriceMode.MARKET, + [fill if v is None else v for v in raw_import], + export, + raw_import, + filled, + found, + ) + + +def grid_charge_allowance( + starts: Sequence[datetime], + known: Sequence[float | None], + *, + load_w: Sequence[float], + battery: PlannerBattery | None, + policy: GridChargePolicy, + tz: tzinfo, + import_limit_w: float | None, +) -> list[float]: + """Most grid-charging power per slot (W); 0 where it is not allowed. + + Allowed only where :meth:`GridChargePolicy.allows` admits the slot start with the slot's + **known** import price (an unknown price never satisfies a price level) and, on a + tariff whose price varies, the spread rule pays against the best known later price + (:meth:`BatteryModel.grid_charge_pays`). The power is bounded by the battery's charge + limit and by the import headroom ``import_limit - base load`` (ADR-0013: the site import + limit always holds). A slot without a known price (flat mode, unpublished prices) never + allows grid charging, even under a schedule-only policy. + """ + n = len(starts) + if battery is None or not policy.enabled: + return [0.0] * n + distinct = {round(v, 6) for v in known if v is not None} + dynamic = len(distinct) > 1 + best_later: list[float | None] = [None] * n + running: float | None = None + for t in range(n - 1, -1, -1): + best_later[t] = running + value = known[t] + if value is not None: + running = value if running is None else max(running, value) + out: list[float] = [] + for t in range(n): + price = known[t] + if price is None or not policy.allows(starts[t], price, tz): + # No grid charging without a known price, whatever the policy (review D2). + out.append(0.0) + continue + if dynamic: + later = best_later[t] + if price is None or later is None or not battery.model.grid_charge_pays(price, later): + out.append(0.0) + continue + cap = battery.max_charge_w + if import_limit_w is not None: + cap = min(cap, max(0.0, import_limit_w - load_w[t])) + out.append(max(0.0, cap)) + return out + + +def _local_occurrences(at: time, start: datetime, end: datetime, tz: tzinfo) -> list[datetime]: + """Every instant in ``(start, end]`` whose local wall time is ``at``.""" + found: list[datetime] = [] + day = start.astimezone(tz).date() - timedelta(days=1) + last = end.astimezone(tz).date() + while day <= last: + moment = datetime.combine(day, at, tzinfo=tz) + if start < moment <= end: + found.append(moment) + day += timedelta(days=1) + return found + + +def sunsets( + starts: Sequence[datetime], step: timedelta, pv: Sequence[float], tz: tzinfo +) -> list[datetime]: + """Per local day of the grid: the end of its last slot above 2 % of the day's PV peak + (:data:`FALLBACK_SUNSET` local time on a day without PV in the forecast).""" + days: dict[date, list[tuple[int, float]]] = {} + for i, (begin, value) in enumerate(zip(starts, pv, strict=True)): + days.setdefault(begin.astimezone(tz).date(), []).append((i, value)) + out: list[datetime] = [] + for day, slots in sorted(days.items()): + peak = max(v for _, v in slots) + lit = [i for i, v in slots if peak > 0 and v > DAYLIGHT_SHARE * peak] + out.append( + starts[lit[-1]] + step if lit else datetime.combine(day, FALLBACK_SUNSET, tzinfo=tz) + ) + return out + + +def buffer_goal( + battery: PlannerBattery, + target_pct: float, + *, + starts: Sequence[datetime], + step: timedelta, + pv: Sequence[float], + load: Sequence[float], + until: datetime, +) -> tuple[datetime, float] | None: + """Where the morning buffer becomes a soft SoC target: ``(time, SoC %)`` or ``None``. + + Self-consumption simulation on P50 from the live SoC, battery first (all PV surplus to + the battery, the battery covers the house deficit down to the reserve, no grid + charging), until ``until`` (the coming sunset). The goal is the end of the first slot at + or above ``target_pct``; when PV cannot get there, the highest SoC the simulation reaches + (at the first slot it reaches it). So the buffer only orders the surplus (battery before + devices) and never makes the plan hold energy or buy it from the grid by itself. + ``None`` = the live SoC is already there, or PV adds nothing. + """ + model = battery.model + target = model.soc_to_wh(target_pct) + energy = battery.soc_wh + if energy >= target - 1e-6: + return None + hours = step / timedelta(hours=1) + best: tuple[datetime, float] | None = None + for t, begin in enumerate(starts): + end = begin + step + if end > until: + break + net = pv[t] - load[t] + if net > 0: + gain = min(net, battery.max_charge_w) * hours * model.charge_efficiency + energy = min(battery.max_wh, energy + gain) + else: + loss = min(-net, battery.max_discharge_w) * hours / model.discharge_efficiency + energy = max(min(energy, battery.reserve_wh), energy - loss) + if energy >= target - 1e-6: + return end, target_pct + if net > 0 and energy > battery.soc_wh + 1e-6 and (best is None or energy > best[1] + 1e-6): + best = (end, energy) + if best is None: + return None + return best[0], round(model.wh_to_soc(best[1]), 3) + + +def _battery( + settings: BatterySettings, soc_pct: float | None, site_battery: BatteryConfig | None +) -> PlannerBattery | None: + model = settings.model + if model is None or soc_pct is None or not math.isfinite(soc_pct): + return None + max_soc = model.max_soc_pct + max_charge, max_discharge = model.max_charge_w, model.max_discharge_w + if site_battery is not None: + if site_battery.max_soc_pct is not None: + max_soc = min(max_soc, site_battery.max_soc_pct) + if site_battery.max_charge_w is not None: + max_charge = min(max_charge, site_battery.max_charge_w) + if site_battery.max_discharge_w is not None: + max_discharge = min(max_discharge, site_battery.max_discharge_w) + reserve = min(effective_reserve_pct(site_battery, model), max_soc) + return PlannerBattery( + model=model, + soc_pct=min(100.0, max(0.0, soc_pct)), + reserve_pct=reserve, + max_soc_pct=max_soc, + max_charge_w=max_charge, + max_discharge_w=max_discharge, + strategy=settings.strategy, + ) + + +def _soc_goals( + battery: PlannerBattery | None, + *, + starts: Sequence[datetime], + step: timedelta, + tz: tzinfo, + pv: Sequence[float], + load: Sequence[float], + goals: GoalsConfig, + morning_buffer: TargetLike | None, + evening_target: TargetLike | None, + evening_at: datetime | None, +) -> tuple[list[SocGoal], float | None]: + if battery is None: + return [], None + begin, end = starts[0], starts[-1] + step + out: list[SocGoal] = [] + cap = battery.max_soc_pct + coming = [at for at in sunsets(starts, step, pv, tz) if at > begin + step] + evening = evening_at if evening_at is not None else (coming[0] if coming else end) + if evening_target is not None and begin + step < evening <= end: + soc = min(cap, evening_target.soc_pct) + at = evening + if soc >= cap - 1e-6: + at = _deficit_start(starts, step, pv, load, evening) + out.append(SocGoal("evening_target", soc, at, evening_target.reason)) + buffer_pct: float | None = None + buffer_reason: Reason | None = None + if morning_buffer is not None: + buffer_pct, buffer_reason = min(cap, morning_buffer.soc_pct), morning_buffer.reason + elif battery.strategy is BatteryStrategy.PREFER_FULL: + buffer_pct = cap + buffer_reason = Reason(key=rk.PREFER_FULL, args={"soc_pct": round(cap, 1)}) + if buffer_pct is not None and buffer_reason is not None: + # The buffer is for the coming daytime: due at the latest by its sunset. + until = evening if begin + step < evening <= end else (coming[0] if coming else end) + until = min(until, end) + reach = buffer_goal( + battery, buffer_pct, starts=starts, step=step, pv=pv, load=load, until=until + ) + if reach is not None: + kind: GoalKind = "morning_buffer" if morning_buffer is not None else "prefer_full" + if reach[1] < buffer_pct - 0.05: + # PV cannot get there today: the reason names what the plan aims at (m3). + args = dict(buffer_reason.args) + args["soc_pct"] = round(reach[1], 1) + buffer_reason = Reason(key=buffer_reason.key, args=args) + out.append(SocGoal(kind, reach[1], reach[0], buffer_reason)) + target = goals.battery_target + if target is not None: + hh, mm = (int(x) for x in target.time.split(":")) + for moment in _local_occurrences(time(hh, mm), begin + step, end, tz): + soc = min(cap, max(battery.reserve_pct, target.soc_pct)) + out.append( + SocGoal( + "user_target", + soc, + moment, + Reason( + key=rk.USER_TARGET, + args={"soc_pct": round(soc, 1), "time": target.time}, + ), + ) + ) + out.sort(key=lambda g: g.at) + return out, buffer_pct + + +def _deficit_start( + starts: Sequence[datetime], + step: timedelta, + pv: Sequence[float], + load: Sequence[float], + evening: datetime, +) -> datetime: + """Start of the deficit run (load above PV) that ends at ``evening``; ``evening`` if the + slot before it has surplus. A full battery is due there, not later (review m2).""" + last = None + for t, begin in enumerate(starts): + if begin + step >= evening: + last = t + break + if last is None: + return evening + first = last + while first > 0 and load[first - 1] >= pv[first - 1]: + first -= 1 + if first == last and load[last] < pv[last]: + return evening + return starts[first] if first > 0 else evening + + +def build_inputs( + now: datetime, + *, + tz: tzinfo, + load: QuantileSeries | None, + pv: QuantileSeries | None, + prices: PriceSeries | None, + battery: BatterySettings, + soc_pct: float | None, + goals: GoalsConfig | None = None, + site_battery: BatteryConfig | None = None, + morning_buffer: TargetLike | None = None, + evening_target: TargetLike | None = None, + evening_at: datetime | None = None, + devices: Sequence[DeviceConfig] = (), + device_max_w: Mapping[str, float] | None = None, + import_limit_w: float | None = None, + export_limit_w: float | None = None, + previous: Plan | None = None, + weights: PlannerWeights | None = None, + horizon: timedelta = PLANNER_HORIZON, + load_fallback_w: float | None = None, +) -> PlannerInputs: + """The planner's snapshot (module doc); pure.""" + goals = goals or GoalsConfig() + grid = planning_grid(now, horizon, PLANNING_STEP) + starts = tuple(grid.starts()) + found: list[Reason] = [] + pv10, pv50, pv90, pv_missing = _quantiles(pv, grid, 0.0) + if pv is None: + found.append(Reason(key=rk.INPUT_NO_PV_FORECAST)) + l10, l50, l90, load_missing = _quantiles(load, grid, None) + no_load = load is None or load_missing == grid.count + if no_load: + # Never plan on 0 W base load (review m4): a flat, conservative profile - the recent + # mean the runtime passes, else DEFAULT_BASE_LOAD_W - and no device planning. + flat = load_fallback_w if load_fallback_w is not None else DEFAULT_BASE_LOAD_W + flat = max(flat, MIN_BASE_LOAD_W) + l10, l50, l90 = [flat * 0.5] * grid.count, [flat] * grid.count, [flat * 2] * grid.count + found.append(Reason(key=rk.INPUT_NO_LOAD_FORECAST, args={"load_w": round(flat)})) + price_data = _prices(prices, grid, tz) + found = price_data.reasons + found + planner_battery = _battery(battery, soc_pct, site_battery) + if battery.model is not None and planner_battery is None: + found.append(Reason(key=rk.INPUT_NO_BATTERY_SOC)) + policy = effective_grid_charge_policy(goals, battery) + allowance = grid_charge_allowance( + starts, + price_data.known if price_data.mode is PriceMode.MARKET else [None] * grid.count, + load_w=l50, + battery=planner_battery, + policy=policy, + tz=tz, + import_limit_w=import_limit_w, + ) + soc_goals, buffer_pct = _soc_goals( + planner_battery, + starts=starts, + step=grid.step, + tz=tz, + pv=pv50, + load=l50, + goals=goals, + morning_buffer=morning_buffer, + evening_target=evening_target, + evening_at=evening_at, + ) + planned: list[PlannerDevice] = [] + for device in [] if no_load else devices: + override = None if device_max_w is None else device_max_w.get(device.id) + max_w = override if override is not None else device_max_power_w(device) + if max_w is None or max_w <= 0: + found.append(Reason(key=rk.INPUT_DEVICE_POWER_UNKNOWN, args={"device": device.id})) + continue + allowed = tuple(window_allows(device.windows, s.astimezone(tz)) for s in starts) + planned.append( + PlannerDevice( + device_id=device.id, + max_w=max_w, + allowed=allowed, + value_per_kwh=device.planner_value_per_kwh, + min_w=_device_min_w(device), + priority=device.priority, + ) + ) + assumptions: dict[str, ScalarArg] = { + "price_mode": price_data.mode.value, + "horizon_slots": grid.count, + "prices_filled_slots": price_data.filled, + "pv_missing_slots": pv_missing, + "load_missing_slots": load_missing, + "devices": len(planned), + "risk": battery.risk.value, + "strategy": battery.strategy.value, + } + if prices is not None: + assumptions["price_source"] = prices.source_id + return PlannerInputs( + now=now, + starts=starts, + step=grid.step, + tz=tz, + import_price=tuple(price_data.import_price), + export_price=tuple(price_data.export_price), + import_known=tuple(price_data.known), + price_mode=price_data.mode, + pv_p10=tuple(pv10), + pv_p50=tuple(pv50), + pv_p90=tuple(pv90), + load_p10=tuple(l10), + load_p50=tuple(l50), + load_p90=tuple(l90), + battery=planner_battery, + grid_charge_w=tuple(allowance), + grid_charge_policy=policy, + goals=tuple(soc_goals), + morning_buffer_pct=buffer_pct, + export_discouraged=tuple( + e <= 0 and (e < 0 or (k is not None and k < 0)) + for e, k in zip(price_data.export_price, price_data.known, strict=True) + ), + import_limit_w=import_limit_w, + export_limit_w=export_limit_w, + devices=tuple(planned), + previous=previous, + weights=weights or PlannerWeights(autarky_per_kwh=battery.autarky_weight_per_kwh), + reasons=tuple(found), + assumptions=assumptions, + ) + + +__all__ = [ + "DEFAULT_BASE_LOAD_W", + "DEFAULT_BUDGET_S", + "DEFAULT_MIP_GAP", + "DEVICE_VALUE_MARGIN", + "FLAT_IMPORT_PRICE", + "PLANNER_HORIZON", + "GoalKind", + "PlannerBattery", + "PlannerDevice", + "PlannerInputs", + "PlannerWeights", + "PriceMode", + "SocGoal", + "TargetLike", + "buffer_goal", + "build_inputs", + "device_max_power_w", + "grid_charge_allowance", + "window_allows", +] diff --git a/suncore/planner/model.py b/suncore/planner/model.py new file mode 100644 index 0000000..5dbfbab --- /dev/null +++ b/suncore/planner/model.py @@ -0,0 +1,779 @@ +# SPDX-License-Identifier: Apache-2.0 +"""The planner's linear program and the solver backend (Phase 4 WP8, ADR-0003). + +**Flows.** PV serves the base load first (what the inverter does physically). Per 15-minute +slot ``t`` the P50 forecast then leaves either a *surplus* ``s_t = max(0, pv - load)`` or a +*deficit* ``d_t = max(0, load - pv)``, known before solving. The variables (kW in the LP, W in +a :class:`Schedule`) split the flows by source and sink: + +========= =================================== ========================================== +variable flow bounds +========= =================================== ========================================== +``gL`` grid -> base load ``[0, d]`` +``bL`` battery -> base load (discharge) ``[0, min(d, max discharge)]`` +``pC`` PV surplus -> battery ``[0, min(s, max charge)]`` +``gC`` grid -> battery (grid charging) ``[0, allowance_t]`` (policy + spread rule) +``E`` PV surplus -> export ``[0, min(s, export limit)]`` +``K`` PV surplus curtailed (informational) ``[0, s]`` +``D_j`` PV surplus -> device ``j`` ``[0, min(max_j, s)]``, 0 outside its window +``e`` stored energy at the end of ``t`` ``[reserve, max SoC]`` (kWh) +========= =================================== ========================================== + +Constraints: ``pC + E + K + sum D = s`` and ``gL + bL = d`` (together the energy balance +``pv + import + discharge = load + devices + charge + export + curtail``); ``pC + gC <= max +charge``; ``e_t = e_{t-1} + dt * (eta_c * (pC + gC) - bL / eta_d)``; soft lower bounds +``e_k + short_k >= target_k`` for the morning buffer, the evening target and the user's timed +target (a high penalty per kWh of shortfall, so the model is always feasible and the +shortfall is explained); the import limit holds through the grid-charging allowance +(``allowance <= import limit - base load``). + +**Rigour of "no import for a device"**: devices draw only from the PV surplus over the base +load (``D_j`` appears only in the surplus balance), so neither the grid nor the battery can +feed them - structurally, not through a price cap. The battery discharges only for the base +load (never for export; ADR-0013 limits cannot express a forced discharge). + +**Simultaneous charge and discharge** needs no binary: in a deficit slot only ``gC`` and +``bL`` could coexist, and that loop only loses efficiency and degradation (``gL`` serves the +same load at the same price without the loss); dumping energy at negative prices is done by +curtailment, which is free of losses. Phase 4 therefore solves a pure LP (``n_binaries = 0``); +the backend accepts integer columns for later device models (Phase 6). + +**Objective** (minimised, currency; energies ``dt * power``):: + + sum_t (p_imp + w_aut) * (gL + gC) import cost + self-sufficiency weight + - p_exp * E export revenue (0 under the negative rule) + + deg / 2 * (pC + gC + bL) degradation per kWh of throughput + + w_cur * K tie-breaker: export at price 0 beats curtail + - sum_j v_jt * D_j device utility + + sum_k P_k * short_k soft targets + + P_res * (below-reserve / above-max slack) only when the live SoC starts outside + - V_term * e_{T} terminal value of the stored energy + +``deg / 2`` on charge and on discharge equals the configured cost per charged kWh over a full +cycle. Device value ``v_jt`` = the configured ``planner_value_per_kwh`` or automatically the +export price + 0.01, capped at ``max(import price, export price + 0.01)`` (plan §0: never above +the import price; in a negative-price slot the floor "consumption beats export" wins, which +is safe because devices cannot import anyway). Penalties derive from the largest absolute +price ``m``: morning buffer ``2m + 0.5`` (beats every device value and export), evening and +user target ``10m + 1``, reserve ``100m + 10``. The terminal value ``median(import) * eta_d - +deg / 2`` is conservative (median, not the peak) so the plan neither empties the battery +because the horizon ends nor hoards energy against a price it may never see. +""" + +from __future__ import annotations + +import math +import statistics +import time +from collections.abc import Sequence +from dataclasses import dataclass +from typing import Final, Literal, Protocol + +import numpy as np +import numpy.typing as npt + +from suncore.planner.inputs import DEVICE_VALUE_MARGIN, PlannerInputs, SocGoal + +FloatArray = npt.NDArray[np.float64] +IntArray = npt.NDArray[np.int64] + +GL, BL, PC, GC, EX, CU, SOC, LOW, HIGH, FIRST = range(10) +SLOT_VARS: Final = 10 +KW: Final = 1000.0 +INF: Final = math.inf +BALANCE_TOL_W: Final = 1.0 +EARLY_CHARGE_PER_KWH: Final = 1e-4 +"""Tie-breaker (review M3): charging PV earlier is worth up to this much more per kWh, falling +linearly over the horizon, so equal-cost plans charge early instead of at the last moment.""" +DISCOURAGED_EXPORT_PER_KWH: Final = 1e-3 +"""Penalty on export where the negative-price rule zeroed the export price (review D3); ten +times the curtailment tie-breaker, so curtailing (informational until Phase 6) wins.""" +BUFFER_KINDS: Final = ("morning_buffer", "prefer_full") +TARGET_KINDS: Final = ("evening_target", "user_target") +SOC_TOL_WH: Final = 1.0 + + +# --- layout and economics ------------------------------------------------------------------- + + +@dataclass(frozen=True, slots=True) +class Layout: + """Column index of every variable.""" + + n: int + n_dev: int + n_goals: int + + @property + def per_slot(self) -> int: + return SLOT_VARS + self.n_dev + + @property + def n_vars(self) -> int: + return self.n * self.per_slot + self.n_goals + + def var(self, t: int, kind: int) -> int: + return t * self.per_slot + kind + + def dev(self, t: int, j: int) -> int: + return t * self.per_slot + SLOT_VARS + j + + def goal(self, k: int) -> int: + return self.n * self.per_slot + k + + +@dataclass(frozen=True, slots=True) +class Economics: + """The numbers the objective uses, derived once from the inputs (module doc).""" + + surplus_w: tuple[float, ...] + deficit_w: tuple[float, ...] + device_value: tuple[tuple[float, ...], ...] + """``[device][slot]`` currency/kWh.""" + buffer_penalty: float + target_penalty: float + reserve_penalty: float + terminal_value: float + goal_slots: tuple[int | None, ...] + goal_penalty: tuple[float, ...] + device_budget: tuple[tuple[int, float], ...] + """Per evening/user target ``(slot, Wh)``: the most device energy until that slot - the + SoC a battery-first day on P50 would have above the target at the slot, divided by the + charge efficiency, plus the PV surplus such a day cannot absorb (charge-power and SoC + limits) up to the slot (review D4: caution enters only through the WP7 targets).""" + first_until: int + """Slots before this index are "battery first" (the morning buffer or ``prefer_full`` + goal is due at its end): surplus beyond what the battery can take + (``s - max charge``) may go to devices, export or curtailment; more costs the buffer + penalty (slack ``FIRST``). ``-1`` = no such rule.""" + + +def economics(inputs: PlannerInputs) -> Economics: + w = inputs.weights + surplus = tuple(max(0.0, p - lo) for p, lo in zip(inputs.pv_p50, inputs.load_p50, strict=True)) + deficit = tuple(max(0.0, lo - p) for p, lo in zip(inputs.pv_p50, inputs.load_p50, strict=True)) + values: list[tuple[float, ...]] = [] + for device in inputs.devices: + row: list[float] = [] + for pi, pe in zip(inputs.import_price, inputs.export_price, strict=True): + floor = pe + DEVICE_VALUE_MARGIN + value = floor if device.value_per_kwh is None else device.value_per_kwh + row.append(min(value, max(pi, floor))) + values.append(tuple(row)) + biggest = max(abs(v) for v in (*inputs.import_price, *inputs.export_price)) + buffer_p = ( + w.buffer_penalty_per_kwh if w.buffer_penalty_per_kwh is not None else 2 * biggest + 0.5 + ) + target_p = ( + w.target_penalty_per_kwh if w.target_penalty_per_kwh is not None else 10 * biggest + 1 + ) + reserve_p = ( + w.reserve_penalty_per_kwh if w.reserve_penalty_per_kwh is not None else 100 * biggest + 10 + ) + battery = inputs.battery + if w.terminal_value_per_kwh is not None: + terminal = w.terminal_value_per_kwh + elif battery is None: + terminal = 0.0 + else: + median = statistics.median(inputs.import_price) + model = battery.model + terminal = max( + 0.0, median * model.discharge_efficiency - model.degradation_cost_per_kwh / 2 + ) + slots = tuple(inputs.slot_of(g.at) for g in inputs.goals) + penalties = tuple(_goal_penalty(g, buffer_p, target_p) for g in inputs.goals) + first_until = max( + ( + slot + for g, slot in zip(inputs.goals, slots, strict=True) + if slot is not None and g.kind in BUFFER_KINDS + ), + default=-1, + ) + return Economics( + surplus_w=surplus, + deficit_w=deficit, + device_value=tuple(values), + buffer_penalty=buffer_p, + target_penalty=target_p, + reserve_penalty=reserve_p, + terminal_value=terminal, + goal_slots=slots, + goal_penalty=penalties, + first_until=first_until, + device_budget=_device_budgets(inputs, slots), + ) + + +def _device_budgets( + inputs: PlannerInputs, slots: tuple[int | None, ...] +) -> tuple[tuple[int, float], ...]: + battery = inputs.battery + if battery is None or not inputs.devices: + return () + model = battery.model + dt = inputs.dt_h + reach: list[float] = [] + e = battery.soc_wh + floor = min(battery.reserve_wh, e) + ceiling = max(battery.max_wh, e) + overflow: list[float] = [] + spilled = 0.0 + for t in range(inputs.n): + net = inputs.pv_p50[t] - inputs.load_p50[t] + if net > 0: + room_w = max(0.0, ceiling - e) / (dt * model.charge_efficiency) + taken = min(net, battery.max_charge_w, room_w) + e = min(ceiling, e + taken * dt * model.charge_efficiency) + spilled += (net - taken) * dt + else: + loss = min(-net, battery.max_discharge_w) * dt / model.discharge_efficiency + e = max(min(e, floor), e - loss) + reach.append(e) + overflow.append(spilled) + out: list[tuple[int, float]] = [] + for goal, slot in zip(inputs.goals, slots, strict=True): + if slot is None or goal.kind not in TARGET_KINDS: + continue + spare = reach[slot] - model.soc_to_wh(goal.soc_pct) + out.append((slot, max(0.0, spare) / model.charge_efficiency + overflow[slot])) + return tuple(out) + + +def _goal_penalty(goal: SocGoal, buffer_p: float, target_p: float) -> float: + return buffer_p if goal.kind in BUFFER_KINDS else target_p + + +# --- schedule -------------------------------------------------------------------------------- + + +@dataclass(frozen=True, slots=True) +class Schedule: + """A planned operation (W per slot, Wh at the end of each slot); LP and heuristic alike.""" + + grid_load_w: tuple[float, ...] + battery_load_w: tuple[float, ...] + pv_charge_w: tuple[float, ...] + grid_charge_w: tuple[float, ...] + export_w: tuple[float, ...] + curtail_w: tuple[float, ...] + soc_wh: tuple[float, ...] + devices_w: tuple[tuple[float, ...], ...] + """``[device][slot]``.""" + + @property + def n(self) -> int: + return len(self.grid_load_w) + + def import_w(self, t: int) -> float: + return self.grid_load_w[t] + self.grid_charge_w[t] + + def charge_w(self, t: int) -> float: + return self.pv_charge_w[t] + self.grid_charge_w[t] + + def battery_w(self, t: int) -> float: + """Battery power, + = charging.""" + return self.charge_w(t) - self.battery_load_w[t] + + def device_total_w(self, t: int) -> float: + return sum(d[t] for d in self.devices_w) + + +# --- the LP ---------------------------------------------------------------------------------- + + +@dataclass(frozen=True, slots=True) +class LinearProblem: + """``min c.x`` s.t. ``row_lower <= A x <= row_upper``, ``col_lower <= x <= col_upper``. + + ``A`` is row-wise (CSR: ``a_start``, ``a_index``, ``a_value``). ``integrality`` lists the + integer columns (none in Phase 4). + """ + + cost: FloatArray + col_lower: FloatArray + col_upper: FloatArray + row_lower: FloatArray + row_upper: FloatArray + a_start: IntArray + a_index: IntArray + a_value: FloatArray + integrality: tuple[int, ...] = () + + @property + def n_cols(self) -> int: + return len(self.cost) + + @property + def n_rows(self) -> int: + return len(self.row_lower) + + +class _Rows: + def __init__(self) -> None: + self.start: list[int] = [0] + self.index: list[int] = [] + self.value: list[float] = [] + self.lower: list[float] = [] + self.upper: list[float] = [] + + def add(self, terms: Sequence[tuple[int, float]], lower: float, upper: float) -> None: + for col, coef in terms: + self.index.append(col) + self.value.append(coef) + self.start.append(len(self.index)) + self.lower.append(lower) + self.upper.append(upper) + + +@dataclass(frozen=True, slots=True) +class _Battery: + e0: float + cap: float + reserve: float + max_: float + max_charge: float + max_discharge: float + eta_c: float + eta_d: float + deg: float + + +def _battery_kwh(inputs: PlannerInputs) -> _Battery | None: + b = inputs.battery + if b is None: + return None + return _Battery( + e0=b.soc_wh / KW, + cap=b.capacity_wh / KW, + reserve=b.reserve_wh / KW, + max_=b.max_wh / KW, + max_charge=b.max_charge_w / KW, + max_discharge=b.max_discharge_w / KW, + eta_c=b.model.charge_efficiency, + eta_d=b.model.discharge_efficiency, + deg=b.model.degradation_cost_per_kwh, + ) + + +def build_problem( # noqa: PLR0912, PLR0915 - one block per constraint family + inputs: PlannerInputs, econ: Economics +) -> tuple[LinearProblem, Layout]: + """The sparse LP of the module doc.""" + n, dt = inputs.n, inputs.dt_h + layout = Layout(n=n, n_dev=len(inputs.devices), n_goals=len(inputs.goals)) + nv = layout.n_vars + cost = np.zeros(nv) + lower = np.zeros(nv) + upper = np.zeros(nv) + rows = _Rows() + bat = _battery_kwh(inputs) + aut = inputs.weights.autarky_per_kwh + cur = inputs.weights.curtail_per_kwh + export_cap = INF if inputs.export_limit_w is None else inputs.export_limit_w / KW + for t in range(n): + s, d = econ.surplus_w[t] / KW, econ.deficit_w[t] / KW + pi, pe = inputs.import_price[t], inputs.export_price[t] + col = layout.var + upper[col(t, GL)] = d + upper[col(t, EX)] = min(s, export_cap) + upper[col(t, CU)] = s + cost[col(t, GL)] = dt * (pi + aut) + cost[col(t, EX)] = -dt * pe + ( + dt * DISCOURAGED_EXPORT_PER_KWH if inputs.discouraged(t) else 0.0 + ) + cost[col(t, CU)] = dt * cur + for j, device in enumerate(inputs.devices): + upper[layout.dev(t, j)] = min(device.max_w / KW, s) if device.allowed[t] else 0.0 + cost[layout.dev(t, j)] = -dt * econ.device_value[j][t] + if bat is not None: + upper[col(t, BL)] = min(d, bat.max_discharge) + upper[col(t, PC)] = min(s, bat.max_charge) + upper[col(t, GC)] = min(inputs.grid_charge_at(t) / KW, bat.max_charge) + half = dt * bat.deg / 2 + cost[col(t, BL)] = half + cost[col(t, PC)] = half - dt * EARLY_CHARGE_PER_KWH * (n - t) / n + cost[col(t, GC)] = dt * (pi + aut) + half + # SoC bounds: inside [reserve, max]; a live SoC outside gets a penalised slack. + lower[col(t, SOC)] = bat.reserve if bat.e0 >= bat.reserve else 0.0 + upper[col(t, SOC)] = bat.max_ if bat.e0 <= bat.max_ else bat.cap + upper[col(t, LOW)] = max(0.0, bat.reserve - bat.e0) + upper[col(t, HIGH)] = max(0.0, bat.e0 - bat.max_) + cost[col(t, LOW)] = econ.reserve_penalty + cost[col(t, HIGH)] = econ.reserve_penalty + if s > 0: + terms = [(col(t, PC), 1.0), (col(t, EX), 1.0), (col(t, CU), 1.0)] + terms += [(layout.dev(t, j), 1.0) for j in range(layout.n_dev)] + rows.add(terms, s, s) + if bat is not None and t < econ.first_until and s > 0: + excess = max(0.0, s - bat.max_charge) + upper[col(t, FIRST)] = s + cost[col(t, FIRST)] = dt * econ.buffer_penalty + others = [(col(t, EX), 1.0), (col(t, CU), 1.0), (col(t, FIRST), -1.0)] + others += [(layout.dev(t, j), 1.0) for j in range(layout.n_dev)] + rows.add(others, -INF, excess) + if d > 0: + rows.add([(col(t, GL), 1.0), (col(t, BL), 1.0)], d, d) + if bat is None: + continue + if upper[col(t, GC)] > 0 and upper[col(t, PC)] > 0: + rows.add([(col(t, PC), 1.0), (col(t, GC), 1.0)], -INF, bat.max_charge) + dyn = [ + (col(t, SOC), 1.0), + (col(t, PC), -dt * bat.eta_c), + (col(t, GC), -dt * bat.eta_c), + (col(t, BL), dt / bat.eta_d), + ] + if t == 0: + rows.add(dyn, bat.e0, bat.e0) + else: + rows.add([*dyn, (col(t - 1, SOC), -1.0)], 0.0, 0.0) + if bat.e0 < bat.reserve: + rows.add([(col(t, SOC), 1.0), (col(t, LOW), 1.0)], bat.reserve, INF) + if bat.e0 > bat.max_: + rows.add([(col(t, SOC), 1.0), (col(t, HIGH), -1.0)], -INF, bat.max_) + for until, budget_wh in econ.device_budget: + terms = [(layout.dev(t, j), dt) for t in range(until + 1) for j in range(layout.n_dev)] + rows.add(terms, -INF, budget_wh / KW) + if bat is not None: + cost[layout.var(n - 1, SOC)] -= econ.terminal_value + for k, goal in enumerate(inputs.goals): + slot = econ.goal_slots[k] + target = inputs.battery.model.soc_to_wh(goal.soc_pct) / KW if inputs.battery else 0.0 + g = layout.goal(k) + if slot is None: + continue + upper[g] = target + cost[g] = econ.goal_penalty[k] + rows.add([(layout.var(slot, SOC), 1.0), (g, 1.0)], target, INF) + problem = LinearProblem( + cost=cost, + col_lower=lower, + col_upper=upper, + row_lower=np.array(rows.lower, dtype=np.float64), + row_upper=np.array(rows.upper, dtype=np.float64), + a_start=np.array(rows.start, dtype=np.int64), + a_index=np.array(rows.index, dtype=np.int64), + a_value=np.array(rows.value, dtype=np.float64), + ) + return problem, layout + + +def schedule_from_vector( + inputs: PlannerInputs, layout: Layout, x: Sequence[float] | FloatArray +) -> Schedule: + """The LP solution as a :class:`Schedule` (W, Wh), tiny negatives clipped to 0.""" + n = layout.n + + def series(kind: int, scale: float = KW) -> tuple[float, ...]: + return tuple(max(0.0, float(x[layout.var(t, kind)])) * scale for t in range(n)) + + soc = series(SOC) if inputs.battery is not None else (0.0,) * n + devices = tuple( + tuple(max(0.0, float(x[layout.dev(t, j)])) * KW for t in range(n)) + for j in range(layout.n_dev) + ) + return Schedule( + grid_load_w=series(GL), + battery_load_w=series(BL), + pv_charge_w=series(PC), + grid_charge_w=series(GC), + export_w=series(EX), + curtail_w=series(CU), + soc_wh=soc, + devices_w=devices, + ) + + +def goal_shortfall_wh(inputs: PlannerInputs, econ: Economics, schedule: Schedule) -> list[float]: + """Per goal: Wh the planned SoC misses the target by (0 = met; outside the grid: 0).""" + out: list[float] = [] + battery = inputs.battery + for goal, slot in zip(inputs.goals, econ.goal_slots, strict=True): + if battery is None or slot is None: + out.append(0.0) + continue + target = battery.model.soc_to_wh(goal.soc_pct) + out.append(max(0.0, target - schedule.soc_wh[slot])) + return out + + +def vector_from_schedule( + inputs: PlannerInputs, layout: Layout, econ: Economics, schedule: Schedule +) -> FloatArray: + """The LP column vector of a schedule, slacks included (for costing and warm starts).""" + x = np.zeros(layout.n_vars) + bat = _battery_kwh(inputs) + for t in range(layout.n): + x[layout.var(t, GL)] = schedule.grid_load_w[t] / KW + x[layout.var(t, BL)] = schedule.battery_load_w[t] / KW + x[layout.var(t, PC)] = schedule.pv_charge_w[t] / KW + x[layout.var(t, GC)] = schedule.grid_charge_w[t] / KW + x[layout.var(t, EX)] = schedule.export_w[t] / KW + x[layout.var(t, CU)] = schedule.curtail_w[t] / KW + e = schedule.soc_wh[t] / KW + x[layout.var(t, SOC)] = e + if bat is not None: + if t < econ.first_until: + others = ( + schedule.export_w[t] + schedule.curtail_w[t] + schedule.device_total_w(t) + ) / KW + excess = max(0.0, econ.surplus_w[t] / KW - bat.max_charge) + x[layout.var(t, FIRST)] = max(0.0, others - excess) + x[layout.var(t, LOW)] = max(0.0, bat.reserve - e) if bat.e0 < bat.reserve else 0.0 + x[layout.var(t, HIGH)] = max(0.0, e - bat.max_) if bat.e0 > bat.max_ else 0.0 + for j in range(layout.n_dev): + x[layout.dev(t, j)] = schedule.devices_w[j][t] / KW + for k, short in enumerate(goal_shortfall_wh(inputs, econ, schedule)): + x[layout.goal(k)] = short / KW + return x + + +def objective(inputs: PlannerInputs, schedule: Schedule, econ: Economics | None = None) -> float: + """The LP's objective of any schedule: the one cost function for LP and heuristic.""" + econ = econ or economics(inputs) + problem, layout = build_problem(inputs, econ) + return float(problem.cost @ vector_from_schedule(inputs, layout, econ, schedule)) + + +def violations( # noqa: PLR0912, PLR0915 - one check per constraint family + inputs: PlannerInputs, schedule: Schedule, econ: Economics | None = None +) -> list[str]: + """Constraint violations of a schedule beyond rounding (empty = feasible).""" + econ = econ or economics(inputs) + found: list[str] = [] + bat = inputs.battery + prev = None if bat is None else bat.soc_wh + dt = inputs.dt_h + for t in range(schedule.n): + flows = ( + schedule.grid_load_w[t], + schedule.battery_load_w[t], + schedule.pv_charge_w[t], + schedule.grid_charge_w[t], + schedule.export_w[t], + schedule.curtail_w[t], + *(d[t] for d in schedule.devices_w), + ) + if any(v < -BALANCE_TOL_W for v in flows): + found.append(f"negative flow at {t}") + left = inputs.pv_p50[t] + schedule.import_w(t) + schedule.battery_load_w[t] + right = ( + inputs.load_p50[t] + + schedule.device_total_w(t) + + schedule.charge_w(t) + + schedule.export_w[t] + + schedule.curtail_w[t] + ) + if abs(left - right) > BALANCE_TOL_W: + found.append(f"balance at {t}: {left:.1f} != {right:.1f}") + if schedule.device_total_w(t) > econ.surplus_w[t] + BALANCE_TOL_W: + found.append(f"devices above the PV surplus at {t}") + # The flow split (review m6): grid and battery serve only the deficit, the surplus + # side takes only PV. + surplus_side = ( + schedule.pv_charge_w[t] + + schedule.export_w[t] + + schedule.curtail_w[t] + + schedule.device_total_w(t) + ) + if abs(surplus_side - econ.surplus_w[t]) > BALANCE_TOL_W: + found.append(f"surplus split at {t}") + deficit_side = schedule.grid_load_w[t] + schedule.battery_load_w[t] + if abs(deficit_side - econ.deficit_w[t]) > BALANCE_TOL_W: + found.append(f"deficit split at {t}") + if ( + inputs.import_limit_w is not None + and schedule.import_w(t) > max(inputs.import_limit_w, econ.deficit_w[t]) + BALANCE_TOL_W + ): + found.append(f"import limit at {t}") + if schedule.grid_charge_w[t] > inputs.grid_charge_at(t) + BALANCE_TOL_W: + found.append(f"grid charging not allowed at {t}") + if ( + inputs.export_limit_w is not None + and schedule.export_w[t] > inputs.export_limit_w + BALANCE_TOL_W + ): + found.append(f"export limit at {t}") + for j, device in enumerate(inputs.devices): + limit = device.max_w if device.allowed[t] else 0.0 + if schedule.devices_w[j][t] > limit + BALANCE_TOL_W: + found.append(f"device {device.device_id} above its limit at {t}") + if bat is None or prev is None: + if schedule.charge_w(t) > BALANCE_TOL_W or schedule.battery_load_w[t] > BALANCE_TOL_W: + found.append(f"battery flow without a battery at {t}") + continue + if schedule.charge_w(t) > bat.max_charge_w + BALANCE_TOL_W: + found.append(f"charge limit at {t}") + if schedule.battery_load_w[t] > bat.max_discharge_w + BALANCE_TOL_W: + found.append(f"discharge limit at {t}") + model = bat.model + expected = prev + dt * ( + model.charge_efficiency * schedule.charge_w(t) + - schedule.battery_load_w[t] / model.discharge_efficiency + ) + e = schedule.soc_wh[t] + if abs(expected - e) > SOC_TOL_WH: + found.append(f"soc dynamics at {t}") + floor = min(bat.reserve_wh, bat.soc_wh) + ceiling = max(bat.max_wh, bat.soc_wh) + if e < floor - SOC_TOL_WH or e > ceiling + SOC_TOL_WH: + found.append(f"soc bounds at {t}: {e:.0f} Wh") + prev = e + for slot, budget_wh in econ.device_budget: + used = sum(schedule.device_total_w(t) for t in range(slot + 1)) * dt + if used > budget_wh + SOC_TOL_WH: + found.append(f"device budget before slot {slot}: {used:.0f} > {budget_wh:.0f} Wh") + return found + + +# --- solver backend ---------------------------------------------------------------------------- + +SolveStatus = Literal["optimal", "time_limit", "infeasible", "error"] + + +@dataclass(frozen=True, slots=True) +class SolverResult: + status: SolveStatus + x: FloatArray | None + """Primal solution when one is feasible (``None`` otherwise).""" + objective: float | None + solve_time_s: float + iterations: int = 0 + mip_gap: float | None = None + detail: str = "" + + +class SolverBackend(Protocol): + """What the planner needs from a solver (ADR-0003: swappable in tests).""" + + @property + def name(self) -> str: ... + + def solve( + self, + problem: LinearProblem, + *, + time_limit_s: float, + mip_gap: float, + warm_start: FloatArray | None = None, + ) -> SolverResult: ... + + +class HighsBackend: + """HiGHS through ``highspy`` (imported lazily: the heuristic works without it).""" + + name = "highs" + + def __init__(self, threads: int = 1) -> None: + self._threads = threads + + @staticmethod + def available() -> bool: + try: + import highspy # noqa: F401, PLC0415 + except ImportError: + return False + return True + + def solve( + self, + problem: LinearProblem, + *, + time_limit_s: float, + mip_gap: float, + warm_start: FloatArray | None = None, + ) -> SolverResult: + import highspy # noqa: PLC0415 - optional at import time + + started = time.perf_counter() + h = highspy.Highs() # type: ignore[no-untyped-call] + h.setOptionValue("output_flag", False) + h.setOptionValue("time_limit", max(0.01, float(time_limit_s))) + h.setOptionValue("mip_rel_gap", float(mip_gap)) + h.setOptionValue("threads", self._threads) + lp = highspy.HighsLp() + lp.num_col_ = problem.n_cols + lp.num_row_ = problem.n_rows + lp.col_cost_ = problem.cost + lp.col_lower_ = problem.col_lower + lp.col_upper_ = problem.col_upper + lp.row_lower_ = problem.row_lower + lp.row_upper_ = problem.row_upper + lp.a_matrix_.format_ = highspy.MatrixFormat.kRowwise + lp.a_matrix_.num_col_ = problem.n_cols + lp.a_matrix_.num_row_ = problem.n_rows + lp.a_matrix_.start_ = problem.a_start + lp.a_matrix_.index_ = problem.a_index + lp.a_matrix_.value_ = problem.a_value + if problem.integrality: + kinds = [highspy.HighsVarType.kContinuous] * problem.n_cols + for col in problem.integrality: + kinds[col] = highspy.HighsVarType.kInteger + lp.integrality_ = kinds + if h.passModel(lp) == highspy.HighsStatus.kError: + return SolverResult("error", None, None, time.perf_counter() - started, detail="model") + if warm_start is not None and len(warm_start) == problem.n_cols: + start = highspy.HighsSolution() + start.col_value = [float(v) for v in warm_start] + start.value_valid = True + h.setSolution(start) + h.run() + elapsed = time.perf_counter() - started + status = h.getModelStatus() + info = h.getInfo() + feasible = info.primal_solution_status == 2 # kSolutionStatusFeasible + x = np.array(h.getSolution().col_value, dtype=np.float64) if feasible else None + value = float(info.objective_function_value) if feasible else None + gap = float(info.mip_gap) if problem.integrality and feasible else None + iterations = int(info.simplex_iteration_count) + ms = highspy.HighsModelStatus + kind: SolveStatus + if status == ms.kOptimal: + kind = "optimal" + elif status in (ms.kTimeLimit, ms.kIterationLimit, ms.kInterrupt): + kind = "time_limit" + elif status in (ms.kInfeasible, ms.kUnboundedOrInfeasible, ms.kUnbounded): + kind = "infeasible" + else: + kind = "error" + return SolverResult( + kind, + x, + value, + elapsed, + iterations, + gap, + detail=h.modelStatusToString(status), + ) + + +__all__ = [ + "BL", + "BUFFER_KINDS", + "CU", + "EX", + "FIRST", + "GC", + "GL", + "HIGH", + "LOW", + "PC", + "SOC", + "TARGET_KINDS", + "Economics", + "HighsBackend", + "Layout", + "LinearProblem", + "Schedule", + "SolveStatus", + "SolverBackend", + "SolverResult", + "build_problem", + "economics", + "goal_shortfall_wh", + "objective", + "schedule_from_vector", + "vector_from_schedule", + "violations", +] diff --git a/suncore/planner/reasons.py b/suncore/planner/reasons.py new file mode 100644 index 0000000..b76e4f7 --- /dev/null +++ b/suncore/planner/reasons.py @@ -0,0 +1,64 @@ +# SPDX-License-Identifier: Apache-2.0 +"""Catalogue keys of the planner's explanations (``planner.*``). + +Every key here exists in ``frontend/src/lib/i18n/locales/{en,de}.json`` +(``scripts/check_reasons.py`` reads this module like the controller's). The risk model's two +keys (``planner.battery.morning_buffer``, ``planner.battery.evening_target``) are built by +``suncore.forecast.risk`` and reach the planner as finished :class:`Reason` objects. +""" + +from __future__ import annotations + +from typing import Final + +# --- plan level: who made the plan and on what ------------------------------------------ +SOLVER_OPTIMAL: Final = "planner.solver.optimal" +SOLVER_INCUMBENT: Final = "planner.solver.incumbent" +HEURISTIC_RULES: Final = "planner.heuristic.rules" +FALLBACK_TIMEOUT: Final = "planner.fallback.timeout" +FALLBACK_INFEASIBLE: Final = "planner.fallback.infeasible" +FALLBACK_ERROR: Final = "planner.fallback.error" +FALLBACK_SOLVER_UNAVAILABLE: Final = "planner.fallback.solver_unavailable" +FALLBACK_INVALID_SOLUTION: Final = "planner.fallback.invalid_solution" +FALLBACK_HEURISTIC_BETTER: Final = "planner.fallback.heuristic_better" +FALLBACK_NO_PRICES: Final = "planner.fallback.no_prices" +FALLBACK_SPOT_WITHOUT_FORMULA: Final = "planner.fallback.spot_without_formula" +INPUT_PRICES_PARTIAL: Final = "planner.input.prices_partial" +INPUT_NO_PV_FORECAST: Final = "planner.input.no_pv_forecast" +INPUT_NO_LOAD_FORECAST: Final = "planner.input.no_load_forecast" +INPUT_NO_BATTERY_SOC: Final = "planner.input.no_battery_soc" +INPUT_DEVICE_POWER_UNKNOWN: Final = "planner.input.device_power_unknown" + +# --- runtime level: why the planner runtime has no (fresh) plan (WP9) --------------------- +STATUS_WAITING: Final = "planner.status.waiting_for_inputs" +STATUS_WAITING_SOC: Final = "planner.status.waiting_for_soc" +STATUS_NO_INPUTS: Final = "planner.status.no_inputs" +STATUS_RUN_FAILED: Final = "planner.status.run_failed" +STATUS_RUN_TIMEOUT: Final = "planner.status.run_timeout" +STATUS_RUN_STUCK: Final = "planner.status.run_stuck" +STATUS_STALE: Final = "planner.status.stale" +STATUS_EXPIRED: Final = "planner.status.expired" +STATUS_NO_PLAN: Final = "planner.status.no_plan" + +# --- interval level ------------------------------------------------------------------- +GRID_CHARGE: Final = "planner.battery.grid_charge" +CHARGE_SURPLUS: Final = "planner.battery.charge_surplus" +DISCHARGE_HOUSE: Final = "planner.battery.discharge_house" +HOLD_FOR_EVENING: Final = "planner.battery.hold_for_evening" +HOLD_FOR_PRICE: Final = "planner.battery.hold_for_price" +AT_RESERVE: Final = "planner.battery.at_reserve" +BATTERY_FULL: Final = "planner.battery.full" +PREFER_FULL: Final = "planner.battery.prefer_full" +USER_TARGET: Final = "planner.battery.user_target" +TARGET_SHORTFALL: Final = "planner.battery.target_shortfall" +DEVICE_SURPLUS: Final = "planner.device.surplus" +DEVICE_THROTTLED: Final = "planner.device.throttled" +EXPORT_NEGATIVE_PRICE_AVOIDED: Final = "planner.export.negative_price_avoided" +EXPORT_LIMIT: Final = "planner.export.limit" +EXPORT_SURPLUS: Final = "planner.export.surplus" +GRID_IMPORT: Final = "planner.grid.import" +BALANCED: Final = "planner.interval.balanced" + +# Built by the risk model (WP7); listed so the planner names them in one place. +MORNING_BUFFER: Final = "planner.battery.morning_buffer" +EVENING_TARGET: Final = "planner.battery.evening_target" diff --git a/suncore/planner/run.py b/suncore/planner/run.py new file mode 100644 index 0000000..c4c483d --- /dev/null +++ b/suncore/planner/run.py @@ -0,0 +1,397 @@ +# SPDX-License-Identifier: Apache-2.0 +"""Entry point of the planner (Phase 4 WP8): inputs -> Plan v2, with the fallback chain. + +:func:`plan` is what the runtime (WP9) calls, in a worker thread, every 15 minutes and on +events. It never raises for a model or solver problem; the chain (ADR-0003) is: + +1. the heuristic schedule is always computed first (milliseconds) - it is the fallback and + the yardstick ("never worse than the heuristic"); +2. the LP is built and solved with HiGHS within the remaining ``budget_s`` and ``mip_gap``, + warm-started from the previous plan shifted onto the new grid (slots the previous plan + does not cover take the heuristic's flows; the start is repaired to be feasible); +3. ``optimal`` -> the solver's plan; ``time_limit`` with a feasible incumbent -> that + incumbent; anything else (time limit without a solution, infeasible, error, a solution + that fails the independent feasibility check, ``highspy`` missing) -> the heuristic with + a ``planner.fallback.*`` reason. An incumbent costlier than the heuristic is replaced by + it (``planner.fallback.heuristic_better``). "Relaxed targets" are built in: every target + is soft, so infeasibility can only come from a broken model. + +The plan's bands follow ADR-0013: limits, not set-points. ``BatteryBand`` carries the SoC +corridor ``[effective reserve, max SoC]``, the power corridor (``min_power_w = 0`` where the +plan holds the battery: ``discharge_lock``), ``grid_charge_max_w`` only where grid charging is +planned (and therefore allowed by the policy and the spread rule), ``priority_until_soc_pct`` += the morning buffer until the plan reaches it, and ``charge_from_surplus = False`` only where +the plan gives devices the surplus while no battery target binds. ``DeviceBand``: devices +planned on surplus are ``prefer_on``; while a battery target binds they are throttled to the +planned power or switched off (``allowed = False``). +""" + +from __future__ import annotations + +import time +from dataclasses import dataclass +from datetime import datetime +from typing import Final + +import numpy as np + +from suncore.core.control import ( + BandPreference, + BatteryBand, + DeviceBand, + IntervalFlows, + IntervalPrices, + Plan, + PlanInterval, + PlanSource, + SolverStats, +) +from suncore.core.decisions import Reason +from suncore.planner import reasons as rk +from suncore.planner.explain import EPS_W, SlotFacts, interval_reasons, slot_facts +from suncore.planner.heuristic import heuristic_schedule +from suncore.planner.inputs import DEFAULT_BUDGET_S, DEFAULT_MIP_GAP, PlannerInputs +from suncore.planner.model import ( + Economics, + FloatArray, + HighsBackend, + Layout, + Schedule, + SolverBackend, + SolverResult, + build_problem, + economics, + objective, + schedule_from_vector, + vector_from_schedule, + violations, +) + +OBJECTIVE_TOL: Final = 1e-6 +MIN_SOLVER_TIME_S: Final = 0.05 + + +@dataclass(frozen=True, slots=True) +class PlannerRun: + """A finished run: the plan and what produced it (tests and the benchmark read it).""" + + plan: Plan + schedule: Schedule + source: PlanSource + objective: float + heuristic_objective: float + solver: SolverResult | None + n_vars: int + n_rows: int + + +def plan( + inputs: PlannerInputs, + budget_s: float = DEFAULT_BUDGET_S, + mip_gap: float = DEFAULT_MIP_GAP, + warm_start: Plan | None = None, + backend: SolverBackend | None = None, +) -> Plan: + """The Plan v2 for ``inputs`` (module doc); ``warm_start`` defaults to ``inputs.previous``.""" + return run( + inputs, budget_s=budget_s, mip_gap=mip_gap, warm_start=warm_start, backend=backend + ).plan + + +def run( # noqa: PLR0912, PLR0915 - the fallback chain, one branch per outcome + inputs: PlannerInputs, + *, + budget_s: float = DEFAULT_BUDGET_S, + mip_gap: float = DEFAULT_MIP_GAP, + warm_start: Plan | None = None, + backend: SolverBackend | None = None, +) -> PlannerRun: + """Plan with the solver, fall back to the heuristic (module doc).""" + started = time.perf_counter() + econ = economics(inputs) + heuristic = heuristic_schedule(inputs, econ) + heuristic_cost = objective(inputs, heuristic, econ) + solver = backend or HighsBackend() + previous = warm_start if warm_start is not None else inputs.previous + result: SolverResult | None = None + fallback: Reason | None = None + chosen: Schedule | None = None + chosen_cost = heuristic_cost + n_vars = n_rows = 0 + n_binaries = 0 + try: + problem, layout = build_problem(inputs, econ) + n_vars, n_rows, n_binaries = problem.n_cols, problem.n_rows, len(problem.integrality) + warm = warm_vector(inputs, econ, layout, heuristic, previous) + remaining = max(MIN_SOLVER_TIME_S, budget_s - (time.perf_counter() - started)) + result = solver.solve(problem, time_limit_s=remaining, mip_gap=mip_gap, warm_start=warm) + except ImportError: + fallback = Reason(key=rk.FALLBACK_SOLVER_UNAVAILABLE) + except Exception as exc: + fallback = Reason(key=rk.FALLBACK_ERROR, args={"error": type(exc).__name__}) + if result is not None and fallback is None: + if result.x is not None and result.status in ("optimal", "time_limit"): + candidate = schedule_from_vector(inputs, layout, result.x) + broken = violations(inputs, candidate, econ) + if broken: + fallback = Reason( + key=rk.FALLBACK_INVALID_SOLUTION, args={"violations": len(broken)} + ) + else: + cost = objective(inputs, candidate, econ) + tolerance = OBJECTIVE_TOL * max(1.0, abs(heuristic_cost)) + if cost > heuristic_cost + tolerance: + fallback = Reason( + key=rk.FALLBACK_HEURISTIC_BETTER, + args={"status": result.status}, + ) + else: + chosen, chosen_cost = candidate, cost + elif result.status == "time_limit": + fallback = Reason(key=rk.FALLBACK_TIMEOUT, args={"budget_s": round(budget_s, 2)}) + elif result.status == "infeasible": + fallback = Reason(key=rk.FALLBACK_INFEASIBLE) + else: + fallback = Reason(key=rk.FALLBACK_ERROR, args={"error": result.detail or "solver"}) + elapsed = time.perf_counter() - started + plan_reasons = list(inputs.reasons) + source: PlanSource + if chosen is not None and result is not None: + source = "solver" + key = rk.SOLVER_OPTIMAL if result.status == "optimal" else rk.SOLVER_INCUMBENT + plan_reasons.insert(0, Reason(key=key, args={"solve_time_s": round(elapsed, 3)})) + status: str = result.status + schedule = chosen + else: + source = "heuristic" + plan_reasons.insert(0, Reason(key=rk.HEURISTIC_RULES)) + if fallback is not None: + plan_reasons.insert(0, fallback) + status = "heuristic" + schedule = heuristic + chosen_cost = heuristic_cost + stats = SolverStats( + solve_time_s=round(elapsed, 4), + status=status, + objective=round(chosen_cost, 6), + n_vars=n_vars, + n_binaries=n_binaries, + mip_gap=None if result is None else result.mip_gap, + ) + assumptions = dict(inputs.assumptions) + assumptions["solver"] = getattr(solver, "name", "unknown") + if result is not None: + assumptions["solver_status"] = result.status + built = to_plan(inputs, econ, schedule, source=source, stats=stats, reasons=plan_reasons) + built = built.model_copy(update={"assumptions": assumptions}) + return PlannerRun( + plan=built, + schedule=schedule, + source=source, + objective=chosen_cost, + heuristic_objective=heuristic_cost, + solver=result, + n_vars=n_vars, + n_rows=n_rows, + ) + + +# --- warm start ------------------------------------------------------------------------------- + + +def _previous_battery_w(inputs: PlannerInputs, previous: Plan | None) -> dict[datetime, float]: + if previous is None: + return {} + wanted = set(inputs.starts) + out: dict[datetime, float] = {} + for interval in previous.intervals: + if interval.start in wanted and interval.expected is not None: + out[interval.start] = interval.expected.battery_w + return out + + +def follow( + inputs: PlannerInputs, + econ: Economics, + battery_w: list[float], + devices_w: list[list[float]], +) -> Schedule: + """A feasible schedule that follows the wanted battery and device powers as far as the + bounds allow (the warm start's repair: SoC re-simulated from the live SoC).""" + n, dt = inputs.n, inputs.dt_h + battery = inputs.battery + gl, bl, pc, gc, ex, cu, soc = ([0.0] * n for _ in range(7)) + dev = [[0.0] * n for _ in inputs.devices] + e = battery.soc_wh if battery else 0.0 + floor = min(battery.reserve_wh, e) if battery else 0.0 + ceiling = max(battery.max_wh, e) if battery else 0.0 + for t in range(n): + s, d = econ.surplus_w[t], econ.deficit_w[t] + rest = s + for j, device in enumerate(inputs.devices): + cap = device.max_w if device.allowed[t] else 0.0 + take = max(0.0, min(devices_w[j][t], cap, rest)) + dev[j][t] = take + rest -= take + if battery is not None: + eta_c, eta_d = battery.model.charge_efficiency, battery.model.discharge_efficiency + want = battery_w[t] + room = max(0.0, ceiling - e) / (dt * eta_c) + if want > 0: + pc[t] = max(0.0, min(want, rest, battery.max_charge_w, room)) + rest -= pc[t] + gc[t] = max( + 0.0, + min( + want - pc[t], + inputs.grid_charge_at(t), + battery.max_charge_w - pc[t], + room - pc[t], + ), + ) + elif want < 0: + avail = max(0.0, e - floor) * eta_d / dt + bl[t] = max(0.0, min(-want, d, battery.max_discharge_w, avail)) + e = e + dt * (eta_c * (pc[t] + gc[t]) - bl[t] / eta_d) + soc[t] = e + if rest > 0: + cap_e = rest if inputs.export_limit_w is None else min(rest, inputs.export_limit_w) + if inputs.export_price[t] < 0 or inputs.discouraged(t): + cap_e = 0.0 + ex[t] = cap_e + cu[t] = rest - cap_e + gl[t] = max(0.0, d - bl[t]) + return Schedule( + grid_load_w=tuple(gl), + battery_load_w=tuple(bl), + pv_charge_w=tuple(pc), + grid_charge_w=tuple(gc), + export_w=tuple(ex), + curtail_w=tuple(cu), + soc_wh=tuple(soc), + devices_w=tuple(tuple(x) for x in dev), + ) + + +def warm_vector( + inputs: PlannerInputs, + econ: Economics, + layout: Layout, + heuristic: Schedule, + previous: Plan | None, +) -> FloatArray: + """The previous plan shifted onto this grid (heuristic where it has no slot), repaired.""" + shifted = _previous_battery_w(inputs, previous) + battery_w = [ + shifted.get(start, heuristic.battery_w(t)) for t, start in enumerate(inputs.starts) + ] + devices = [list(d) for d in heuristic.devices_w] + start = follow(inputs, econ, battery_w, devices) + x = vector_from_schedule(inputs, layout, econ, start) + return np.asarray(x, dtype=np.float64) + + +# --- plan ------------------------------------------------------------------------------------- + + +def _w(value: float) -> float: + return round(max(0.0, value), 1) + + +def _device_band(power_w: float, cap_w: float, fact: SlotFacts) -> DeviceBand: + if power_w > EPS_W: + throttled = fact.tight and power_w < cap_w - EPS_W + return DeviceBand( + allowed=True, + preference=BandPreference.PREFER_ON, + max_power_w=_w(power_w) if throttled else None, + ) + if fact.tight: + return DeviceBand(allowed=False, preference=BandPreference.PREFER_OFF, max_power_w=0.0) + return DeviceBand() + + +def _battery_band( + inputs: PlannerInputs, schedule: Schedule, fact: SlotFacts, t: int +) -> BatteryBand | None: + battery = inputs.battery + if battery is None: + # No planner battery: no band, the controller keeps the goal rules (cs review m6). + return None + grid = schedule.grid_charge_w[t] + devices = schedule.device_total_w(t) + return BatteryBand( + min_power_w=0.0 if fact.discharge_lock else -battery.max_discharge_w, + max_power_w=battery.max_charge_w, + min_soc_pct=round(battery.reserve_pct, 2), + max_soc_pct=round(max(battery.reserve_pct, battery.max_soc_pct), 2), + charge_from_surplus=not (devices > EPS_W and not fact.tight), + priority_until_soc_pct=None + if fact.priority_until_pct is None + else round(min(100.0, fact.priority_until_pct), 1), + grid_charge_max_w=_w(grid) if grid > EPS_W else None, + discharge_lock=fact.discharge_lock, + ) + + +def to_plan( + inputs: PlannerInputs, + econ: Economics, + schedule: Schedule, + *, + source: PlanSource, + stats: SolverStats, + reasons: list[Reason], +) -> Plan: + """The Plan v2 of a schedule: bands, expected flows, prices and reasons per interval.""" + facts = slot_facts(inputs, econ, schedule) + battery = inputs.battery + intervals: list[PlanInterval] = [] + for t, start in enumerate(inputs.starts): + fact = facts[t] + p50 = _w(inputs.pv_p50[t]) + expected = IntervalFlows( + pv_p10_w=min(p50, _w(inputs.pv_p10[t])), + pv_p50_w=p50, + pv_p90_w=max(p50, _w(inputs.pv_p90[t])), + load_w=_w(inputs.load_p50[t]), + import_w=_w(schedule.import_w(t)), + export_w=_w(schedule.export_w[t]), + battery_w=round(schedule.battery_w(t), 1), + soc_pct=None + if battery is None + else round(min(100.0, max(0.0, battery.model.wh_to_soc(schedule.soc_wh[t]))), 2), + devices_w=_w(schedule.device_total_w(t)), + curtail_w=_w(schedule.curtail_w[t]), + ) + devices = { + device.device_id: _device_band(schedule.devices_w[j][t], device.max_w, fact) + for j, device in enumerate(inputs.devices) + } + intervals.append( + PlanInterval( + start=start, + end=start + inputs.step, + devices=devices, + battery=_battery_band(inputs, schedule, fact, t), + grid_import_limit_w=inputs.import_limit_w, + expected=expected, + prices=IntervalPrices( + import_price=round(inputs.import_price[t], 6), + export_price=round(inputs.export_price[t], 6), + estimated=inputs.price_estimated(t), + ), + reasons=interval_reasons(inputs, econ, schedule, facts, t), + ) + ) + return Plan( + created_at=inputs.now, + intervals=tuple(intervals), + reasons=tuple(reasons), + assumptions=dict(inputs.assumptions), + source=source, + stats=stats, + ) + + +__all__ = ["PlannerRun", "follow", "plan", "run", "to_plan", "warm_vector"] diff --git a/suncore/planner/views.py b/suncore/planner/views.py new file mode 100644 index 0000000..9fb7f65 --- /dev/null +++ b/suncore/planner/views.py @@ -0,0 +1,102 @@ +# SPDX-License-Identifier: Apache-2.0 +"""Read models of the planner runtime (Phase 4 WP9): what ``/api/v1/plan*`` and the live feed serve. + +Pure data (``core`` only): the runtime (``suncore.app.planning``) fills them, the API serves them +and the OpenAPI document is generated from them. +""" + +from __future__ import annotations + +from typing import Literal + +from pydantic import AwareDatetime, BaseModel, ConfigDict, Field + +from suncore.core.control import Plan, PlanSource +from suncore.core.decisions import Reason + +Trigger = Literal[ + "start", "schedule", "prices", "forecast", "deviation", "config", "override", "manual" +] +"""Why a run started: the first run, the 15-minute cadence, or an event.""" +RunOutcome = Literal["ok", "failed", "skipped"] +"""``skipped``: nothing to plan with yet (or an earlier run still hangs); ``failed``: the run +raised or timed out - the last good plan stays.""" + + +class _View(BaseModel): + model_config = ConfigDict(frozen=True, extra="forbid") + + +class PlanView(_View): + """``GET /api/v1/plan``: the current plan and whether the controller follows it. + + ``plan`` is :meth:`Plan.default` (no intervals, ``source = "default"``) until the first + plan exists. ``in_use`` is ``False`` when the plan is stale or has run out: the controller + then runs on Phase 3 rules only (``fallback`` says why, as a catalogue reason). + """ + + generated_at: AwareDatetime + plan: Plan + stale: bool + """Older than the stale limit (2 h): shown, but not handed to the controller.""" + expired: bool + """Every interval lies in the past.""" + in_use: bool + fallback: Reason | None = None + + +class PlanSummary(_View): + """The live feed's ``plan`` message and the status' short form: no intervals.""" + + created_at: AwareDatetime | None + source: PlanSource + status: str | None + """Solver status slug (``optimal``, ``time_limit``, ``heuristic`` ...).""" + solve_time_s: float | None + intervals: int + horizon_end: AwareDatetime | None + stale: bool + in_use: bool + reasons: list[Reason] = Field(default_factory=list) + """Plan-level reasons (who made the plan, input gaps).""" + + +class PlanStatusView(_View): + """``GET /api/v1/plan/status``: the scheduler's bookkeeping.""" + + generated_at: AwareDatetime + running: bool + last_trigger: Trigger | None + last_started_at: AwareDatetime | None + last_finished_at: AwareDatetime | None + last_duration_s: float | None + last_outcome: RunOutcome | None + last_ok_at: AwareDatetime | None + consecutive_failures: int + reason: Reason | None = None + """Why the last run did not produce a plan (``outcome`` skipped or failed).""" + next_scheduled_at: AwareDatetime | None + """The next quarter-hour run (cadence).""" + pending: list[Trigger] = Field(default_factory=list) + """Events waiting for the debounce.""" + earliest_event_run_at: AwareDatetime | None + """When a pending event may start a run (debounce).""" + plan: PlanSummary + + +class ReplanAck(_View): + """``POST /api/v1/plan/replan`` (202): the request is queued, not done.""" + + accepted: bool = True + earliest_start_at: AwareDatetime + """Start of the run: now, or the end of the debounce interval.""" + + +__all__ = [ + "PlanStatusView", + "PlanSummary", + "PlanView", + "ReplanAck", + "RunOutcome", + "Trigger", +] diff --git a/suncore/sim/demo_devices.py b/suncore/sim/demo_devices.py index c7add45..6087a74 100644 --- a/suncore/sim/demo_devices.py +++ b/suncore/sim/demo_devices.py @@ -140,10 +140,16 @@ def _gauss(x: float, centre: float, sigma: float) -> float: return math.exp(-0.5 * ((x - centre) / sigma) ** 2) -def sim_price(when: datetime) -> float: - """Synthetic dynamic price in EUR/kWh for the 15 min slot containing ``when``.""" +def sim_price(when: datetime, profile: str = "default") -> float: + """Synthetic dynamic price in EUR/kWh for the 15 min slot containing ``when``. + + ``profile`` ``negative_midday`` deepens the midday dip so that the price is negative + between about 11:30 and 14:30 (the minimum is -0.08 EUR/kWh at 13:00). + """ hour = when.hour + (when.minute // 15) * 0.25 - price = 0.30 + 0.12 * _gauss(hour, 19.0, 2.0) - 0.10 * _gauss(hour, 13.0, 2.5) + dip = 0.38 if profile == "negative_midday" else 0.10 + sigma = 2.0 if profile == "negative_midday" else 2.5 + price = 0.30 + 0.12 * _gauss(hour, 19.0, 2.0) - dip * _gauss(hour, 13.0, sigma) if hour < 5: price -= 0.04 return round(price, 3) @@ -353,7 +359,7 @@ def entities(self) -> list[DemoEntity]: [ DemoEntity( PRICE_ID, - f"{sim_price(state.time):.3f}", + f"{sim_price(state.time, self.scenario.prices.profile):.3f}", { "friendly_name": "Sim electricity price", "unit_of_measurement": f"{PRICE_CURRENCY}/kWh", diff --git a/suncore/sim/fake_ha.py b/suncore/sim/fake_ha.py index ed38f7c..229ddd4 100644 --- a/suncore/sim/fake_ha.py +++ b/suncore/sim/fake_ha.py @@ -485,10 +485,7 @@ async def call_action_response( raise ActionRateLimitedError(key, self._action_limiter.retry_after(key)) now = self._house_state.time if self._house_state is not None else self._clock() if (domain, service) == ("tibber", "get_prices"): - start = now.replace(minute=(now.minute // 15) * 15, second=0, microsecond=0) - slots = [start + timedelta(minutes=15 * i) for i in range(96)] - prices = [{"start_time": t.isoformat(), "price": sim_price(t)} for t in slots] - return {"prices": {"Home": prices}} + return {"prices": {"Home": self._tibber_prices(now, data)}} if (domain, service) == ("solcast_solar", "query_forecast_data"): slots_data: list[Any] = [] for entity_id in (FORECAST_TODAY_ID, FORECAST_TOMORROW_ID): @@ -505,6 +502,37 @@ async def call_action_response( return {entity_id: {"workday": demo.is_workday(asked)}} raise CommandError("not_found", f"Service {domain}.{service} not found.") + def _tibber_prices(self, now: datetime, data: Mapping[str, Any] | None) -> list[dict[str, Any]]: + """``tibber.get_prices`` like core's ``services.py`` (re-read 2026-10-16): 15-minute + slots ``start <= t < end``, ``start``/``end`` default to local today; tomorrow only + exists after ``scenario.prices.tomorrow_after_hour`` local time.""" + + def parse(name: str) -> datetime | None: + raw = (data or {}).get(name) + if not isinstance(raw, str): + return None + parsed = datetime.fromisoformat(raw) + return parsed if parsed.tzinfo is not None else parsed.replace(tzinfo=now.tzinfo) + + midnight = now.replace(hour=0, minute=0, second=0, microsecond=0) + start = parse("start") or midnight + end = parse("end") or start + timedelta(days=1) + if start >= end: + end = start + timedelta(days=1) + params = self._scenario.prices + published_until = midnight + timedelta( + days=2 if now.hour >= params.tomorrow_after_hour else 1 + ) + end = min(end, published_until) + slots: list[dict[str, Any]] = [] + t = max(start, midnight) + t = t.replace(minute=(t.minute // 15) * 15, second=0, microsecond=0) + while t < end: + if t >= start: + slots.append({"start_time": t.isoformat(), "price": sim_price(t, params.profile)}) + t += timedelta(minutes=15) + return slots + def entity_metas(self) -> list[EntityMeta]: """Registry entries joined with the published states (what detection ranks).""" self._require_connected() diff --git a/suncore/sim/planner_scenarios.py b/suncore/sim/planner_scenarios.py new file mode 100644 index 0000000..a039590 --- /dev/null +++ b/suncore/sim/planner_scenarios.py @@ -0,0 +1,404 @@ +# SPDX-License-Identifier: Apache-2.0 +"""Planner scenarios of the virtual house (Phase 4 WP8): inputs for tests and the benchmark. + +Each scenario is a deterministic 48 h situation - PV forecast (P10/P50/P90), base load, prices, +battery, devices - turned into :class:`~suncore.planner.inputs.PlannerInputs` the way the +runtime will (WP9): through :func:`~suncore.planner.inputs.build_inputs`, with the morning +buffer and the evening target from the real risk model (``suncore.forecast.risk``, source +quantiles because the scenarios have no learnt history). + +Shapes are reasoned, not measured: PV is a sine-shaped day per array (east and west arrays +peak 1.5 h apart), P10 = 0.6 x P50 and P90 = min(1.15 x P50, clear sky) unless a scenario +says otherwise; the base load is 300 W with a morning and an evening bump; "Tibber-like" +prices are 0.27/kWh with a morning and an evening peak and a midday dip. +""" + +from __future__ import annotations + +import math +from collections.abc import Callable, Sequence +from dataclasses import dataclass, field +from datetime import date, datetime, timedelta +from typing import Final +from zoneinfo import ZoneInfo + +from suncore.core.battery import ( + BatteryModel, + BatterySettings, + BatteryStrategy, + GridChargePolicy, + RiskLevel, +) +from suncore.core.config import GoalsConfig +from suncore.core.devices import ( + ComfortBand, + DeviceConfig, + DeviceKind, + PowerModel, + PowerModelKind, + SetpointControl, +) +from suncore.core.series import ( + PLANNING_STEP, + PriceSeries, + QuantileSeries, + SeriesUnit, + TimeSeries, + planning_grid, +) +from suncore.core.site import EntityRef +from suncore.core.tariff import WeeklySchedule +from suncore.forecast.risk import ( + RiskWindow, + day_windows, + evening_target_pct, + morning_buffer_pct, +) +from suncore.planner.inputs import PLANNER_HORIZON, PlannerInputs, build_inputs + +TZ: Final = ZoneInfo("Europe/Berlin") +SUMMER: Final = date(2026, 6, 20) +WINTER: Final = date(2026, 12, 8) +EEG_UP_TO_10_KWP: Final = 0.0786 +EEG_ABOVE_10_KWP: Final = 0.068 +"""EEG feed-in rates (currency/kWh) of the maintainer's tiers; reasoned example values, the +maintainer enters his own (plan §6 question 8).""" + + +def blended_eeg(kwp: float) -> float: + """Tiered EEG rate blended by kWp share (like ``core.tariff.blended_export_price``).""" + low = min(kwp, 10.0) + return (low * EEG_UP_TO_10_KWP + max(0.0, kwp - 10.0) * EEG_ABOVE_10_KWP) / kwp + + +def _hours(at: datetime) -> float: + local = at.astimezone(TZ) + return local.hour + local.minute / 60 + + +def _bell(hour: float, rise: float, set_: float) -> float: + if not rise < hour < set_: + return 0.0 + return float(math.sin(math.pi * (hour - rise) / (set_ - rise)) ** 1.3) + + +def pv_clear_w(at: datetime, kwp: float, *, summer: bool = True, east_west: bool = True) -> float: + """Clear-sky PV (W) at the slot's middle; ``kwp`` split evenly east/west.""" + hour = _hours(at + PLANNING_STEP / 2) + rise, set_ = (5.2, 21.6) if summer else (8.2, 16.4) + peak = kwp * 1000 * (0.78 if summer else 0.35) + if not east_west: + return peak * _bell(hour, rise, set_) + shift = 1.5 if summer else 0.6 + east = _bell(hour, rise, set_ - 2 * shift) + west = _bell(hour, rise + 2 * shift, set_) + return peak * 0.62 * (east + west) + + +def base_load_w(at: datetime, base: float = 300.0) -> float: + hour = _hours(at) + morning = 350 * math.exp(-(((hour - 7.5) / 1.0) ** 2)) + evening = 650 * math.exp(-(((hour - 19.5) / 1.8) ** 2)) + return base + morning + evening + + +def tibber_price(at: datetime) -> float: + hour = _hours(at) + morning = 0.05 * math.exp(-(((hour - 8.0) / 1.5) ** 2)) + evening = 0.09 * math.exp(-(((hour - 19.0) / 2.0) ** 2)) + midday = 0.07 * math.exp(-(((hour - 13.5) / 2.5) ** 2)) + night = 0.03 * math.exp(-(((hour - 3.0) / 2.0) ** 2)) + return round(0.27 + morning + evening - midday - night, 4) + + +def series( + starts: Sequence[datetime], values: Sequence[float | None], unit: SeriesUnit +) -> TimeSeries: + return TimeSeries(start=starts[0], step=PLANNING_STEP, values=tuple(values), unit=unit) + + +def quantiles( + starts: Sequence[datetime], + p50: Sequence[float], + low: float = 0.6, + high: float = 1.15, + cap: Sequence[float] | None = None, +) -> QuantileSeries: + upper = [ + v * high if cap is None else max(v, min(v * high, c)) + for v, c in zip(p50, cap or p50, strict=True) + ] + return QuantileSeries( + p10=series(starts, [v * low for v in p50], SeriesUnit.W), + p50=series(starts, list(p50), SeriesUnit.W), + p90=series(starts, upper, SeriesUnit.W), + ) + + +def prices( + starts: Sequence[datetime], + import_price: Sequence[float | None], + export_price: Sequence[float | None], + *, + includes: str = "all_in", +) -> PriceSeries: + return PriceSeries( + source_id="sim.tibber", + price_includes="all_in" if includes == "all_in" else "spot_only", + import_price=series(starts, import_price, SeriesUnit.PRICE), + export_price=series(starts, export_price, SeriesUnit.PRICE), + ) + + +def climate(device_id: str, nominal_w: float, value: float | None = None) -> DeviceConfig: + return DeviceConfig( + id=device_id, + template_id="lg.thinq_climate", + name=device_id, + kind=DeviceKind.CLIMATE, + entities={"climate": EntityRef(entity_id=f"climate.{device_id}")}, + power_model=PowerModel(kind=PowerModelKind.NOMINAL, nominal_w=nominal_w), + control=SetpointControl(kind="setpoint", role="climate", shift_max_c=2.0), + comfort=ComfortBand(min_c=20.0, max_c=26.0), + planner_value_per_kwh=value, + ) + + +@dataclass(frozen=True, slots=True) +class Situation: + """One scenario before it becomes planner inputs.""" + + now: datetime + kwp: float = 8.0 + summer: bool = True + day_factors: Sequence[float] = (1.0, 1.0, 1.0) + """Cloud factor per local day (today, tomorrow, the day after).""" + cloud: Callable[[datetime], float] | None = None + """Extra factor per slot (mixed clouds).""" + p10_share: float = 0.6 + load_base_w: float = 300.0 + import_price: Callable[[datetime], float | None] = tibber_price + export_price: Callable[[datetime], float | None] = lambda _at: 0.08 + capacity_wh: float = 10_000.0 + max_power_w: float = 5_000.0 + soc_pct: float = 30.0 + strategy: BatteryStrategy = BatteryStrategy.SELF_CONSUMPTION + risk: RiskLevel = RiskLevel.CAUTIOUS + grid_charge: GridChargePolicy = field(default_factory=GridChargePolicy) + goals: GoalsConfig = field(default_factory=GoalsConfig) + devices: Sequence[DeviceConfig] = () + export_limit_w: float | None = None + import_limit_w: float | None = None + price_includes: str = "all_in" + with_prices: bool = True + + +def battery_settings(s: Situation) -> BatterySettings: + return BatterySettings( + model=BatteryModel( + capacity_wh=s.capacity_wh, + max_charge_w=s.max_power_w, + max_discharge_w=s.max_power_w, + ), + strategy=s.strategy, + risk=s.risk, + grid_charge=s.grid_charge, + ) + + +def forecasts(s: Situation) -> tuple[list[datetime], QuantileSeries, QuantileSeries]: + grid = planning_grid(s.now, PLANNER_HORIZON) + starts = grid.starts() + first = s.now.astimezone(TZ).date() + clear, p50 = [], [] + for at in starts: + day = (at.astimezone(TZ).date() - first).days + factor = s.day_factors[min(day, len(s.day_factors) - 1)] + if s.cloud is not None: + factor *= s.cloud(at) + c = pv_clear_w(at, s.kwp, summer=s.summer) + clear.append(c) + p50.append(c * factor) + pv = quantiles(starts, p50, low=s.p10_share, cap=clear) + load = quantiles(starts, [base_load_w(at, s.load_base_w) for at in starts], 0.8, 1.3) + return starts, pv, load + + +def situation_inputs(s: Situation) -> PlannerInputs: + """The planner inputs of a situation, with the risk model's buffer and target.""" + starts, pv, load = forecasts(s) + settings = battery_settings(s) + assert settings.model is not None + windows = day_windows(s.now, pv, load, TZ) + target = s.goals.battery_target + evening = evening_target_pct( + settings.model, + settings, + windows, + user_target_pct=None if target is None else target.soc_pct, + ) + buffer = morning_buffer_pct(settings.model, settings, windows, evening.soc_pct) + price = ( + prices( + starts, + [s.import_price(at) for at in starts], + [s.export_price(at) for at in starts], + includes=s.price_includes, + ) + if s.with_prices + else None + ) + return build_inputs( + s.now, + tz=TZ, + load=load, + pv=pv, + prices=price, + battery=settings, + soc_pct=s.soc_pct, + goals=s.goals, + morning_buffer=buffer, + evening_target=evening, + evening_at=windows[RiskWindow.NIGHT].start, + devices=s.devices, + import_limit_w=s.import_limit_w, + export_limit_w=s.export_limit_w, + ) + + +def _at(day: date, hour: int, minute: int = 0) -> datetime: + return datetime(day.year, day.month, day.day, hour, minute, tzinfo=TZ) + + +def _clouds(at: datetime) -> float: + hour = _hours(at) + return 0.35 + 0.65 * abs(math.sin(1.7 * hour) * math.cos(0.45 * hour)) + + +def _negative_midday(at: datetime) -> float: + hour, day = _hours(at), at.astimezone(TZ).date() + if day == SUMMER and 12 <= hour < 15: + return -0.05 + return tibber_price(at) + + +def _rule_export(at: datetime) -> float: + price = _negative_midday(at) + return 0.0 if price < 0 else 0.08 + + +def _spike(at: datetime) -> float: + """0.30/kWh, but 1.50/kWh from 01:00 to 02:00 the night after the summer day.""" + local = at.astimezone(TZ) + after = local.date() == SUMMER + timedelta(days=1) + return 1.5 if after and 1 <= _hours(at) < 2 else 0.3 + + +def _night_cheap(at: datetime) -> float: + hour = _hours(at) + return 0.15 if 1 <= hour < 5 else 0.35 + + +DEVICES: Final = (climate("ac_living", 1000.0), climate("ac_office", 800.0)) + + +def situation(name: str) -> Situation: # noqa: PLR0911 - one scenario per branch + """The named scenario (see :data:`SCENARIOS`).""" + morning = _at(SUMMER, 6) + if name == "sunny_day": + return Situation(now=morning, devices=DEVICES) + if name == "mixed_clouds": + return Situation(now=morning, cloud=_clouds, devices=DEVICES) + if name == "two_poor_days": + return Situation( + now=_at(WINTER, 9), + summer=False, + day_factors=(0.25, 0.15, 0.15), + soc_pct=85.0, + devices=DEVICES, + import_price=lambda _at: 0.30, + ) + if name == "forecast_too_optimistic": + return Situation(now=morning, p10_share=0.25, devices=DEVICES, soc_pct=15.0) + if name == "negative_prices": + return Situation( + now=morning, + soc_pct=20.0, + capacity_wh=8_000.0, + import_price=_negative_midday, + export_price=_rule_export, + devices=DEVICES, + ) + if name == "price_spike": + return Situation(now=_at(SUMMER, 22), soc_pct=20.0, import_price=_spike) + if name == "grid_charge_price_level": + return Situation( + now=_at(WINTER, 22), + summer=False, + day_factors=(0.05, 0.05, 0.05), + soc_pct=20.0, + import_price=_night_cheap, + grid_charge=GridChargePolicy( + enabled=True, max_price=0.2, schedule=WeeklySchedule.daily("00:00", "06:00") + ), + ) + if name == "prefer_full": + return Situation( + now=morning, + strategy=BatteryStrategy.PREFER_FULL, + devices=(climate("ac_living", 1000.0, value=0.3),), + ) + if name == "reference_house": + return reference_situation() + msg = f"unknown planner scenario {name!r}" + raise KeyError(msg) + + +def reference_situation(now: datetime | None = None) -> Situation: + """The maintainer's house (plan WP8): 17 kWp east-west, 29.6 kWh, 13.5 kW export limit, + Tibber-like 15-minute prices for 48 h, tiered EEG export price blended, two climate + devices with a value.""" + return Situation( + now=now or _at(SUMMER, 5, 7), + kwp=17.0, + capacity_wh=29_600.0, + max_power_w=10_000.0, + soc_pct=35.0, + load_base_w=450.0, + strategy=BatteryStrategy.PREFER_FULL, + export_price=lambda _at: round(blended_eeg(17.0), 4), + export_limit_w=13_500.0, + devices=(climate("ac_living", 1500.0, value=0.12), climate("ac_bedroom", 1200.0, 0.1)), + day_factors=(1.0, 0.7, 0.9), + cloud=_clouds, + ) + + +SCENARIOS: Final = ( + "sunny_day", + "mixed_clouds", + "two_poor_days", + "forecast_too_optimistic", + "negative_prices", + "price_spike", + "grid_charge_price_level", + "prefer_full", + "reference_house", +) + + +def scenario_inputs(name: str) -> PlannerInputs: + return situation_inputs(situation(name)) + + +__all__ = [ + "SCENARIOS", + "TZ", + "Situation", + "blended_eeg", + "forecasts", + "reference_situation", + "scenario_inputs", + "situation", + "situation_inputs", +] diff --git a/suncore/sim/runner.py b/suncore/sim/runner.py index 0375fde..005b059 100644 --- a/suncore/sim/runner.py +++ b/suncore/sim/runner.py @@ -37,6 +37,7 @@ from datetime import datetime, timedelta from typing import Any, Final +from suncore.app.control import PlanProvider from suncore.core.config import GoalsConfig from suncore.core.control import ControlSettings from suncore.core.decisions import ( @@ -354,6 +355,8 @@ class ScenarioRunner: configs: device configurations to control instead of the scenario's own ``devices`` (the demo: ``suncore.sim.demo_config.demo_devices(catalog).devices`` on the default demo devices); their modes come from ``device_modes`` (default: shadow). + plan_provider: ``now -> Plan`` the stack's controller reads once per tick (Phase 4 WP9; + default: no plan, ``Plan.default()``). """ def __init__( @@ -366,9 +369,11 @@ def __init__( settings: Mapping[str, float | int] | None = None, store: RuntimeStore | None = None, configs: Sequence[DeviceConfig] | None = None, + plan_provider: PlanProvider | None = None, ) -> None: self.scenario = scenario self.catalog = catalog + self.plan_provider = plan_provider self.vt = VirtualTime(scenario.start) self.limiter = RateLimiter(clock=self.vt.monotonic, sleep=self.vt.sleep) self.conn = FakeHAConnection( @@ -434,6 +439,7 @@ def new_stack(self) -> ControlStack: reserve_soc_pct=sc.control.reserve_soc_pct, cadences=cadences, decisions=self.decisions, + plan_provider=self.plan_provider, ) async def start(self) -> None: diff --git a/suncore/sim/scenario.py b/suncore/sim/scenario.py index 28ddce0..52fe9c9 100644 --- a/suncore/sim/scenario.py +++ b/suncore/sim/scenario.py @@ -155,6 +155,20 @@ class ControlParams(BaseModel): """Overrides of ``ControlSettings`` (``smoothing_s``, ``min_write_interval_s`` ...).""" +PriceProfile = Literal["default", "negative_midday"] +"""``negative_midday``: the spot price turns negative around 13:00 (sunny weekends in DE).""" + + +class PriceParams(BaseModel): + """The simulated dynamic price (what the fake ``tibber.get_prices`` answers).""" + + model_config = ConfigDict(extra="forbid", frozen=True) + + profile: PriceProfile = "default" + tomorrow_after_hour: int = Field(default=13, ge=0, le=23) + """Local hour from which tomorrow's prices are published (the real market: afternoon).""" + + class Scenario(BaseModel): """A complete simulator scenario.""" @@ -172,6 +186,7 @@ class Scenario(BaseModel): devices: tuple[SimDeviceSpec, ...] = () manual: tuple[ManualEvent, ...] = () control: ControlParams = ControlParams() + prices: PriceParams = PriceParams() @model_validator(mode="after") def _check(self) -> Scenario: diff --git a/suncore/sim/scenarios/negative_prices.yaml b/suncore/sim/scenarios/negative_prices.yaml new file mode 100644 index 0000000..f318fd1 --- /dev/null +++ b/suncore/sim/scenarios/negative_prices.yaml @@ -0,0 +1,18 @@ +# SPDX-License-Identifier: Apache-2.0 +name: negative_prices +description: Clear summer weekend in Bavaria, the day-ahead price turns negative around noon. +start: "2026-06-21T00:00:00+02:00" +duration_s: 86400 +step_s: 60 +house: + seed: 1 + pv: {kwp: 8.0, latitude: 48.0, longitude: 11.0} + load: {noise_fraction: 0.1} + battery: {capacity_wh: 10000, initial_soc_pct: 30} +outdoor: {mean_c: 26.0, amplitude_c: 7.0} +clouds: + - {at_s: 21600, factor: 0.9} + - {at_s: 32400, factor: 1.0} +prices: + profile: negative_midday + tomorrow_after_hour: 13 diff --git a/suncore/sim/scenarios/planner_in_shadow.yaml b/suncore/sim/scenarios/planner_in_shadow.yaml new file mode 100644 index 0000000..19fcf31 --- /dev/null +++ b/suncore/sim/scenarios/planner_in_shadow.yaml @@ -0,0 +1,31 @@ +# SPDX-License-Identifier: Apache-2.0 +name: planner_in_shadow +description: A clear summer morning with a half-empty 10 kWh battery. The planner computes a plan from the simulated house every quarter hour and hands it to the controller, which follows its bands (battery first until the morning buffer, then the surplus may go to the consumers) while every device stays in shadow mode - nothing is written. +start: "2026-06-21T06:00:00+02:00" +duration_s: 21600 +step_s: 30 +house: + seed: 7 + pv: {kwp: 8.0, latitude: 48.0, longitude: 11.0} + load: + noise_fraction: 0.05 + battery: {capacity_wh: 10000, initial_soc_pct: 25} +outdoor: {mean_c: 24.0, amplitude_c: 5.0} +clouds: + - {at_s: 0, factor: 0.9} + - {at_s: 10800, factor: 1.0} +devices: + - id: rod + template: generic.number_load + physics: {kind: number, max: 3000, step: 100, power_sensor: true} + control: + priority: 10 + power_model: {kind: measured, power_role: power, nominal_w: 3000} + - id: pool + template: generic.switch + physics: {kind: switch, nominal_w: 750, power_sensor: true} + control: + priority: 20 + min_run_s: 300 + min_pause_s: 300 + power_model: {kind: measured, power_role: power, nominal_w: 750} diff --git a/suncore/tariff/__init__.py b/suncore/tariff/__init__.py index df1bcf7..60a1784 100644 --- a/suncore/tariff/__init__.py +++ b/suncore/tariff/__init__.py @@ -1,2 +1,86 @@ # SPDX-License-Identifier: Apache-2.0 -"""SunCore tariff package (Phase 0 placeholder, see docs/architecture.md).""" +"""Tariff adapters, price formula application and the price service (Phase 4 WP4). + +* :mod:`suncore.tariff.parse` - pure parsing of price lists (timestamps, shapes, segments); +* :mod:`suncore.tariff.engine` - a :class:`TariffTemplate` becomes a price source; +* :mod:`suncore.tariff.sources` - fixed and HT/NT sources, the source protocol; +* :mod:`suncore.tariff.pricing` - formula, export side and the negative-price rule; +* :mod:`suncore.tariff.service` - :class:`TariffService`: refresh, cache, store, serve. + +Home Assistant is reached only through the injected ``ActionCaller`` and ``AttributeReader`` +(wired in ``suncore.app.adapters``). +""" + +from suncore.tariff.engine import ( + ActionCaller, + CurrentPriceSource, + EntityReader, + EntityReading, + SourceBinding, + TemplatePriceSource, +) +from suncore.tariff.errors import ( + AmbiguousSeriesError, + CurrencyMismatchError, + ExportConfigError, + ExportTiersError, + MalformedPayloadError, + MissingEntityError, + MissingParamError, + SourceFailedError, + SourceThrottledError, + SourceUnavailableError, + TariffError, + UnitMismatchError, +) +from suncore.tariff.pricing import apply_import_formula, export_base_price, planning_prices +from suncore.tariff.report import PriceReport +from suncore.tariff.service import ( + PriceStore, + RefreshResult, + ServiceSettings, + TariffPlan, + TariffService, +) +from suncore.tariff.sources import ( + FixedPriceSource, + SegmentSource, + SourceData, + TouPriceSource, + finest_series, +) + +__all__ = [ + "ActionCaller", + "AmbiguousSeriesError", + "CurrencyMismatchError", + "CurrentPriceSource", + "EntityReader", + "EntityReading", + "ExportConfigError", + "ExportTiersError", + "FixedPriceSource", + "MalformedPayloadError", + "MissingEntityError", + "MissingParamError", + "PriceReport", + "PriceStore", + "RefreshResult", + "SegmentSource", + "ServiceSettings", + "SourceBinding", + "SourceData", + "SourceFailedError", + "SourceThrottledError", + "SourceUnavailableError", + "TariffError", + "TariffPlan", + "TariffService", + "TemplatePriceSource", + "TouPriceSource", + "UnitMismatchError", + "apply_import_formula", + "export_base_price", + "finest_series", + "planning_prices", +] diff --git a/suncore/tariff/engine.py b/suncore/tariff/engine.py new file mode 100644 index 0000000..3ecc65b --- /dev/null +++ b/suncore/tariff/engine.py @@ -0,0 +1,431 @@ +# SPDX-License-Identifier: Apache-2.0 +"""Template-driven price adapter: a :class:`TariffTemplate` becomes a price source. + +The template (``price_series``) says where the curve is: the response of a read-only action +(Tibber, Nord Pool) or an attribute of one or more entities (ENTSO-E, EPEX Spot, Octopus, +generic). This module knows the shapes, not the integrations: field names, units and paths +come from the template; the rules below are the contract of the schema. + +* **Grid.** The native step is derived from the data: ``end - start`` per slot when the + template names ``end_field`` (Nord Pool, EPEX Spot, Octopus), otherwise the template's + ``resolution_min`` or the most common spacing of the timestamps (Tibber, ENTSO-E). Changes + between 15 and 60 minutes inside a list start a new segment; missing slots are ``None``. +* **Unit.** ``/MWh`` values are divided by 1000; ``{currency}`` is the region's currency. +* **Time.** Timestamps need a UTC offset (see :mod:`suncore.tariff.parse`); request dates of + ``date_field`` actions are local dates of the site's zone (DST: a day has 23 or 25 hours). +* **No I/O of its own.** Actions go through an injected :class:`ActionCaller` + (``suncore.app.adapters`` is the only app module allowed to call actions), attributes + through an injected :data:`EntityReader` of the entity cache. +""" + +from __future__ import annotations + +from collections.abc import Callable, Mapping, Sequence +from dataclasses import dataclass, field +from datetime import date, datetime, time, timedelta, tzinfo +from typing import Any, Final, Protocol +from zoneinfo import ZoneInfo + +from suncore.core.series import ( + PLANNING_STEP, + PriceIncludes, + PriceSeries, + SeriesUnit, + TimeRange, + TimeSeries, + floor_to_step, +) +from suncore.tariff.errors import ( + CurrencyMismatchError, + MalformedPayloadError, + MissingEntityError, + MissingParamError, + SourceUnavailableError, + UnitMismatchError, +) +from suncore.tariff.parse import ( + ParseReport, + RawSlot, + build_segments, + clip_series, + expand_path, + normalise, + parse_number, + select_series, + slots_from_mapping, + slots_from_records, + walk, +) +from suncore.tariff.sources import SourceData, SourceKind, finest_series +from suncore.tariff.units import ( + currency_of, + divisor_to_kwh, + energy_scale, + normalise_price_unit, + resolve_value_unit, +) +from suncore.templates.models import ActionSeries, AttributeSeries, TariffTemplate + +DEFAULT_MIN_INTERVAL_S: Final = 30.0 +"""Floor between two calls of the same action (``ActionRateLimiter`` default, follow-up A3).""" + + +class ActionCaller(Protocol): + """Calls a read-only action and returns its response object. + + Implemented in ``suncore.app.adapters`` on top of ``HAConnection.call_action_response``; + it raises :class:`~suncore.tariff.errors.SourceThrottledError` for a call skipped by the + rate limiter and :class:`~suncore.tariff.errors.SourceFailedError` for anything else. + """ + + async def __call__( + self, + domain: str, + service: str, + data: Mapping[str, Any], + *, + min_interval_s: float, + max_wait_s: float, + ) -> Mapping[str, Any]: ... + + +@dataclass(frozen=True, slots=True) +class EntityReading: + """State text and attributes of an entity as last seen.""" + + state: str + attributes: Mapping[str, Any] + + +EntityReader = Callable[[str], EntityReading | None] +"""Current reading of an entity, ``None`` while it is unknown to Home Assistant or +``unavailable``.""" + + +@dataclass(frozen=True, slots=True) +class SourceBinding: + """What the user's tariff configuration adds to a template (see ``ImportTariff``).""" + + tz: tzinfo + entities: Mapping[str, str] = field(default_factory=dict) + """Template role -> entity id (``price_entity`` is the role ``price``).""" + action_params: Mapping[str, str | Sequence[str]] = field(default_factory=dict) + series_key: str | None = None + price_includes: PriceIncludes | None = None + """The user's statement overriding the template's classification.""" + currency: str = "EUR" + min_interval_s: float = DEFAULT_MIN_INTERVAL_S + + +def _local_midnight(day: date, tz: tzinfo) -> datetime: + return datetime.combine(day, time.min, tzinfo=tz) + + +def request_dates(window: TimeRange, now: datetime, tz: tzinfo, max_horizon_h: int) -> list[date]: + """Local delivery dates to ask a per-date action for. + + From the window's first local day to the last, but not beyond today plus + ``ceil(max_horizon_h / 24)`` days (Nord Pool: "one day in the future" -> 24 h). + """ + first = window.start.astimezone(tz).date() + last = (window.end - timedelta(microseconds=1)).astimezone(tz).date() + limit = now.astimezone(tz).date() + timedelta(days=-(-max_horizon_h // 24)) + last = min(last, limit) + days = (last - first).days + return [first + timedelta(days=i) for i in range(max(0, days + 1))] + + +class TemplatePriceSource: + """A :class:`SegmentSource` (and ``PriceSource``) built from a dynamic tariff template.""" + + def __init__( + self, + template: TariffTemplate, + binding: SourceBinding, + *, + action: ActionCaller | None = None, + attributes: EntityReader | None = None, + clock: Callable[[], datetime], + ) -> None: + series = template.price_series + if template.tariff_type != "dynamic" or series is None: + msg = f"template {template.id} is not a dynamic tariff with a price_series" + raise ValueError(msg) + if isinstance(series, ActionSeries) and action is None: + msg = f"template {template.id} reads an action: an ActionCaller is required" + raise ValueError(msg) + if isinstance(series, AttributeSeries) and attributes is None: + msg = f"template {template.id} reads attributes: an EntityReader is required" + raise ValueError(msg) + self._template = template + self._series = series + self._binding = binding + self._action = action + self._attributes = attributes + self._clock = clock + self._unit = resolve_value_unit(series.fields.value_unit, binding.currency) + self._divisor = divisor_to_kwh(self._unit) + self._resolution = ( + None if template.resolution_min is None else timedelta(minutes=template.resolution_min) + ) + assert template.price_includes is not None # validated: required for dynamic + self._includes: PriceIncludes = binding.price_includes or template.price_includes + + # --- SegmentSource --------------------------------------------------------------- + + @property + def source_id(self) -> str: + return self._template.id + + @property + def kind(self) -> SourceKind: + return "dynamic" + + @property + def price_includes(self) -> PriceIncludes: + return self._includes + + @property + def uses_action(self) -> bool: + return isinstance(self._series, ActionSeries) + + @property + def watched_entities(self) -> tuple[str, ...]: + return tuple(dict.fromkeys(self._binding.entities.values())) + + @property + def delivery_tz(self) -> tzinfo | None: + series = self._series + if isinstance(series, ActionSeries) and series.date_tz is not None: + return ZoneInfo(series.date_tz) + return None + + def _check_currency(self, source_currency: str | None, where: str) -> None: + """Refuse prices in another currency than the region's (a silent mix-up of money).""" + expected = self._binding.currency + if source_currency is not None and source_currency.upper() != expected: + raise CurrencyMismatchError( + f"{where} is in {source_currency}, the region uses {expected}", + source_currency=source_currency.upper(), + region_currency=expected, + ) + + async def fetch_segments(self, window: TimeRange, now: datetime) -> SourceData: + self._check_currency(currency_of(self._unit), "the template") + if isinstance(self._series, ActionSeries): + slots, bad = await self._from_action(self._series, window, now) + else: + slots, bad = self._from_attributes(self._series) + normalised, report = normalise(slots, unreadable=bad) + series = build_segments(normalised, divisor=self._divisor, resolution=self._resolution) + clipped = [c for s in series if (c := clip_series(s, window.start, window.end))] + return SourceData( + segments=tuple(self._price_series(s) for s in clipped), + report=ParseReport( + points=report.points, + unreadable_values=report.unreadable_values, + duplicates=report.duplicates, + overlaps=report.overlaps, + ), + ) + + async def fetch(self, window: TimeRange) -> PriceSeries: + """``PriceSource`` protocol: one series on the finest native step.""" + data = await self.fetch_segments(window, self._clock()) + return finest_series(self.source_id, self._includes, data.segments, window) + + def _price_series(self, series: TimeSeries) -> PriceSeries: + return PriceSeries( + source_id=self.source_id, price_includes=self._includes, import_price=series + ) + + # --- action ---------------------------------------------------------------------- + + def _request_base(self, series: ActionSeries) -> dict[str, Any]: + data: dict[str, Any] = {} + for param in series.params: + value = self._binding.action_params.get(param.name) + if value is None: + if param.required: + raise MissingParamError( + f"action field `{param.name}` is not configured", field=param.name + ) + continue + data[param.name] = value if isinstance(value, str) else list(value) + if param.name == "currency" and isinstance(value, str): + self._check_currency(value, "the action's `currency` field") + return data + + async def _from_action( + self, series: ActionSeries, window: TimeRange, now: datetime + ) -> tuple[list[RawSlot], int]: + assert self._action is not None + tz = self._binding.tz + base = self._request_base(series) + requests: list[dict[str, Any]] + if series.date_field is not None: + market_tz = ZoneInfo(series.date_tz) if series.date_tz is not None else tz + dates = request_dates(window, now, market_tz, series.max_horizon_h) + requests = [{**base, series.date_field: d.isoformat()} for d in dates] + else: + data = dict(base) + if series.start_field is not None: + first = window.start.astimezone(tz).date() + data[series.start_field] = _local_midnight(first, tz).isoformat() + if series.end_field is not None: + last = (window.end - timedelta(microseconds=1)).astimezone(tz).date() + data[series.end_field] = _local_midnight(last + timedelta(days=1), tz).isoformat() + requests = [data] + slots: list[RawSlot] = [] + bad = 0 + for index, data in enumerate(requests): + response = await self._action( + series.domain, + series.service, + data, + min_interval_s=self._binding.min_interval_s, + # the second and later dates wait for the limiter's next slot + max_wait_s=0.0 if index == 0 else self._binding.min_interval_s + 1.0, + ) + candidates = expand_path(response, series.response_path) + node = select_series(candidates, self._binding.series_key) + if node is None: + continue + part, unreadable = slots_from_records(node, series.fields) + slots.extend(part) + bad += unreadable + return slots, bad + + # --- attributes ------------------------------------------------------------------ + + def _check_unit(self, attrs: Mapping[str, Any]) -> None: + """Refuse an entity whose unit says per MWh where the template says per kWh (or back). + + A silent factor 1000 would poison every plan; an entity without a price unit + (event entities, template sensors) is not checked. + """ + raw = attrs.get("unit_of_measurement") + if not isinstance(raw, str): + return + normalised = normalise_price_unit(raw) + if energy_scale(normalised) is not None: + self._check_currency(currency_of(normalised), f"the sensor unit {raw!r}") + seen = energy_scale(normalised) + expected = energy_scale(self._unit) + if seen is not None and expected is not None and seen != expected: + raise UnitMismatchError( + f"sensor unit {raw!r} vs template unit {self._unit!r}", + sensor_unit=raw, + template_unit=self._unit, + ) + + def _from_attributes(self, series: AttributeSeries) -> tuple[list[RawSlot], int]: + assert self._attributes is not None + slots: list[RawSlot] = [] + bad = 0 + seen_entity = False + found_attribute = False + for role in series.roles: + entity_id = self._binding.entities.get(role) + if entity_id is None: + if self._template.roles[role].required: + raise MissingEntityError(f"no entity for role `{role}`", role=role) + continue + reading = self._attributes(entity_id) + if reading is None: + continue + attrs = reading.attributes + seen_entity = True + self._check_unit(attrs) + value = attrs.get(series.attribute) + if value is None: + continue + found_attribute = True + if series.list_path is not None: + value = walk(value, series.list_path) + if series.shape == "mapping": + part, unreadable = slots_from_mapping(value) + else: + part, unreadable = slots_from_records(value, series.fields) + slots.extend(part) + bad += unreadable + if not slots and not seen_entity: + raise SourceUnavailableError("no price entity is available") + if not slots and not found_attribute: + raise MalformedPayloadError( + f"attribute `{series.attribute}` is missing on the price entity", + attribute=series.attribute, + ) + return slots, bad + + +class CurrentPriceSource: + """A dynamic tariff with only a price sensor (no template): the current slot's price. + + The state is the price of the running 15-minute slot (units per kWh, as the wizard asks + for); nothing is known about later slots, so the series is one slot long. Better than no + price, much worse than a curve - the wizard recommends a template. + """ + + def __init__( + self, + entity_id: str, + reader: EntityReader, + *, + price_includes: PriceIncludes, + clock: Callable[[], datetime], + ) -> None: + self._entity_id = entity_id + self._reader = reader + self._includes = price_includes + self._clock = clock + + @property + def source_id(self) -> str: + return "entity" + + @property + def kind(self) -> SourceKind: + return "dynamic" + + @property + def price_includes(self) -> PriceIncludes: + return self._includes + + @property + def uses_action(self) -> bool: + return False + + @property + def watched_entities(self) -> tuple[str, ...]: + return (self._entity_id,) + + @property + def delivery_tz(self) -> tzinfo | None: + return None + + async def fetch_segments(self, window: TimeRange, now: datetime) -> SourceData: # noqa: ARG002 + reading = self._reader(self._entity_id) + if reading is None: + raise SourceUnavailableError("the price sensor is not available") + value = parse_number(reading.state) + if value is None: + raise SourceUnavailableError("the price sensor has no numeric state") + divisor = 1.0 + unit = reading.attributes.get("unit_of_measurement") + if isinstance(unit, str) and energy_scale(normalise_price_unit(unit)) == "MWh": + divisor = 1000.0 + series = TimeSeries( + start=floor_to_step(now), + step=PLANNING_STEP, + values=(value / divisor,), + unit=SeriesUnit.PRICE, + ) + price = PriceSeries( + source_id=self.source_id, price_includes=self._includes, import_price=series + ) + return SourceData(segments=(price,), report=ParseReport(points=1)) + + async def fetch(self, window: TimeRange) -> PriceSeries: + data = await self.fetch_segments(window, self._clock()) + return data.segments[0] diff --git a/suncore/tariff/errors.py b/suncore/tariff/errors.py new file mode 100644 index 0000000..07c16be --- /dev/null +++ b/suncore/tariff/errors.py @@ -0,0 +1,107 @@ +# SPDX-License-Identifier: Apache-2.0 +"""Errors of the tariff adapters; each carries a catalogue key (``tariff.error.*``). + +The keys are rendered by the frontend's ICU catalogue (``en.json`` / ``de.json``); ``args`` +are the ICU arguments. An error never carries free text for the user. +""" + +from __future__ import annotations + +from typing import Any, ClassVar, Final + +ERR_UNAVAILABLE: Final = "tariff.error.source_unavailable" +ERR_MALFORMED: Final = "tariff.error.malformed_payload" +ERR_AMBIGUOUS: Final = "tariff.error.ambiguous_series" +ERR_MISSING_PARAM: Final = "tariff.error.missing_param" +ERR_MISSING_ROLE: Final = "tariff.error.missing_entity" +ERR_THROTTLED: Final = "tariff.error.throttled" +ERR_FAILED: Final = "tariff.error.action_failed" +ERR_UNIT_MISMATCH: Final = "tariff.error.unit_mismatch" +ERR_CURRENCY_MISMATCH: Final = "tariff.error.currency_mismatch" +ERR_EXPORT_NEEDS_KWP: Final = "tariff.error.export_needs_kwp" +ERR_EXPORT_TIERS: Final = "tariff.error.export_tiers" + + +class TariffError(Exception): + """Base class: ``key`` is the catalogue key, ``args`` its ICU arguments.""" + + key: ClassVar[str] = ERR_FAILED + + def __init__(self, detail: str = "", **args: Any) -> None: + super().__init__(detail or self.key) + self.detail = detail + self.args_: dict[str, Any] = args + + @property + def message_args(self) -> dict[str, Any]: + return dict(self.args_) + + +class SourceUnavailableError(TariffError): + """The price entity (or all of them) is unknown, ``unavailable`` or has no price list.""" + + key = ERR_UNAVAILABLE + + +class MalformedPayloadError(TariffError): + """The response or attribute does not have the documented shape.""" + + key = ERR_MALFORMED + + +class AmbiguousSeriesError(TariffError): + """A response holds several series (homes, areas) and the configuration names none.""" + + key = ERR_AMBIGUOUS + + +class MissingParamError(TariffError): + """The action needs a request field the tariff configuration does not supply.""" + + key = ERR_MISSING_PARAM + + +class MissingEntityError(TariffError): + """A role the series is read from has no configured entity.""" + + key = ERR_MISSING_ROLE + + +class SourceThrottledError(TariffError): + """The action was asked for too often and skipped (not a failure: use the last data).""" + + key = ERR_THROTTLED + + def __init__(self, retry_after_s: float, detail: str = "") -> None: + super().__init__(detail, retry_after_s=retry_after_s) + self.retry_after_s = retry_after_s + + +class SourceFailedError(TariffError): + """Home Assistant or the integration failed to answer the action.""" + + key = ERR_FAILED + + +class UnitMismatchError(TariffError): + """The entity's price unit (per kWh or per MWh) contradicts the template's value unit.""" + + key = ERR_UNIT_MISMATCH + + +class CurrencyMismatchError(UnitMismatchError): + """The source's currency differs from the region's (prices would be in the wrong money).""" + + key = ERR_CURRENCY_MISMATCH + + +class ExportConfigError(TariffError): + """The export tariff cannot be turned into a price (tiered without the plant size).""" + + key = ERR_EXPORT_NEEDS_KWP + + +class ExportTiersError(ExportConfigError): + """The feed-in tiers do not cover the whole plant (or are not ordered).""" + + key = ERR_EXPORT_TIERS diff --git a/suncore/tariff/parse.py b/suncore/tariff/parse.py new file mode 100644 index 0000000..960e283 --- /dev/null +++ b/suncore/tariff/parse.py @@ -0,0 +1,330 @@ +# SPDX-License-Identifier: Apache-2.0 +"""Pure parsing of price lists (Phase 4 WP4): no I/O, no clock, time zones explicit. + +Shapes (all from ``docs/research/integrations.md``, pinned sources there): + +* Tibber ``tibber.get_prices``: ``{"prices": {"": [{"start_time": iso, "price": float}]}}``; +* Nord Pool ``nordpool.get_prices_for_date``: ``{"": [{"start", "end", "price"}]}``, UTC + ``+00:00``, currency per MWh; +* ENTSO-E ``prices`` attribute: ``[{"time": "2026-10-16 00:00:00+02:00", "price": float}]`` + (``str(datetime)``: a space instead of ``T``); +* EPEX Spot ``data`` attribute: ``[{"start_time", "end_time", "price_per_kwh"}]``, local ISO; +* Octopus ``rates`` attribute: ``[{"start", "end", "value_inc_vat"}]``, local datetimes; +* ``mapping`` shape: ``{iso_timestamp: value}``. + +A timestamp without a UTC offset is rejected (SunCore never guesses a zone); all arithmetic is +done in UTC, so a DST day of 23 h or 25 h needs no special case. +""" + +from __future__ import annotations + +import itertools +import math +from collections import Counter +from collections.abc import Iterable, Mapping, Sequence +from dataclasses import dataclass +from datetime import UTC, datetime, timedelta +from typing import Any, Final + +from suncore.core.series import SeriesUnit, TimeSeries, segments_from_points +from suncore.tariff.errors import AmbiguousSeriesError, MalformedPayloadError +from suncore.templates.models import SeriesFields + +DEFAULT_STEP: Final = timedelta(hours=1) +"""Step assumed when a list has a single point and the template names no resolution.""" +KNOWN_STEPS: Final = (timedelta(minutes=15), timedelta(hours=1)) +"""Resolutions SunCore accepts to change to inside one list (15 min <-> 60 min).""" + + +@dataclass(frozen=True, slots=True) +class RawSlot: + """One price point: ``start`` (UTC), optional ``end`` (UTC) and the value (``None`` = gap).""" + + start: datetime + end: datetime | None + value: float | None + + +@dataclass(frozen=True, slots=True) +class ParseReport: + """What the parser had to drop; shown as quality, never silently ignored.""" + + points: int = 0 + unreadable_values: int = 0 + """Points whose value was missing or not a finite number (they become gaps).""" + duplicates: int = 0 + """Points with a start already seen (the later one wins).""" + overlaps: int = 0 + """Points that start before the previous slot ends (dropped, the earlier one wins).""" + + +def parse_timestamp(value: object) -> datetime: + """An ISO 8601 timestamp (``T`` or space separated, ``Z`` or offset) as aware UTC. + + Accepts ``str(datetime)`` output (ENTSO-E) and ``datetime.isoformat()`` (EPEX Spot, + Octopus, Nord Pool, Tibber). Raises :class:`MalformedPayloadError` for anything else, + including a timestamp without an offset. + """ + if isinstance(value, datetime): + parsed = value + elif isinstance(value, str): + try: + parsed = datetime.fromisoformat(value.strip()) + except ValueError as exc: + msg = f"not an ISO 8601 timestamp: {value!r}" + raise MalformedPayloadError(msg) from exc + else: + msg = f"timestamp is neither text nor datetime: {type(value).__name__}" + raise MalformedPayloadError(msg) + if parsed.tzinfo is None or parsed.utcoffset() is None: + msg = f"timestamp without a UTC offset: {value!r}" + raise MalformedPayloadError(msg) + return parsed.astimezone(UTC) + + +def parse_number(value: object) -> float | None: + """A finite number from a number or numeric text; ``None`` for everything else.""" + if isinstance(value, bool): + return None + if isinstance(value, int | float): + number = float(value) + elif isinstance(value, str): + try: + number = float(value.strip()) + except ValueError: + return None + else: + return None + return number if math.isfinite(number) else None + + +# --- locating the points --------------------------------------------------------------- + + +def walk(value: object, path: str) -> object: + """Follow a dotted path of mapping keys (no ``*``); ``MalformedPayloadError`` if absent.""" + node = value + for part in path.split("."): + if not isinstance(node, Mapping) or part not in node: + msg = f"path {path!r} not found at {part!r}" + raise MalformedPayloadError(msg) + node = node[part] + return node + + +def expand_path(payload: object, path: str) -> list[tuple[str, object]]: + """All ``(label, node)`` pairs a response path leads to; ``*`` fans out over a mapping. + + The label is the last expanded mapping key (home name, area) or ``""``. A path through a + missing key yields no candidate (an empty response is not an error); a path through a + non-mapping raises :class:`MalformedPayloadError`. + """ + found: list[tuple[str, object]] = [("", payload)] + for part in path.split("."): + nxt: list[tuple[str, object]] = [] + for label, node in found: + if not isinstance(node, Mapping): + msg = f"path {path!r}: {part!r} is not inside an object" + raise MalformedPayloadError(msg) + if part == "*": + nxt.extend((str(k), v) for k, v in node.items()) + elif part in node: + nxt.append((label, node[part])) + found = nxt + return found + + +def select_series(candidates: Sequence[tuple[str, object]], key: str | None) -> object | None: + """The one node of a fan-out: the entry named ``key`` or the only one. + + Raises :class:`AmbiguousSeriesError` when several entries exist and no key is configured + (SunCore never merges two homes' prices), and :class:`MalformedPayloadError` when the + configured key is absent while others exist. No candidate at all returns ``None``. + """ + if key is not None: + for label, node in candidates: + if label == key or label.casefold() == key.casefold(): + return node + if candidates: + msg = f"series key {key!r} not in the response" + raise MalformedPayloadError(msg, key=key, available=[c[0] for c in candidates]) + return None + if len(candidates) > 1: + raise AmbiguousSeriesError( + "the response holds several series", + available=", ".join(sorted(c[0] for c in candidates)), + ) + return candidates[0][1] if candidates else None + + +def _optional_stamp(value: object) -> datetime | None: + return None if value is None else parse_timestamp(value) + + +def slots_from_records(records: object, fields: SeriesFields) -> tuple[list[RawSlot], int]: + """Points from a list of objects named by ``fields``; also the count of unreadable values. + + A record without a timestamp is malformed (raises); a missing or non-numeric value is a + gap. ``fields.end_field`` gives the slot end when present in the record. + """ + if not isinstance(records, list): + msg = f"expected a list of price points, got {type(records).__name__}" + raise MalformedPayloadError(msg) + assert fields.timestamp_field is not None + assert fields.value_field is not None + slots: list[RawSlot] = [] + bad = 0 + for record in records: + if not isinstance(record, Mapping) or fields.timestamp_field not in record: + msg = f"price point without `{fields.timestamp_field}`" + raise MalformedPayloadError(msg) + value = parse_number(record.get(fields.value_field)) + bad += value is None + end = ( + _optional_stamp(record.get(fields.end_field)) if fields.end_field is not None else None + ) + slots.append(RawSlot(parse_timestamp(record[fields.timestamp_field]), end, value)) + return slots, bad + + +def slots_from_mapping(mapping: object) -> tuple[list[RawSlot], int]: + """Points from ``{iso_timestamp: value}``.""" + if not isinstance(mapping, Mapping): + msg = f"expected an object of timestamp -> value, got {type(mapping).__name__}" + raise MalformedPayloadError(msg) + slots: list[RawSlot] = [] + bad = 0 + for stamp, raw in mapping.items(): + value = parse_number(raw) + bad += value is None + slots.append(RawSlot(parse_timestamp(stamp), None, value)) + return slots, bad + + +# --- normalising and segmenting ---------------------------------------------------------- + + +def normalise( + slots: Iterable[RawSlot], *, unreadable: int = 0 +) -> tuple[list[RawSlot], ParseReport]: + """Sort by start, collapse duplicate starts (later wins) and drop overlapping slots. + + Merging two lists (Octopus current day + next day) therefore needs no special case. + Slots with an ``end`` not after their ``start`` are dropped as overlaps. + """ + ordered = sorted(enumerate(slots), key=lambda p: (p[1].start, p[0])) + unique: dict[datetime, RawSlot] = {} + total = 0 + for _, slot in ordered: + total += 1 + unique[slot.start] = slot # same start: the later one in input order wins + duplicates = total - len(unique) + result: list[RawSlot] = [] + overlaps = 0 + for slot in unique.values(): + if slot.end is not None and slot.end <= slot.start: + overlaps += 1 + continue + if result and (prev_end := result[-1].end) is not None and slot.start < prev_end: + overlaps += 1 + continue + result.append(slot) + report = ParseReport( + points=len(result), unreadable_values=unreadable, duplicates=duplicates, overlaps=overlaps + ) + return result, report + + +def infer_step(starts: Sequence[datetime], fallback: timedelta | None) -> timedelta: + """The resolution of a list without slot ends: the most common distance of neighbours. + + Ties go to the finer step. A single point uses ``fallback`` (the template's + ``resolution_min``), else one hour. + """ + distances = Counter(b - a for a, b in itertools.pairwise(starts)) + if not distances: + return fallback or DEFAULT_STEP + best = max(distances.values()) + return min(d for d, n in distances.items() if n == best) + + +def _explicit_segments(slots: Sequence[RawSlot], divisor: float) -> list[TimeSeries]: + """Segments for slots that all carry an ``end``: runs of equal length that touch.""" + segments: list[TimeSeries] = [] + run: list[RawSlot] = [] + + def close() -> None: + if run: + first = run[0] + assert first.end is not None + segments.append( + TimeSeries( + start=first.start, + step=first.end - first.start, + values=tuple(None if s.value is None else s.value / divisor for s in run), + unit=SeriesUnit.PRICE, + ) + ) + run.clear() + + for slot in slots: + assert slot.end is not None + if run: + prev = run[-1] + assert prev.end is not None + same_length = slot.end - slot.start == prev.end - prev.start + if not (same_length and slot.start == prev.end): + close() + run.append(slot) + close() + return segments + + +def build_segments( + slots: Sequence[RawSlot], *, divisor: float, resolution: timedelta | None +) -> tuple[TimeSeries, ...]: + """Regular ``currency/kWh`` segments from normalised slots. + + * every slot has an ``end`` (Nord Pool, EPEX Spot, Octopus): the slot length is + ``end - start`` and consecutive slots of equal length that touch form one segment, so a + 15/60-minute change or a gap just starts a new segment; + * otherwise (Tibber, ENTSO-E, mapping attributes): the resolution is the template's + ``resolution_min`` or the most common distance; 15 <-> 60 minutes changes inside the list + are accepted, missing slots become ``None`` (:func:`segments_from_points`). + + ``divisor`` converts the source unit to currency/kWh (``1000`` for per-MWh values). + """ + if not slots: + return () + if all(s.end is not None for s in slots): + return tuple(_explicit_segments(slots, divisor)) + expected = resolution or infer_step([s.start for s in slots], None) + other = {s for s in KNOWN_STEPS if s != expected} + points = [(s.start, None if s.value is None else s.value / divisor) for s in slots] + try: + return segments_from_points( + points, SeriesUnit.PRICE, expected_step=expected, other_steps=other + ) + except ValueError as exc: + raise MalformedPayloadError(str(exc)) from exc + + +def clip_series(series: TimeSeries, start: datetime, end: datetime) -> TimeSeries | None: + """The part of ``series`` that overlaps ``[start, end)`` (whole slots), else ``None``.""" + if series.end <= start or series.start >= end: + return None + first = max(0, (start - series.start) // series.step) + last = min(len(series), -(-(end - series.start) // series.step)) + if last <= first: + return None + return TimeSeries( + start=series.slot_start(first), + step=series.step, + values=series.values[first:last], + unit=series.unit, + ) + + +def as_attributes(value: Any) -> Mapping[str, Any]: + """Attributes mapping of an entity state (never ``None``).""" + return value if isinstance(value, Mapping) else {} diff --git a/suncore/tariff/pricing.py b/suncore/tariff/pricing.py new file mode 100644 index 0000000..d862189 --- /dev/null +++ b/suncore/tariff/pricing.py @@ -0,0 +1,153 @@ +# SPDX-License-Identifier: Apache-2.0 +"""From source prices to the planning prices: formula, export side, negative-price rule. + +Pure functions on :class:`~suncore.core.series.PriceSeries` and the contracts of +``core/tariff.py``; the service only feeds them. + +**Import.** A ``spot_only`` source goes through :meth:`PriceFormula.end_price` at the slot's +start instant, in the site's zone (``end_price`` is the 4-A ``apply``: the boundary test +reserves the call ``.apply(`` for the actuator write path). An ``all_in`` source is never +touched, even if a formula is configured (the API refuses that combination, this is the second +line of defence). + +**Export.** ``fixed``: the fixed price; ``tiered``: :func:`blended_export_price` with the +site's total kWp (the tiers must cover it, else :class:`ExportConfigError`); ``none``: 0. +A source that brings its own export prices (none of the known integrations does) wins over the +configuration. + +**Negative-price rule** (region template ``negative_price_rule``): + +* ``no_remuneration`` (``de``): in every slot whose *spot* price is negative, the export price + is 0 - the grid operator pays nothing then, so the planner must see that exporting earns + nothing and avoid it (curtail, store, consume). The spot price is the source price of a + ``spot_only`` source (before the formula). For an ``all_in`` source (Tibber) the spot price + is not known; the **import end price** is used as the proxy, which only marks slots where + the end price itself is negative, i.e. fewer slots than the true negative-spot slots + (UNVERIFIED approximation: the planner may see a remuneration in a slot with a slightly + negative spot price). A slot whose price is unknown gets an unknown export price. +* ``curtailment_required`` and ``none``: prices are not changed here (curtailment is a + planner/controller matter, not a price). +""" + +from __future__ import annotations + +from collections.abc import Sequence +from datetime import tzinfo +from typing import Final + +from suncore.core.config import ExportTariff +from suncore.core.series import ( + Grid, + PriceIncludes, + PriceSeries, + SeriesUnit, + TimeSeries, + resample_prices, +) +from suncore.core.tariff import PriceFormula, blended_export_price +from suncore.tariff.errors import ExportConfigError, ExportTiersError +from suncore.templates.models import NegativePriceRule + +NEGATIVE_EXPORT_PRICE: Final = 0.0 +"""Export price (currency/kWh) in a slot without remuneration.""" + + +def export_base_price(tariff: ExportTariff, total_kwp: float | None) -> float: + """The export price per kWh the configuration gives (``none`` -> 0). + + Raises :class:`ExportConfigError` for ``tiered`` without a known plant size or with tiers + that do not cover it (SunCore never guesses a rate). + """ + if tariff.kind == "none": + return 0.0 + if tariff.kind == "fixed": + assert tariff.fixed_price is not None + return tariff.fixed_price + if total_kwp is None: + raise ExportConfigError("tiered export needs `kwp` on every PV array") + try: + return blended_export_price(tariff.tiers, total_kwp) + except ValueError as exc: + raise ExportTiersError(str(exc), kwp=total_kwp) from exc + + +def apply_import_formula( + spot: TimeSeries, + includes: PriceIncludes, + formula: PriceFormula | None, + tz: tzinfo, +) -> tuple[TimeSeries, PriceIncludes]: + """End prices for a resampled source series, and the ``price_includes`` of the result. + + ``spot_only`` + formula -> ``all_in``; ``spot_only`` without formula stays ``spot_only`` + (the caller reports it); ``all_in`` is returned unchanged. + """ + if includes == "all_in" or formula is None: + return spot, includes + values = tuple( + None if v is None else formula.end_price(v, spot.slot_start(i), tz) + for i, v in enumerate(spot.values) + ) + return spot.model_copy(update={"values": values}), "all_in" + + +def planning_prices( + segments: Sequence[PriceSeries], + grid: Grid, + *, + formula: PriceFormula | None, + export_price: float, + rule: NegativePriceRule, + tz: tzinfo, + source_id: str | None = None, +) -> tuple[PriceSeries, int]: + """Import and export prices on ``grid`` and how many slots the negative-price rule zeroed. + + ``segments`` are one source's segments (any mix of 15/60 minutes). Slots no source value + covers are ``None`` in both series. + """ + if not segments: + empty = TimeSeries( + start=grid.start, + step=grid.step, + values=(None,) * grid.count, + unit=SeriesUnit.PRICE, + ) + return ( + PriceSeries( + source_id=source_id or "none", + price_includes="all_in", + import_price=empty, + export_price=empty, + ), + 0, + ) + resampled = resample_prices(list(segments), grid) + spot = resampled.import_price + end, includes = apply_import_formula(spot, resampled.price_includes, formula, tz) + zeroed = 0 + export_values: list[float | None] = [] + for i, end_price in enumerate(end.values): + if resampled.export_price is not None: + export_values.append(resampled.export_price.values[i]) + continue + reference = spot.values[i] if resampled.price_includes == "spot_only" else end_price + if end_price is None or reference is None: + export_values.append(None) + elif rule is NegativePriceRule.NO_REMUNERATION and reference < 0: + export_values.append(NEGATIVE_EXPORT_PRICE) + zeroed += 1 + else: + export_values.append(export_price) + export = TimeSeries( + start=end.start, step=end.step, values=tuple(export_values), unit=SeriesUnit.PRICE + ) + return ( + PriceSeries( + source_id=source_id or resampled.source_id, + price_includes=includes, + import_price=end, + export_price=export, + ), + zeroed, + ) diff --git a/suncore/tariff/report.py b/suncore/tariff/report.py new file mode 100644 index 0000000..e5fbd48 --- /dev/null +++ b/suncore/tariff/report.py @@ -0,0 +1,95 @@ +# SPDX-License-Identifier: Apache-2.0 +"""What ``GET /api/v1/prices`` returns: the planning prices with source and freshness. + +Pydantic models are the schema (OpenAPI is generated from them). Error ``key`` values are +catalogue keys (``tariff.error.*``); ``args`` are their ICU arguments. +""" + +from __future__ import annotations + +from typing import Annotated, Literal + +from pydantic import AwareDatetime, BaseModel, ConfigDict, Field + +from suncore.core.series import PriceIncludes + +SourceKindOut = Literal["dynamic", "fixed", "tou"] +FreshnessStatus = Literal["fresh", "stale", "missing", "static"] +ExportKind = Literal["fixed", "tiered", "none"] +ErrorArg = str | float | int | list[str] + + +class _Out(BaseModel): + model_config = ConfigDict(frozen=True, extra="forbid") + + +class PriceSlot(_Out): + """One 15-minute interval; a price is ``null`` where no source value covers it.""" + + start: AwareDatetime + import_price: float | None + """End price of imported energy, currency/kWh (may be negative).""" + export_price: float | None + """Remuneration of exported energy, currency/kWh (0 when the negative-price rule applies).""" + + +class PriceErrorOut(_Out): + """Why the last refresh failed, as a catalogue key.""" + + key: str + args: dict[str, ErrorArg] = Field(default_factory=dict) + + +class PriceSourceInfo(_Out): + import_source_id: str + """Template id (``tibber.price``), ``fixed`` or ``tou``.""" + import_kind: SourceKindOut + source_price_includes: PriceIncludes + """What the source delivers: the bare spot price or the all-in end price.""" + price_includes: PriceIncludes + """What ``import_price`` is: ``all_in`` once the formula was applied.""" + formula_applied: bool + export_kind: ExportKind + negative_price_rule: str + """Region template value: ``none``, ``no_remuneration`` or ``curtailment_required``.""" + export_zeroed_slots: Annotated[int, Field(ge=0)] + """Slots whose export price was set to 0 by the negative-price rule.""" + native_step_min: int | None + """Finest native resolution of the source (15 or 60), ``null`` for fixed prices.""" + currency: str + + +class PriceFreshness(_Out): + status: FreshnessStatus + fetched_at: AwareDatetime | None + age_s: float | None + known_until: AwareDatetime | None + """End of the last interval the source has a price for.""" + next_refresh_at: AwareDatetime | None + last_error: PriceErrorOut | None + + +class PriceQuality(_Out): + slots: Annotated[int, Field(ge=0)] + known_slots: Annotated[int, Field(ge=0)] + has_tomorrow: bool + """Prices cover the whole next local day.""" + dropped_points: Annotated[int, Field(ge=0)] + """Points of the last fetch that were unreadable, duplicated or overlapping.""" + carried_slots: Annotated[int, Field(ge=0)] = 0 + """Slots the latest fetch left unknown and an earlier fetch supplied (degraded data).""" + + +class PriceReport(_Out): + unit: Literal["currency/kWh"] = "currency/kWh" + step_min: Literal[15] = 15 + price_includes: PriceIncludes + """What ``import_price`` is: ``all_in`` (end price) or ``spot_only`` (bare market price).""" + formula_missing: bool + """The import price is a bare spot price and no price formula turns it into the end price: + do not plan with it.""" + start: AwareDatetime + slots: list[PriceSlot] + source: PriceSourceInfo + freshness: PriceFreshness + quality: PriceQuality diff --git a/suncore/tariff/service.py b/suncore/tariff/service.py new file mode 100644 index 0000000..eb65610 --- /dev/null +++ b/suncore/tariff/service.py @@ -0,0 +1,610 @@ +# SPDX-License-Identifier: Apache-2.0 +"""The tariff service: keeps import and export prices fresh and serves them on the 15-minute grid. + +One service per configured tariff. It owns a :class:`~suncore.tariff.sources.SegmentSource` +(template adapter, fixed or HT/NT), the price formula, the export side and the region's +negative-price rule. Time is injected (``clock``); nothing here sleeps except :meth:`run`, +whose ``sleep`` is injected too. + +**When it refreshes** (:meth:`due`, the one decision function; :meth:`next_refresh` mirrors it): + +* ``initial``: never fetched; +* ``changed``: the price entity changed (:meth:`notify_changed`) - at once for attribute + sources (cheap: reads the entity cache), for action sources only when the current slot has no + price (an action call costs a request to the cloud service; the sensor changes every slot); +* ``interval``: the last fetch is ``refresh_interval_s`` old (default one hour); +* ``tomorrow``: a dynamic source does not cover the whole next local day yet and the local + publication time (``tomorrow_after``, default 13:00, ``UNVERIFIED`` for Tibber and Nord + Pool) has passed: ask again every ``tomorrow_poll_s`` until it does; +* ``retry``: after a failure, with a doubling back-off (``retry_interval_s`` ... one hour). + +Action calls are additionally limited by the connection's per-action rate limiter (at least 30 s +apart); a throttled call is not a failure, the last data stays and the service asks again when +the limiter would admit it. A failed or empty fetch never replaces good data; the data of an +earlier fetch beyond the end of the new data is kept (a source that briefly forgets tomorrow's +prices does not blank them). +""" + +from __future__ import annotations + +import asyncio +from collections.abc import Awaitable, Callable, Iterable, Sequence +from dataclasses import dataclass, field +from datetime import date, datetime, time, timedelta, tzinfo +from typing import Final, Literal, Protocol + +import structlog + +from suncore.core.config import ExportTariff +from suncore.core.series import ( + PLANNING_STEP, + Grid, + PriceSeries, + TimeRange, + floor_to_step, +) +from suncore.core.tariff import PriceFormula +from suncore.tariff.errors import ( + SourceThrottledError, + SourceUnavailableError, + TariffError, +) +from suncore.tariff.parse import ParseReport, clip_series +from suncore.tariff.pricing import export_base_price, planning_prices +from suncore.tariff.report import ( + PriceErrorOut, + PriceFreshness, + PriceQuality, + PriceReport, + PriceSlot, + PriceSourceInfo, +) +from suncore.tariff.sources import SegmentSource, SourceData +from suncore.templates.models import NegativePriceRule + +log = structlog.get_logger(__name__) + +RefreshReason = Literal["initial", "changed", "interval", "tomorrow", "retry", "forced"] + +MIN_HORIZON: Final = timedelta(hours=24) +"""The series is at least this long when a window of it is requested (``None`` beyond the data).""" +FETCH_HORIZON: Final = timedelta(hours=72) +MIN_REFRESH_INTERVAL_S: Final = 60.0 +"""Below the connection's 30 s action floor with margin; a smaller setting is raised.""" +POLL_S: Final = 30.0 + + +class PriceStore(Protocol): + """``TimeseriesStore.store_prices``; ``None`` = do not persist.""" + + async def store_prices(self, prices: PriceSeries) -> int: ... + + +@dataclass(frozen=True, slots=True) +class ServiceSettings: + """Timing of the refresh logic (all configurable, defaults per the Phase 4 plan).""" + + refresh_interval_s: float = 3600.0 + """Tibber and Nord Pool: once per hour.""" + retry_interval_s: float = 300.0 + """First retry after a failure; doubles up to one hour.""" + tomorrow_after: time = time(13, 0) + """Local time from which tomorrow's day-ahead prices are expected (``UNVERIFIED``).""" + tomorrow_poll_s: float = 900.0 + """Spacing of the asks between the publication time and the arrival of tomorrow's prices.""" + + def __post_init__(self) -> None: + if self.refresh_interval_s < MIN_REFRESH_INTERVAL_S: + object.__setattr__(self, "refresh_interval_s", MIN_REFRESH_INTERVAL_S) + if self.retry_interval_s < MIN_REFRESH_INTERVAL_S: + object.__setattr__(self, "retry_interval_s", MIN_REFRESH_INTERVAL_S) + if self.tomorrow_poll_s < MIN_REFRESH_INTERVAL_S: + object.__setattr__(self, "tomorrow_poll_s", MIN_REFRESH_INTERVAL_S) + + +@dataclass(frozen=True, slots=True) +class TariffPlan: + """The configured tariff, resolved: what the service needs to turn source data into prices.""" + + source: SegmentSource + export_tariff: ExportTariff + negative_rule: NegativePriceRule + tz: tzinfo + currency: str + formula: PriceFormula | None = None + total_kwp: float | None = None + + +@dataclass(frozen=True, slots=True) +class RefreshResult: + """Outcome of one :meth:`TariffService.refresh`.""" + + reason: RefreshReason + ok: bool + throttled: bool = False + error: TariffError | None = None + known_until: datetime | None = None + + +@dataclass(slots=True) +class _State: + segments: tuple[PriceSeries, ...] = () + fetched_at: datetime | None = None + report: ParseReport = field(default_factory=ParseReport) + error: TariffError | None = None + failures: int = 0 + retry_at: datetime | None = None + dirty: bool = False + last_attempt: datetime | None = None + """Start of the latest fetch, successful or not.""" + carried: int = 0 + """Slots of the current data that an earlier fetch supplied because the latest had none.""" + + @property + def known_end(self) -> datetime | None: + return max((s.import_price.end for s in self.segments), default=None) + + +def _midnight(day: date, tz: tzinfo) -> datetime: + return datetime.combine(day, time.min, tzinfo=tz) + + +def _value_at(segments: Sequence[PriceSeries], at: datetime) -> float | None: + for series in segments: + ts = series.import_price + if ts.start <= at < ts.end: + return ts.values[int((at - ts.start) // ts.step)] + return None + + +def _fill_gaps( + new: Sequence[PriceSeries], old: Sequence[PriceSeries] +) -> tuple[tuple[PriceSeries, ...], int]: + """``new`` with every unknown slot replaced by the earlier fetch's value (if it had one). + + Returns the segments and how many slots were carried over; a source that suddenly reports + ``None`` for a price it knew an hour ago does not blank it. + """ + carried = 0 + out: list[PriceSeries] = [] + for series in new: + ts = series.import_price + values = list(ts.values) + for i, value in enumerate(values): + if value is None and (kept := _value_at(old, ts.slot_start(i))) is not None: + values[i] = kept + carried += 1 + out.append( + series.model_copy( + update={"import_price": ts.model_copy(update={"values": tuple(values)})} + ) + ) + return tuple(out), carried + + +def _old_tail( + new: Sequence[PriceSeries], old: Sequence[PriceSeries], floor: datetime +) -> list[PriceSeries]: + """The old slots that begin at or after the new data's end (and are not past). + + Each old segment is cut at its own slot boundary (rounded up), so the tail never overlaps + the new data even if the old slots were hourly and the new data ends inside an hour. + """ + new_end = max(s.import_price.end for s in new) + limit = max(new_end, floor) + tail: list[PriceSeries] = [] + for previous in old: + ts = previous.import_price + if previous.price_includes != new[0].price_includes or ts.end <= limit: + continue + first = max(0, -(-(limit - ts.start) // ts.step)) + piece = clip_series(ts, ts.slot_start(first), ts.end) + if piece is not None: + tail.append( + PriceSeries( + source_id=previous.source_id, + price_includes=previous.price_includes, + import_price=piece, + ) + ) + return tail + + +class TariffService: + """Keeps the prices fresh and answers :meth:`prices` / :meth:`report` from the cache.""" + + def __init__( + self, + plan: TariffPlan, + *, + clock: Callable[[], datetime], + store: PriceStore | None = None, + settings: ServiceSettings | None = None, + ) -> None: + self._plan = plan + self._clock = clock + self._store = store + self._settings = settings or ServiceSettings() + self._state = _State() + self._lock = asyncio.Lock() + self._listeners: list[Callable[[], None]] = [] + self._export_base = export_base_price(plan.export_tariff, plan.total_kwp) + self._last_written: tuple[object, ...] | None = None + + # --- identity ---------------------------------------------------------------------- + + @property + def plan(self) -> TariffPlan: + return self._plan + + @property + def watched_entities(self) -> tuple[str, ...]: + return self._plan.source.watched_entities + + def add_listener(self, listener: Callable[[], None]) -> Callable[[], None]: + """Call ``listener`` after every successful refresh (new prices); returns the remover.""" + self._listeners.append(listener) + + def remove() -> None: + if listener in self._listeners: + self._listeners.remove(listener) + + return remove + + # --- when to refresh --------------------------------------------------------------- + + def watched_entities_isdisjoint(self, entity_ids: Iterable[str]) -> bool: + """Whether none of ``entity_ids`` is an entity this service watches.""" + return set(self._plan.source.watched_entities).isdisjoint(entity_ids) + + def reset_backoff(self) -> None: + """Forget the failure back-off (Home Assistant is connected again).""" + self._state.failures = 0 + self._state.retry_at = None + self._state.error = None if self._state.fetched_at is not None else self._state.error + + def notify_changed(self) -> None: + """A watched entity changed state; see ``changed`` in the module docstring.""" + self._state.dirty = True + + def _current_slot_known(self, now: datetime) -> bool: + step = floor_to_step(now) + for series in self._state.segments: + ts = series.import_price + if ts.start <= step < ts.end: + index = int((step - ts.start) // ts.step) + return ts.values[index] is not None + return False + + def _tomorrow_covered(self, now: datetime) -> bool: + end = self._state.known_end + if end is None: + return False + zones = [self._plan.tz] + market = self._plan.source.delivery_tz + if market is not None: + zones.append(market) + # the day-ahead prices stop at the end of tomorrow in the market's zone, which lies + # before the site's midnight west of it (never "covered" otherwise): the earlier counts + deadline = min(_midnight(now.astimezone(z).date() + timedelta(days=2), z) for z in zones) + return end >= deadline + + def _schedule(self, now: datetime) -> tuple[datetime, RefreshReason] | None: + """The earliest time-based refresh (``None`` = nothing scheduled).""" + state = self._state + if state.fetched_at is None: + return (state.retry_at or now, "initial") + candidates: list[tuple[datetime, RefreshReason]] = [ + (state.fetched_at + timedelta(seconds=self._settings.refresh_interval_s), "interval") + ] + if state.retry_at is not None: + candidates.append((state.retry_at, "retry")) + if self._plan.source.kind == "dynamic" and not self._tomorrow_covered(now): + tz = self._plan.tz + published = datetime.combine( + now.astimezone(tz).date(), self._settings.tomorrow_after, tzinfo=tz + ) + earliest = state.fetched_at + timedelta(seconds=self._settings.tomorrow_poll_s) + candidates.append((max(published, earliest), "tomorrow")) + if state.retry_at is not None: + # after a failure or a throttled call only the retry time counts, not the regular + # schedule (which may be overdue because the fetch did not work) + return (state.retry_at, "retry") + return min(candidates, key=lambda c: c[0]) + + def due(self, now: datetime | None = None) -> RefreshReason | None: + """Why a refresh is due now, else ``None``.""" + now = now or self._clock() + state = self._state + in_backoff = state.retry_at is not None and now < state.retry_at + if state.dirty: + source = self._plan.source + recent = state.last_attempt is not None and ( + now - state.last_attempt < timedelta(seconds=POLL_S) + ) + if not source.uses_action and not recent: + return "changed" # reads the entity cache: free (but not in a tight loop) + if ( + state.fetched_at is not None + and not in_backoff + and not self._current_slot_known(now) + ): + return "changed" + scheduled = self._schedule(now) + if scheduled is not None and scheduled[0] <= now: + return scheduled[1] + return None + + def next_refresh(self, now: datetime | None = None) -> datetime | None: + """When the next time-based refresh is due (a state change can only make it earlier).""" + now = now or self._clock() + scheduled = self._schedule(now) + return None if scheduled is None else max(scheduled[0], now) + + # --- refreshing -------------------------------------------------------------------- + + async def tick(self) -> RefreshResult | None: + """One scheduler step: refresh if :meth:`due`.""" + reason = self.due() + return None if reason is None else await self.refresh(reason) + + async def run( + self, + sleep: Callable[[float], Awaitable[None]] = asyncio.sleep, + poll_s: float = POLL_S, + ) -> None: + """Poll :meth:`tick` every ``poll_s`` until cancelled; never raises (errors are state).""" + while True: + try: + await self.tick() + except asyncio.CancelledError: + raise + except Exception: + log.exception("tariff.tick_crashed") + await sleep(poll_s) + + async def refresh(self, reason: RefreshReason = "forced") -> RefreshResult | None: + """Fetch now. ``None`` when another refresh is already running.""" + if self._lock.locked(): + return None + async with self._lock: + now = self._clock() + self._state.last_attempt = now + window = TimeRange(start=floor_to_step(now), end=floor_to_step(now) + FETCH_HORIZON) + try: + data = await self._plan.source.fetch_segments(window, now) + if not any(v is not None for s in data.segments for v in s.import_price.values): + raise SourceUnavailableError("the source returned no price") + self._accept(data, now) + except SourceThrottledError as exc: + self._state.retry_at = now + timedelta(seconds=max(exc.retry_after_s, 1.0)) + return RefreshResult(reason, ok=False, throttled=True, error=exc) + except TariffError as exc: + return self._failed(reason, now, exc) + except Exception as exc: + log.exception("tariff.fetch_crashed", source=self._plan.source.source_id) + return self._failed(reason, now, TariffError(f"{type(exc).__name__}: {exc}")) + await self._persist(now) + for listener in list(self._listeners): + try: + listener() + except Exception: + log.exception("tariff.listener_failed") + return RefreshResult(reason, ok=True, known_until=self._state.known_end) + + def _failed(self, reason: RefreshReason, now: datetime, error: TariffError) -> RefreshResult: + state = self._state + state.failures += 1 + state.error = error + state.dirty = False # this fetch has seen the change; only a newer one counts + backoff = min(3600.0, self._settings.retry_interval_s * 2 ** (state.failures - 1)) + state.retry_at = now + timedelta(seconds=backoff) + log.warning( + "tariff.refresh_failed", + source=self._plan.source.source_id, + reason=reason, + error=error.key, + failures=state.failures, + retry_in_s=backoff, + ) + return RefreshResult(reason, ok=False, error=error) + + def _accept(self, data: SourceData, now: datetime) -> None: + """Take over a fetch: fill its holes from the earlier data, keep the earlier tail. + + Everything is computed before the state is touched, so an error leaves the earlier + data as it was. + """ + old = self._state.segments + filled, carried = _fill_gaps(data.segments, old) + merged = (*filled, *_old_tail(filled, old, floor_to_step(now))) + state = self._state + state.segments = merged + state.fetched_at = now + state.report = data.report + state.carried = carried + state.error = None + state.failures = 0 + state.retry_at = None + state.dirty = False + + async def _persist(self, now: datetime) -> None: + if self._store is None: + return + try: + series = self._trimmed(now) + if series is None: + return + key = ( + series.start, + series.import_price.values, + series.export_price.values if series.export_price else None, + ) + if key == self._last_written: + return + await self._store.store_prices(series) + except Exception: + log.exception("tariff.store_failed", source=self._plan.source.source_id) + return + self._last_written = key + + def _trimmed(self, now: datetime) -> PriceSeries | None: + """The planning prices from now to the end of the known prices without ``None`` edges.""" + grid = self._grid(now, FETCH_HORIZON) + prices, _ = self._planning(grid) + values = prices.import_price.values + known = [i for i, v in enumerate(values) if v is not None] + if not known: + return None + lo, hi = known[0], known[-1] + 1 + export = prices.export_price + return PriceSeries( + source_id=prices.source_id, + price_includes=prices.price_includes, + import_price=prices.import_price.model_copy( + update={"start": prices.import_price.slot_start(lo), "values": values[lo:hi]} + ), + export_price=None + if export is None + else export.model_copy( + update={"start": export.slot_start(lo), "values": export.values[lo:hi]} + ), + ) + + # --- serving ----------------------------------------------------------------------- + + def _grid(self, now: datetime, horizon: timedelta) -> Grid: + """From the interval containing ``now`` to the end of the known prices. + + At least 24 h (``None`` beyond the data) and at most ``horizon``. + """ + end = self._state.known_end + floor = floor_to_step(now) + lower = now + MIN_HORIZON + upper = now + horizon + target = min(lower if end is None else max(end, lower), upper) + count = max(1, -(-(target - floor) // PLANNING_STEP)) + return Grid(start=floor, step=PLANNING_STEP, count=count) + + def _planning(self, grid: Grid) -> tuple[PriceSeries, int]: + plan = self._plan + return planning_prices( + self._state.segments, + grid, + formula=plan.formula, + export_price=self._export_base, + rule=plan.negative_rule, + tz=plan.tz, + source_id=plan.source.source_id, + ) + + def prices(self, hours: float = 48, now: datetime | None = None) -> PriceSeries: + """Import and export prices on the 15-minute grid from now (see :meth:`_grid`).""" + now = now or self._clock() + prices, _ = self._planning(self._grid(now, timedelta(hours=hours))) + return prices + + def report(self, hours: float = 48, now: datetime | None = None) -> PriceReport: + """The API view: prices, source, freshness and quality.""" + now = now or self._clock() + plan, state = self._plan, self._state + grid = self._grid(now, timedelta(hours=hours)) + prices, zeroed = self._planning(grid) + export = prices.export_price + slots = [ + PriceSlot( + start=prices.import_price.slot_start(i), + import_price=v, + export_price=None if export is None else export.values[i], + ) + for i, v in enumerate(prices.import_price.values) + ] + known = sum(s.import_price is not None for s in slots) + native = [s.step for s in state.segments] + has_formula = plan.formula is not None and plan.source.price_includes == "spot_only" + steps = ( + min(native) // timedelta(minutes=1) + if native and plan.source.kind == "dynamic" + else None + ) + return PriceReport( + price_includes=prices.price_includes, + formula_missing=prices.price_includes == "spot_only", + start=grid.start, + slots=slots, + source=PriceSourceInfo( + import_source_id=plan.source.source_id, + import_kind=plan.source.kind, + source_price_includes=plan.source.price_includes, + price_includes=prices.price_includes, + formula_applied=has_formula, + export_kind=plan.export_tariff.kind, + negative_price_rule=plan.negative_rule.value, + export_zeroed_slots=zeroed, + native_step_min=int(steps) if steps is not None else None, + currency=plan.currency, + ), + freshness=self._freshness(now), + quality=PriceQuality( + slots=len(slots), + known_slots=known, + has_tomorrow=self._tomorrow_covered(now), + dropped_points=state.report.unreadable_values + + state.report.duplicates + + state.report.overlaps, + carried_slots=state.carried, + ), + ) + + def _freshness(self, now: datetime) -> PriceFreshness: + state = self._state + error = ( + None + if state.error is None + else PriceErrorOut(key=state.error.key, args=_json_args(state.error)) + ) + age = None if state.fetched_at is None else (now - state.fetched_at).total_seconds() + status: Literal["fresh", "stale", "missing", "static"] + if state.fetched_at is None or not state.segments: + status = "missing" + elif self._plan.source.kind != "dynamic": + status = "static" + else: + limit = 2 * self._settings.refresh_interval_s + status = ( + "fresh" + if (age or 0.0) <= limit and self._current_slot_known(now) and state.error is None + else "stale" + ) + return PriceFreshness( + status=status, + fetched_at=state.fetched_at, + age_s=age, + known_until=state.known_end, + next_refresh_at=self.next_refresh(now), + last_error=error, + ) + + +def _json_args(error: TariffError) -> dict[str, str | float | int | list[str]]: + out: dict[str, str | float | int | list[str]] = {} + for key, value in error.message_args.items(): + if isinstance(value, str | int | float) and not isinstance(value, bool): + out[key] = value + elif isinstance(value, list): + out[key] = [str(v) for v in value] + else: + out[key] = str(value) + return out + + +__all__ = [ + "FETCH_HORIZON", + "MIN_HORIZON", + "PriceStore", + "RefreshReason", + "RefreshResult", + "ServiceSettings", + "TariffPlan", + "TariffService", +] diff --git a/suncore/tariff/sources.py b/suncore/tariff/sources.py new file mode 100644 index 0000000..605cf9d --- /dev/null +++ b/suncore/tariff/sources.py @@ -0,0 +1,162 @@ +# SPDX-License-Identifier: Apache-2.0 +"""Price sources behind one small protocol: fixed, HT/NT and the template-driven adapters. + +A :class:`SegmentSource` returns what it knows for a window as regular segments (a source may +mix 15- and 60-minute slots); :func:`finest_series` turns them into the single +:class:`~suncore.core.series.PriceSeries` that the ``PriceSource`` protocol of +``core/forecast.py`` promises. The :class:`~suncore.tariff.service.TariffService` works with +the segments directly and resamples once onto the planning grid. +""" + +from __future__ import annotations + +from collections.abc import Sequence +from dataclasses import dataclass, field +from datetime import datetime, tzinfo +from typing import Literal, Protocol + +from suncore.core.series import ( + PLANNING_STEP, + Grid, + PriceIncludes, + PriceSeries, + SeriesUnit, + TimeRange, + TimeSeries, + floor_to_step, + resample_prices, +) +from suncore.core.tariff import TouTariff +from suncore.tariff.parse import ParseReport + +SourceKind = Literal["dynamic", "fixed", "tou"] + + +@dataclass(frozen=True, slots=True) +class SourceData: + """What one fetch returned: segments (one source, one ``price_includes``) and the parse + report (what was dropped).""" + + segments: tuple[PriceSeries, ...] + report: ParseReport = field(default_factory=ParseReport) + + @property + def known_end(self) -> datetime | None: + """End of the last segment, ``None`` when nothing was returned.""" + return max((s.import_price.end for s in self.segments), default=None) + + +class SegmentSource(Protocol): + """What the :class:`TariffService` needs from an import price source.""" + + @property + def source_id(self) -> str: ... + + @property + def kind(self) -> SourceKind: ... + + @property + def price_includes(self) -> PriceIncludes: ... + + @property + def uses_action(self) -> bool: + """Whether a fetch calls a Home Assistant action (rate limited) rather than reading + entity attributes.""" + ... + + @property + def watched_entities(self) -> tuple[str, ...]: + """Entities whose state change may mean new prices.""" + ... + + @property + def delivery_tz(self) -> tzinfo | None: + """Time zone of the market's delivery day when it is not the site's (Nord Pool: CET), + else ``None``. The day-ahead prices end at the end of that zone's next day.""" + ... + + async def fetch_segments(self, window: TimeRange, now: datetime) -> SourceData: ... + + +def finest_series( + source_id: str, + price_includes: PriceIncludes, + segments: Sequence[PriceSeries], + window: TimeRange, +) -> PriceSeries: + """One series on the finest native step of ``segments`` (step-hold for coarser ones). + + Without segments: an empty 15-minute series at ``window.start`` (nothing is invented). + """ + if not segments: + empty = TimeSeries(start=window.start, step=PLANNING_STEP, values=(), unit=SeriesUnit.PRICE) + return PriceSeries(source_id=source_id, price_includes=price_includes, import_price=empty) + step = min(s.step for s in segments) + start = floor_to_step(min(s.start for s in segments), step) + end = max(s.import_price.end for s in segments) + count = max(1, -(-(end - start) // step)) + return resample_prices(list(segments), Grid(start=start, step=step, count=count)) + + +def _slots(window: TimeRange) -> tuple[datetime, int]: + start = floor_to_step(window.start) + return start, max(1, -(-(window.end - start) // PLANNING_STEP)) + + +def _static_series( + source_id: str, values: Sequence[float], start: datetime, price_includes: PriceIncludes +) -> SourceData: + series = TimeSeries( + start=start, step=PLANNING_STEP, values=tuple(values), unit=SeriesUnit.PRICE + ) + price = PriceSeries(source_id=source_id, price_includes=price_includes, import_price=series) + return SourceData(segments=(price,), report=ParseReport(points=len(values))) + + +@dataclass(frozen=True, slots=True) +class FixedPriceSource: + """One all-in price per kWh at all times (``tariff.import.kind = fixed``).""" + + price: float + source_id: str = "fixed" + kind: SourceKind = "fixed" + price_includes: PriceIncludes = "all_in" + uses_action: bool = False + watched_entities: tuple[str, ...] = () + delivery_tz: tzinfo | None = None + + async def fetch_segments(self, window: TimeRange, now: datetime) -> SourceData: # noqa: ARG002 + start, count = _slots(window) + return _static_series(self.source_id, [self.price] * count, start, self.price_includes) + + async def fetch(self, window: TimeRange) -> PriceSeries: + data = await self.fetch_segments(window, window.start) + return data.segments[0] + + +@dataclass(frozen=True, slots=True) +class TouPriceSource: + """HT/NT prices from local weekly windows (``tariff.import.kind = tou``). + + A slot is priced at its **start** instant, judged in the site's local time (DST safe: the + slots are absolute 15-minute intervals). A window boundary that is not on a quarter hour + therefore takes effect at the next slot start. + """ + + tou: TouTariff + tz: tzinfo + source_id: str = "tou" + kind: SourceKind = "tou" + price_includes: PriceIncludes = "all_in" + uses_action: bool = False + watched_entities: tuple[str, ...] = () + delivery_tz: tzinfo | None = None + + async def fetch_segments(self, window: TimeRange, now: datetime) -> SourceData: # noqa: ARG002 + start, count = _slots(window) + values = [self.tou.price_at(start + PLANNING_STEP * i, self.tz) for i in range(count)] + return _static_series(self.source_id, values, start, self.price_includes) + + async def fetch(self, window: TimeRange) -> PriceSeries: + data = await self.fetch_segments(window, window.start) + return data.segments[0] diff --git a/suncore/tariff/units.py b/suncore/tariff/units.py new file mode 100644 index 0000000..6483267 --- /dev/null +++ b/suncore/tariff/units.py @@ -0,0 +1,51 @@ +# SPDX-License-Identifier: Apache-2.0 +"""Price units of integrations -> SunCore's ``currency/kWh``. + +Documented additive alias (Phase 4 WP4): EPEX Spot labels its sensors with the *symbol* of the +currency (``"€/kWh"``, ``"£/kWh"``; ``custom_components/epex_spot/const.py:57``, tag ``4.1.0``) +while the template schema's price unit is ``/kWh|MWh``. The template keeps +``{currency}/kWh`` as the unit of the *values* and lists the literal symbols in its matcher +(``units``); :func:`normalise_price_unit` maps the symbol to the ISO code wherever an entity's +unit is compared with a template's (conformance test, wizard). +""" + +from __future__ import annotations + +from typing import Final + +from suncore.templates.models import price_unit_factor + +CURRENCY_SYMBOLS: Final[dict[str, str]] = {"€": "EUR", "£": "GBP"} +"""Currency symbols that integrations put in front of ``/kWh`` (EPEX Spot: EUR and GBP).""" + + +def normalise_price_unit(unit: str) -> str: + """``"€/kWh"`` -> ``"EUR/kWh"``; any other unit is returned unchanged.""" + symbol, sep, rest = unit.strip().partition("/") + return f"{CURRENCY_SYMBOLS[symbol]}{sep}{rest}" if symbol in CURRENCY_SYMBOLS else unit.strip() + + +def resolve_value_unit(unit: str, currency: str) -> str: + """The template's ``{currency}`` placeholder replaced by the region's ISO code.""" + return unit.replace("{currency}", currency) + + +def divisor_to_kwh(unit: str) -> float: + """What to divide a price in ``unit`` by to get currency/kWh (``EUR/MWh`` -> 1000). + + Division (not multiplication by 0.001) keeps ``45.5 / 1000`` the exact nearest double. + Raises ``ValueError`` for a unit that is not ``/kWh|MWh``. + """ + return float(round(1 / price_unit_factor(unit))) + + +def energy_scale(unit: str) -> str | None: + """``"kWh"`` or ``"MWh"`` of a ``/`` unit, else ``None``.""" + _, _, scale = unit.partition("/") + return scale if scale in ("kWh", "MWh") else None + + +def currency_of(unit: str) -> str | None: + """ISO code of a ``/`` unit (a symbol is mapped), else ``None``.""" + code, sep, _ = normalise_price_unit(unit).partition("/") + return code if sep and len(code) == 3 and code.isalpha() and code.isupper() else None diff --git a/suncore/templates/__init__.py b/suncore/templates/__init__.py index 455fa61..6c1c6d3 100644 --- a/suncore/templates/__init__.py +++ b/suncore/templates/__init__.py @@ -20,6 +20,7 @@ ) from suncore.templates.models import ( TEMPLATE_ADAPTER, + ActionParam, ActionSeries, AttributeSeries, BatteryTemplate, @@ -36,6 +37,7 @@ __all__ = [ "TEMPLATE_ADAPTER", + "ActionParam", "ActionSeries", "AttributeSeries", "BatteryTemplate", diff --git a/suncore/templates/models.py b/suncore/templates/models.py index bf12d4b..32dd05e 100644 --- a/suncore/templates/models.py +++ b/suncore/templates/models.py @@ -18,6 +18,7 @@ from enum import StrEnum, unique from functools import lru_cache from typing import Annotated, Final, Literal, Self +from zoneinfo import ZoneInfo, ZoneInfoNotFoundError from pydantic import ( BaseModel, @@ -227,6 +228,10 @@ class SeriesFields(_Frozen): value_field: Text | None = None p10_field: Text | None = None p90_field: Text | None = None + end_field: Text | None = None + """Phase 4 WP4 (price lists): field with the slot *end*; the slot length is ``end - start`` + per point (Nord Pool, EPEX Spot, Octopus). Absent = derive the length from the spacing of + the timestamps or from the template's ``resolution_min``.""" value_unit: Text def require_point_fields(self, where: str) -> None: @@ -267,13 +272,28 @@ def _unique(self) -> Self: if self.shape == "list": f.require_point_fields("series.fields") elif any( - x is not None for x in (f.timestamp_field, f.value_field, f.p10_field, f.p90_field) + x is not None + for x in (f.timestamp_field, f.value_field, f.p10_field, f.p90_field, f.end_field) ): msg = "series.fields: shape `mapping` takes only `value_unit` (keys are the timestamps)" raise ValueError(msg) return self +class ActionParam(_Frozen): + """A field of the action's request that the user's tariff configuration supplies. + + The value comes from ``tariff.import.action_params[name]`` (Phase 4 WP4), e.g. the + Nord Pool ``config_entry`` id or ``areas``. SunCore never invents such a value. + """ + + name: Text + """The action's field name.""" + required: bool = True + description: MessageKey + """i18n key explaining the field to the user.""" + + class ActionSeries(_Frozen): """Series returned by a read-only action (``return_response`` is implied).""" @@ -282,8 +302,20 @@ class ActionSeries(_Frozen): service: Slug start_field: Text | None = None end_field: Text | None = None + date_field: Text | None = None + """Phase 4 WP4: the action takes one delivery *date* (``YYYY-MM-DD``, local date of the + site) per call (Nord Pool ``date``); the adapter calls once for every date of the window. + Excludes ``start_field``/``end_field``.""" + date_tz: ( + Annotated[str, StringConstraints(pattern=r"^[A-Za-z_]+(/[A-Za-z_+\-0-9]+){1,2}$")] | None + ) = None + """IANA zone in which ``date_field`` names the delivery day (the market's, e.g. Nord Pool's + CET day: ``Europe/Berlin``); ``None`` = the site's zone.""" + params: Annotated[tuple[ActionParam, ...], Field(max_length=8)] = () + """Request fields the user supplies (see :class:`ActionParam`).""" response_path: Annotated[ - str, StringConstraints(pattern=r"^[A-Za-z0-9_]+(\.([A-Za-z0-9_]+|\*))*$", max_length=200) + str, + StringConstraints(pattern=r"^(\*|[A-Za-z0-9_]+)(\.([A-Za-z0-9_]+|\*))*$", max_length=200), ] """Dotted path into the response; a ``*`` segment means every value of that mapping.""" fields: SeriesFields @@ -292,6 +324,28 @@ class ActionSeries(_Frozen): @model_validator(mode="after") def _allowed(self) -> Self: self.fields.require_point_fields("series.fields") + if self.date_field is not None and ( + self.start_field is not None or self.end_field is not None + ): + msg = "series: `date_field` excludes `start_field` and `end_field`" + raise ValueError(msg) + if self.date_tz is not None: + if self.date_field is None: + msg = "series: `date_tz` needs `date_field`" + raise ValueError(msg) + try: + ZoneInfo(self.date_tz) + except (ZoneInfoNotFoundError, ValueError, OSError) as exc: + msg = f"series.date_tz: unknown time zone `{self.date_tz}`" + raise ValueError(msg) from exc + names = [p.name for p in self.params] + if len(set(names)) != len(names): + msg = "series.params: names must be unique" + raise ValueError(msg) + reserved = {self.date_field, self.start_field, self.end_field} - {None} + if reserved & set(names): + msg = "series.params: a parameter cannot reuse a date, start or end field" + raise ValueError(msg) if not is_read_only_action(self.domain, self.service): msg = ( f"{ERR_ACTION_NOT_ALLOWED}: `{self.domain}.{self.service}` is not on the " @@ -528,7 +582,12 @@ def _tariff(self) -> Self: return self def message_keys(self) -> list[str]: - return [self.name, *(r.description for r in self.roles.values())] + params = ( + [p.description for p in self.price_series.params] + if isinstance(self.price_series, ActionSeries) + else [] + ) + return [self.name, *(r.description for r in self.roles.values()), *params] # --- forecast ---------------------------------------------------------------- diff --git a/templates/README.md b/templates/README.md index 04f25ce..a1eb70c 100644 --- a/templates/README.md +++ b/templates/README.md @@ -26,6 +26,11 @@ drift). | device | `generic.water_heater_steps` | water heater with power levels through one select entity, optional tank probe | generic, simulator only (`UNVERIFIED`: no hardware) | | device | `generic.water_heater_relays` | water heater with 1-3 heating elements switched by relays | generic, simulator only (`UNVERIFIED`: no hardware) | | tariff | `tibber.price` | Tibber dynamic price, curve from `tibber.get_prices` | from integration source | +| tariff | `nordpool.price` | Nord Pool day-ahead prices per area, one `nordpool.get_prices_for_date` call per date, per MWh, excl. VAT and fees | from integration source, `config_entry` entered by the user | +| tariff | `entsoe.price`, `entsoe.price_mwh` | ENTSO-E (HACS) `prices` attribute of the average-price sensor, kWh or MWh scale | from integration source; includes VAT and fees only if the user set them up | +| tariff | `epex_spot.total_price`, `epex_spot.market_price` | EPEX Spot (HACS) `data` attribute: all-in total price or bare market price, unit `€/kWh` | from integration source | +| tariff | `octopus_energy.rates` | Octopus Energy (HACS) `rates` attribute of the current-day and next-day event entities, GBP/kWh incl. VAT | from integration source | +| tariff | `generic.price_list` | any sensor with a `prices` attribute `[{start, price}]` (SunCore's own convention) | generic | | forecast | `solcast.pv` | Solcast PV Forecast (HACS), `detailedForecast` P10/P50/P90 of today, tomorrow, d3, d4; fallback action `query_forecast_data` | from integration source (tag v4.6.1) | | forecast | `forecast_solar.pv` | Forecast.Solar (core), hourly Wh through `energy/solar_forecast` (only if linked in the Energy dashboard), P50 only | from integration source, `UNVERIFIED` timestamp semantics | | forecast | `open_meteo_solar_forecast.pv` | Open-Meteo Solar Forecast (HACS), `wh_period_15m` (Wh per 15 min), P50 only | from integration source (tag 0.1.33) | @@ -73,7 +78,7 @@ unverified: [] # facts you could not verify; required if tes - Tariff and forecast curves come from `series`: an entity attribute (`source: attribute`, lists of the given roles are concatenated) or the response of a read-only action (`source: action`). Only actions on the built-in allowlist - (`suncore/core/actions.py`, currently `tibber.get_prices`, + (`suncore/core/actions.py`, currently `tibber.get_prices`, `nordpool.get_prices_for_date`, `solcast_solar.query_forecast_data`, `weather.get_forecasts`) are accepted; any other service is refused at load time with the key `template.error.action_not_allowed`. Power units in a forecast mean the average power over the slot, energy units the energy @@ -144,4 +149,5 @@ Every addition is recorded below with the SunCore version that introduced it. | 0.3.0 (unreleased, Phase 2) | `region.currency` is optional for `country: generic` (`None` = currency of the Home Assistant configuration). | | 0.4.0 (unreleased, Phase 3) | New `defaults.control` kind `relays` (additive union member, ADR-0012 policy): 1–3 switch roles (`roles`) and `steps`, each step naming the relays that are on (`relays`) and the power it draws (`power_w`, strictly increasing, relay sets distinct). `DeviceConfig` accepts the same control. Used by `generic.water_heater_relays`. | | 0.5.0 (unreleased, Phase 4) | New template kind `battery` (`battery.schema.json`): `roles`, `controls` (union on `kind`: `min_soc`, `max_charge`, `max_discharge`, `grid_charge_power` numbers; `mode` select with option meanings; `force_charge` switch), optional `settle_s`. New capabilities `battery_soc`, `min_soc_limit`, `charge_limit`, `discharge_limit`, `grid_charge`, `battery_modes`. `series` of `source: attribute` takes an optional `list_path` for the generic attribute adapter and an optional `shape` (`list` default, or `mapping` for `{iso_timestamp: value}` attributes such as Forecast.Solar `wh_hours` and Open-Meteo Solar Forecast `wh_period_15m`; `fields` then holds only `value_unit`, so `fields.timestamp_field`/`value_field` became optional and are required only for lists of point objects). Tariff `price_unit` and `price_series.fields.value_unit` may be per MWh (`{currency}/MWh`, `EUR/MWh`); the value unit's currency must match `price_unit`'s (or be `{currency}`), and adapters convert to currency/kWh (`price_unit_factor`: MWh / 1000). Battery mode option `value` is kept verbatim (no whitespace stripping). HT/NT needs no template change: time windows and prices are contract data in the `tariff` configuration section (v3). | +| 0.5.0 (unreleased, Phase 4, WP4) | Tariff price curves (all additive): `series.fields.end_field` (slot end, slot length = `end - start`; lists only); action series take `date_field` (one call per delivery date, excludes `start_field`/`end_field`) with an optional `date_tz` (IANA zone of that delivery day, e.g. Nord Pool's CET day; default the site's zone) and `params` (`name`, `required`, `description` i18n key: request fields the user supplies in the tariff configuration, e.g. Nord Pool `config_entry`, `areas`, `currency`); `response_path` may start with `*` (every entry of the response, e.g. `*` for `{area: [...]}`); the read-only action allowlist gains `nordpool.get_prices_for_date`. The `tariff` configuration section (v3) gains optional `import.role_entities`, `import.action_params`, `import.series_key` and `import.price_includes` (the user's statement overriding the template's classification). Eight tariff templates: `tibber.price` (updated), `nordpool.price`, `entsoe.price`, `entsoe.price_mwh`, `epex_spot.total_price`, `epex_spot.market_price`, `octopus_energy.rates`, `generic.price_list`. The currency symbols `€`/`£` that EPEX Spot puts in front of `/kWh` need no schema change: the matcher lists the literal units and `suncore.tariff.units.normalise_price_unit` maps them to ISO codes. | | 0.5.0 (unreleased, Phase 4, PV forecasts) | Forecast templates: `series.source: energy_solar_forecast` (new union member, `fields` holds only `value_unit`, optional `missing_is_zero`) for the Energy dashboard's `energy/solar_forecast`; optional `fallback_series` (an `action` series) used when the attribute yields nothing. New templates `forecast_solar.pv`, `open_meteo_solar_forecast.pv`, `generic.pv_forecast`; `solcast.pv` gained the optional roles `forecast_d3`, `forecast_d4` and the fallback action `query_forecast_data`. | diff --git a/templates/schema/forecast.schema.json b/templates/schema/forecast.schema.json index e09b09c..100b1dd 100644 --- a/templates/schema/forecast.schema.json +++ b/templates/schema/forecast.schema.json @@ -1,9 +1,65 @@ { "$defs": { + "ActionParam": { + "additionalProperties": false, + "description": "A field of the action's request that the user's tariff configuration supplies.\n\nThe value comes from ``tariff.import.action_params[name]`` (Phase 4 WP4), e.g. the\nNord Pool ``config_entry`` id or ``areas``. SunCore never invents such a value.", + "properties": { + "description": { + "maxLength": 120, + "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+$", + "title": "Description", + "type": "string" + }, + "name": { + "maxLength": 200, + "minLength": 1, + "title": "Name", + "type": "string" + }, + "required": { + "default": true, + "title": "Required", + "type": "boolean" + } + }, + "required": [ + "name", + "description" + ], + "title": "ActionParam", + "type": "object" + }, "ActionSeries": { "additionalProperties": false, "description": "Series returned by a read-only action (``return_response`` is implied).", "properties": { + "date_field": { + "anyOf": [ + { + "maxLength": 200, + "minLength": 1, + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Date Field" + }, + "date_tz": { + "anyOf": [ + { + "pattern": "^[A-Za-z_]+(/[A-Za-z_+\\-0-9]+){1,2}$", + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Date Tz" + }, "domain": { "maxLength": 48, "pattern": "^[a-z][a-z0-9_]*$", @@ -33,9 +89,18 @@ "title": "Max Horizon H", "type": "integer" }, + "params": { + "default": [], + "items": { + "$ref": "#/$defs/ActionParam" + }, + "maxItems": 8, + "title": "Params", + "type": "array" + }, "response_path": { "maxLength": 200, - "pattern": "^[A-Za-z0-9_]+(\\.([A-Za-z0-9_]+|\\*))*$", + "pattern": "^(\\*|[A-Za-z0-9_]+)(\\.([A-Za-z0-9_]+|\\*))*$", "title": "Response Path", "type": "string" }, @@ -352,6 +417,20 @@ "additionalProperties": false, "description": "Names of the fields of one series point and the unit of its values.\n\n``timestamp_field`` and ``value_field`` are required for a list of point objects\n(``action`` series, ``attribute`` series of shape ``list``) and absent for an\n``attribute`` series of shape ``mapping``, whose keys are the timestamps and whose\nvalues are the values.", "properties": { + "end_field": { + "anyOf": [ + { + "maxLength": 200, + "minLength": 1, + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "End Field" + }, "p10_field": { "anyOf": [ { diff --git a/templates/schema/tariff.schema.json b/templates/schema/tariff.schema.json index f3ce82a..ad01729 100644 --- a/templates/schema/tariff.schema.json +++ b/templates/schema/tariff.schema.json @@ -1,9 +1,65 @@ { "$defs": { + "ActionParam": { + "additionalProperties": false, + "description": "A field of the action's request that the user's tariff configuration supplies.\n\nThe value comes from ``tariff.import.action_params[name]`` (Phase 4 WP4), e.g. the\nNord Pool ``config_entry`` id or ``areas``. SunCore never invents such a value.", + "properties": { + "description": { + "maxLength": 120, + "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+$", + "title": "Description", + "type": "string" + }, + "name": { + "maxLength": 200, + "minLength": 1, + "title": "Name", + "type": "string" + }, + "required": { + "default": true, + "title": "Required", + "type": "boolean" + } + }, + "required": [ + "name", + "description" + ], + "title": "ActionParam", + "type": "object" + }, "ActionSeries": { "additionalProperties": false, "description": "Series returned by a read-only action (``return_response`` is implied).", "properties": { + "date_field": { + "anyOf": [ + { + "maxLength": 200, + "minLength": 1, + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Date Field" + }, + "date_tz": { + "anyOf": [ + { + "pattern": "^[A-Za-z_]+(/[A-Za-z_+\\-0-9]+){1,2}$", + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Date Tz" + }, "domain": { "maxLength": 48, "pattern": "^[a-z][a-z0-9_]*$", @@ -33,9 +89,18 @@ "title": "Max Horizon H", "type": "integer" }, + "params": { + "default": [], + "items": { + "$ref": "#/$defs/ActionParam" + }, + "maxItems": 8, + "title": "Params", + "type": "array" + }, "response_path": { "maxLength": 200, - "pattern": "^[A-Za-z0-9_]+(\\.([A-Za-z0-9_]+|\\*))*$", + "pattern": "^(\\*|[A-Za-z0-9_]+)(\\.([A-Za-z0-9_]+|\\*))*$", "title": "Response Path", "type": "string" }, @@ -327,6 +392,20 @@ "additionalProperties": false, "description": "Names of the fields of one series point and the unit of its values.\n\n``timestamp_field`` and ``value_field`` are required for a list of point objects\n(``action`` series, ``attribute`` series of shape ``list``) and absent for an\n``attribute`` series of shape ``mapping``, whose keys are the timestamps and whose\nvalues are the values.", "properties": { + "end_field": { + "anyOf": [ + { + "maxLength": 200, + "minLength": 1, + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "End Field" + }, "p10_field": { "anyOf": [ { diff --git a/templates/schema/template.schema.json b/templates/schema/template.schema.json index c1d997f..8fe0013 100644 --- a/templates/schema/template.schema.json +++ b/templates/schema/template.schema.json @@ -1,9 +1,65 @@ { "$defs": { + "ActionParam": { + "additionalProperties": false, + "description": "A field of the action's request that the user's tariff configuration supplies.\n\nThe value comes from ``tariff.import.action_params[name]`` (Phase 4 WP4), e.g. the\nNord Pool ``config_entry`` id or ``areas``. SunCore never invents such a value.", + "properties": { + "description": { + "maxLength": 120, + "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+$", + "title": "Description", + "type": "string" + }, + "name": { + "maxLength": 200, + "minLength": 1, + "title": "Name", + "type": "string" + }, + "required": { + "default": true, + "title": "Required", + "type": "boolean" + } + }, + "required": [ + "name", + "description" + ], + "title": "ActionParam", + "type": "object" + }, "ActionSeries": { "additionalProperties": false, "description": "Series returned by a read-only action (``return_response`` is implied).", "properties": { + "date_field": { + "anyOf": [ + { + "maxLength": 200, + "minLength": 1, + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Date Field" + }, + "date_tz": { + "anyOf": [ + { + "pattern": "^[A-Za-z_]+(/[A-Za-z_+\\-0-9]+){1,2}$", + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Date Tz" + }, "domain": { "maxLength": 48, "pattern": "^[a-z][a-z0-9_]*$", @@ -33,9 +89,18 @@ "title": "Max Horizon H", "type": "integer" }, + "params": { + "default": [], + "items": { + "$ref": "#/$defs/ActionParam" + }, + "maxItems": 8, + "title": "Params", + "type": "array" + }, "response_path": { "maxLength": 200, - "pattern": "^[A-Za-z0-9_]+(\\.([A-Za-z0-9_]+|\\*))*$", + "pattern": "^(\\*|[A-Za-z0-9_]+)(\\.([A-Za-z0-9_]+|\\*))*$", "title": "Response Path", "type": "string" }, @@ -1527,6 +1592,20 @@ "additionalProperties": false, "description": "Names of the fields of one series point and the unit of its values.\n\n``timestamp_field`` and ``value_field`` are required for a list of point objects\n(``action`` series, ``attribute`` series of shape ``list``) and absent for an\n``attribute`` series of shape ``mapping``, whose keys are the timestamps and whose\nvalues are the values.", "properties": { + "end_field": { + "anyOf": [ + { + "maxLength": 200, + "minLength": 1, + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "End Field" + }, "p10_field": { "anyOf": [ { diff --git a/templates/tariff/entsoe.price.yaml b/templates/tariff/entsoe.price.yaml new file mode 100644 index 0000000..6a6ccc9 --- /dev/null +++ b/templates/tariff/entsoe.price.yaml @@ -0,0 +1,50 @@ +# yaml-language-server: $schema=../schema/tariff.schema.json +# ENTSO-E (HACS `JaccoR/hass-entso-e`, domain `entsoe`). The price list sits on the "Average +# electricity price" sensor (`avg_price`) in the attribute `prices` (today and tomorrow): +# `[{"time": "2026-10-16 00:00:00+02:00", "price": 0.123}]`, local `str(datetime)`, slot start. +# Slot length = the integration's configured period (60 or 15 minutes), derived from the +# spacing. Unit `/kWh` (default scale). The integration adds the user's modifier +# template and VAT to the price: it is the market price only if the user configured none; say +# so with `price_includes` in the tariff configuration. For the `MWh` scale use +# `entsoe.price_mwh`. +id: entsoe.price +kind: tariff +schema_version: 1 +name: template.entsoe.price.name +source: + - title: "hass-entso-e v0.7.5 sensor.py (avg_price sensor with prices, prices_today, prices_tomorrow)" + url: "https://github.com/JaccoR/hass-entso-e/blob/v0.7.5/custom_components/entsoe/sensor.py" + date: 2026-10-16 + - title: "hass-entso-e v0.7.5 coordinator.py (entry shape {time, price}, calc_price)" + url: "https://github.com/JaccoR/hass-entso-e/blob/v0.7.5/custom_components/entsoe/coordinator.py" + date: 2026-10-16 + - title: "hass-entso-e v0.7.5 const.py (period PT60M or PT15M, energy scale kWh or MWh)" + url: "https://github.com/JaccoR/hass-entso-e/blob/v0.7.5/custom_components/entsoe/const.py" + date: 2026-10-16 +tested_with: [] +capabilities: [price_now, price_curve] +unverified: + - Read from the integration source (tag v0.7.5, commit cbdf67ac) only; not observed on a running Home Assistant. + - 'Entity id and translation key of the `avg_price` sensor: the role matches platform and unit only; pick "Average electricity price", the only sensor with the price list.' + - '`spot_only` is right for an installation without modifier template and VAT; otherwise the price is an end price and the user states `price_includes: all_in` (else the formula counts fees twice).' + - '`prices` holds today and tomorrow, or yesterday and today while tomorrow is unpublished; SunCore keeps only the future part.' +direction: import +tariff_type: dynamic +roles: + price: + matcher: + domain: sensor + platforms: [entsoe] + unit_pattern: '^[A-Z]{3}/kWh$' + description: template.entsoe.price.role.price +price_unit: "{currency}/kWh" +price_includes: spot_only +price_series: + source: attribute + roles: [price] + attribute: prices + shape: list + fields: + timestamp_field: time + value_field: price + value_unit: "{currency}/kWh" diff --git a/templates/tariff/entsoe.price_mwh.yaml b/templates/tariff/entsoe.price_mwh.yaml new file mode 100644 index 0000000..8b02bb0 --- /dev/null +++ b/templates/tariff/entsoe.price_mwh.yaml @@ -0,0 +1,51 @@ +# yaml-language-server: $schema=../schema/tariff.schema.json +# ENTSO-E (HACS `JaccoR/hass-entso-e`, domain `entsoe`). The price list sits on the "Average +# electricity price" sensor (`avg_price`) in the attribute `prices` (today and tomorrow): +# `[{"time": "2026-10-16 00:00:00+02:00", "price": 0.123}]`, local `str(datetime)`, slot start. +# Slot length = the integration's configured period (60 or 15 minutes), derived from the +# spacing. Unit `/MWh`: this template is for an installation configured with the +# `MWh` energy scale (the sensor unit says `/MWh`); the default scale is +# `entsoe.price`. The integration adds the user's modifier template and VAT to the price: it +# is the market price only if the user configured none; say so with `price_includes` in the +# tariff configuration. +id: entsoe.price_mwh +kind: tariff +schema_version: 1 +name: template.entsoe.price_mwh.name +source: + - title: "hass-entso-e v0.7.5 sensor.py (avg_price sensor with prices, prices_today, prices_tomorrow)" + url: "https://github.com/JaccoR/hass-entso-e/blob/v0.7.5/custom_components/entsoe/sensor.py" + date: 2026-10-16 + - title: "hass-entso-e v0.7.5 coordinator.py (entry shape {time, price}, calc_price)" + url: "https://github.com/JaccoR/hass-entso-e/blob/v0.7.5/custom_components/entsoe/coordinator.py" + date: 2026-10-16 + - title: "hass-entso-e v0.7.5 const.py (period PT60M or PT15M, energy scale kWh or MWh)" + url: "https://github.com/JaccoR/hass-entso-e/blob/v0.7.5/custom_components/entsoe/const.py" + date: 2026-10-16 +tested_with: [] +capabilities: [price_now, price_curve] +unverified: + - Read from the integration source (tag v0.7.5, commit cbdf67ac) only; not observed on a running Home Assistant. + - 'Entity id and translation key of the `avg_price` sensor: the role matches platform and unit only; pick "Average electricity price", the only sensor with the price list.' + - '`spot_only` is right for an installation without modifier template and VAT; otherwise the price is an end price and the user states `price_includes: all_in` (else the formula counts fees twice).' + - '`prices` holds today and tomorrow, or yesterday and today while tomorrow is unpublished; SunCore keeps only the future part.' +direction: import +tariff_type: dynamic +roles: + price: + matcher: + domain: sensor + platforms: [entsoe] + unit_pattern: '^[A-Z]{3}/MWh$' + description: template.entsoe.price_mwh.role.price +price_unit: "{currency}/MWh" +price_includes: spot_only +price_series: + source: attribute + roles: [price] + attribute: prices + shape: list + fields: + timestamp_field: time + value_field: price + value_unit: "{currency}/MWh" diff --git a/templates/tariff/epex_spot.market_price.yaml b/templates/tariff/epex_spot.market_price.yaml new file mode 100644 index 0000000..fa53052 --- /dev/null +++ b/templates/tariff/epex_spot.market_price.yaml @@ -0,0 +1,51 @@ +# yaml-language-server: $schema=../schema/tariff.schema.json +# EPEX Spot (HACS `mampfes/ha_epex_spot`, domain `epex_spot`). The "Total Price" sensor carries +# the whole curve in the attribute `data`: `[{"start_time", "end_time", "price_per_kwh"}]` +# (local ISO 8601, `price_per_kwh` for EUR and GBP alike). "Market Price" is the bare +# market price (the source clients convert MWh to kWh): without surcharges and VAT, so a price +# formula in the tariff configuration turns it into the end price. For the price including +# the integration's surcharges use `epex_spot.total_price`. +# Sensor unit: the currency SYMBOL (`€/kWh`, `£/kWh`), not the ISO code - the matcher lists the +# literals, SunCore maps them to EUR/GBP (`suncore.tariff.units`). +id: epex_spot.market_price +kind: tariff +schema_version: 1 +name: template.epex_spot.market_price.name +source: + - title: "ha_epex_spot 4.1.0 sensor.py (Total Price and Market Price sensors, data attribute)" + url: "https://github.com/mampfes/ha_epex_spot/blob/4.1.0/custom_components/epex_spot/sensor.py" + date: 2026-10-16 + - title: "ha_epex_spot 4.1.0 const.py (attribute names, unit literals)" + url: "https://github.com/mampfes/ha_epex_spot/blob/4.1.0/custom_components/epex_spot/const.py" + date: 2026-10-16 + - title: "ha_epex_spot 4.1.0 SourceShell.py (to_total_price: surcharges and VAT)" + url: "https://github.com/mampfes/ha_epex_spot/blob/4.1.0/custom_components/epex_spot/SourceShell.py" + date: 2026-10-16 +tested_with: [] +capabilities: [price_now, price_curve] +unverified: + - "Read from the integration source (tag 4.1.0, commit 2aad1eb7) only; not observed on a running Home Assistant." + - "Entity ids and translation keys: the role matches platform and the unit literal only; \"Total Price\" and \"Market Price\" share the unit, so both are candidates and the user picks \"Market Price\"." + - "Which sources deliver a bare market price in this sensor was read from the source clients only (MWh converted to kWh)." + - "Slot length is `end_time - start_time` (configurable per entry, 60 minutes by default, 15 or 60 for Energy-Charts)." +direction: import +tariff_type: dynamic +roles: + price: + matcher: + domain: sensor + platforms: [epex_spot] + units: ["€/kWh", "£/kWh"] + description: template.epex_spot.market_price.role.price +price_unit: "{currency}/kWh" +price_includes: spot_only +price_series: + source: attribute + roles: [price] + attribute: data + shape: list + fields: + timestamp_field: start_time + end_field: end_time + value_field: price_per_kwh + value_unit: "{currency}/kWh" diff --git a/templates/tariff/epex_spot.total_price.yaml b/templates/tariff/epex_spot.total_price.yaml new file mode 100644 index 0000000..7d3f85e --- /dev/null +++ b/templates/tariff/epex_spot.total_price.yaml @@ -0,0 +1,50 @@ +# yaml-language-server: $schema=../schema/tariff.schema.json +# EPEX Spot (HACS `mampfes/ha_epex_spot`, domain `epex_spot`). The "Total Price" sensor carries +# the whole curve in the attribute `data`: `[{"start_time", "end_time", "price_per_kwh"}]` +# (local ISO 8601, `price_per_kwh` for EUR and GBP alike). "Total Price" is the market price +# plus the percentage and absolute surcharges the user configured, times (1 + VAT): an all-in +# price, no price formula on top. For the bare market price use `epex_spot.market_price`. +# Sensor unit: the currency SYMBOL (`€/kWh`, `£/kWh`), not the ISO code - the matcher lists the +# literals, SunCore maps them to EUR/GBP (`suncore.tariff.units`). +id: epex_spot.total_price +kind: tariff +schema_version: 1 +name: template.epex_spot.total_price.name +source: + - title: "ha_epex_spot 4.1.0 sensor.py (Total Price and Market Price sensors, data attribute)" + url: "https://github.com/mampfes/ha_epex_spot/blob/4.1.0/custom_components/epex_spot/sensor.py" + date: 2026-10-16 + - title: "ha_epex_spot 4.1.0 const.py (attribute names, unit literals)" + url: "https://github.com/mampfes/ha_epex_spot/blob/4.1.0/custom_components/epex_spot/const.py" + date: 2026-10-16 + - title: "ha_epex_spot 4.1.0 SourceShell.py (to_total_price: surcharges and VAT)" + url: "https://github.com/mampfes/ha_epex_spot/blob/4.1.0/custom_components/epex_spot/SourceShell.py" + date: 2026-10-16 +tested_with: [] +capabilities: [price_now, price_curve] +unverified: + - "Read from the integration source (tag 4.1.0, commit 2aad1eb7) only; not observed on a running Home Assistant." + - "Entity ids and translation keys: the role matches platform and the unit literal only; \"Total Price\" and \"Market Price\" share the unit, so both are candidates and the user picks \"Total Price\"." + - "The Tibber source of the integration returns its price as is (no surcharges); the total sensor is then Tibber's own price." + - "Slot length is `end_time - start_time` (configurable per entry, 60 minutes by default, 15 or 60 for Energy-Charts)." +direction: import +tariff_type: dynamic +roles: + price: + matcher: + domain: sensor + platforms: [epex_spot] + units: ["€/kWh", "£/kWh"] + description: template.epex_spot.total_price.role.price +price_unit: "{currency}/kWh" +price_includes: all_in +price_series: + source: attribute + roles: [price] + attribute: data + shape: list + fields: + timestamp_field: start_time + end_field: end_time + value_field: price_per_kwh + value_unit: "{currency}/kWh" diff --git a/templates/tariff/generic.price_list.yaml b/templates/tariff/generic.price_list.yaml new file mode 100644 index 0000000..d432ec6 --- /dev/null +++ b/templates/tariff/generic.price_list.yaml @@ -0,0 +1,38 @@ +# yaml-language-server: $schema=../schema/tariff.schema.json +# Generic price list: any sensor with an attribute `prices` that is a list of +# `{"start": , "price": }`. This is SunCore's +# own convention for a template sensor the user writes (no integration is known to produce +# it); the slot length is derived from the spacing of `start`. +id: generic.price_list +kind: tariff +schema_version: 1 +name: template.generic.price_list.name +source: + - title: "Home Assistant template sensor (attributes option)" + url: "https://www.home-assistant.io/integrations/template/" + date: 2026-10-16 +tested_with: [] +capabilities: [price_now, price_curve] +unverified: + - "SunCore's own convention, not the shape of an existing integration: the attribute name `prices` and the fields `start` and `price` are defined here." + - "The Home Assistant template integration page could not be read in the authoring session (documentation sites unreachable); that template sensors accept attributes is general knowledge, not verified." + - "The price is treated as the end price (`all_in`); a spot-only list needs its own template." +direction: import +tariff_type: dynamic +roles: + price: + matcher: + domain: sensor + unit_pattern: '^[A-Z]{3}/kWh$' + description: template.generic.price_list.role.price +price_unit: "{currency}/kWh" +price_includes: all_in +price_series: + source: attribute + roles: [price] + attribute: prices + shape: list + fields: + timestamp_field: start + value_field: price + value_unit: "{currency}/kWh" diff --git a/templates/tariff/nordpool.price.yaml b/templates/tariff/nordpool.price.yaml new file mode 100644 index 0000000..1d0b59d --- /dev/null +++ b/templates/tariff/nordpool.price.yaml @@ -0,0 +1,66 @@ +# yaml-language-server: $schema=../schema/tariff.schema.json +# Nord Pool (core integration `nordpool`, cloud polling). Day-ahead market prices per area +# from the read-only action `nordpool.get_prices_for_date` (one call per delivery date): +# response `{"": [{"start", "end", "price"}]}`, UTC with `+00:00`, currency per MWh, +# VAT, grid fees and levies NOT included (`spot_only`): add a price formula in the tariff +# configuration. `date` is the CET delivery day (`date_tz`). Slot length is `end - start` (15 or 60 minutes, a series may mix both). +id: nordpool.price +kind: tariff +schema_version: 1 +name: template.nordpool.price.name +source: + - title: "home-assistant/core nordpool services.py (get_prices_for_date, response shape)" + url: "https://github.com/home-assistant/core/blob/5cfe9aad/homeassistant/components/nordpool/services.py" + date: 2026-10-16 + - title: "home-assistant/core nordpool services.yaml (config_entry, date, areas, currency)" + url: "https://github.com/home-assistant/core/blob/5cfe9aad/homeassistant/components/nordpool/services.yaml" + date: 2026-10-16 + - title: "home-assistant/core nordpool sensor.py (currency/kWh sensors, slot length end - start)" + url: "https://github.com/home-assistant/core/blob/5cfe9aad/homeassistant/components/nordpool/sensor.py" + date: 2026-10-16 + - title: "pynordpool 0.4.0 (PyPI wheel: model.py, util.py)" + url: "https://pypi.org/project/pynordpool/0.4.0/" + date: 2026-10-16 +tested_with: [] +capabilities: [price_now, price_curve] +unverified: + - Read from the integration source (core 5cfe9aad, pynordpool 0.4.0) only; not observed on a running Home Assistant. + - 'Entity ids and translation keys of the price sensors: all carry `/kWh`, so the role matches platform and unit only and the user picks the current price sensor.' + - Exact publication time of tomorrow's prices (afternoon CET expected); before it the action returns an empty list for that date. + - The action accepts dates from two months back to one day ahead (strings.json); SunCore asks for today and tomorrow only. + - The price is the raw day-ahead value in currency per MWh of the entry's currency (or the optional `currency` field); the integration's exchange-rate handling was not read. + - The `config_entry` id has to be entered by the user; which registry command exposes it to SunCore was not verified. +direction: import +tariff_type: dynamic +roles: + price: + matcher: + domain: sensor + platforms: [nordpool] + unit_pattern: '^[A-Z]{3}/kWh$' + description: template.nordpool.price.role.price +price_unit: "{currency}/MWh" +price_includes: spot_only +price_series: + source: action + domain: nordpool + service: get_prices_for_date + date_field: date + date_tz: Europe/Berlin + params: + - name: config_entry + required: true + description: template.nordpool.price.param.config_entry + - name: areas + required: false + description: template.nordpool.price.param.areas + - name: currency + required: false + description: template.nordpool.price.param.currency + response_path: "*" + fields: + timestamp_field: start + end_field: end + value_field: price + value_unit: "{currency}/MWh" + max_horizon_h: 24 diff --git a/templates/tariff/octopus_energy.rates.yaml b/templates/tariff/octopus_energy.rates.yaml new file mode 100644 index 0000000..3595765 --- /dev/null +++ b/templates/tariff/octopus_energy.rates.yaml @@ -0,0 +1,64 @@ +# yaml-language-server: $schema=../schema/tariff.schema.json +# Octopus Energy (HACS `BottlecapDave/HomeAssistant-OctopusEnergy`, domain `octopus_energy`). +# The rate lists are on EVENT entities (`..._current_day_rates`, `..._next_day_rates`), not on +# the rate sensors: core's EventEntity exposes the last event's data as attributes, so the +# attribute `rates` holds `[{"start", "end", "value_inc_vat"}]` (local datetimes, GBP/kWh +# including VAT). SunCore merges the current and the next day by `start`. The slot length is +# `end - start` (30 minutes for the usual tariffs). Import rates only; export rates have their +# own `..._export_...` entities and are not a price source of this template. +id: octopus_energy.rates +kind: tariff +schema_version: 1 +name: template.octopus_energy.rates.name +source: + - title: "HomeAssistant-OctopusEnergy v19.2.1 electricity/rates_current_day.py (event entity, rates)" + url: "https://github.com/BottlecapDave/HomeAssistant-OctopusEnergy/blob/v19.2.1/custom_components/octopus_energy/electricity/rates_current_day.py" + date: 2026-10-16 + - title: "HomeAssistant-OctopusEnergy v19.2.1 utils/__init__.py (private_rates_to_public_rates: start, end, value_inc_vat)" + url: "https://github.com/BottlecapDave/HomeAssistant-OctopusEnergy/blob/v19.2.1/custom_components/octopus_energy/utils/__init__.py" + date: 2026-10-16 + - title: "HomeAssistant-OctopusEnergy v19.2.1 electricity/current_rate.py (GBP/kWh current rate sensor)" + url: "https://github.com/BottlecapDave/HomeAssistant-OctopusEnergy/blob/v19.2.1/custom_components/octopus_energy/electricity/current_rate.py" + date: 2026-10-16 + - title: "home-assistant/core event/entity.py (state_attributes: event_type plus last event data)" + url: "https://github.com/home-assistant/core/blob/5cfe9aad/homeassistant/components/event/entity.py" + date: 2026-10-16 +tested_with: [] +capabilities: [price_now, price_curve] +unverified: + - Read from the integration source (tag v19.2.1, commit ccfbccc3) only; not observed on a running Home Assistant. + - 'Entity ids and translation keys of the event entities: the roles match domain `event` and platform only; current-day, next-day, previous-day and export entities are all candidates.' + - The event fires only when the rates changed and is restored after a restart; before the first event the `rates` attribute is missing. + - Whether `value_inc_vat` is a complete end price (standing charges, caps) is not stated; SunCore treats it as all-in. +direction: import +tariff_type: dynamic +roles: + price: + matcher: + domain: sensor + platforms: [octopus_energy] + units: ["GBP/kWh"] + description: template.octopus_energy.rates.role.price + current_day_rates: + matcher: + domain: event + platforms: [octopus_energy] + description: template.octopus_energy.rates.role.current_day_rates + next_day_rates: + required: false + matcher: + domain: event + platforms: [octopus_energy] + description: template.octopus_energy.rates.role.next_day_rates +price_unit: "GBP/kWh" +price_includes: all_in +price_series: + source: attribute + roles: [current_day_rates, next_day_rates] + attribute: rates + shape: list + fields: + timestamp_field: start + end_field: end + value_field: value_inc_vat + value_unit: "GBP/kWh" diff --git a/templates/tariff/tibber.price.yaml b/templates/tariff/tibber.price.yaml index f642982..7591013 100644 --- a/templates/tariff/tibber.price.yaml +++ b/templates/tariff/tibber.price.yaml @@ -1,27 +1,31 @@ # yaml-language-server: $schema=../schema/tariff.schema.json # Tibber (core integration `tibber`, cloud polling). The price sensor only holds the current -# slot; the curve of today and tomorrow comes from the read-only action `tibber.get_prices`. +# slot; the curve of today and tomorrow comes from the read-only action `tibber.get_prices` +# (response `{"prices": {"": [{"start_time", "price"}]}}`, `price` = energy plus +# taxes). Several homes: set `series_key` in the tariff configuration to the home name. id: tibber.price kind: tariff schema_version: 1 name: template.tibber.price.name source: - title: "home-assistant/core tibber sensor.py (electricity_price, unit, state)" - url: "https://github.com/home-assistant/core/blob/14f093e/homeassistant/components/tibber/sensor.py" - date: 2026-10-13 - - title: "home-assistant/core tibber services.py (get_prices, response shape)" - url: "https://github.com/home-assistant/core/blob/14f093e/homeassistant/components/tibber/services.py" - date: 2026-10-13 + url: "https://github.com/home-assistant/core/blob/5cfe9aad/homeassistant/components/tibber/sensor.py" + date: 2026-10-16 + - title: "home-assistant/core tibber services.py (get_prices, response shape, price_total)" + url: "https://github.com/home-assistant/core/blob/5cfe9aad/homeassistant/components/tibber/services.py" + date: 2026-10-16 - title: "home-assistant/core tibber services.yaml (start, end fields)" - url: "https://github.com/home-assistant/core/blob/14f093e/homeassistant/components/tibber/services.yaml" - date: 2026-10-13 + url: "https://github.com/home-assistant/core/blob/5cfe9aad/homeassistant/components/tibber/services.yaml" + date: 2026-10-16 tested_with: [] capabilities: [price_now, price_curve] unverified: - - "Whether grid fees (network charges) are included in Tibber's `total` price is country dependent; SunCore treats the value as all-in (`price_includes: all_in`) without checking." - - "Read from the integration source (core 14f093e, pyTibber 0.37.6) only; not observed on a running Home Assistant." - - "Exact entity id (derived from the home nickname) and the time Tibber publishes tomorrow's prices." - - "Slot length is not part of the response: 15 min with pyTibber 0.37, hourly with older libraries (resolution derived from the timestamps)." + - Read from the integration source (core 5cfe9aad, pyTibber 0.37.6) only; not observed on a running Home Assistant. + - '`price` is the library''s `total` (energy plus tax). Grid fees are country dependent; SunCore treats it as all-in (plan answer 9). A supplier contract with extra fees stays the user''s call.' + - Exact entity id (derived from the home nickname) and the time Tibber publishes tomorrow's prices (about 13:00 local). + - 'Slot length is not in the response: 15 min with pyTibber 0.37, hourly with older libraries; derived from the timestamps, a mix of both is accepted.' + - '`start`/`end` are sent as local ISO 8601 with offset; the source documents `YYYY-MM-DD HH:MM:SS` or ISO 8601 (parse_datetime), the offset form was not run against a live system.' + - The home name is the key of the response (two homes with the same name collide in the integration); with several homes set `series_key`. direction: import tariff_type: dynamic roles: diff --git a/tests/api/conftest.py b/tests/api/conftest.py index f6315f9..50c04b9 100644 --- a/tests/api/conftest.py +++ b/tests/api/conftest.py @@ -22,9 +22,11 @@ HAUnavailableError, HealthReport, PeerPolicy, + TariffNotConfiguredError, UnknownRoleError, UnknownTemplateError, ) +from suncore.app.planning import LiveReading, PlanningService, PlanningSnapshot from suncore.core.balance import Flow, FlowSnapshot from suncore.core.battery import BatterySettings from suncore.core.config import SECTION_MODELS, OperationConfig @@ -57,12 +59,14 @@ from suncore.forecast.risk import ErrorModel from suncore.forecast.risk_learning import risk_view from suncore.forecast.views import ForecastAccuracyView, LoadForecastView, PvForecastView, RiskView +from suncore.planner.views import PlanStatusView, PlanSummary, PlanView, ReplanAck from suncore.storage import ( HistoryEntry, HistoryEntryNotFoundError, ImportRejectedError, UnknownSectionError, ) +from suncore.tariff.report import PriceReport from suncore.templates import TemplateCatalog, load_templates TEMPLATES_DIR = Path(__file__).resolve().parents[2] / "templates" @@ -230,6 +234,30 @@ def __init__(self) -> None: tz=UTC, plant=None, ) + self.price_report: PriceReport | None = None + self.price_hours: list[int] = [] + + async def nothing(now: datetime, previous: object) -> PlanningSnapshot: + return PlanningSnapshot(None) + + self.planning = PlanningService(nothing, LiveReading, clock=lambda: NOW) + + async def plan_view(self, hours: int) -> PlanView: + self.calls.append(("plan_view", hours)) + return self.planning.view(hours) + + async def plan_status(self) -> PlanStatusView: + return self.planning.status() + + async def replan(self) -> ReplanAck: + self.calls.append(("replan", None)) + return self.planning.request("manual") + + def plan_summary(self) -> PlanSummary: + return self.planning.summary() + + def add_plan_listener(self, listener: Callable[[], None]) -> Callable[[], None]: + return self.planning.add_listener(listener) async def pv_forecast(self, hours: int) -> PvForecastView: self.pv_hours.append(hours) @@ -245,6 +273,12 @@ async def load_forecast(self, hours: int) -> LoadForecastView: async def forecast_risk(self) -> RiskView: return self.risk + async def prices(self, hours: int) -> PriceReport: + self.price_hours.append(hours) + if self.price_report is None: + raise TariffNotConfiguredError + return self.price_report + async def health(self) -> HealthReport: self.health_calls += 1 return HealthReport(self.ha_state, 1.5, self.db_ok, self.version) diff --git a/tests/api/test_config_api.py b/tests/api/test_config_api.py index 72a3930..9be4001 100644 --- a/tests/api/test_config_api.py +++ b/tests/api/test_config_api.py @@ -190,3 +190,56 @@ async def test_tariff_formula_on_an_all_in_template_is_rejected(services: FakeSe } assert plain.status_code == 200 assert entity.status_code == 200 + + +async def test_the_users_price_statement_decides_whether_a_formula_is_allowed( + services: FakeServices, +) -> None: + """ENTSO-E is spot-only by default but may carry the user's modifier template and VAT.""" + formula = {"grid_fee": 0.08, "vat_pct": 19} + export = VALID["tariff"]["export"] + + def body(template: str, includes: str | None) -> dict[str, Any]: + imp: dict[str, Any] = {"kind": "dynamic", "template_id": template, "formula": formula} + if includes is not None: + imp["price_includes"] = includes + return {"import": imp, "export": export} + + async with client_for(create_app(services)) as client: + spot_default = await client.put("/api/v1/config/tariff", json=body("entsoe.price", None)) + declared_all_in = await client.put( + "/api/v1/config/tariff", json=body("entsoe.price", "all_in") + ) + declared_spot = await client.put( # a contract that passes the spot price through + "/api/v1/config/tariff", json=body("tibber.price", "spot_only") + ) + assert spot_default.status_code == 200 + assert declared_all_in.status_code == 422 + assert declared_all_in.json()["issues"][0]["key"] == "api.validation.import_formula_all_in" + assert declared_spot.status_code == 200 + + +async def test_required_request_fields_of_the_template_are_checked(services: FakeServices) -> None: + """m1: Nord Pool needs the `config_entry` id; a tariff without it is rejected with a key.""" + export = VALID["tariff"]["export"] + base = {"kind": "dynamic", "template_id": "nordpool.price"} + async with client_for(create_app(services)) as client: + bad = await client.put("/api/v1/config/tariff", json={"import": base, "export": export}) + optional_only = await client.put( + "/api/v1/config/tariff", + json={"import": {**base, "action_params": {"areas": ["SE3"]}}, "export": export}, + ) + good = await client.put( + "/api/v1/config/tariff", + json={"import": {**base, "action_params": {"config_entry": "01H"}}, "export": export}, + ) + assert bad.status_code == 422 + assert bad.json()["issues"] == [ + { + "loc": ["body", "import", "action_params", "config_entry"], + "key": "api.validation.import_param_missing", + "args": {"template_id": "nordpool.price", "field": "config_entry"}, + } + ] + assert optional_only.status_code == 422 + assert good.status_code == 200 diff --git a/tests/api/test_plan_api.py b/tests/api/test_plan_api.py new file mode 100644 index 0000000..e928d1f --- /dev/null +++ b/tests/api/test_plan_api.py @@ -0,0 +1,151 @@ +# SPDX-License-Identifier: Apache-2.0 +"""``/api/v1/plan``, ``/plan/status``, ``/plan/replan`` and the live ``plan`` message (WP9).""" + +from __future__ import annotations + +from datetime import datetime + +from websockets.asyncio.client import connect + +from suncore.api import create_app +from suncore.app.planning import PlanningService +from tests.api.conftest import FakeServices, client_for, serving +from tests.api.test_control_api import recv +from tests.app.planning_helpers import World + + +def with_planner(services: FakeServices) -> tuple[World, PlanningService]: + world = World() + services.planning = PlanningService(world.collect, world.live, clock=world.clock) + return world, services.planning + + +def parse(text: str) -> datetime: + return datetime.fromisoformat(text) + + +async def test_no_plan_yet_is_the_default_plan_with_a_reason(services: FakeServices) -> None: + async with client_for(create_app(services)) as client: + r = await client.get("/api/v1/plan") + assert r.status_code == 200 + body = r.json() + assert body["plan"]["source"] == "default" + assert body["plan"]["intervals"] == [] + assert body["in_use"] is False + assert body["fallback"]["key"] == "planner.status.no_plan" + + +async def test_the_plan_carries_intervals_flows_prices_bands_reasons_and_stats( + services: FakeServices, +) -> None: + _, planning = with_planner(services) + await planning.tick() + async with client_for(create_app(services)) as client: + r = await client.get("/api/v1/plan", params={"hours": 6}) + body = r.json() + plan = body["plan"] + assert plan["source"] in ("solver", "heuristic") + assert plan["stats"]["status"] + assert plan["created_at"] + assert body["stale"] is False + assert body["in_use"] is True + first = plan["intervals"][0] + assert {"expected", "prices", "battery", "devices", "reasons"} <= set(first) + assert first["expected"]["soc_pct"] is not None + assert plan["reasons"] + assert len(plan["intervals"]) <= 6 * 4 + 1 + + +async def test_the_horizon_is_validated(services: FakeServices) -> None: + async with client_for(create_app(services)) as client: + assert (await client.get("/api/v1/plan", params={"hours": 0})).status_code == 422 + assert (await client.get("/api/v1/plan", params={"hours": 49})).status_code == 422 + + +async def test_a_stale_plan_is_flagged_and_not_in_use(services: FakeServices) -> None: + world, planning = with_planner(services) + await planning.tick() + world.clock.advance(3 * 3600) + async with client_for(create_app(services)) as client: + body = (await client.get("/api/v1/plan")).json() + assert body["stale"] is True + assert body["in_use"] is False + assert body["fallback"]["key"] == "planner.status.stale" + + +async def test_status_reports_the_last_run_and_the_next(services: FakeServices) -> None: + _, planning = with_planner(services) + await planning.tick() + async with client_for(create_app(services)) as client: + body = (await client.get("/api/v1/plan/status")).json() + assert body["last_outcome"] == "ok" + assert body["last_trigger"] == "start" + assert body["last_duration_s"] >= 0 + assert body["consecutive_failures"] == 0 + assert parse(body["next_scheduled_at"]) == parse(body["last_started_at"]).replace( + minute=15, second=20 + ) + assert body["plan"]["intervals"] > 0 + assert body["running"] is False + + +async def test_replan_is_accepted_and_debounced(services: FakeServices) -> None: + _, planning = with_planner(services) + await planning.tick() + async with client_for(create_app(services)) as client: + r = await client.post("/api/v1/plan/replan") + again = await client.post("/api/v1/plan/replan") + status = (await client.get("/api/v1/plan/status")).json() + assert r.status_code == 202 + assert r.json()["accepted"] is True + assert r.json()["earliest_start_at"] == again.json()["earliest_start_at"] # merged + assert status["pending"] == ["manual"] + assert ("replan", None) in services.calls + + +async def test_replan_without_a_planner_is_a_catalogue_error(services: FakeServices) -> None: + async def broken() -> object: + raise RuntimeError("not built") + + services.replan = broken # type: ignore[method-assign,assignment] + async with client_for(create_app(services)) as client: + r = await client.post("/api/v1/plan/replan") + assert r.status_code == 409 + assert r.json()["detail"] == "api.error.planning_unavailable" + + +async def test_plan_and_status_without_a_planner_are_catalogue_errors( + services: FakeServices, +) -> None: + """Review m8: like replan, not a 500.""" + + async def broken(*_a: object) -> object: + raise RuntimeError("not built") + + services.plan_view = broken # type: ignore[method-assign,assignment] + services.plan_status = broken # type: ignore[method-assign,assignment] + async with client_for(create_app(services)) as client: + plan = await client.get("/api/v1/plan") + status = await client.get("/api/v1/plan/status") + for r in (plan, status): + assert r.status_code == 409 + assert r.json()["detail"] == "api.error.planning_unavailable" + + +async def test_the_live_feed_announces_a_new_plan_without_the_intervals( + services: FakeServices, +) -> None: + _, planning = with_planner(services) + app = create_app(services, live_min_interval_s=0.05, live_health_interval_s=30) + async with serving(app) as port, connect(f"ws://127.0.0.1:{port}/api/v1/live") as ws: + assert (await recv(ws))["type"] == "snapshot" + await planning.tick() + msg = await recv(ws) + while msg["type"] != "plan": + msg = await recv(ws) + summary = msg["plan"] + assert summary["source"] in ("solver", "heuristic") + assert summary["intervals"] > 0 + assert summary["in_use"] is True + assert "plan" not in summary # no interval data in the feed + assert "reasons" in summary diff --git a/tests/api/test_prices_api.py b/tests/api/test_prices_api.py new file mode 100644 index 0000000..d13bf96 --- /dev/null +++ b/tests/api/test_prices_api.py @@ -0,0 +1,111 @@ +# SPDX-License-Identifier: Apache-2.0 +"""``GET /api/v1/prices``: the 15-minute planning prices with source and freshness.""" + +from __future__ import annotations + +from datetime import UTC, datetime, timedelta + +from suncore.api import create_app +from suncore.tariff.report import ( + PriceFreshness, + PriceQuality, + PriceReport, + PriceSlot, + PriceSourceInfo, +) +from tests.api.conftest import FakeServices, client_for + +T0 = datetime(2026, 10, 16, 8, 0, tzinfo=UTC) + + +def report() -> PriceReport: + return PriceReport( + price_includes="all_in", + formula_missing=False, + start=T0, + slots=[ + PriceSlot(start=T0, import_price=0.31, export_price=0.08), + PriceSlot(start=T0 + timedelta(minutes=15), import_price=-0.01, export_price=0.0), + PriceSlot(start=T0 + timedelta(minutes=30), import_price=None, export_price=None), + ], + source=PriceSourceInfo( + import_source_id="tibber.price", + import_kind="dynamic", + source_price_includes="all_in", + price_includes="all_in", + formula_applied=False, + export_kind="fixed", + negative_price_rule="no_remuneration", + export_zeroed_slots=1, + native_step_min=15, + currency="EUR", + ), + freshness=PriceFreshness( + status="fresh", + fetched_at=T0, + age_s=12.5, + known_until=T0 + timedelta(hours=36), + next_refresh_at=T0 + timedelta(hours=1), + last_error=None, + ), + quality=PriceQuality(slots=3, known_slots=2, has_tomorrow=True, dropped_points=0), + ) + + +async def test_prices_are_returned_with_source_and_freshness(services: FakeServices) -> None: + services.price_report = report() + async with client_for(create_app(services)) as client: + r = await client.get("/api/v1/prices") + assert r.status_code == 200 + body = r.json() + assert services.price_hours == [48] # the default + assert body["unit"] == "currency/kWh" + assert body["step_min"] == 15 + assert body["slots"][1] == { + "start": "2026-10-16T08:15:00Z", + "import_price": -0.01, + "export_price": 0.0, + } + assert body["slots"][2]["import_price"] is None + assert body["source"]["import_source_id"] == "tibber.price" + assert body["source"]["negative_price_rule"] == "no_remuneration" + assert body["freshness"]["status"] == "fresh" + assert body["freshness"]["last_error"] is None + assert body["quality"] == { + "slots": 3, + "known_slots": 2, + "has_tomorrow": True, + "dropped_points": 0, + "carried_slots": 0, + } + + +async def test_hours_parameter_is_passed_and_bounded(services: FakeServices) -> None: + services.price_report = report() + async with client_for(create_app(services)) as client: + ok = await client.get("/api/v1/prices", params={"hours": 24}) + zero = await client.get("/api/v1/prices", params={"hours": 0}) + many = await client.get("/api/v1/prices", params={"hours": 73}) + text = await client.get("/api/v1/prices", params={"hours": "soon"}) + assert ok.status_code == 200 + assert services.price_hours == [24] + assert zero.status_code == many.status_code == text.status_code == 422 + assert zero.json()["detail"] == "api.error.validation" + + +async def test_no_tariff_is_a_404_with_a_catalogue_key(services: FakeServices) -> None: + async with client_for(create_app(services)) as client: + r = await client.get("/api/v1/prices") + assert r.status_code == 404 + assert r.json() == {"detail": "api.error.tariff_not_configured"} + + +async def test_prices_are_in_the_openapi_document(services: FakeServices) -> None: + async with client_for(create_app(services)) as client: + schema = ( + (await client.get("/openapi.json")).json() if False else create_app(services).openapi() + ) + operation = schema["paths"]["/api/v1/prices"]["get"] + assert operation["operationId"] == "get_prices" + assert {"200", "404", "422"} <= set(operation["responses"]) + assert "PriceReport" in schema["components"]["schemas"] diff --git a/tests/app/planning_helpers.py b/tests/app/planning_helpers.py new file mode 100644 index 0000000..40f3e19 --- /dev/null +++ b/tests/app/planning_helpers.py @@ -0,0 +1,69 @@ +# SPDX-License-Identifier: Apache-2.0 +"""Helpers for the planner runtime tests: a fake clock, a collector on the sim scenarios.""" + +from __future__ import annotations + +from dataclasses import dataclass, field, replace +from datetime import datetime, timedelta + +from suncore.app.planning import LiveReading, PlanningService, PlanningSettings, PlanningSnapshot +from suncore.core.control import Plan +from suncore.planner.run import PlannerRun +from suncore.sim.planner_scenarios import SUMMER, TZ, situation, situation_inputs + +START = datetime(SUMMER.year, SUMMER.month, SUMMER.day, 6, 0, tzinfo=TZ) + + +@dataclass +class Clock: + now: datetime = START + + def __call__(self) -> datetime: + return self.now + + def advance(self, seconds: float) -> None: + self.now += timedelta(seconds=seconds) + + +@dataclass +class World: + """What the collector and the live reading see; tests change it between ticks.""" + + clock: Clock = field(default_factory=Clock) + soc_pct: float = 30.0 + grid_w: float = 0.0 + complete: bool = True + ready: bool = True + collect_calls: int = 0 + collect_error: Exception | None = None + + async def collect(self, now: datetime, previous: Plan | None) -> PlanningSnapshot: + self.collect_calls += 1 + if self.collect_error is not None: + raise self.collect_error + if not self.ready: + return PlanningSnapshot(None) + base = replace(situation("sunny_day"), now=now, soc_pct=self.soc_pct) + inputs = situation_inputs(base) + if previous is not None: + inputs = replace(inputs, previous=previous) + return PlanningSnapshot(inputs, complete=self.complete) + + def live(self) -> LiveReading: + return LiveReading(soc_pct=self.soc_pct, grid_w=self.grid_w) + + +def service( + world: World, + *, + settings: PlanningSettings | None = None, + **kw: object, +) -> PlanningService: + args: dict[str, object] = {"clock": world.clock, "settings": settings or PlanningSettings()} + args.update(kw) + return PlanningService(world.collect, world.live, **args) # type: ignore[arg-type] + + +def broken_solver(*_a: object) -> PlannerRun: + msg = "boom" + raise RuntimeError(msg) diff --git a/tests/app/test_adapters.py b/tests/app/test_adapters.py new file mode 100644 index 0000000..b538569 --- /dev/null +++ b/tests/app/test_adapters.py @@ -0,0 +1,236 @@ +# SPDX-License-Identifier: Apache-2.0 +"""Composition of the tariff service: the action caller, the cache reader, the builders.""" + +from __future__ import annotations + +from collections.abc import Mapping +from typing import Any +from zoneinfo import ZoneInfo + +import pytest + +from suncore.app.adapters import ( + ConnectionActionCaller, + build_tariff_plan, + build_tariff_service, + cache_reader, + negative_price_rule, +) +from suncore.core.config import ExportTariff, ExportTier, ImportTariff, RegionConfig, TariffConfig +from suncore.core.site import EntityRef, GridConfig, PvArray, SiteConfig +from suncore.core.tariff import PriceFormula, TouPeriod, TouTariff, TouWindow +from suncore.ha import EntityCache, HAError +from suncore.ha.connection import ActionRateLimitedError, EntityState, EntityUpdate +from suncore.tariff import ( + CurrentPriceSource, + ExportConfigError, + FixedPriceSource, + SourceFailedError, + SourceThrottledError, + TemplatePriceSource, + TouPriceSource, +) +from suncore.templates.models import NegativePriceRule +from tests.tariff.helpers import CATALOG, NOW + +BERLIN = ZoneInfo("Europe/Berlin") +DE = RegionConfig(region_id="de", currency="EUR", timezone="Europe/Berlin") +SITE = SiteConfig( + grid=GridConfig(power=EntityRef(entity_id="sensor.grid")), + pv=[PvArray(name="PV", power=EntityRef(entity_id="sensor.pv"), kwp=17.0)], +) + + +class Connection: + """Just enough of ``HAConnection`` for the action caller.""" + + def __init__(self) -> None: + self.error: Exception | None = None + self.calls: list[tuple[str, str, Mapping[str, Any] | None, float | None, float]] = [] + + async def call_action_response( + self, + domain: str, + service: str, + data: Mapping[str, Any] | None = None, + *, + target: Mapping[str, Any] | None = None, # noqa: ARG002 + min_interval_s: float | None = None, + max_wait_s: float = 0.0, + ) -> dict[str, Any]: + self.calls.append((domain, service, data, min_interval_s, max_wait_s)) + if self.error is not None: + raise self.error + return {"ok": True} + + +async def test_the_action_caller_passes_the_request_and_the_interval_through() -> None: + conn = Connection() + caller = ConnectionActionCaller(conn) # type: ignore[arg-type] + out = await caller("tibber", "get_prices", {"start": "x"}, min_interval_s=45.0, max_wait_s=31.0) + assert out == {"ok": True} + assert conn.calls == [("tibber", "get_prices", {"start": "x"}, 45.0, 31.0)] + + +async def test_a_rate_limited_call_becomes_a_throttle_not_a_failure() -> None: + conn = Connection() + conn.error = ActionRateLimitedError("tibber.get_prices", 12.5) + with pytest.raises(SourceThrottledError) as err: + await ConnectionActionCaller(conn)( + "tibber", "get_prices", {}, min_interval_s=30.0, max_wait_s=0.0 + ) # type: ignore[arg-type] + assert err.value.retry_after_s == 12.5 + + +@pytest.mark.parametrize("error", [HAError("down"), TimeoutError("slow")]) +async def test_home_assistant_errors_become_source_failures(error: Exception) -> None: + conn = Connection() + conn.error = error + with pytest.raises(SourceFailedError): + await ConnectionActionCaller(conn)( + "tibber", "get_prices", {}, min_interval_s=30.0, max_wait_s=0.0 + ) # type: ignore[arg-type] + + +def test_cache_reader() -> None: + cache = EntityCache() + cache.ingest( + EntityUpdate( + changed={ + "sensor.ok": EntityState("sensor.ok", "0.3", {"prices": []}), + "sensor.gone": EntityState("sensor.gone", "unavailable", {"prices": []}), + "event.new": EntityState("event.new", "unknown", {"event_types": ["x"]}), + }, + full=True, + ) + ) + read = cache_reader(cache) + ok = read("sensor.ok") + assert ok is not None + assert (ok.state, dict(ok.attributes)) == ("0.3", {"prices": []}) + assert read("sensor.gone") is None + assert read("sensor.absent") is None + unknown = read("event.new") + assert unknown is not None # an event entity is `unknown` until its first event + assert unknown.state == "unknown" + + +def test_the_negative_price_rule_comes_from_the_region_template() -> None: + assert negative_price_rule(CATALOG, DE) is NegativePriceRule.NO_REMUNERATION + generic = RegionConfig(region_id="generic", currency="EUR", timezone="UTC") + assert negative_price_rule(CATALOG, generic) is NegativePriceRule.NONE + other = RegionConfig(region_id="xx", currency="EUR", timezone="UTC") + assert negative_price_rule(CATALOG, other) is NegativePriceRule.NONE + + +def build(tariff: TariffConfig, site: SiteConfig | None = SITE) -> Any: + return build_tariff_plan( + tariff, + DE, + site, + BERLIN, + CATALOG, + connection=Connection(), # type: ignore[arg-type] + cache=EntityCache(), + clock=lambda: NOW, + ) + + +EXPORT = ExportTariff(kind="fixed", fixed_price=0.08) + + +def test_a_fixed_tariff_builds_a_fixed_source() -> None: + plan = build(TariffConfig(import_=ImportTariff(kind="fixed", fixed_price=0.3), export=EXPORT)) + assert isinstance(plan.source, FixedPriceSource) + assert plan.negative_rule is NegativePriceRule.NO_REMUNERATION + assert plan.total_kwp == 17.0 + assert plan.currency == "EUR" + + +def test_a_tou_tariff_builds_a_tou_source() -> None: + tou = TouTariff( + base_price=0.35, + periods=(TouPeriod(window=TouWindow(start="22:00", end="06:00"), price=0.25),), + ) + plan = build(TariffConfig(import_=ImportTariff(kind="tou", tou=tou), export=EXPORT)) + assert isinstance(plan.source, TouPriceSource) + + +def test_a_dynamic_tariff_builds_the_template_source_with_the_users_settings() -> None: + tariff = TariffConfig( + import_=ImportTariff( + kind="dynamic", + template_id="octopus_energy.rates", + price_entity=EntityRef(entity_id="sensor.rate"), + role_entities={ + "current_day_rates": EntityRef(entity_id="event.today"), + "next_day_rates": EntityRef(entity_id="event.tomorrow"), + }, + price_includes="spot_only", + formula=PriceFormula(grid_fee=0.1), + ), + export=EXPORT, + ) + plan = build(tariff) + assert isinstance(plan.source, TemplatePriceSource) + assert plan.source.watched_entities == ("event.today", "event.tomorrow", "sensor.rate") + assert plan.source.price_includes == "spot_only" # the user's statement beats the template + assert plan.formula is not None + + +def test_a_price_entity_without_a_template_uses_the_current_slot_only() -> None: + tariff = TariffConfig( + import_=ImportTariff(kind="dynamic", price_entity=EntityRef(entity_id="sensor.p")), + export=EXPORT, + ) + assert isinstance(build(tariff).source, CurrentPriceSource) + + +def test_an_unknown_or_unsuitable_template_builds_nothing() -> None: + unknown = TariffConfig( + import_=ImportTariff(kind="dynamic", template_id="no.such"), export=EXPORT + ) + assert build(unknown) is None + not_a_tariff = TariffConfig( + import_=ImportTariff(kind="dynamic", template_id="lg.thinq_climate"), export=EXPORT + ) + assert build(not_a_tariff) is None + + +def test_the_service_gets_the_configured_timing_and_the_store() -> None: + class Store: + async def store_prices(self, prices: object) -> int: # noqa: ARG002 + return 0 + + store = Store() + service = build_tariff_service( + TariffConfig(import_=ImportTariff(kind="fixed", fixed_price=0.3), export=EXPORT), + DE, + SITE, + BERLIN, + CATALOG, + connection=Connection(), # type: ignore[arg-type] + cache=EntityCache(), + clock=lambda: NOW, + store=store, + refresh_interval_s=1800.0, + ) + assert service is not None + assert service._settings.refresh_interval_s == 1800.0 + assert service._store is store + + +def test_a_tiered_export_needs_the_site_size() -> None: + tiered = ExportTariff( + kind="tiered", tiers=(ExportTier(up_to_kwp=10, price=0.08), ExportTier(price=0.07)) + ) + tariff = TariffConfig(import_=ImportTariff(kind="fixed", fixed_price=0.3), export=tiered) + kwargs: dict[str, Any] = { + "connection": Connection(), + "cache": EntityCache(), + "clock": lambda: NOW, + "store": None, + } + assert build_tariff_service(tariff, DE, SITE, BERLIN, CATALOG, **kwargs) is not None + with pytest.raises(ExportConfigError): + build_tariff_service(tariff, DE, None, BERLIN, CATALOG, **kwargs) diff --git a/tests/app/test_demo.py b/tests/app/test_demo.py index 1c9b5b0..b905f74 100644 --- a/tests/app/test_demo.py +++ b/tests/app/test_demo.py @@ -35,7 +35,7 @@ from suncore.core.site import EntityRef from suncore.ha.connection import CommandTimeoutError from suncore.sim.demo_config import WIZARD_STEPS -from suncore.sim.demo_devices import AC_ID +from suncore.sim.demo_devices import AC_ID, PRICE_ID from suncore.sim.fake_ha import SIM_ENTITY_IDS, FakeHAConnection, demo_site_config from suncore.templates import DeviceTemplate from tests.api.conftest import client_for, serving @@ -126,8 +126,11 @@ async def test_demo_live_feed_balance_closes(demo_runtime: Runtime) -> None: } ) """The configured PV forecast sources' day sensors (Phase 4 WP5) and the load forecast's workday -sensor and weather entity (WP6) are subscribed too.""" -DEMO_SUBSCRIBED = frozenset(SIM_ENTITY_IDS) | DEMO_DEVICE_ENTITIES | DEMO_FORECAST_ENTITIES +sensor and weather entity (WP6) are subscribed too, and the price sensor of the tariff (it tells +the price service when to look again).""" +DEMO_SUBSCRIBED = ( + frozenset(SIM_ENTITY_IDS) | DEMO_DEVICE_ENTITIES | DEMO_FORECAST_ENTITIES | {PRICE_ID} +) async def test_demo_starts_fully_configured(demo_runtime: Runtime) -> None: @@ -221,7 +224,9 @@ async def test_put_site_survives_subscribe_timeout( r = await client.put("/api/v1/config/site", json=reduced.model_dump(mode="json")) assert r.status_code == 200 assert (await demo_runtime.config.get_site()) == reduced # persisted - assert [e["event"] for e in logs if e["log_level"] == "warning"] == ["ha.subscribe_failed"] + # (the fixture's wall clock is not the simulator's, so the price service may warn as well) + warnings = [e["event"] for e in logs if e["log_level"] == "warning"] + assert [e for e in warnings if not e.startswith("tariff.")] == ["ha.subscribe_failed"] async def test_put_site_notifies_live_listeners(demo_runtime: Runtime) -> None: @@ -376,6 +381,7 @@ async def test_put_devices_resubscribes_and_shadows_new_ones(demo_runtime: Runti assert conn.subscriptions[-1] == frozenset(SIM_ENTITY_IDS) | DEMO_FORECAST_ENTITIES | { "switch.heater", "sensor.heater_power", + PRICE_ID, } assert await demo_runtime.get_section("devices") == stored @@ -408,4 +414,4 @@ async def test_import_reloads_devices(demo_runtime: Runtime) -> None: exported["sections"]["devices"]["body"]["devices"] = [] await demo_runtime.import_config(exported) assert demo_runtime.devices == DevicesConfig() - assert conn.subscriptions[-1] == frozenset(SIM_ENTITY_IDS) | DEMO_FORECAST_ENTITIES + assert conn.subscriptions[-1] == frozenset(SIM_ENTITY_IDS) | DEMO_FORECAST_ENTITIES | {PRICE_ID} diff --git a/tests/app/test_planning.py b/tests/app/test_planning.py new file mode 100644 index 0000000..08fd9ac --- /dev/null +++ b/tests/app/test_planning.py @@ -0,0 +1,519 @@ +# SPDX-License-Identifier: Apache-2.0 +"""The planner runtime: cadence, events, debounce, single flight, failure handling (WP9).""" + +from __future__ import annotations + +import asyncio +import threading +from dataclasses import replace +from datetime import timedelta +from typing import Any + +import pytest + +from suncore.app.planning import ( + PlanningService, + PlanningSettings, + floor_quarter, + planned_net_w, + planned_soc_at, + run_in_daemon_thread, +) +from suncore.core.control import Plan +from suncore.planner import reasons as rk +from suncore.planner.run import PlannerRun, run +from suncore.sim.planner_scenarios import situation, situation_inputs +from tests.app.planning_helpers import START, World, broken_solver, service + + +async def poll(svc: PlanningService, world: World, seconds: float, step: float = 5.0) -> int: + """Tick every ``step`` simulated seconds; returns how many runs happened.""" + runs = 0 + for _ in range(int(seconds / step)): + runs += await svc.tick() + world.clock.advance(step) + return runs + + +QUARTER_S = 920 # a quarter hour plus the 20 s offset + + +def real_solver(inputs: Any, budget: float, gap: float, previous: Plan | None) -> PlannerRun: + return run(inputs, budget_s=budget, mip_gap=gap, warm_start=previous) + + +async def test_first_run_then_every_quarter_hour() -> None: + world = World() + svc = service(world) + assert await svc.tick() + first = svc.plan + assert first is not None + assert first.source in ("solver", "heuristic") + assert svc.status().last_trigger == "start" + assert await poll(svc, world, 600) == 0 # nothing in between + world.clock.now = START.replace(minute=14, second=50) + assert await poll(svc, world, 60) == 1 # the quarter (06:15:20) triggers one run + assert svc.status().last_trigger == "schedule" + assert await poll(svc, world, 600) == 0 + assert svc.plan is not first + + +async def test_runs_are_aligned_to_the_quarter_plus_offset() -> None: + world = World() + svc = service(world, settings=PlanningSettings(offset_s=20.0)) + await svc.tick() + world.clock.now = START.replace(minute=15, second=10) + assert not await svc.tick() # 10 s past the quarter: before the offset + world.clock.now = START.replace(minute=15, second=21) + assert await svc.tick() + assert svc.status().next_scheduled_at == START.replace(minute=30, second=20) + + +async def test_events_are_debounced_and_merged() -> None: + world = World() + svc = service(world) + await svc.tick() + started = svc.status().last_started_at + assert started is not None + world.clock.advance(10) + svc.request("prices") + svc.request("forecast") + ack = svc.request("config") + assert not await svc.tick() # less than 60 s after the last run + assert ack.earliest_start_at == started + timedelta(seconds=60) + assert svc.status().pending == ["config", "prices", "forecast"] + world.clock.advance(55) + assert await svc.tick() + assert svc.status().last_trigger == "config" # one run for all three, highest priority + assert svc.status().pending == [] + assert not await svc.tick() + + +async def test_a_manual_replan_follows_the_same_debounce() -> None: + world = World() + svc = service(world) + await svc.tick() + first_start = svc.status().last_started_at + assert first_start is not None + world.clock.advance(30) + svc.request("manual") + assert not await svc.tick() + world.clock.advance(31) + assert await svc.tick() + assert svc.status().last_trigger == "manual" + later = svc.status().last_started_at + assert later is not None + assert later > first_start + + +async def test_single_flight_events_during_a_run_wait_for_its_end() -> None: + world = World() + started = threading.Event() + release = threading.Event() + + def slow(inputs: Any, budget: float, gap: float, previous: Plan | None) -> PlannerRun: + started.set() + release.wait(5) + return real_solver(inputs, budget, gap, previous) + + svc = service(world, solve=slow) + task = asyncio.create_task(svc.tick()) + while not started.is_set(): # noqa: ASYNC110 + await asyncio.sleep(0.005) + assert svc.status().running + svc.request("prices") + assert not await svc.tick() # a second tick while running starts nothing + release.set() + assert await task + assert not svc.status().running + assert svc.status().pending == ["prices"] # kept for the next run + world.clock.advance(61) + assert await svc.tick() + assert svc.status().last_trigger == "prices" + + +async def test_the_solve_runs_off_the_event_loop() -> None: + world = World() + seen: list[str] = [] + + def spy(inputs: Any, budget: float, gap: float, previous: Plan | None) -> PlannerRun: + seen.append(threading.current_thread().name) + return real_solver(inputs, budget, gap, previous) + + svc = service(world, solve=spy) + await svc.tick() + assert seen == ["suncore-planner"] + assert threading.current_thread().name != "suncore-planner" + + +async def test_warm_start_hands_the_previous_plan_to_the_solver() -> None: + world = World() + previous_seen: list[Plan | None] = [] + + def spy(inputs: Any, budget: float, gap: float, previous: Plan | None) -> PlannerRun: + previous_seen.append(previous) + return real_solver(inputs, budget, gap, previous) + + svc = service(world, solve=spy) + await svc.tick() + world.clock.advance(QUARTER_S) + await svc.tick() + assert previous_seen[0] is None + assert previous_seen[1] is not None + assert previous_seen[1].created_at == START + + +# --- triggers: deviation ----------------------------------------------------------------- + + +async def test_a_soc_deviation_over_ten_points_triggers_a_run() -> None: + world = World() + svc = service(world) + await svc.tick() + world.clock.advance(120) + plan = svc.plan + assert plan is not None + planned = planned_soc_at(plan, world.clock()) + assert planned is not None + world.soc_pct = planned + 9.0 + assert not await svc.tick() + assert svc.status().pending == [] + world.soc_pct = planned + 11.0 + assert await svc.tick() + assert svc.status().last_trigger == "deviation" + + +async def test_a_sustained_net_power_deviation_triggers_after_30_minutes() -> None: + """Judged on the tracker directly: the quarter-hour replans would reset it in a full run + (a new plan starts from the live state, so the deviation counts from there).""" + world = World() + svc = service(world) + await svc.tick() + first_at: timedelta | None = None + for k in range(1, 120): + world.clock.advance(30) + svc._update_net_deviation(world.clock(), 3000.0) + if "deviation" in svc.status().pending: + first_at = timedelta(seconds=30 * k) + break + assert first_at is not None, "a +3 kW deviation for an hour must trigger a replan" + assert timedelta(minutes=30) <= first_at <= timedelta(minutes=32) + + +async def test_a_short_power_spike_does_not_trigger() -> None: + world = World() + svc = service(world, settings=PlanningSettings(offset_s=0.0)) + await svc.tick() + plan = svc.plan + assert plan is not None + for k in range(40): + world.clock.advance(5) + world.grid_w = (planned_net_w(plan, world.clock()) or 0.0) + (4000.0 if k < 6 else 0.0) + world.soc_pct = planned_soc_at(plan, world.clock()) or world.soc_pct + await svc.tick() + assert svc.status().pending == [] + + +# --- failure handling -------------------------------------------------------------------- + + +async def test_a_failed_run_keeps_the_last_good_plan() -> None: + world = World() + svc = service(world) + await svc.tick() + good = svc.plan + svc._solve = broken_solver # type: ignore[assignment] + world.clock.advance(QUARTER_S) + assert await svc.tick() + status = svc.status() + assert status.last_outcome == "failed" + assert status.reason is not None + assert status.reason.key == rk.STATUS_RUN_FAILED + assert status.consecutive_failures == 1 + assert svc.plan is good + assert svc.active_plan() is good # still fresh: still followed + + +async def test_a_collector_error_is_a_failed_run_not_a_crash() -> None: + world = World() + svc = service(world) + await svc.tick() + world.collect_error = ValueError("bad inputs") + world.clock.advance(QUARTER_S) + assert await svc.tick() + assert svc.status().last_outcome == "failed" + assert svc.plan is not None + + +async def test_the_plan_is_stale_after_two_hours_and_the_controller_gets_the_default() -> None: + world = World() + svc = service(world) + await svc.tick() + plan = svc.plan + assert plan is not None + world.clock.advance(7200 - 1) + assert svc.active_plan() is plan + assert not svc.view().stale + world.clock.advance(2) + assert svc.active_plan().is_default # Phase 3 behaviour + view = svc.view() + assert view.stale + assert not view.in_use + assert view.fallback is not None + assert view.fallback.key == rk.STATUS_STALE + assert view.plan.intervals # still shown, flagged + assert svc.summary().stale + + +async def test_staleness_counts_from_the_hand_over() -> None: + """Review n3: the age runs from the hand-over, and a plan without any time is stale.""" + world = World() + svc = service(world) + await svc.tick() + plan = svc.plan + assert plan is not None + svc._plan = plan.model_copy(update={"created_at": world.clock.now - timedelta(days=1)}) + assert svc.fallback_reason() is None # handed over just now + svc._plan = plan.model_copy(update={"created_at": None}) + svc._plan_stamp = None + reason = svc.fallback_reason() + assert reason is not None + assert reason.key == rk.STATUS_STALE + + +async def test_an_expired_plan_gives_the_default() -> None: + world = World() + svc = service(world, settings=PlanningSettings(stale_after_s=10 * 86400)) + await svc.tick() + assert svc.plan is not None + world.clock.advance(49 * 3600) + fallback = svc.fallback_reason() + assert fallback is not None + assert fallback.key == rk.STATUS_EXPIRED + assert svc.active_plan().is_default + assert svc.view().expired + + +async def test_no_plan_yet_is_the_default_with_a_reason() -> None: + world = World(ready=False) + svc = service(world) + assert svc.active_plan().is_default + assert await svc.tick() + assert svc.status().last_outcome == "skipped" + view = svc.view() + assert view.plan.source == "default" + assert view.fallback is not None + assert view.fallback.key == rk.STATUS_NO_PLAN + + +async def test_a_run_that_is_not_ready_is_retried_soon_not_every_tick() -> None: + world = World(ready=False) + svc = service(world) + await svc.tick() + calls = world.collect_calls + await poll(svc, world, 10) + assert world.collect_calls == calls # retry_skipped_s = 15 + world.ready = True + await poll(svc, world, 20) + assert svc.plan is not None + + +async def test_the_first_plan_waits_for_prices_and_forecasts_within_the_grace_period() -> None: + world = World(complete=False) + svc = service(world, settings=PlanningSettings(first_run_grace_s=120.0)) + await svc.tick() + assert svc.plan is None + reason = svc.status().reason + assert reason is not None + assert reason.key == rk.STATUS_WAITING + world.clock.advance(60) + await svc.tick() + assert svc.plan is None + world.clock.advance(70) # the grace is over: plan with what there is + await svc.tick() + assert svc.plan is not None + + +async def test_a_hanging_planner_is_abandoned_and_stacks_no_threads() -> None: + world = World() + release = threading.Event() + + # A canned result, computed before the clock-critical part: the run timeout below is + # 0.1 s, which a real solve under coverage on a busy runner can exceed (review B2). + canned = real_solver( + situation_inputs(replace(situation("sunny_day"), now=START)), 8, 0.01, None + ) + + def hang(inputs: Any, budget: float, gap: float, previous: Plan | None) -> PlannerRun: + release.wait(10) + return canned + + def fast(*_a: object) -> PlannerRun: + return canned + + settings = PlanningSettings(budget_s=0.05, run_timeout_margin_s=0.05) + svc = service(world, settings=settings, solve=hang) + assert await svc.tick() + assert svc.status().last_outcome == "failed" + reason = svc.status().reason + assert reason is not None + assert reason.key == rk.STATUS_RUN_TIMEOUT + world.clock.advance(QUARTER_S) # the thread still lives: no second one is started on top of it + assert await svc.tick() + assert svc.status().last_outcome == "skipped" + reason = svc.status().reason + assert reason is not None + assert reason.key == rk.STATUS_RUN_STUCK + release.set() + await asyncio.sleep(0.3) + svc._solve = fast # type: ignore[assignment] + world.clock.advance(QUARTER_S) + assert await svc.tick() + assert svc.status().last_outcome == "ok" + + +async def test_cancelling_the_service_does_not_wait_for_a_hanging_planner() -> None: + world = World() + release = threading.Event() + started = threading.Event() + + def hang(inputs: Any, budget: float, gap: float, previous: Plan | None) -> PlannerRun: + started.set() + release.wait(10) + return real_solver(inputs, budget, gap, previous) + + async def sleep(_s: float) -> None: + await asyncio.sleep(0.001) + + svc = service(world, solve=hang, sleep=sleep) + task = asyncio.create_task(svc.run()) + while not started.is_set(): # noqa: ASYNC110 + await asyncio.sleep(0.005) + loop = asyncio.get_running_loop() + began = loop.time() + task.cancel() + with pytest.raises(asyncio.CancelledError): + await task + assert loop.time() - began < 0.5 + release.set() + + +async def test_the_run_loop_polls_and_survives_errors() -> None: + world = World() + ticks = 0 + + async def sleep(seconds: float) -> None: + nonlocal ticks + ticks += 1 + world.clock.advance(seconds) + await asyncio.sleep(0) + + svc = service(world, sleep=sleep) + world.collect_error = RuntimeError("down") + task = asyncio.create_task(svc.run()) + while ticks < 5: # noqa: ASYNC110 + await asyncio.sleep(0) + world.collect_error = None + while svc.plan is None: # noqa: ASYNC110 + await asyncio.sleep(0.01) + task.cancel() + with pytest.raises(asyncio.CancelledError): + await task + + +# --- hand-over, listeners ---------------------------------------------------------------- + + +async def test_listeners_hear_about_every_new_plan_and_the_plan_has_the_start_soc() -> None: + world = World(soc_pct=42.5) + svc = service(world) + heard: list[int] = [] + remove = svc.add_listener(lambda: heard.append(1)) + await svc.tick() + assert heard == [1] + assert svc.plan is not None + assert svc.plan.assumptions["soc_start_pct"] == 42.5 + remove() + world.clock.advance(QUARTER_S) + await svc.tick() + assert heard == [1] + + +async def test_a_failing_listener_does_not_break_the_hand_over() -> None: + world = World() + svc = service(world) + + def bad() -> None: + raise RuntimeError + + svc.add_listener(bad) + await svc.tick() + assert svc.plan is not None + + +async def test_the_hand_over_is_one_reference_a_reader_thread_gets_whole() -> None: + world = World() + svc = service(world) + await svc.tick() + seen: list[Plan] = [] + stop = threading.Event() + now = world.clock() + + def reader() -> None: + while not stop.is_set(): + seen.append(svc.active_plan(now)) + + thread = threading.Thread(target=reader) + thread.start() + for _ in range(3): + world.clock.advance(QUARTER_S) + await svc.tick() + stop.set() + thread.join() + stamps = {p.created_at for p in seen} + assert stamps <= {START + timedelta(seconds=QUARTER_S * k) for k in range(4)} + assert all(p.intervals for p in seen) + + +async def test_the_view_cuts_the_horizon_and_the_past() -> None: + world = World() + svc = service(world) + await svc.tick() + world.clock.advance(3600) + view = svc.view(hours=6) + assert view.in_use + first = view.plan.intervals[0] + assert first.start <= world.clock() < first.end + assert view.plan.intervals[-1].start < world.clock() + timedelta(hours=6) + assert len(view.plan.intervals) <= 6 * 4 + 1 + + +async def test_daemon_thread_helper_returns_results_and_errors() -> None: + assert await run_in_daemon_thread(lambda: 7) == 7 + + def boom() -> int: + raise KeyError("x") + + with pytest.raises(KeyError): + await run_in_daemon_thread(boom) + + +def test_floor_quarter() -> None: + assert floor_quarter(START.replace(minute=44, second=59)).minute == 30 + assert floor_quarter(START.replace(minute=0, second=0)).minute == 0 + + +async def test_planned_soc_interpolates_inside_the_first_interval() -> None: + world = World(soc_pct=30.0) + svc = service(world) + await svc.tick() + plan = svc.plan + assert plan is not None + first = plan.intervals[0] + assert first.expected is not None + assert first.expected.soc_pct is not None + assert planned_soc_at(plan, first.start) == pytest.approx(30.0) + mid = first.start + (first.end - first.start) / 2 + assert planned_soc_at(plan, mid) == pytest.approx((30.0 + first.expected.soc_pct) / 2, abs=0.01) + assert planned_soc_at(plan, plan.intervals[-1].end + timedelta(seconds=1)) is None + assert planned_soc_at(Plan.default(), START) is None diff --git a/tests/app/test_planning_runtime.py b/tests/app/test_planning_runtime.py new file mode 100644 index 0000000..9dc6a7b --- /dev/null +++ b/tests/app/test_planning_runtime.py @@ -0,0 +1,179 @@ +# SPDX-License-Identifier: Apache-2.0 +"""The planner in the runtime: demo plan, hand-over to the stack, events, stop order (WP9).""" + +from __future__ import annotations + +import asyncio +import threading +import time +from collections.abc import AsyncIterator +from pathlib import Path +from typing import Any + +import pytest + +from suncore.api import create_app +from suncore.app.runtime import Runtime +from suncore.core.config import BatteryTarget, GoalsConfig +from suncore.core.control import Plan +from suncore.core.controlstate import OverrideCommand +from suncore.planner.run import PlannerRun, run +from tests.api.conftest import client_for +from tests.app.test_tariff_runtime import start_runtime, until + + +@pytest.fixture +async def runtime(tmp_path: Path) -> AsyncIterator[Runtime]: + started = await start_runtime(tmp_path, "summer_day") + try: + yield started + finally: + await started.stop() + + +async def first_plan(runtime: Runtime) -> Plan: + assert runtime.planning is not None + planning = runtime.planning + await until(lambda: planning.plan is not None, timeout_s=30.0) + assert planning.plan is not None + return planning.plan + + +async def test_the_demo_runs_the_planner_on_its_prices_and_forecasts(runtime: Runtime) -> None: + plan = await first_plan(runtime) + assert plan.source in ("solver", "heuristic") + assert plan.intervals + assert plan.assumptions["price_mode"] == "market" + assert plan.assumptions["price_source"] == "tibber.price" + assert plan.assumptions["pv_missing_slots"] < 96 # the forecast covers the first day or two + async with client_for(create_app(runtime)) as client: + body = (await client.get("/api/v1/plan")).json() + status = (await client.get("/api/v1/plan/status")).json() + assert body["plan"]["source"] == plan.source + assert body["in_use"] is True + assert body["plan"]["intervals"][0]["prices"]["import_price"] > 0 + assert status["last_outcome"] == "ok" + + +async def test_the_control_stack_reads_the_plan_through_the_provider(runtime: Runtime) -> None: + plan = await first_plan(runtime) + stack = runtime.stack + assert stack is not None + now = runtime.clock() + assert stack.current_plan(now) is runtime.planning.active_plan(now) # type: ignore[union-attr] + assert not stack.current_plan(now).is_default + assert runtime.planning.plan is plan or runtime.planning.plan.created_at >= plan.created_at # type: ignore[union-attr] + # A rebuilt stack (configuration change) keeps following the same planner. + await runtime._rebuild_stack() + assert runtime.stack is not stack + assert not runtime.stack.current_plan(runtime.clock()).is_default # type: ignore[union-attr] + + +async def test_the_demo_plan_is_deterministic(runtime: Runtime) -> None: + await first_plan(runtime) + now = runtime.clock() + plans = [] + for _ in range(2): + snapshot = await runtime._collect_planning(now, None) + assert snapshot.inputs is not None + plans.append(run(snapshot.inputs, budget_s=8.0).plan) + assert plans[0].intervals == plans[1].intervals + assert plans[0].source == plans[1].source + + +async def test_events_ask_for_a_plan(runtime: Runtime) -> None: + await first_plan(runtime) + planning = runtime.planning + assert planning is not None + seen: list[str] = [] + planning.request = seen.append # type: ignore[method-assign,assignment] + # prices, forecasts + assert runtime.tariff is not None + for listener in list(runtime.tariff._listeners): + listener() + assert runtime.pv_service is not None + runtime.pv_service._notify() + assert runtime.load_service is not None + runtime.load_service._notify() + assert seen == ["prices", "forecast", "forecast"] + # configuration + seen.clear() + await runtime.put_section( + "goals", GoalsConfig(battery_target=BatteryTarget(soc_pct=40.0, time="06:00")) + ) + assert "config" in seen + # operation changes do not matter for the plan + seen.clear() + await runtime.put_section("operation", runtime.modes.operation) + assert seen == [] + # user override + await runtime.override_device("pool_pump", OverrideCommand(action="pause")) + assert "override" in seen + + +async def test_a_replan_through_the_runtime_is_queued(runtime: Runtime) -> None: + await first_plan(runtime) + ack = await runtime.replan() + assert ack.accepted + status = await runtime.plan_status() + assert "manual" in status.pending or status.last_trigger == "manual" + + +async def test_a_hanging_planner_does_not_delay_the_release_on_stop(tmp_path: Path) -> None: + runtime = await start_runtime(tmp_path, "summer_day") + await first_plan(runtime) + planning = runtime.planning + assert planning is not None + release = threading.Event() + started = threading.Event() + + def hang(inputs: Any, budget: float, gap: float, previous: Plan | None) -> PlannerRun: + started.set() + release.wait(30) + return run(inputs, budget_s=budget, mip_gap=gap, warm_start=previous) + + planning._solve = hang # type: ignore[assignment] + planning._settings = type(planning.settings)(min_event_gap_s=0.0, run_timeout_margin_s=60.0) + planning.request("manual") + await until(started.is_set, timeout_s=30.0) + assert planning.status().running + stack = runtime.stack + assert stack is not None + order: list[str] = [] + real_shutdown = stack.shutdown + + async def shutdown() -> None: + order.append("release") + await real_shutdown() + + stack.shutdown = shutdown # type: ignore[method-assign] + began = time.monotonic() + await asyncio.wait_for(runtime.stop(), timeout=20.0) + assert time.monotonic() - began < 15.0 + assert order == ["release"] + task = runtime._planning_task + assert task is None + release.set() + + +async def test_stop_awaits_the_planning_task_after_the_devices_are_released( + tmp_path: Path, +) -> None: + runtime = await start_runtime(tmp_path, "summer_day") + await first_plan(runtime) + stack = runtime.stack + task = runtime._planning_task + assert stack is not None + assert task is not None + observed: list[bool] = [] + real_shutdown = stack.shutdown + + async def shutdown() -> None: + await real_shutdown() + # Cancelled early (as the other storage tasks) but only awaited once the release ran. + observed.append(task.cancelling() > 0 or task.cancelled() or task.done()) + + stack.shutdown = shutdown # type: ignore[method-assign] + await runtime.stop() + assert observed == [True] + assert task.done() diff --git a/tests/app/test_tariff_runtime.py b/tests/app/test_tariff_runtime.py new file mode 100644 index 0000000..d3efee6 --- /dev/null +++ b/tests/app/test_tariff_runtime.py @@ -0,0 +1,271 @@ +# SPDX-License-Identifier: Apache-2.0 +"""The price service in the runtime: demo wiring, refresh on events, API, rebuild on change.""" + +from __future__ import annotations + +import asyncio +from collections.abc import AsyncIterator, Callable +from datetime import timedelta, timezone +from pathlib import Path + +import pytest + +from suncore.api import create_app +from suncore.app.demo import DemoClock +from suncore.app.main import build_runtime +from suncore.app.runtime import Runtime +from suncore.core.config import ExportTariff, ImportTariff, TariffConfig +from suncore.core.site import EntityRef +from suncore.ha.connection import ConnectionState, EntityState, EntityUpdate +from suncore.sim.demo_devices import PRICE_ID, sim_price +from suncore.sim.fake_ha import FakeHAConnection +from suncore.sim.scenario import load_scenario +from suncore.tariff import TariffService +from tests.api.conftest import client_for +from tests.app.conftest import demo_settings + +SPEED = 600.0 +START_HOUR = 14 +SIM_ZONE = timezone(timedelta(hours=2)) # the scenario's offset + + +class Subscribed(FakeHAConnection): + def __init__(self, scenario_name: str, clock: DemoClock) -> None: + super().__init__( + load_scenario(scenario_name), + clock=clock, + speed=SPEED, + sim_clock=clock, + start_offset_s=START_HOUR * 3600, + ) + self.subscriptions: list[frozenset[str]] = [] + + async def subscribe_entities(self, entity_ids: object) -> None: + self.subscriptions.append(frozenset(entity_ids)) # type: ignore[call-overload] + await super().subscribe_entities(entity_ids) # type: ignore[arg-type] + + +async def until(predicate: Callable[[], bool], timeout_s: float = 10.0) -> None: + async with asyncio.timeout(timeout_s): + while not predicate(): # noqa: ASYNC110 - polling a plain predicate + await asyncio.sleep(0.01) + + +async def start_runtime(tmp_path: Path, scenario_name: str) -> Runtime: + scenario = load_scenario(scenario_name) + clock = DemoClock( + scenario.start.replace(hour=START_HOUR), SPEED + ) # tomorrow's prices are published + connection = Subscribed(scenario_name, clock) + runtime = await build_runtime( + demo_settings(tmp_path, demo_speed=SPEED), env={}, connection=connection, clock=clock + ) + runtime.control_sleep = clock.sleep # the price loop polls in simulated time, like the demo + await runtime.start() + return runtime + + +@pytest.fixture +async def runtime(tmp_path: Path) -> AsyncIterator[Runtime]: + started = await start_runtime(tmp_path, "summer_day") + try: + yield started + finally: + await started.stop() + + +def service_of(runtime: Runtime) -> TariffService: + assert runtime.tariff is not None + return runtime.tariff + + +async def fetched(runtime: Runtime) -> TariffService: + service = service_of(runtime) + await until(lambda: service.report(24).freshness.fetched_at is not None) + return service + + +async def test_demo_tariff_goes_through_the_tibber_template_and_the_fake_action( + runtime: Runtime, +) -> None: + service = await fetched(runtime) + report = service.report(24) + assert report.source.import_source_id == "tibber.price" + assert report.source.import_kind == "dynamic" + assert report.source.native_step_min == 15 + assert report.source.price_includes == "all_in" + assert not report.source.formula_applied + assert report.freshness.status == "fresh" + assert report.quality.known_slots == report.quality.slots + assert report.quality.has_tomorrow + assert report.quality.slots > 24 * 4 + slot = report.slots[0] + assert slot.import_price == pytest.approx(sim_price(slot.start.astimezone(SIM_ZONE))) + assert slot.export_price == 0.08 # the demo's fixed feed-in remuneration + + +async def test_the_prices_reach_timeseries_db(runtime: Runtime) -> None: + await fetched(runtime) + assert runtime.timeseries is not None + from suncore.core.series import TimeRange # noqa: PLC0415 + + now = runtime.clock() + stored = await runtime.timeseries.read_prices( + "tibber.price", TimeRange(start=now, end=now + timedelta(hours=24)) + ) + assert stored + assert stored[0].step == timedelta(minutes=15) + assert stored[0].export_price is not None + + +async def test_negative_prices_scenario_zeroes_export_in_the_slots_below_zero( + tmp_path: Path, +) -> None: + runtime = await start_runtime(tmp_path, "negative_prices") + try: + service = await fetched(runtime) + report = service.report(24) + negative = [s for s in report.slots if s.import_price is not None and s.import_price < 0] + assert negative, "the scenario has a negative midday" + assert all(s.export_price == 0.0 for s in negative) + others = [s for s in report.slots if s.import_price is not None and s.import_price >= 0] + assert all(s.export_price == 0.08 for s in others) + assert report.source.negative_price_rule == "no_remuneration" # region template `de` + assert report.source.export_zeroed_slots == len(negative) + finally: + await runtime.stop() + + +async def test_the_api_serves_the_report(runtime: Runtime) -> None: + await fetched(runtime) + async with client_for(create_app(runtime)) as client: + r = await client.get("/api/v1/prices", params={"hours": 12}) + assert r.status_code == 200 + body = r.json() + assert body["freshness"]["status"] == "fresh" + assert 12 * 4 <= len(body["slots"]) <= 24 * 4 + 1 # at least 24 h are kept ... capped at 12 h + assert len(body["slots"]) <= 12 * 4 + 1 + + +async def test_the_price_entity_is_subscribed_and_a_change_marks_the_service( + runtime: Runtime, +) -> None: + service = await fetched(runtime) + conn = runtime.connection + assert isinstance(conn, Subscribed) + assert any(PRICE_ID in ids for ids in conn.subscriptions) + assert not service._state.dirty + runtime._on_entities( + EntityUpdate(changed={PRICE_ID: EntityState(PRICE_ID, "0.3", {})}, full=False) + ) + assert service._state.dirty + service._state.dirty = False + runtime._on_entities( + EntityUpdate(changed={"sensor.other": EntityState("sensor.other", "1", {})}) + ) + assert not service._state.dirty + + +async def test_reconnecting_clears_the_back_off(runtime: Runtime) -> None: + service = await fetched(runtime) + service._state.failures = 3 + runtime._on_state(ConnectionState.CONNECTED) + assert service._state.failures == 0 + + +async def test_putting_a_fixed_tariff_rebuilds_the_service_and_serves_static_prices( + runtime: Runtime, +) -> None: + old = service_of(runtime) + await runtime.put_section( + "tariff", + TariffConfig( + import_=ImportTariff(kind="fixed", fixed_price=0.33), + export=ExportTariff(kind="none"), + ), + ) + new = service_of(runtime) + assert new is not old + await until(lambda: new.report(24).freshness.fetched_at is not None) + report = new.report(24) + assert report.freshness.status == "static" + assert {s.import_price for s in report.slots} == {0.33} + assert {s.export_price for s in report.slots} == {0.0} + assert (await runtime.prices(24)).source.import_source_id == "fixed" + + +async def test_putting_a_price_entity_only_tariff_uses_the_current_slot(runtime: Runtime) -> None: + await runtime.put_section( + "tariff", + TariffConfig( + import_=ImportTariff(kind="dynamic", price_entity=EntityRef(entity_id=PRICE_ID)), + export=ExportTariff(kind="fixed", fixed_price=0.08), + ), + ) + service = service_of(runtime) + await until(lambda: service.report(24).freshness.fetched_at is not None) + assert service.report(24).source.import_source_id == "entity" + + +async def test_an_unusable_template_leaves_the_service_off_and_the_api_says_so( + runtime: Runtime, +) -> None: + await runtime.put_section( + "tariff", + TariffConfig( + import_=ImportTariff(kind="dynamic", template_id="no.such_template"), + export=ExportTariff(kind="none"), + ), + ) + assert runtime.tariff is None + async with client_for(create_app(runtime)) as client: + r = await client.get("/api/v1/prices") + assert r.status_code == 404 + + +async def test_a_tiered_export_without_the_plant_size_leaves_the_service_off( + runtime: Runtime, +) -> None: + from suncore.core.config import ExportTier # noqa: PLC0415 + + site = runtime.site + assert site is not None + # The demo plant has 8 kWp since the PV forecast (the clear-sky model reads it): drop it. + await runtime.put_section( + "site", + site.model_copy(update={"pv": [a.model_copy(update={"kwp": None}) for a in site.pv]}), + ) + await runtime.put_section( + "tariff", + TariffConfig( + import_=ImportTariff(kind="fixed", fixed_price=0.3), + export=ExportTariff(kind="tiered", tiers=(ExportTier(price=0.08),)), + ), + ) + assert runtime.tariff is None # the site has no kWp: no rate is guessed + + +async def test_stop_cancels_the_price_loop(tmp_path: Path) -> None: + runtime = await start_runtime(tmp_path, "summer_day") + task = runtime._tariff_task + assert task is not None + await runtime.stop() + assert task.done() + assert runtime._tariff_task is None + + +async def test_the_system_check_warns_about_spot_prices_without_a_formula(runtime: Runtime) -> None: + keys = [i.reason.key for i in await runtime.system_check(None)] + assert "wizard.check.tariff_spot_without_formula" not in keys # Tibber is all-in + await runtime.put_section( + "tariff", + TariffConfig( + import_=ImportTariff( + kind="dynamic", template_id="tibber.price", price_includes="spot_only" + ), + export=ExportTariff(kind="none"), + ), + ) + items = await runtime.system_check(None) + (warning,) = [i for i in items if i.reason.key == "wizard.check.tariff_spot_without_formula"] + assert warning.severity == "warn" diff --git a/tests/controller/test_plan_handover.py b/tests/controller/test_plan_handover.py new file mode 100644 index 0000000..63fffce --- /dev/null +++ b/tests/controller/test_plan_handover.py @@ -0,0 +1,295 @@ +# SPDX-License-Identifier: Apache-2.0 +"""The plan hand-over (Phase 4 WP9): a plan can only restrict the devices and move the surplus. + +* ``priority_until_soc_pct`` is judged against the live SoC of every tick; +* device bands never force a device on and never raise a level above what the plan-less + controller reaches (property test); +* a plan interval that does not cover ``now`` leaves the Phase 3 goal rules in charge; +* the controller never proposes a battery action, whatever the battery band says (the gate + rejects them anyway until WP10: ``tests/safety/test_gate.py``, the scenario test in + ``tests/sim/test_planner_shadow.py``). +""" + +from __future__ import annotations + +import itertools +from dataclasses import dataclass +from datetime import datetime, timedelta + +from hypothesis import given, settings +from hypothesis import strategies as st + +from suncore.controller import Controller, ControllerInputs +from suncore.core.config import BatteryTarget, GoalsConfig +from suncore.core.control import ( + BandPreference, + BatteryBand, + DeviceBand, + DeviceState, + Plan, + PlanInterval, + PowerEstimate, +) +from suncore.core.decisions import BatteryAction, Decision, DecisionKind, Intent, OperatingMode +from tests.safety.helpers import T0, flows, steps_device, switch_device + +GOALS = GoalsConfig(climate_before_export=True) +HEATER = steps_device("heater") +EST = PowerEstimate(value_w=0.0, uncertainty_w=5.0) +STEP_W = (0.0, 1000.0, 3000.0) + + +def at(seconds: float) -> datetime: + return T0 + timedelta(seconds=seconds) + + +def plan_of( + battery: BatteryBand | None = None, + device: DeviceBand | None = None, + *, + start: datetime = T0, + hours: float = 24.0, +) -> Plan: + return Plan( + intervals=( + PlanInterval( + start=start, + end=start + timedelta(hours=hours), + battery=battery or BatteryBand(), + devices={} if device is None else {"heater": device}, + ), + ) + ) + + +def accepted(intent: Intent) -> Decision: + return Decision( + intent=intent, kind=DecisionKind.ACCEPTED, ts=intent.ts, mode=OperatingMode.AUTOMATIC + ) + + +def run_heater( + plan: Plan, *, grid_w: float, soc_pct: float = 50.0, battery_w: float = 0.0, seconds: int = 240 +) -> tuple[int, list[Intent]]: + """Tick a step heater on a constant surplus; returns its final step and all intents.""" + controller = Controller([HEATER]) + step = 0 + sent: list[Intent] = [] + for k in range(seconds // 5): + result = controller.step( + at(5 * k), + ControllerInputs( + flows=flows(grid_w=grid_w, battery_w=battery_w, soc_pct=soc_pct), + states={"heater": DeviceState(step=step)}, + estimates={"heater": EST}, + goals=GOALS, + plan=plan, + ), + ) + for intent in result.intents: + controller.report(accepted(intent)) + step = intent.action.step # type: ignore[union-attr] + sent.append(intent) + return step, sent + + +def test_priority_judges_the_live_soc_every_tick() -> None: + """Battery first below the priority, then the surplus may go to the consumers.""" + band = BatteryBand(charge_from_surplus=False, priority_until_soc_pct=60.0) + controller = Controller([HEATER]) + + def charging(soc: float) -> bool: + result = controller.step( + at(0), + ControllerInputs( + flows=flows(grid_w=0.0, battery_w=3000.0, soc_pct=soc), + states={"heater": DeviceState(step=0)}, + estimates={"heater": EST}, + goals=GOALS, + plan=plan_of(band), + ), + ) + return result.site.charging_available + + assert not charging(40.0) + assert not charging(59.9) + assert charging(60.0) + assert not charging(30.0) # the SoC fell again (a deviation from the plan): battery first + + +def test_below_the_priority_the_heater_gets_nothing_from_the_battery_share() -> None: + surplus_from_battery = {"grid_w": 0.0, "battery_w": 3500.0} + band = BatteryBand(charge_from_surplus=False, priority_until_soc_pct=80.0) + low, _ = run_heater(plan_of(band), soc_pct=50.0, **surplus_from_battery) + high, _ = run_heater(plan_of(band), soc_pct=85.0, **surplus_from_battery) + assert low == 0 # the charging power stays with the battery + assert high >= 1 + + +def test_a_plan_that_ran_out_leaves_the_goal_rules_in_charge() -> None: + """Outside every interval the band is ``None``: the Phase 3 goal decides, not the empty band.""" + goals = GoalsConfig(battery_target=BatteryTarget(soc_pct=80.0, time="06:00")) + ran_out = plan_of( + BatteryBand(charge_from_surplus=False), start=T0 - timedelta(hours=2), hours=1 + ) + controller = Controller([HEATER]) + result = controller.step( + at(0), + ControllerInputs( + flows=flows(grid_w=0.0, battery_w=3000.0, soc_pct=50.0), + states={"heater": DeviceState(step=0)}, + estimates={"heater": EST}, + goals=goals, + plan=ran_out, + ), + ) + assert not result.site.charging_available # the target (80 %) blocks it, as in Phase 3 + assert result.site.target_soc_pct == 80.0 + + +def test_the_controller_never_proposes_a_battery_action() -> None: + band = BatteryBand( + min_power_w=0.0, + max_power_w=3000.0, + min_soc_pct=12.0, + max_soc_pct=95.0, + grid_charge_max_w=2500.0, + discharge_lock=True, + priority_until_soc_pct=70.0, + charge_from_surplus=False, + ) + for grid_w in (-4000.0, 0.0, 2000.0): + for soc in (10.0, 50.0, 99.0): + _, sent = run_heater(plan_of(band), grid_w=grid_w, soc_pct=soc, battery_w=1000.0) + assert not [i for i in sent if isinstance(i.action, BatteryAction)] + + +@dataclass(frozen=True) +class Case: + allowed: bool + max_power_w: float | None + preference: BandPreference + grid_w: float + soc: float + from_surplus: bool + priority: float | None + + +CASES = st.builds( + Case, + allowed=st.booleans(), + max_power_w=st.one_of(st.none(), st.floats(min_value=0.0, max_value=6000.0)), + preference=st.sampled_from(list(BandPreference)), + grid_w=st.floats(min_value=-6000.0, max_value=3000.0), + soc=st.floats(min_value=0.0, max_value=100.0), + from_surplus=st.booleans(), + priority=st.one_of(st.none(), st.floats(min_value=0.0, max_value=100.0)), +) + + +@settings(max_examples=60, deadline=None) +@given(case=CASES) +def test_a_plan_never_raises_a_device_above_the_plan_less_controller(case: Case) -> None: + """Device bands only restrict; ``prefer_on`` forces nothing. The battery band only moves the + surplus share; the comparison below isolates the device band's effect.""" + device = DeviceBand( + allowed=case.allowed, max_power_w=case.max_power_w, preference=case.preference + ) + battery = BatteryBand( + charge_from_surplus=case.from_surplus, priority_until_soc_pct=case.priority + ) + world = {"grid_w": case.grid_w, "soc_pct": case.soc, "battery_w": 1500.0} + free, _ = run_heater(plan_of(battery), **world) + restricted, sent = run_heater(plan_of(battery, device), **world) + assert restricted <= free + cap = 2 + if not case.allowed: + cap = 0 + elif case.max_power_w is not None: + cap = max((k for k, w in enumerate(STEP_W) if w <= case.max_power_w), default=0) + assert restricted <= cap + # Every command on the way stayed inside the cap too (no overshoot that is taken back). + assert all(i.action.step <= cap for i in sent) # type: ignore[union-attr] + + +@settings(max_examples=40, deadline=None) +@given( + battery_w=st.floats(min_value=0.0, max_value=4000.0), + soc=st.floats(min_value=0.0, max_value=100.0), + priority=st.floats(min_value=0.0, max_value=100.0), + from_surplus=st.booleans(), +) +def test_below_its_priority_a_plan_gives_the_heater_no_more_than_no_plan( + battery_w: float, soc: float, priority: float, from_surplus: bool +) -> None: + band = BatteryBand(charge_from_surplus=from_surplus, priority_until_soc_pct=priority) + planned, _ = run_heater(plan_of(band), grid_w=0.0, soc_pct=soc, battery_w=battery_w) + plain, _ = run_heater(Plan.default(), grid_w=0.0, soc_pct=soc, battery_w=battery_w) + if soc < priority: + assert planned <= plain + + +def test_a_default_plan_is_the_phase_3_controller() -> None: + no_plan, _ = run_heater(Plan.default(), grid_w=-6000.0) + open_plan, _ = run_heater(plan_of(BatteryBand(), DeviceBand()), grid_w=-6000.0) + assert no_plan == open_plan == 2 + + +# --- flapping plan bands (control-safety review m1) ---------------------------------------- + + +def _flapping( + *, min_run_s: int = 0, min_pause_s: int = 0, max_switches: int | None = None, hours: int = 3 +) -> list[tuple[float, bool]]: + """A switch under steady surplus while the plan alternates allowed/blocked every 15 min.""" + device = switch_device( + "pool", min_run_s=min_run_s, min_pause_s=min_pause_s, max_switches_per_hour=max_switches + ) + intervals = [] + for k in range(hours * 4): + start = T0 + timedelta(minutes=15 * k) + band = DeviceBand() if k % 2 == 0 else DeviceBand(allowed=False, max_power_w=0.0) + intervals.append( + PlanInterval(start=start, end=start + timedelta(minutes=15), devices={"pool": band}) + ) + plan = Plan(intervals=tuple(intervals)) + controller = Controller([device]) + on = False + switches: list[tuple[float, bool]] = [] + for k in range(hours * 3600 // 5): + now = at(5 * k) + result = controller.step( + now, + ControllerInputs( + flows=flows(grid_w=-4000.0 + (1000.0 if on else 0.0), battery_w=0.0, soc_pct=50.0), + states={"pool": DeviceState(on=on)}, + estimates={"pool": PowerEstimate(value_w=1000.0 if on else 0.0, uncertainty_w=5.0)}, + goals=GOALS, + plan=plan, + ), + ) + for intent in result.intents: + controller.report(accepted(intent)) + on = bool(getattr(intent.action, "on", on)) + switches.append(((now - T0).total_seconds(), on)) + return switches + + +def _per_hour(switches: list[tuple[float, bool]]) -> list[int]: + hours = int(max((s for s, _ in switches), default=0) // 3600) + 1 + return [sum(1 for s, _ in switches if h * 3600 <= s < (h + 1) * 3600) for h in range(hours)] + + +def test_flapping_bands_respect_the_switch_limit() -> None: + default_limit = 6 # ControlSettings.default_max_switches_per_hour + assert all(n <= default_limit for n in _per_hour(_flapping())) + limited = _flapping(max_switches=2) + assert limited + assert all(n <= 2 for n in _per_hour(limited)) + + +def test_flapping_bands_respect_the_minimum_run_and_pause() -> None: + switches = _flapping(min_run_s=1200, min_pause_s=600) + assert switches + for (t0, on0), (t1, _) in itertools.pairwise(switches): + assert t1 - t0 >= (1200 if on0 else 600) diff --git a/tests/controller/test_surplus.py b/tests/controller/test_surplus.py index 8704a79..e8481ca 100644 --- a/tests/controller/test_surplus.py +++ b/tests/controller/test_surplus.py @@ -120,13 +120,26 @@ def test_battery_share_follows_the_goals( assert battery_share_available(goals, soc) == expected -def test_a_plan_band_decides_over_the_goals() -> None: +def test_a_plan_band_decides_over_the_goals_above_the_target() -> None: goals = GoalsConfig(battery_target=TARGET) band = BatteryBand(charge_from_surplus=False) - assert battery_share_available(goals, 10.0, band) == (True, None) + assert battery_share_available(goals, 90.0, band) == (True, None) + # The user's target stays a floor under a plan (review D1). + assert battery_share_available(goals, 10.0, band) == (False, 80) + assert battery_share_available(goals, None, band) == (False, 80) assert battery_share_available(GOALS, 90.0, BatteryBand()) == (False, None) +def test_the_adr_0013_band_fields_do_not_change_the_controller_yet() -> None: + """Until WP10 (4-G) the controller ignores ``grid_charge_max_w`` and ``discharge_lock``.""" + for plain in (BatteryBand(), BatteryBand(charge_from_surplus=False)): + planned = plain.model_copy(update={"grid_charge_max_w": 3000.0, "discharge_lock": True}) + for soc in (None, 10.0, 90.0): + assert battery_share_available(GOALS, soc, planned) == battery_share_available( + GOALS, soc, plain + ) + + # --- tracker ------------------------------------------------------------------------- @@ -253,3 +266,56 @@ def test_reset_forgets_window_and_members() -> None: tracker.reset() site = tracker.update(at(5), flows(grid_w=-200.0), GOALS, controlled_draw={"p": 500.0}) assert site.available_w == 700.0 + + +# --- priority_until_soc_pct against the live SoC (Phase 4 WP9) --------------------------- + +PRIORITY_GOALS = st.sampled_from( + [ + GoalsConfig(), + GoalsConfig(climate_before_export=True), + GoalsConfig(battery_target=TARGET), + GoalsConfig(battery_target=TARGET, climate_before_export=True), + ] +) +SOC = st.one_of(st.none(), st.floats(min_value=0.0, max_value=100.0)) + + +def test_priority_keeps_the_battery_first_until_the_live_soc_reaches_it() -> None: + band = BatteryBand(charge_from_surplus=False, priority_until_soc_pct=60.0) + assert battery_share_available(GOALS, 59.9, band) == (False, 60.0) + assert battery_share_available(GOALS, None, band) == (False, 60.0) # unknown = not reached + # Reached: the band's own rule applies again (devices before the battery here). + assert battery_share_available(GOALS, 60.0, band) == (True, None) + assert battery_share_available( + GOALS, 60.0, band.model_copy(update={"charge_from_surplus": True}) + ) == ( + False, + None, + ) + + +@given( + goals=PRIORITY_GOALS, + soc=SOC, + priority=st.floats(min_value=0.0, max_value=100.0), + from_surplus=st.booleans(), +) +def test_below_its_priority_a_plan_never_gives_the_consumers_more( + goals: GoalsConfig, soc: float | None, priority: float, from_surplus: bool +) -> None: + band = BatteryBand(charge_from_surplus=from_surplus, priority_until_soc_pct=priority) + without_priority = battery_share_available( + goals, soc, band.model_copy(update={"priority_until_soc_pct": None}) + ) + with_priority, _ = battery_share_available(goals, soc, band) + if soc is None or soc < priority: + assert with_priority is False # battery first, whatever else the band says + # A priority only ever takes surplus away from the consumers. + assert with_priority <= without_priority[0] + # Below max(priority, user target) a plan never gives the consumers more than Phase 3 + # (no plan) would (review D1: the target is a floor under a plan as well). + target = 0.0 if goals.battery_target is None else goals.battery_target.soc_pct + if soc is None or soc < max(priority, target): + phase3, _ = battery_share_available(goals, soc) + assert with_priority <= phase3 diff --git a/tests/core/test_config_phase4.py b/tests/core/test_config_phase4.py index 3fa38b6..5c0d235 100644 --- a/tests/core/test_config_phase4.py +++ b/tests/core/test_config_phase4.py @@ -237,3 +237,87 @@ def test_forecast_load_entities_are_checked_and_listed() -> None: ForecastConfig.model_validate({"load": {"workday": {"entity_id": "sensor.x"}}}) with pytest.raises(ValidationError, match="forecast_weather_domain"): ForecastConfig.model_validate({"load": {"weather": {"entity_id": "sensor.x"}}}) + + +# --- tariff source settings (WP4, additive) ---------------------------------------------- + + +def test_dynamic_import_takes_source_settings_and_lists_their_entities() -> None: + from suncore.core.site import EntityRef # noqa: PLC0415 + + body = { + "import": { + "kind": "dynamic", + "template_id": "octopus_energy.rates", + "price_entity": {"entity_id": "sensor.rate"}, + "role_entities": { + "current_day_rates": {"entity_id": "event.today"}, + "next_day_rates": {"entity_id": "event.tomorrow"}, + }, + "action_params": {"config_entry": "01H", "areas": ["SE3", "SE4"]}, + "series_key": "SE3", + "price_includes": "all_in", + }, + "export": {"kind": "none"}, + } + tariff = TariffConfig.model_validate(body) + assert [r.entity_id for r in tariff.entity_refs()] == [ + "sensor.rate", + "event.today", + "event.tomorrow", + ] + assert tariff.import_.action_params["areas"] == ["SE3", "SE4"] + assert EntityRef(entity_id="sensor.rate") in tariff.entity_refs() + again = TariffConfig.model_validate(tariff.model_dump(mode="json", by_alias=True)) + assert again == tariff + + +def test_older_tariff_documents_load_without_the_new_fields() -> None: + tariff = TariffConfig.model_validate( + {"import": {"kind": "dynamic", "template_id": "tibber.price"}, "export": {"kind": "none"}} + ) + assert tariff.import_.role_entities == {} + assert tariff.import_.action_params == {} + assert tariff.import_.series_key is None + assert tariff.import_.price_includes is None + + +@pytest.mark.parametrize( + "extra", + [ + {"role_entities": {"x": {"entity_id": "sensor.x"}}}, + {"action_params": {"a": "b"}}, + {"series_key": "SE3"}, + {"price_includes": "all_in"}, + ], +) +def test_source_settings_need_a_dynamic_tariff(extra: dict[str, Any]) -> None: + with pytest.raises(ValidationError) as err: + TariffConfig.model_validate( + {"import": {"kind": "fixed", "fixed_price": 0.3, **extra}, "export": {"kind": "none"}} + ) + assert "suncore.import_source_dynamic_only" in str(err.value) + + +def test_the_price_role_is_the_price_entity() -> None: + with pytest.raises(ValidationError) as err: + TariffConfig.model_validate( + { + "import": { + "kind": "dynamic", + "template_id": "tibber.price", + "role_entities": {"price": {"entity_id": "sensor.x"}}, + }, + "export": {"kind": "none"}, + } + ) + assert "suncore.import_role_price" in str(err.value) + + +def test_action_params_reject_empty_and_oversized_values() -> None: + base = {"kind": "dynamic", "template_id": "nordpool.price"} + for params in ({"": "x"}, {"a": ""}, {"a": "x" * 201}, {"a": []}, {"a": [""]}, {"a": 5}): + with pytest.raises(ValidationError): + TariffConfig.model_validate( + {"import": {**base, "action_params": params}, "export": {"kind": "none"}} + ) diff --git a/tests/core/test_plan_v2.py b/tests/core/test_plan_v2.py index 804fc17..142e101 100644 --- a/tests/core/test_plan_v2.py +++ b/tests/core/test_plan_v2.py @@ -137,3 +137,26 @@ def test_plan_source_stats_and_band_validation() -> None: with pytest.raises(ValidationError): BatteryBand(priority_until_soc_pct=120) assert IntervalFlows(pv_p50_w=0, load_w=0, import_w=0, export_w=0).battery_w == 0 + + +def test_adr_0013_battery_band_fields_are_additive() -> None: + """``grid_charge_max_w`` and ``discharge_lock`` (ADR-0013 decision 4) default to "none".""" + band = BatteryBand() + assert band.grid_charge_max_w is None + assert band.discharge_lock is False + planned = BatteryBand(grid_charge_max_w=2500, discharge_lock=True, min_power_w=0) + assert BatteryBand.model_validate(planned.model_dump(mode="json")) == planned + with pytest.raises(ValidationError): + BatteryBand(grid_charge_max_w=-1) + old = {"min_soc_pct": 15, "charge_from_surplus": False} + assert BatteryBand.model_validate(old).discharge_lock is False + + +def test_interval_flows_devices_and_curtailment_are_additive() -> None: + flows = IntervalFlows(pv_p50_w=5000, load_w=500, import_w=0, export_w=2000, battery_w=1000) + assert flows.devices_w == 0 + assert flows.curtail_w == 0 + full = flows.model_copy(update={"devices_w": 1000.0, "curtail_w": 500.0}) + assert IntervalFlows.model_validate(full.model_dump(mode="json")) == full + with pytest.raises(ValidationError): + IntervalFlows(pv_p50_w=0, load_w=0, import_w=0, export_w=0, curtail_w=-1) diff --git a/tests/core/test_series.py b/tests/core/test_series.py index f7715cb..e6190e4 100644 --- a/tests/core/test_series.py +++ b/tests/core/test_series.py @@ -228,13 +228,14 @@ def test_segments_from_points_split_on_resolution_change() -> None: points = [(T0 + MIN15 * i, float(i)) for i in range(4)] + [ (T0 + HOUR, 10.0), (T0 + 2 * HOUR, 20.0), + (T0 + 3 * HOUR, 30.0), ] segments = segments_from_points( points, SeriesUnit.PRICE, expected_step=MIN15, other_steps={HOUR} ) - assert [(s.step, len(s)) for s in segments] == [(MIN15, 4), (HOUR, 2)] + assert [(s.step, len(s)) for s in segments] == [(MIN15, 4), (HOUR, 3)] assert segments[0].values == (0.0, 1.0, 2.0, 3.0) - assert segments[-1].end == T0 + 3 * HOUR + assert segments[-1].end == T0 + 4 * HOUR single = segments_from_points([(T0, 1.0)], SeriesUnit.W, expected_step=MIN15) assert single[0].end == T0 + MIN15 assert segments_from_points([], SeriesUnit.W, expected_step=MIN15) == () @@ -242,6 +243,24 @@ def test_segments_from_points_split_on_resolution_change() -> None: segments_from_points([(T0, 1.0), (T0, 2.0)], SeriesUnit.W, expected_step=MIN15) +def test_a_hole_at_the_end_of_the_list_is_a_gap_not_a_resolution_change() -> None: + """Review m4: the last distance has no following distance to confirm an hourly rhythm.""" + points = [(T0 + MIN15 * i, float(i)) for i in range(3)] + [(T0 + 2 * MIN15 + HOUR, 9.0)] + (segment,) = segments_from_points( + points, SeriesUnit.PRICE, expected_step=MIN15, other_steps={HOUR} + ) + assert segment.step == MIN15 + assert segment.values == (0.0, 1.0, 2.0, None, None, None, 9.0) + # two further hourly points confirm the rhythm: now it is a change + more = [*points, (T0 + 2 * MIN15 + 2 * HOUR, 10.0)] + assert [ + s.step + for s in segments_from_points( + more, SeriesUnit.PRICE, expected_step=MIN15, other_steps={HOUR} + ) + ] == [MIN15, HOUR] + + def test_segments_from_points_gap_is_none_not_filled() -> None: """Reviewer example 1: 15-minute prices 10:00, 10:15, 10:45 -> 10:30 is missing.""" t10 = T0 + 10 * HOUR diff --git a/tests/core/test_tariff.py b/tests/core/test_tariff.py index bbd6200..29e5d15 100644 --- a/tests/core/test_tariff.py +++ b/tests/core/test_tariff.py @@ -105,12 +105,12 @@ def test_dst_night_is_judged_in_local_time() -> None: def test_price_formula() -> None: f = PriceFormula(grid_fee=0.08, levies=0.03, margin=0.02, vat_pct=19) - assert f.apply(0.10, None, BERLIN) == pytest.approx((0.10 + 0.13) * 1.19) - assert f.apply(-0.20, None, BERLIN) == pytest.approx( + assert f.end_price(0.10, None, BERLIN) == pytest.approx((0.10 + 0.13) * 1.19) + assert f.end_price(-0.20, None, BERLIN) == pytest.approx( (-0.20 + 0.13) * 1.19 ) # negative end price - assert PriceFormula().apply(0.1, None, BERLIN) == pytest.approx(0.1) - assert PriceFormula(spot_multiplier=1.1).apply(0.1, None, BERLIN) == pytest.approx(0.11) + assert PriceFormula().end_price(0.1, None, BERLIN) == pytest.approx(0.1) + assert PriceFormula(spot_multiplier=1.1).end_price(0.1, None, BERLIN) == pytest.approx(0.11) def test_price_formula_time_variable_grid_fee() -> None: @@ -118,10 +118,10 @@ def test_price_formula_time_variable_grid_fee() -> None: high = GridFeeWindow(window=TouWindow(start="17:00", end="20:00"), fee=0.15) f = PriceFormula(grid_fee=0.08, grid_fee_windows=(low, high)) assert f.grid_fee_at(None, BERLIN) == 0.08 - assert f.apply(0.1, at(FRI, 3), BERLIN) == pytest.approx(0.12) - assert f.apply(0.1, at(FRI, 18), BERLIN) == pytest.approx(0.25) - assert f.apply(0.1, at(FRI, 12), BERLIN) == pytest.approx(0.18) - assert f.apply(0.1, datetime(2026, 10, 16, 1, tzinfo=UTC), BERLIN) == pytest.approx(0.12) + assert f.end_price(0.1, at(FRI, 3), BERLIN) == pytest.approx(0.12) + assert f.end_price(0.1, at(FRI, 18), BERLIN) == pytest.approx(0.25) + assert f.end_price(0.1, at(FRI, 12), BERLIN) == pytest.approx(0.18) + assert f.end_price(0.1, datetime(2026, 10, 16, 1, tzinfo=UTC), BERLIN) == pytest.approx(0.12) with pytest.raises(ValidationError): PriceFormula(spot_multiplier=0) with pytest.raises(ValidationError): @@ -222,3 +222,8 @@ def test_utc_instant_is_judged_in_the_given_zone_not_its_own() -> None: utc_23 = datetime(2026, 10, 16, 21, 30, tzinfo=UTC) # 23:30 in Berlin assert NIGHT_WINDOW.contains(utc_23, BERLIN) assert not NIGHT_WINDOW.contains(utc_23, UTC) + + +def test_apply_is_a_deprecated_alias_of_end_price() -> None: + f = PriceFormula(grid_fee=0.1, vat_pct=19) + assert f.apply(0.2, None, BERLIN) == f.end_price(0.2, None, BERLIN) diff --git a/tests/core/test_wizard.py b/tests/core/test_wizard.py index bc74deb..528d943 100644 --- a/tests/core/test_wizard.py +++ b/tests/core/test_wizard.py @@ -7,7 +7,7 @@ import pytest -from suncore.core.config import DevicesConfig +from suncore.core.config import DevicesConfig, TariffConfig from suncore.core.devices import DeviceConfig from suncore.core.signals import Quality, Sample from suncore.core.site import ( @@ -383,3 +383,32 @@ def test_no_duplicate_for_different_names_one_registry_device_or_unknown_registr registry.get, ) assert not any(i.reason.key == "wizard.check.duplicate_unit" for i in plugs) + + +# --- tariff check (review m1) --------------------------------------------------------- + + +def _tariff(**imp: object) -> TariffConfig: + return TariffConfig.model_validate( + {"import": {"kind": "dynamic", "template_id": "x.y", **imp}, "export": {"kind": "none"}} + ) + + +def test_spot_only_prices_without_a_formula_are_a_warning() -> None: + from suncore.core.wizard import check_tariff # noqa: PLC0415 + + (item,) = check_tariff(_tariff(), "spot_only") + assert item.severity == "warn" + assert item.reason.key == "wizard.check.tariff_spot_without_formula" + assert item.subject == "tariff" + assert check_tariff(_tariff(formula={"grid_fee": 0.1}), "spot_only") == [] + assert check_tariff(_tariff(), "all_in") == [] + assert check_tariff(_tariff(), None) == [] # unknown source: the user decides + # the user's statement beats the template + assert check_tariff(_tariff(price_includes="all_in"), "spot_only") == [] + assert len(check_tariff(_tariff(price_includes="spot_only"), "all_in")) == 1 + assert check_tariff(None, "spot_only") == [] + fixed = TariffConfig.model_validate( + {"import": {"kind": "fixed", "fixed_price": 0.3}, "export": {"kind": "none"}} + ) + assert check_tariff(fixed, "spot_only") == [] diff --git a/tests/fixtures/tariff/entsoe_avg_price.yaml b/tests/fixtures/tariff/entsoe_avg_price.yaml new file mode 100644 index 0000000..36a237a --- /dev/null +++ b/tests/fixtures/tariff/entsoe_avg_price.yaml @@ -0,0 +1,19 @@ +# Attributes of the ENTSO-E `avg_price` sensor: +# docs/research/integrations.md "ENTSO-E" (lines 277-305, Phase 4 verification 2026-10-16); +# JaccoR/hass-entso-e@v0.7.5 sensor.py:269-279 (attributes prices_today, prices_tomorrow, +# prices) and coordinator.py:250-256 (entry `{time, price}`, `time` = str() of a +# timezone-aware local datetime: a SPACE instead of `T`). Synthetic values. +entities: + - entity_id: sensor.entsoe_average_electricity_price + state: "0.0834" + attributes: + unit_of_measurement: EUR/kWh + prices_today: + - {time: "2026-10-16 00:00:00+02:00", price: 0.0712} + - {time: "2026-10-16 01:00:00+02:00", price: 0.0690} + - {time: "2026-10-16 02:00:00+02:00", price: 0.0668} + prices_tomorrow: [] + prices: + - {time: "2026-10-16 00:00:00+02:00", price: 0.0712} + - {time: "2026-10-16 01:00:00+02:00", price: 0.0690} + - {time: "2026-10-16 02:00:00+02:00", price: 0.0668} diff --git a/tests/fixtures/tariff/epex_spot_total_price.yaml b/tests/fixtures/tariff/epex_spot_total_price.yaml new file mode 100644 index 0000000..59ee2c7 --- /dev/null +++ b/tests/fixtures/tariff/epex_spot_total_price.yaml @@ -0,0 +1,15 @@ +# Attributes of the EPEX Spot "Total Price" sensor: +# docs/research/integrations.md "EPEX Spot" (lines 307-332, Phase 4 verification 2026-10-16); +# mampfes/ha_epex_spot@4.1.0 const.py:6-8,14 and sensor.py:69-82 (attribute `data`, entries +# `{start_time, end_time, price_per_kwh}`, dt_util.as_local(...).isoformat()); the unit is the +# literal `€/kWh` (const.py:57). Synthetic values. +entities: + - entity_id: sensor.epex_spot_total_price + state: "0.2631" + attributes: + unit_of_measurement: "€/kWh" + data: + - {start_time: "2026-10-16T00:00:00+02:00", end_time: "2026-10-16T01:00:00+02:00", price_per_kwh: 0.2631} + - {start_time: "2026-10-16T01:00:00+02:00", end_time: "2026-10-16T02:00:00+02:00", price_per_kwh: 0.2587} + - {start_time: "2026-10-16T02:00:00+02:00", end_time: "2026-10-16T02:15:00+02:00", price_per_kwh: 0.2561} + - {start_time: "2026-10-16T02:15:00+02:00", end_time: "2026-10-16T02:30:00+02:00", price_per_kwh: 0.2549} diff --git a/tests/fixtures/tariff/generic_price_list.yaml b/tests/fixtures/tariff/generic_price_list.yaml new file mode 100644 index 0000000..35caeb4 --- /dev/null +++ b/tests/fixtures/tariff/generic_price_list.yaml @@ -0,0 +1,11 @@ +# SunCore's own convention for a template sensor (templates/tariff/generic.price_list.yaml): +# attribute `prices` = list of `{start, price}`. Not the shape of an existing integration. +entities: + - entity_id: sensor.my_price_list + state: "0.31" + attributes: + unit_of_measurement: EUR/kWh + prices: + - {start: "2026-10-16T00:00:00+02:00", price: 0.31} + - {start: "2026-10-16T00:15:00+02:00", price: 0.30} + - {start: "2026-10-16T00:30:00+02:00", price: 0.29} diff --git a/tests/fixtures/tariff/nordpool_get_prices_for_date.yaml b/tests/fixtures/tariff/nordpool_get_prices_for_date.yaml new file mode 100644 index 0000000..81fd262 --- /dev/null +++ b/tests/fixtures/tariff/nordpool_get_prices_for_date.yaml @@ -0,0 +1,12 @@ +# Shape of the response of `nordpool.get_prices_for_date`: +# docs/research/integrations.md "Nord Pool (Core)" (lines 235-275, Phase 4 verification +# 2026-10-16); home-assistant/core@5cfe9aad components/nordpool/services.py:140-150 and +# pynordpool 0.4.0. `{AREA: [{start, end, price}]}`, `start`/`end` are datetime.isoformat() of +# UTC datetimes (`+00:00`), `price` is the raw day-ahead value in currency per MWh. +# Synthetic values, not a recording. Local date 2026-10-16 in Europe/Berlin starts at +# 2026-10-15T22:00:00+00:00. +response: + SE3: + - {start: "2026-10-15T22:00:00+00:00", end: "2026-10-15T23:00:00+00:00", price: 45.5} + - {start: "2026-10-15T23:00:00+00:00", end: "2026-10-16T00:00:00+00:00", price: 41.25} + - {start: "2026-10-16T00:00:00+00:00", end: "2026-10-16T01:00:00+00:00", price: -3.5} diff --git a/tests/fixtures/tariff/octopus_rates.yaml b/tests/fixtures/tariff/octopus_rates.yaml new file mode 100644 index 0000000..279fbaf --- /dev/null +++ b/tests/fixtures/tariff/octopus_rates.yaml @@ -0,0 +1,25 @@ +# Attributes of the Octopus Energy current-day and next-day rate event entities: +# docs/research/integrations.md "Octopus Energy" (lines 334-371, Phase 4 verification +# 2026-10-16); BottlecapDave/HomeAssistant-OctopusEnergy@v19.2.1 utils/__init__.py:149-170 +# (private_rates_to_public_rates: `start`, `end`, `value_inc_vat`, optional `is_capped`, +# `is_intelligent_adjusted`) and core event/entity.py:145-152 (last event data become +# attributes next to `event_type`). Rates in GBP/kWh including VAT, 30-minute slots, local +# datetimes. Synthetic values. +entities: + - entity_id: event.octopus_energy_electricity_1234_5678_current_day_rates + state: "2026-10-16T00:05:00.000+00:00" + attributes: + event_type: octopus_energy_electricity_current_day_rates + min_rate: 0.1245 + max_rate: 0.3421 + rates: + - {start: "2026-10-16T00:00:00+01:00", end: "2026-10-16T00:30:00+01:00", value_inc_vat: 0.1245} + - {start: "2026-10-16T00:30:00+01:00", end: "2026-10-16T01:00:00+01:00", value_inc_vat: 0.1302, is_capped: false} + - {start: "2026-10-16T01:00:00+01:00", end: "2026-10-16T01:30:00+01:00", value_inc_vat: 0.1519} + - entity_id: event.octopus_energy_electricity_1234_5678_next_day_rates + state: "2026-10-16T16:05:00.000+00:00" + attributes: + event_type: octopus_energy_electricity_next_day_rates + rates: + - {start: "2026-10-17T00:00:00+01:00", end: "2026-10-17T00:30:00+01:00", value_inc_vat: 0.1010} + - {start: "2026-10-17T00:30:00+01:00", end: "2026-10-17T01:00:00+01:00", value_inc_vat: 0.0955} diff --git a/tests/fixtures/tariff/tibber_get_prices.yaml b/tests/fixtures/tariff/tibber_get_prices.yaml new file mode 100644 index 0000000..a5acb13 --- /dev/null +++ b/tests/fixtures/tariff/tibber_get_prices.yaml @@ -0,0 +1,15 @@ +# Shape of the response of `tibber.get_prices`: +# docs/research/integrations.md "Tibber (Core)" (lines 212-233, Phase 4 verification +# 2026-10-16) and docs/research/device-integrations.md "Action tibber.get_prices" +# (lines 286-317); home-assistant/core@5cfe9aad components/tibber/services.py. +# `start_time` is the string Tibber delivers (ISO 8601 with UTC offset, slot start); `price` +# is the total (energy plus tax) per kWh. Synthetic values, not a recording. +response: + prices: + Home: + - {start_time: "2026-10-16T00:00:00.000+02:00", price: 0.2812} + - {start_time: "2026-10-16T00:15:00.000+02:00", price: 0.2790} + - {start_time: "2026-10-16T00:30:00.000+02:00", price: 0.2755} + - {start_time: "2026-10-16T00:45:00.000+02:00", price: 0.2701} + - {start_time: "2026-10-16T01:00:00.000+02:00", price: 0.2688} + - {start_time: "2026-10-16T01:15:00.000+02:00", price: 0.2650} diff --git a/tests/ha/test_websocket_registry.py b/tests/ha/test_websocket_registry.py index c7797a9..daba8e2 100644 --- a/tests/ha/test_websocket_registry.py +++ b/tests/ha/test_websocket_registry.py @@ -216,6 +216,7 @@ def test_allowlist_is_exactly_the_verified_read_only_set() -> None: frozenset( { "tibber.get_prices", + "nordpool.get_prices_for_date", "solcast_solar.query_forecast_data", "weather.get_forecasts", "workday.check_date", diff --git a/tests/planner/__init__.py b/tests/planner/__init__.py new file mode 100644 index 0000000..9881313 --- /dev/null +++ b/tests/planner/__init__.py @@ -0,0 +1 @@ +# SPDX-License-Identifier: Apache-2.0 diff --git a/tests/planner/helpers.py b/tests/planner/helpers.py new file mode 100644 index 0000000..2655c2a --- /dev/null +++ b/tests/planner/helpers.py @@ -0,0 +1,134 @@ +# SPDX-License-Identifier: Apache-2.0 +"""Random planner situations for the property tests (hypothesis strategies).""" + +from __future__ import annotations + +import math +from collections.abc import Callable +from dataclasses import replace +from datetime import datetime, timedelta + +from hypothesis import strategies as st + +from suncore.core.battery import BatteryStrategy, GridChargePolicy, RiskLevel +from suncore.core.config import BatteryTarget, GoalsConfig +from suncore.core.tariff import WeeklySchedule +from suncore.sim.planner_scenarios import ( + SUMMER, + TZ, + WINTER, + Situation, + climate, + tibber_price, +) + +PriceFn = Callable[[datetime], float | None] + + +def _hour(at: datetime) -> float: + local = at.astimezone(TZ) + return local.hour + local.minute / 60 + + +def price_pattern(kind: str, level: float) -> tuple[PriceFn, PriceFn]: # noqa: PLR0911 + """Import and export price functions of a named pattern.""" + + def export(_at: datetime) -> float: + return 0.08 + + if kind == "flat": + return (lambda _at: level), export + if kind == "negative": + + def imp(at: datetime) -> float: + return -0.05 if 11 <= _hour(at) < 15 else tibber_price(at) + + def exp(at: datetime) -> float: + return 0.0 if imp(at) < 0 else 0.08 + + return imp, exp + if kind == "spike": + return (lambda at: 1.2 if 18 <= _hour(at) < 19.5 else level), export + if kind == "night_cheap": + return (lambda at: 0.12 if 1 <= _hour(at) < 5 else level), export + if kind == "partial": + + def partial(at: datetime) -> float | None: + start = datetime(2026, 1, 1, tzinfo=TZ) + known = (at - start) % timedelta(days=2) < timedelta(hours=30) + return tibber_price(at) if known else None + + return partial, export + if kind == "negative_export": + return tibber_price, (lambda at: -0.03 if 12 <= _hour(at) < 14 else 0.08) + return tibber_price, export + + +@st.composite +def situations(draw: st.DrawFn) -> Situation: + summer = draw(st.booleans()) + day = SUMMER if summer else WINTER + hour = draw(st.integers(0, 23)) + minute = draw(st.sampled_from([0, 7, 15, 44])) + now = datetime(day.year, day.month, day.day, hour, minute, tzinfo=TZ) + kind = draw( + st.sampled_from( + ["tibber", "flat", "negative", "spike", "night_cheap", "partial", "negative_export"] + ) + ) + level = draw(st.floats(0.15, 0.45)) + imp, exp = price_pattern(kind, level) + policy = draw( + st.sampled_from( + [ + GridChargePolicy(), + GridChargePolicy(enabled=True, max_price=0.2), + GridChargePolicy(enabled=True, schedule=WeeklySchedule.daily("00:00", "06:00")), + GridChargePolicy( + enabled=True, + max_price=0.25, + schedule=WeeklySchedule.daily("22:00", "05:00"), + ), + ] + ) + ) + n_dev = draw(st.integers(0, 2)) + values = [draw(st.one_of(st.none(), st.floats(0.0, 0.5))) for _ in range(n_dev)] + devices = tuple( + climate(f"dev{i}", draw(st.floats(300, 2500)), value) for i, value in enumerate(values) + ) + target = draw( + st.one_of( + st.none(), + st.builds( + BatteryTarget, + soc_pct=st.floats(20, 100), + time=st.sampled_from(["07:00", "12:30", "18:00", "21:45"]), + ), + ) + ) + situation = Situation( + now=now, + kwp=draw(st.floats(0.0, 20.0)), + summer=summer, + day_factors=tuple(draw(st.lists(st.floats(0.05, 1.0), min_size=3, max_size=3))), + cloud=draw(st.sampled_from([None, lambda at: 0.4 + 0.6 * abs(math.sin(_hour(at)))])), + p10_share=draw(st.floats(0.2, 1.0)), + load_base_w=draw(st.floats(100, 1500)), + import_price=imp, + export_price=exp, + capacity_wh=draw(st.floats(2_000, 40_000)), + max_power_w=draw(st.floats(500, 12_000)), + soc_pct=draw(st.floats(0, 100)), + strategy=draw(st.sampled_from(list(BatteryStrategy))), + risk=draw(st.sampled_from(list(RiskLevel))), + grid_charge=policy, + goals=GoalsConfig(battery_target=target), + devices=devices, + export_limit_w=draw(st.one_of(st.none(), st.floats(0, 15_000))), + # Review D2: flat mode (no prices, or spot prices without a formula) is generated too. + with_prices=draw(st.sampled_from([True, True, True, False])), + price_includes=draw(st.sampled_from(["all_in", "all_in", "all_in", "spot_only"])), + import_limit_w=draw(st.one_of(st.none(), st.floats(2_000, 30_000))), + ) + return replace(situation) diff --git a/tests/planner/replay.py b/tests/planner/replay.py new file mode 100644 index 0000000..f369762 --- /dev/null +++ b/tests/planner/replay.py @@ -0,0 +1,117 @@ +# SPDX-License-Identifier: Apache-2.0 +"""A rolling replay of plans against an actual day (test helper, Phase 4 WP8). + +Every ``replan`` the situation is planned again from the live SoC (the forecast itself does not +learn: it stays as optimistic as it was), then the next slots run on the *actual* PV with the +plan's bands interpreted the way the controller and the inverter will (ADR-0013 limits): + +* surplus: the battery takes first while the live SoC is below ``priority_until_soc_pct`` or + ``charge_from_surplus`` is set (devices get what the battery cannot take); otherwise devices + first. A device runs only where its band is ``allowed`` and ``prefer_on``, capped at + ``max_power_w``. +* deficit: the battery covers it down to the reserve unless the band has ``discharge_lock``. +""" + +from __future__ import annotations + +from dataclasses import dataclass, replace +from datetime import datetime, timedelta + +from suncore.core.control import BandPreference +from suncore.planner.run import run +from suncore.sim.planner_scenarios import Situation, forecasts, situation_inputs + +STEP_H = 0.25 + + +@dataclass(frozen=True, slots=True) +class Replay: + soc_pct: dict[datetime, float] + device_wh: float + targets: dict[datetime, float] + """Evening target (%) per replan time.""" + + +def replay( + situation: Situation, + *, + hours: int, + actual_share: float, + replan_slots: int = 4, +) -> Replay: + """Plan and run ``hours`` hours; actual PV = ``actual_share`` x the forecast P50.""" + starts, pv, _load = forecasts(situation) + actual = { + s: v * actual_share for s, v in zip(starts, pv.p50.values, strict=True) if v is not None + } + soc = situation.soc_pct + now = situation.now + end = now + timedelta(hours=hours) + socs: dict[datetime, float] = {} + targets: dict[datetime, float] = {} + device_wh = 0.0 + while now < end: + inputs = situation_inputs(replace(situation, now=now, soc_pct=soc)) + battery = inputs.battery + assert battery is not None + model = battery.model + targets.update({g.at: g.soc_pct for g in inputs.goals if g.kind == "evening_target"}) + plan = run(inputs).plan + devices = {d.device_id: d for d in inputs.devices} + for t in range(min(replan_slots, inputs.n)): + interval = plan.intervals[t] + band = interval.battery + start = inputs.starts[t] + pv_w = actual.get(start, 0.0) + load_w = inputs.load_p50[t] + e = model.soc_to_wh(soc) + net = pv_w - load_w + if net >= 0: + room = max(0.0, battery.max_wh - e) / (STEP_H * model.charge_efficiency) + battery_cap = min(battery.max_charge_w, room) + first = ( + band.priority_until_soc_pct is not None and soc < band.priority_until_soc_pct + ) or band.charge_from_surplus + charge = min(net, battery_cap) if first else 0.0 + rest = net - charge + for device_id, dband in interval.devices.items(): + if not dband.allowed or dband.preference is not BandPreference.PREFER_ON: + continue + cap = ( + devices[device_id].max_w if dband.max_power_w is None else dband.max_power_w + ) + take = min(cap, rest) + rest -= take + device_wh += take * STEP_H + if not first: + charge = min(rest, battery_cap) + e += charge * STEP_H * model.charge_efficiency + elif not band.discharge_lock: + avail = max(0.0, e - battery.reserve_wh) * model.discharge_efficiency / STEP_H + out = min(-net, battery.max_discharge_w, avail) + e -= out * STEP_H / model.discharge_efficiency + soc = model.wh_to_soc(e) + socs[start + inputs.step] = soc + now = inputs.starts[0] + inputs.step * replan_slots + return Replay(socs, device_wh, targets) + + +def battery_first_soc(situation: Situation, *, until: datetime, actual_share: float) -> float: + """SoC (%) at ``until`` if every actual surplus went to the battery and deficits drew on it.""" + starts, pv, load = forecasts(situation) + inputs = situation_inputs(situation) + battery = inputs.battery + assert battery is not None + model = battery.model + e = battery.soc_wh + for start, pv_w, load_w in zip(starts, pv.p50.values, load.p50.values, strict=True): + if start >= until: + break + net = (pv_w or 0.0) * actual_share - (load_w or 0.0) + if net > 0: + gain = min(net, battery.max_charge_w) * STEP_H * model.charge_efficiency + e = min(battery.max_wh, e + gain) + else: + loss = min(-net, battery.max_discharge_w) * STEP_H / model.discharge_efficiency + e = max(min(e, battery.reserve_wh), e - loss) + return model.wh_to_soc(e) diff --git a/tests/planner/test_bench.py b/tests/planner/test_bench.py new file mode 100644 index 0000000..d922e2d --- /dev/null +++ b/tests/planner/test_bench.py @@ -0,0 +1,31 @@ +# SPDX-License-Identifier: Apache-2.0 +"""Solve-time budget of the reference house (risk R3; ``scripts/bench_planner.py``). + +ADR-0003 budget: 8 s on the target hardware, < 10 s on a Raspberry Pi 4 (BRIEF §2). CI's x86 +runner must stay far below that: < 3 s for the whole run (inputs, heuristic, LP, plan). +""" + +from __future__ import annotations + +import importlib.util +from pathlib import Path + +import pytest + +SCRIPT = Path(__file__).resolve().parents[2] / "scripts" / "bench_planner.py" +CI_BUDGET_S = 3.0 + + +@pytest.mark.slow +def test_reference_house_plans_within_the_ci_budget() -> None: + spec = importlib.util.spec_from_file_location("bench_planner", SCRIPT) + assert spec is not None + assert spec.loader is not None + module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(module) + result = module.bench(3) + assert result["source"] == "solver" + assert result["status"] == "optimal" + assert result["binaries"] == 0 + assert result["plan_total_s"] < CI_BUDGET_S + assert result["build_inputs_s"] + result["plan_total_s"] < CI_BUDGET_S diff --git a/tests/planner/test_explain.py b/tests/planner/test_explain.py new file mode 100644 index 0000000..370f5e7 --- /dev/null +++ b/tests/planner/test_explain.py @@ -0,0 +1,47 @@ +# SPDX-License-Identifier: Apache-2.0 +"""Band derivation details (PR 4-F review): hysteresis of ``tight`` against the previous plan.""" + +from __future__ import annotations + +from dataclasses import replace + +from suncore.core.control import DeviceBand, Plan, PlanInterval +from suncore.planner.explain import TIGHT_HOLD_PCT, TIGHT_PCT, slot_facts +from suncore.planner.model import economics +from suncore.planner.run import run +from suncore.sim.planner_scenarios import scenario_inputs + + +def test_a_slot_the_previous_plan_throttled_stays_tight_within_the_hold_margin() -> None: + inputs = scenario_inputs("sunny_day") + result = run(inputs) + econ = economics(inputs) + assert inputs.battery is not None + k = next(i for i, g in enumerate(inputs.goals) if g.kind == "evening_target") + slot = econ.goal_slots[k] + assert slot is not None + planned = inputs.battery.model.wh_to_soc(result.schedule.soc_wh[slot]) + # A target 2 % below the plan: not binding by the strict rule, binding with hysteresis. + margin = (TIGHT_PCT + TIGHT_HOLD_PCT) / 2 + goals = list(inputs.goals) + goals[k] = replace(goals[k], soc_pct=planned - margin) + probe = replace(inputs, goals=tuple(goals)) + charging = [t for t in range(slot) if result.schedule.pv_charge_w[t] > 1.0] + assert charging + fresh = slot_facts(probe, economics(probe), result.schedule) + assert not any(fresh[t].tight for t in charging) + t = charging[0] + start = inputs.starts[t] + previous = Plan( + intervals=( + PlanInterval( + start=start, + end=start + inputs.step, + devices={"ac_living": DeviceBand(allowed=False, max_power_w=0.0)}, + ), + ) + ) + sticky = replace(probe, previous=previous) + held = slot_facts(sticky, economics(sticky), result.schedule) + assert held[t].tight + assert not any(held[x].tight for x in charging if x != t) diff --git a/tests/planner/test_fallback.py b/tests/planner/test_fallback.py new file mode 100644 index 0000000..2fe4e83 --- /dev/null +++ b/tests/planner/test_fallback.py @@ -0,0 +1,190 @@ +# SPDX-License-Identifier: Apache-2.0 +"""The planner's fallback chain (ADR-0003): every solver outcome ends in a usable plan.""" + +from __future__ import annotations + +from dataclasses import dataclass + +import numpy as np +import pytest + +from suncore.planner import reasons as rk +from suncore.planner.inputs import PlannerInputs +from suncore.planner.model import ( + FloatArray, + HighsBackend, + LinearProblem, + SolverResult, + build_problem, + economics, + objective, + violations, +) +from suncore.planner.run import plan, run +from suncore.sim.planner_scenarios import scenario_inputs + + +@dataclass +class FakeBackend: + """Returns a fixed outcome; records what it was asked.""" + + status: str + x: str = "none" + raise_exc: BaseException | None = None + name: str = "fake" + calls: int = 0 + time_limit_s: float = 0.0 + warm: FloatArray | None = None + + def solve( + self, + problem: LinearProblem, + *, + time_limit_s: float, + mip_gap: float, # noqa: ARG002 + warm_start: FloatArray | None = None, + ) -> SolverResult: + self.calls += 1 + self.time_limit_s = time_limit_s + self.warm = warm_start + if self.raise_exc is not None: + raise self.raise_exc + x = None + if self.x == "zeros": + x = np.zeros(problem.n_cols) + elif self.x == "warm": + x = warm_start + elif self.x == "optimal": + x = HighsBackend().solve(problem, time_limit_s=5, mip_gap=0.0).x + return SolverResult(self.status, x, None, 0.01) # type: ignore[arg-type] + + +@pytest.fixture(scope="module") +def inputs() -> PlannerInputs: + return scenario_inputs("two_poor_days") + + +def _first(result_plan_reasons: tuple[object, ...]) -> str: + return result_plan_reasons[0].key # type: ignore[attr-defined] + + +@pytest.mark.parametrize( + ("backend", "key"), + [ + (FakeBackend("time_limit"), rk.FALLBACK_TIMEOUT), + (FakeBackend("infeasible"), rk.FALLBACK_INFEASIBLE), + (FakeBackend("error"), rk.FALLBACK_ERROR), + (FakeBackend("optimal", raise_exc=RuntimeError("boom")), rk.FALLBACK_ERROR), + (FakeBackend("optimal", raise_exc=ImportError("highspy")), rk.FALLBACK_SOLVER_UNAVAILABLE), + (FakeBackend("optimal", x="zeros"), rk.FALLBACK_INVALID_SOLUTION), + ], +) +def test_every_failure_falls_back_to_the_heuristic( + inputs: PlannerInputs, backend: FakeBackend, key: str +) -> None: + result = run(inputs, backend=backend) + assert result.source == "heuristic" + assert result.plan.source == "heuristic" + assert _first(result.plan.reasons) == key + assert result.plan.reasons[1].key == rk.HEURISTIC_RULES + assert result.plan.stats is not None + assert result.plan.stats.status == "heuristic" + assert violations(inputs, result.schedule) == [] + assert len(result.plan.intervals) == inputs.n + assert all(i.reasons for i in result.plan.intervals) + + +def test_a_feasible_incumbent_on_timeout_is_used(inputs: PlannerInputs) -> None: + result = run(inputs, backend=FakeBackend("time_limit", x="optimal")) + assert result.source == "solver" + assert _first(result.plan.reasons) == rk.SOLVER_INCUMBENT + + +def test_an_incumbent_costlier_than_the_heuristic_is_replaced(inputs: PlannerInputs) -> None: + # The warm start (previous plan or heuristic, repaired) is feasible but not optimal; when + # it is costlier than the heuristic itself the heuristic wins. + econ = economics(inputs) + result = run(inputs, backend=FakeBackend("time_limit", x="warm")) + assert result.objective <= result.heuristic_objective + 1e-9 + assert result.source in ("solver", "heuristic") + if result.source == "heuristic": + assert _first(result.plan.reasons) == rk.FALLBACK_HEURISTIC_BETTER + assert objective(inputs, result.schedule, econ) == pytest.approx(result.objective) + + +def test_the_time_budget_reaches_the_solver(inputs: PlannerInputs) -> None: + backend = FakeBackend("optimal", x="optimal") + run(inputs, budget_s=2.5, backend=backend) + assert 0 < backend.time_limit_s <= 2.5 + + +def test_a_real_timeout_without_a_solution_falls_back() -> None: + inputs = scenario_inputs("reference_house") + result = run(inputs, budget_s=0.0) + # 0 s budget = the minimum solver time; whatever HiGHS achieves, the plan is valid. + assert result.source in ("solver", "heuristic") + assert violations(inputs, result.schedule) == [] + + +def test_plan_returns_the_plan(inputs: PlannerInputs) -> None: + built = plan(inputs, backend=FakeBackend("infeasible")) + assert built.source == "heuristic" + + +def test_highs_reports_an_infeasible_model() -> None: + problem = LinearProblem( + cost=np.array([1.0]), + col_lower=np.array([0.0]), + col_upper=np.array([1.0]), + row_lower=np.array([2.0]), + row_upper=np.array([np.inf]), + a_start=np.array([0, 1], dtype=np.int64), + a_index=np.array([0], dtype=np.int64), + a_value=np.array([1.0]), + ) + result = HighsBackend().solve(problem, time_limit_s=1, mip_gap=0.01) + assert result.status == "infeasible" + assert result.x is None + + +def test_highs_solves_integer_columns() -> None: + problem = LinearProblem( + cost=np.array([-1.0, -1.0]), + col_lower=np.array([0.0, 0.0]), + col_upper=np.array([10.0, 10.0]), + row_lower=np.array([-np.inf]), + row_upper=np.array([3.5]), + a_start=np.array([0, 2], dtype=np.int64), + a_index=np.array([0, 1], dtype=np.int64), + a_value=np.array([1.0, 1.0]), + integrality=(0, 1), + ) + result = HighsBackend().solve(problem, time_limit_s=1, mip_gap=0.0) + assert result.status == "optimal" + assert result.x is not None + assert sum(result.x) == pytest.approx(3.0) + assert result.mip_gap is not None + + +def test_the_highs_backend_is_available() -> None: + assert HighsBackend.available() + + +def test_the_warm_start_is_feasible_and_reaches_the_solver(inputs: PlannerInputs) -> None: + backend = FakeBackend("optimal", x="optimal") + first = run(inputs) + run(inputs, backend=backend, warm_start=first.plan) + assert backend.warm is not None + problem, _ = build_problem(inputs, economics(inputs)) + assert len(backend.warm) == problem.n_cols + assert np.all(backend.warm >= problem.col_lower - 1e-9) + assert np.all(backend.warm <= problem.col_upper + 1e-9) + + +def test_a_warm_start_from_the_previous_plan_keeps_the_optimum(inputs: PlannerInputs) -> None: + cold = run(inputs) + warm = run(inputs, warm_start=cold.plan) + assert warm.objective == pytest.approx(cold.objective, rel=1e-6, abs=1e-6) + assert cold.solver is not None + assert warm.solver is not None + assert warm.solver.iterations <= cold.solver.iterations diff --git a/tests/planner/test_gil.py b/tests/planner/test_gil.py new file mode 100644 index 0000000..1693a56 --- /dev/null +++ b/tests/planner/test_gil.py @@ -0,0 +1,66 @@ +# SPDX-License-Identifier: Apache-2.0 +"""HiGHS releases the GIL while it solves (control-safety review m5). + +The runtime (WP9) solves in a daemon thread; if ``Highs.run()`` kept the GIL, the event loop +(controller ticks every 5 s, the websocket) would stall for the whole solve. highspy's own +``Highs.solve`` runs ``run()`` in a thread and polls it from the main thread with timeouts, +which only works with the GIL released; this test measures it with an LP that takes long +enough to notice: the event loop's largest gap must stay far below the solve time. +``UNVERIFIED`` on aarch64 (same wheel build, not run on a Pi). +""" + +from __future__ import annotations + +import asyncio +import time + +import numpy as np +import pytest + +from suncore.planner.model import HighsBackend, LinearProblem + + +def _large_lp(n: int, m: int) -> LinearProblem: + rng = np.random.default_rng(0) + starts, index, value = [0], [], [] + dense = rng.random((m, n)) * (rng.random((m, n)) < 0.05) + for row in dense: + nz = np.nonzero(row)[0] + index.extend(nz.tolist()) + value.extend(row[nz].tolist()) + starts.append(len(index)) + return LinearProblem( + cost=-rng.random(n), + col_lower=np.zeros(n), + col_upper=np.ones(n), + row_lower=np.full(m, -np.inf), + row_upper=dense.sum(axis=1) * 0.3, + a_start=np.array(starts, dtype=np.int64), + a_index=np.array(index, dtype=np.int64), + a_value=np.array(value, dtype=np.float64), + ) + + +@pytest.mark.slow +async def test_the_event_loop_keeps_ticking_while_highs_solves() -> None: + problem = _large_lp(1500, 750) + gaps: list[float] = [] + done = asyncio.Event() + + async def ticker() -> None: + last = time.perf_counter() + while not done.is_set(): + await asyncio.sleep(0.01) + now = time.perf_counter() + gaps.append(now - last) + last = now + + task = asyncio.create_task(ticker()) + began = time.perf_counter() + result = await asyncio.to_thread(HighsBackend().solve, problem, time_limit_s=30, mip_gap=0.0) + solve_s = time.perf_counter() - began + done.set() + await task + assert result.status in ("optimal", "time_limit") + assert solve_s > 0.3, "the LP must take long enough to measure the loop" + assert max(gaps) < min(0.25, solve_s / 2) diff --git a/tests/planner/test_inputs.py b/tests/planner/test_inputs.py new file mode 100644 index 0000000..98f3026 --- /dev/null +++ b/tests/planner/test_inputs.py @@ -0,0 +1,461 @@ +# SPDX-License-Identifier: Apache-2.0 +"""PlannerInputs: the pure builder from the services' outputs (Phase 4 WP8).""" + +from __future__ import annotations + +from dataclasses import dataclass, replace +from datetime import UTC, datetime, time, timedelta + +import pytest + +from suncore.core.battery import ( + BatteryModel, + BatterySettings, + BatteryStrategy, + GridChargePolicy, +) +from suncore.core.config import BatteryTarget, GoalsConfig +from suncore.core.decisions import Reason +from suncore.core.devices import ( + ContinuousControl, + DeviceConfig, + DeviceKind, + OnOffControl, + PowerModel, + PowerModelKind, + Step, + StepsControl, + TimeWindow, +) +from suncore.core.site import BatteryConfig, EntityRef +from suncore.core.tariff import WeeklySchedule +from suncore.planner import reasons as rk +from suncore.planner.inputs import ( + DEFAULT_BASE_LOAD_W, + PlannerBattery, + PlannerInputs, + PriceMode, + SocGoal, + buffer_goal, + build_inputs, + device_max_power_w, + grid_charge_allowance, + window_allows, +) +from suncore.sim.planner_scenarios import ( + SUMMER, + TZ, + climate, + forecasts, + prices, + situation, +) + +NOW = datetime(SUMMER.year, SUMMER.month, SUMMER.day, 6, 7, tzinfo=TZ) +SETTINGS = BatterySettings( + model=BatteryModel(capacity_wh=10_000, max_charge_w=5_000, max_discharge_w=5_000) +) + + +@pytest.fixture(scope="module") +def series(): # type: ignore[no-untyped-def] + starts, pv, load = forecasts(replace(situation("sunny_day"), now=NOW)) + return starts, pv, load + + +def _build(series, **kw): # type: ignore[no-untyped-def] + starts, pv, load = series + args = { + "tz": TZ, + "load": load, + "pv": pv, + "prices": prices(starts, [0.3] * len(starts), [0.08] * len(starts)), + "battery": SETTINGS, + "soc_pct": 40.0, + } + args.update(kw) + return build_inputs(NOW, **args) + + +def test_the_grid_starts_at_the_quarter_hour_and_covers_48_hours(series) -> None: # type: ignore[no-untyped-def] + inputs = _build(series) + assert inputs.starts[0] == datetime(2026, 6, 20, 4, 0, tzinfo=UTC) + assert inputs.end >= NOW + timedelta(hours=48) + assert inputs.n == 193 + assert inputs.price_mode is PriceMode.MARKET + assert inputs.assumptions["price_mode"] == "market" + assert inputs.reasons == () + + +def test_missing_prices_are_filled_with_the_median_and_reported(series) -> None: # type: ignore[no-untyped-def] + starts = series[0] + half = len(starts) // 2 + values = [0.2 if i % 2 else 0.4 for i in range(half)] + [None] * (len(starts) - half) + inputs = _build(series, prices=prices(starts, values, [0.08] * len(starts))) + assert inputs.price_mode is PriceMode.MARKET + assert inputs.import_price[-1] == pytest.approx(0.3) + assert inputs.import_known[-1] is None + assert inputs.reasons[0].key == rk.INPUT_PRICES_PARTIAL + assert inputs.reasons[0].args["filled_slots"] == inputs.assumptions["prices_filled_slots"] + assert inputs.assumptions["prices_filled_slots"] > 0 + + +def test_spot_only_prices_are_refused(series) -> None: # type: ignore[no-untyped-def] + starts = series[0] + spot = prices(starts, [0.1] * len(starts), [0.08] * len(starts), includes="spot_only") + inputs = _build(series, prices=spot) + assert inputs.price_mode is PriceMode.FLAT + assert set(inputs.import_price) == {1.0} + assert inputs.reasons[0] == Reason( + key=rk.FALLBACK_SPOT_WITHOUT_FORMULA, args={"source": "sim.tibber"} + ) + + +def test_unknown_prices_everywhere_mean_flat_mode(series) -> None: # type: ignore[no-untyped-def] + starts = series[0] + inputs = _build(series, prices=prices(starts, [None] * len(starts), [None] * len(starts))) + assert inputs.price_mode is PriceMode.FLAT + assert inputs.reasons[0].key == rk.FALLBACK_NO_PRICES + assert set(inputs.export_price) == {0.0} + + +def test_missing_forecasts_are_explicit(series) -> None: # type: ignore[no-untyped-def] + inputs = _build(series, pv=None, load=None, prices=None) + keys = {r.key for r in inputs.reasons} + assert keys == {rk.FALLBACK_NO_PRICES, rk.INPUT_NO_PV_FORECAST, rk.INPUT_NO_LOAD_FORECAST} + assert set(inputs.pv_p50) == {0.0} + + +def test_without_soc_or_model_the_battery_is_left_out(series) -> None: # type: ignore[no-untyped-def] + inputs = _build(series, soc_pct=None) + assert inputs.battery is None + assert rk.INPUT_NO_BATTERY_SOC in {r.key for r in inputs.reasons} + assert _build(series, battery=BatterySettings()).battery is None + + +def test_the_site_battery_narrows_the_model(series) -> None: # type: ignore[no-untyped-def] + site = BatteryConfig( + power=EntityRef(entity_id="sensor.bat_power"), + soc=EntityRef(entity_id="sensor.bat_soc"), + min_soc_pct=25.0, + max_soc_pct=90.0, + max_charge_w=3_000, + ) + battery = _build(series, site_battery=site).battery + assert battery is not None + assert battery.reserve_pct == 25.0 + assert battery.max_soc_pct == 90.0 + assert battery.max_charge_w == 3_000 + assert battery.max_discharge_w == 5_000 + + +def test_the_user_target_is_a_timed_goal_on_every_day(series) -> None: # type: ignore[no-untyped-def] + goals = GoalsConfig(battery_target=BatteryTarget(soc_pct=80, time="18:00")) + inputs = _build(series, goals=goals) + user = [g for g in inputs.goals if g.kind == "user_target"] + assert [g.at.astimezone(TZ).time() for g in user] == [time(18, 0), time(18, 0)] + assert {g.at.astimezone(TZ).day for g in user} == {20, 21} + assert all(g.reason.key == rk.USER_TARGET for g in user) + + +def test_risk_targets_become_goals(series) -> None: # type: ignore[no-untyped-def] + @dataclass_like + class Target: + soc_pct: float + reason: Reason + + evening = Target(60.0, Reason(key=rk.EVENING_TARGET, args={"soc_pct": 60.0})) + buffer = Target(50.0, Reason(key=rk.MORNING_BUFFER, args={"soc_pct": 50.0})) + at = datetime(2026, 6, 20, 21, 0, tzinfo=TZ) + inputs = _build(series, evening_target=evening, morning_buffer=buffer, evening_at=at) + kinds = {g.kind: g for g in inputs.goals} + assert kinds["evening_target"].at == at + assert kinds["evening_target"].soc_pct == 60.0 + assert kinds["morning_buffer"].soc_pct == 50.0 + assert kinds["morning_buffer"].at < at + assert inputs.morning_buffer_pct == 50.0 + # An evening that has passed is no goal. + late = _build(series, evening_target=evening, evening_at=NOW - timedelta(hours=1)) + assert not [g for g in late.goals if g.kind == "evening_target"] + + +def dataclass_like(cls): # type: ignore[no-untyped-def] + from dataclasses import dataclass # noqa: PLC0415 + + return dataclass(frozen=True)(cls) + + +def test_prefer_full_without_a_buffer_goes_battery_first_to_max(series) -> None: # type: ignore[no-untyped-def] + settings = SETTINGS.model_copy(update={"strategy": BatteryStrategy.PREFER_FULL}) + inputs = _build(series, battery=settings) + goal = next(g for g in inputs.goals if g.kind == "prefer_full") + assert goal.soc_pct == 100.0 + assert goal.reason.key == rk.PREFER_FULL + + +def test_the_buffer_goal_is_the_reachable_soc() -> None: + model = BatteryModel(capacity_wh=10_000, max_charge_w=5_000, max_discharge_w=5_000) + battery = PlannerBattery(model, 20.0, 15.0, 100.0, 5_000, 5_000) + start = datetime(2026, 6, 20, 6, 0, tzinfo=UTC) + starts = [start + timedelta(minutes=15 * i) for i in range(8)] + step = timedelta(minutes=15) + reach = buffer_goal( + battery, + 30.0, + starts=starts, + step=step, + pv=[2_000.0] * 8, + load=[0.0] * 8, + until=starts[-1] + step, + ) + assert reach is not None + assert reach[1] == 30.0 + # 2 kW * 0.25 h * 0.95 = 475 Wh per slot: 1000 Wh need three slots. + assert reach[0] == starts[2] + step + weak = buffer_goal( + battery, + 90.0, + starts=starts, + step=step, + pv=[1_000.0] * 8, + load=[0.0] * 8, + until=starts[-1] + step, + ) + assert weak is not None + assert weak[0] == starts[-1] + step + assert weak[1] == pytest.approx(20 + 8 * 2.375) + assert ( + buffer_goal( + battery, 10.0, starts=starts, step=step, pv=[0.0] * 8, load=[0.0] * 8, until=starts[-1] + ) + is None + ) + assert ( + buffer_goal( + battery, + 50.0, + starts=starts, + step=step, + pv=[0.0] * 8, + load=[500.0] * 8, + until=starts[-1], + ) + is None + ) + + +def test_grid_charge_allowance_follows_policy_spread_and_import_limit() -> None: + model = BatteryModel(capacity_wh=10_000, max_charge_w=5_000, max_discharge_w=5_000) + battery = PlannerBattery(model, 20.0, 15.0, 100.0, 5_000, 5_000) + start = datetime(2026, 12, 8, 0, 0, tzinfo=TZ) + starts = [start + timedelta(hours=i) for i in range(8)] + known: list[float | None] = [0.15, 0.15, None, 0.15, 0.35, 0.35, 0.18, 0.35] + policy = GridChargePolicy( + enabled=True, max_price=0.2, schedule=WeeklySchedule.daily("00:00", "06:00") + ) + allowed = grid_charge_allowance( + starts, + known, + load_w=[300.0] * 8, + battery=battery, + policy=policy, + tz=TZ, + import_limit_w=4_000, + ) + assert allowed == [3_700.0, 3_700.0, 0.0, 3_700.0, 0.0, 0.0, 0.0, 0.0] + off = grid_charge_allowance( + starts, + known, + load_w=[300.0] * 8, + battery=battery, + policy=GridChargePolicy(), + tz=TZ, + import_limit_w=None, + ) + assert off == [0.0] * 8 + # A flat tariff has no spread rule: the policy alone decides. + flat = grid_charge_allowance( + starts, + [0.3] * 8, + load_w=[0.0] * 8, + battery=battery, + policy=GridChargePolicy(enabled=True, schedule=WeeklySchedule.daily("00:00", "02:00")), + tz=TZ, + import_limit_w=None, + ) + assert flat == [5_000.0, 5_000.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0] + + +def _device(control, nominal=None, windows=()): # type: ignore[no-untyped-def] + return DeviceConfig( + id="d", + template_id="generic.x", + name="d", + kind=next(iter(DeviceKind)), + entities={"sw": EntityRef(entity_id="number.d")}, + power_model=PowerModel(kind=PowerModelKind.NOMINAL, nominal_w=nominal) + if nominal + else PowerModel(kind=PowerModelKind.MEASURED, power_role="sw"), + control=control, + windows=windows, + ) + + +def test_device_max_power_from_the_control() -> None: + steps = StepsControl( + kind="steps", role="sw", steps=(Step(value=0, power_w=0), Step(value=1, power_w=900)) + ) + assert device_max_power_w(_device(steps)) == 900 + amps = ContinuousControl(kind="continuous", role="sw", unit="A", min=6, max=16, phases=3) + assert device_max_power_w(_device(amps)) == pytest.approx(16 * 230 * 3) + watts = ContinuousControl(kind="continuous", role="sw", unit="W", min=100, max=2000) + assert device_max_power_w(_device(watts)) == 2000 + pct = ContinuousControl(kind="continuous", role="sw", unit="%", min=0, max=100) + assert device_max_power_w(_device(pct, nominal=1800.0)) == 1800.0 + assert device_max_power_w(_device(OnOffControl(kind="on_off", role="sw"))) is None + assert device_max_power_w(climate("ac", 700.0)) == 700.0 + + +def test_devices_with_unknown_power_are_left_out_with_a_reason(series) -> None: # type: ignore[no-untyped-def] + switch = _device(OnOffControl(kind="on_off", role="sw")) + inputs = _build(series, devices=[switch]) + assert inputs.devices == () + assert inputs.reasons[-1].key == rk.INPUT_DEVICE_POWER_UNKNOWN + known = _build(series, devices=[switch], device_max_w={"d": 1500.0}) + assert known.devices[0].max_w == 1500.0 + + +def test_device_windows_block_slots(series) -> None: # type: ignore[no-untyped-def] + window = TimeWindow(start=time(10, 0), end=time(14, 0)) + quiet = TimeWindow(start=time(12, 0), end=time(13, 0), mode="block") + device = climate("ac", 800.0).model_copy(update={"windows": (window, quiet)}) + inputs = _build(series, devices=[device]) + allowed = { + s.astimezone(TZ).hour + for s, ok in zip(inputs.starts, inputs.devices[0].allowed, strict=True) + if ok + } + assert allowed == {10, 11, 13} + assert window_allows((), NOW) + + +def test_overnight_windows() -> None: + night = TimeWindow(start=time(22, 0), end=time(6, 0), days=(0,)) + monday_late = datetime(2026, 10, 19, 23, 0, tzinfo=TZ) + tuesday_early = datetime(2026, 10, 20, 5, 0, tzinfo=TZ) + tuesday_late = datetime(2026, 10, 20, 23, 0, tzinfo=TZ) + assert window_allows((night,), monday_late) + assert window_allows((night,), tuesday_early) + assert not window_allows((night,), tuesday_late) + + +def test_inputs_are_validated() -> None: + start = datetime(2026, 6, 20, 4, 0, tzinfo=UTC) + base = { + "now": start, + "starts": (start,), + "step": timedelta(minutes=15), + "tz": TZ, + "import_price": (0.3,), + "export_price": (0.08,), + "import_known": (0.3,), + "price_mode": PriceMode.MARKET, + "pv_p10": (0.0,), + "pv_p50": (0.0,), + "pv_p90": (0.0,), + "load_p10": (0.0,), + "load_p50": (0.0,), + "load_p90": (0.0,), + } + inputs = PlannerInputs(**base) # type: ignore[arg-type] + assert inputs.slot_of(start) is None + assert inputs.slot_of(start + timedelta(minutes=10)) == 0 + assert inputs.slot_of(start + timedelta(hours=1)) is None + assert inputs.grid_charge_at(0) == 0.0 + with pytest.raises(ValueError, match="one value per slot"): + PlannerInputs(**{**base, "pv_p50": (0.0, 1.0)}) # type: ignore[arg-type] + with pytest.raises(ValueError, match="finite"): + PlannerInputs(**{**base, "pv_p50": (float("nan"),)}) # type: ignore[arg-type] + with pytest.raises(ValueError, match="empty"): + PlannerInputs(**{**base, "starts": ()}) # type: ignore[arg-type] + with pytest.raises(ValueError, match="grid_charge_w"): + PlannerInputs(**{**base, "grid_charge_w": (1.0, 2.0)}) # type: ignore[arg-type] + + +def test_no_grid_charging_without_a_known_price(series) -> None: # type: ignore[no-untyped-def] + """Review D2: flat mode or an unknown price never allows grid charging, not even under a + schedule-only policy.""" + night = GridChargePolicy(enabled=True, schedule=WeeklySchedule.daily("00:00", "23:59")) + settings = SETTINGS.model_copy(update={"grid_charge": night}) + assert not any(_build(series, battery=settings, prices=None).grid_charge_w) + starts = series[0] + spot = prices(starts, [0.1] * len(starts), [0.08] * len(starts), includes="spot_only") + assert not any(_build(series, battery=settings, prices=spot).grid_charge_w) + half = [0.3] * 60 + [None] * (len(starts) - 60) + partial = _build(series, battery=settings, prices=prices(starts, half, [0.08] * len(starts))) + assert all( + w == 0 + for w, k in zip(partial.grid_charge_w, partial.import_known, strict=True) + if k is None + ) + assert any(w > 0 for w in partial.grid_charge_w) + + +def test_negative_rule_slots_discourage_export(series) -> None: # type: ignore[no-untyped-def] + starts = series[0] + imp = [-0.05 if 30 <= i < 40 else 0.3 for i in range(len(starts))] + exp = [0.0 if 30 <= i < 40 else 0.08 for i in range(len(starts))] + inputs = _build(series, prices=prices(starts, imp, exp)) + assert [inputs.discouraged(t) for t in range(28, 42)] == [False] * 2 + [True] * 10 + [False] * 2 + # Export "none" (price 0 everywhere) with positive import prices is not discouraged. + plain = _build(series, prices=prices(starts, [0.3] * len(starts), [0.0] * len(starts))) + assert not any(plain.export_discouraged) + + +def test_without_a_load_forecast_a_flat_load_and_no_devices(series) -> None: # type: ignore[no-untyped-def] + inputs = _build(series, load=None, devices=[climate("ac", 800.0)]) + assert set(inputs.load_p50) == {DEFAULT_BASE_LOAD_W} + assert inputs.devices == () + reason = next(r for r in inputs.reasons if r.key == rk.INPUT_NO_LOAD_FORECAST) + assert reason.args["load_w"] == DEFAULT_BASE_LOAD_W + recent = _build(series, load=None, load_fallback_w=730.0) + assert set(recent.load_p50) == {730.0} + + +@dataclass(frozen=True) +class _Target: + soc_pct: float + reason: Reason + + +def test_a_full_evening_target_is_due_when_the_evening_deficit_starts(series) -> None: # type: ignore[no-untyped-def] + """Review m2: at 100 % the target sits before the evening deficit, so a full battery is + never held while the house imports.""" + evening = datetime(2026, 6, 20, 21, 15, tzinfo=TZ) + full = _Target(100.0, Reason(key=rk.EVENING_TARGET, args={"soc_pct": 100.0})) + inputs = _build(series, evening_target=full, evening_at=evening) + goal = next(g for g in inputs.goals if g.kind == "evening_target") + assert goal.at < evening + slot = inputs.slot_of(goal.at) + assert slot is not None + assert inputs.load_p50[slot + 1] >= inputs.pv_p50[slot + 1] + assert inputs.load_p50[slot] < inputs.pv_p50[slot] + half = _Target(60.0, Reason(key=rk.EVENING_TARGET, args={"soc_pct": 60.0})) + plain = _build(series, evening_target=half, evening_at=evening) + assert next(g for g in plain.goals if g.kind == "evening_target").at == evening + + +def test_an_unreachable_buffer_names_the_reachable_soc(series) -> None: # type: ignore[no-untyped-def] + pv = series[1] + scaled = tuple(None if v is None else v * 0.2 for v in pv.p50.values) + weak = type(pv).deterministic(pv.p50.model_copy(update={"values": scaled})) + buffer = _Target(90.0, Reason(key=rk.MORNING_BUFFER, args={"soc_pct": 90.0})) + inputs = _build(series, pv=weak, morning_buffer=buffer, soc_pct=20.0) + goal = next(g for g in inputs.goals if g.kind == "morning_buffer") + assert goal.soc_pct < 90.0 + assert goal.reason.args["soc_pct"] == pytest.approx(round(goal.soc_pct, 1)) + + +def test_soc_goal_is_plain_data() -> None: + goal = SocGoal("user_target", 50.0, NOW, Reason(key=rk.USER_TARGET)) + assert goal.kind == "user_target" diff --git a/tests/planner/test_properties.py b/tests/planner/test_properties.py new file mode 100644 index 0000000..39d1daf --- /dev/null +++ b/tests/planner/test_properties.py @@ -0,0 +1,181 @@ +# SPDX-License-Identifier: Apache-2.0 +"""Property tests of the planner (Phase 4 WP8, ADR-0003): random situations, solver and heuristic. + +Every generated situation is planned by the HiGHS LP and by the heuristic; both schedules must +keep the energy balance, the SoC corridor and every bound, never charge from the grid outside +the effective policy, never feed devices from grid or battery, and the LP is never costlier +than the heuristic under the one shared cost function. A missed evening/user target is only +allowed when even an LP that maximises the SoC at that time cannot reach it. +``SUNCORE_PLANNER_EXAMPLES`` raises the number of examples for a local stress run. +""" + +from __future__ import annotations + +import json +import os +from pathlib import Path + +import numpy as np +import pytest +from hypothesis import HealthCheck, given, settings + +from suncore.planner.heuristic import heuristic_schedule +from suncore.planner.inputs import PlannerInputs, PriceMode +from suncore.planner.model import ( + SOC, + HighsBackend, + Schedule, + build_problem, + economics, + goal_shortfall_wh, + objective, + violations, +) +from suncore.planner.run import run +from suncore.sim.planner_scenarios import situation_inputs +from tests.planner.helpers import situations + +LOCALES = Path(__file__).resolve().parents[2] / "frontend" / "src" / "lib" / "i18n" / "locales" +CATALOGUE = json.loads((LOCALES / "en.json").read_text(encoding="utf-8")) +PROPS = settings( + max_examples=int(os.environ.get("SUNCORE_PLANNER_EXAMPLES", "60")), + deadline=None, + suppress_health_check=[HealthCheck.too_slow, HealthCheck.data_too_large], +) +TOL_W = 1.0 +TOL_WH = 50.0 + + +def _common(inputs: PlannerInputs, schedule: Schedule) -> None: + assert violations(inputs, schedule) == [] + econ = economics(inputs) + battery = inputs.battery + policy = inputs.grid_charge_policy + for t in range(inputs.n): + # No import for devices: they only ever draw PV surplus over the base load. + surplus = max(0.0, inputs.pv_p50[t] - inputs.load_p50[t]) + assert schedule.device_total_w(t) <= surplus + TOL_W + # Grid charging only inside the effective policy (price level, schedule) and limits. + if schedule.grid_charge_w[t] > TOL_W: + assert inputs.price_mode is PriceMode.MARKET + assert policy.allows(inputs.starts[t], inputs.import_known[t], inputs.tz) + if inputs.import_limit_w is not None: + cap = max(inputs.import_limit_w, inputs.load_p50[t]) + assert schedule.import_w(t) <= cap + TOL_W + # A negative export price is never paid when curtailing is possible, and where the + # region rule zeroed the export price nothing is exported either (review D3). + if inputs.export_price[t] < 0 or inputs.discouraged(t): + assert schedule.export_w[t] <= TOL_W + # Review D2: no grid charging without a known price (flat mode included). + if inputs.import_known[t] is None: + assert schedule.grid_charge_w[t] <= TOL_W + if battery is not None: + low = min(battery.reserve_wh, battery.soc_wh) - TOL_WH + high = max(battery.max_wh, battery.soc_wh) + TOL_WH + assert low <= schedule.soc_wh[t] <= high + assert len(econ.goal_slots) == len(inputs.goals) + + +@PROPS +@given(situations()) +def test_solver_plan_keeps_every_rule(situation) -> None: # type: ignore[no-untyped-def] + inputs = situation_inputs(situation) + result = run(inputs) + assert result.source == "solver" + _common(inputs, result.schedule) + assert result.objective <= result.heuristic_objective + 1e-6 * max( + 1.0, abs(result.heuristic_objective) + ) + plan = result.plan + assert len(plan.intervals) == inputs.n + for t, interval in enumerate(plan.intervals): + assert interval.reasons, "every interval explains itself" + assert all(r.key in CATALOGUE for r in interval.reasons) + band = interval.battery + if band.grid_charge_max_w is not None: + assert inputs.grid_charge_at(t) > 0 + if interval.expected is not None: + e = interval.expected + left = e.pv_p50_w + e.import_w + max(-e.battery_w, 0.0) + right = e.load_w + e.devices_w + max(e.battery_w, 0.0) + e.export_w + e.curtail_w + assert abs(left - right) <= 2.0 + assert all(r.key in CATALOGUE for r in plan.reasons) + _no_export_while_a_device_could_use_it(inputs, result.schedule) + + +def _no_export_while_a_device_could_use_it(inputs: PlannerInputs, schedule: Schedule) -> None: + """Review D4: no export in a slot where an allowed device worth more than the export price + has headroom while no target binds (its device budget is not used up).""" + econ = economics(inputs) + for t in range(inputs.n): + if schedule.export_w[t] <= TOL_W: + continue + budget_left = min( + ( + b - sum(schedule.device_total_w(x) for x in range(s + 1)) * inputs.dt_h + for s, b in econ.device_budget + if s >= t + ), + default=float("inf"), + ) + if budget_left <= 1.0: + continue + for j, device in enumerate(inputs.devices): + headroom = device.allowed[t] and schedule.devices_w[j][t] < device.max_w - TOL_W + if headroom and econ.device_value[j][t] > inputs.export_price[t] + 1e-9: + pytest.fail(f"export at {t} while device {device.device_id} could take it") + + +@PROPS +@given(situations()) +def test_heuristic_keeps_every_rule(situation) -> None: # type: ignore[no-untyped-def] + inputs = situation_inputs(situation) + _common(inputs, heuristic_schedule(inputs)) + + +def _max_soc_wh(inputs: PlannerInputs, slot: int) -> float: + econ = economics(inputs) + problem, layout = build_problem(inputs, econ) + cost = np.zeros_like(problem.cost) + cost[layout.var(slot, SOC)] = -1.0 + probe = type(problem)( + cost=cost, + col_lower=problem.col_lower, + col_upper=problem.col_upper, + row_lower=problem.row_lower, + row_upper=problem.row_upper, + a_start=problem.a_start, + a_index=problem.a_index, + a_value=problem.a_value, + ) + result = HighsBackend().solve(probe, time_limit_s=5, mip_gap=0.0) + assert result.x is not None + return float(result.x[layout.var(slot, SOC)]) * 1000 + + +@PROPS +@given(situations()) +def test_targets_are_met_whenever_feasible(situation) -> None: # type: ignore[no-untyped-def] + inputs = situation_inputs(situation) + result = run(inputs) + econ = economics(inputs) + battery = inputs.battery + assert battery is not None + shortfalls = goal_shortfall_wh(inputs, econ, result.schedule) + for goal, slot, short in zip(inputs.goals, econ.goal_slots, shortfalls, strict=True): + if slot is None or short <= TOL_WH or goal.kind not in ("evening_target", "user_target"): + continue + reachable = _max_soc_wh(inputs, slot) + assert reachable < battery.model.soc_to_wh(goal.soc_pct) + TOL_WH + + +@PROPS +@given(situations()) +def test_objective_is_the_lp_value(situation) -> None: # type: ignore[no-untyped-def] + inputs = situation_inputs(situation) + result = run(inputs) + assert result.solver is not None + assert result.solver.objective is not None + assert abs(objective(inputs, result.schedule) - result.solver.objective) <= 1e-4 * max( + 1.0, abs(result.solver.objective) + ) diff --git a/tests/planner/test_scenarios.py b/tests/planner/test_scenarios.py new file mode 100644 index 0000000..408068a --- /dev/null +++ b/tests/planner/test_scenarios.py @@ -0,0 +1,358 @@ +# SPDX-License-Identifier: Apache-2.0 +"""Planner scenarios of the virtual house (Phase 4 WP8): what each situation must produce.""" + +from __future__ import annotations + +from dataclasses import replace +from datetime import timedelta + +import pytest + +from suncore.core.battery import BatteryStrategy, RiskLevel +from suncore.core.control import BandPreference +from suncore.planner import reasons as rk +from suncore.planner.heuristic import heuristic_schedule +from suncore.planner.inputs import PriceMode +from suncore.planner.model import economics, goal_shortfall_wh, violations +from suncore.planner.run import PlannerRun, run +from suncore.sim.planner_scenarios import ( + SCENARIOS, + TZ, + scenario_inputs, + situation, + situation_inputs, +) +from tests.planner.replay import battery_first_soc, replay + +EPS = 1.0 + + +def _keys(result: PlannerRun, t: int) -> set[str]: + return {r.key for r in result.plan.intervals[t].reasons} + + +def _hour(result: PlannerRun, t: int) -> float: + local = result.plan.intervals[t].start.astimezone(TZ) + return local.hour + local.minute / 60 + + +@pytest.mark.parametrize("name", SCENARIOS) +def test_every_scenario_is_solved_feasibly_and_beats_the_heuristic(name: str) -> None: + inputs = scenario_inputs(name) + result = run(inputs) + assert result.source == "solver" + assert result.plan.stats is not None + assert result.plan.stats.status == "optimal" + assert result.plan.stats.n_binaries == 0 + assert violations(inputs, result.schedule) == [] + assert violations(inputs, heuristic_schedule(inputs)) == [] + assert result.objective <= result.heuristic_objective + 1e-9 + assert all(interval.reasons for interval in result.plan.intervals) + assert result.plan.reasons[0].key == rk.SOLVER_OPTIMAL + + +def test_sunny_day_meets_the_evening_target_and_runs_devices_on_surplus() -> None: + inputs = scenario_inputs("sunny_day") + result = run(inputs) + econ = economics(inputs) + assert [g.kind for g in inputs.goals] == ["evening_target"] + assert goal_shortfall_wh(inputs, econ, result.schedule) == [0.0] + device_wh = sum(sum(d) for d in result.schedule.devices_w) * inputs.dt_h + assert device_wh > 5_000 + assert not any(result.schedule.grid_charge_w) + assert any(rk.DEVICE_SURPLUS in _keys(result, t) for t in range(inputs.n)) + # The evening target's own reason is shown at its slot. + slot = econ.goal_slots[0] + assert slot is not None + assert rk.EVENING_TARGET in _keys(result, slot) + + +def test_mixed_clouds_keeps_the_target() -> None: + inputs = scenario_inputs("mixed_clouds") + result = run(inputs) + assert goal_shortfall_wh(inputs, economics(inputs), result.schedule) == [0.0] + + +def test_two_poor_days_raise_the_evening_target_to_max_and_hold_the_battery() -> None: + inputs = scenario_inputs("two_poor_days") + result = run(inputs) + evening = next(g for g in inputs.goals if g.kind == "evening_target") + assert inputs.battery is not None + assert evening.soc_pct == pytest.approx(inputs.battery.max_soc_pct) + assert evening.reason.args["cause"] in ("next_day_deficit", "max_soc") + econ = economics(inputs) + slot = econ.goal_slots[inputs.goals.index(evening)] + assert slot is not None + assert result.schedule.soc_wh[slot] >= inputs.battery.max_wh - 50 + # Before the evening the plan holds the battery (discharge lock) and keeps devices off. + locks = [t for t in range(slot + 1) if result.plan.intervals[t].battery.discharge_lock] + assert locks + assert all(rk.HOLD_FOR_EVENING in _keys(result, t) for t in locks) + assert all(result.plan.intervals[t].battery.min_power_w == 0.0 for t in locks) + assert sum(sum(d[: slot + 1]) for d in result.schedule.devices_w) == pytest.approx(0.0) + throttled = [ + t + for t in range(slot + 1) + if any(not band.allowed for band in result.plan.intervals[t].devices.values()) + ] + assert throttled + assert all(rk.DEVICE_THROTTLED in _keys(result, t) for t in throttled) + + +def test_forecast_too_optimistic_still_reaches_the_evening_target() -> None: + """PV comes in at half the forecast's P50 all day (P10 is a quarter); hourly replanning. + + Review D4 (lead decision, plan §0): caution enters only through the WP7 targets, the device + budget is planned on P50 plus the overflow a battery-first day cannot absorb. At half the + P50 the evening target is still met; a whole day at P10 is the WP7 morning buffer's job + (``docs/plans/phase-4.md`` deviations: with PV at 0.4 x P50 all day the target is missed by + ~5 %, because the buffer's margin does not count the consumers). + """ + s = situation("forecast_too_optimistic") + share = 0.5 + result = replay(s, hours=16, actual_share=share) + evening = min(result.targets) + target = result.targets[evening] + best = battery_first_soc(s, until=evening, actual_share=share) + assert result.soc_pct[evening] >= min(target, best) - 1.0 + + +def test_a_cautious_risk_level_spends_less_on_devices_than_a_bold_one() -> None: + s = situation("forecast_too_optimistic") + cautious = run(situation_inputs(s)).schedule + bold = run(situation_inputs(replace(s, risk=RiskLevel.BOLD))).schedule + assert sum(map(sum, cautious.devices_w)) <= sum(map(sum, bold.devices_w)) + EPS + + +def test_negative_prices_keep_room_in_the_battery_and_avoid_export() -> None: + inputs = scenario_inputs("negative_prices") + result = run(inputs) + negative = [t for t in range(inputs.n) if inputs.import_price[t] < 0] + assert negative + # The battery charges inside the negative-price window ... + charged = sum(result.schedule.pv_charge_w[t] for t in negative) * inputs.dt_h + assert charged > 5_000 + # ... because it exported earlier at a positive price instead of filling up. + before = [t for t in range(negative[0]) if inputs.export_price[t] > 0] + assert sum(result.schedule.export_w[t] for t in before) > 0 + absorbing = [t for t in negative if result.schedule.pv_charge_w[t] > EPS] + assert absorbing + assert all(rk.EXPORT_NEGATIVE_PRICE_AVOIDED in _keys(result, t) for t in absorbing) + assert result.objective < result.heuristic_objective + + +def test_negative_export_price_is_curtailed_not_paid() -> None: + s = situation("sunny_day") + inputs = situation_inputs( + replace(s, export_price=lambda at: -0.02 if 11 <= at.astimezone(TZ).hour < 15 else 0.08) + ) + result = run(inputs) + for t in range(inputs.n): + if inputs.export_price[t] < 0: + assert result.schedule.export_w[t] == pytest.approx(0.0, abs=EPS) + + +def test_price_spike_reserves_the_battery_for_the_spike() -> None: + inputs = scenario_inputs("price_spike") + result = run(inputs) + spike = [t for t in range(inputs.n) if inputs.import_price[t] > 1] + assert spike + assert all(result.schedule.battery_load_w[t] >= inputs.load_p50[t] - EPS for t in spike) + held = [t for t in range(spike[0]) if result.plan.intervals[t].battery.discharge_lock] + assert held + assert all(rk.HOLD_FOR_PRICE in _keys(result, t) for t in held) + reason = next(r for r in result.plan.intervals[held[0]].reasons if r.key == rk.HOLD_FOR_PRICE) + assert reason.args["later_price"] == pytest.approx(1.5) + + +def test_grid_charging_only_below_the_price_level_inside_the_schedule() -> None: + inputs = scenario_inputs("grid_charge_price_level") + result = run(inputs) + charged = [t for t in range(inputs.n) if result.schedule.grid_charge_w[t] > EPS] + assert charged + for t in range(inputs.n): + band = result.plan.intervals[t].battery + hour = _hour(result, t) + if t in charged: + assert inputs.import_price[t] <= 0.2 + assert 0 <= hour < 6 + assert band.grid_charge_max_w == pytest.approx( + result.schedule.grid_charge_w[t], abs=0.1 + ) + reason = next(r for r in result.plan.intervals[t].reasons if r.key == rk.GRID_CHARGE) + assert reason.args["later_price"] > reason.args["price"] + else: + assert band.grid_charge_max_w is None + # The spread rule: what is charged at 0.15 pays against the later 0.35. + assert inputs.battery is not None + assert inputs.battery.model.grid_charge_pays(0.15, 0.35) + + +def test_grid_charging_needs_the_spread_on_a_dynamic_tariff() -> None: + s = situation("grid_charge_price_level") + inputs = situation_inputs( + replace(s, import_price=lambda at: 0.15 if 1 <= at.astimezone(TZ).hour < 5 else 0.2) + ) + assert not any(inputs.grid_charge_w) + assert not any(run(inputs).schedule.grid_charge_w) + + +def test_grid_charging_stays_off_without_a_policy() -> None: + s = situation("grid_charge_price_level") + inputs = situation_inputs(replace(s, grid_charge=type(s.grid_charge)())) + assert not any(inputs.grid_charge_w) + + +def test_prefer_full_keeps_the_battery_first_until_max() -> None: + inputs = scenario_inputs("prefer_full") + result = run(inputs) + assert inputs.battery is not None + assert inputs.battery.strategy is BatteryStrategy.PREFER_FULL + full = next( + t for t in range(inputs.n) if result.schedule.soc_wh[t] >= inputs.battery.max_wh - 1 + ) + econ = economics(inputs) + for t in range(full): + # Devices only get what the battery cannot take (its charge limit). + assert ( + result.schedule.device_total_w(t) + <= max(0.0, econ.surplus_w[t] - inputs.battery.max_charge_w) + EPS + ) + assert result.plan.intervals[t].battery.priority_until_soc_pct == pytest.approx( + inputs.battery.max_soc_pct + ) + assert any( + band.preference is BandPreference.PREFER_ON + for interval in result.plan.intervals[full + 1 :] + for band in interval.devices.values() + ) + + +def test_reference_house_uses_the_export_limit_and_both_devices() -> None: + inputs = scenario_inputs("reference_house") + result = run(inputs) + assert inputs.export_limit_w == 13_500 + assert max(result.schedule.export_w) <= 13_500 + EPS + assert all(sum(d) > 0 for d in result.schedule.devices_w) + + +def test_spot_prices_without_a_formula_are_not_optimised() -> None: + s = situation("grid_charge_price_level") + inputs = situation_inputs(replace(s, price_includes="spot_only")) + assert inputs.price_mode is PriceMode.FLAT + assert inputs.reasons[0].key == rk.FALLBACK_SPOT_WITHOUT_FORMULA + assert not any(inputs.grid_charge_w) + result = run(inputs) + assert result.plan.reasons[1].key == rk.FALLBACK_SPOT_WITHOUT_FORMULA + assert result.plan.assumptions["price_mode"] == "flat" + + +def test_no_prices_plan_for_self_sufficiency() -> None: + inputs = situation_inputs(replace(situation("sunny_day"), with_prices=False)) + assert inputs.price_mode is PriceMode.FLAT + assert {r.key for r in inputs.reasons} >= {rk.FALLBACK_NO_PRICES} + assert run(inputs).source == "solver" + + +def test_the_plan_covers_48_hours_on_the_quarter_hour_grid() -> None: + inputs = scenario_inputs("sunny_day") + plan = run(inputs).plan + assert len(plan.intervals) == 192 + assert plan.intervals[-1].end - plan.intervals[0].start == timedelta(hours=48) + assert plan.source == "solver" + assert plan.created_at == inputs.now + + +# --- review fixes (PR 4-F) -------------------------------------------------------------------- + + +def _day_one(inputs, t: int) -> bool: # type: ignore[no-untyped-def] + return inputs.starts[t].astimezone(TZ).date() == inputs.now.astimezone(TZ).date() + + +@pytest.mark.parametrize("name", ["reference_house", "prefer_full"]) +def test_consumers_get_energy_on_day_one_once_the_battery_is_full(name: str) -> None: + """Review B1/D4: the device budget includes the overflow a full battery cannot take.""" + inputs = scenario_inputs(name) + result = run(inputs) + assert inputs.battery is not None + full = [ + t + for t in range(inputs.n) + if _day_one(inputs, t) and result.schedule.soc_wh[t] >= inputs.battery.max_wh - 1 + ] + assert full + assert sum(result.schedule.device_total_w(t) for t in full) > 1_000 + + +def test_the_morning_priority_ends_with_the_buffers_day() -> None: + """Review m3: ``priority_until_soc_pct`` only until the buffer's goal slot, not 48 h.""" + inputs = scenario_inputs("prefer_full") + result = run(inputs) + econ = economics(inputs) + assert econ.first_until >= 0 + for t, interval in enumerate(result.plan.intervals): + if t > econ.first_until: + assert interval.battery is not None + assert interval.battery.priority_until_soc_pct is None + + +def test_filled_prices_are_flagged_and_never_cited() -> None: + """Review m5: median stand-ins are marked and not used as 'later price' in a hold.""" + s = situation("price_spike") + known_until = s.now + timedelta(hours=10) + inputs = situation_inputs( + replace(s, import_price=lambda at: s.import_price(at) if at < known_until else None) + ) + result = run(inputs) + holds: list[int] | None = [] + for t, interval in enumerate(result.plan.intervals): + assert interval.prices is not None + assert interval.prices.estimated is (inputs.import_known[t] is None) + for reason in interval.reasons: + if reason.key != rk.HOLD_FOR_PRICE: + continue + later = [ + tau + for tau in range(t + 1, inputs.n) + if inputs.starts[tau].astimezone(TZ).strftime("%H:%M") == reason.args["later_time"] + ] + assert any(inputs.import_known[tau] is not None for tau in later) + assert holds is not None + holds.append(t) + assert holds, "the spike is inside the known prices: the plan holds for it" + + +def test_without_a_planner_battery_no_band_is_attached() -> None: + """Control-safety review m6: no battery in the plan -> the goal rules stay in charge.""" + s = situation("sunny_day") + inputs = situation_inputs(s) + inputs = replace(inputs, battery=None, goals=(), morning_buffer_pct=None, grid_charge_w=()) + plan = run(inputs).plan + assert all(interval.battery is None for interval in plan.intervals) + + +def test_negative_rule_slots_are_curtailed_not_exported() -> None: + """Review D3 under the de rule: where the rule zeroed the export price, no export.""" + inputs = scenario_inputs("negative_prices") + result = run(inputs) + flagged = [t for t in range(inputs.n) if inputs.discouraged(t)] + assert flagged + for t in flagged: + assert result.schedule.export_w[t] <= EPS + if econ_surplus(inputs, t) > EPS: + assert rk.EXPORT_NEGATIVE_PRICE_AVOIDED in _keys(result, t) + + +def econ_surplus(inputs, t: int) -> float: # type: ignore[no-untyped-def] + return max(0.0, inputs.pv_p50[t] - inputs.load_p50[t]) + + +def test_pv_charging_is_not_postponed_without_a_reason() -> None: + """Review M3: among equal-cost plans the battery charges early (tie-breaker).""" + s = situation("sunny_day") + inputs = situation_inputs(replace(s, devices=(), soc_pct=60.0)) + result = run(inputs) + first_surplus = next(t for t in range(inputs.n) if econ_surplus(inputs, t) > 100) + first_charge = next(t for t in range(inputs.n) if result.schedule.pv_charge_w[t] > EPS) + assert first_charge == first_surplus diff --git a/tests/safety/test_boundary.py b/tests/safety/test_boundary.py index 5af2c3c..9207593 100644 --- a/tests/safety/test_boundary.py +++ b/tests/safety/test_boundary.py @@ -22,7 +22,11 @@ sibling package; ``suncore.safety`` imports only ``suncore.core`` and itself; ``suncore.templates`` imports only ``suncore.core`` and itself (plus yaml/pydantic, ADR-0012); ``suncore.controller`` imports only ``suncore.core`` - and itself (Phase 3 WP7: drivers, power models and the gate are injected). + and itself (Phase 3 WP7: drivers, power models and the gate are injected); + ``suncore.tariff`` imports only ``suncore.core``, ``suncore.templates`` and itself (Phase 4 + WP4: Home Assistant reaches it through the injected action caller and entity reader); + ``suncore.planner`` imports only ``suncore.core`` and itself (Phase 4 WP8: the runtime + hands it the services' outputs). 5. ``suncore.api`` imports none of ``suncore.safety``, ``suncore.ha``, ``suncore.devices`` (it talks to the ``Services`` protocol only). 6. ``suncore.safety`` imports neither ``suncore.core.config`` nor ``suncore.storage`` and @@ -59,6 +63,8 @@ CORE = "suncore.core" TEMPLATES = "suncore.templates" CONTROLLER = "suncore.controller" +TARIFF = "suncore.tariff" +PLANNER = "suncore.planner" ACTUATOR_MODULE = "suncore.safety.actuator" GATE_MODULE = "suncore.safety.gate" DRIVERS = "suncore.devices.drivers" @@ -278,7 +284,7 @@ def test_api_does_not_import_write_side_packages(path: Path) -> None: @pytest.mark.parametrize("path", SOURCES, ids=lambda p: str(p.relative_to(ROOT))) def test_dependency_rule(path: Path) -> None: - """Rule 4: core imports no sibling; safety, templates, controller only core and itself.""" + """Rule 4: core imports no sibling; the other layered packages only what they may.""" module = module_name(path) if in_package(module, CORE): allowed = (CORE,) @@ -288,6 +294,10 @@ def test_dependency_rule(path: Path) -> None: allowed = (CORE, TEMPLATES) elif in_package(module, CONTROLLER): allowed = (CORE, CONTROLLER) + elif in_package(module, TARIFF): + allowed = (CORE, TEMPLATES, TARIFF) + elif in_package(module, PLANNER): + allowed = (CORE, PLANNER) else: return offenders = fmt( @@ -382,6 +392,7 @@ def test_read_only_action_allowlist_is_fixed() -> None: frozenset( { "tibber.get_prices", + "nordpool.get_prices_for_date", "solcast_solar.query_forecast_data", "weather.get_forecasts", "workday.check_date", diff --git a/tests/scenarios/tariff/entsoe.price.yaml b/tests/scenarios/tariff/entsoe.price.yaml new file mode 100644 index 0000000..7bce5f5 --- /dev/null +++ b/tests/scenarios/tariff/entsoe.price.yaml @@ -0,0 +1,19 @@ +template: entsoe.price +sim_scenario: summer_day +fixture: entsoe_avg_price +user_input: + now: "2026-10-16T10:07:00+02:00" + window_start: "2026-10-16T00:00:00+02:00" + window_hours: 24 +extra_entities: + - {entity_id: sensor.entsoe_average_electricity_price, platform: entsoe, unit: EUR/kWh} + - {entity_id: sensor.entsoe_current_electricity_price, platform: entsoe, unit: EUR/kWh, state: "0.07"} +roles: + price: + tied: [sensor.entsoe_average_electricity_price, sensor.entsoe_current_electricity_price] + pick: sensor.entsoe_average_electricity_price + unit: EUR/kWh +expect: + segments: [{step_min: 60, points: 3}] + first_price: 0.0712 + includes: spot_only diff --git a/tests/scenarios/tariff/entsoe.price_mwh.yaml b/tests/scenarios/tariff/entsoe.price_mwh.yaml new file mode 100644 index 0000000..353fe75 --- /dev/null +++ b/tests/scenarios/tariff/entsoe.price_mwh.yaml @@ -0,0 +1,11 @@ +# Same sensor as `entsoe.price` set to the MWh scale: the fixture has no MWh variant, so only +# the role resolution is checked here; the conversion and the unit guard are unit-tested. +template: entsoe.price_mwh +sim_scenario: summer_day +extra_entities: + - {entity_id: sensor.entsoe_average_electricity_price, platform: entsoe, unit: EUR/MWh, state: "71.2"} +roles: + price: + entity: sensor.entsoe_average_electricity_price + unit: EUR/MWh + criteria: [domain, platforms, unit_pattern] diff --git a/tests/scenarios/tariff/epex_spot.market_price.yaml b/tests/scenarios/tariff/epex_spot.market_price.yaml new file mode 100644 index 0000000..38f5613 --- /dev/null +++ b/tests/scenarios/tariff/epex_spot.market_price.yaml @@ -0,0 +1,21 @@ +template: epex_spot.market_price +sim_scenario: summer_day +fixture: epex_spot_total_price +user_input: + now: "2026-10-16T10:07:00+02:00" + window_start: "2026-10-16T00:00:00+02:00" + window_hours: 24 +extra_entities: + - {entity_id: sensor.epex_spot_total_price, platform: epex_spot, unit: "€/kWh"} + - {entity_id: sensor.epex_spot_market_price, platform: epex_spot, unit: "€/kWh", state: "0.0712"} +roles: + price: + tied: [sensor.epex_spot_total_price, sensor.epex_spot_market_price] + pick: sensor.epex_spot_total_price + unit: "€/kWh" +# The fixture is the total-price sensor's attribute; the market-price template reads the same +# attribute name from the chosen entity. +expect: + segments: [{step_min: 60, points: 2}, {step_min: 15, points: 2}] + first_price: 0.2631 + includes: spot_only diff --git a/tests/scenarios/tariff/epex_spot.total_price.yaml b/tests/scenarios/tariff/epex_spot.total_price.yaml new file mode 100644 index 0000000..b949268 --- /dev/null +++ b/tests/scenarios/tariff/epex_spot.total_price.yaml @@ -0,0 +1,21 @@ +# The unit is the currency SYMBOL (research "EPEX Spot": const.py:57): `€/kWh` resolves to EUR +# through suncore.tariff.units.normalise_price_unit. +template: epex_spot.total_price +sim_scenario: summer_day +fixture: epex_spot_total_price +user_input: + now: "2026-10-16T10:07:00+02:00" + window_start: "2026-10-16T00:00:00+02:00" + window_hours: 24 +extra_entities: + - {entity_id: sensor.epex_spot_total_price, platform: epex_spot, unit: "€/kWh"} + - {entity_id: sensor.epex_spot_market_price, platform: epex_spot, unit: "€/kWh", state: "0.0712"} +roles: + price: + tied: [sensor.epex_spot_total_price, sensor.epex_spot_market_price] + pick: sensor.epex_spot_total_price + unit: "€/kWh" +expect: + segments: [{step_min: 60, points: 2}, {step_min: 15, points: 2}] + first_price: 0.2631 + includes: all_in diff --git a/tests/scenarios/tariff/generic.price_list.yaml b/tests/scenarios/tariff/generic.price_list.yaml new file mode 100644 index 0000000..71d5aee --- /dev/null +++ b/tests/scenarios/tariff/generic.price_list.yaml @@ -0,0 +1,19 @@ +template: generic.price_list +sim_scenario: summer_day +fixture: generic_price_list +user_input: + now: "2026-10-16T10:07:00+02:00" + window_start: "2026-10-16T00:00:00+02:00" + window_hours: 24 +extra_entities: + - {entity_id: sensor.my_price_list, unit: EUR/kWh} +roles: + price: + # the demo's price sensor has the same unit: the user picks their template sensor + tied: [sensor.my_price_list, sensor.sim_electricity_price] + pick: sensor.my_price_list + unit: EUR/kWh +expect: + segments: [{step_min: 15, points: 3}] + first_price: 0.31 + includes: all_in diff --git a/tests/scenarios/tariff/nordpool.price.yaml b/tests/scenarios/tariff/nordpool.price.yaml new file mode 100644 index 0000000..f0eaa61 --- /dev/null +++ b/tests/scenarios/tariff/nordpool.price.yaml @@ -0,0 +1,22 @@ +# Nord Pool is not modelled by the simulator: the response is the documented shape +# (tests/fixtures/tariff/nordpool_get_prices_for_date.yaml, research "Nord Pool (Core)"). +template: nordpool.price +sim_scenario: summer_day +fixture: nordpool_get_prices_for_date +user_input: + now: "2026-10-16T10:07:00+02:00" + window_start: "2026-10-16T00:00:00+02:00" + window_hours: 24 + action_params: {config_entry: 01HXEXAMPLEENTRYID, areas: [SE3]} +extra_entities: + - {entity_id: sensor.nord_pool_se3_current_price, platform: nordpool, unit: EUR/kWh, state: "0.0455"} + - {entity_id: sensor.nord_pool_se3_next_price, platform: nordpool, unit: EUR/kWh, state: "0.0412"} +roles: + price: + tied: [sensor.nord_pool_se3_current_price, sensor.nord_pool_se3_next_price] + pick: sensor.nord_pool_se3_current_price + unit: EUR/kWh +expect: + segments: [{step_min: 60, points: 3}] + first_price: 0.0455 + includes: spot_only diff --git a/tests/scenarios/tariff/octopus_energy.rates.yaml b/tests/scenarios/tariff/octopus_energy.rates.yaml new file mode 100644 index 0000000..197583b --- /dev/null +++ b/tests/scenarios/tariff/octopus_energy.rates.yaml @@ -0,0 +1,32 @@ +template: octopus_energy.rates +sim_scenario: summer_day +fixture: octopus_rates +user_input: + now: "2026-10-16T10:07:00+01:00" + window_start: "2026-10-16T00:00:00+01:00" + window_hours: 48 + timezone: Europe/London + currency: GBP +extra_entities: + - {entity_id: sensor.octopus_energy_electricity_1234_5678_current_rate, platform: octopus_energy, unit: GBP/kWh, state: "0.1302"} + - {entity_id: event.octopus_energy_electricity_1234_5678_current_day_rates, platform: octopus_energy} + - {entity_id: event.octopus_energy_electricity_1234_5678_next_day_rates, platform: octopus_energy} +roles: + price: + entity: sensor.octopus_energy_electricity_1234_5678_current_rate + unit: GBP/kWh + criteria: [domain, platforms, units] + current_day_rates: + tied: + - event.octopus_energy_electricity_1234_5678_current_day_rates + - event.octopus_energy_electricity_1234_5678_next_day_rates + pick: event.octopus_energy_electricity_1234_5678_current_day_rates + next_day_rates: + tied: + - event.octopus_energy_electricity_1234_5678_current_day_rates + - event.octopus_energy_electricity_1234_5678_next_day_rates + pick: event.octopus_energy_electricity_1234_5678_next_day_rates +expect: + segments: [{step_min: 30, points: 3}, {step_min: 30, points: 2}] + first_price: 0.1245 + includes: all_in diff --git a/tests/scenarios/tariff/tibber.price.yaml b/tests/scenarios/tariff/tibber.price.yaml index 7cd5cd4..05953a1 100644 --- a/tests/scenarios/tariff/tibber.price.yaml +++ b/tests/scenarios/tariff/tibber.price.yaml @@ -5,3 +5,10 @@ roles: entity: sensor.sim_electricity_price unit: EUR/kWh criteria: [domain, translation_key, platforms, unit_pattern] +# The simulator answers `tibber.get_prices` through the same template path as the real +# integration: 15-minute slots for today and (after 13:00 local) tomorrow. +expect: + segments: null + min_points: 96 + includes: all_in + matches_state: true diff --git a/tests/scenarios/test_conformance.py b/tests/scenarios/test_conformance.py index 6fb9edf..3c7c97c 100644 --- a/tests/scenarios/test_conformance.py +++ b/tests/scenarios/test_conformance.py @@ -14,7 +14,12 @@ * kind specific facts: a device can be instantiated from the template defaults and the resolved mapping, the tariff price unit equals the currency of the HA configuration, the forecast attribute carries the declared fields in the declared unit and resolution, the - region currency is consistent with the HA configuration. + region currency is consistent with the HA configuration; +* tariffs with a price curve run the real adapter (``suncore.tariff``) on the curve: from the + simulator (Tibber: the fake answers ``tibber.get_prices``) or from a documented-shape fixture + (``tests/fixtures/tariff``) for integrations the simulator does not model. A scenario may + list ``extra_entities`` - the registry metadata of fixture entities - and states what the + adapter must return under ``expect``. """ from __future__ import annotations @@ -23,7 +28,7 @@ import itertools import re from collections.abc import AsyncIterator, Mapping, Sequence -from datetime import UTC, datetime +from datetime import UTC, datetime, timedelta from pathlib import Path from typing import Any from zoneinfo import ZoneInfo @@ -34,11 +39,14 @@ from suncore.core.devices import DeviceConfig from suncore.core.entities import EntityMeta +from suncore.core.series import TimeRange, floor_to_step from suncore.core.site import EntityRef from suncore.core.units import Dimension, parse_unit from suncore.ha.connection import EntityState from suncore.sim.fake_ha import FakeHAConnection from suncore.sim.scenario import load_scenario +from suncore.tariff import EntityReading, SourceBinding, TemplatePriceSource +from suncore.tariff.units import normalise_price_unit from suncore.templates import ( DeviceTemplate, ForecastTemplate, @@ -70,13 +78,52 @@ class RoleExpectation(BaseModel): criteria: list[str] | None = None +class ExtraEntity(BaseModel): + """Registry metadata of an entity of a documented-shape fixture (not in the demo house).""" + + model_config = ConfigDict(extra="forbid") + + entity_id: str + platform: str | None = None + unit: str | None = None + translation_key: str | None = None + device_class: str | None = None + state: str = "0" + """State when the fixture has no entity of this id (action fixtures carry none).""" + + +class SegmentExpectation(BaseModel): + model_config = ConfigDict(extra="forbid") + + step_min: int + points: int + + +class SeriesExpectation(BaseModel): + """What the adapter returns for the curve.""" + + model_config = ConfigDict(extra="forbid") + + segments: list[SegmentExpectation] | None = None + min_points: int | None = None + first_price: float | None = None + """First known price, currency/kWh (after the MWh conversion).""" + includes: str | None = None + matches_state: bool = False + """The first price equals the state of the price role's entity (the sim's Tibber).""" + + class ScenarioFile(BaseModel): model_config = ConfigDict(extra="forbid") template: str sim_scenario: str + fixture: str | None = None + """Documented-shape fixture under ``tests/fixtures/tariff`` (entities and/or response).""" user_input: dict[str, Any] = Field(default_factory=dict) + extra_entities: list[ExtraEntity] = Field(default_factory=list) roles: dict[str, RoleExpectation] + expect: SeriesExpectation | None = None def _scenario_files() -> dict[str, Path]: @@ -159,18 +206,20 @@ def _check_tied( assert {m.entity_id for m in top} == set(expected.tied), name if required: # the user has to choose between the tied candidates assert expected.pick in expected.tied, f"{name}: a required role needs a pick" - resolved[name] = by_id[expected.pick] # type: ignore[index] - else: - assert expected.pick is None, f"{name}: pick is only for required roles" + if expected.pick is not None: # an optional role may be chosen too + assert expected.pick in expected.tied, f"{name}: the pick must be a tied candidate" + resolved[name] = by_id[expected.pick] @pytest.mark.parametrize("template_id", sorted(FILES)) async def test_template_conforms(template_id: str, fake: FakeHAConnection) -> None: scenario = _load(FILES[template_id]) template = CATALOG.templates[template_id] - metas = fake.entity_metas() + fixture = _fixture(scenario) + metas = [*fake.entity_metas(), *_extra_metas(scenario)] by_id = {m.entity_id: m for m in metas} states = {s.entity_id: s for s in await fake.get_states()} + states.update(_extra_states(scenario, fixture)) ranked = _resolve( template, metas, {r: e.pick for r, e in scenario.roles.items() if e.pick is not None} ) @@ -203,7 +252,9 @@ async def test_template_conforms(template_id: str, fake: FakeHAConnection) -> No if isinstance(template, DeviceTemplate): _check_device(template, scenario, resolved) elif isinstance(template, TariffTemplate): - await _check_tariff(template, fake, resolved, states) + await _check_tariff( + template, scenario, fake=fake, resolved=resolved, states=states, fixture=fixture + ) elif isinstance(template, ForecastTemplate): await _check_forecast(template, fake, resolved, states) elif isinstance(template, RegionTemplate): @@ -240,18 +291,145 @@ def _check_device( assert config.max_switches_per_hour is None # None = safety default, not unlimited +FIXTURES = ROOT / "tests" / "fixtures" / "tariff" + + +def _fixture(scenario: ScenarioFile) -> dict[str, Any]: + if scenario.fixture is None: + return {} + data = yaml.safe_load((FIXTURES / f"{scenario.fixture}.yaml").read_text(encoding="utf-8")) + assert isinstance(data, dict) + return data + + +def _extra_metas(scenario: ScenarioFile) -> list[EntityMeta]: + return [ + EntityMeta.of( + e.entity_id, + platform=e.platform, + unit=e.unit, + translation_key=e.translation_key, + device_class=e.device_class, + ) + for e in scenario.extra_entities + ] + + +def _extra_states(scenario: ScenarioFile, fixture: Mapping[str, Any]) -> dict[str, EntityState]: + from_fixture = {e["entity_id"]: e for e in fixture.get("entities", [])} + states: dict[str, EntityState] = {} + for extra in scenario.extra_entities: + recorded = from_fixture.get(extra.entity_id) + states[extra.entity_id] = EntityState( + extra.entity_id, + str(recorded["state"]) if recorded else extra.state, + dict(recorded["attributes"]) if recorded else {}, + ) + return states + + +def _currency_of(unit: str) -> str: + return normalise_price_unit(unit).split("/")[0] + + async def _check_tariff( template: TariffTemplate, + scenario: ScenarioFile, + *, fake: FakeHAConnection, resolved: Mapping[str, EntityMeta], states: Mapping[str, EntityState], + fixture: Mapping[str, Any], ) -> None: - currency = (await fake.get_config())["currency"] + currency = scenario.user_input.get("currency") or (await fake.get_config())["currency"] price = resolved["price"] - assert price.unit == template.price_unit.replace("{currency}", currency) - assert float(states[price.entity_id].state) > 0 # state = all-in price of the current slot - assert template.price_series is not None - assert template.price_series.fields.value_unit == "{currency}/kWh" + assert price.unit is not None + # the entity unit may carry a currency symbol (EPEX Spot `€/kWh`) and the other energy scale + # (Nord Pool sensors are per kWh, its action per MWh): the currency has to agree + assert ( + _currency_of(price.unit) + == template.price_unit.replace("{currency}", currency).split("/")[0] + ) + assert float(states[price.entity_id].state) is not None # the state is a number + if template.price_series is None: + return + series = template.price_series + assert series.fields.value_unit == template.price_unit # one unit for the whole template + if scenario.expect is not None: + await _check_series( + template, + scenario, + fake=fake, + resolved=resolved, + states=states, + fixture=fixture, + currency=currency, + ) + + +async def _check_series( + template: TariffTemplate, + scenario: ScenarioFile, + *, + fake: FakeHAConnection, + resolved: Mapping[str, EntityMeta], + states: Mapping[str, EntityState], + fixture: Mapping[str, Any], + currency: str, +) -> None: + """Run the real adapter on the scenario's curve and compare with the expectation.""" + expect = scenario.expect + assert expect is not None + user = scenario.user_input + now = datetime.fromisoformat(user["now"]) if "now" in user else fake.sim_time + assert now is not None + first = floor_to_step( + datetime.fromisoformat(user["window_start"]) if "window_start" in user else now + ) + window = TimeRange( + start=first, end=first + timedelta(hours=float(user.get("window_hours", 48))) + ) + readings = { + entity_id: EntityReading(state.state, state.attributes) + for entity_id, state in states.items() + } + + async def action( + domain: str, service: str, data: Mapping[str, Any], **_: float + ) -> Mapping[str, Any]: + if "response" in fixture: + return fixture["response"] # type: ignore[no-any-return] + return await fake.call_action_response(domain, service, data) + + source = TemplatePriceSource( + template, + SourceBinding( + tz=ZoneInfo(user.get("timezone", "Europe/Berlin")), + entities={role: meta.entity_id for role, meta in resolved.items()}, + action_params=user.get("action_params", {}), + series_key=user.get("series_key"), + currency=currency, + ), + action=action, # type: ignore[arg-type] + attributes=readings.get, + clock=lambda: now, + ) + data = await source.fetch_segments(window, now) + if expect.segments is not None: + got = [(int(s.step.total_seconds() // 60), len(s)) for s in data.segments] + assert got == [(e.step_min, e.points) for e in expect.segments] + if expect.min_points is not None: + assert sum(len(s) for s in data.segments) >= expect.min_points + values = [v for s in data.segments for v in s.import_price.values if v is not None] + assert values, "the adapter returned no price" + if expect.first_price is not None: + assert values[0] == pytest.approx(expect.first_price) + if expect.matches_state: + price = resolved["price"] + # the state is the total price of the running slot, rounded to 3 decimals + assert values[0] == pytest.approx(float(states[price.entity_id].state), abs=0.0006) + if expect.includes is not None: + assert {s.price_includes for s in data.segments} == {expect.includes} def _energy_kwh(points: Sequence[float], unit_text: str, resolution_min: int) -> float: diff --git a/tests/sim/test_fake_prices.py b/tests/sim/test_fake_prices.py new file mode 100644 index 0000000..60e7d88 --- /dev/null +++ b/tests/sim/test_fake_prices.py @@ -0,0 +1,140 @@ +# SPDX-License-Identifier: Apache-2.0 +"""The simulator's ``tibber.get_prices``: the documented response, the negative-price scenario.""" + +from __future__ import annotations + +import asyncio +import itertools +from collections.abc import AsyncIterator +from datetime import UTC, datetime, timedelta + +import pytest + +from suncore.sim.demo_devices import sim_price +from suncore.sim.fake_ha import FakeHAConnection +from suncore.sim.scenario import PriceParams, load_scenario, parse_scenario + +pytestmark = pytest.mark.simulator + +Q = timedelta(minutes=15) + + +async def started(name: str, hour: int) -> FakeHAConnection: + never = asyncio.Event() + + async def sleep(_: float) -> None: + await never.wait() + + conn = FakeHAConnection( + load_scenario(name), + clock=lambda: datetime(2026, 6, 21, tzinfo=UTC), + sleep=sleep, + start_offset_s=hour * 3600, + ) + await conn.connect() + return conn + + +@pytest.fixture +async def morning() -> AsyncIterator[FakeHAConnection]: + conn = await started("summer_day", 9) + yield conn + await conn.close() + + +@pytest.fixture +async def afternoon() -> AsyncIterator[FakeHAConnection]: + conn = await started("summer_day", 14) + yield conn + await conn.close() + + +def starts(response: dict[str, object]) -> list[datetime]: + slots = response["prices"]["Home"] # type: ignore[index] + return [datetime.fromisoformat(s["start_time"]) for s in slots] + + +async def test_default_window_is_local_today_in_15_minute_slots( + morning: FakeHAConnection, +) -> None: + out = await morning.call_action_response("tibber", "get_prices") + stamps = starts(out) + assert len(stamps) == 96 + assert stamps[0] == datetime(2026, 6, 21, 0, 0, tzinfo=stamps[0].tzinfo) + assert {b - a for a, b in itertools.pairwise(stamps)} == {Q} + assert stamps[0].utcoffset() == timedelta(hours=2) # the scenario's local offset + first = out["prices"]["Home"][0] + assert first == {"start_time": stamps[0].isoformat(), "price": sim_price(stamps[0])} + + +async def test_tomorrow_exists_only_after_the_publication_hour( + morning: FakeHAConnection, afternoon: FakeHAConnection +) -> None: + window = {"start": "2026-06-21T00:00:00+02:00", "end": "2026-06-23T00:00:00+02:00"} + early = starts(await morning.call_action_response("tibber", "get_prices", window)) + late = starts(await afternoon.call_action_response("tibber", "get_prices", window)) + assert len(early) == 96 # 09:00 local: tomorrow is not published yet + assert len(late) == 192 # 14:00 local: today and tomorrow + assert late[-1] == datetime(2026, 6, 22, 23, 45, tzinfo=late[-1].tzinfo) + + +async def test_start_and_end_filter_the_slots_like_the_integration( + afternoon: FakeHAConnection, +) -> None: + # The fake is rate limited like the real connection (4-B): one sub-key per call. + out = await afternoon.call_action_response( + "tibber", + "get_prices", + {"start": "2026-06-21T10:00:00+02:00", "end": "2026-06-21T11:00:00+02:00"}, + rate_key="a", + ) + assert [s.hour for s in starts(out)] == [10, 10, 10, 10] # start <= t < end + inverted = await afternoon.call_action_response( + "tibber", + "get_prices", + {"start": "2026-06-21T10:00:00+02:00", "end": "2026-06-21T09:00:00+02:00"}, + rate_key="b", + ) + assert len(starts(inverted)) == 96 # start >= end: end = start + 1 day, capped to what exists + naive = await afternoon.call_action_response( + "tibber", + "get_prices", + {"start": "2026-06-21 12:00:00", "end": "2026-06-21 12:30:00"}, + rate_key="c", + ) + assert len(starts(naive)) == 2 + + +async def test_the_negative_prices_scenario_dips_below_zero_at_noon() -> None: + conn = await started("negative_prices", 9) + try: + out = await conn.call_action_response("tibber", "get_prices") + finally: + await conn.close() + prices = { + datetime.fromisoformat(s["start_time"]).hour: s["price"] for s in out["prices"]["Home"] + } + assert prices[13] < 0 + assert min(prices.values()) == pytest.approx(-0.08, abs=0.005) + assert prices[3] > 0 + assert prices[19] > 0.3 + + +def test_the_default_profile_never_goes_negative() -> None: + day = datetime(2026, 6, 21, tzinfo=UTC) + assert min(sim_price(day + Q * i) for i in range(96)) > 0 + assert min(sim_price(day + Q * i, "negative_midday") for i in range(96)) < 0 + + +def test_the_price_profile_is_part_of_the_scenario_schema() -> None: + assert load_scenario("summer_day").prices == PriceParams() + assert load_scenario("negative_prices").prices.profile == "negative_midday" + base = "name: x\nstart: '2026-06-21T00:00:00+02:00'\nduration_s: 60\nstep_s: 60\n" + assert ( + parse_scenario(base + "prices: {profile: negative_midday}\n").prices.profile + == "negative_midday" + ) + with pytest.raises(ValueError, match="profile"): + parse_scenario(base + "prices: {profile: sideways}\n") + with pytest.raises(ValueError, match="tomorrow_after_hour"): + parse_scenario(base + "prices: {tomorrow_after_hour: 24}\n") diff --git a/tests/sim/test_planner_shadow.py b/tests/sim/test_planner_shadow.py new file mode 100644 index 0000000..d935765 --- /dev/null +++ b/tests/sim/test_planner_shadow.py @@ -0,0 +1,200 @@ +# SPDX-License-Identifier: Apache-2.0 +"""``planner_in_shadow``: the planner feeds the real controller; nothing is written (WP9). + +The scenario runs the whole chain in simulated time: the simulated house, the +``PlanningService`` (real inputs, real HiGHS planner in its daemon thread, a plan every quarter +hour), the control stack with the real controller and gate, every device in shadow mode. +""" + +from __future__ import annotations + +import asyncio +from dataclasses import replace +from datetime import timedelta + +import pytest + +from suncore.app.planning import LiveReading, PlanningService, PlanningSettings, PlanningSnapshot +from suncore.core.battery import BatteryStrategy +from suncore.core.control import BatteryBand, DeviceBand, Plan, PlanInterval +from suncore.core.decisions import BatteryAction, DecisionKind, OperatingMode +from suncore.sim.planner_scenarios import situation, situation_inputs +from suncore.sim.runner import RunResult, ScenarioRunner +from suncore.sim.scenario import load_scenario +from tests.safety.helpers import make_intent +from tests.sim.helpers import catalog + +pytestmark = pytest.mark.simulator + +PLAN_EVERY_STEPS = 30 # 15 minutes at 30 s per step + + +class Observed: + """What the test saw while the scenario ran.""" + + def __init__(self) -> None: + self.plans: list[Plan] = [] + self.followed_ticks = 0 + self.priority_ticks = 0 + self.battery_first_violations: list[str] = [] + self.battery_decision: DecisionKind | None = None + self.battery_reasons: list[str] = [] + self.run_ticks = 0 + + +async def play() -> tuple[RunResult, ScenarioRunner, PlanningService, Observed]: + scenario = load_scenario("planner_in_shadow") + runner = ScenarioRunner(scenario, catalog(), global_mode=OperatingMode.SHADOW) + observed = Observed() + + def live() -> LiveReading: + last = runner._steps[-1] if runner._steps else None + return LiveReading(soc_pct=None if last is None else last.soc_pct) + + async def collect(now, previous): # type: ignore[no-untyped-def] + soc = live().soc_pct or 25.0 + # ``prefer_full`` carries a morning priority (battery first until full) the controller + # must keep; since review m3 a buffer already reached carries none. + base = replace(situation("sunny_day"), strategy=BatteryStrategy.PREFER_FULL) + inputs = situation_inputs(replace(base, now=now, soc_pct=soc)) + return PlanningSnapshot(replace(inputs, previous=previous)) + + planning = PlanningService(collect, live, clock=runner.vt.clock, settings=PlanningSettings()) + planning.add_listener(lambda: observed.plans.append(planning.plan)) # type: ignore[arg-type] + runner.plan_provider = planning.active_plan + await runner.start() + for index in range(scenario.steps): + if index % PLAN_EVERY_STEPS == 0: + await planning.tick() # the daemon thread solves; simulated time stands still + await runner.step(index) + stack = runner.stack + assert stack is not None + last = stack.last + if last is None: + continue + observed.run_ticks += 1 + plan = stack.current_plan(last.ts) + band = plan.battery_band_at(last.ts) + if plan.is_default: + continue + observed.followed_ticks += 1 + priority = band.priority_until_soc_pct + if priority is not None and plan.interval_at(last.ts) is not None: + observed.priority_ticks += 1 + soc = last.site.soc_pct + if (soc is None or soc < priority) and last.site.charging_available: + observed.battery_first_violations.append(f"{last.ts}: soc {soc} < {priority}") + # A plan is present: the gate still rejects battery limits (BatteryAction, until WP10). + assert runner.stack is not None + decision = await runner.stack.gate.submit( + make_intent( + BatteryAction(grid_charge_w=3000, min_soc_pct=20), + asset_id="rod", + ts=runner.vt.now, + ) + ) + observed.battery_decision = decision.kind + observed.battery_reasons = [r.key for r in decision.reasons] + result = await runner.finish() + await runner.close() + return result, runner, planning, observed + + +@pytest.fixture(scope="module") +def played() -> tuple[RunResult, ScenarioRunner, PlanningService, Observed]: + return asyncio.run(play()) + + +def test_a_plan_is_computed_every_quarter_hour_and_followed( + played: tuple[RunResult, ScenarioRunner, PlanningService, Observed], +) -> None: + result, _, planning, observed = played + assert len(observed.plans) >= 20 # 6 h of quarter hours (the first run is a "start") + assert {p.source for p in observed.plans} <= {"solver", "heuristic"} + assert observed.followed_ticks > 0.9 * observed.run_ticks + assert planning.status().consecutive_failures == 0 + assert result.scenario.name == "planner_in_shadow" + + +def test_the_controller_keeps_the_battery_first_below_the_plans_priority( + played: tuple[RunResult, ScenarioRunner, PlanningService, Observed], +) -> None: + _, _, _, observed = played + assert observed.priority_ticks > 0, "the plan must carry a morning priority for this scenario" + assert observed.battery_first_violations == [] + + +def test_in_shadow_mode_nothing_is_written( + played: tuple[RunResult, ScenarioRunner, PlanningService, Observed], +) -> None: + result, _, _, _ = played + assert result.of_kind(DecisionKind.ACCEPTED) == [] + for device_id in result.configs: + assert result.transitions(device_id) == [] + assert not any(result.devices[device_id].on) + assert result.of_kind(DecisionKind.SHADOW), "the controller followed the plan: 'would have'" + + +def test_the_gate_rejects_battery_limits_with_a_plan_present( + played: tuple[RunResult, ScenarioRunner, PlanningService, Observed], +) -> None: + _, _, planning, observed = played + assert not planning.active_plan(planning.plan.created_at).is_default # type: ignore[union-attr] + assert observed.battery_decision is DecisionKind.REJECTED + assert observed.battery_reasons == ["safety.battery_not_supported"] + + +def test_no_decision_of_the_run_carries_a_battery_action( + played: tuple[RunResult, ScenarioRunner, PlanningService, Observed], +) -> None: + """The controller never proposes battery limits (control-safety review m4); the only + battery intent is the one this test submits to the gate itself (asset ``rod``).""" + result, _, _, _ = played + controller_made = [d for d in result.decisions if isinstance(d.intent.action, BatteryAction)] + assert all(d.kind is DecisionKind.REJECTED for d in controller_made) + assert all(d.intent.asset_id == "rod" for d in controller_made) + assert len(controller_made) <= 1 + + +async def _blocked_run() -> RunResult: + scenario = load_scenario("planner_in_shadow") + runner = ScenarioRunner(scenario, catalog(), global_mode=OperatingMode.SHADOW) + start = runner.vt.now + half = start + timedelta(hours=3) + consumers_first = BatteryBand(charge_from_surplus=False) + blocked = DeviceBand(allowed=False, max_power_w=0.0) + plan = Plan( + intervals=( + PlanInterval(start=start - timedelta(hours=1), end=half, battery=consumers_first), + PlanInterval( + start=half, + end=start + timedelta(hours=7), + battery=consumers_first, + devices={"rod": blocked, "pool": blocked}, + ), + ) + ) + runner.plan_provider = lambda _now: plan + await runner.start() + for index in range(scenario.steps): + await runner.step(index) + result = await runner.finish() + await runner.close() + return result + + +def test_a_blocking_device_band_takes_effect_in_shadow() -> None: + """``DeviceBand(allowed=False)``: the 'would have' level drops with ``plan_blocked``.""" + result = asyncio.run(_blocked_run()) + shadow = result.of_kind(DecisionKind.SHADOW) + assert shadow + blocked = [d for d in shadow if "controller.plan_blocked" in [r.key for r in d.intent.reasons]] + assert blocked + first_blocked = min(d.ts for d in blocked) + # After the block no shadow decision raises a device again. + assert all( + "controller.plan_blocked" in [r.key for r in d.intent.reasons] + for d in shadow + if d.ts >= first_blocked + ) + assert result.of_kind(DecisionKind.ACCEPTED) == [] diff --git a/tests/sim/test_scenario.py b/tests/sim/test_scenario.py index 8b8286c..462eb14 100644 --- a/tests/sim/test_scenario.py +++ b/tests/sim/test_scenario.py @@ -17,6 +17,8 @@ "ha_disconnect", "inverter_hang", "manual_override", + "negative_prices", + "planner_in_shadow", "sensor_dropout", "summer_day", "water_heater_steps", @@ -139,7 +141,7 @@ def test_outdoor_temperature_is_a_daily_cosine() -> None: @pytest.mark.parametrize( "name", - [n for n in BUNDLED if n not in ("summer_day", "winter_fog")], + [n for n in BUNDLED if n not in ("summer_day", "winter_fog", "negative_prices")], ) def test_closed_loop_scenarios_declare_devices(name: str) -> None: sc = load_scenario(name) diff --git a/tests/tariff/__init__.py b/tests/tariff/__init__.py new file mode 100644 index 0000000..9881313 --- /dev/null +++ b/tests/tariff/__init__.py @@ -0,0 +1 @@ +# SPDX-License-Identifier: Apache-2.0 diff --git a/tests/tariff/helpers.py b/tests/tariff/helpers.py new file mode 100644 index 0000000..eb0e0b3 --- /dev/null +++ b/tests/tariff/helpers.py @@ -0,0 +1,126 @@ +# SPDX-License-Identifier: Apache-2.0 +"""Shared test doubles and builders for the tariff tests (no network, no wall clock).""" + +from __future__ import annotations + +from collections.abc import Callable, Mapping +from datetime import datetime, timedelta +from pathlib import Path +from typing import Any +from zoneinfo import ZoneInfo + +import yaml + +from suncore.core.series import PriceSeries, TimeSeries +from suncore.tariff import EntityReader, EntityReading, SourceBinding, TemplatePriceSource +from suncore.templates import TariffTemplate, load_templates + +ROOT = Path(__file__).resolve().parents[2] +FIXTURES = ROOT / "tests" / "fixtures" / "tariff" +CATALOG = load_templates(ROOT / "templates") +BERLIN = ZoneInfo("Europe/Berlin") +LONDON = ZoneInfo("Europe/London") +NOW = datetime(2026, 10, 16, 10, 7, tzinfo=BERLIN) +"""A Friday morning, CEST.""" + + +def fixture(name: str) -> dict[str, Any]: + """A documented-shape fixture (``tests/fixtures/tariff/.yaml``).""" + data = yaml.safe_load((FIXTURES / f"{name}.yaml").read_text(encoding="utf-8")) + assert isinstance(data, dict) + return data + + +def template(template_id: str) -> TariffTemplate: + found = CATALOG.get(template_id) + assert isinstance(found, TariffTemplate), template_id + return found + + +class StubActions: + """An ``ActionCaller`` answering from a function, recording every call.""" + + def __init__(self, respond: Callable[[Mapping[str, Any]], Mapping[str, Any]]) -> None: + self._respond = respond + self.calls: list[tuple[str, str, dict[str, Any], float, float]] = [] + self.error: Exception | None = None + + async def __call__( + self, + domain: str, + service: str, + data: Mapping[str, Any], + *, + min_interval_s: float, + max_wait_s: float, + ) -> Mapping[str, Any]: + self.calls.append((domain, service, dict(data), min_interval_s, max_wait_s)) + if self.error is not None: + raise self.error + return self._respond(data) + + +def reader_of(entities: Mapping[str, EntityReading | None]) -> EntityReader: + def read(entity_id: str) -> EntityReading | None: + return entities.get(entity_id) + + return read + + +def readings(name: str) -> dict[str, EntityReading]: + """Entity readings of a fixture file.""" + return { + e["entity_id"]: EntityReading(str(e["state"]), e["attributes"]) + for e in fixture(name)["entities"] + } + + +def attribute_source( + template_id: str, + entities: Mapping[str, str], + reading: Mapping[str, EntityReading | None], + *, + now: datetime = NOW, + **binding: Any, +) -> TemplatePriceSource: + tz = binding.pop("tz", BERLIN) + return TemplatePriceSource( + template(template_id), + SourceBinding(tz=tz, entities=entities, **binding), + attributes=reader_of(reading), + clock=lambda: now, + ) + + +def action_source( + template_id: str, + actions: StubActions, + *, + now: datetime = NOW, + **binding: Any, +) -> TemplatePriceSource: + tz = binding.pop("tz", BERLIN) + return TemplatePriceSource( + template(template_id), + SourceBinding(tz=tz, **binding), + action=actions, + clock=lambda: now, + ) + + +def quarter_hours( + start: datetime, count: int, first: float = 0.2, step: float = 0.001 +) -> list[tuple[datetime, float]]: + return [(start + timedelta(minutes=15 * i), round(first + step * i, 6)) for i in range(count)] + + +def prices( + start: datetime, + values: list[float | None], + *, + step: timedelta = timedelta(minutes=15), + includes: str = "all_in", + source_id: str = "t", +) -> PriceSeries: + series = TimeSeries(start=start, step=step, values=tuple(values), unit="currency/kWh") # type: ignore[arg-type] + return PriceSeries(source_id=source_id, price_includes=includes, import_price=series) # type: ignore[arg-type] diff --git a/tests/tariff/test_engine.py b/tests/tariff/test_engine.py new file mode 100644 index 0000000..347bd7e --- /dev/null +++ b/tests/tariff/test_engine.py @@ -0,0 +1,691 @@ +# SPDX-License-Identifier: Apache-2.0 +"""The template-driven adapters, one per integration, from documented-shape fixtures.""" + +from __future__ import annotations + +from collections.abc import Mapping +from datetime import UTC, date, datetime, timedelta +from typing import Any + +import pytest + +from suncore.core.series import TimeRange, floor_to_step +from suncore.tariff import ( + CurrencyMismatchError, + CurrentPriceSource, + EntityReading, + MissingEntityError, + MissingParamError, + SourceBinding, + SourceUnavailableError, + TemplatePriceSource, + UnitMismatchError, +) +from suncore.tariff.engine import request_dates +from suncore.tariff.errors import AmbiguousSeriesError, MalformedPayloadError +from suncore.tariff.sources import finest_series +from tests.tariff.helpers import ( + BERLIN, + LONDON, + NOW, + StubActions, + action_source, + attribute_source, + fixture, + reader_of, + readings, + template, +) + +H = timedelta(hours=1) +Q = timedelta(minutes=15) +MIDNIGHT = datetime(2026, 10, 16, 0, 0, tzinfo=BERLIN) + + +def window(hours: int = 48, start: datetime = NOW) -> TimeRange: + begin = floor_to_step(start) + return TimeRange(start=begin, end=begin + timedelta(hours=hours)) + + +def iso(moment: datetime) -> str: + return moment.isoformat() + + +# --- Tibber (action, 15 minutes, per home) ---------------------------------------------- + + +def tibber_response(start: datetime, slots: int, *, home: str = "Home") -> dict[str, Any]: + return { + "prices": { + home: [ + {"start_time": iso(start + Q * i), "price": round(0.30 + 0.001 * i, 4)} + for i in range(slots) + ] + } + } + + +async def test_tibber_fixture_is_parsed_on_the_native_15_minute_grid() -> None: + actions = StubActions(lambda _data: fixture("tibber_get_prices")["response"]) + source = action_source("tibber.price", actions) + data = await source.fetch_segments(window(2, datetime(2026, 10, 16, 0, 0, tzinfo=BERLIN)), NOW) + (segment,) = data.segments + assert segment.source_id == "tibber.price" + assert segment.price_includes == "all_in" + assert segment.step == Q + assert segment.import_price.values[:3] == (0.2812, 0.279, 0.2755) + assert segment.start == datetime(2026, 10, 15, 22, 0, tzinfo=UTC) + assert data.known_end == datetime(2026, 10, 15, 22, 0, tzinfo=UTC) + 6 * Q + + +async def test_tibber_request_asks_for_the_local_days_of_the_window() -> None: + actions = StubActions(lambda _data: {"prices": {}}) + source = action_source("tibber.price", actions) + await source.fetch_segments(window(48), NOW) + ((domain, service, data, interval, wait),) = actions.calls + assert (domain, service) == ("tibber", "get_prices") + assert data == { + "start": "2026-10-16T00:00:00+02:00", + "end": "2026-10-19T00:00:00+02:00", # NOW + 48 h is 18 Oct 10:00: the day after is the 19th + } + assert interval == 30.0 + assert wait == 0.0 + + +async def test_tibber_empty_response_is_no_data_not_an_error() -> None: + actions = StubActions(lambda _data: {"prices": {}}) + data = await action_source("tibber.price", actions).fetch_segments(window(), NOW) + assert data.segments == () + assert data.known_end is None + + +async def test_tibber_two_homes_need_a_series_key() -> None: + payload = { + "prices": { + "Home": tibber_response(datetime(2026, 10, 16, 10, tzinfo=BERLIN), 4)["prices"]["Home"], + "Cabin": tibber_response(datetime(2026, 10, 16, 10, tzinfo=BERLIN), 4, home="x")[ + "prices" + ]["x"], + } + } + actions = StubActions(lambda _data: payload) + with pytest.raises(AmbiguousSeriesError): + await action_source("tibber.price", actions).fetch_segments(window(), NOW) + data = await action_source("tibber.price", actions, series_key="Cabin").fetch_segments( + window(), NOW + ) + assert len(data.segments[0].import_price) == 4 + + +async def test_tibber_gaps_and_unreadable_prices_are_none() -> None: + start = datetime(2026, 10, 16, 10, 0, tzinfo=BERLIN) + rows = tibber_response(start, 6)["prices"]["Home"] + del rows[2] # a missing slot + rows[4] = {"start_time": rows[4]["start_time"], "price": None} # an unreadable price + actions = StubActions(lambda _data: {"prices": {"Home": rows}}) + data = await action_source("tibber.price", actions).fetch_segments(window(), NOW) + (segment,) = data.segments + values = segment.import_price.values + assert len(values) == 6 + assert values[2] is None # the gap + assert values[3] is not None + assert values[4] is not None + assert values[5] is None # a null price is a gap too + assert data.report.unreadable_values == 1 + + +async def test_tibber_mixed_15_and_60_minutes_gives_two_segments_and_a_15_minute_series() -> None: + day = datetime(2026, 10, 16, 12, 0, tzinfo=BERLIN) + quarter = [ + {"start_time": iso(day + Q * i), "price": 0.30 + 0.01 * i} + for i in range(8) # 12:00-14:00 + ] + hourly = [ + {"start_time": iso(day + 2 * H + H * i), "price": 0.50 + 0.1 * i} for i in range(3) + ] # 14:00-17:00 + actions = StubActions(lambda _data: {"prices": {"Home": quarter + hourly}}) + source = action_source("tibber.price", actions) + data = await source.fetch_segments(window(), NOW) + first, second = data.segments + assert (first.step, len(first)) == (Q, 8) + assert (second.step, len(second)) == (H, 3) + merged = await source.fetch(window()) + assert merged.step == Q + assert len(merged) == 8 + 12 # hourly values held for four quarters each + assert merged.import_price.values[8:12] == (0.5, 0.5, 0.5, 0.5) + + +async def test_tibber_dst_end_day_has_25_hours_of_quarters() -> None: + start = datetime(2026, 10, 25, 0, 0, tzinfo=BERLIN).astimezone(UTC) # 22:00 UTC the day before + rows = [ + {"start_time": iso((start + Q * i).astimezone(BERLIN)), "price": 0.2 + 0.0001 * i} + for i in range(25 * 4) + ] + actions = StubActions(lambda _data: {"prices": {"Home": rows}}) + now = datetime(2026, 10, 25, 0, 30, tzinfo=BERLIN) + data = await action_source("tibber.price", actions, now=now).fetch_segments( + TimeRange(start=start, end=start + timedelta(hours=25)), now + ) + (segment,) = data.segments + assert len(segment.import_price) == 100 + assert segment.import_price.end - segment.start == timedelta(hours=25) + # the repeated local hour 02:00-03:00 exists twice, with different offsets, both kept + stamps = [iso((start + Q * i).astimezone(BERLIN)) for i in range(8, 16)] + assert stamps[0].endswith("+02:00") + assert stamps[-1].endswith("+01:00") + + +async def test_tibber_dst_start_day_has_23_hours() -> None: + start = datetime(2026, 3, 29, 0, 0, tzinfo=BERLIN).astimezone(UTC) + rows = [ + {"start_time": iso((start + Q * i).astimezone(BERLIN)), "price": 0.2} for i in range(23 * 4) + ] + now = datetime(2026, 3, 29, 0, 30, tzinfo=BERLIN) + actions = StubActions(lambda _data: {"prices": {"Home": rows}}) + data = await action_source("tibber.price", actions, now=now).fetch_segments( + TimeRange(start=start, end=start + timedelta(hours=23)), now + ) + assert data.segments[0].import_price.end - start == timedelta(hours=23) + + +async def test_tibber_malformed_payloads_are_rejected() -> None: + for payload in ( + {"prices": {"Home": "nope"}}, + {"prices": {"Home": [{"price": 1}]}}, + {"prices": []}, + ): + actions = StubActions(lambda _data, p=payload: p) + with pytest.raises(MalformedPayloadError): + await action_source("tibber.price", actions).fetch_segments(window(), NOW) + + +async def test_a_window_clips_the_series_to_whole_overlapping_slots() -> None: + actions = StubActions( + lambda _data: tibber_response(datetime(2026, 10, 16, 8, tzinfo=BERLIN), 40) + ) + narrow = TimeRange( + start=datetime(2026, 10, 16, 10, 0, tzinfo=BERLIN), + end=datetime(2026, 10, 16, 11, 0, tzinfo=BERLIN), + ) + data = await action_source("tibber.price", actions).fetch_segments(narrow, NOW) + (segment,) = data.segments + assert len(segment.import_price) == 4 + assert segment.start == narrow.start.astimezone(UTC) + + +# --- Nord Pool (action per date, UTC, per MWh, slot end) ------------------------------- + +NORDPOOL_PARAMS: Mapping[str, str | list[str]] = {"config_entry": "01HXENTRY", "areas": ["SE3"]} + + +def nordpool_by_date(day17: list[dict[str, Any]] | None = None) -> StubActions: + first = fixture("nordpool_get_prices_for_date")["response"] + + def respond(data: Mapping[str, Any]) -> Mapping[str, Any]: + return first if data["date"] == "2026-10-16" else {"SE3": day17 or []} + + return StubActions(respond) + + +async def test_nordpool_calls_once_per_local_date_and_never_beyond_tomorrow() -> None: + actions = nordpool_by_date() + source = action_source("nordpool.price", actions, action_params=NORDPOOL_PARAMS) + await source.fetch_segments(window(72), NOW) # a long window must not ask for the 18th/19th + assert [(c[2]["date"], c[4]) for c in actions.calls] == [ + ("2026-10-16", 0.0), + ("2026-10-17", 31.0), # the limiter's next slot is awaited for the second date + ] + assert all(c[2]["config_entry"] == "01HXENTRY" for c in actions.calls) + assert all(c[2]["areas"] == ["SE3"] for c in actions.calls) + assert "currency" not in actions.calls[0][2] # optional and not configured + + +async def test_nordpool_prices_are_divided_by_1000_and_the_slot_length_is_end_minus_start() -> None: + actions = nordpool_by_date() + source = action_source("nordpool.price", actions, action_params=NORDPOOL_PARAMS) + data = await source.fetch_segments(window(24, datetime(2026, 10, 16, 0, 0, tzinfo=BERLIN)), NOW) + (segment,) = data.segments + assert segment.price_includes == "spot_only" + assert segment.step == H + assert segment.start == datetime(2026, 10, 15, 22, tzinfo=UTC) + assert segment.import_price.values == pytest.approx((0.0455, 0.04125, -0.0035)) + + +async def test_nordpool_15_minute_day_after_the_transition_is_mixed_with_hourly() -> None: + t = datetime(2026, 10, 16, 22, 0, tzinfo=UTC) # local 17 Oct 00:00 + quarter = [ + {"start": iso(t + Q * i), "end": iso(t + Q * (i + 1)), "price": 100.0 + i} for i in range(8) + ] + actions = nordpool_by_date(quarter) + source = action_source("nordpool.price", actions, action_params=NORDPOOL_PARAMS) + data = await source.fetch_segments(window(48, MIDNIGHT), NOW) + steps = [s.step for s in data.segments] + assert steps == [H, Q] + assert data.segments[1].import_price.values[:2] == pytest.approx((0.1, 0.101)) + merged = await source.fetch(window(48, MIDNIGHT)) + assert merged.step == Q + + +async def test_nordpool_unpublished_tomorrow_returns_only_today() -> None: + source = action_source("nordpool.price", nordpool_by_date(), action_params=NORDPOOL_PARAMS) + data = await source.fetch_segments(window(48, MIDNIGHT), NOW) + assert data.known_end == datetime(2026, 10, 16, 1, 0, tzinfo=UTC) + + +async def test_nordpool_needs_the_config_entry_and_makes_no_call_without_it() -> None: + actions = nordpool_by_date() + source = action_source("nordpool.price", actions, action_params={"areas": ["SE3"]}) + with pytest.raises(MissingParamError) as err: + await source.fetch_segments(window(), NOW) + assert err.value.message_args == {"field": "config_entry"} + assert actions.calls == [] + + +async def test_nordpool_several_areas_need_a_series_key() -> None: + both = {"SE3": [], "SE4": []} + actions = StubActions(lambda _data: both) + source = action_source("nordpool.price", actions, action_params={"config_entry": "x"}) + with pytest.raises(AmbiguousSeriesError): + await source.fetch_segments(window(), NOW) + chosen = action_source( + "nordpool.price", actions, action_params={"config_entry": "x"}, series_key="SE4" + ) + assert (await chosen.fetch_segments(window(), NOW)).segments == () + + +async def test_nordpool_optional_fields_are_passed_when_configured() -> None: + actions = nordpool_by_date() + source = action_source( + "nordpool.price", + actions, + action_params={"config_entry": "x", "areas": "SE3", "currency": "EUR"}, + ) + await source.fetch_segments(window(2), NOW) + assert actions.calls[0][2] == { + "config_entry": "x", + "areas": "SE3", + "currency": "EUR", + "date": "2026-10-16", + } + + +def test_request_dates_follow_the_local_calendar_across_the_dst_change() -> None: + now = datetime(2026, 10, 24, 23, 30, tzinfo=BERLIN) + win = TimeRange(start=floor_to_step(now), end=floor_to_step(now) + timedelta(hours=30)) + assert request_dates(win, now, BERLIN, 48) == [ + date(2026, 10, 24), + date(2026, 10, 25), + date(2026, 10, 26), + ] + assert request_dates(win, now, BERLIN, 24) == [date(2026, 10, 24), date(2026, 10, 25)] + # a window that starts after the limit asks for nothing + late = TimeRange(start=now + timedelta(days=5), end=now + timedelta(days=6)) + assert request_dates(late, now, BERLIN, 24) == [] + + +# --- ENTSO-E (attribute, local str(datetime), spacing) --------------------------------- + +ENTSOE_ENTITY = "sensor.entsoe_average_electricity_price" + + +async def test_entsoe_fixture_hourly_spot_only() -> None: + source = attribute_source( + "entsoe.price", {"price": ENTSOE_ENTITY}, readings("entsoe_avg_price") + ) + data = await source.fetch_segments(window(24, datetime(2026, 10, 16, 0, 0, tzinfo=BERLIN)), NOW) + (segment,) = data.segments + assert segment.step == H + assert segment.price_includes == "spot_only" + assert segment.import_price.values == (0.0712, 0.069, 0.0668) + assert segment.start == datetime(2026, 10, 15, 22, tzinfo=UTC) + + +async def test_entsoe_user_statement_overrides_the_template_classification() -> None: + source = attribute_source( + "entsoe.price", + {"price": ENTSOE_ENTITY}, + readings("entsoe_avg_price"), + price_includes="all_in", + ) + assert source.price_includes == "all_in" + data = await source.fetch_segments(window(24, datetime(2026, 10, 16, 0, 0, tzinfo=BERLIN)), NOW) + assert data.segments[0].price_includes == "all_in" + + +async def test_entsoe_fifteen_minute_period_is_inferred_from_the_spacing() -> None: + base = datetime(2026, 10, 16, 0, 0, tzinfo=BERLIN) + rows = [{"time": str(base + Q * i), "price": 0.05 + 0.001 * i} for i in range(96)] + entity = EntityReading("0.05", {"unit_of_measurement": "EUR/kWh", "prices": rows}) + source = attribute_source("entsoe.price", {"price": ENTSOE_ENTITY}, {ENTSOE_ENTITY: entity}) + assert rows[0]["time"] == "2026-10-16 00:00:00+02:00" # the documented str(datetime) form + data = await source.fetch_segments(window(24, base), NOW) + assert data.segments[0].step == Q + assert len(data.segments[0].import_price) == 96 + + +async def test_entsoe_dst_end_day_with_str_datetime_offsets() -> None: + base = datetime(2026, 10, 25, 0, 0, tzinfo=BERLIN).astimezone(UTC) + rows = [ + {"time": str((base + H * i).astimezone(BERLIN)), "price": 0.05 + 0.001 * i} + for i in range(25) + ] + assert rows[2]["time"].endswith("+02:00") + assert rows[3]["time"] == "2026-10-25 02:00:00+01:00" + entity = EntityReading("0.05", {"prices": rows}) + now = datetime(2026, 10, 25, 0, 30, tzinfo=BERLIN) + source = attribute_source( + "entsoe.price", {"price": ENTSOE_ENTITY}, {ENTSOE_ENTITY: entity}, now=now + ) + data = await source.fetch_segments(window(25, base), now) + assert len(data.segments[0].import_price) == 25 + assert data.report.duplicates == 0 + + +async def test_entsoe_mwh_template_divides_by_1000_and_refuses_a_kwh_entity() -> None: + rows = [ + {"time": "2026-10-16 00:00:00+02:00", "price": 85.5}, + {"time": "2026-10-16 01:00:00+02:00", "price": 80.0}, + ] + mwh = EntityReading("85.5", {"unit_of_measurement": "EUR/MWh", "prices": rows}) + source = attribute_source("entsoe.price_mwh", {"price": ENTSOE_ENTITY}, {ENTSOE_ENTITY: mwh}) + data = await source.fetch_segments(window(24, datetime(2026, 10, 16, 0, 0, tzinfo=BERLIN)), NOW) + assert data.segments[0].import_price.values == pytest.approx((0.0855, 0.08)) + # the kWh template on an entity that says MWh would be a silent factor 1000: refused + wrong = attribute_source("entsoe.price", {"price": ENTSOE_ENTITY}, {ENTSOE_ENTITY: mwh}) + with pytest.raises(UnitMismatchError) as err: + await wrong.fetch_segments(window(24), NOW) + assert err.value.message_args["sensor_unit"] == "EUR/MWh" + + +async def test_entsoe_unavailable_entity_missing_attribute_and_empty_list() -> None: + entities = {"price": ENTSOE_ENTITY} + with pytest.raises(SourceUnavailableError): + await attribute_source("entsoe.price", entities, {}).fetch_segments(window(), NOW) + bare = {ENTSOE_ENTITY: EntityReading("unknown", {})} + with pytest.raises(MalformedPayloadError): + await attribute_source("entsoe.price", entities, bare).fetch_segments(window(), NOW) + empty = {ENTSOE_ENTITY: EntityReading("0.1", {"prices": []})} + data = await attribute_source("entsoe.price", entities, empty).fetch_segments(window(), NOW) + assert data.segments == () # published, but nothing yet: no error + + +async def test_a_required_role_without_an_entity_is_reported() -> None: + source = attribute_source("entsoe.price", {}, readings("entsoe_avg_price")) + with pytest.raises(MissingEntityError): + await source.fetch_segments(window(), NOW) + + +# --- EPEX Spot (attribute, local ISO, end_time, unit literal) -------------------------- + + +async def test_epex_total_price_mixed_hourly_and_quarter_hour_slots() -> None: + entity = "sensor.epex_spot_total_price" + source = attribute_source( + "epex_spot.total_price", {"price": entity}, readings("epex_spot_total_price") + ) + data = await source.fetch_segments(window(24, datetime(2026, 10, 16, 0, 0, tzinfo=BERLIN)), NOW) + hourly, quarter = data.segments + assert (hourly.step, hourly.import_price.values) == (H, (0.2631, 0.2587)) + assert (quarter.step, quarter.import_price.values) == (Q, (0.2561, 0.2549)) + assert source.price_includes == "all_in" + assert hourly.price_includes == "all_in" + + +async def test_epex_market_price_template_is_spot_only() -> None: + entity = "sensor.epex_spot_market_price" + source = attribute_source( + "epex_spot.market_price", + {"price": entity}, + readings("epex_spot_total_price") + | {entity: readings("epex_spot_total_price")["sensor.epex_spot_total_price"]}, + ) + assert source.price_includes == "spot_only" + data = await source.fetch_segments(window(24, datetime(2026, 10, 16, 0, 0, tzinfo=BERLIN)), NOW) + assert data.segments[0].price_includes == "spot_only" + + +async def test_epex_gbp_symbol_is_accepted_by_the_unit_check() -> None: + attrs = dict(readings("epex_spot_total_price")["sensor.epex_spot_total_price"].attributes) + attrs["unit_of_measurement"] = "£/kWh" + source = attribute_source( + "epex_spot.total_price", + {"price": "sensor.x"}, + {"sensor.x": EntityReading("0.2", attrs)}, + currency="GBP", + ) + data = await source.fetch_segments(window(24, datetime(2026, 10, 16, 0, 0, tzinfo=BERLIN)), NOW) + assert data.segments + + +# --- Octopus (two event entities merged, 30 minutes, GBP) ------------------------------- + +CURRENT = "event.octopus_energy_electricity_1234_5678_current_day_rates" +NEXT = "event.octopus_energy_electricity_1234_5678_next_day_rates" + + +async def test_octopus_merges_current_and_next_day_rates() -> None: + source = attribute_source( + "octopus_energy.rates", + {"current_day_rates": CURRENT, "next_day_rates": NEXT}, + readings("octopus_rates"), + tz=LONDON, + currency="GBP", + ) + win = TimeRange( + start=datetime(2026, 10, 15, 23, 0, tzinfo=UTC), + end=datetime(2026, 10, 17, 23, 0, tzinfo=UTC), + ) + data = await source.fetch_segments(win, NOW) + today, tomorrow = data.segments # 00:00-01:30 today, 00:00-01:00 tomorrow: two runs + assert today.step == tomorrow.step == timedelta(minutes=30) + assert today.price_includes == "all_in" + assert today.import_price.values == (0.1245, 0.1302, 0.1519) + assert tomorrow.import_price.values == (0.101, 0.0955) + assert data.known_end == datetime(2026, 10, 17, 0, 0, tzinfo=UTC) + + +async def test_octopus_without_the_next_day_entity_still_reads_the_current_day() -> None: + source = attribute_source( + "octopus_energy.rates", + {"current_day_rates": CURRENT}, + readings("octopus_rates"), + tz=LONDON, + currency="GBP", + ) + win = TimeRange( + start=datetime(2026, 10, 15, 23, 0, tzinfo=UTC), + end=datetime(2026, 10, 17, 23, 0, tzinfo=UTC), + ) + data = await source.fetch_segments(win, NOW) + assert len(data.segments) == 1 + + +async def test_octopus_event_entity_before_its_first_event_has_no_rates() -> None: + r = readings("octopus_rates") + r[NEXT] = EntityReading("unknown", {"event_types": ["x"]}) + source = attribute_source( + "octopus_energy.rates", + {"current_day_rates": CURRENT, "next_day_rates": NEXT}, + r, + tz=LONDON, + currency="GBP", + ) + win = TimeRange( + start=datetime(2026, 10, 15, 23, 0, tzinfo=UTC), + end=datetime(2026, 10, 17, 23, 0, tzinfo=UTC), + ) + data = await source.fetch_segments(win, NOW) + assert data.known_end == datetime(2026, 10, 16, 0, 30, tzinfo=UTC) + + +async def test_octopus_next_day_published_in_a_different_slot_length_makes_a_new_segment() -> None: + r = readings("octopus_rates") + r[NEXT] = EntityReading( + "x", + { + "rates": [ + { + "start": "2026-10-17T00:00:00+01:00", + "end": "2026-10-17T01:00:00+01:00", + "value_inc_vat": 0.1, + } + ] + }, + ) + source = attribute_source( + "octopus_energy.rates", + {"current_day_rates": CURRENT, "next_day_rates": NEXT}, + r, + tz=LONDON, + currency="GBP", + ) + win = TimeRange( + start=datetime(2026, 10, 15, 23, 0, tzinfo=UTC), + end=datetime(2026, 10, 17, 23, 0, tzinfo=UTC), + ) + data = await source.fetch_segments(win, NOW) + assert [s.step for s in data.segments] == [timedelta(minutes=30), H] + + +# --- generic ---------------------------------------------------------------------------- + + +async def test_generic_price_list_quarter_hours() -> None: + entity = "sensor.my_price_list" + source = attribute_source( + "generic.price_list", {"price": entity}, readings("generic_price_list") + ) + data = await source.fetch_segments(window(24, datetime(2026, 10, 16, 0, 0, tzinfo=BERLIN)), NOW) + (segment,) = data.segments + assert (segment.step, segment.import_price.values) == (Q, (0.31, 0.3, 0.29)) + + +# --- the PriceSource protocol ----------------------------------------------------------- + + +async def test_fetch_without_data_is_an_empty_series_at_the_window_start() -> None: + actions = StubActions(lambda _data: {"prices": {}}) + out = await action_source("tibber.price", actions).fetch(window()) + assert len(out) == 0 + assert out.start == window().start + + +async def test_finest_series_holds_coarse_prices_over_finer_slots() -> None: + entity = "sensor.epex_spot_total_price" + source = attribute_source( + "epex_spot.total_price", {"price": entity}, readings("epex_spot_total_price") + ) + series = await source.fetch(window(24, datetime(2026, 10, 16, 0, 0, tzinfo=BERLIN))) + assert series.step == Q + assert series.import_price.values[:4] == (0.2631,) * 4 + assert series.import_price.values[8:10] == (0.2561, 0.2549) + again = finest_series("x", "all_in", [], window()) + assert len(again) == 0 + + +# --- construction guards ---------------------------------------------------------------- + + +def test_the_engine_refuses_templates_it_cannot_serve() -> None: + binding = SourceBinding(tz=BERLIN) + with pytest.raises(ValueError, match="ActionCaller"): + TemplatePriceSource(template("tibber.price"), binding, clock=lambda: NOW) + with pytest.raises(ValueError, match="EntityReader"): + TemplatePriceSource(template("entsoe.price"), binding, clock=lambda: NOW) + + +# --- price entity only (no template) ---------------------------------------------------- + + +async def test_current_price_source_is_one_slot_from_the_entity_state() -> None: + entity = {"sensor.p": EntityReading("0.25", {"unit_of_measurement": "EUR/kWh"})} + source = CurrentPriceSource( + "sensor.p", reader_of(entity), price_includes="all_in", clock=lambda: NOW + ) + data = await source.fetch_segments(window(), NOW) + (segment,) = data.segments + assert segment.import_price.values == (0.25,) + assert segment.start == floor_to_step(NOW) + assert source.watched_entities == ("sensor.p",) + assert (await source.fetch(window())).import_price.values == (0.25,) + + +async def test_current_price_source_converts_mwh_and_rejects_bad_states() -> None: + mwh = {"sensor.p": EntityReading("85.0", {"unit_of_measurement": "EUR/MWh"})} + data = await CurrentPriceSource( + "sensor.p", reader_of(mwh), price_includes="spot_only", clock=lambda: NOW + ).fetch_segments(window(), NOW) + assert data.segments[0].import_price.values == (0.085,) + for reading in (None, EntityReading("unknown", {})): + source = CurrentPriceSource( + "sensor.p", reader_of({"sensor.p": reading}), price_includes="all_in", clock=lambda: NOW + ) + with pytest.raises(SourceUnavailableError): + await source.fetch_segments(window(), NOW) + + +# --- delivery day in the market's zone, currency guard (review M4, m2) ------------------ + + +async def test_nordpool_dates_are_cet_delivery_days_not_the_sites_days() -> None: + """A site in London at 23:30 local on 16 Oct is already in the CET day 17 Oct.""" + now = datetime(2026, 10, 16, 22, 30, tzinfo=UTC) + actions = nordpool_by_date() + source = action_source( + "nordpool.price", actions, now=now, tz=LONDON, action_params=NORDPOOL_PARAMS + ) + win = TimeRange(start=floor_to_step(now), end=floor_to_step(now) + timedelta(hours=48)) + await source.fetch_segments(win, now) + assert [c[2]["date"] for c in actions.calls] == ["2026-10-17", "2026-10-18"] + assert source.delivery_tz is not None + assert str(source.delivery_tz) == "Europe/Berlin" + + +async def test_templates_without_a_date_zone_have_no_delivery_zone() -> None: + assert action_source("tibber.price", StubActions(lambda _d: {})).delivery_tz is None + entity = "sensor.entsoe_average_electricity_price" + assert attribute_source("entsoe.price", {"price": entity}, {}).delivery_tz is None + + +async def test_prices_in_another_currency_than_the_region_are_refused() -> None: + # the template's own currency (Octopus is GBP) against a euro region + source = attribute_source( + "octopus_energy.rates", + {"current_day_rates": CURRENT}, + readings("octopus_rates"), + tz=LONDON, + ) + with pytest.raises(CurrencyMismatchError) as err: + await source.fetch_segments(window(), NOW) + assert err.value.message_args == {"source_currency": "GBP", "region_currency": "EUR"} + assert err.value.key == "tariff.error.currency_mismatch" + assert isinstance(err.value, UnitMismatchError) + + +async def test_a_sensor_unit_in_another_currency_is_refused() -> None: + rows = [{"time": "2026-10-16 00:00:00+02:00", "price": 0.1}] + entity = EntityReading("0.1", {"unit_of_measurement": "SEK/kWh", "prices": rows}) + source = attribute_source("entsoe.price", {"price": ENTSOE_ENTITY}, {ENTSOE_ENTITY: entity}) + with pytest.raises(CurrencyMismatchError): + await source.fetch_segments(window(24, MIDNIGHT), NOW) + # a symbol maps to its code: EPEX's euro sign is EUR + epex = readings("epex_spot_total_price") + ok = attribute_source("epex_spot.total_price", {"price": "sensor.epex_spot_total_price"}, epex) + assert (await ok.fetch_segments(window(24, MIDNIGHT), NOW)).segments + + +async def test_a_currency_field_for_the_action_must_match_the_region() -> None: + actions = nordpool_by_date() + source = action_source( + "nordpool.price", + actions, + action_params={"config_entry": "x", "currency": "SEK"}, + ) + with pytest.raises(CurrencyMismatchError): + await source.fetch_segments(window(), NOW) + assert actions.calls == [] + same = action_source( + "nordpool.price", actions, action_params={"config_entry": "x", "currency": "eur"} + ) + await same.fetch_segments(window(2), NOW) + assert actions.calls diff --git a/tests/tariff/test_parse.py b/tests/tariff/test_parse.py new file mode 100644 index 0000000..9cea91d --- /dev/null +++ b/tests/tariff/test_parse.py @@ -0,0 +1,349 @@ +# SPDX-License-Identifier: Apache-2.0 +"""Parsing of price lists: timestamps, numbers, paths, normalising and segmenting.""" + +from __future__ import annotations + +from datetime import UTC, datetime, timedelta + +import pytest + +from suncore.core.series import SeriesUnit, TimeSeries +from suncore.tariff.errors import AmbiguousSeriesError, MalformedPayloadError +from suncore.tariff.parse import ( + RawSlot, + build_segments, + clip_series, + expand_path, + infer_step, + normalise, + parse_number, + parse_timestamp, + select_series, + slots_from_mapping, + slots_from_records, + walk, +) +from suncore.templates.models import SeriesFields +from tests.tariff.helpers import BERLIN + +H = timedelta(hours=1) +Q = timedelta(minutes=15) + + +def utc(*args: int) -> datetime: + return datetime(*args, tzinfo=UTC) + + +# --- timestamps ------------------------------------------------------------------------- + + +@pytest.mark.parametrize( + ("text", "expected"), + [ + # ENTSO-E: str(datetime) with a space (research: coordinator.py:250-256) + ("2026-10-16 00:00:00+02:00", utc(2026, 10, 15, 22)), + # EPEX Spot / Octopus: local ISO 8601 + ("2026-10-16T00:00:00+02:00", utc(2026, 10, 15, 22)), + # Nord Pool: UTC +00:00 + ("2026-10-15T22:00:00+00:00", utc(2026, 10, 15, 22)), + # Tibber: milliseconds and Z + ("2026-10-16T00:00:00.000+02:00", utc(2026, 10, 15, 22)), + ("2026-10-15T22:00:00Z", utc(2026, 10, 15, 22)), + (" 2026-10-16 00:00:00+02:00 ", utc(2026, 10, 15, 22)), + ], +) +def test_timestamps_are_parsed_to_utc(text: str, expected: datetime) -> None: + assert parse_timestamp(text) == expected + assert parse_timestamp(text).tzinfo is UTC + + +def test_datetime_objects_are_accepted() -> None: + assert parse_timestamp(datetime(2026, 10, 16, tzinfo=BERLIN)) == utc(2026, 10, 15, 22) + + +@pytest.mark.parametrize( + "bad", + [ + "2026-10-16 00:00:00", + "yesterday", + "", + None, + 5, + datetime.fromisoformat("2026-01-01T00:00:00"), + ], +) +def test_a_timestamp_without_offset_or_text_is_malformed(bad: object) -> None: + with pytest.raises(MalformedPayloadError): + parse_timestamp(bad) + + +@pytest.mark.parametrize( + ("raw", "expected"), + [(1, 1.0), (0.25, 0.25), ("0.5", 0.5), (" -3.5 ", -3.5), ("1e-3", 0.001)], +) +def test_numbers(raw: object, expected: float) -> None: + assert parse_number(raw) == expected + + +@pytest.mark.parametrize("raw", [None, True, "n/a", "", float("nan"), float("inf"), "nan", [], {}]) +def test_unreadable_numbers_are_none(raw: object) -> None: + assert parse_number(raw) is None + + +# --- paths ------------------------------------------------------------------------------ + + +def test_walk_follows_dotted_keys_and_rejects_a_missing_one() -> None: + assert walk({"a": {"b": [1]}}, "a.b") == [1] + with pytest.raises(MalformedPayloadError): + walk({"a": {}}, "a.b") + with pytest.raises(MalformedPayloadError): + walk({"a": 1}, "a.b") + + +def test_star_fans_out_over_a_mapping() -> None: + payload = {"prices": {"Home": [1], "Cabin": [2]}} + assert expand_path(payload, "prices.*") == [("Home", [1]), ("Cabin", [2])] + assert expand_path({"SE3": [3]}, "*") == [("SE3", [3])] + assert expand_path({"other": 1}, "prices.*") == [] # nothing there: not an error + + +def test_a_path_through_a_non_object_is_malformed() -> None: + with pytest.raises(MalformedPayloadError): + expand_path({"prices": [1]}, "prices.*") + + +def test_select_series_the_only_one_or_the_named_one() -> None: + assert select_series([("Home", [1])], None) == [1] + assert select_series([], None) is None + two = [("Home", [1]), ("Cabin", [2])] + assert select_series(two, "Cabin") == [2] + assert select_series(two, "cabin") == [2] # area codes are case-insensitive + assert select_series([], "Home") is None + + +def test_several_series_without_a_key_are_ambiguous() -> None: + with pytest.raises(AmbiguousSeriesError) as err: + select_series([("Home", [1]), ("Cabin", [2])], None) + assert err.value.message_args["available"] == "Cabin, Home" + + +def test_an_unknown_key_is_malformed() -> None: + with pytest.raises(MalformedPayloadError): + select_series([("Home", [1])], "Cabin") + + +# --- records and mappings --------------------------------------------------------------- + +TIBBER = SeriesFields(timestamp_field="start_time", value_field="price", value_unit="EUR/kWh") +NORDPOOL = SeriesFields( + timestamp_field="start", end_field="end", value_field="price", value_unit="EUR/MWh" +) + + +def test_records_with_a_missing_or_text_value_become_gaps() -> None: + slots, bad = slots_from_records( + [ + {"start_time": "2026-10-16T00:00:00+02:00", "price": 0.1}, + {"start_time": "2026-10-16T00:15:00+02:00", "price": None}, + {"start_time": "2026-10-16T00:30:00+02:00", "price": "x"}, + {"start_time": "2026-10-16T00:45:00+02:00"}, + ], + TIBBER, + ) + assert [s.value for s in slots] == [0.1, None, None, None] + assert bad == 3 + + +def test_records_need_a_timestamp_and_a_list() -> None: + with pytest.raises(MalformedPayloadError): + slots_from_records([{"price": 1}], TIBBER) + with pytest.raises(MalformedPayloadError): + slots_from_records("nope", TIBBER) + with pytest.raises(MalformedPayloadError): + slots_from_records(["nope"], TIBBER) + + +def test_records_with_an_end_field() -> None: + slots, _ = slots_from_records( + [{"start": "2026-10-15T22:00:00+00:00", "end": "2026-10-15T23:00:00+00:00", "price": 45.5}], + NORDPOOL, + ) + assert slots == [RawSlot(utc(2026, 10, 15, 22), utc(2026, 10, 15, 23), 45.5)] + + +def test_mapping_shape() -> None: + slots, bad = slots_from_mapping( + {"2026-10-16T00:00:00+02:00": 0.1, "2026-10-16T01:00:00+02:00": "?"} + ) + assert [s.value for s in slots] == [0.1, None] + assert bad == 1 + with pytest.raises(MalformedPayloadError): + slots_from_mapping([1]) + + +# --- normalise -------------------------------------------------------------------------- + + +def test_normalise_sorts_and_the_later_duplicate_wins() -> None: + slots, report = normalise( + [ + RawSlot(utc(2026, 1, 1, 1), None, 2.0), + RawSlot(utc(2026, 1, 1, 0), None, 1.0), + RawSlot(utc(2026, 1, 1, 1), None, 3.0), + ] + ) + assert [(s.start.hour, s.value) for s in slots] == [(0, 1.0), (1, 3.0)] + assert report.duplicates == 1 + assert report.points == 2 + + +def test_normalise_drops_overlapping_and_inverted_slots() -> None: + a = RawSlot(utc(2026, 1, 1, 0), utc(2026, 1, 1, 1), 1.0) + overlap = RawSlot(utc(2026, 1, 1, 0, 30), utc(2026, 1, 1, 1, 30), 2.0) + inverted = RawSlot(utc(2026, 1, 1, 5), utc(2026, 1, 1, 4), 3.0) + slots, report = normalise([a, overlap, inverted], unreadable=2) + assert slots == [a] + assert report.overlaps == 2 + assert report.unreadable_values == 2 + + +# --- segments --------------------------------------------------------------------------- + + +def slot(start: datetime, minutes: int | None, value: float | None) -> RawSlot: + end = None if minutes is None else start + timedelta(minutes=minutes) + return RawSlot(start, end, value) + + +def test_infer_step_uses_the_most_common_distance_and_prefers_the_finer_on_a_tie() -> None: + t0 = utc(2026, 1, 1) + assert infer_step([t0, t0 + Q, t0 + 2 * Q], None) == Q + assert infer_step([t0, t0 + H], None) == H + assert infer_step([t0, t0 + Q, t0 + Q + H], None) == Q # tie: finer + assert infer_step([t0], Q) == Q + assert infer_step([t0], None) == H + + +def test_explicit_slots_hourly_become_one_segment_with_the_mwh_conversion() -> None: + t0 = utc(2026, 10, 15, 22) + slots = [slot(t0 + H * i, 60, 45.0 * (i + 1)) for i in range(3)] + (seg,) = build_segments(slots, divisor=1000.0, resolution=None) + assert seg.step == H + assert seg.unit is SeriesUnit.PRICE + assert seg.values == (0.045, 0.09, 0.135) + + +def test_explicit_slots_mixed_15_and_60_minutes_make_two_segments() -> None: + t0 = utc(2026, 10, 15, 22) + slots = [ + slot(t0, 60, 1.0), + slot(t0 + H, 60, 2.0), + slot(t0 + 2 * H, 15, 3.0), + slot(t0 + 2 * H + Q, 15, 4.0), + ] + hourly, quarter = build_segments(slots, divisor=1.0, resolution=None) + assert (hourly.step, hourly.values) == (H, (1.0, 2.0)) + assert (quarter.step, quarter.start, quarter.values) == (Q, t0 + 2 * H, (3.0, 4.0)) + + +def test_explicit_slots_with_a_hole_start_a_new_segment_and_no_value_is_invented() -> None: + t0 = utc(2026, 10, 15, 22) + slots = [slot(t0, 60, 1.0), slot(t0 + 2 * H, 60, 3.0)] + first, second = build_segments(slots, divisor=1.0, resolution=None) + assert first.end == t0 + H + assert second.start == t0 + 2 * H + + +def test_inferred_hourly_with_a_gap_has_none_in_the_gap() -> None: + t0 = utc(2026, 10, 15, 22) + slots = [slot(t0, None, 1.0), slot(t0 + H, None, 2.0), slot(t0 + 3 * H, None, 4.0)] + (seg,) = build_segments(slots, divisor=1.0, resolution=None) + assert seg.values == (1.0, 2.0, None, 4.0) + + +def test_inferred_quarter_hours_then_hourly_tomorrow() -> None: + t0 = utc(2026, 10, 15, 22) + slots = [slot(t0 + Q * i, None, float(i)) for i in range(8)] + slots += [slot(t0 + 2 * H + H * i, None, 10.0 + i) for i in range(3)] + quarter, hourly = build_segments(slots, divisor=1.0, resolution=None) + assert quarter.step == Q + assert len(quarter) == 8 + assert hourly.step == H + assert hourly.values == (10.0, 11.0, 12.0) + + +def test_inferred_template_resolution_wins_for_a_single_point() -> None: + (seg,) = build_segments([slot(utc(2026, 1, 1), None, 1.0)], divisor=1.0, resolution=Q) + assert seg.step == Q + + +def test_irregular_timestamps_are_malformed_never_guessed() -> None: + t0 = utc(2026, 1, 1) + slots = [ + slot(t0, None, 1.0), + slot(t0 + H, None, 2.0), + slot(t0 + 2 * H, None, 3.0), + slot(t0 + 2 * H + timedelta(minutes=20), None, 4.0), + ] + with pytest.raises(MalformedPayloadError): + build_segments(slots, divisor=1.0, resolution=None) + + +def test_no_slots_no_segments() -> None: + assert build_segments([], divisor=1.0, resolution=None) == () + + +def test_dst_days_have_23_and_25_hours() -> None: + """Europe/Berlin: 2026-03-29 has 23 h, 2026-10-25 has 25 h (hourly local slots).""" + for day, hours in ( + (datetime(2026, 3, 29, tzinfo=UTC), 23), + (datetime(2026, 10, 25, tzinfo=UTC), 25), + ): + start = datetime.combine(day.date(), datetime.min.time(), tzinfo=BERLIN) + end = datetime.combine(day.date() + timedelta(days=1), datetime.min.time(), tzinfo=BERLIN) + assert end.astimezone(UTC) - start.astimezone(UTC) == timedelta(hours=hours) + slots = [] + t = start.astimezone(UTC) + while t < end.astimezone(UTC): + slots.append(slot(t, None, 0.1)) + t += H + (seg,) = build_segments(slots, divisor=1.0, resolution=None) + assert len(seg) == hours + assert seg.end == end.astimezone(UTC) + + +def test_the_repeated_local_hour_of_the_25_hour_day_keeps_both_slots() -> None: + """ENTSO-E prints `str(datetime)` with the offset: 02:00+02:00 and 02:00+01:00 differ.""" + slots = [ + slot(parse_timestamp("2026-10-25 01:00:00+02:00"), None, 1.0), + slot(parse_timestamp("2026-10-25 02:00:00+02:00"), None, 2.0), + slot(parse_timestamp("2026-10-25 02:00:00+01:00"), None, 3.0), + slot(parse_timestamp("2026-10-25 03:00:00+01:00"), None, 4.0), + ] + normalised, report = normalise(slots) + (seg,) = build_segments(normalised, divisor=1.0, resolution=None) + assert seg.values == (1.0, 2.0, 3.0, 4.0) + assert report.duplicates == 0 + + +# --- clip ------------------------------------------------------------------------------- + + +def series(start: datetime, n: int, step: timedelta = H) -> TimeSeries: + return TimeSeries( + start=start, step=step, values=tuple(float(i) for i in range(n)), unit=SeriesUnit.PRICE + ) + + +def test_clip_keeps_whole_slots_that_overlap_the_window() -> None: + t0 = utc(2026, 1, 1) + s = series(t0, 6) + clipped = clip_series(s, t0 + H + timedelta(minutes=30), t0 + 4 * H - timedelta(minutes=30)) + assert clipped is not None + assert (clipped.start, clipped.values) == (t0 + H, (1.0, 2.0, 3.0)) + assert clip_series(s, t0 + 7 * H, t0 + 8 * H) is None + assert clip_series(s, t0 - 2 * H, t0) is None + whole = clip_series(s, t0 - H, t0 + 10 * H) + assert whole is not None + assert whole.values == s.values diff --git a/tests/tariff/test_pricing.py b/tests/tariff/test_pricing.py new file mode 100644 index 0000000..24f4c2d --- /dev/null +++ b/tests/tariff/test_pricing.py @@ -0,0 +1,189 @@ +# SPDX-License-Identifier: Apache-2.0 +"""Price formula on spot sources, the export side and the negative-price rule.""" + +from __future__ import annotations + +from datetime import UTC, datetime, timedelta + +import pytest + +from suncore.core.config import ExportTariff, ExportTier +from suncore.core.series import Grid, PriceSeries, SeriesUnit, TimeSeries +from suncore.core.tariff import GridFeeWindow, PriceFormula, TouWindow +from suncore.tariff import ( + ExportConfigError, + ExportTiersError, + apply_import_formula, + export_base_price, + planning_prices, +) +from suncore.templates.models import NegativePriceRule +from tests.tariff.helpers import BERLIN, prices + +T0 = datetime(2026, 10, 16, 0, 0, tzinfo=BERLIN).astimezone(UTC) +Q = timedelta(minutes=15) +H = timedelta(hours=1) +RULE = NegativePriceRule.NO_REMUNERATION + + +def grid(count: int, start: datetime = T0) -> Grid: + return Grid(start=start, step=Q, count=count) + + +def run( + segments: list[PriceSeries], + count: int, + *, + formula: PriceFormula | None = None, + export: float = 0.08, + rule: NegativePriceRule = RULE, +) -> tuple[PriceSeries, int]: + return planning_prices( + segments, grid(count), formula=formula, export_price=export, rule=rule, tz=BERLIN + ) + + +# --- formula ---------------------------------------------------------------------------- + +FORMULA = PriceFormula(grid_fee=0.10, levies=0.05, margin=0.02, vat_pct=19) + + +def test_a_spot_source_gets_the_formula_at_the_slot_start() -> None: + spot = prices(T0, [0.10, 0.20, None, -0.05], includes="spot_only").import_price + end, includes = apply_import_formula(spot, "spot_only", FORMULA, BERLIN) + assert includes == "all_in" + assert end.values[0] == pytest.approx((0.10 + 0.10 + 0.05 + 0.02) * 1.19) + assert end.values[2] is None + assert end.values[3] == pytest.approx((-0.05 + 0.17) * 1.19) + + +def test_an_all_in_source_never_gets_the_formula_even_if_one_is_configured() -> None: + series = prices(T0, [0.30, 0.31], includes="all_in").import_price + end, includes = apply_import_formula(series, "all_in", FORMULA, BERLIN) + assert end is series + assert includes == "all_in" + + +def test_a_spot_source_without_a_formula_stays_spot_only() -> None: + series = prices(T0, [0.10], includes="spot_only").import_price + end, includes = apply_import_formula(series, "spot_only", None, BERLIN) + assert end is series + assert includes == "spot_only" + + +def test_time_variable_grid_fee_is_judged_in_local_time() -> None: + formula = PriceFormula( + grid_fee=0.10, + grid_fee_windows=(GridFeeWindow(window=TouWindow(start="22:00", end="06:00"), fee=0.03),), + ) + # 21:45 local (CEST) = 19:45Z, 22:00 local = 20:00Z + start = datetime(2026, 10, 16, 21, 45, tzinfo=BERLIN) + spot = prices(start, [0.0, 0.0], includes="spot_only").import_price + end, _ = apply_import_formula(spot, "spot_only", formula, BERLIN) + assert end.values == pytest.approx((0.10, 0.03)) + + +# --- export side ------------------------------------------------------------------------ + + +def test_export_fixed_none_and_tiered() -> None: + assert export_base_price(ExportTariff(kind="fixed", fixed_price=0.081), None) == 0.081 + assert export_base_price(ExportTariff(kind="none"), None) == 0.0 + tiered = ExportTariff( + kind="tiered", + tiers=(ExportTier(up_to_kwp=10, price=0.08), ExportTier(price=0.07)), + ) + assert export_base_price(tiered, 17.0) == pytest.approx((10 * 0.08 + 7 * 0.07) / 17) + assert export_base_price(tiered, 8.0) == pytest.approx(0.08) + + +def test_tiered_export_needs_the_plant_size_and_tiers_that_cover_it() -> None: + tiered = ExportTariff(kind="tiered", tiers=(ExportTier(up_to_kwp=10, price=0.08),)) + with pytest.raises(ExportConfigError): + export_base_price(tiered, None) + with pytest.raises(ExportTiersError) as err: + export_base_price(tiered, 17.0) # the tiers end at 10 kWp: no rate is guessed + assert err.value.key == "tariff.error.export_tiers" + assert err.value.message_args == {"kwp": 17.0} + assert isinstance(err.value, ExportConfigError) + + +# --- planning prices -------------------------------------------------------------------- + + +def test_negative_spot_price_zeroes_export_before_the_formula_hides_it() -> None: + """Spot -0.02 becomes a positive end price (grid fee, levies) but the grid operator pays + nothing in that slot: the rule looks at the spot price of a spot-only source.""" + series = prices(T0, [0.10, -0.02, 0.0, -0.001], includes="spot_only") + out, zeroed = run([series], 4, formula=FORMULA) + assert out.price_includes == "all_in" + assert out.import_price.values[1] == pytest.approx((-0.02 + 0.17) * 1.19) + assert out.import_price.values[1] > 0 + assert out.export_price is not None + assert out.export_price.values == (0.08, 0.0, 0.08, 0.0) + assert zeroed == 2 + + +def test_an_all_in_source_uses_the_import_price_as_the_negative_proxy() -> None: + series = prices(T0, [0.25, -0.01, 0.0], includes="all_in") + out, zeroed = run([series], 3) + assert out.import_price.values == (0.25, -0.01, 0.0) + assert out.export_price is not None + assert out.export_price.values == (0.08, 0.0, 0.08) # zero is not negative + assert zeroed == 1 + + +def test_without_the_rule_export_keeps_its_price_at_negative_prices() -> None: + series = prices(T0, [-0.05, 0.1], includes="spot_only") + for rule in (NegativePriceRule.NONE, NegativePriceRule.CURTAILMENT_REQUIRED): + out, zeroed = run([series], 2, rule=rule) + assert out.export_price is not None + assert out.export_price.values == (0.08, 0.08) + assert zeroed == 0 + + +def test_unknown_prices_stay_unknown_in_both_series() -> None: + series = prices(T0, [0.2, None, 0.2], includes="all_in") + out, _ = run([series], 5) + assert out.import_price.values == (0.2, None, 0.2, None, None) + assert out.export_price is not None + assert out.export_price.values == (0.08, None, 0.08, None, None) + + +def test_mixed_15_and_60_minute_segments_are_held_onto_the_grid() -> None: + hourly = prices(T0, [0.30, -0.10], step=H, includes="all_in") + quarter = prices(T0 + 2 * H, [0.20, 0.21], includes="all_in") + out, zeroed = run([hourly, quarter], 10) + assert out.import_price.values == (0.3,) * 4 + (-0.1,) * 4 + (0.2, 0.21) + assert zeroed == 4 + assert out.source_id == "t" + + +def test_a_source_with_its_own_export_prices_wins() -> None: + imp = prices(T0, [0.3, -0.2]).import_price + own = TimeSeries(start=T0, step=Q, values=(0.05, 0.04), unit=SeriesUnit.PRICE) + out, zeroed = run( + [PriceSeries(source_id="s", price_includes="all_in", import_price=imp, export_price=own)], 2 + ) + assert out.export_price is not None + assert out.export_price.values == (0.05, 0.04) # the source decides, the rule is not applied + assert zeroed == 0 + + +def test_no_segments_gives_unknown_prices_not_zeros() -> None: + out, zeroed = planning_prices( + [], grid(3), formula=None, export_price=0.08, rule=RULE, tz=BERLIN, source_id="x" + ) + assert out.source_id == "x" + assert out.import_price.values == (None, None, None) + assert out.export_price is not None + assert out.export_price.values == (None, None, None) + assert zeroed == 0 + + +def test_export_none_means_zero_not_unknown() -> None: + out, _ = run( + [prices(T0, [0.3, 0.3])], 2, export=export_base_price(ExportTariff(kind="none"), None) + ) + assert out.export_price is not None + assert out.export_price.values == (0.0, 0.0) diff --git a/tests/tariff/test_service.py b/tests/tariff/test_service.py new file mode 100644 index 0000000..4a1b050 --- /dev/null +++ b/tests/tariff/test_service.py @@ -0,0 +1,739 @@ +# SPDX-License-Identifier: Apache-2.0 +"""The tariff service: refresh decisions with injected time, caching, storing, serving.""" + +from __future__ import annotations + +import asyncio +from collections.abc import Iterable +from dataclasses import dataclass, field +from datetime import UTC, datetime, time, timedelta, tzinfo + +import pytest + +from suncore.core.config import ExportTariff, ExportTier +from suncore.core.series import PriceSeries, TimeRange, TimeSeries +from suncore.tariff import ( + ExportConfigError, + FixedPriceSource, + MalformedPayloadError, + ServiceSettings, + SourceThrottledError, + SourceUnavailableError, + TariffPlan, + TariffService, +) +from suncore.tariff.sources import SourceData, SourceKind +from suncore.templates.models import NegativePriceRule +from tests.tariff.helpers import BERLIN + +Q = timedelta(minutes=15) +H = timedelta(hours=1) +FIXED_EXPORT = ExportTariff(kind="fixed", fixed_price=0.08) + + +def local(day: int, hour: int, minute: int = 0) -> datetime: + return datetime(2026, 10, day, hour, minute, tzinfo=BERLIN) + + +class Clock: + def __init__(self, now: datetime) -> None: + self.now = now + + def __call__(self) -> datetime: + return self.now + + def advance(self, **kwargs: float) -> None: + self.now += timedelta(**kwargs) + + +def hourly(start: datetime, values: Iterable[float | None]) -> PriceSeries: + series = TimeSeries(start=start, step=H, values=tuple(values), unit="currency/kWh") # type: ignore[arg-type] + return PriceSeries(source_id="fake", price_includes="all_in", import_price=series) + + +@dataclass +class FakeSource: + """A dynamic source whose answer the test controls.""" + + segments: tuple[PriceSeries, ...] = () + error: Exception | None = None + kind: SourceKind = "dynamic" + uses_action: bool = True + price_includes: str = "all_in" + source_id: str = "fake" + watched_entities: tuple[str, ...] = ("sensor.price",) + delivery_tz: tzinfo | None = None + calls: list[datetime] = field(default_factory=list) + + async def fetch_segments(self, window: TimeRange, now: datetime) -> SourceData: # noqa: ARG002 + self.calls.append(now) + if self.error is not None: + raise self.error + return SourceData(segments=self.segments) + + +def day_prices(day: int, days: int = 1, value: float = 0.30) -> PriceSeries: + return hourly(local(day, 0), [value] * 24 * days) + + +class Store: + def __init__(self, *, fail: bool = False) -> None: + self.written: list[PriceSeries] = [] + self.fail = fail + + async def store_prices(self, prices: PriceSeries) -> int: + if self.fail: + msg = "disk full" + raise OSError(msg) + self.written.append(prices) + return len(prices) + + +def make( + source: FakeSource | FixedPriceSource, + now: datetime, + *, + store: Store | None = None, + export: ExportTariff = FIXED_EXPORT, + rule: NegativePriceRule = NegativePriceRule.NONE, + settings: ServiceSettings | None = None, + kwp: float | None = None, +) -> tuple[TariffService, Clock]: + clock = Clock(now) + plan = TariffPlan( + source=source, # type: ignore[arg-type] + export_tariff=export, + negative_rule=rule, + tz=BERLIN, + currency="EUR", + total_kwp=kwp, + ) + return TariffService(plan, clock=clock, store=store, settings=settings), clock + + +# --- when to refresh -------------------------------------------------------------------- + + +async def test_first_refresh_is_initial_then_nothing_is_due_until_the_interval() -> None: + source = FakeSource(segments=(day_prices(16, 2),)) + service, clock = make(source, local(16, 10, 7)) + assert service.due() == "initial" + result = await service.tick() + assert result is not None + assert result.ok + assert result.reason == "initial" + assert service.due() is None + clock.advance(minutes=59) + assert service.due() is None + clock.advance(minutes=1) + assert service.due() == "interval" + assert service.next_refresh() == clock.now + await service.tick() + assert len(source.calls) == 2 + + +async def test_tomorrow_is_asked_from_the_publication_time_every_poll_interval() -> None: + source = FakeSource(segments=(day_prices(16),)) # today only + service, clock = make(source, local(16, 12, 30)) + await service.refresh("initial") + assert not service.report(48).quality.has_tomorrow + assert service.next_refresh() == local(16, 13, 0) # publication time, before the hourly one + clock.now = local(16, 12, 59) + assert service.due() is None + clock.now = local(16, 13, 0) + assert service.due() == "tomorrow" + await service.tick() # still not published + clock.now = local(16, 13, 14) + assert service.due() is None # the poll interval (15 min) has not passed + clock.now = local(16, 13, 15) + assert service.due() == "tomorrow" + source.segments = (day_prices(16, 2),) + await service.tick() + assert service.report(48).quality.has_tomorrow + clock.now = local(16, 13, 40) + assert service.due() is None # covered: back to the hourly rhythm + assert service.next_refresh() == local(16, 14, 15) + + +async def test_static_sources_do_not_poll_for_tomorrow() -> None: + service, clock = make(FixedPriceSource(price=0.3), local(16, 14, 0)) + await service.refresh("initial") + clock.now = local(16, 14, 30) + assert service.due() is None + assert service.report().freshness.status == "static" + + +async def test_an_entity_change_refreshes_attribute_sources_at_once() -> None: + source = FakeSource(segments=(day_prices(16, 2),), uses_action=False) + service, clock = make(source, local(16, 10, 0)) + await service.refresh("initial") + clock.advance(minutes=5) + assert service.due() is None + service.notify_changed() + assert service.due() == "changed" + result = await service.tick() + assert result is not None + assert result.reason == "changed" + assert service.due() is None # the flag is cleared by a successful refresh + + +async def test_an_entity_change_does_not_hit_an_action_source_while_the_slot_is_known() -> None: + source = FakeSource(segments=(day_prices(16, 2),), uses_action=True) + service, clock = make(source, local(16, 10, 0)) + await service.refresh("initial") + clock.advance(minutes=15) + service.notify_changed() + assert service.due() is None # an action costs a request, the sensor changes every slot + clock.now = local(18, 0, 0) # the known prices ran out: now the change is worth a call + assert service.due() == "changed" + + +async def test_a_new_change_after_a_failed_first_fetch_does_not_wait_for_the_back_off() -> None: + source = FakeSource(error=SourceUnavailableError("cache empty"), uses_action=False) + service, clock = make(source, local(16, 10, 0)) + await service.refresh("initial") + assert service.due() is None # backing off; the change that caused the attempt is consumed + source.error = None + source.segments = (day_prices(16, 2),) + clock.advance(seconds=30) + service.notify_changed() # the entity arrived: a new change + assert service.due() == "changed" + + +async def test_a_failing_attribute_source_is_not_refetched_every_poll() -> None: + """M1: the dirty flag of a failed fetch used to stay set -> a fetch every 30 s.""" + source = FakeSource(error=MalformedPayloadError("bad"), uses_action=False) + service, clock = make(source, local(16, 10, 0)) + service.notify_changed() + await service.tick() # the first fetch fails + for _ in range(8): # four minutes of 30 s polls inside the five-minute back-off + clock.advance(seconds=30) + assert await service.tick() is None + assert len(source.calls) == 1 + clock.advance(seconds=60) + assert service.due() == "initial" # back-off over + + +async def test_changes_in_quick_succession_do_not_hammer_the_source() -> None: + source = FakeSource(segments=(day_prices(16, 2),), uses_action=False) + service, clock = make(source, local(16, 10, 0)) + await service.refresh("initial") + clock.advance(seconds=10) + service.notify_changed() + assert service.due() is None # fetched 10 s ago + clock.advance(seconds=20) + assert service.due() == "changed" + + +# --- failures --------------------------------------------------------------------------- + + +async def test_failures_back_off_exponentially_and_success_resets() -> None: + source = FakeSource(error=SourceUnavailableError("down")) + service, clock = make(source, local(16, 10, 0)) + first = await service.refresh("initial") + assert first is not None + assert not first.ok + assert first.error is not None + assert service.due() is None + clock.advance(minutes=5) + assert service.due() == "initial" + await service.refresh("initial") + clock.advance(minutes=9) + assert service.due() is None # second failure: 10 minutes + clock.advance(minutes=1) + assert service.due() == "initial" + source.error = None + source.segments = (day_prices(16, 2),) + ok = await service.refresh("initial") + assert ok is not None + assert ok.ok + assert service.report().freshness.last_error is None + assert service.next_refresh() == clock.now + H + + +async def test_back_off_is_capped_at_one_hour() -> None: + source = FakeSource(error=MalformedPayloadError("bad")) + service, clock = make(source, local(16, 10, 0)) + for _ in range(10): + await service.refresh("retry") + clock.advance(hours=2) + assert service._state.retry_at is not None + assert service._state.retry_at - (clock.now - timedelta(hours=2)) == H + + +async def test_a_failure_keeps_the_good_data_and_reports_the_error_key() -> None: + source = FakeSource(segments=(day_prices(16, 2),)) + service, clock = make(source, local(16, 10, 0)) + await service.refresh("initial") + source.error = MalformedPayloadError("bad", attribute="prices") + clock.advance(hours=1) + await service.tick() + report = service.report(24) + assert report.quality.known_slots == report.quality.slots # still served + assert report.freshness.last_error is not None + assert report.freshness.last_error.key == "tariff.error.malformed_payload" + assert report.freshness.last_error.args == {"attribute": "prices"} + assert report.freshness.status == "stale" + + +async def test_an_empty_answer_never_replaces_good_data() -> None: + source = FakeSource(segments=(day_prices(16, 2),)) + service, clock = make(source, local(16, 10, 0)) + await service.refresh("initial") + source.segments = () + clock.advance(hours=1) + result = await service.tick() + assert result is not None + assert not result.ok + assert service.report(24).quality.known_slots > 0 + + +async def test_a_throttled_call_is_not_a_failure() -> None: + source = FakeSource(segments=(day_prices(16, 2),)) + service, clock = make(source, local(16, 10, 0)) + await service.refresh("initial") + source.error = SourceThrottledError(40.0) + clock.advance(hours=1) + result = await service.tick() + assert result is not None + assert result.throttled + assert service._state.failures == 0 + assert service.report().freshness.last_error is None + assert service.next_refresh() == clock.now + timedelta(seconds=40) + clock.advance(seconds=39) + assert service.due() is None + clock.advance(seconds=1) + assert service.due() == "retry" + + +async def test_an_unexpected_exception_becomes_a_failure_not_a_crash() -> None: + source = FakeSource(error=RuntimeError("boom")) + service, _ = make(source, local(16, 10, 0)) + result = await service.refresh() + assert result is not None + assert not result.ok + assert result.error is not None + assert result.error.key == "tariff.error.action_failed" + + +async def test_reset_backoff_after_reconnect() -> None: + source = FakeSource(error=SourceUnavailableError("down")) + service, clock = make(source, local(16, 10, 0)) + await service.refresh("initial") + service.reset_backoff() + assert service.due() == "initial" + clock.advance(seconds=1) + assert service.report().freshness.last_error is not None # never succeeded: the error stays + + +async def test_a_refresh_in_progress_blocks_a_second_one() -> None: + gate = asyncio.Event() + + class Slow(FakeSource): + async def fetch_segments(self, window: TimeRange, now: datetime) -> SourceData: + await gate.wait() + return await super().fetch_segments(window, now) + + source = Slow(segments=(day_prices(16, 2),)) + service, _ = make(source, local(16, 10, 0)) + first = asyncio.create_task(service.refresh("initial")) + await asyncio.sleep(0) + assert await service.refresh("forced") is None + gate.set() + result = await first + assert result is not None + assert result.ok + + +# --- merging and serving ---------------------------------------------------------------- + + +async def test_slots_beyond_the_new_data_are_kept_when_a_source_forgets_tomorrow() -> None: + source = FakeSource(segments=(day_prices(16, 2),)) + service, clock = make(source, local(16, 10, 0)) + await service.refresh("initial") + source.segments = (hourly(local(16, 0), [0.40] * 24),) # today only, new values + clock.advance(hours=1) + await service.refresh() + report = service.report(48) + assert report.quality.has_tomorrow + prices = service.prices(48).import_price.values + assert prices[0] == 0.40 # new data wins where it has data + assert prices[-1] == 0.30 # tomorrow comes from the earlier fetch + + +async def test_the_series_is_at_least_24_hours_and_ends_with_the_known_prices() -> None: + now = local(16, 10, 7) + source = FakeSource(segments=(hourly(local(16, 10), [0.3] * 12),)) # 12 h known + service, _ = make(source, now) + await service.refresh("initial") + short = service.prices(48) + assert ( + len(short) == 24 * 4 + 1 + ) # 24 h from the quarter hour of "now" (10:00 -> 10:00 next day, +1) + assert short.import_price.values[: 12 * 4].count(None) == 0 + assert short.import_price.values[12 * 4 :].count(None) == len(short) - 12 * 4 + source.segments = (hourly(local(16, 10), [0.3] * 36),) + await service.refresh() + assert len(service.prices(48)) == 36 * 4 + assert len(service.prices(30)) == 30 * 4 + 1 # capped by the request + assert service.prices(48).step == Q + + +async def test_fixed_prices_fill_the_whole_request() -> None: + service, _ = make(FixedPriceSource(price=0.31), local(16, 10, 7)) + await service.refresh("initial") + out = service.prices(48) + assert len(out) >= 192 + assert set(out.import_price.values) == {0.31} + assert out.export_price is not None + assert set(out.export_price.values) == {0.08} + + +async def test_prices_before_any_fetch_are_unknown() -> None: + service, _ = make(FakeSource(), local(16, 10, 0)) + out = service.prices(48) + assert len(out) == 24 * 4 + assert set(out.import_price.values) == {None} + assert service.report().freshness.status == "missing" + assert service.report().freshness.next_refresh_at is not None + + +# --- no known value, partial data, overlapping tails (review M2, M3) -------------------- + + +def all_unknown(start: datetime, hours: int) -> PriceSeries: + return hourly(start, [None] * hours) + + +async def test_a_fetch_without_any_known_price_is_a_failure_and_keeps_good_data() -> None: + source = FakeSource(segments=(day_prices(16, 2),)) # 48 good hours + service, clock = make(source, local(16, 10, 0)) + await service.refresh("initial") + source.segments = (all_unknown(local(16, 0), 48),) + clock.advance(hours=1) + result = await service.tick() + assert result is not None + assert not result.ok + after = service.prices(48) + known = [v for v in after.import_price.values if v is not None] + assert known + assert set(known) == {0.30} + assert len(known) >= 36 * 4 # the 48 good hours are still served + assert service.report(48).freshness.last_error is not None + + +async def test_unknown_slots_of_a_fetch_are_filled_from_the_earlier_data_and_reported() -> None: + source = FakeSource(segments=(day_prices(16, 2),)) + service, clock = make(source, local(16, 10, 0)) + await service.refresh("initial") + values: list[float | None] = [0.40] * 48 + values[14:18] = [None] * 4 # 14:00-18:00 missing in the new answer + source.segments = (hourly(local(16, 0), values),) + clock.advance(hours=1) + await service.refresh() + report = service.report(48) + assert report.quality.carried_slots == 4 + by_hour = {s.start.astimezone(BERLIN).hour: s.import_price for s in report.slots[:40]} + assert by_hour[15] == 0.30 # carried over + assert by_hour[12] == 0.40 # new data wins + + +async def test_the_old_tail_starts_at_the_next_whole_old_slot_when_the_grids_differ() -> None: + """M3: 60-minute old data, 15-minute new data ending inside an hour must not overlap.""" + source = FakeSource(segments=(hourly(local(16, 0), [0.30] * 48),)) + service, clock = make(source, local(16, 10, 0)) + await service.refresh("initial") + start = local(16, 10).astimezone(UTC) + quarter = prices_q(start, 15) # 10:00-13:45: ends inside the 13:00 hour + source.segments = (quarter,) + clock.advance(hours=1) + result = await service.refresh() + assert result is not None + assert result.ok + out = service.prices(48) + at = { + out.import_price.slot_start(i).astimezone(BERLIN).strftime("%H:%M"): v + for i, v in enumerate(out.import_price.values) + if out.import_price.slot_start(i).astimezone(BERLIN).day == 16 + } + assert at["13:30"] == 0.55 # the new data + # 13:45-14:00 is covered by neither (the old hour is not cut), 14:00 on is old data again + assert at["13:45"] is None + assert at["14:00"] == 0.30 + assert service.report(48).freshness.last_error is None + + +def prices_q(start: datetime, count: int) -> PriceSeries: + series = TimeSeries(start=start, step=Q, values=(0.55,) * count, unit="currency/kWh") # type: ignore[arg-type] + return PriceSeries(source_id="fake", price_includes="all_in", import_price=series) + + +async def test_a_storing_error_in_the_series_assembly_does_not_escape( + monkeypatch: pytest.MonkeyPatch, +) -> None: + store = Store() + service, _ = make(FakeSource(segments=(day_prices(16, 2),)), local(16, 10, 0), store=store) + + def boom(_now: datetime) -> None: + msg = "assembly bug" + raise ValueError(msg) + + monkeypatch.setattr(service, "_trimmed", boom) + result = await service.refresh("initial") + assert result is not None + assert result.ok # prices are served; only the storing failed + assert store.written == [] + + +# --- report ----------------------------------------------------------------------------- + + +async def test_report_describes_source_formula_rule_and_freshness() -> None: + from suncore.core.tariff import PriceFormula # noqa: PLC0415 + + source = FakeSource( + segments=(hourly(local(16, 0), [0.10, -0.05] * 36),), price_includes="spot_only" + ) + spot = PriceSeries( + source_id="fake", price_includes="spot_only", import_price=source.segments[0].import_price + ) + source.segments = (spot,) + clock = Clock(local(16, 10, 7)) + plan = TariffPlan( + source=source, # type: ignore[arg-type] + export_tariff=FIXED_EXPORT, + negative_rule=NegativePriceRule.NO_REMUNERATION, + tz=BERLIN, + currency="EUR", + formula=PriceFormula(grid_fee=0.1, vat_pct=19), + ) + service = TariffService(plan, clock=clock) + await service.refresh("initial") + report = service.report(24) + assert report.unit == "currency/kWh" + assert report.step_min == 15 + info = report.source + assert info.import_source_id == "fake" + assert info.import_kind == "dynamic" + assert info.source_price_includes == "spot_only" + assert info.price_includes == "all_in" + assert info.formula_applied + assert info.export_kind == "fixed" + assert info.negative_price_rule == "no_remuneration" + assert info.export_zeroed_slots > 0 + assert info.native_step_min == 60 + assert info.currency == "EUR" + assert report.freshness.status == "fresh" + assert report.freshness.fetched_at == clock.now + assert report.freshness.age_s == 0 + assert report.freshness.known_until == local(16, 0).astimezone(UTC) + 72 * H + assert report.quality.has_tomorrow + assert report.slots[0].start == local(16, 10).astimezone(UTC) + zero = [s for s in report.slots if s.export_price == 0.0] + assert zero + assert all(s.import_price is not None for s in zero) + + +async def test_freshness_becomes_stale_with_age_or_a_missing_current_slot() -> None: + source = FakeSource(segments=(day_prices(16, 2),)) + service, clock = make( + source, local(16, 10, 0), settings=ServiceSettings(refresh_interval_s=3600) + ) + await service.refresh("initial") + assert service.report().freshness.status == "fresh" + source.error = SourceUnavailableError("down") + clock.advance(hours=2, minutes=1) + await service.tick() + assert service.report().freshness.status == "stale" + clock.now = local(18, 0) # the prices ended + assert service.report().freshness.status == "stale" + + +async def test_report_counts_dropped_points() -> None: + from suncore.tariff.parse import ParseReport # noqa: PLC0415 + + class Reporting(FakeSource): + async def fetch_segments( + self, + window: TimeRange, # noqa: ARG002 + now: datetime, # noqa: ARG002 + ) -> SourceData: + return SourceData( + segments=self.segments, + report=ParseReport(points=24, unreadable_values=2, duplicates=1, overlaps=3), + ) + + service, _ = make(Reporting(segments=(day_prices(16, 2),)), local(16, 10, 0)) + await service.refresh("initial") + assert service.report().quality.dropped_points == 6 + + +# --- export wiring ---------------------------------------------------------------------- + + +async def test_tiered_export_is_resolved_with_the_plant_size_at_construction() -> None: + tiered = ExportTariff( + kind="tiered", tiers=(ExportTier(up_to_kwp=10, price=0.08), ExportTier(price=0.07)) + ) + service, _ = make(FixedPriceSource(price=0.3), local(16, 10, 0), export=tiered, kwp=17.0) + await service.refresh("initial") + out = service.prices(24) + assert out.export_price is not None + assert out.export_price.values[0] == pytest.approx((10 * 0.08 + 7 * 0.07) / 17) + with pytest.raises(ExportConfigError): + make(FixedPriceSource(price=0.3), local(16, 10, 0), export=tiered, kwp=None) + + +# --- storing ---------------------------------------------------------------------------- + + +async def test_prices_are_stored_trimmed_to_the_known_range_and_only_when_changed() -> None: + store = Store() + source = FakeSource(segments=(hourly(local(16, 10), [0.3, 0.31, 0.32]),)) + service, clock = make(source, local(16, 10, 7), store=store) + await service.refresh("initial") + (written,) = store.written + assert written.source_id == "fake" + assert written.start == local(16, 10).astimezone(UTC) + assert written.import_price.values == (0.3,) * 4 + (0.31,) * 4 + (0.32,) * 4 + assert written.export_price is not None + assert set(written.export_price.values) == {0.08} + clock.advance(minutes=1) + await service.refresh() + assert len(store.written) == 1 # identical: not written again + source.segments = (hourly(local(16, 10), [0.3, 0.31, 0.33]),) + await service.refresh() + assert len(store.written) == 2 + + +async def test_a_failing_store_does_not_fail_the_refresh() -> None: + source = FakeSource(segments=(day_prices(16, 2),)) + service, _ = make(source, local(16, 10, 0), store=Store(fail=True)) + result = await service.refresh("initial") + assert result is not None + assert result.ok + + +async def test_nothing_is_stored_without_prices() -> None: + store = Store() + service, _ = make( + FakeSource(segments=(hourly(local(1, 0), [0.3]),)), local(16, 10, 0), store=store + ) + await service.refresh("initial") + assert store.written == [] # the only price lies in the past + + +# --- listeners, watch, run -------------------------------------------------------------- + + +async def test_listeners_hear_about_new_prices_and_can_be_removed() -> None: + source = FakeSource(segments=(day_prices(16, 2),)) + service, clock = make(source, local(16, 10, 0)) + heard: list[int] = [] + + def bad() -> None: + msg = "listener bug" + raise RuntimeError(msg) + + remove = service.add_listener(lambda: heard.append(1)) + service.add_listener(bad) + await service.refresh("initial") + assert heard == [1] + remove() + remove() # idempotent + clock.advance(hours=1) + await service.refresh() + assert heard == [1] + + +def test_watched_entities() -> None: + service, _ = make(FakeSource(watched_entities=("sensor.a",)), local(16, 10, 0)) + assert service.watched_entities == ("sensor.a",) + assert not service.watched_entities_isdisjoint(["sensor.b", "sensor.a"]) + assert service.watched_entities_isdisjoint(["sensor.b"]) + + +async def test_run_ticks_until_cancelled_and_survives_a_crashing_tick( + monkeypatch: pytest.MonkeyPatch, +) -> None: + source = FakeSource(segments=(day_prices(16, 2),)) + service, clock = make(source, local(16, 10, 0)) + sleeps: list[float] = [] + + async def sleep(seconds: float) -> None: + sleeps.append(seconds) + clock.advance(seconds=seconds) + if len(sleeps) == 2: + monkeypatch.setattr(service, "tick", crash) + if len(sleeps) >= 4: + raise asyncio.CancelledError + + async def crash() -> None: + msg = "tick bug" + raise RuntimeError(msg) + + with pytest.raises(asyncio.CancelledError): + await service.run(sleep, poll_s=30.0) + assert sleeps == [30.0] * 4 + assert ( + len(source.calls) == 1 + ) # the first tick fetched, the later ones found nothing due / crashed + + +def test_settings_have_a_floor_below_the_action_limiter() -> None: + low = ServiceSettings( + refresh_interval_s=1, retry_interval_s=1, tomorrow_poll_s=1, tomorrow_after=time(12) + ) + assert (low.refresh_interval_s, low.retry_interval_s, low.tomorrow_poll_s) == (60.0, 60.0, 60.0) + + +async def test_tomorrow_is_covered_at_the_end_of_the_market_day_west_of_the_market() -> None: + """Review M4: Nord Pool ends at CET midnight, an hour before London's; it must terminate.""" + from zoneinfo import ZoneInfo # noqa: PLC0415 + + london = ZoneInfo("Europe/London") + now = datetime(2026, 10, 16, 14, 0, tzinfo=london) + cet_end = datetime(2026, 10, 18, 0, 0, tzinfo=BERLIN) # end of tomorrow in CET + start = datetime(2026, 10, 16, 13, 0, tzinfo=london) + count = int((cet_end - start) / H) + for market, expected in ((BERLIN, True), (None, False)): + source = FakeSource(segments=(hourly(start, [0.3] * count),), delivery_tz=market) + plan = TariffPlan( + source=source, # type: ignore[arg-type] + export_tariff=FIXED_EXPORT, + negative_rule=NegativePriceRule.NONE, + tz=london, + currency="EUR", + ) + service = TariffService(plan, clock=Clock(now)) + await service.refresh("initial") + assert service.report(48).quality.has_tomorrow is expected + + +async def test_report_says_when_a_spot_price_has_no_formula() -> None: + from suncore.core.tariff import PriceFormula # noqa: PLC0415 + + source = FakeSource(segments=(day_prices(16, 2),), price_includes="spot_only") + spot = PriceSeries( + source_id="fake", price_includes="spot_only", import_price=day_prices(16, 2).import_price + ) + source.segments = (spot,) + for formula, missing, includes in ( + (None, True, "spot_only"), + (PriceFormula(grid_fee=0.1), False, "all_in"), + ): + plan = TariffPlan( + source=source, # type: ignore[arg-type] + export_tariff=FIXED_EXPORT, + negative_rule=NegativePriceRule.NONE, + tz=BERLIN, + currency="EUR", + formula=formula, + ) + service = TariffService(plan, clock=Clock(local(16, 10, 0))) + await service.refresh("initial") + report = service.report(24) + assert report.formula_missing is missing + assert report.price_includes == includes diff --git a/tests/tariff/test_sources.py b/tests/tariff/test_sources.py new file mode 100644 index 0000000..512a3dc --- /dev/null +++ b/tests/tariff/test_sources.py @@ -0,0 +1,89 @@ +# SPDX-License-Identifier: Apache-2.0 +"""Fixed and HT/NT sources, the unit helpers.""" + +from __future__ import annotations + +from datetime import UTC, datetime, timedelta + +import pytest + +from suncore.core.series import PLANNING_STEP, TimeRange +from suncore.core.tariff import TouPeriod, TouTariff, TouWindow +from suncore.tariff import FixedPriceSource, TouPriceSource +from suncore.tariff.units import ( + divisor_to_kwh, + energy_scale, + normalise_price_unit, + resolve_value_unit, +) +from tests.tariff.helpers import BERLIN, NOW + +H = timedelta(hours=1) + + +def rng(start: datetime, hours: float) -> TimeRange: + return TimeRange(start=start, end=start + timedelta(hours=hours)) + + +async def test_fixed_price_is_constant_all_in_on_the_planning_grid() -> None: + source = FixedPriceSource(price=0.31) + data = await source.fetch_segments(rng(NOW, 24), NOW) + (segment,) = data.segments + assert segment.price_includes == "all_in" + assert segment.step == PLANNING_STEP + assert segment.start == datetime(2026, 10, 16, 8, 0, tzinfo=UTC) # 10:07 local floors to 10:00 + assert len(segment.import_price) == 96 + 1 # the partial first quarter hour is included + assert set(segment.import_price.values) == {0.31} + assert source.kind == "fixed" + assert not source.uses_action + assert source.watched_entities == () + assert (await source.fetch(rng(NOW, 2))).import_price.values[0] == 0.31 + + +TOU = TouTariff( + base_price=0.35, + periods=(TouPeriod(window=TouWindow(start="22:00", end="06:00"), price=0.25),), +) + + +async def test_tou_prices_follow_the_local_windows() -> None: + source = TouPriceSource(tou=TOU, tz=BERLIN) + start = datetime(2026, 10, 16, 21, 0, tzinfo=BERLIN) + data = await source.fetch_segments(rng(start, 2), start) + values = data.segments[0].import_price.values + assert values == (0.35,) * 4 + (0.25,) * 4 # 22:00 local is the first NT slot + assert (await source.fetch(rng(start, 2))).import_price.values == values + + +@pytest.mark.parametrize( + ("day", "local_hours"), [((2026, 3, 29), 23), ((2026, 10, 25), 25), ((2026, 10, 16), 24)] +) +async def test_tou_on_dst_days_counts_real_hours( + day: tuple[int, int, int], local_hours: int +) -> None: + """NT 22:00-06:00 on the 25 h day: 00:00-06:00 is seven real hours, 22:00-24:00 two.""" + start = datetime(*day, tzinfo=BERLIN) + end = datetime(*day, tzinfo=BERLIN) + timedelta(days=1) + window = TimeRange(start=start.astimezone(UTC), end=end.astimezone(UTC)) + assert window.duration == timedelta(hours=local_hours) + data = await TouPriceSource(tou=TOU, tz=BERLIN).fetch_segments(window, start) + values = data.segments[0].import_price.values + assert len(values) == local_hours * 4 + nt_hours = {23: 5 + 2, 25: 7 + 2, 24: 6 + 2}[local_hours] # 00:00-06:00 is 5, 7 or 6 hours + assert values.count(0.25) == nt_hours * 4 + + +def test_unit_helpers() -> None: + assert normalise_price_unit("€/kWh") == "EUR/kWh" + assert normalise_price_unit("£/kWh") == "GBP/kWh" + assert normalise_price_unit("EUR/MWh") == "EUR/MWh" + assert normalise_price_unit(" CHF/kWh ") == "CHF/kWh" + assert resolve_value_unit("{currency}/MWh", "SEK") == "SEK/MWh" + assert divisor_to_kwh("EUR/kWh") == 1.0 + assert divisor_to_kwh("{currency}/MWh") == 1000.0 + assert 45.5 / divisor_to_kwh("EUR/MWh") == 0.0455 + assert energy_scale("EUR/MWh") == "MWh" + assert energy_scale("EUR/kWh") == "kWh" + assert energy_scale("EUR/m3") is None + with pytest.raises(ValueError, match="not a price unit"): + divisor_to_kwh("kWh") diff --git a/tests/templates/test_models.py b/tests/templates/test_models.py index 82d4e9e..2eb16f5 100644 --- a/tests/templates/test_models.py +++ b/tests/templates/test_models.py @@ -217,7 +217,11 @@ def test_action_allowlist_refuses_unknown_service_with_reason_key() -> None: doc["price_series"].update(domain="light", service="turn_on") with pytest.raises(ValidationError, match=ERR_ACTION_NOT_ALLOWED): TEMPLATE_ADAPTER.validate_python(doc) - for domain, service in (("tibber", "get_prices"), ("weather", "get_forecasts")): + for domain, service in ( + ("tibber", "get_prices"), + ("nordpool", "get_prices_for_date"), + ("weather", "get_forecasts"), + ): doc["price_series"].update(domain=domain, service=service) assert TEMPLATE_ADAPTER.validate_python(doc).kind == "tariff" @@ -315,3 +319,78 @@ def test_energy_solar_forecast_series_and_fallback() -> None: doc2["fallback_series"]["service"] = "evil" with pytest.raises(ValidationError): TEMPLATE_ADAPTER.validate_python(doc2) + + +def test_action_series_per_date_requests_and_user_parameters() -> None: + """WP4: Nord Pool style action - one call per delivery date, request fields from the user.""" + doc = tariff_doc() + series = doc["price_series"] + series.update(domain="nordpool", service="get_prices_for_date", response_path="*") + series.pop("start_field") + series.pop("end_field") + series.update( + date_field="date", + params=[ + { + "name": "config_entry", + "required": True, + "description": "template.acme.dynamic.param.entry", + }, + { + "name": "areas", + "required": False, + "description": "template.acme.dynamic.param.areas", + }, + ], + ) + series["fields"].update(end_field="end", value_unit="{currency}/MWh") + doc["price_unit"] = "{currency}/MWh" + template = TEMPLATE_ADAPTER.validate_python(doc) + assert isinstance(template, TariffTemplate) + assert template.message_keys() == [ + "template.acme.dynamic.name", + "template.acme.dynamic.role.price", + "template.acme.dynamic.param.entry", + "template.acme.dynamic.param.areas", + ] + _bad(doc, lambda d: d["price_series"].update(start_field="start")) # date XOR start/end + _bad(doc, lambda d: d["price_series"].update(end_field="end")) + _bad( + doc, + lambda d: d["price_series"]["params"].append( + {"name": "areas", "required": False, "description": "template.acme.dynamic.param.x"} + ), + ) + _bad( + doc, + lambda d: d["price_series"]["params"].append( + {"name": "date", "required": False, "description": "template.acme.dynamic.param.x"} + ), + ) + _bad(doc, lambda d: d["price_series"].update(params=[{"name": "x", "description": "bad key"}])) + _bad(doc, lambda d: d["price_series"].update(response_path="*.")) + + +def test_the_slot_end_field_belongs_to_lists_not_to_mapping_attributes() -> None: + doc = tariff_doc() + doc["price_series"]["fields"]["end_field"] = "end" + assert TEMPLATE_ADAPTER.validate_python(doc).kind == "tariff" + mapping = forecast_doc() + mapping["series"].update(attribute="wh_hours", shape="mapping") + mapping["series"]["fields"] = {"value_unit": "Wh", "end_field": "end"} + mapping["resolution_min"] = 60 + _bad(mapping, lambda d: d["series"].update(shape="mapping")) # end_field on a mapping + + +def test_date_zone_of_a_per_date_action() -> None: + doc = tariff_doc() + series = doc["price_series"] + series.update(domain="nordpool", service="get_prices_for_date", response_path="*") + series.pop("start_field") + series.pop("end_field") + series["date_field"] = "date" + series["date_tz"] = "Europe/Berlin" + assert TEMPLATE_ADAPTER.validate_python(doc).price_series.date_tz == "Europe/Berlin" # type: ignore[union-attr] + _bad(doc, lambda d: d["price_series"].update(date_tz="Mars/Olympus")) + _bad(doc, lambda d: d["price_series"].update(date_tz="CET")) + _bad(doc, lambda d: d["price_series"].pop("date_field")) # a zone needs a date field diff --git a/uv.lock b/uv.lock index c7be204..f70abcd 100644 --- a/uv.lock +++ b/uv.lock @@ -524,6 +524,47 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/04/4b/29cac41a4d98d144bf5f6d33995617b185d14b22401f75ca86f384e87ff1/h11-0.16.0-py3-none-any.whl", hash = "sha256:63cf8bbe7522de3bf65932fda1d9c2772064ffb3dae62d55932da54b31cb6c86", size = 37515, upload-time = "2025-04-24T03:35:24.344Z" }, ] +[[package]] +name = "highspy" +version = "1.15.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "numpy" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/87/02/c6b658f79911fee921721da728b9ab8f5e19ff06121fff36f90f77127f4d/highspy-1.15.1.tar.gz", hash = "sha256:20ed2fbf1cb64bf3044ee6632364b7e2653d93e6901e2b19fd3d5df10702e8c5", size = 1703256, upload-time = "2026-07-02T12:03:25.009Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/de/59/b79a7b1711ddfcca36674ddb41759e98eb1797f4a94513e7dd215e32e94d/highspy-1.15.1-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:a781dc8432568ea990fcdcc8d6e4365e67aa4848ca1f99275db096645b27cae3", size = 4878738, upload-time = "2026-07-02T12:02:03.82Z" }, + { url = "https://files.pythonhosted.org/packages/5e/e4/ae08124f71187628471a177e6db1ed2c1c45e9dceadc45f7111dfd7c2254/highspy-1.15.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:9499d631edeb9642fc08dee59ca6c5815be1764c13a336c58ab7ba063011aa24", size = 4473938, upload-time = "2026-07-02T12:02:05.754Z" }, + { url = "https://files.pythonhosted.org/packages/ff/7f/185b8c9579a9e4ef88eda45d1fdaf8d23a3a640f73c403a7b29fc0f0c4be/highspy-1.15.1-cp312-cp312-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:ef048fa722cdeb80062d271b8ba211cd6650ab73419762d80da7642bbd4a8420", size = 4636755, upload-time = "2026-07-02T12:02:07.996Z" }, + { url = "https://files.pythonhosted.org/packages/82/6b/18bec60d8585df860b8d33d310e99e7893eaabe3c8e9ebfa7e387ba9d2a4/highspy-1.15.1-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:9730647160a6481426729f46d9989a0507d05f3cf96f9fb180f4ab9891bea67b", size = 5034168, upload-time = "2026-07-02T12:02:09.89Z" }, + { url = "https://files.pythonhosted.org/packages/d4/51/e43f06e64e994ccb41a336ff78802c0dae63aed46c17acd52167b5ca3d76/highspy-1.15.1-cp312-cp312-manylinux_2_26_i686.manylinux_2_28_i686.whl", hash = "sha256:6a6a2f21ee31a9205a928fbbc3f8c054893c1aec34f6a7c56588317e2800e673", size = 5861937, upload-time = "2026-07-02T12:02:11.801Z" }, + { url = "https://files.pythonhosted.org/packages/d4/2a/5501a23cac55926e4b0554352b4285734b417dbec385c593f2ae405ea637/highspy-1.15.1-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:9a6760962b3e813814dc5e88301890d7cce975de5ce97cc3aed589cfdd461811", size = 6192004, upload-time = "2026-07-02T12:02:14.544Z" }, + { url = "https://files.pythonhosted.org/packages/94/08/fb7d30ea0e6c83fb943b16bf31951ba13a5be01a638ec13962a477009b91/highspy-1.15.1-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:787c92d5ff274256ba8848ab174cfc65d5af696f51bffe87423c85b2ea25c3fe", size = 7233098, upload-time = "2026-07-02T12:02:16.609Z" }, + { url = "https://files.pythonhosted.org/packages/23/77/9a07df7181834cfb61dafa5594e5eedc78369797c6487806bd3221d20667/highspy-1.15.1-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:dd9ee8e139e7260ec1306a48e30f1bd7937d9cfb8cb201d25da10e1099e5129b", size = 6636717, upload-time = "2026-07-02T12:02:18.72Z" }, + { url = "https://files.pythonhosted.org/packages/9a/25/5083d8e3d5cf5ff5edf5bcc03e3f693630ab59142c9d0a0bcbb2d315c50e/highspy-1.15.1-cp312-cp312-win32.whl", hash = "sha256:01c6585e83938ecf4139248b074b2ee736816d63716a20dc608b1d2fc9637b66", size = 2306753, upload-time = "2026-07-02T12:02:20.837Z" }, + { url = "https://files.pythonhosted.org/packages/d4/01/05521ca6b38e34e68d707888c378d3bcac34e62715b739e7c0c9b9887993/highspy-1.15.1-cp312-cp312-win_amd64.whl", hash = "sha256:8c548165270608a40147a7ea6d985fd62a65fabf0f075b3c0c59ea910b724223", size = 2711114, upload-time = "2026-07-02T12:02:22.621Z" }, + { url = "https://files.pythonhosted.org/packages/3f/1e/283ea32eac82dd24fe86c439013d7c7666f4889de89f0957362ea5fa425e/highspy-1.15.1-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:4db297486a7a42a18656d1cc0ea9e1596fe45b8f7f75669a0c55b9081531ee0a", size = 4878819, upload-time = "2026-07-02T12:02:24.668Z" }, + { url = "https://files.pythonhosted.org/packages/7f/1c/c6518fc7c2bd5c90d86bd7a8f3cf16c1ea0ace4335a80d45b8d3f96c0cba/highspy-1.15.1-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:818256db731339605a7b2c31cabfcbf820fe50402ff5e9b7aa8410ead06e8735", size = 4474016, upload-time = "2026-07-02T12:02:26.572Z" }, + { url = "https://files.pythonhosted.org/packages/2f/97/4b5e345affc107f1f315c55dd0b6f35f13be07092feccbdfe1d9bfe38e63/highspy-1.15.1-cp313-cp313-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:383cd3f28cce0753dec8e949719b10864e068c53a485624fcab4c6b585496dd7", size = 4636833, upload-time = "2026-07-02T12:02:28.467Z" }, + { url = "https://files.pythonhosted.org/packages/ca/6e/f00e914f2bd88e2b73a8b3ea1b47171a85cfa23d1a06dc373ca797f43208/highspy-1.15.1-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:238b2ee88b974b21c7e9ef198139502a7d87451939cae143dce789bbda121182", size = 5034140, upload-time = "2026-07-02T12:02:30.294Z" }, + { url = "https://files.pythonhosted.org/packages/61/03/8f821d39dc8ee06a35e0fa54c754ab592139640c1e839b587e60068ad822/highspy-1.15.1-cp313-cp313-manylinux_2_26_i686.manylinux_2_28_i686.whl", hash = "sha256:b6dcc545235c0765b48fc736122b105e174d907622d20986ac653c5b2a04911f", size = 5862229, upload-time = "2026-07-02T12:02:32.065Z" }, + { url = "https://files.pythonhosted.org/packages/ea/55/708b7523ad80106b91fb66471ab8b1c178a8c8adc222c839cc14147542cd/highspy-1.15.1-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:6e1f8a21a0f48aedb129a5a60d4cad9ee0767de271cd7450de16192440671b38", size = 6191747, upload-time = "2026-07-02T12:02:34.034Z" }, + { url = "https://files.pythonhosted.org/packages/8d/cd/737f43e9c56163ebae501ab21fdbc37dd2dde3e02fd18e37d0062b9b9c7c/highspy-1.15.1-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:9ea683af80e4fb7c9d712b5df4bae34c63fa9e6afc78d750ba2d9f5e6f3203e0", size = 7233066, upload-time = "2026-07-02T12:02:36.109Z" }, + { url = "https://files.pythonhosted.org/packages/33/60/b9ae92e8454f42cb5c5ccca63862a75f5d43afead1f725f3b8af19f507f5/highspy-1.15.1-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:565cf6a6e7c84e36c101b118a3c5fd09bc14aeece599bba12625e79b5ab0cecb", size = 6636826, upload-time = "2026-07-02T12:02:37.863Z" }, + { url = "https://files.pythonhosted.org/packages/54/0b/35e5e63be2e70951c3224ed33c4300f1cd37fcfe4eb6d25e259e13571e0f/highspy-1.15.1-cp313-cp313-win32.whl", hash = "sha256:6cc7008b82094b2a2377338398b38f5b6c306397bd23282e55dec46a101a2dac", size = 2306720, upload-time = "2026-07-02T12:02:39.839Z" }, + { url = "https://files.pythonhosted.org/packages/ca/63/2e104bab0117415c68950f249e42f0974f74665d0313dfeddceb1f74c47d/highspy-1.15.1-cp313-cp313-win_amd64.whl", hash = "sha256:46fe314b918257361c54170852bc561c78d0f84d94e2ad263859d818127e6e76", size = 2711119, upload-time = "2026-07-02T12:02:41.861Z" }, + { url = "https://files.pythonhosted.org/packages/0c/73/8cd42c3ca7baf4857494a0294ef068f2216f1216173f3f298046820a7a57/highspy-1.15.1-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:a7b11dc80781052a6e7c163b5c2696fe9e06c72927cfdb48f67f7e8c77096f4f", size = 4879694, upload-time = "2026-07-02T12:02:43.623Z" }, + { url = "https://files.pythonhosted.org/packages/fb/5b/308821aeefa0e85f90645e15a86bc63c156bf08b00e33a0a906a0c430b41/highspy-1.15.1-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:9a00e1278ea46a426b1eaa0aea69df9d72ed1d75b18227cad992384ebbdc0c74", size = 4475059, upload-time = "2026-07-02T12:02:45.455Z" }, + { url = "https://files.pythonhosted.org/packages/a3/20/9c75531c03c7121d576ef0ff8415bfb255fdd060c435f9f26e5b103b0559/highspy-1.15.1-cp314-cp314-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:193b9751d3705bc948552b138800af0ad8af17a5b801d5940d7db7ff1ffc4f10", size = 4637880, upload-time = "2026-07-02T12:02:47.239Z" }, + { url = "https://files.pythonhosted.org/packages/89/ea/6d6136f01ce82c049740b00380a39999a15c689a9a4d43fdb1ea25090c2b/highspy-1.15.1-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:6298b6ef691e83544d395d45fa4e856874c44b32936d85c36564f7697d27bb0b", size = 5034792, upload-time = "2026-07-02T12:02:49.044Z" }, + { url = "https://files.pythonhosted.org/packages/38/9d/ccf4a0d4e7a4fa4141dbabe9f78e94fa9d37b6b5becafe8a61e8369031eb/highspy-1.15.1-cp314-cp314-manylinux_2_26_i686.manylinux_2_28_i686.whl", hash = "sha256:9d436b5f8d50b01497d494606695746147e15b8e22eec6ae475a60cb8b22c1d7", size = 5861891, upload-time = "2026-07-02T12:02:51.432Z" }, + { url = "https://files.pythonhosted.org/packages/19/b4/655f6ce06e17159c001456c97c4be84dcb1448477e3ea52bd5401f5c27c3/highspy-1.15.1-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:bbb22b7ceed298c0b75237186eb4671915b1c41c07f966e527643af10493671e", size = 6195707, upload-time = "2026-07-02T12:02:53.446Z" }, + { url = "https://files.pythonhosted.org/packages/ea/93/a35495b3326cdc0c2ff59de69d26f2600f41399d9381b59f4826742c054e/highspy-1.15.1-cp314-cp314-musllinux_1_2_i686.whl", hash = "sha256:74c1eb71d3c0fa0c190492d9c0c67266d1dd6b4244c93b53e95a687504db309d", size = 7235019, upload-time = "2026-07-02T12:02:55.989Z" }, + { url = "https://files.pythonhosted.org/packages/20/5e/8b21c908ee94db28f2de58326c8a25e361b3d504f145f7972f096028a908/highspy-1.15.1-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:cb8b8298a74786e1cbc1a9e102b7749e2bbd9c41826ffd4a1d7ba738232646ff", size = 6637185, upload-time = "2026-07-02T12:02:58.165Z" }, + { url = "https://files.pythonhosted.org/packages/25/81/8f984e500536ca40a8fb1d74ecb7a213e170683adcfd01edee8e21e5735b/highspy-1.15.1-cp314-cp314-win32.whl", hash = "sha256:780c021441f548711818833d3a986fcb253849734aa00c3bf83d342c38b03629", size = 2362473, upload-time = "2026-07-02T12:03:00.147Z" }, + { url = "https://files.pythonhosted.org/packages/bf/97/e85d751aaba8231e86915077532fd584711d30aa9eb85c26331e2bd87596/highspy-1.15.1-cp314-cp314-win_amd64.whl", hash = "sha256:864258c59aeaea9d3bd7ccdd10c03258e2be764e2cf1e21f829fd1f8d8c15d57", size = 2813851, upload-time = "2026-07-02T12:03:01.836Z" }, +] + [[package]] name = "httpcore" version = "1.0.9" @@ -948,6 +989,79 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/79/7b/2c79738432f5c924bef5071f933bcc9efd0473bac3b4aa584a6f7c1c8df8/mypy_extensions-1.1.0-py3-none-any.whl", hash = "sha256:1be4cccdb0f2482337c4743e60421de3a356cd97508abadd57d47403e94f5505", size = 4963, upload-time = "2025-04-22T14:54:22.983Z" }, ] +[[package]] +name = "numpy" +version = "2.5.4" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/95/b0/c7453d0b6e2073c3264468b106ee1563750cecc910965e67357e3698c83e/numpy-2.5.4.tar.gz", hash = "sha256:9a94cf751c9ad8ebaa835bcd3d40dacf8534ad086b88c38029b65123c7999d2a", size = 20866315, upload-time = "2026-10-10T20:05:31.422Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/d0/97/ba2074e92b7befea137e77ea8471e768bbd87c339b7e8c9f5a931949f977/numpy-2.5.4-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:c6342f54c67093cae5c0227eb0eb772fdb79f2a2c37a6eb278b9909ee06aa356", size = 17001609, upload-time = "2026-10-10T20:02:40.843Z" }, + { url = "https://files.pythonhosted.org/packages/ff/a9/bac826765e971d8e16e2064e9ac7525fd69b40ac17c905033a7f5442023f/numpy-2.5.4-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:b11e8fda06a7d69f15ebf542660b74466c2e51094800c1fb794f47ad4faeef17", size = 12015718, upload-time = "2026-10-10T20:02:43.45Z" }, + { url = "https://files.pythonhosted.org/packages/31/2f/5ea3570fcb8ccd0882bea99436a513b2c85dad8f774a2057849130a8fb99/numpy-2.5.4-cp312-cp312-macosx_14_0_arm64.whl", hash = "sha256:9cb18a327b49c5c337f972b03682f6a49855525faaf3c0d3e9c96cd0fd8880a8", size = 5451717, upload-time = "2026-10-10T20:02:46.169Z" }, + { url = "https://files.pythonhosted.org/packages/34/f2/b4fc1bafca03868220b5eaf729d2f21ebd7d7b151c0f9e144fe212bbca35/numpy-2.5.4-cp312-cp312-macosx_14_0_x86_64.whl", hash = "sha256:aec3fc4b32ff82421274f5d205c559c51c840c8df66a78efd7f3612dd005a26a", size = 6789926, upload-time = "2026-10-10T20:02:48.139Z" }, + { url = "https://files.pythonhosted.org/packages/dc/96/8319e2457ae4333c62c815c7006b869a4f60985c1e01024c2f8c6c040fe5/numpy-2.5.4-cp312-cp312-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:fe4d21ab149f15e4e6043dfb0de87e6e5f34ac176cde83060e9802981fca2ac2", size = 15695312, upload-time = "2026-10-10T20:02:50.115Z" }, + { url = "https://files.pythonhosted.org/packages/43/a3/c799c62e19c337e6d3770b08e475887fb30ce8477d3c09efca6b2f0228a6/numpy-2.5.4-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:fbde6962867ee75b48b0ee29b2b9372ec5d617799dbaf38e82dc0596f2f7738a", size = 16727283, upload-time = "2026-10-10T20:02:53.186Z" }, + { url = "https://files.pythonhosted.org/packages/39/6b/3604e53fb00314d0dc1b94ec9125a1484f649c0a17480b1f0f0c7a9d6250/numpy-2.5.4-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:381a7a3d2e65e64c0ec302795ab9dc12bb1e73f150904699c153716177eebdaf", size = 17047890, upload-time = "2026-10-10T20:02:56.038Z" }, + { url = "https://files.pythonhosted.org/packages/4a/7a/e8b58a5289a0d464c52885de47c35a935cdd70c03a4c3ab94a5126416dd0/numpy-2.5.4-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:b89d0aaae2fe498c648f4c4795c084db535af5bd98ef942b2a3681fb74ce8645", size = 18485839, upload-time = "2026-10-10T20:02:59.018Z" }, + { url = "https://files.pythonhosted.org/packages/6f/c9/47094f597015009f310b8c900def59065ef1ff5a6fe7b51fc65ec58ec2c6/numpy-2.5.4-cp312-cp312-win32.whl", hash = "sha256:9968ab7e49b93ac6e1c3b2239732183152c9150f16308d30b66a372cffe3483c", size = 6138936, upload-time = "2026-10-10T20:03:01.626Z" }, + { url = "https://files.pythonhosted.org/packages/12/33/fefe62073dc8acfd0f2b9ed7c003af2f50aa61555e113e6db02b8f79f145/numpy-2.5.4-cp312-cp312-win_amd64.whl", hash = "sha256:a7b1b6353e36a7e50de2973a38d705c88ee93adcf120673cee7f45a4a3fa223a", size = 12573091, upload-time = "2026-10-10T20:03:04.349Z" }, + { url = "https://files.pythonhosted.org/packages/1a/07/161270b0c2eec56e4c905f6d6d22e1b836887b2cb189d3f5820aa588e9dd/numpy-2.5.4-cp312-cp312-win_arm64.whl", hash = "sha256:aa1cce2ff3f8d953de38b76bf44602caeb69f101430208f64a10067f7cb4b1d3", size = 10521630, upload-time = "2026-10-10T20:03:06.767Z" }, + { url = "https://files.pythonhosted.org/packages/67/14/1c3ee0118a8fce08565a5d8482631608426a33af10a01077fada5dc7c119/numpy-2.5.4-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:2377da2dd3ba2c1200956acbab2a358c83b8e1f8531191672d1cd6ad83250d53", size = 16997729, upload-time = "2026-10-10T20:03:09.291Z" }, + { url = "https://files.pythonhosted.org/packages/83/8c/b0ea9477fb1f0d4484bbc5cba21678cc9969704d8d7f3f158d1db35f8e14/numpy-2.5.4-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:7415db95818b39ec475a5eea54d9e3b6bc83e3912158e46da3438cdce399804d", size = 12009826, upload-time = "2026-10-10T20:03:11.946Z" }, + { url = "https://files.pythonhosted.org/packages/e2/84/6a3d75b3ba3dfe84ac0053450753d1e6d250a8bf80f66474cc46d1fb643f/numpy-2.5.4-cp313-cp313-macosx_14_0_arm64.whl", hash = "sha256:6d6a71b9d9a97c03633aa12565ef2825ffa036cc1d99cfd50dacf0f128af4fe2", size = 5445803, upload-time = "2026-10-10T20:03:14.329Z" }, + { url = "https://files.pythonhosted.org/packages/61/18/bb993f267ca20b376e07092a16793a5b31ed3138751e9ba480011a14d742/numpy-2.5.4-cp313-cp313-macosx_14_0_x86_64.whl", hash = "sha256:d8200f16437b289a5bb927c6e184eccc3e8389bc0070fea4cd5b9e13c1757959", size = 6786220, upload-time = "2026-10-10T20:03:16.602Z" }, + { url = "https://files.pythonhosted.org/packages/db/b6/135bb0953b61dc21c6cafa14b424ae666944e4899cf140e00c2b322a1a45/numpy-2.5.4-cp313-cp313-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:1c2e71b04c6cad90026e544501bbe0ab9290fa8a4d845e7e8c0d124fb429c988", size = 15689178, upload-time = "2026-10-10T20:03:18.721Z" }, + { url = "https://files.pythonhosted.org/packages/da/24/3bd070f3269dc609d8f26b2643f62ef91bb415841c0b294805aaf7fe06da/numpy-2.5.4-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:6ffa07666f8da0eef81d149934a626d0d95fbd6838432a33e66245423a9062c0", size = 16718044, upload-time = "2026-10-10T20:03:21.386Z" }, + { url = "https://files.pythonhosted.org/packages/c7/8e/9d15bd356b0a019c965312b1a3c6a727cac4cae5bc40045fbc12ce4cff9c/numpy-2.5.4-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:2fa3328f784fc8277fc48026f6cad516f5c561c5d8e2e39b3c9e0c8f23223b34", size = 17048364, upload-time = "2026-10-10T20:03:24.468Z" }, + { url = "https://files.pythonhosted.org/packages/dc/fe/9d5b560db964f15871885f2250795d15945f8699e17ef90c0c2ff4c875b2/numpy-2.5.4-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:b86966fbe4ad7de710422175572bcdc75fdedadfb54bc6fab7deabccddd7780b", size = 18474904, upload-time = "2026-10-10T20:03:27.895Z" }, + { url = "https://files.pythonhosted.org/packages/e9/98/d27552990f1bd611ef3e7466adadc78312ea2df63b83aad47fdc3d3ca8df/numpy-2.5.4-cp313-cp313-win32.whl", hash = "sha256:5258bc06526964be5face2fc6f756857a3f24f21ec3e72ca131337a75b165d6c", size = 6134537, upload-time = "2026-10-10T20:03:30.511Z" }, + { url = "https://files.pythonhosted.org/packages/90/8c/140a40398a66b4471211be1affdb6ed24c486d581bd28d07b7f2fcb69540/numpy-2.5.4-cp313-cp313-win_amd64.whl", hash = "sha256:8b4d2fd2d34e5f8c9235ee787de5631a37a28402b15cb80814df973d2be54129", size = 12566113, upload-time = "2026-10-10T20:03:32.612Z" }, + { url = "https://files.pythonhosted.org/packages/34/52/01d205e5e8ccb27b2b0b141e801f22b830198c979111b0fa44771438d9a9/numpy-2.5.4-cp313-cp313-win_arm64.whl", hash = "sha256:bc39ac66a7a9a3fbd6134fda43136b60ffde99c8f4501e64e0d2b24da137babf", size = 10519523, upload-time = "2026-10-10T20:03:35.163Z" }, + { url = "https://files.pythonhosted.org/packages/99/ba/005cb5edd580d2f84d7ca3206b92dc17d4388e56e6f87ffe8f2762f83139/numpy-2.5.4-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:c668b2f0d651605b58892644b0e302c7157f7159544227758c896982ef384b18", size = 17005499, upload-time = "2026-10-10T20:03:37.961Z" }, + { url = "https://files.pythonhosted.org/packages/f3/49/fee7587c33ee35f7977f9051d7f2023d4e7246d62710c80f20c2361ea232/numpy-2.5.4-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:ffa6ce09a1c6a08e9667dd9c97aa0b14184e8d18f2a14b78b2a2328c9147f076", size = 12019666, upload-time = "2026-10-10T20:03:40.606Z" }, + { url = "https://files.pythonhosted.org/packages/d5/b2/c6ce165acffceb15a82c07b9cc77d391f86b3f379ba62911908ae5d34b91/numpy-2.5.4-cp314-cp314-macosx_14_0_arm64.whl", hash = "sha256:956555e0603a4d38019ae6925711cb9dc43195c076a928accf7ea5d50bddfe53", size = 5455617, upload-time = "2026-10-10T20:03:43.138Z" }, + { url = "https://files.pythonhosted.org/packages/77/7f/dd85ce260a669a89be06842cf355d7353a33e6cfbc590fb8ebb947d88dc9/numpy-2.5.4-cp314-cp314-macosx_14_0_x86_64.whl", hash = "sha256:2c2c4afffdeb7920e445028dd71eb932cac3e704792e964bc2a232426d4f1255", size = 6791932, upload-time = "2026-10-10T20:03:44.874Z" }, + { url = "https://files.pythonhosted.org/packages/63/d6/34b0a2b0741386a63025a65a2c09caaaaaad6d0ca95b66cd65c30dd7fcb5/numpy-2.5.4-cp314-cp314-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:4054173604cd8658796053f1f3bc0befb68ec1c0762c57fdad61e199256a8617", size = 15710899, upload-time = "2026-10-10T20:03:46.839Z" }, + { url = "https://files.pythonhosted.org/packages/16/d5/928078d2b28f26829b138b4a6c3980045022fb409f570657a224ae60ef4e/numpy-2.5.4-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:d549420b8858885cea8838a727842249218b9c1da24dd517e25c9c7a948310a3", size = 16721710, upload-time = "2026-10-10T20:03:49.489Z" }, + { url = "https://files.pythonhosted.org/packages/f9/cf/673fd1b8f4cd78eb6320e87ec4c90ac19c095644259e3749853a405c70f4/numpy-2.5.4-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:823874a507a84af050493b622affde94b6f7c3a0dc22cb2801381bc03b871c00", size = 17066182, upload-time = "2026-10-10T20:03:52.25Z" }, + { url = "https://files.pythonhosted.org/packages/f3/92/a77b5061b1b3e2643928c37976d79ee173e1b171ed158b7a3c61056b41bc/numpy-2.5.4-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:4e263278bfb5ee6409db8aedbc4cc32973b1b82bc1e8d3c668551d04d83a7e37", size = 18480315, upload-time = "2026-10-10T20:03:55.39Z" }, + { url = "https://files.pythonhosted.org/packages/bb/1d/1486ef3d3fb2279fd93c4c43c1bbbf1ca389a19816696684409f71babaab/numpy-2.5.4-cp314-cp314-win32.whl", hash = "sha256:cfd73180400042a7c532d30c5e287bdd03c59ff9ee1b4c0316af0539e29dfe23", size = 6185739, upload-time = "2026-10-10T20:03:58.186Z" }, + { url = "https://files.pythonhosted.org/packages/52/9a/e1e512ebc948d5b9dd33b08736760f0ebbed2848fd4eda1f553088a6dcee/numpy-2.5.4-cp314-cp314-win_amd64.whl", hash = "sha256:2ca144f15135b6212a5c47b1e2aeca6e412f102f95a2d5d88d8aec77eb255de3", size = 12703552, upload-time = "2026-10-10T20:04:00.28Z" }, + { url = "https://files.pythonhosted.org/packages/2c/05/de709a982d7bbcd688a3fad71f002e9ff80c2db39e03ee726609b610f1d1/numpy-2.5.4-cp314-cp314-win_arm64.whl", hash = "sha256:468397ba3c64427474706e5c9123fe266395496714dc684294eac75cd4930d1e", size = 10803901, upload-time = "2026-10-10T20:04:02.659Z" }, + { url = "https://files.pythonhosted.org/packages/13/34/083570ada3bb2a30fbe5d77c8c6fef9141144a15d33e6f793a67e9749ab8/numpy-2.5.4-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:1ef3aa6d7e29bb13677323114280b05acc57607fa2300e66432d665d5418a162", size = 12138695, upload-time = "2026-10-10T20:04:05.012Z" }, + { url = "https://files.pythonhosted.org/packages/94/06/1f9c24db48eef0c2d1207e3b11fffb0478e39dfd8c1e1be7476936885eed/numpy-2.5.4-cp314-cp314t-macosx_14_0_arm64.whl", hash = "sha256:98b053943e5a0474ec0da309d2cb9d3f18ea57f8a2067c2ab7b5f763d1068380", size = 5574615, upload-time = "2026-10-10T20:04:07.316Z" }, + { url = "https://files.pythonhosted.org/packages/da/0f/593fba2e1560e949123bc7d2fc48b5893d56e58cd4bd5a273d2fbf60b220/numpy-2.5.4-cp314-cp314t-macosx_14_0_x86_64.whl", hash = "sha256:b64a85f40e154983960a4167d4c1d57a50c7f109b3d3264a3a984154e90a8454", size = 6889383, upload-time = "2026-10-10T20:04:09.918Z" }, + { url = "https://files.pythonhosted.org/packages/eb/9f/b799dfdce4e05e80ed4bc815c71ff343a11533b2c0ffc221cae8538cda63/numpy-2.5.4-cp314-cp314t-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:a813ed7719bf45463c51779e6a98d0385fe905e48447526938a4b8337333d551", size = 15753763, upload-time = "2026-10-10T20:04:12.278Z" }, + { url = "https://files.pythonhosted.org/packages/34/88/16c5f12f86f5ad2817c4d103205131fc6c8acb3d1878af05a1a4f23ec859/numpy-2.5.4-cp314-cp314t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:c9b80cdf5cedba0e90d93fa5f9a333c4d65bd545cd669b71bb97ce2b703c9d73", size = 16757212, upload-time = "2026-10-10T20:04:14.799Z" }, + { url = "https://files.pythonhosted.org/packages/ff/4f/a1fe40e18a898e6a5089f4f0d891f0a493eb0574d5b34458f0fbe5aa3e5c/numpy-2.5.4-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:2199ed071f460487c8db2c0e5c0b564494190edb4772fe80f9aad88b2604def5", size = 17116471, upload-time = "2026-10-10T20:04:17.58Z" }, + { url = "https://files.pythonhosted.org/packages/aa/46/e923a11c78e65c1722e7aaad817c06bd591324174b9d28ce5d31eee4d432/numpy-2.5.4-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:64f9c9878c1938476365e11ccfb6b770f3b9e5f045ccddc514235041e6959365", size = 18524063, upload-time = "2026-10-10T20:04:20.365Z" }, + { url = "https://files.pythonhosted.org/packages/5a/fa/84ab064514440c1f64a1b21088f2c82756defdd05e07c75ab233899565b2/numpy-2.5.4-cp314-cp314t-win32.whl", hash = "sha256:64d1c8ac28a4077cf987e0a71a7a0ef7e2df70722f07f0baa42dbb7eb6938647", size = 6340926, upload-time = "2026-10-10T20:04:22.865Z" }, + { url = "https://files.pythonhosted.org/packages/7e/7e/6cd886876f435b10685db9b9f7eeb70356f99e052116f4e5f11c5792c714/numpy-2.5.4-cp314-cp314t-win_amd64.whl", hash = "sha256:067374eb538c34c745436365cf7b0112595c1d326f21ce4ff340f61230239fbb", size = 12901584, upload-time = "2026-10-10T20:04:24.99Z" }, + { url = "https://files.pythonhosted.org/packages/38/1b/3c1684f6a06f7307f2335fca6e486cb162847fb97e91d65f8eb5cabad213/numpy-2.5.4-cp314-cp314t-win_arm64.whl", hash = "sha256:e94aef2c639da4a960ad0db8e06471208d8589974953d78b61d345b4eb99e394", size = 10891152, upload-time = "2026-10-10T20:04:27.52Z" }, + { url = "https://files.pythonhosted.org/packages/08/f4/3224deff3af2bef6bc0b175369698d8cb348f3d91d9bb0286cd5c9eae9e0/numpy-2.5.4-cp315-cp315-macosx_10_15_x86_64.whl", hash = "sha256:8dddfbee2e68d26d0d7d7d9cb247b1fd4409241cce32d815a11d97ec2cfde179", size = 17003231, upload-time = "2026-10-10T20:04:30.021Z" }, + { url = "https://files.pythonhosted.org/packages/be/75/fee0b8c6d94b44b2fdfae74f6a4ad5a138739589a8aebaec28ce4e713ed5/numpy-2.5.4-cp315-cp315-macosx_11_0_arm64.whl", hash = "sha256:81e3420b27048b65eb14c3acf0c174a8cb0e023277716110347d2dcb26026dad", size = 12018300, upload-time = "2026-10-10T20:04:32.519Z" }, + { url = "https://files.pythonhosted.org/packages/47/c0/d0b335a499a04b65f532c3f034346ef390f81299060f928492dabc1e0272/numpy-2.5.4-cp315-cp315-macosx_14_0_arm64.whl", hash = "sha256:0b4724a19de67bea8cfc4970798efa78bcbbe2ac2613cfac16721a42d44de2a5", size = 5454250, upload-time = "2026-10-10T20:04:34.943Z" }, + { url = "https://files.pythonhosted.org/packages/5a/0e/461b3783c03d668052e6a21b01b673db6ffcb7831fd32d9aa5368c1cd426/numpy-2.5.4-cp315-cp315-macosx_14_0_x86_64.whl", hash = "sha256:2132418bf8dd124a427ca9e6a1daf9ee1a87185344c95119ceae868b99466da1", size = 6789644, upload-time = "2026-10-10T20:04:37.258Z" }, + { url = "https://files.pythonhosted.org/packages/b3/02/5dad269b02166965a7b4ca14adaddd75dbee0de42435bfecf561b84ba5a6/numpy-2.5.4-cp315-cp315-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:325518d4245b9e331387702aa58c2ce1dc4cdcbb41dfb4ccd5dcbc7e08db1266", size = 15704353, upload-time = "2026-10-10T20:04:39.616Z" }, + { url = "https://files.pythonhosted.org/packages/93/3a/01360c8036822ed9f7aa32189a77d1476567ec1e8e1383522389e4faac45/numpy-2.5.4-cp315-cp315-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:56733449d2544178beaa4545cee357370440cf056c197f9c7bfb19dbfdd0e86d", size = 16718648, upload-time = "2026-10-10T20:04:42.383Z" }, + { url = "https://files.pythonhosted.org/packages/7d/5c/b863a2c093c4d6f21a597fcaf24ead0835c09ab16a8312d5a5a8868af683/numpy-2.5.4-cp315-cp315-musllinux_1_2_aarch64.whl", hash = "sha256:5ec3753760c1a6d8bb91200666e545c3a9728e6269dfb5d6ce02340996698aa3", size = 17059053, upload-time = "2026-10-10T20:04:44.976Z" }, + { url = "https://files.pythonhosted.org/packages/0a/60/ced4f57f9a1258a0af74f17cb0b0c2700b5c67cd6678823c803b263e4df3/numpy-2.5.4-cp315-cp315-musllinux_1_2_x86_64.whl", hash = "sha256:b1185012870173de7ae33d370bd45b1cf5baee747ea4b97036b65f4e93016877", size = 18477406, upload-time = "2026-10-10T20:04:47.863Z" }, + { url = "https://files.pythonhosted.org/packages/f9/bd/0ef22dafaafcc7d4bb3ca26b8d2afbd55dedad8eaba99a8c864e1997456f/numpy-2.5.4-cp315-cp315-win32.whl", hash = "sha256:298eca75243f2cbbfdb460560b9fb2a1792a33cf2ab4286efd43d92e8d3df508", size = 6185133, upload-time = "2026-10-10T20:04:50.467Z" }, + { url = "https://files.pythonhosted.org/packages/50/bc/d2651b155ecc608a77e6f4d15495c11f14f19bb98f8bf0c5b0d38f86dda1/numpy-2.5.4-cp315-cp315-win_amd64.whl", hash = "sha256:332f3378fe077dd850e677ec01bdcc4f22368fb5d50ef10b2c79230b1bf5a592", size = 12703085, upload-time = "2026-10-10T20:04:52.63Z" }, + { url = "https://files.pythonhosted.org/packages/dc/d2/45e404f8abb26fb9eda12b94012936873e827b1be76f2ee7890be128312e/numpy-2.5.4-cp315-cp315-win_arm64.whl", hash = "sha256:d4cccbbc78717966f764cd3af4fb70276fa01fc7a2688af11c78901fa5c04f05", size = 10801451, upload-time = "2026-10-10T20:04:55.677Z" }, + { url = "https://files.pythonhosted.org/packages/c6/c3/2ae14e09cfdb67dc187a342e15308a21c15bf4d2071f8079e6aee5fe56dc/numpy-2.5.4-cp315-cp315t-macosx_10_15_x86_64.whl", hash = "sha256:950ea81d57ef070665581b6e1b5f6a029306423cd1739c5b95fe78aa30db6b9d", size = 17097121, upload-time = "2026-10-10T20:04:58.403Z" }, + { url = "https://files.pythonhosted.org/packages/f5/cf/305ae624ef8a039414317224abe9ec9c2fe7ea3c2e1cf204d43ff6b2ffb9/numpy-2.5.4-cp315-cp315t-macosx_11_0_arm64.whl", hash = "sha256:c05ede731b03fb1b7591faca9389ade3267d2bddf1ad8882bb3f2cc5e101694f", size = 12135439, upload-time = "2026-10-10T20:05:01.65Z" }, + { url = "https://files.pythonhosted.org/packages/a9/a8/f75c63813aef95827bb2c0d13b12803016853056e8792c280058cdbfe783/numpy-2.5.4-cp315-cp315t-macosx_14_0_arm64.whl", hash = "sha256:5fbf7141bbfd63aea22f435c9062a032b9ea0082fe9845dad7f021d3f1234e71", size = 5571451, upload-time = "2026-10-10T20:05:04.135Z" }, + { url = "https://files.pythonhosted.org/packages/6f/0f/f17763f983868b5c49b4101ebd7e00760bd1769478a6bb6a8de6e085bbac/numpy-2.5.4-cp315-cp315t-macosx_14_0_x86_64.whl", hash = "sha256:3573cd22564692a5b899ec344e5d5b9cc4576f2985b96f22af3564ed54f2710f", size = 6883356, upload-time = "2026-10-10T20:05:06.249Z" }, + { url = "https://files.pythonhosted.org/packages/67/a7/8af04c5a79e047996cfa38854dcfbececdd0343a7c933a46fdd03ef6f5da/numpy-2.5.4-cp315-cp315t-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:6c109eac9cd439193678f69d70733c1108487546ca8eafc107b510ae10c1aecd", size = 15750991, upload-time = "2026-10-10T20:05:08.376Z" }, + { url = "https://files.pythonhosted.org/packages/57/7a/648254290d0c504faa8f2d07aa206660c728802c781a6f3fc68ab7cb5d71/numpy-2.5.4-cp315-cp315t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:80d6ef6e8620eb2c2b4c4caad50b5935d6db3cde2d51581b55dcc79e14016d1d", size = 16757675, upload-time = "2026-10-10T20:05:11.393Z" }, + { url = "https://files.pythonhosted.org/packages/b8/fe/4a8c3cdb0c70400cfe4c5bec42d3099a5673802a95064614b33e07b82aa1/numpy-2.5.4-cp315-cp315t-musllinux_1_2_aarch64.whl", hash = "sha256:77045a4b175bbf5316ec08003880804336c78f92281a1b72222b274ea85ec5ac", size = 17113846, upload-time = "2026-10-10T20:05:14.49Z" }, + { url = "https://files.pythonhosted.org/packages/1b/7e/619692bb67778702c0e9eb2d468568a7573f4e269386ea61aed01ee4e557/numpy-2.5.4-cp315-cp315t-musllinux_1_2_x86_64.whl", hash = "sha256:0f02a46e49cfb6c73bdb7aea1c0d3461dbae9aba613542b65f657cd3d17b9fab", size = 18522915, upload-time = "2026-10-10T20:05:17.33Z" }, + { url = "https://files.pythonhosted.org/packages/b7/b5/4da41c328788f575838f97a098fe8ca691ebc6f6fd73ad4a262ee40b184d/numpy-2.5.4-cp315-cp315t-win32.whl", hash = "sha256:ad62a416ddcf863bf44bba76fbf6b53366ab0692e294f51cae4b5fbe0d246788", size = 6335804, upload-time = "2026-10-10T20:05:19.921Z" }, + { url = "https://files.pythonhosted.org/packages/98/94/6482ddfa3d312490cb9358f375bf2ad56427dbea8769187158e94d653753/numpy-2.5.4-cp315-cp315t-win_amd64.whl", hash = "sha256:38f47be9f74ab870d2633b5456ae519c43758a8d1fd05342f0ce4ecc034396ee", size = 12890095, upload-time = "2026-10-10T20:05:21.875Z" }, + { url = "https://files.pythonhosted.org/packages/48/7f/c2d1b436b6e7cfebac140c2579a298344b85f2991a2ce5c3615cefb29400/numpy-2.5.4-cp315-cp315t-win_arm64.whl", hash = "sha256:7a14a461d9340f1b46b8648578aed9cdb8b3b018a8fac6c1dde2c9192a01a87f", size = 10883718, upload-time = "2026-10-10T20:05:28.547Z" }, +] + [[package]] name = "opentelemetry-api" version = "1.45.1" @@ -1404,6 +1518,8 @@ dependencies = [ { name = "aiohttp" }, { name = "aiosqlite" }, { name = "fastapi" }, + { name = "highspy" }, + { name = "numpy" }, { name = "pydantic" }, { name = "pydantic-settings" }, { name = "pyyaml" }, @@ -1429,6 +1545,8 @@ requires-dist = [ { name = "aiohttp", specifier = ">=3.14.5" }, { name = "aiosqlite", specifier = ">=0.22.1" }, { name = "fastapi", specifier = ">=0.143.0" }, + { name = "highspy", specifier = ">=1.11" }, + { name = "numpy", specifier = ">=2.3" }, { name = "pydantic", specifier = ">=2.11,<3" }, { name = "pydantic-settings", specifier = ">=2.15.0" }, { name = "pyyaml", specifier = ">=6.0.3" },