cantabile_edge, cantabile_modbus, cantabile_eebus 0.1.650: full source
This commit is contained in:
1 parent
85edd56ec8
commit
3edd015039
20 files changed
+2021
-35
No files matched your search
@@ -47,6 +47,14 @@ Model v1 (the forecasts' data; the ML in ml/ is a placeholder, 2026-10-28):
|
||||
local hour) and "solar_w_per_kw" (W of heat per kW/m² of global
|
||||
irradiance) (2026-11-03, Finding B6-a): the fit's other terms, taken
|
||||
into the room's model with R and C (room_rc). Absent: 0, as before.
|
||||
- "models" (2026-11-04, methods.md B9): per series (load_w, pv_w,
|
||||
base_load_w) the model in force in the form the box runs it
|
||||
(building/boxmodel.py: how, gbm as lgbm-trees-v1, pvphys), and
|
||||
"weather": the hourly weather the cloud forecast with, [{"end": unix,
|
||||
"solar": kWh/m², "cloud": %, "temp": °C}] for ~96 h. Where the series
|
||||
no longer covers a step, the box's own prediction (localml.py) takes
|
||||
it before the profile. Only from a model for this site. A model the
|
||||
box cannot run is left out (box_errors), the rest of the bundle stays.
|
||||
A malformed series or room refuses the whole bundle.
|
||||
"""
|
||||
import json
|
||||
@@ -54,11 +62,15 @@ import logging
|
||||
import math
|
||||
import os
|
||||
import re
|
||||
import struct
|
||||
import time
|
||||
import zlib
|
||||
from dataclasses import dataclass
|
||||
from datetime import datetime, timezone
|
||||
from zoneinfo import ZoneInfo
|
||||
|
||||
from . import localml
|
||||
|
||||
log = logging.getLogger(__name__)
|
||||
|
||||
|
||||
@@ -257,6 +269,8 @@ class Bundles:
|
||||
self.flats = _File(os.path.join(state_dir, "flats.json"), _check_flats)
|
||||
self.market = _File(os.path.join(state_dir, "market.json"), _check_market)
|
||||
self.flat: float | None = None # the last known tariff's mean import price
|
||||
self._box_key, self._box, self.box_errors = None, {}, {}
|
||||
self._box_cache: dict = {} # (series, start, model id) -> the box's forecast
|
||||
|
||||
def stamps(self):
|
||||
"""The tariff's and the model's file identities: a change means a new
|
||||
@@ -321,7 +335,9 @@ class Bundles:
|
||||
return None
|
||||
return {"id": m.get("id"), "source": m.get("source") or m.get("id"), "issued": m.get("issued"),
|
||||
"expires": m.get("expires"), "series": sorted((m.get("forecasts") or {})),
|
||||
"rooms": sorted(m.get("rooms") or {}) if m.get("site") == self.site else []}
|
||||
"rooms": sorted(m.get("rooms") or {}) if m.get("site") == self.site else [],
|
||||
"box_models": sorted(m.get("models") or {}) if m.get("site") == self.site and
|
||||
isinstance(m.get("models"), dict) else []}
|
||||
|
||||
def flat_list(self) -> list[dict]:
|
||||
d = self.flats.get()
|
||||
@@ -397,6 +413,13 @@ class Bundles:
|
||||
def forecast(self, name: str, start: int, step_s: int, steps: int, tz: str) -> list[float] | None:
|
||||
"""A model series for the horizon, or None (no model or no such
|
||||
series: the caller falls back to history)."""
|
||||
parts = self.forecast_parts(name, start, step_s, steps, tz)
|
||||
return None if parts is None else [v for v, _ in parts]
|
||||
|
||||
def forecast_parts(self, name: str, start: int, step_s: int, steps: int,
|
||||
tz: str) -> list[tuple[float, str]] | None:
|
||||
"""forecast() with, per step, where its value is from: "series"
|
||||
(the cloud's trained forecast) or "profile" (the hour-of-week)."""
|
||||
m = self.model.get()
|
||||
if m is None or m.get("site") not in (self.site, "*") or (m.get("expires") and m["expires"] <= start):
|
||||
return None
|
||||
@@ -411,12 +434,52 @@ class Bundles:
|
||||
t = start + k * step_s
|
||||
i = int((t - s0) // 900) if sv else -1
|
||||
if 0 <= i < len(sv):
|
||||
out.append(float(sv[i])) # the trained series where it covers
|
||||
out.append((float(sv[i]), "series")) # the trained series where it covers
|
||||
continue
|
||||
d = datetime.fromtimestamp(t, timezone.utc).astimezone(zone)
|
||||
out.append(float(f["values"][d.weekday() * 24 + d.hour]))
|
||||
out.append((float(f["values"][d.weekday() * 24 + d.hour]), "profile"))
|
||||
return out
|
||||
|
||||
def box_model(self, name: str):
|
||||
"""The bundle's own model for a series (localml.Model), or None: no
|
||||
model bundle for this site, none for the series, or one the box
|
||||
cannot run (its reason in box_errors; logged once per bundle)."""
|
||||
m = self.model.get()
|
||||
if m is None or m.get("site") != self.site:
|
||||
return None
|
||||
if self._box_key != self.model._key:
|
||||
self._box_key, self._box, self.box_errors, self._box_cache = self.model._key, {}, {}, {}
|
||||
models = m.get("models")
|
||||
for n, d in (models.items() if isinstance(models, dict) else []):
|
||||
try:
|
||||
self._box[n] = localml.Model(n, d)
|
||||
except (ValueError, TypeError, KeyError, AttributeError, struct.error, zlib.error) as e:
|
||||
self.box_errors[n] = str(e)[:200]
|
||||
log.warning("model bundle %s: the box's %s model left out: %s", m.get("id"), n, e)
|
||||
return self._box.get(name)
|
||||
|
||||
def box_forecast(self, name: str, start: int, steps: int, history, ha_forecast: list[dict] | None,
|
||||
weather_entity: str = "") -> tuple[list, dict] | None:
|
||||
"""The box's own forecast of a series for the horizon from start
|
||||
(localml.predict): per step a value or None, and what it was made
|
||||
with; None without a model for it. Made once per quarter hour."""
|
||||
mdl = self.box_model(name)
|
||||
if mdl is None:
|
||||
return None
|
||||
m = self.model.get() or {}
|
||||
key = (name, start, m.get("id"))
|
||||
hit = self._box_cache.get(key)
|
||||
if hit is None:
|
||||
try:
|
||||
hit = localml.predict(mdl, [start + k * localml.SLOT_S for k in range(steps)], history, ha_forecast,
|
||||
m.get("weather"), weather_entity, m.get("issued"))
|
||||
except Exception as e: # the box's model never stops a plan: the profile then
|
||||
log.warning("the box's %s model: %s", name, e)
|
||||
hit = ([None] * steps, {"kind": mdl.kind, "weather": "", "steps": 0, "error": str(e)[:200]})
|
||||
self._box_cache = {k: v for k, v in self._box_cache.items() if k[1] == start}
|
||||
self._box_cache[key] = hit
|
||||
return hit
|
||||
|
||||
def room_rc(self, control_id: str, area: str = "", only_one: bool = False,
|
||||
now: float | None = None) -> dict | None:
|
||||
"""A heating or cooling control's room in the model (R and C fitted
|
||||
|
||||
@@ -35,6 +35,7 @@ import time
|
||||
from . import inputs as inputs_mod
|
||||
from .building import Building
|
||||
from .bundles import Bundles
|
||||
from . import steady
|
||||
from .evphases import EvPhases
|
||||
from .executor import Executor, building_msg
|
||||
from .gridorder import GridOrders
|
||||
@@ -102,6 +103,7 @@ class Controller:
|
||||
self.plan_error = ""
|
||||
self.forecast: list[dict] = [] # the weather entity's hourly forecast
|
||||
self.wake = asyncio.Event()
|
||||
self.calm = False # the next plan is for a bundle only: the quarter under way stays
|
||||
self.act_now = asyncio.Event() # a control, release or new plan: act at once
|
||||
self.on_plan = [] # callbacks (the announcer) when a plan is made
|
||||
self.received: list[dict] = [] # the last commands and bundles (shown in HA, announce.py)
|
||||
@@ -242,6 +244,12 @@ class Controller:
|
||||
self.plan_error = plan["error"]
|
||||
log.warning("no new plan: %s (the last one stays while fresh)", plan["error"])
|
||||
return None
|
||||
calm, self.calm = self.calm, False
|
||||
if calm:
|
||||
steady.carry_quarter(plan, self.plan, self.clock())
|
||||
# changes that do not matter stay out of it (deadband, hold, gain: steady.py)
|
||||
steady.stabilise(plan, state, [c for c in self.controls if c.id in plan.get("devices", {})], self.col,
|
||||
self.guard.last_change, self.clock())
|
||||
plan["mode"] = self.mode()
|
||||
plan["id"] = f"{self.cfg.site_id[:8]}-{plan['made']}"
|
||||
plan["model"] = self.bundles.model_id()
|
||||
@@ -357,6 +365,7 @@ class Controller:
|
||||
d != {}, f.error or "stored")
|
||||
last = now
|
||||
log.info("plan: a new tariff or model: planning again")
|
||||
self.calm = True # nothing urgent: from the next quarter (steady.carry_quarter)
|
||||
self.wake.set()
|
||||
|
||||
async def _planner(self, stop):
|
||||
@@ -380,7 +389,7 @@ class Controller:
|
||||
await asyncio.wait_for(asyncio.wait([asyncio.ensure_future(stop.wait()),
|
||||
asyncio.ensure_future(self.wake.wait())],
|
||||
return_when=asyncio.FIRST_COMPLETED),
|
||||
self.cfg.control_interval_s)
|
||||
plan_wait(self.clock(), self.cfg.control_interval_s))
|
||||
woken = self.wake.is_set()
|
||||
except asyncio.TimeoutError:
|
||||
pass
|
||||
@@ -656,3 +665,20 @@ async def solve(state: dict, timeout: float) -> dict:
|
||||
return json.loads(out)
|
||||
except ValueError:
|
||||
return {"error": (err.decode(errors="replace").strip().splitlines() or ["no output"])[-1][:300]}
|
||||
|
||||
|
||||
PLAN_AT_S = 5.0 # a plan this long after a quarter hour: its first step is the quarter just begun
|
||||
|
||||
|
||||
def plan_wait(now: float, interval: float, at: float = PLAN_AT_S) -> float:
|
||||
"""Seconds to the next regular plan: just after the next boundary of
|
||||
the interval (the quarter hours), not interval after the last plan. A
|
||||
plan made mid-quarter takes the room as it is now for the quarter's
|
||||
start, and its first step's setpoint differed from the plan before it
|
||||
for that same quarter: a heat pump was set 20.5 at the quarter hour and
|
||||
back to 20.0 when the next plan came 12 minutes later (sim-munich-1,
|
||||
2026-11-03)."""
|
||||
if interval <= 0:
|
||||
return 0.0
|
||||
nxt = (now - at) // interval * interval + interval + at
|
||||
return max(1.0, nxt - now)
|
||||
@@ -91,17 +91,22 @@ NEEDED = {"battery": (("charge_from_grid", "setpoint"),), "heating": (("climate"
|
||||
PARAMS = {
|
||||
"battery": {"capacity_wh": 5000.0, "max_charge_w": 2500.0, "max_discharge_w": 2500.0, "efficiency": 0.95,
|
||||
"soc_pct": 50.0, # soc_pct: the estimate when no sensor says
|
||||
"manual_option": "manual", "auto_option": "self-consumption", "min_switch_s": 0.0},
|
||||
"manual_option": "manual", "auto_option": "self-consumption", "min_switch_s": 0.0,
|
||||
# steady.py: the least time between two changes of a mode / a setpoint, and
|
||||
# the least gain (ct) a battery's change must bring over its hold
|
||||
"hold_mode_s": 1800.0, "hold_set_s": 900.0, "min_gain_ct": 1.0},
|
||||
"heating": {"r_k_per_kw": 10.0, "c_kwh_per_k": 3.0, "max_power_w": 2000.0, "comfort_c": 21.0,
|
||||
"setback_c": 17.0, "cop": 1.0, # cop 1: electric; a heat pump ~3
|
||||
"min_switch_s": 600.0,
|
||||
# the room's other heat (W; the model's fit, inputs._room_rc): internal
|
||||
# (a number, or 24 by local hour) and the sun's per W/m² of irradiance
|
||||
"internal_gain_w": 0.0, "solar_m2": 0.0},
|
||||
"internal_gain_w": 0.0, "solar_m2": 0.0, "hold_mode_s": 1800.0, "hold_set_s": 900.0, "min_gain_ct": 1.0},
|
||||
"cooling": {"r_k_per_kw": 10.0, "c_kwh_per_k": 3.0, "max_power_w": 1500.0, "comfort_c": 25.0,
|
||||
"setup_c": 28.0, "cop": 3.0, "min_switch_s": 600.0, "internal_gain_w": 0.0, "solar_m2": 0.0},
|
||||
"setup_c": 28.0, "cop": 3.0, "min_switch_s": 600.0, "internal_gain_w": 0.0, "solar_m2": 0.0,
|
||||
"hold_mode_s": 1800.0, "hold_set_s": 900.0, "min_gain_ct": 1.0},
|
||||
"ev": {"need_wh": 10000.0, "departure": "07:00", "min_current_a": 6.0, "max_current_a": 16.0,
|
||||
"phases": None, "voltage": 230.0, "min_switch_s": 0.0}, # phases: None, not said (evphases.py)
|
||||
"phases": None, "voltage": 230.0, "min_switch_s": 0.0, # phases: None, not said (evphases.py)
|
||||
"hold_mode_s": 1800.0, "hold_set_s": 900.0, "min_gain_ct": 1.0},
|
||||
"cover": {"room": "", "gain_w": 800.0, "min_switch_s": 0.0, "area": "", "facing": -1.0,
|
||||
"open_pct": 100.0, "shade_pct": 30.0, "closed_pct": 0.0, "quiet_from": "22:00", "quiet_to": "07:00",
|
||||
"night_moves": 0.0, "min_move_s": 1800.0, "override_hold_s": 14400.0},
|
||||
|
||||
@@ -59,18 +59,24 @@ def actions_for(c, want, col, level="plan", why="") -> list[Action]:
|
||||
if c.kind == "battery":
|
||||
if isinstance(want, dict): # a plan entry: power and whether from the grid
|
||||
power, grid = float(want.get("set", 0)), bool(want.get("grid"))
|
||||
auto = bool(want.get("auto")) # the inverter's own self-consumption (optimizer._entry)
|
||||
else:
|
||||
power, grid = float(want), float(want) > 0
|
||||
auto = abs(power) < 50 # a command: about 0 is the inverter's own mode
|
||||
# With a setpoint the power is set there and the grid switch stays
|
||||
# off (it means "full power" on many inverters and would override
|
||||
# the setpoint); a battery with the switch alone is driven by it.
|
||||
switch("charge_from_grid", grid and "setpoint" not in e)
|
||||
if "mode" in e:
|
||||
# the inverter's own mode: manual while the plan sets power,
|
||||
# its self-consumption otherwise (the setpoint counts in manual only)
|
||||
opt = str(c.p("manual_option") if abs(power) >= 50 else c.p("auto_option"))
|
||||
# the inverter's own mode: its self-consumption where the plan's
|
||||
# battery balances the house, else manual at the plan's power (0:
|
||||
# hold, the self-consumption mode would discharge); the setpoint
|
||||
# counts in manual only
|
||||
opt = str(c.p("auto_option") if auto else c.p("manual_option"))
|
||||
if col.state(e["mode"]) != opt:
|
||||
act("mode", "select_option", {"option": opt}, opt)
|
||||
if opt == str(c.p("auto_option")):
|
||||
return out # the setpoint counts in manual only: not touched
|
||||
setnum("setpoint", power, "power_w")
|
||||
elif c.kind in ("heating", "cooling"):
|
||||
v = want.get("set") if isinstance(want, dict) else want
|
||||
@@ -131,7 +137,8 @@ def safe_want(c):
|
||||
"""The control's safe value when plans or data are stale."""
|
||||
if c.kind == "battery":
|
||||
s = c.safe or {}
|
||||
return {"set": float(s.get("setpoint", 0)), "grid": bool(s.get("charge_from_grid", False))}
|
||||
sp = float(s.get("setpoint", 0))
|
||||
return {"set": sp, "grid": bool(s.get("charge_from_grid", False)), "auto": abs(sp) < 50}
|
||||
v = (c.safe or {}).get(next(iter(c.writable()), ""), RELEASE)
|
||||
return v
|
||||
|
||||
|
||||
@@ -0,0 +1,376 @@
|
||||
# Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
|
||||
"""The forecast models the trainer fits (trainer.py; docs/methods.md §5).
|
||||
|
||||
Everything here is pure (numpy, LightGBM; no database, no network) and
|
||||
works on 15-minute slots: `t` the slots' starts (unix seconds, multiples
|
||||
of 900, ascending), `y` the series' mean power (W, NaN where nothing was
|
||||
metered). The kinds:
|
||||
|
||||
how the hour-of-week profile: the mean of each local hour of the
|
||||
week (168 values; the box's fallback format, ml/model_bundle.py).
|
||||
The baseline every other kind has to beat.
|
||||
gbm LightGBM on calendar (local hour, weekday, a day off: weekend or
|
||||
a German public holiday), the hour-of-week value, the same slot a
|
||||
week before, the weather (temperature, irradiance, cloud cover)
|
||||
and, for PV, the sun and the physical prior. Small (150 trees, 15
|
||||
leaves, one thread): hundreds of sites a night.
|
||||
pvphys PV only: the physical irradiance model (pvforecast.py, shared
|
||||
with the Mieterstrom pricing) times the site's calibration
|
||||
(pvcalib.py).
|
||||
|
||||
A model is a JSON-able dict ("params"); fit_* makes it, predict() uses it.
|
||||
The weather per slot comes from hourly records (pvforecast.Hour: the hour
|
||||
ENDING at `end`, solar in kWh/m² over that hour, cloud %, temp °C)."""
|
||||
from __future__ import annotations
|
||||
|
||||
import math
|
||||
from dataclasses import dataclass, field
|
||||
from datetime import date, datetime, timedelta, timezone
|
||||
from functools import lru_cache
|
||||
from zoneinfo import ZoneInfo
|
||||
|
||||
import numpy as np
|
||||
|
||||
try: # on the box: the Edge Agent's copies (edge/cantabile_edge; methods.md B9)
|
||||
from . import lgbtrees, pvcalib, pvforecast
|
||||
except ImportError:
|
||||
import lgbtrees
|
||||
import pvcalib
|
||||
import pvforecast
|
||||
|
||||
SLOT_S = 900
|
||||
WEEK = 7 * 96
|
||||
KINDS = ("how", "gbm", "pvphys")
|
||||
GBM_PARAMS = dict(objective="regression", learning_rate=0.05, num_leaves=15, min_data_in_leaf=12, bagging_fraction=0.9,
|
||||
bagging_freq=1, feature_fraction=0.9, lambda_l2=1.0, num_threads=1, verbose=-1, seed=1)
|
||||
GBM_ROUNDS = 150
|
||||
MIN_GBM_SLOTS = 96 # a day of data at least
|
||||
LOAD_FEATURES = ["hod", "dow", "off", "how", "lag7", "temp", "ghi", "cloud", "hdd"]
|
||||
PV_FEATURES = ["hod", "how", "lag7", "temp", "ghi", "cloud", "elev", "az", "phys"]
|
||||
|
||||
|
||||
# ---- the calendar -------------------------------------------------------------
|
||||
|
||||
def _easter(y: int) -> date:
|
||||
a, b, c = y % 19, y // 100, y % 100
|
||||
d, e = b // 4, b % 4
|
||||
f = (b + 8) // 25
|
||||
g = (b - f + 1) // 3
|
||||
h = (19 * a + b - d - g + 15) % 30
|
||||
i, k = c // 4, c % 4
|
||||
l_ = (32 + 2 * e + 2 * i - h - k) % 7
|
||||
m = (a + 11 * h + 22 * l_) // 451
|
||||
mo = (h + l_ - 7 * m + 114) // 31
|
||||
da = (h + l_ - 7 * m + 114) % 31 + 1
|
||||
return date(y, mo, da)
|
||||
|
||||
|
||||
@lru_cache(maxsize=16)
|
||||
def holidays_de(year: int) -> frozenset:
|
||||
"""Germany's nationwide public holidays (the states' own are not in)."""
|
||||
e = _easter(year)
|
||||
fixed = [date(year, 1, 1), date(year, 5, 1), date(year, 10, 3), date(year, 12, 25), date(year, 12, 26)]
|
||||
moving = [e - timedelta(days=2), e + timedelta(days=1), e + timedelta(days=39), e + timedelta(days=50)]
|
||||
return frozenset(fixed + moving)
|
||||
|
||||
|
||||
def calendar(t: np.ndarray, tz: str) -> dict[str, np.ndarray]:
|
||||
"""Per slot: local hour of day (fractional), weekday (Monday 0), hour of
|
||||
the week, day of year, and whether it is a day off."""
|
||||
zone = ZoneInfo(tz or "UTC")
|
||||
n = len(t)
|
||||
hod, dow, how, doy, off = (np.zeros(n) for _ in range(5))
|
||||
cache: dict[int, tuple] = {}
|
||||
for i, ts in enumerate(t.tolist()):
|
||||
hour_key = int(ts) // 3600
|
||||
c = cache.get(hour_key)
|
||||
if c is None:
|
||||
d = datetime.fromtimestamp(hour_key * 3600, timezone.utc).astimezone(zone)
|
||||
c = (d.hour, d.weekday(), d.timetuple().tm_yday,
|
||||
1.0 if d.weekday() >= 5 or d.date() in holidays_de(d.year) else 0.0)
|
||||
cache[hour_key] = c
|
||||
h, wd, dy, of = c
|
||||
hod[i] = h + (int(ts) % 3600) / 3600.0
|
||||
dow[i], how[i], doy[i], off[i] = wd, wd * 24 + h, dy, of
|
||||
return {"hod": hod, "dow": dow, "how": how, "doy": doy, "off": off}
|
||||
|
||||
|
||||
# ---- the weather per slot -------------------------------------------------------
|
||||
|
||||
@dataclass
|
||||
class Weather:
|
||||
"""Per slot: air temperature (°C), global horizontal irradiance (W/m²),
|
||||
cloud cover (%), the sun's elevation and azimuth (degrees). NaN where
|
||||
no record covers the slot (sun: always known with a location)."""
|
||||
temp: np.ndarray
|
||||
ghi: np.ndarray
|
||||
cloud: np.ndarray
|
||||
elev: np.ndarray
|
||||
az: np.ndarray
|
||||
hours: list = field(default_factory=list) # the records (pvforecast.Hour), for pvforecast
|
||||
|
||||
|
||||
def sun(t: np.ndarray, lat: float | None, lon: float | None) -> tuple[np.ndarray, np.ndarray]:
|
||||
"""The sun at each slot's middle (NaN without a location)."""
|
||||
if lat is None or lon is None:
|
||||
return np.full(len(t), np.nan), np.full(len(t), np.nan)
|
||||
el, az = np.zeros(len(t)), np.zeros(len(t))
|
||||
for i, ts in enumerate(t.tolist()):
|
||||
el[i], az[i] = pvforecast.sun_position(datetime.fromtimestamp(ts + SLOT_S / 2, timezone.utc), lat, lon)
|
||||
return el, az
|
||||
|
||||
|
||||
def weather(t: np.ndarray, hours: list, lat: float | None, lon: float | None) -> Weather:
|
||||
"""Hourly records → slots. Temperature: linear between the records'
|
||||
times; cloud: the record of the hour the slot is in; irradiance: the
|
||||
hour's irradiation shaped over its quarters by the sun's height (as
|
||||
pvforecast.forecast does), else a clear sky dimmed by the cloud cover."""
|
||||
n = len(t)
|
||||
el, az = sun(t, lat, lon)
|
||||
temp, ghi, cloud = np.full(n, np.nan), np.full(n, np.nan), np.full(n, np.nan)
|
||||
if not hours:
|
||||
return Weather(temp, ghi, cloud, el, az, [])
|
||||
by_end = {}
|
||||
for h in hours:
|
||||
by_end[int(h.end.timestamp()) // 3600 * 3600] = h
|
||||
ends = sorted(by_end)
|
||||
tt = np.array([e for e in ends if by_end[e].temp_c is not None], dtype=float)
|
||||
tv = np.array([by_end[e].temp_c for e in ends if by_end[e].temp_c is not None], dtype=float)
|
||||
mids = t + SLOT_S / 2
|
||||
if len(tt):
|
||||
inside = (mids >= tt[0] - 3600) & (mids <= tt[-1] + 3600)
|
||||
temp = np.where(inside, np.interp(mids, tt, tv), np.nan)
|
||||
sines: dict[int, float] = {}
|
||||
for i, ts in enumerate(t.tolist()):
|
||||
hour_end = (int(ts) // 3600 + 1) * 3600
|
||||
h = by_end.get(hour_end)
|
||||
if h is None:
|
||||
continue
|
||||
if h.cloud_pct is not None:
|
||||
cloud[i] = h.cloud_pct
|
||||
if lat is None or lon is None:
|
||||
if h.solar_kwh_m2 is not None:
|
||||
ghi[i] = h.solar_kwh_m2 * 1000.0
|
||||
continue
|
||||
mine = max(0.0, math.sin(math.radians(el[i])))
|
||||
if h.solar_kwh_m2 is not None:
|
||||
s = sines.get(hour_end)
|
||||
if s is None:
|
||||
s = sum(max(0.0, math.sin(math.radians(pvforecast.sun_position(
|
||||
datetime.fromtimestamp(hour_end - 3600 + q * SLOT_S + SLOT_S / 2, timezone.utc), lat, lon)[0])))
|
||||
for q in range(4))
|
||||
sines[hour_end] = s
|
||||
ghi[i] = h.solar_kwh_m2 * 1000.0 * (4 * mine / s) if s > 0 else 0.0
|
||||
elif h.cloud_pct is not None:
|
||||
ghi[i] = pvforecast.cloud_dimmed(pvforecast.clear_sky_ghi(el[i]), h.cloud_pct)
|
||||
return Weather(temp, ghi, cloud, el, az, list(hours))
|
||||
|
||||
|
||||
# ---- metrics ------------------------------------------------------------------
|
||||
|
||||
def metrics(y: np.ndarray, p: np.ndarray) -> dict:
|
||||
"""MAE and RMSE (W) and nMAE (MAE over the mean metered value) on the
|
||||
slots where both exist; nMAE None when the metered mean is ~0 (a night)."""
|
||||
m = ~(np.isnan(y) | np.isnan(p))
|
||||
if not m.any():
|
||||
return {"n": 0, "mae": None, "rmse": None, "nmae": None}
|
||||
e = y[m] - p[m]
|
||||
mae = float(np.abs(e).mean())
|
||||
level = float(np.abs(y[m]).mean())
|
||||
return {"n": int(m.sum()), "mae": mae, "rmse": float(np.sqrt((e ** 2).mean())),
|
||||
"nmae": mae / level if level > 1.0 else None}
|
||||
|
||||
|
||||
# ---- how: the hour-of-week profile -----------------------------------------------
|
||||
|
||||
def fit_how(t: np.ndarray, y: np.ndarray, tz: str) -> dict:
|
||||
cal = calendar(t, tz)
|
||||
vals: list[float | None] = []
|
||||
have = ~np.isnan(y)
|
||||
overall = float(y[have].mean()) if have.any() else 0.0
|
||||
for h in range(168):
|
||||
m = have & (cal["how"] == h)
|
||||
vals.append(float(y[m].mean()) if m.any() else None)
|
||||
out = []
|
||||
for h, v in enumerate(vals):
|
||||
if v is None: # the same hour on the other weekdays, else the mean
|
||||
same = [vals[d * 24 + h % 24] for d in range(7) if vals[d * 24 + h % 24] is not None]
|
||||
v = sum(same) / len(same) if same else overall
|
||||
out.append(round(max(v, 0.0), 1))
|
||||
return {"kind": "how", "values": out, "tz": tz}
|
||||
|
||||
|
||||
def how_values(params: dict, t: np.ndarray, tz: str) -> np.ndarray:
|
||||
v = np.asarray(params["values"], dtype=float)
|
||||
return v[calendar(t, tz)["how"].astype(int)]
|
||||
|
||||
|
||||
# ---- gbm ----------------------------------------------------------------------
|
||||
|
||||
def _lag7(t: np.ndarray, y: np.ndarray, hist_t: np.ndarray | None, hist_y: np.ndarray | None) -> np.ndarray:
|
||||
"""The same slot a week before, from y itself and older history."""
|
||||
lookup: dict[int, float] = {}
|
||||
if hist_t is not None:
|
||||
lookup.update({int(a): float(b) for a, b in zip(hist_t.tolist(), hist_y.tolist()) if not math.isnan(b)})
|
||||
lookup.update({int(a): float(b) for a, b in zip(t.tolist(), y.tolist()) if not math.isnan(b)})
|
||||
return np.array([lookup.get(int(ts) - 7 * 86400, np.nan) for ts in t.tolist()])
|
||||
|
||||
|
||||
def features(series: str, t: np.ndarray, w: Weather, how_p: dict, tz: str, lag7: np.ndarray,
|
||||
phys: np.ndarray | None) -> tuple[np.ndarray, list[str]]:
|
||||
cal = calendar(t, tz)
|
||||
cols = {"hod": cal["hod"], "dow": cal["dow"], "off": cal["off"], "doy": cal["doy"],
|
||||
"how": how_values(how_p, t, tz), "lag7": lag7, "temp": w.temp, "ghi": w.ghi, "cloud": w.cloud,
|
||||
"hdd": np.maximum(15.0 - w.temp, 0.0), "elev": w.elev, "az": w.az,
|
||||
"phys": phys if phys is not None else np.full(len(t), np.nan)}
|
||||
names = PV_FEATURES if series == "pv" else LOAD_FEATURES
|
||||
return np.column_stack([cols[c] for c in names]), names
|
||||
|
||||
|
||||
def fit_gbm(series: str, t: np.ndarray, y: np.ndarray, w: Weather, tz: str, lag7: np.ndarray,
|
||||
phys: np.ndarray | None) -> dict | None:
|
||||
import lightgbm as lgb
|
||||
have = ~np.isnan(y)
|
||||
if have.sum() < MIN_GBM_SLOTS:
|
||||
return None
|
||||
how_p = fit_how(t, y, tz)
|
||||
X, names = features(series, t, w, how_p, tz, lag7, phys)
|
||||
m = lgb.train(GBM_PARAMS, lgb.Dataset(X[have], y[have], feature_name=names), num_boost_round=GBM_ROUNDS)
|
||||
return {"kind": "gbm", "model": m.model_to_string(), "features": names, "how": how_p["values"], "tz": tz,
|
||||
"cap_w": float(np.nanpercentile(y[have], 99.9)) * 1.2 if have.any() else None}
|
||||
|
||||
|
||||
@lru_cache(maxsize=256)
|
||||
def _booster(model: str):
|
||||
import lightgbm as lgb
|
||||
return lgb.Booster(model_str=model)
|
||||
|
||||
|
||||
def _predictor(params: dict):
|
||||
"""LightGBM's booster (params["model"], the trainer's), else the trees
|
||||
as the box carries them (params["trees"], lgbtrees.py: no LightGBM
|
||||
needed; the same predictions, methods.md B9)."""
|
||||
if "model" in params:
|
||||
return _booster(params["model"])
|
||||
trees = params.get("_trees")
|
||||
if trees is None:
|
||||
trees = params["_trees"] = lgbtrees.Trees(params["trees"], len(params["features"]))
|
||||
return trees
|
||||
|
||||
|
||||
def box_params(params: dict) -> dict:
|
||||
"""A gbm's params in the form the box carries (lgbtrees.py), others as
|
||||
they are: what fcmodels.predict takes on the box."""
|
||||
if params.get("kind") != "gbm" or "model" not in params:
|
||||
return params
|
||||
out = {k: v for k, v in params.items() if k != "model"}
|
||||
out["trees"] = lgbtrees.pack(_booster(params["model"]).dump_model())
|
||||
return out
|
||||
|
||||
|
||||
def predict_gbm(params: dict, series: str, t: np.ndarray, w: Weather, lag7: np.ndarray,
|
||||
phys: np.ndarray | None) -> np.ndarray:
|
||||
tz = params.get("tz", "UTC")
|
||||
X, names = features(series, t, w, {"values": params["how"]}, tz, lag7, phys)
|
||||
if names != params["features"]:
|
||||
raise ValueError("gbm: the features changed since it was trained")
|
||||
p = np.asarray(_predictor(params).predict(X), dtype=float)
|
||||
p = np.maximum(p, 0.0)
|
||||
if params.get("cap_w"):
|
||||
p = np.minimum(p, params["cap_w"])
|
||||
if series == "pv":
|
||||
p = np.where(w.elev <= 0, 0.0, p) if not np.isnan(w.elev).all() else p
|
||||
return p
|
||||
|
||||
|
||||
# ---- one entry point -----------------------------------------------------------
|
||||
|
||||
@dataclass
|
||||
class Site:
|
||||
"""What a model needs besides the series: where, the time zone, and the
|
||||
PV's configuration where known (kWp None: estimated by the calibration)."""
|
||||
tz: str = "Europe/Berlin"
|
||||
lat: float | None = None
|
||||
lon: float | None = None
|
||||
kwp: float | None = None
|
||||
tilt: float = 30.0
|
||||
azimuth: float = 180.0
|
||||
pvgis_monthly: list | None = None # PVGIS's kWh per kWp per month (pvcalib.pvgis_monthly)
|
||||
|
||||
|
||||
def phys_prior(t: np.ndarray, w: Weather, s: Site) -> np.ndarray | None:
|
||||
"""The physical model's PV per slot for 1 kWp (W), None without a
|
||||
location or weather."""
|
||||
if s.lat is None or s.lon is None or not w.hours:
|
||||
return None
|
||||
return pvcalib.prior_w_per_kwp(t, w.hours, s.lat, s.lon, s.tilt, s.azimuth)
|
||||
|
||||
|
||||
def fit(kind: str, series: str, t: np.ndarray, y: np.ndarray, w: Weather, s: Site,
|
||||
hist_t: np.ndarray | None = None, hist_y: np.ndarray | None = None) -> dict | None:
|
||||
"""A model of this kind on (t, y), or None where the kind cannot be made
|
||||
(too little data, PV physics without a location or weather)."""
|
||||
if kind == "how":
|
||||
return fit_how(t, y, s.tz) if (~np.isnan(y)).any() else None
|
||||
if kind == "gbm":
|
||||
prior = phys_prior(t, w, s) if series == "pv" else None
|
||||
return fit_gbm(series, t, y, w, s.tz, _lag7(t, y, hist_t, hist_y), prior)
|
||||
if kind == "pvphys":
|
||||
if series != "pv":
|
||||
return None
|
||||
prior = phys_prior(t, w, s)
|
||||
if prior is None:
|
||||
return None
|
||||
p = pvcalib.fit(t, y, prior, w.elev, w.az, kwp=s.kwp, pvgis_monthly=s.pvgis_monthly)
|
||||
if p is None:
|
||||
return None
|
||||
p.update({"kind": "pvphys", "tilt": s.tilt, "azimuth": s.azimuth})
|
||||
return p
|
||||
raise ValueError(f"unknown kind {kind}")
|
||||
|
||||
|
||||
def predict(params: dict, series: str, t: np.ndarray, w: Weather, s: Site,
|
||||
hist_t: np.ndarray | None = None, hist_y: np.ndarray | None = None) -> np.ndarray:
|
||||
"""The model's forecast per slot (W). hist_*: metered history before t
|
||||
(the week-ago lag; NaN where unknown)."""
|
||||
kind = params["kind"]
|
||||
if kind == "how":
|
||||
return how_values(params, t, params.get("tz", s.tz))
|
||||
if kind == "gbm":
|
||||
prior = phys_prior(t, w, s) if series == "pv" else None
|
||||
nan = np.full(len(t), np.nan)
|
||||
return predict_gbm(params, series, t, w, _lag7(t, nan, hist_t, hist_y), prior)
|
||||
if kind == "pvphys":
|
||||
ss = Site(s.tz, s.lat, s.lon, s.kwp, params.get("tilt", s.tilt), params.get("azimuth", s.azimuth))
|
||||
prior = phys_prior(t, w, ss)
|
||||
if prior is None:
|
||||
return np.full(len(t), np.nan)
|
||||
return pvcalib.apply(params, prior, w.elev, w.az)
|
||||
raise ValueError(f"unknown kind {kind}")
|
||||
|
||||
|
||||
# ---- held-out window and the choice ----------------------------------------------
|
||||
|
||||
def holdout(t: np.ndarray, y: np.ndarray, max_days: float = 7.0) -> int:
|
||||
"""The index where the held-out window starts: the last 7 days, or with
|
||||
less data the last quarter of what was metered (at least 6 hours)."""
|
||||
have = np.flatnonzero(~np.isnan(y))
|
||||
if len(have) == 0:
|
||||
return len(t)
|
||||
span_s = float(t[have[-1]] - t[have[0]]) + SLOT_S
|
||||
h = min(max_days * 86400, max(0.25 * span_s, 6 * 3600))
|
||||
cut = t[have[-1]] + SLOT_S - h
|
||||
return int(np.searchsorted(t, cut))
|
||||
|
||||
|
||||
def choose(challengers: dict[str, float | None], champion: float | None) -> str | None:
|
||||
"""The kind to put in force, or None to keep the champion: the best
|
||||
challenger by held-out nMAE, if it beats the model in force (and so,
|
||||
being the best, the hour-of-week baseline too)."""
|
||||
scored = {k: v for k, v in challengers.items() if v is not None and math.isfinite(v)}
|
||||
if not scored:
|
||||
return None
|
||||
best = min(scored, key=lambda k: (scored[k], KINDS.index(k)))
|
||||
if champion is not None and math.isfinite(champion) and scored[best] >= champion:
|
||||
return None
|
||||
return best
|
||||
@@ -56,6 +56,7 @@ class _Track:
|
||||
override_until: float = 0.0
|
||||
override_entity: str = ""
|
||||
moved: float = -1e18 # when a cover was last moved by the agent
|
||||
changed: dict = field(default_factory=dict) # "mode" | "set" -> when the agent last changed it (steady.py)
|
||||
|
||||
|
||||
# The service each channel uses, by domain: nothing else can be called.
|
||||
@@ -151,6 +152,9 @@ class Guard:
|
||||
tr = self._t(a.control)
|
||||
tr.times.append(now)
|
||||
tr.commanded[a.entity] = (now, a.value)
|
||||
c = self.controls.get(a.control)
|
||||
boiler = c is not None and c.kind in ("heating", "cooling") and a.channel == "switch"
|
||||
tr.changed["set" if a.quantity or boiler else "mode"] = now
|
||||
if a.domain == "cover":
|
||||
tr.moved = now
|
||||
if a.quantity == "":
|
||||
@@ -187,6 +191,11 @@ class Guard:
|
||||
self.events.append({"control": control_id, "entity": entity, "value": value, "agent_set": want,
|
||||
"until": int(tr.override_until), "at": int(now)})
|
||||
|
||||
def last_change(self, control_id: str, kind: str) -> float | None:
|
||||
"""When the agent last changed a control's mode or setpoint (kind
|
||||
"mode" | "set"; a boiler's on/off is its setpoint), or None."""
|
||||
return self._t(control_id).changed.get(kind)
|
||||
|
||||
def overridden(self, control_id: str) -> bool:
|
||||
return self.clock() < self._t(control_id).override_until
|
||||
|
||||
|
||||
@@ -25,7 +25,7 @@ log = logging.getLogger(__name__)
|
||||
|
||||
STEP_S = 900
|
||||
STEPS = 192 # 48 h
|
||||
HISTORY_S = 3 * 86400
|
||||
HISTORY_S = 8 * 86400 # a day back (the fallback) and a week back (the box's models' lag)
|
||||
|
||||
|
||||
def number(v) -> float | None:
|
||||
@@ -83,8 +83,9 @@ class Collector:
|
||||
|
||||
|
||||
class History:
|
||||
"""Quarter-hour means of load and PV (W) for the last 3 days, kept on
|
||||
disk, for "the same quarter hour yesterday"."""
|
||||
"""Quarter-hour means of load and PV (W) for the last 8 days, kept on
|
||||
disk, for "the same quarter hour yesterday" and the box's models' "the
|
||||
same slot a week before" (localml.py)."""
|
||||
|
||||
def __init__(self, path: str):
|
||||
self.path = path
|
||||
@@ -162,14 +163,56 @@ def base_load(col: Collector, inputs) -> float | None:
|
||||
return max(0.0, sum(vals) - ctl)
|
||||
|
||||
|
||||
def _series(name, start, bundles, history, tz, now_value, default, model_names=None):
|
||||
def _model_series(m, start, bundles, history, tz, box) -> tuple[list[float], dict] | None:
|
||||
"""The model bundle's series m for the horizon: the cloud's forecast
|
||||
where its series covers a step, else the box's own model (localml.py;
|
||||
box: HA's weather forecast and its entity) where it has a value, else
|
||||
the hour-of-week profile; and how many steps each gave."""
|
||||
if not hasattr(bundles, "forecast_parts"):
|
||||
s = bundles.forecast(m, start, STEP_S, STEPS, tz)
|
||||
return None if s is None else (s, {})
|
||||
parts = bundles.forecast_parts(m, start, STEP_S, STEPS, tz)
|
||||
if parts is None:
|
||||
return None
|
||||
vals = [v for v, _ in parts]
|
||||
info = {"series": m, "cloud": sum(src == "series" for _, src in parts), "box": 0, "hour_of_week": 0}
|
||||
own = None
|
||||
if box is not None and info["cloud"] < STEPS:
|
||||
own = bundles.box_forecast(m, start, STEPS, history, box[0], box[1])
|
||||
for k, (v, src) in enumerate(parts):
|
||||
if src == "series":
|
||||
continue
|
||||
b = own[0][k] if own is not None else None
|
||||
if b is not None:
|
||||
vals[k] = b
|
||||
info["box"] += 1
|
||||
else:
|
||||
info["hour_of_week"] += 1
|
||||
if own is not None:
|
||||
info["box_model"] = own[1].get("kind")
|
||||
if own[1].get("weather"):
|
||||
info["box_weather"] = own[1]["weather"]
|
||||
if own[1].get("error"):
|
||||
info["box_error"] = own[1]["error"]
|
||||
return vals, info
|
||||
|
||||
|
||||
def _series(name, start, bundles, history, tz, now_value, default, model_names=None, box=None, info=None):
|
||||
"""A series for the horizon: the model bundle's (the first of
|
||||
model_names it has, default name), else the same quarter hour 1 or 2
|
||||
days back, else the value now, else the default."""
|
||||
model_names it has, default name: _model_series), else the same quarter
|
||||
hour 1 or 2 days back, else the value now, else the default. info (a
|
||||
dict): filled with the model's steps by source."""
|
||||
for m in (model_names if model_names is not None else (name,)):
|
||||
s = bundles.forecast(m, start, STEP_S, STEPS, tz) if bundles else None
|
||||
if s is not None:
|
||||
return s, "model" if m == name else f"model ({m})"
|
||||
got = _model_series(m, start, bundles, history, tz, box) if bundles else None
|
||||
if got is not None:
|
||||
s, n = got
|
||||
src = "model" if m == name else f"model ({m})"
|
||||
if n.get("box"):
|
||||
src += (f"; the box's own {n.get('box_model')} model for {n['box']} of {STEPS} steps"
|
||||
f" (weather: {n.get('box_weather') or 'none'})")
|
||||
if info is not None:
|
||||
info.update(n)
|
||||
return s, src
|
||||
out, have = [], 0
|
||||
for k in range(STEPS):
|
||||
t = start + k * STEP_S
|
||||
@@ -273,12 +316,16 @@ def model_state(now: float, controls, inputs, col: Collector, bundles, history,
|
||||
# (load.power as metered) is too only where no planned device has a meter
|
||||
# inside it, else the history of the base load stands in.
|
||||
ctl = getattr(inputs, "controlled_power", None) or []
|
||||
# the box's own models where the cloud's forecast no longer covers a step
|
||||
# (localml.py), on HA's weather forecast where the mapping has one
|
||||
box = (weather_forecast or [], getattr(inputs, "weather", "") or "")
|
||||
fc_src: dict = {"load": {}, "pv": {}}
|
||||
load, load_src = _series("load_w", start, bundles, history, tz, base_load(col, inputs), 500.0,
|
||||
("base_load_w",) if ctl else ("base_load_w", "load_w"))
|
||||
("base_load_w",) if ctl else ("base_load_w", "load_w"), box, fc_src["load"])
|
||||
if ctl and not load_src.startswith("model") and bundles and \
|
||||
bundles.forecast("load_w", start, STEP_S, 1, tz) is not None:
|
||||
load_src += " (the model's load_w includes the planned devices: not used)"
|
||||
pv, pv_src = _series("pv_w", start, bundles, history, tz, None, 0.0)
|
||||
pv, pv_src = _series("pv_w", start, bundles, history, tz, None, 0.0, None, box, fc_src["pv"])
|
||||
t_out = _hourly(weather_forecast or [], "temperature", start, STEPS)
|
||||
t_src = "weather forecast"
|
||||
measured = col.value(inputs.outside_temp) if inputs.outside_temp else None
|
||||
@@ -342,7 +389,10 @@ def model_state(now: float, controls, inputs, col: Collector, bundles, history,
|
||||
"ghi_w_m2": ghi, "location": location or {},
|
||||
"sources": {"load": load_src, "pv": pv_src, "t_out": t_src, "model": bundles.model_id(),
|
||||
"sky": "weather forecast" if clouds else "clear", "rooms": rooms_src, "ghi": ghi_src,
|
||||
"ev_phases": phases_src},
|
||||
"ev_phases": phases_src,
|
||||
# per series the steps from the cloud's forecast, the box's own model
|
||||
# (its kind and weather) and the hour-of-week profile (methods.md B9)
|
||||
"forecast": {k: v for k, v in fc_src.items() if v}},
|
||||
"devices": devices, "building": building or {}, "grid_order": grid_order or {},
|
||||
# the market's contracts in force as sources and sinks (shadow, the market's step 2)
|
||||
"market": bundles.market_for_model(start, STEP_S, STEPS, now) if hasattr(bundles, "market_for_model") else []}
|
||||
|
||||
@@ -0,0 +1,151 @@
|
||||
# Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
|
||||
"""A LightGBM regression booster as numbers the box can carry and evaluate
|
||||
without LightGBM (docs/methods.md B9). Standard library only; one file for
|
||||
the cloud (building/) and the box (edge/cantabile_edge/lgbtrees.py, a copy:
|
||||
building/test_boxmodel.py checks they are the same).
|
||||
|
||||
pack(dump) takes LightGBM's dump_model() (one tree per round, numerical
|
||||
splits only, objective regression: no output transform) and gives
|
||||
{"enc": "lgbm-trees-v1", "n": trees, "data": base64(zlib(trees))}; per
|
||||
tree, little-endian: uint16 the number of leaves L; L-1 internal nodes of
|
||||
(uint8 feature, uint8 decision: bit 1 default left, bits 2-3 the missing
|
||||
type 0 none / 1 zero / 2 NaN, int16 left, int16 right: >= 0 an internal
|
||||
node, < 0 the leaf ~child, float64 threshold); L float64 leaf values.
|
||||
Nodes by LightGBM's split_index, leaves by its leaf_index. Doubles as they
|
||||
are.
|
||||
|
||||
Trees(enc, n_features).predict(rows) sums the leaves in LightGBM's order
|
||||
with its decision rule (tree.h NumericalDecision), so it gives LightGBM's
|
||||
raw score to the last bit (measured 2026-11-04: max
|
||||
relative difference 0.0 over 192 slots)."""
|
||||
from __future__ import annotations
|
||||
|
||||
import base64
|
||||
import math
|
||||
import struct
|
||||
import zlib
|
||||
|
||||
ENCODING = "lgbm-trees-v1"
|
||||
NODE = struct.Struct("<BBhhd")
|
||||
MISSING = {"None": 0, "Zero": 1, "NaN": 2}
|
||||
ZERO = 1.0000000180025095e-35 # LightGBM's kZeroThreshold (1e-35f)
|
||||
MAX_TREES, MAX_LEAVES, MAX_RAW = 2000, 1024, 4 << 20
|
||||
|
||||
|
||||
def _ref(n: dict) -> int:
|
||||
return int(n["split_index"]) if "split_index" in n else ~int(n.get("leaf_index", 0))
|
||||
|
||||
|
||||
def pack_tree(root: dict) -> bytes:
|
||||
"""One tree (dump_model()'s tree_info[i]["tree_structure"])."""
|
||||
if "split_index" not in root: # no split: one leaf
|
||||
return struct.pack("<Hd", 1, float(root["leaf_value"]))
|
||||
nodes: dict[int, dict] = {}
|
||||
leaves: dict[int, float] = {}
|
||||
stack = [root]
|
||||
while stack:
|
||||
n = stack.pop()
|
||||
if "split_index" in n:
|
||||
if n.get("decision_type", "<=") != "<=":
|
||||
raise ValueError("a categorical split: not supported")
|
||||
nodes[int(n["split_index"])] = n
|
||||
stack += [n["left_child"], n["right_child"]]
|
||||
else:
|
||||
leaves[int(n["leaf_index"])] = float(n["leaf_value"])
|
||||
k = len(leaves)
|
||||
if sorted(nodes) != list(range(k - 1)) or sorted(leaves) != list(range(k)):
|
||||
raise ValueError("a tree's node or leaf indices are not contiguous")
|
||||
out = [struct.pack("<H", k)]
|
||||
for i in range(k - 1):
|
||||
n = nodes[i]
|
||||
dec = (2 if n.get("default_left") else 0) | (MISSING[n.get("missing_type", "None")] << 2)
|
||||
out.append(NODE.pack(int(n["split_feature"]), dec, _ref(n["left_child"]), _ref(n["right_child"]),
|
||||
float(n["threshold"])))
|
||||
out.append(struct.pack(f"<{k}d", *(leaves[i] for i in range(k))))
|
||||
return b"".join(out)
|
||||
|
||||
|
||||
def pack(dump: dict) -> dict:
|
||||
"""A booster's dump_model() as lgbm-trees-v1."""
|
||||
if dump.get("num_class", 1) != 1 or dump.get("num_tree_per_iteration", 1) != 1:
|
||||
raise ValueError("one tree per round only")
|
||||
obj = str(dump.get("objective") or "").split(" ")[0]
|
||||
if obj != "regression":
|
||||
raise ValueError(f"objective {obj!r}: regression only (no output transform)")
|
||||
raw = b"".join(pack_tree(t["tree_structure"]) for t in dump["tree_info"])
|
||||
return {"enc": ENCODING, "n": len(dump["tree_info"]), "data": base64.b64encode(zlib.compress(raw, 9)).decode()}
|
||||
|
||||
|
||||
class Trees:
|
||||
"""lgbm-trees-v1, checked (ValueError): every child a later node or a
|
||||
leaf (no loops), features in range, finite leaves."""
|
||||
|
||||
def __init__(self, enc: dict, n_features: int):
|
||||
if not isinstance(enc, dict) or enc.get("enc") != ENCODING:
|
||||
raise ValueError(f"trees: {ENCODING} only")
|
||||
z = zlib.decompressobj()
|
||||
try:
|
||||
raw = z.decompress(base64.b64decode(str(enc.get("data")), validate=True), MAX_RAW)
|
||||
except zlib.error as e:
|
||||
raise ValueError(f"trees: {e}") from None
|
||||
if z.unconsumed_tail:
|
||||
raise ValueError("trees: too large")
|
||||
if not z.eof:
|
||||
raise ValueError("trees: truncated")
|
||||
self.trees = []
|
||||
off = 0
|
||||
try:
|
||||
while off < len(raw):
|
||||
(k,) = struct.unpack_from("<H", raw, off)
|
||||
off += 2
|
||||
if not 1 <= k <= MAX_LEAVES:
|
||||
raise ValueError("trees: leaves")
|
||||
nodes = []
|
||||
for i in range(k - 1):
|
||||
f, dec, left, right, threshold = NODE.unpack_from(raw, off)
|
||||
off += NODE.size
|
||||
for c in (left, right):
|
||||
if not (i < c < k - 1 or -k <= c < 0):
|
||||
raise ValueError("trees: a child out of range")
|
||||
if f >= n_features or dec & 1 or (dec >> 2) & 3 > 2 or math.isnan(threshold):
|
||||
raise ValueError("trees: a split")
|
||||
nodes.append((f, threshold, bool(dec & 2), (dec >> 2) & 3, left, right))
|
||||
leaves = struct.unpack_from(f"<{k}d", raw, off)
|
||||
off += 8 * k
|
||||
if not all(math.isfinite(v) for v in leaves):
|
||||
raise ValueError("trees: a leaf")
|
||||
self.trees.append((nodes, leaves))
|
||||
if len(self.trees) > MAX_TREES:
|
||||
raise ValueError("trees: too many")
|
||||
except struct.error as e:
|
||||
raise ValueError(f"trees: truncated ({e})") from None
|
||||
if len(self.trees) != int(enc.get("n", -1)):
|
||||
raise ValueError("trees: count")
|
||||
|
||||
def predict_row(self, x) -> float:
|
||||
"""LightGBM's raw score for one row: per tree, a split goes left
|
||||
where the value is <= its threshold; a NaN counts 0 unless the
|
||||
split knows NaN; the split's missing values (zero or NaN, by its
|
||||
type) go its default way; the leaves summed in order."""
|
||||
total = 0.0
|
||||
for nodes, leaves in self.trees:
|
||||
if not nodes:
|
||||
total += leaves[0]
|
||||
continue
|
||||
i = 0
|
||||
while i >= 0:
|
||||
f, threshold, default_left, missing, left, right = nodes[i]
|
||||
v = x[f]
|
||||
if v != v and missing != 2:
|
||||
v = 0.0
|
||||
if (missing == 1 and -ZERO <= v <= ZERO) or (missing == 2 and v != v):
|
||||
i = left if default_left else right
|
||||
else:
|
||||
i = left if v <= threshold else right
|
||||
total += leaves[~i]
|
||||
return total
|
||||
|
||||
def predict(self, rows) -> list[float]:
|
||||
"""Rows: a list of lists or a 2-D numpy array (as Booster.predict)."""
|
||||
rows = rows.tolist() if hasattr(rows, "tolist") else rows
|
||||
return [self.predict_row([float(v) for v in r]) for r in rows]
|
||||
@@ -0,0 +1,226 @@
|
||||
# Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
|
||||
"""The forecast models on the box (docs/methods.md B9).
|
||||
|
||||
The cloud trains each site's models (building/trainer.py) and sends the
|
||||
box their forecast every 6 hours in the model bundle; since 2026-11-04 it
|
||||
also sends the models in force (bundle key "models", building/boxmodel.py)
|
||||
and the hourly weather it forecast with ("weather", 96 h). The cloud's
|
||||
forecast stays the default wherever its series covers a step; for the
|
||||
steps it no longer covers (a box offline for more than the series' 48 h)
|
||||
the box predicts with its own copy of the model, once per quarter hour
|
||||
(bundles.box_forecast); the hour-of-week profile stays the last fallback.
|
||||
|
||||
The same code as the cloud: fcmodels.py, pvcalib.py, pvforecast.py and
|
||||
lgbtrees.py here are copies of building/'s (building/test_boxmodel.py
|
||||
checks they are the same and that the box predicts what the cloud does).
|
||||
A gbm runs on lgbtrees (LightGBM's trees evaluated in plain Python, its
|
||||
decision rule, the same sums), so the box needs numpy, not LightGBM
|
||||
(step 2, the box training its own models, would add LightGBM:
|
||||
fcmodels.fit is already here).
|
||||
|
||||
The weather, per hour, in this order: Home Assistant's own forecast (the
|
||||
mapping's weather entity: temperature and cloud cover; the irradiance from
|
||||
the cloud cover, Haurwitz dimmed by Kasten-Czeplak, as fcmodels.weather
|
||||
and pvforecast do without irradiation), else the cloud's last hourly
|
||||
weather from the bundle. A step with neither: PV from PVGIS's climatology
|
||||
(pvforecast's climatology path) with the calibration (pvphys) or at the
|
||||
kWp it implies (climate_kwp); load: nothing here (the hour-of-week then).
|
||||
The lag (the same slot a week before) comes from the agent's history
|
||||
(inputs.History, 8 days)."""
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
import math
|
||||
from datetime import datetime, timezone
|
||||
|
||||
import numpy as np
|
||||
|
||||
from . import fcmodels, pvcalib, pvforecast
|
||||
|
||||
log = logging.getLogger(__name__)
|
||||
|
||||
SLOT_S = 900
|
||||
SERIES = {"load_w": "load", "pv_w": "pv", "base_load_w": "base_load"} # the bundle's names: fcmodels'
|
||||
# the agent's history (inputs.History) a series' lag comes from: its load_w
|
||||
# is the base load already (the house without the planned devices), which
|
||||
# is the load where the box plans none (the only case its load_w is used)
|
||||
HISTORY = {"load_w": "load_w", "base_load_w": "load_w", "pv_w": "pv_w"}
|
||||
SITE_FIELDS = {"tz": str, "lat": float, "lon": float, "kwp": float, "tilt": float, "azimuth": float}
|
||||
|
||||
|
||||
def _num(v) -> bool:
|
||||
return isinstance(v, (int, float)) and not isinstance(v, bool) and math.isfinite(v)
|
||||
|
||||
|
||||
def _numbers(v, n: int) -> bool:
|
||||
return isinstance(v, list) and len(v) == n and all(_num(x) for x in v)
|
||||
|
||||
|
||||
class Model:
|
||||
"""One series' model from the bundle's "models", checked: ValueError
|
||||
where it is not one the box can run."""
|
||||
|
||||
def __init__(self, name: str, d: dict):
|
||||
if name not in SERIES or not isinstance(d, dict) or not isinstance(d.get("params"), dict):
|
||||
raise ValueError("a model: {params, site} for load_w, pv_w or base_load_w")
|
||||
self.name, self.series = name, SERIES[name]
|
||||
p, s = dict(d["params"]), d.get("site") or {}
|
||||
if not isinstance(s, dict):
|
||||
raise ValueError("site: an object")
|
||||
kw = {}
|
||||
for k, typ in SITE_FIELDS.items():
|
||||
v = s.get(k)
|
||||
if v is None:
|
||||
continue
|
||||
if typ is str and not isinstance(v, str) or typ is float and not _num(v):
|
||||
raise ValueError(f"site {k}")
|
||||
kw[k] = v
|
||||
if "pvgis_monthly" in s and s["pvgis_monthly"] is not None:
|
||||
if not _numbers(s["pvgis_monthly"], 12):
|
||||
raise ValueError("site pvgis_monthly: 12 numbers")
|
||||
kw["pvgis_monthly"] = [float(x) for x in s["pvgis_monthly"]]
|
||||
self.site = fcmodels.Site(**kw)
|
||||
self.climate_kwp = float(s["climate_kwp"]) if _num(s.get("climate_kwp")) and s["climate_kwp"] > 0 else None
|
||||
self.kind = p.get("kind")
|
||||
if self.kind == "how":
|
||||
if not _numbers(p.get("values"), 168):
|
||||
raise ValueError("how: 168 numbers")
|
||||
elif self.kind == "gbm":
|
||||
want = fcmodels.PV_FEATURES if self.series == "pv" else fcmodels.LOAD_FEATURES
|
||||
if p.get("features") != want or not _numbers(p.get("how"), 168) or "model" in p:
|
||||
raise ValueError(f"gbm: the features {', '.join(want)}, 168 hour-of-week values, trees")
|
||||
if p.get("cap_w") is not None and not _num(p["cap_w"]):
|
||||
raise ValueError("gbm: cap_w")
|
||||
fcmodels._predictor(p) # decodes and checks the trees (lgbtrees)
|
||||
elif self.kind == "pvphys":
|
||||
if self.series != "pv" or not _num(p.get("scale_kwp")) or not isinstance(p.get("bins") or {}, dict) \
|
||||
or not all(_num(v) for v in (p.get("bins") or {}).values()) \
|
||||
or (p.get("cap_w") is not None and not _num(p["cap_w"])):
|
||||
raise ValueError("pvphys: scale_kwp, bins, cap_w")
|
||||
p["bins"] = dict(p.get("bins") or {})
|
||||
else:
|
||||
raise ValueError(f"kind {self.kind!r}: how, gbm or pvphys")
|
||||
self.params = p
|
||||
|
||||
def climate(self, t: np.ndarray) -> np.ndarray | None:
|
||||
"""PV (W) from PVGIS's climatology alone (no weather), or None."""
|
||||
s = self.site
|
||||
if self.series != "pv" or not s.pvgis_monthly or s.lat is None or s.lon is None or not len(t):
|
||||
return None
|
||||
start = datetime.fromtimestamp(int(t[0]), timezone.utc)
|
||||
if self.kind == "pvphys":
|
||||
kwh, _ = pvcalib.forecast(start, len(t), [], s.lat, s.lon, 1.0, s.tilt, s.azimuth,
|
||||
calib=self.params, climatology=s.pvgis_monthly)
|
||||
return np.asarray(kwh) * 4000.0
|
||||
if not self.climate_kwp:
|
||||
return None
|
||||
kwh, _ = pvforecast.forecast(start, len(t), [], s.lat, s.lon, self.climate_kwp, s.tilt, s.azimuth,
|
||||
climatology=s.pvgis_monthly)
|
||||
out = np.asarray(kwh) * 4000.0
|
||||
cap = self.params.get("cap_w")
|
||||
return np.minimum(out, cap) if cap else out
|
||||
|
||||
|
||||
# ---- the weather on the box ---------------------------------------------------
|
||||
|
||||
def ha_hours(forecast: list[dict] | None) -> list:
|
||||
"""Home Assistant's hourly forecast (weather.get_forecasts) as records
|
||||
(pvforecast.Hour): the temperature and the cloud cover at each record's
|
||||
time, as the cloud's records give them (no irradiation)."""
|
||||
out = {}
|
||||
for f in forecast or []:
|
||||
try:
|
||||
ts = int(datetime.fromisoformat(str(f.get("datetime")).replace("Z", "+00:00")).timestamp())
|
||||
except ValueError:
|
||||
continue
|
||||
if ts % 3600:
|
||||
continue
|
||||
temp, cloud = f.get("temperature"), f.get("cloud_coverage")
|
||||
temp = float(temp) if _num(temp) else None
|
||||
cloud = float(cloud) if _num(cloud) else None
|
||||
if temp is not None or cloud is not None:
|
||||
out[ts] = pvforecast.Hour(datetime.fromtimestamp(ts, timezone.utc), None, cloud, temp)
|
||||
return [out[k] for k in sorted(out)]
|
||||
|
||||
|
||||
def cloud_hours(recs) -> list:
|
||||
"""The bundle's "weather": [{"end", "solar", "cloud", "temp"}]."""
|
||||
out = []
|
||||
for r in recs if isinstance(recs, list) else []:
|
||||
if not isinstance(r, dict) or not isinstance(r.get("end"), int) or r["end"] % 3600:
|
||||
continue
|
||||
v = [float(r[k]) if _num(r.get(k)) else None for k in ("solar", "cloud", "temp")]
|
||||
out.append(pvforecast.Hour(datetime.fromtimestamp(r["end"], timezone.utc), *v))
|
||||
return out
|
||||
|
||||
|
||||
def merge_hours(ha: list, cloud: list) -> tuple[list, dict[int, str]]:
|
||||
"""Per hour HA's record, else the cloud's; and per hour end which."""
|
||||
by, src = {}, {}
|
||||
for kind, hs in (("cloud", cloud), ("ha", ha)):
|
||||
for h in hs:
|
||||
k = int(h.end.timestamp())
|
||||
by[k], src[k] = h, kind
|
||||
return [by[k] for k in sorted(by)], src
|
||||
|
||||
|
||||
def describe(src: dict[int, str], t: list[int], entity: str, issued) -> str:
|
||||
n = {"ha": 0, "cloud": 0, "none": 0}
|
||||
for ts in t:
|
||||
n[src.get((ts // 3600 + 1) * 3600, "none")] += 1
|
||||
parts = []
|
||||
if n["ha"]:
|
||||
parts.append(f"Home Assistant's forecast ({entity or 'weather'}) {n['ha']} steps")
|
||||
if n["cloud"]:
|
||||
when = datetime.fromtimestamp(issued, timezone.utc).strftime("%Y-%m-%d %H:%M UTC") if _num(issued) else "?"
|
||||
parts.append(f"the cloud's weather of {when} {n['cloud']} steps")
|
||||
if n["none"]:
|
||||
parts.append(f"none {n['none']} steps")
|
||||
return ", ".join(parts)
|
||||
|
||||
|
||||
def _history(history, name: str, t0: int, t1: int) -> tuple[np.ndarray, np.ndarray]:
|
||||
"""The agent's quarter-hour means of a series in [t0, t1) as arrays."""
|
||||
slots = (getattr(history, "slots", None) or {}).get(name) or {}
|
||||
ts = sorted(k for k in slots if t0 <= k < t1)
|
||||
vals = [history.mean(name, k) for k in ts]
|
||||
return (np.array(ts, dtype=np.int64),
|
||||
np.array([np.nan if v is None else float(v) for v in vals], dtype=float))
|
||||
|
||||
|
||||
# ---- the box's forecast ------------------------------------------------------
|
||||
|
||||
def predict(model: Model, t: list[int], history, ha_forecast: list[dict] | None, cloud_weather,
|
||||
entity: str = "", issued=None) -> tuple[list[float | None], dict]:
|
||||
"""The box's forecast for the slots t (fcmodels.predict, as the cloud
|
||||
publishes it): per slot a value (W) or None (no weather for a model that
|
||||
needs it: the hour-of-week then), and {"kind", "weather", "steps"}."""
|
||||
ta = np.asarray(t, dtype=np.int64)
|
||||
info = {"kind": model.kind, "weather": "", "steps": 0}
|
||||
if model.kind == "how":
|
||||
p = fcmodels.predict(model.params, model.series, ta, fcmodels.weather(ta, [], None, None), model.site)
|
||||
out = [float(v) for v in p]
|
||||
info["steps"] = len(out)
|
||||
return out, info
|
||||
hours, src = merge_hours(ha_hours(ha_forecast), cloud_hours(cloud_weather))
|
||||
info["weather"] = describe(src, t, entity, issued)
|
||||
covered = [((ts // 3600 + 1) * 3600) in src for ts in t]
|
||||
s = model.site
|
||||
w = fcmodels.weather(ta, hours, s.lat, s.lon)
|
||||
ht, hy = _history(history, HISTORY[model.name], int(ta[0]) - 7 * 86400, int(ta[0]))
|
||||
p = fcmodels.predict(model.params, model.series, ta, w, s, ht, hy) if any(covered) else np.full(len(t), np.nan)
|
||||
clim = model.climate(ta) if not all(covered) else None
|
||||
out: list[float | None] = []
|
||||
n_clim = 0
|
||||
for k, v in enumerate(p.tolist()):
|
||||
if covered[k] and not math.isnan(v):
|
||||
out.append(max(0.0, v))
|
||||
elif clim is not None and not math.isnan(clim[k]):
|
||||
out.append(max(0.0, float(clim[k])))
|
||||
n_clim += 1
|
||||
else:
|
||||
out.append(None)
|
||||
if n_clim:
|
||||
info["weather"] += f"; PVGIS climatology {n_clim} steps"
|
||||
info["steps"] = sum(v is not None for v in out)
|
||||
return out, info
|
||||
@@ -459,9 +459,8 @@ def plan(s: dict, time_limit: float = 30.0) -> dict:
|
||||
kind, v = m.devices.get(d["id"], (d["kind"], None))
|
||||
entries = []
|
||||
for t in range(T):
|
||||
e = _entry(d, kind, v, t, x, s, pi)
|
||||
if e is not None and (not entries or (entries[-1]["set"], entries[-1].get("grid")) !=
|
||||
(e["set"], e.get("grid"))):
|
||||
e = _entry(d, kind, v, t, x, s, pi, (x(m.gin[t]), x(m.gout[t])))
|
||||
if e is not None and (not entries or _key(entries[-1]) != _key(e)):
|
||||
entries.append({"t": start + t * step, **e})
|
||||
devices[d["id"]] = entries
|
||||
energy = sum(m.eur_wh(t, pi[t]) * x(m.gin[t]) - m.eur_wh(t, s["price_export"][t]) * x(m.gout[t])
|
||||
@@ -550,8 +549,34 @@ def flexibility(m, x) -> dict:
|
||||
return {"grid_w": grid, "shed_w": [round(min(sh, g)) for sh, g in zip(shed, grid)]}
|
||||
|
||||
|
||||
def _entry(d, kind, v, t, x, s, pi):
|
||||
"""What a device is to do in step t, and why (a few words)."""
|
||||
def _charge_why(pi, t) -> str:
|
||||
"""Why the battery charges from the grid: "cheap grid power" only in the
|
||||
cheapest quarter of the horizon's prices and 10 % below their mean
|
||||
(sim-munich-1 called 47.6 ct cheap: an evening day-ahead price under a
|
||||
50 ct flat); else what it is for, the dearer hours later."""
|
||||
p25 = sorted(pi)[len(pi) // 4]
|
||||
mean = sum(pi) / len(pi)
|
||||
if pi[t] <= p25 + 1e-9 and pi[t] < 0.9 * mean:
|
||||
return f"cheap grid power ({pi[t]:.1f} ct)"
|
||||
later = pi[t + 1:]
|
||||
if later and max(later) > pi[t]:
|
||||
k = t + 1 + later.index(max(later))
|
||||
return f"charge for dearer hours later ({pi[t]:.1f} ct now, {pi[k]:.1f} ct in {(k - t) * 15 // 60} h)"
|
||||
return f"charge from the grid ({pi[t]:.1f} ct)"
|
||||
|
||||
|
||||
def _key(e) -> tuple:
|
||||
"""What makes a plan entry a change: a battery's self-consumption is one
|
||||
state whatever its power (it follows the house)."""
|
||||
return ("auto",) if e.get("auto") else (e["set"], e.get("grid"))
|
||||
|
||||
|
||||
GRID_ZERO_W = 50.0 # the meter's import and export below this: the battery balances the house
|
||||
|
||||
|
||||
def _entry(d, kind, v, t, x, s, pi, grid_w=(1e9, 1e9)):
|
||||
"""What a device is to do in step t, and why (a few words). grid_w:
|
||||
the meter's planned import and export in t."""
|
||||
occ = s["occupied"][t]
|
||||
if v is None:
|
||||
return None
|
||||
@@ -561,7 +586,7 @@ def _entry(d, kind, v, t, x, s, pi):
|
||||
surplus = s["pv_w"][t] - s["load_w"][t]
|
||||
grid = net > max(0.0, surplus) + 50
|
||||
if net > 0:
|
||||
why = f"cheap grid power ({pi[t]:.1f} ct)" if grid else "PV surplus"
|
||||
why = _charge_why(pi, t) if grid else "PV surplus"
|
||||
elif net < 0:
|
||||
mean = sum(pi) / len(pi)
|
||||
# "peak" only well above the horizon's average (Sim Munich: a plain
|
||||
@@ -570,6 +595,13 @@ def _entry(d, kind, v, t, x, s, pi):
|
||||
f"above the average price ({pi[t]:.1f} ct, average {mean:.1f})")
|
||||
else:
|
||||
why = "hold"
|
||||
if grid_w[0] < GRID_ZERO_W and grid_w[1] < GRID_ZERO_W and not grid:
|
||||
# what the battery does is what its own self-consumption mode does:
|
||||
# the inverter follows the house (no setpoint to chase the PV or
|
||||
# the load every quarter hour)
|
||||
return {"set": net, "grid": False, "auto": True,
|
||||
"why": "self-consumption: the battery covers the house" if net <= 0 else
|
||||
"self-consumption: PV surplus into the battery"}
|
||||
return {"set": net, "grid": grid, "why": why}
|
||||
if kind in ("heating", "cooling"):
|
||||
temp = x(v["temp"][t])
|
||||
@@ -590,7 +622,16 @@ def _entry(d, kind, v, t, x, s, pi):
|
||||
return {"set": "off", "why": "off: cool enough or away"}
|
||||
return {"set": target, "why": "pre-cool before someone is home" if not occ and ahead else "keep cool"}
|
||||
if pw < 50:
|
||||
return {"set": target, "why": "setback: away or night" if not occ else "warm enough"}
|
||||
# no heat planned: the thermostat at what the room must keep (the
|
||||
# comfort or setback target in the bounds), not at the room's
|
||||
# predicted temperature, which a thermostat holds by heating; the
|
||||
# room never cooled as planned, every next plan started from it
|
||||
# again (a replay of a munich-1 day: kept at 24 °C all evening)
|
||||
occ1 = s["occupied"][min(t + 1, s["steps"] - 1)]
|
||||
p = d["params"]
|
||||
want = float(p["comfort_c"]) if occ1 else float(p["setback_c"])
|
||||
floor_t = min(max(math.floor(want * 2) / 2, math.ceil(lo * 2) / 2), math.floor(hi * 2) / 2)
|
||||
return {"set": min(target, floor_t), "why": "setback: away or night" if not occ else "warm enough"}
|
||||
return {"set": target, "why": f"pre-heat while power is cheap ({pi[t]:.1f} ct)" if not occ and ahead
|
||||
else "keep the room warm"}
|
||||
if kind == "ev":
|
||||
|
||||
@@ -0,0 +1,199 @@
|
||||
# Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
|
||||
"""A site's PV calibration on top of the physical model (pvforecast.py; one
|
||||
implementation for the trainer and the Mieterstrom / GGV pricing).
|
||||
|
||||
The physical model knows the sun, the weather and the panels' orientation,
|
||||
not the site: shading by a neighbour's roof in the morning, dirty panels,
|
||||
a wrong kWp, an inverter that clips at noon. The calibration learns that
|
||||
from the metered PV (docs/methods.md §5):
|
||||
|
||||
scale the effective kWp: metered / the model's output for 1 kWp over the
|
||||
daylight slots (recent days weigh more: half-life 14 days). With
|
||||
a configured kWp, the ratio to it is shrunk to 1 (as if 16
|
||||
slots at the configured kWp had been seen); without one, it is
|
||||
shrunk the same way toward the kWp PVGIS's climatology implies
|
||||
(pvgis.monthly_yield_per_kwp: the metered kWh over the expected
|
||||
kWh per kWp of those days), which also overrules a configured
|
||||
kWp the metered yield contradicts by more than a factor 2.
|
||||
bins a ratio per sun position (elevation 3-10-20-35-90°, azimuth east
|
||||
< 150° ≤ south < 210° ≤ west): what is left after the scale,
|
||||
shrunk to 1 like a mean with 8 pseudo-slots at ratio 1, clipped
|
||||
to 0.3..2.
|
||||
cap the inverter's limit: with daylight data on at least 4 days and
|
||||
at least 96 daylight slots in all (CAP_DAYS, CAP_SLOTS), the
|
||||
99.5th percentile of the metered power (+2 %); the forecast never
|
||||
goes above it. Both, because 96 slots alone are 1.5 summer days or
|
||||
2.5 November days, and a cap from a short overcast run would clip
|
||||
every sunny forecast at the overcast maximum.
|
||||
|
||||
prior_w_per_kwp() and apply() work on numpy slot arrays (the trainer);
|
||||
forecast() is pvforecast.forecast() with a calibration (the coordinator's
|
||||
Mieterstrom / GGV pricing: the trainer's calibration in force for the
|
||||
building, else one fitted here from the box's last 30 days)."""
|
||||
from __future__ import annotations
|
||||
|
||||
import calendar
|
||||
import math
|
||||
from datetime import datetime, timedelta, timezone
|
||||
|
||||
import numpy as np
|
||||
|
||||
try: # on the box: the Edge Agent's copy (edge/cantabile_edge; methods.md B9)
|
||||
from . import pvforecast
|
||||
except ImportError:
|
||||
import pvforecast
|
||||
|
||||
SLOT_S = 900
|
||||
ELEV_EDGES = (3.0, 10.0, 20.0, 35.0, 91.0)
|
||||
AZ_EDGES = (150.0, 210.0)
|
||||
HALF_LIFE_D = 14.0
|
||||
PSEUDO_SCALE = 16.0
|
||||
PSEUDO_BIN = 8.0
|
||||
DAY_W_PER_KWP = 20.0 # a slot counts as daylight above this prior
|
||||
MIN_DAY_SLOTS = 8
|
||||
CAP_DAYS = 4 # the inverter cap: daylight data on this many days
|
||||
CAP_SLOTS = 96 # and this many daylight slots in all
|
||||
|
||||
|
||||
def prior_w_per_kwp(t: np.ndarray, hours: list, lat: float, lon: float, tilt: float = 30.0,
|
||||
azimuth: float = 180.0, pr: float = 0.85) -> np.ndarray:
|
||||
"""The physical model's mean power per slot for 1 kWp (W); NaN where no
|
||||
weather record covers the slot. t: contiguous 15-minute slots."""
|
||||
if len(t) == 0:
|
||||
return np.zeros(0)
|
||||
start = datetime.fromtimestamp(int(t[0]), timezone.utc)
|
||||
kwh, _ = pvforecast.forecast(start, len(t), hours, lat, lon, 1.0, tilt, azimuth, pr)
|
||||
out = np.asarray(kwh, dtype=float) * 4000.0
|
||||
have = {int(h.end.timestamp()) // 3600 * 3600 for h in hours
|
||||
if h.solar_kwh_m2 is not None or h.cloud_pct is not None}
|
||||
covered = np.array([(int(ts) // 3600 + 1) * 3600 in have for ts in t.tolist()])
|
||||
return np.where(covered, out, np.nan)
|
||||
|
||||
|
||||
def _bin(elev: float, az: float) -> str | None:
|
||||
if not (elev >= ELEV_EDGES[0]) or math.isnan(az):
|
||||
return None
|
||||
e = next(i for i, edge in enumerate(ELEV_EDGES[1:]) if elev < edge)
|
||||
a = 0 if az < AZ_EDGES[0] else 1 if az < AZ_EDGES[1] else 2
|
||||
return f"e{e}a{a}"
|
||||
|
||||
|
||||
def pvgis_kwp(t: np.ndarray, y: np.ndarray, prior: np.ndarray, day: np.ndarray, monthly: list[float]) -> float | None:
|
||||
"""The kWp the metered energy implies against PVGIS's climatology
|
||||
(pvgis.monthly_yield_per_kwp: kWh per kWp per month): metered kWh over
|
||||
the days' expected kWh per kWp, each day's share that was metered
|
||||
weighed by the physical model's shape of that day."""
|
||||
if not monthly or len(monthly) != 12:
|
||||
return None
|
||||
d_all = t // 86400
|
||||
expected = 0.0
|
||||
for d in np.unique(d_all[day]).tolist():
|
||||
on = d_all == d
|
||||
whole = float(np.nansum(np.where(on & (prior > DAY_W_PER_KWP), prior, 0.0)))
|
||||
seen = float(np.nansum(np.where(on & day, prior, 0.0)))
|
||||
if whole <= 0:
|
||||
continue
|
||||
dt = datetime.fromtimestamp(d * 86400, timezone.utc)
|
||||
expected += monthly[dt.month - 1] / calendar.monthrange(dt.year, dt.month)[1] * seen / whole
|
||||
metered = float(np.nansum(np.where(day, y, 0.0))) * SLOT_S / 3600 / 1000
|
||||
return metered / expected if expected > 0 else None
|
||||
|
||||
|
||||
def fit(t: np.ndarray, y: np.ndarray, prior: np.ndarray, elev: np.ndarray, az: np.ndarray,
|
||||
kwp: float | None = None, pr: float = 0.85, pvgis_monthly: list[float] | None = None) -> dict | None:
|
||||
"""The calibration from metered PV y (W) against the prior (W per kWp);
|
||||
None with fewer than 8 daylight slots metered. pvgis_monthly: PVGIS's
|
||||
expected kWh per kWp per month at the site (pvgis.py), the climatology's
|
||||
say on the kWp: the scale is shrunk toward it where no kWp is
|
||||
configured, and a configured kWp the metered yield contradicts (off by
|
||||
more than a factor 2 over 3 days or more) gives way to it."""
|
||||
day = (~np.isnan(y)) & (~np.isnan(prior)) & (prior > DAY_W_PER_KWP) & (elev >= ELEV_EDGES[0])
|
||||
n_day = int(day.sum())
|
||||
if n_day < MIN_DAY_SLOTS:
|
||||
return None
|
||||
age_d = (t[day].max() - t) / 86400.0
|
||||
w = np.where(day, 0.5 ** (age_d / HALF_LIFE_D), 0.0)
|
||||
sy, sp = float((w * np.nan_to_num(y)).sum()), float((w * np.nan_to_num(prior)).sum())
|
||||
if sp <= 0:
|
||||
return None
|
||||
days = len({int(ts) // 86400 for ts in t[day].tolist()})
|
||||
typical = float(np.nanmean(prior[day]))
|
||||
k_c = pvgis_kwp(t, y, prior, day, pvgis_monthly) if pvgis_monthly else None
|
||||
doubtful = bool(kwp and k_c and days >= 3 and not (0.5 * kwp <= k_c <= 2 * kwp))
|
||||
if kwp and not doubtful:
|
||||
ratio = (sy + PSEUDO_SCALE * kwp * typical) / (kwp * sp + PSEUDO_SCALE * kwp * typical)
|
||||
scale, scale_from = kwp * min(max(ratio, 0.3), 2.0), "configured kWp, calibrated"
|
||||
elif k_c:
|
||||
scale = (sy + PSEUDO_SCALE * k_c * typical) / (sp + PSEUDO_SCALE * typical)
|
||||
scale_from = (f"the metered yield says about {k_c:.1f} kWp (PVGIS), not the configured {kwp:g}" if doubtful
|
||||
else f"estimated from the metered PV, shrunk toward PVGIS's yield ({k_c:.1f} kWp)")
|
||||
else:
|
||||
scale, scale_from = sy / sp, "estimated from the metered PV"
|
||||
bins = {}
|
||||
for i in np.flatnonzero(day).tolist():
|
||||
b = _bin(float(elev[i]), float(az[i]))
|
||||
if b is None:
|
||||
continue
|
||||
s = bins.setdefault(b, [0.0, 0.0, 0])
|
||||
s[0] += w[i] * y[i]
|
||||
s[1] += w[i] * scale * prior[i]
|
||||
s[2] += 1
|
||||
typical_w = scale * float(np.nanmean(prior[day]))
|
||||
ratios = {b: round(min(max((a + PSEUDO_BIN * typical_w) / (p + PSEUDO_BIN * typical_w), 0.3), 2.0), 4)
|
||||
for b, (a, p, _) in bins.items()}
|
||||
cap = None
|
||||
if n_day >= CAP_SLOTS and days >= CAP_DAYS:
|
||||
cap = round(float(np.nanpercentile(y[day], 99.5)) * 1.02, 1)
|
||||
return {"scale_kwp": round(scale, 4), "scale_from": scale_from, "kwp_configured": kwp, "pr": pr, "days": days,
|
||||
"pvgis_kwp": round(k_c, 3) if k_c else None, "kwp_doubtful": doubtful,
|
||||
"bins": ratios, "bin_slots": {b: v[2] for b, v in bins.items()}, "cap_w": cap, "day_slots": n_day}
|
||||
|
||||
|
||||
def factor(params: dict, elev: float, az: float) -> float:
|
||||
b = _bin(elev, az)
|
||||
return params["scale_kwp"] * (params["bins"].get(b, 1.0) if b else 1.0)
|
||||
|
||||
|
||||
def apply(params: dict, prior: np.ndarray, elev: np.ndarray, az: np.ndarray) -> np.ndarray:
|
||||
"""The calibrated forecast (W) from the prior (W per kWp)."""
|
||||
f = np.array([factor(params, float(e), float(a)) for e, a in zip(elev.tolist(), az.tolist())])
|
||||
out = prior * f
|
||||
if params.get("cap_w"):
|
||||
out = np.minimum(out, params["cap_w"])
|
||||
return np.where(elev <= 0, 0.0, out)
|
||||
|
||||
|
||||
def forecast(start: datetime, n: int, hours: list, lat: float, lon: float, kwp: float,
|
||||
tilt: float = 30, azimuth: float = 180, pr: float = 0.85,
|
||||
calib: dict | None = None, climatology: list[float] | None = None) -> tuple[list[float], str]:
|
||||
"""pvforecast.forecast() (kWh per 15-minute slot, what it was made
|
||||
from), calibrated to the site when a calibration is given (the
|
||||
trainer's pvphys model in force: its tilt and azimuth then win).
|
||||
climatology: PVGIS's kWh per kWp per month, for slots without weather."""
|
||||
if not calib:
|
||||
return pvforecast.forecast(start, n, hours, lat, lon, kwp, tilt, azimuth, pr, climatology)
|
||||
base, kind = pvforecast.forecast(start, n, hours, lat, lon, 1.0, calib.get("tilt", tilt),
|
||||
calib.get("azimuth", azimuth), calib.get("pr", pr), climatology)
|
||||
out = []
|
||||
for k, v in enumerate(base):
|
||||
mid = start + timedelta(seconds=k * SLOT_S + SLOT_S / 2)
|
||||
el, az = pvforecast.sun_position(mid, lat, lon)
|
||||
e = v * factor(calib, el, az)
|
||||
if calib.get("cap_w"):
|
||||
e = min(e, calib["cap_w"] / 4000.0)
|
||||
out.append(round(e if el > 0 else 0.0, 4))
|
||||
return out, kind + ", calibrated"
|
||||
|
||||
|
||||
def pvgis_monthly(lat: float | None, lon: float | None, tilt: float = 30.0, azimuth: float = 180.0) -> list[float] | None:
|
||||
"""PVGIS's expected kWh per kWp per month at the site (pvgis.py: cached,
|
||||
rate-limited; PVGIS_OFFLINE=1: the cache only); None where it can't be
|
||||
had (no location, offline without the cache, PVGIS down)."""
|
||||
if lat is None or lon is None:
|
||||
return None
|
||||
try:
|
||||
import pvgis
|
||||
monthly, _sd = pvgis.monthly_yield_per_kwp(lat, lon, tilt, azimuth)
|
||||
return [float(v) for v in monthly] if len(monthly) == 12 else None
|
||||
except Exception: # the prior is optional
|
||||
return None
|
||||
@@ -0,0 +1,206 @@
|
||||
# Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
|
||||
"""A building's PV forecast from a weather forecast (docs/mieterstrom-ggv.md
|
||||
§4): irradiance → plane of array → kWp × performance ratio.
|
||||
|
||||
The weather comes from fleet's weather_forecasts (weather.go: DWD's MOSMIX
|
||||
through Bright Sky, hourly): `solar` is the global horizontal irradiation
|
||||
of the hour *ending* at the record's timestamp (kWh/m²), plus cloud cover
|
||||
(%) and the air temperature (°C). Per 15-minute slot:
|
||||
|
||||
1. the hour's irradiation spread over its quarter-hours by the sun's
|
||||
height (sin of the elevation at each quarter's middle);
|
||||
2. global → beam + diffuse with Erbs' correlation on the clearness index;
|
||||
3. plane of array (tilt, azimuth): beam × cos(incidence) + isotropic sky
|
||||
diffuse + ground reflection (albedo 0.2);
|
||||
4. P = kWp × POA / 1000 W/m² × PR × (1 − 0.4 %/K × (T_cell − 25 °C)),
|
||||
T_cell = T_air + 25 K × POA / 800 W/m².
|
||||
|
||||
Without irradiation (no forecast, or a station without it) a clear-sky
|
||||
model (Haurwitz) dimmed by the cloud cover (Kasten–Czeplak). Without any
|
||||
weather the climate: Haurwitz's clear-sky shape scaled so each day's
|
||||
energy is PVGIS's mean daily yield of that month at the site and
|
||||
orientation (`climatology`: pvgis.monthly_yield_per_kwp, kWh per kWp per
|
||||
month; PVGIS's 14 % system loss stands for PR 0.85, so the yield is scaled
|
||||
by pr / 0.85). Only where PVGIS can't be had either, the last resort: a
|
||||
clear sky dimmed by 60 % cloud, which takes only 13 % off (about 1.9 times
|
||||
November's climate in Berlin; methods.md B3-a), noted by the caller.
|
||||
Units: W/m², kWh per slot, degrees."""
|
||||
from __future__ import annotations
|
||||
|
||||
import calendar
|
||||
|
||||
import math
|
||||
from dataclasses import dataclass
|
||||
from datetime import datetime, timedelta, timezone
|
||||
|
||||
SLOT = timedelta(minutes=15)
|
||||
|
||||
|
||||
@dataclass
|
||||
class Hour:
|
||||
"""A weather record: the hour ending at `end` (UTC)."""
|
||||
end: datetime
|
||||
solar_kwh_m2: float | None = None
|
||||
cloud_pct: float | None = None
|
||||
temp_c: float | None = None
|
||||
|
||||
|
||||
def sun_position(t: datetime, lat: float, lon: float) -> tuple[float, float]:
|
||||
"""(elevation, azimuth) in degrees; azimuth from north, clockwise
|
||||
(180 = south). NOAA's simple formulas, good to about a degree."""
|
||||
t = t.astimezone(timezone.utc)
|
||||
doy = t.timetuple().tm_yday
|
||||
hour = t.hour + t.minute / 60 + t.second / 3600
|
||||
g = 2 * math.pi / 365 * (doy - 1 + (hour - 12) / 24)
|
||||
decl = (0.006918 - 0.399912 * math.cos(g) + 0.070257 * math.sin(g) - 0.006758 * math.cos(2 * g)
|
||||
+ 0.000907 * math.sin(2 * g) - 0.002697 * math.cos(3 * g) + 0.00148 * math.sin(3 * g))
|
||||
eqt = 229.18 * (0.000075 + 0.001868 * math.cos(g) - 0.032077 * math.sin(g) - 0.014615 * math.cos(2 * g)
|
||||
- 0.040849 * math.sin(2 * g))
|
||||
tst = hour * 60 + eqt + 4 * lon
|
||||
ha = math.radians(tst / 4 - 180)
|
||||
la = math.radians(lat)
|
||||
cz = math.sin(la) * math.sin(decl) + math.cos(la) * math.cos(decl) * math.cos(ha)
|
||||
cz = max(-1.0, min(1.0, cz))
|
||||
zen = math.acos(cz)
|
||||
elev = 90 - math.degrees(zen)
|
||||
sz = math.sin(zen)
|
||||
if sz < 1e-9:
|
||||
return elev, 180.0
|
||||
ca = (math.sin(decl) - math.sin(la) * cz) / (math.cos(la) * sz)
|
||||
az = math.degrees(math.acos(max(-1.0, min(1.0, ca))))
|
||||
if ha > 0:
|
||||
az = 360 - az
|
||||
return elev, az
|
||||
|
||||
|
||||
def extraterrestrial(t: datetime) -> float:
|
||||
doy = t.timetuple().tm_yday
|
||||
return 1367 * (1 + 0.033 * math.cos(2 * math.pi * doy / 365))
|
||||
|
||||
|
||||
def erbs_diffuse_fraction(kt: float) -> float:
|
||||
if kt <= 0.22:
|
||||
return 1 - 0.09 * kt
|
||||
if kt <= 0.8:
|
||||
return 0.9511 - 0.1604 * kt + 4.388 * kt ** 2 - 16.638 * kt ** 3 + 12.336 * kt ** 4
|
||||
return 0.165
|
||||
|
||||
|
||||
def clear_sky_ghi(elev: float) -> float:
|
||||
"""Haurwitz: W/m² on the horizontal."""
|
||||
s = math.sin(math.radians(elev))
|
||||
return 1098 * s * math.exp(-0.057 / s) if s > 0.01 else 0.0
|
||||
|
||||
|
||||
def cloud_dimmed(ghi_clear: float, cloud_pct: float) -> float:
|
||||
"""Kasten–Czeplak: G = G_clear × (1 − 0.75 × N^3.4), N the cover 0..1."""
|
||||
n = max(0.0, min(1.0, cloud_pct / 100))
|
||||
return ghi_clear * (1 - 0.75 * n ** 3.4)
|
||||
|
||||
|
||||
def poa(ghi: float, t: datetime, lat: float, lon: float, tilt: float, azimuth: float, albedo: float = 0.2) -> float:
|
||||
"""Plane-of-array irradiance (W/m²) from the global horizontal at t."""
|
||||
elev, az = sun_position(t, lat, lon)
|
||||
if elev <= 0 or ghi <= 0:
|
||||
return 0.0
|
||||
se = math.sin(math.radians(elev))
|
||||
g0 = extraterrestrial(t) * se
|
||||
kt = max(0.0, min(1.0, ghi / g0)) if g0 > 0 else 0.0
|
||||
dhi = erbs_diffuse_fraction(kt) * ghi
|
||||
beam_h = ghi - dhi
|
||||
b, ts = math.radians(tilt), math.radians(elev)
|
||||
cos_inc = math.cos(b) * se + math.sin(b) * math.cos(ts) * math.cos(math.radians(az - azimuth))
|
||||
beam = beam_h / se * max(cos_inc, 0.0) if elev > 2 else 0.0
|
||||
if elev <= 2:
|
||||
dhi = ghi # near the horizon: all of it as diffuse
|
||||
return max(0.0, beam + dhi * (1 + math.cos(b)) / 2 + ghi * albedo * (1 - math.cos(b)) / 2)
|
||||
|
||||
|
||||
def power_kw(poa_w: float, kwp: float, pr: float, temp_c: float | None) -> float:
|
||||
if poa_w <= 0:
|
||||
return 0.0
|
||||
t_cell = (temp_c if temp_c is not None else 10.0) + 25 * poa_w / 800
|
||||
derate = max(0.75, min(1.05, 1 - 0.004 * (t_cell - 25)))
|
||||
return kwp * poa_w / 1000 * pr * derate
|
||||
|
||||
|
||||
CLIMATE_PR = 0.85 # the PR PVGIS's 14 % system loss stands for
|
||||
FALLBACK_CLOUD = 60.0 # the last resort without weather and without PVGIS
|
||||
|
||||
|
||||
def clear_day_kwh(day: datetime, lat: float, lon: float, tilt: float, azimuth: float) -> float:
|
||||
"""The clear-sky (Haurwitz, undimmed) energy of 1 kWp at PR 1 over a UTC
|
||||
day (96 slots, 10 °C air): the shape's total, for scaling it to a day's
|
||||
climate. Europe's daylight lies inside the UTC day."""
|
||||
d0 = day.astimezone(timezone.utc).replace(hour=0, minute=0, second=0, microsecond=0)
|
||||
e = 0.0
|
||||
for k in range(96):
|
||||
mid = d0 + SLOT * k + SLOT / 2
|
||||
ghi = clear_sky_ghi(sun_position(mid, lat, lon)[0])
|
||||
e += power_kw(poa(ghi, mid, lat, lon, tilt, azimuth), 1.0, 1.0, None) * 0.25
|
||||
return e
|
||||
|
||||
|
||||
def climate_day_kwh(day: datetime, climatology: list[float], kwp: float, pr: float) -> float:
|
||||
"""A day's expected energy (kWh) from PVGIS's monthly yield per kWp:
|
||||
the month's yield over its days, times kWp, times pr / 0.85."""
|
||||
d = day.astimezone(timezone.utc)
|
||||
return climatology[d.month - 1] / calendar.monthrange(d.year, d.month)[1] * kwp * pr / CLIMATE_PR
|
||||
|
||||
|
||||
def forecast(start: datetime, n: int, hours: list[Hour], lat: float, lon: float, kwp: float,
|
||||
tilt: float = 30, azimuth: float = 180, pr: float = 0.85,
|
||||
climatology: list[float] | None = None) -> tuple[list[float], str]:
|
||||
"""kWh per 15-minute slot from `start` (UTC) for n slots, and what it was
|
||||
made from: "irradiance", "cloud" (some slots from the cloud cover, or a
|
||||
mix), "climatology" (no weather at all: the clear-sky shape at PVGIS's
|
||||
mean daily yield of the month; `climatology` = 12 × kWh per kWp per
|
||||
month at this site and orientation), or "clear-sky" (no weather and no
|
||||
climatology: the last resort, 60 % cloud)."""
|
||||
by_end = {h.end.astimezone(timezone.utc).replace(minute=0, second=0, microsecond=0): h for h in hours}
|
||||
clim = climatology if climatology and len(climatology) == 12 else None
|
||||
day_scale: dict = {}
|
||||
out, kinds = [], set()
|
||||
for k in range(n):
|
||||
s = start + k * SLOT
|
||||
mid = s + SLOT / 2
|
||||
hour_end = (s.replace(minute=0, second=0, microsecond=0) + timedelta(hours=1)).astimezone(timezone.utc)
|
||||
h = by_end.get(hour_end)
|
||||
if h is not None and h.solar_kwh_m2 is not None:
|
||||
# the hour's mean irradiance, shaped over its quarters by the sun's height
|
||||
quarters = [hour_end - timedelta(hours=1) + SLOT * q + SLOT / 2 for q in range(4)]
|
||||
sines = [max(0.0, math.sin(math.radians(sun_position(q, lat, lon)[0]))) for q in quarters]
|
||||
mine = max(0.0, math.sin(math.radians(sun_position(mid, lat, lon)[0])))
|
||||
ghi = h.solar_kwh_m2 * 1000 * (4 * mine / sum(sines)) if sum(sines) > 0 else 0.0
|
||||
kinds.add("irradiance")
|
||||
elif clim is not None and (h is None or h.cloud_pct is None):
|
||||
# no weather: the clear sky's shape, scaled to the month's mean day
|
||||
day = mid.astimezone(timezone.utc).date()
|
||||
if day not in day_scale:
|
||||
shape = clear_day_kwh(mid, lat, lon, tilt, azimuth)
|
||||
day_scale[day] = climate_day_kwh(mid, clim, kwp, pr) / shape if shape > 0 else 0.0
|
||||
kinds.add("climatology")
|
||||
ghi = clear_sky_ghi(sun_position(mid, lat, lon)[0])
|
||||
p = power_kw(poa(ghi, mid, lat, lon, tilt, azimuth), 1.0, 1.0, None) * day_scale[day]
|
||||
out.append(round(p * 0.25, 4))
|
||||
continue
|
||||
else:
|
||||
cloud = h.cloud_pct if h is not None and h.cloud_pct is not None else FALLBACK_CLOUD
|
||||
kinds.add("cloud" if h is not None and h.cloud_pct is not None else "clear-sky")
|
||||
ghi = cloud_dimmed(clear_sky_ghi(sun_position(mid, lat, lon)[0]), cloud)
|
||||
p = power_kw(poa(ghi, mid, lat, lon, tilt, azimuth), kwp, pr, h.temp_c if h is not None else None)
|
||||
out.append(round(p * 0.25, 4))
|
||||
kind = next(iter(kinds)) if len(kinds) == 1 else "cloud"
|
||||
return out, kind
|
||||
|
||||
|
||||
# ---- the inverter's AC limit ------------------------------------------------
|
||||
#
|
||||
# The calibration to the plant (its metered history: shading, soiling, a
|
||||
# wrong kWp, the inverter) is pvcalib.py, one implementation for the
|
||||
# trainer and the Mieterstrom / GGV pricing.
|
||||
|
||||
|
||||
def clip(pv: list[float], ac_kw: float) -> list[float]:
|
||||
"""kWh per slot at most the inverter's AC limit (0: none)."""
|
||||
return [min(v, ac_kw * 0.25) for v in pv] if ac_kw > 0 else list(pv)
|
||||
@@ -0,0 +1,232 @@
|
||||
# Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
|
||||
"""A steady plan: no command for a change that does not matter (sim-munich-1
|
||||
in auto, 2026-11-03: a battery set 4.7 times an hour in steps of 50-150 W,
|
||||
its mode switched 2.9 times an hour, a heat pump's setpoint 20.5 and back to
|
||||
20.0 every quarter hour).
|
||||
|
||||
The optimiser's plan is exact to the watt and the tenth of a kelvin; every
|
||||
small difference became a command. Here, after the solve (controller.py
|
||||
make_plan), each control's plan entries are walked in time order from what
|
||||
the device is set to now, and a change is kept out of the plan (the entry
|
||||
keeps the value in force, its why says so) unless all hold:
|
||||
|
||||
deadband it changes enough: a battery's power by max(300 W, 10 % of its
|
||||
max), a setpoint by 0.5 K, an EV's current by 2 A (any change
|
||||
of on/off or mode counts: a battery's self-consumption is no
|
||||
power of its own, it follows the house)
|
||||
lasts a temperature: the plan keeps the new value for 30 minutes
|
||||
(a one-step blip is no command)
|
||||
hold the control's last change of the same kind is older than its
|
||||
hold: a mode (a battery's manual/self-consumption, a climate's
|
||||
off/heat, an EV's on/off) params.hold_mode_s (30 min), a
|
||||
setpoint params.hold_set_s (15 min); the first from the agent's
|
||||
last command (the guard's record), later ones from the plan
|
||||
gain a battery's setpoint: the energy the change moves over its
|
||||
hold, valued at the most a kWh can be worth moved in the
|
||||
horizon (its dearest import price less the lower of its
|
||||
cheapest import and feed-in price), at least
|
||||
params.min_gain_ct (1 ct): an upper bound, so only changes that
|
||||
cannot be worth a cent are kept
|
||||
|
||||
Not here, so never held back: the console's and the building's commands,
|
||||
the safe defaults, the grid operator's order (the plan is made again at
|
||||
once within its bounds; a kept value outside the bounds in force is never
|
||||
kept), the owner's own changes (the guard's hands off) and the guard's
|
||||
floors. The entry the plan made is kept in the entry as "planned".
|
||||
"""
|
||||
import math
|
||||
|
||||
MIN_BATTERY_W = 300.0
|
||||
BATTERY_SHARE = 0.10
|
||||
TEMP_K = 0.5
|
||||
EV_A = 2.0
|
||||
LASTS_S = 1800.0
|
||||
SAME_K = 0.25
|
||||
AUTO = "auto" # a battery in its own self-consumption mode (a plan entry's "auto")
|
||||
|
||||
|
||||
def _num(v):
|
||||
try:
|
||||
x = float(v)
|
||||
except (TypeError, ValueError):
|
||||
return None
|
||||
return x if math.isfinite(x) else None
|
||||
|
||||
|
||||
def current(c, col):
|
||||
"""What the device is set to now, in a plan entry's terms (None:
|
||||
unknown, the plan is followed as it is)."""
|
||||
e = c.entities
|
||||
if c.kind == "battery":
|
||||
if "setpoint" not in e:
|
||||
return None
|
||||
if "mode" in e and col.state(e["mode"]) == str(c.p("auto_option")):
|
||||
return AUTO
|
||||
return _num(col.state(e["setpoint"]))
|
||||
if c.kind in ("heating", "cooling"):
|
||||
if "climate" in e:
|
||||
if col.state(e["climate"]) in ("off", None):
|
||||
return "off" if col.state(e["climate"]) == "off" else None
|
||||
return _num(col.attr(e["climate"], "temperature"))
|
||||
if "switch" in e:
|
||||
s = col.state(e["switch"])
|
||||
return s if s in ("on", "off") else None
|
||||
return None
|
||||
if c.kind == "ev":
|
||||
if col.state(e.get("switch", "")) == "off":
|
||||
return "off"
|
||||
return _num(col.state(e["current"])) if "current" in e else None
|
||||
return None
|
||||
|
||||
|
||||
def _val(c, e):
|
||||
"""A plan entry's value: its set, or a battery's AUTO."""
|
||||
return AUTO if c.kind == "battery" and e.get("auto") else e["set"]
|
||||
|
||||
|
||||
def _big(c, old, new) -> bool:
|
||||
if c.kind == "battery":
|
||||
top = max(float(c.p("max_charge_w")), float(c.p("max_discharge_w")))
|
||||
return abs(new - old) >= max(MIN_BATTERY_W, BATTERY_SHARE * top) - 1e-9
|
||||
if c.kind in ("heating", "cooling"):
|
||||
return abs(new - old) >= TEMP_K - 1e-9
|
||||
if c.kind == "ev":
|
||||
return abs(new - old) >= EV_A - 1e-9
|
||||
return True
|
||||
|
||||
|
||||
def _same(a, b) -> bool:
|
||||
if isinstance(a, str) or isinstance(b, str):
|
||||
return a == b
|
||||
return abs(a - b) < SAME_K
|
||||
|
||||
|
||||
def _lasts(c, entries, i, end) -> float:
|
||||
"""How long the plan keeps entry i's value (s)."""
|
||||
v = _val(c, entries[i])
|
||||
for e in entries[i + 1:]:
|
||||
if not _same(_val(c, e), v):
|
||||
return e["t"] - entries[i]["t"]
|
||||
return end - entries[i]["t"]
|
||||
|
||||
|
||||
def _within(bounds, v) -> bool:
|
||||
if not bounds or isinstance(v, str):
|
||||
return True
|
||||
lo, hi = bounds[0], bounds[1]
|
||||
return (lo is None or v >= lo - 1e-9) and (hi is None or v <= hi + 1e-9)
|
||||
|
||||
|
||||
def stabilise(plan: dict, state: dict, controls, col, last_set=None, now: float | None = None) -> dict:
|
||||
"""The plan with changes that do not matter kept out (module
|
||||
docstring). last_set(control id, kind "mode"|"set") -> when the agent
|
||||
last changed that (None: not known). In place; returns the plan."""
|
||||
now = plan.get("made", 0) if now is None else now
|
||||
step = plan.get("step_s", 900)
|
||||
end = plan.get("start", now) + step * state.get("steps", 192)
|
||||
prices = state.get("price_import") or []
|
||||
feed = state.get("price_export") or []
|
||||
spread = (max(prices) - min(prices + feed)) if prices else 0.0 # ct per kWh, at most
|
||||
devs = {d["id"]: d for d in state.get("devices") or []}
|
||||
kept_n = 0
|
||||
for c in controls:
|
||||
entries = (plan.get("devices") or {}).get(c.id)
|
||||
if not entries or c.kind not in ("battery", "heating", "cooling", "ev"):
|
||||
continue
|
||||
cur = current(c, col)
|
||||
if cur is None:
|
||||
continue
|
||||
p = devs.get(c.id, {}).get("params") or {}
|
||||
hold = {"mode": float(p.get("hold_mode_s", c.p("hold_mode_s"))),
|
||||
"set": float(p.get("hold_set_s", c.p("hold_set_s")))}
|
||||
min_gain = float(p.get("min_gain_ct", c.p("min_gain_ct")))
|
||||
bq = {"battery": "power_w", "heating": "temp_c", "cooling": "temp_c", "ev": "current_a"}[c.kind]
|
||||
bounds = (devs.get(c.id, {}).get("bounds") or {}).get(bq)
|
||||
changed = {}
|
||||
for k in ("mode", "set"):
|
||||
t = last_set(c.id, k) if last_set else None
|
||||
changed[k] = t if t is not None else -1e18
|
||||
raw = [dict(e) for e in entries]
|
||||
out = []
|
||||
for i, e in enumerate(raw):
|
||||
new = _val(c, e)
|
||||
if _same(cur, new):
|
||||
kind = None
|
||||
elif isinstance(cur, str) or isinstance(new, str):
|
||||
kind = "mode" # on/off, a climate's off, a battery's auto
|
||||
else:
|
||||
kind = "set"
|
||||
if kind is None:
|
||||
out.append(e)
|
||||
continue
|
||||
if kind == "mode" and c.kind in ("heating", "cooling") and "climate" not in c.entities:
|
||||
kind = "set" # a boiler's on/off is its setpoint
|
||||
t = max(e["t"], now)
|
||||
why = ""
|
||||
if not _within(bounds, cur):
|
||||
why = "" # what is set now is outside the bounds: change
|
||||
elif kind == "set" and not isinstance(new, str) and not _big(c, cur, new):
|
||||
why = f"kept: a change of {_amount(c, cur, new)} is below the deadband"
|
||||
elif c.kind in ("heating", "cooling") and _lasts(c, raw, i, end) < LASTS_S:
|
||||
why = f"kept: the plan holds {new:g} for less than {LASTS_S / 60:.0f} min" if not isinstance(new, str) \
|
||||
else f"kept: the plan is {new} for less than {LASTS_S / 60:.0f} min"
|
||||
elif t - changed[kind] < hold[kind]:
|
||||
why = f"kept: changed {int((t - changed[kind]) // 60)} min ago (hold {hold[kind] / 60:.0f} min)"
|
||||
elif c.kind == "battery" and kind == "set" and prices:
|
||||
gain = abs(new - cur) * hold["set"] / 3600 / 1000 * spread
|
||||
if gain < min_gain:
|
||||
why = f"kept: gain below {min_gain:g} ct ({gain:.2f} ct)"
|
||||
if why:
|
||||
kept_n += 1
|
||||
ke = {"t": e["t"], "set": cur, "why": why, "planned": e["set"]}
|
||||
if c.kind == "battery":
|
||||
ke["grid"] = bool(out[-1].get("grid")) if out and "grid" in out[-1] else cur != AUTO and cur > 0
|
||||
if cur == AUTO:
|
||||
ke.update(set=e["set"], auto=True)
|
||||
out.append(ke)
|
||||
continue
|
||||
out.append(e)
|
||||
cur = new
|
||||
changed[kind] = t
|
||||
if kind == "mode" and c.kind != "battery":
|
||||
changed["set"] = t
|
||||
# a plan lists changes only
|
||||
merged = []
|
||||
for e in out:
|
||||
if merged and _same(_val(c, merged[-1]), _val(c, e)) and \
|
||||
(merged[-1].get("grid") == e.get("grid") or _val(c, e) == AUTO):
|
||||
continue
|
||||
merged.append(e)
|
||||
plan["devices"][c.id] = merged
|
||||
plan["kept"] = kept_n
|
||||
return plan
|
||||
|
||||
|
||||
def _amount(c, a, b) -> str:
|
||||
unit = {"battery": "W", "heating": "K", "cooling": "K", "ev": "A"}[c.kind]
|
||||
d = abs(b - a)
|
||||
return f"{d:.0f} {unit}" if unit == "W" else f"{d:.1f} {unit}"
|
||||
|
||||
|
||||
def carry_quarter(plan: dict, old: dict | None, now: float) -> dict:
|
||||
"""A plan made in the middle of a quarter hour for no urgent reason (a
|
||||
tariff or model bundle came): the quarter under way keeps the values of
|
||||
the plan in force; the new plan decides from the next quarter on. Each
|
||||
plan reckons the quarter from its own start with the room as it is when
|
||||
it is made, and two plans in one quarter set a heat pump to 20.5 and
|
||||
back to 20.0 (sim-munich-1). In place; returns the plan."""
|
||||
if not old or old.get("start") != plan.get("start"):
|
||||
return plan
|
||||
nxt = plan["start"] + plan["step_s"]
|
||||
for cid, entries in (plan.get("devices") or {}).items():
|
||||
prev = [e for e in (old.get("devices") or {}).get(cid) or [] if e["t"] <= now]
|
||||
if not prev or not entries:
|
||||
continue
|
||||
keep = dict(prev[-1], t=plan["start"])
|
||||
rest = [e for e in entries if e["t"] >= nxt]
|
||||
if not rest or rest[0]["t"] > nxt:
|
||||
at = [e for e in entries if e["t"] < nxt]
|
||||
if at:
|
||||
rest.insert(0, dict(at[-1], t=nxt)) # the new plan's value from the next quarter
|
||||
plan["devices"][cid] = [keep] + rest
|
||||
return plan
|
||||
@@ -14,6 +14,7 @@ dependencies = [
|
||||
"nats-py==2.10.0",
|
||||
"PyYAML==6.0.2",
|
||||
"highspy==1.11.0", # the optimiser (HiGHS MILP), v1
|
||||
"numpy==2.3.5", # the box's forecast models (localml.py, fcmodels.py): as building/requirements.txt
|
||||
]
|
||||
|
||||
[project.optional-dependencies]
|
||||
|
||||
@@ -0,0 +1,188 @@
|
||||
# Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
|
||||
"""The box's own forecast models (localml.py, methods.md B9): the bundle's
|
||||
"models" and "weather" keys, LightGBM's decision rule in lgbtrees, the
|
||||
switch from the cloud's forecast to the box's model where the series no
|
||||
longer covers a step, the hour-of-week last. The parity with the cloud's
|
||||
LightGBM on a trained model: building/test_boxmodel.py."""
|
||||
import json
|
||||
import math
|
||||
from datetime import datetime, timezone
|
||||
|
||||
import pytest
|
||||
|
||||
from cantabile_edge import fcmodels, lgbtrees, localml
|
||||
from cantabile_edge.bundles import Bundles, _check_model
|
||||
from cantabile_edge.inputs import Collector, History, model_state
|
||||
|
||||
from test_base_load import gauge, site_mapping, watts
|
||||
from test_control_parts import SITE
|
||||
|
||||
START = 1_800_000_000 // 3600 * 3600 # a Friday, on the hour (UTC)
|
||||
LAT, LON = 51.34, 12.37
|
||||
|
||||
|
||||
def leaf(i, v):
|
||||
return {"leaf_index": i, "leaf_value": v}
|
||||
|
||||
|
||||
def split(i, f, threshold, left, right, default_left=True, missing="None"):
|
||||
return {"split_index": i, "split_feature": f, "threshold": threshold, "decision_type": "<=",
|
||||
"default_left": default_left, "missing_type": missing, "left_child": left, "right_child": right}
|
||||
|
||||
|
||||
def trees():
|
||||
"""Two trees on the load's features: lag7 (index 4) above 1000 W: 900,
|
||||
else 300 (a NaN lag: left); the afternoon (hod > 12): +100."""
|
||||
return lgbtrees.pack({"objective": "regression", "tree_info": [
|
||||
{"tree_structure": split(0, 4, 1000.0, leaf(0, 300.0), leaf(1, 900.0), True, "NaN")},
|
||||
{"tree_structure": split(0, 0, 12.0, leaf(0, 0.0), leaf(1, 100.0))}]})
|
||||
|
||||
|
||||
def gbm(features=None):
|
||||
return {"params": {"kind": "gbm", "features": features or list(fcmodels.LOAD_FEATURES), "how": [0.0] * 168,
|
||||
"tz": "UTC", "cap_w": None, "trees": trees()},
|
||||
"site": {"tz": "UTC", "lat": LAT, "lon": LON}}
|
||||
|
||||
|
||||
def weather(hours=48, start=START):
|
||||
return [{"end": start + h * 3600, "solar": None, "cloud": 50.0, "temp": 5.0} for h in range(hours + 1)]
|
||||
|
||||
|
||||
def bundle(series_start=START - 40 * 3600, models=None, wx=None, n=192):
|
||||
fc = {"profile": "hour_of_week", "values": [111.0] * 168,
|
||||
"series": {"start": series_start, "step_s": 900, "values": [5000.0] * n}}
|
||||
m = {"v": 1, "kind": "model", "id": "m1", "site": SITE, "issued": series_start, "forecasts": {"base_load_w": fc}}
|
||||
if models is not None:
|
||||
m["models"] = models
|
||||
if wx is not None:
|
||||
m["weather"] = wx
|
||||
return m
|
||||
|
||||
|
||||
def put(tmp_path, m):
|
||||
(tmp_path / "model.json").write_text(json.dumps(m))
|
||||
return Bundles(str(tmp_path), SITE)
|
||||
|
||||
|
||||
def history(tmp_path, value=2000.0):
|
||||
h = History(str(tmp_path / "history.json"))
|
||||
for k in range(8 * 96):
|
||||
h.slots["load_w"][START - 8 * 86400 + k * 900] = [value, 1]
|
||||
return h
|
||||
|
||||
|
||||
def state(tmp_path, b, h, ha=None):
|
||||
m = site_mapping(tmp_path, [], [])
|
||||
col = Collector()
|
||||
watts(col, sensor__load=700)
|
||||
return model_state(START, [], m.inputs, col, b, h, "UTC", ha)
|
||||
|
||||
|
||||
# -- the trees ------------------------------------------------------------------
|
||||
def test_lightgbms_decision_rule():
|
||||
t = lgbtrees.Trees(lgbtrees.pack({"objective": "regression", "tree_info": [
|
||||
{"tree_structure": split(0, 0, 1.5, leaf(0, 1.0), leaf(1, 2.0), True, "NaN")},
|
||||
{"tree_structure": split(0, 0, 1.5, leaf(0, 10.0), leaf(1, 20.0), False, "None")},
|
||||
{"tree_structure": split(0, 1, -0.5, leaf(0, 100.0), leaf(1, 200.0), True, "Zero")},
|
||||
{"tree_structure": {"leaf_value": 1000.0}}]}), 2)
|
||||
assert t.predict_row([1.5, 1.0]) == 1.0 + 10.0 + 200.0 + 1000.0 # <= goes left
|
||||
assert t.predict_row([1.6, 1.0]) == 2.0 + 20.0 + 200.0 + 1000.0
|
||||
# NaN: its default way where the split knows NaN, else as 0 (left of 1.5)
|
||||
assert t.predict_row([math.nan, 1.0]) == 1.0 + 10.0 + 200.0 + 1000.0
|
||||
# a zero on a split whose missing values are zeros: its default way (left), not by the threshold
|
||||
assert t.predict_row([2.0, 0.0]) == 2.0 + 20.0 + 100.0 + 1000.0
|
||||
assert t.predict_row([2.0, math.nan]) == 2.0 + 20.0 + 100.0 + 1000.0 # NaN counts 0: a zero
|
||||
|
||||
|
||||
def test_bad_trees_are_refused():
|
||||
good = trees()
|
||||
lgbtrees.Trees(good, 9)
|
||||
for bad in (dict(good, enc="onnx"), dict(good, n=3), dict(good, data="!!"), dict(good, data=good["data"][:20])):
|
||||
with pytest.raises(ValueError):
|
||||
lgbtrees.Trees(bad, 9)
|
||||
with pytest.raises(ValueError):
|
||||
lgbtrees.Trees(good, 3) # a split on a feature it does not have
|
||||
loop = lgbtrees.pack({"objective": "regression", "tree_info": [{"tree_structure": split(
|
||||
0, 0, 1.0, split(1, 0, 2.0, leaf(0, 1.0), leaf(1, 2.0)), leaf(2, 3.0))}]})
|
||||
lgbtrees.Trees(loop, 1)
|
||||
|
||||
|
||||
# -- the bundle ------------------------------------------------------------------
|
||||
def test_a_bundle_with_the_new_keys_is_accepted_and_one_without_still_works(tmp_path):
|
||||
m = bundle(models={"base_load_w": gbm()}, wx=weather())
|
||||
_check_model(m) # the release's check: the new keys are not looked at
|
||||
b = put(tmp_path, m)
|
||||
assert b.model.get() is not None and b.box_model("base_load_w") is not None
|
||||
assert b.model_info()["box_models"] == ["base_load_w"]
|
||||
b = put(tmp_path, bundle())
|
||||
assert b.model.get() is not None and b.box_model("base_load_w") is None
|
||||
s = state(tmp_path, b, history(tmp_path))
|
||||
assert s["sources"]["load"] == "model (base_load_w)"
|
||||
assert s["load_w"][0] == 5000.0 and s["load_w"][-1] == 111.0 # the series, then the profile
|
||||
assert s["sources"]["forecast"]["load"] == {"series": "base_load_w", "cloud": 32, "box": 0, "hour_of_week": 160}
|
||||
|
||||
|
||||
def test_a_model_the_box_cannot_run_is_left_out(tmp_path):
|
||||
b = put(tmp_path, bundle(models={"base_load_w": gbm(["hod", "temp"]), "pv_w": {"params": {"kind": "arima"}}},
|
||||
wx=weather()))
|
||||
assert b.box_model("base_load_w") is None and b.box_model("pv_w") is None
|
||||
assert set(b.box_errors) == {"base_load_w", "pv_w"}
|
||||
s = state(tmp_path, b, history(tmp_path))
|
||||
assert s["load_w"][0] == 5000.0 and s["load_w"][-1] == 111.0 # the rest of the bundle stays
|
||||
|
||||
|
||||
def test_the_box_takes_the_steps_the_cloud_no_longer_covers(tmp_path):
|
||||
"""The cloud's series of 40 h ago covers the first 8 h; the box's own
|
||||
model the rest where the weather reaches (the cloud's 48 h), the
|
||||
hour-of-week after."""
|
||||
b = put(tmp_path, bundle(models={"base_load_w": gbm()}, wx=weather(30)))
|
||||
s = state(tmp_path, b, history(tmp_path, 2000.0))
|
||||
load, src = s["load_w"], s["sources"]
|
||||
assert load[:32] == [5000.0] * 32 # the cloud's while it covers
|
||||
assert load[32] == 900.0 + 100.0 and load[64] == 900.0 # lag7 2000 W: 900; 16:00 UTC: +100
|
||||
assert load[-1] == 111.0 # beyond the weather: the profile
|
||||
f = src["forecast"]["load"]
|
||||
assert f["cloud"] == 32 and f["box"] == 30 * 4 - 32 and f["hour_of_week"] == 192 - 30 * 4
|
||||
assert f["box_model"] == "gbm" and "the cloud's weather" in f["box_weather"]
|
||||
assert src["load"].startswith("model (base_load_w); the box's own gbm model for 88 of 192 steps")
|
||||
# no lag in the history (a NaN): the tree's NaN way, left
|
||||
b2 = put(tmp_path, bundle(models={"base_load_w": gbm()}, wx=weather(30)))
|
||||
s = state(tmp_path, b2, History(str(tmp_path / "none.json")))
|
||||
assert s["load_w"][32] == 300.0 + 100.0
|
||||
|
||||
|
||||
def test_home_assistants_weather_first(tmp_path):
|
||||
b = put(tmp_path, bundle(models={"base_load_w": gbm()}, wx=weather(10)))
|
||||
ha = [{"datetime": datetime.fromtimestamp(START + h * 3600, timezone.utc).isoformat(),
|
||||
"temperature": 4.0, "cloud_coverage": 80} for h in range(49)]
|
||||
s = state(tmp_path, b, history(tmp_path), ha)
|
||||
f = s["sources"]["forecast"]["load"]
|
||||
assert f["box"] == 160 and f["hour_of_week"] == 0
|
||||
assert f["box_weather"].startswith("Home Assistant's forecast")
|
||||
|
||||
|
||||
def test_a_fresh_cloud_forecast_is_used_as_it_is(tmp_path, monkeypatch):
|
||||
b = put(tmp_path, bundle(series_start=START, models={"base_load_w": gbm()}, wx=weather()))
|
||||
monkeypatch.setattr(b, "box_forecast", lambda *a, **k: pytest.fail("the box's model while the cloud's covers"))
|
||||
s = state(tmp_path, b, history(tmp_path))
|
||||
assert s["load_w"] == [5000.0] * 192 and s["sources"]["load"] == "model (base_load_w)"
|
||||
|
||||
|
||||
def test_once_per_quarter_hour(tmp_path, monkeypatch):
|
||||
b = put(tmp_path, bundle(models={"base_load_w": gbm()}, wx=weather()))
|
||||
calls = []
|
||||
real = localml.predict
|
||||
monkeypatch.setattr(localml, "predict", lambda *a, **k: calls.append(1) or real(*a, **k))
|
||||
h = history(tmp_path)
|
||||
state(tmp_path, b, h)
|
||||
state(tmp_path, b, h)
|
||||
assert len(calls) == 1
|
||||
|
||||
|
||||
def test_the_history_keeps_eight_days(tmp_path):
|
||||
h = History(str(tmp_path / "history.json"))
|
||||
for d in range(10):
|
||||
h.add("load_w", 500.0, START - d * 86400)
|
||||
h.save(START)
|
||||
h2 = History(str(tmp_path / "history.json"))
|
||||
assert sorted(h2.slots["load_w"]) == [START - d * 86400 for d in range(8, -1, -1)]
|
||||
@@ -0,0 +1,206 @@
|
||||
# Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
|
||||
"""No command flapping (sim-munich-1 in auto, 2026-11-03): plans at the
|
||||
quarter hour, the quarter under way kept by a bundle's plan, a deadband,
|
||||
a hold and a least gain per change (steady.py), the battery's
|
||||
self-consumption mode where the plan's battery balances the house, a
|
||||
thermostat at its target while no heat is planned, honest labels."""
|
||||
import pytest
|
||||
|
||||
from cantabile_edge import steady
|
||||
from cantabile_edge.controller import plan_wait
|
||||
from cantabile_edge.controls import Control
|
||||
from cantabile_edge.executor import actions_for
|
||||
from cantabile_edge.inputs import Collector
|
||||
|
||||
T0 = 1_800_000_000 // 900 * 900 # a quarter hour
|
||||
|
||||
|
||||
def bat():
|
||||
return Control("battery", "battery", {"setpoint": "number.bp", "mode": "select.bm"}, True,
|
||||
{"capacity_wh": 10000, "max_charge_w": 2500, "max_discharge_w": 2500})
|
||||
|
||||
|
||||
def hp(**params):
|
||||
return Control("hp", "heating", {"climate": "climate.hp"}, True, dict({"cop": 3.0}, **params))
|
||||
|
||||
|
||||
def car():
|
||||
return Control("car", "ev", {"switch": "switch.wb", "current": "number.wb_a"}, True, {})
|
||||
|
||||
|
||||
def col_with(**kv):
|
||||
col = Collector()
|
||||
col.on_entities({"a": {k.replace("__", "."): {"s": v[0], "a": v[1] if len(v) > 1 else {}} for k, v in kv.items()}})
|
||||
return col
|
||||
|
||||
|
||||
def plan_of(cid, entries, steps=8):
|
||||
return {"made": T0, "start": T0, "step_s": 900,
|
||||
"devices": {cid: [dict({"t": T0 + 900 * k, "why": "plan"}, **e) for k, e in entries]}}
|
||||
|
||||
|
||||
def state(steps=8, price=None, devices=(), export=8.0):
|
||||
return {"steps": steps, "price_import": price or [30.0] * steps, "price_export": [export] * steps,
|
||||
"devices": list(devices)}
|
||||
|
||||
|
||||
# -- 1. the cause: plans at the quarter hour ------------------------------------------------
|
||||
def test_plans_at_the_quarter_hour():
|
||||
assert plan_wait(T0 + 12 * 60, 900) == pytest.approx(3 * 60 + 5) # made at :12: the next at :15:05
|
||||
assert plan_wait(T0 + 5, 900) == pytest.approx(900) # made at :00:05: the next at :15:05
|
||||
assert plan_wait(T0 + 4, 900) == pytest.approx(1) # just before: at once (at least 1 s)
|
||||
assert plan_wait(T0 + 60, 900) == pytest.approx(845)
|
||||
|
||||
|
||||
def test_a_bundles_plan_keeps_the_quarter_under_way():
|
||||
old = plan_of("hp", [(0, {"set": 20.5}), (1, {"set": 20.0})])
|
||||
new = plan_of("hp", [(0, {"set": 20.0}), (2, {"set": 21.0})])
|
||||
steady.carry_quarter(new, old, T0 + 12 * 60)
|
||||
assert [(e["t"] - T0, e["set"]) for e in new["devices"]["hp"]] == [(0, 20.5), (900, 20.0), (1800, 21.0)]
|
||||
# a plan of the next quarter: as it is
|
||||
nxt = plan_of("hp", [(0, {"set": 20.0})])
|
||||
nxt["start"] = T0 + 900
|
||||
assert steady.carry_quarter(nxt, old, T0 + 960)["devices"]["hp"][0]["set"] == 20.0
|
||||
|
||||
|
||||
# -- 2. deadband ----------------------------------------------------------------------------
|
||||
def test_battery_deadband_and_its_mode():
|
||||
col = col_with(number__bp=("1200",), select__bm=("manual",))
|
||||
p = plan_of("battery", [(0, {"set": 1350.0, "grid": True}), (1, {"set": 200.0, "grid": True}),
|
||||
(2, {"set": 150.0, "grid": True})])
|
||||
steady.stabilise(p, state(), [bat()], col, None, T0)
|
||||
got = [(e["t"] - T0, e["set"], e["why"][:30]) for e in p["devices"]["battery"]]
|
||||
# 150 W off 1200: kept (deadband 300 W); 1000 W off: done; 50 W off that: kept
|
||||
assert got[0][1] == 1200.0 and got[0][2].startswith("kept: a change of 150 W")
|
||||
assert got[1][:2] == (900, 200.0)
|
||||
assert len(got) == 2 and p["kept"] == 2
|
||||
|
||||
|
||||
def test_temperature_needs_half_a_kelvin_and_half_an_hour():
|
||||
col = col_with(climate__hp=("heat", {"temperature": 20.0}))
|
||||
# the see-saw: 20.5 for one quarter, then 20.0 again: no command
|
||||
p = plan_of("hp", [(0, {"set": 20.5}), (1, {"set": 20.0}), (2, {"set": 20.5}), (3, {"set": 20.0})])
|
||||
steady.stabilise(p, state(), [hp()], col, None, T0)
|
||||
assert [e["set"] for e in p["devices"]["hp"]] == [20.0]
|
||||
assert "less than 30 min" in p["devices"]["hp"][0]["why"]
|
||||
# 21 for an hour: done
|
||||
p = plan_of("hp", [(0, {"set": 21.0}), (4, {"set": 20.0})])
|
||||
steady.stabilise(p, state(), [hp()], col, None, T0)
|
||||
assert [e["set"] for e in p["devices"]["hp"]] == [21.0, 20.0]
|
||||
|
||||
|
||||
def test_ev_current_two_amps():
|
||||
col = col_with(switch__wb=("on",), number__wb_a=("10",))
|
||||
p = plan_of("car", [(0, {"set": 11}), (1, {"set": 13})])
|
||||
steady.stabilise(p, state(), [car()], col, None, T0)
|
||||
assert [e["set"] for e in p["devices"]["car"]] == [10.0, 13]
|
||||
|
||||
|
||||
# -- 3. hold ----------------------------------------------------------------------------------
|
||||
def test_hold_per_kind_and_configurable():
|
||||
col = col_with(number__bp=("1500",), select__bm=("manual",))
|
||||
last = {("battery", "mode"): T0 - 600, ("battery", "set"): T0 - 300}
|
||||
p = plan_of("battery", [(0, {"set": 0.0, "grid": False, "auto": True})])
|
||||
steady.stabilise(p, state(), [bat()], col, lambda c, k: last.get((c, k)), T0)
|
||||
e = p["devices"]["battery"][0]
|
||||
assert e["set"] == 1500.0 and "changed 10 min ago (hold 30 min)" in e["why"]
|
||||
# the same with a 5-minute hold for modes (params.hold_mode_s)
|
||||
b = bat()
|
||||
b.params["hold_mode_s"] = 300
|
||||
p = plan_of("battery", [(0, {"set": 0.0, "grid": False, "auto": True})])
|
||||
steady.stabilise(p, state(), [b], col, lambda c, k: last.get((c, k)), T0)
|
||||
assert p["devices"]["battery"][0].get("auto") is True
|
||||
# a setpoint 5 minutes after the last: held for 15 minutes, then done
|
||||
p = plan_of("battery", [(0, {"set": 2500.0, "grid": True}), (1, {"set": 2500.0, "grid": True})])
|
||||
steady.stabilise(p, state(price=[10.0] + [40.0] * 7), [bat()], col, lambda c, k: last.get((c, k)), T0)
|
||||
assert [(e["t"] - T0, e["set"]) for e in p["devices"]["battery"]] == [(0, 1500.0), (900, 2500.0)]
|
||||
|
||||
|
||||
# -- 4. gain ----------------------------------------------------------------------------------
|
||||
def test_least_gain():
|
||||
col = col_with(number__bp=("1000",), select__bm=("manual",))
|
||||
# 1000 -> 1500 W where a kWh is worth nothing moved (one price, feed-in at it): kept
|
||||
p = plan_of("battery", [(0, {"set": 1500.0, "grid": True})])
|
||||
steady.stabilise(p, state(export=30.0), [bat()], col, None, T0)
|
||||
assert p["devices"]["battery"][0]["set"] == 1000.0 and "gain below 1 ct" in p["devices"]["battery"][0]["why"]
|
||||
p = plan_of("battery", [(0, {"set": 1500.0, "grid": True})])
|
||||
steady.stabilise(p, state(price=[10.0] + [40.0] * 7), [bat()], col, None, T0)
|
||||
assert p["devices"]["battery"][0]["set"] == 1500.0 # 0.5 kW x 15 min x 32 ct = 4 ct
|
||||
p = plan_of("battery", [(0, {"set": 1500.0, "grid": True})])
|
||||
b = bat()
|
||||
b.params["min_gain_ct"] = 5.0
|
||||
steady.stabilise(p, state(price=[10.0] + [40.0] * 7), [b], col, None, T0)
|
||||
assert p["devices"]["battery"][0]["set"] == 1000.0
|
||||
|
||||
|
||||
# -- exceptions -------------------------------------------------------------------------------
|
||||
def test_a_value_outside_the_bounds_is_never_kept():
|
||||
"""The grid operator's order (or a new limit) lowered the bound under
|
||||
what is set: the plan's value goes, deadband or not."""
|
||||
col = col_with(switch__wb=("on",), number__wb_a=("16",))
|
||||
p = plan_of("car", [(0, {"set": 15})])
|
||||
d = {"id": "car", "params": {}, "bounds": {"current_a": [0, 15.0, "device", "grid"]}}
|
||||
steady.stabilise(p, state(devices=[d]), [car()], col, None, T0)
|
||||
assert p["devices"]["car"][0]["set"] == 15
|
||||
|
||||
|
||||
def test_guard_records_the_changes():
|
||||
from cantabile_edge.consent import Consent
|
||||
from cantabile_edge.guard import Action, Guard
|
||||
import tempfile
|
||||
with tempfile.TemporaryDirectory() as d:
|
||||
g = Guard([bat(), hp(), Control("boiler", "heating", {"switch": "switch.b"}, True, {})], Consent(d),
|
||||
clock=lambda: T0)
|
||||
g.done(Action("battery", "mode", "select.bm", "select", "select_option", {}, "manual"))
|
||||
g.done(Action("battery", "setpoint", "number.bp", "number", "set_value", {}, 100.0, "power_w"))
|
||||
g.done(Action("boiler", "switch", "switch.b", "switch", "turn_on", {}, "on"))
|
||||
assert g.last_change("battery", "mode") == T0 and g.last_change("battery", "set") == T0
|
||||
assert g.last_change("boiler", "set") == T0 and g.last_change("boiler", "mode") is None
|
||||
|
||||
|
||||
# -- the battery's own mode, the thermostat, the labels ------------------------------------------
|
||||
def test_battery_self_consumption_and_hold():
|
||||
pytest.importorskip("highspy")
|
||||
from cantabile_edge import optimizer
|
||||
from test_optimizer import battery, house
|
||||
s = house([battery(soc=50, floor=10)], steps=16)
|
||||
s["price_import"] = [40.0] * 8 + [20.0] * 8 # dear now, cheap later: cover the house now
|
||||
p = optimizer.plan(s, 10)
|
||||
first = p["devices"]["battery"][0]
|
||||
assert first.get("auto") is True and first["why"].startswith("self-consumption")
|
||||
col = col_with(number__bp=("700",), select__bm=("manual",))
|
||||
acts = actions_for(bat(), first, col)
|
||||
assert [(a.service, a.value) for a in acts] == [("select_option", "self-consumption")] # no setpoint
|
||||
# hold (0 W while the grid supplies the house): manual at 0, not self-consumption (it would discharge)
|
||||
acts = actions_for(bat(), {"set": 0.0, "grid": False}, col)
|
||||
assert [(a.service, a.value) for a in acts] == [("set_value", 0.0)]
|
||||
|
||||
|
||||
def test_thermostat_at_its_target_without_heat():
|
||||
pytest.importorskip("highspy")
|
||||
from cantabile_edge import optimizer
|
||||
from test_optimizer import heating, house
|
||||
d = heating(temp=24.0) # a warm room: no heat for hours
|
||||
s = house([d], steps=16)
|
||||
p = optimizer.plan(s, 10)
|
||||
first = p["devices"]["heating"][0]
|
||||
# not the predicted 23.x (a thermostat would hold it by heating): the target, 17 at night, 21 by day
|
||||
assert first["set"] in (17.0, 21.0) and first["set"] < 23.0
|
||||
|
||||
|
||||
def test_cheap_only_in_the_cheapest_quarter():
|
||||
from cantabile_edge.optimizer import _charge_why
|
||||
pi = [30.0] * 24 + [47.6] * 8 + [50.0] * 16
|
||||
assert _charge_why(pi, 0).startswith("cheap grid power")
|
||||
assert _charge_why(pi, 24).startswith("charge for dearer hours later (47.6 ct now, 50.0 ct")
|
||||
assert _charge_why([50.0] * 4, 3) == "charge from the grid (50.0 ct)"
|
||||
|
||||
|
||||
def test_a_replayed_morning_is_quiet():
|
||||
"""A replay (replay_flapping.py) of three hours: at most 2 commands an
|
||||
hour, the heat pump not every quarter hour."""
|
||||
pytest.importorskip("highspy")
|
||||
import replay_flapping
|
||||
per, total, _eur, _kh = replay_flapping.run(hours=3, steps=48, how="after")
|
||||
assert total <= 2.0, per
|
||||
assert per.get(("heat_pump", "set_temperature"), 0) <= 1.0, per
|
||||
Reference in new issue
Block a user