cantabile_edge, cantabile_modbus, cantabile_eebus 0.1.650: full source

This commit is contained in:
Setti Solutions S.R.L committed 2026-11-04 03:22:07 +02:00
1 parent 85edd56ec8
commit 3edd015039
20 files changed
+2021 -35

No files matched your search

+66 -3
View File
@@ -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
+27 -1
View File
@@ -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)
+9 -4
View File
@@ -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},
+11 -4
View File
@@ -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
+376
View File
@@ -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
+9
View File
@@ -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
+62 -12
View File
@@ -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 []}
+151
View File
@@ -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]
+226
View File
@@ -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
+48 -7
View File
@@ -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":
+199
View File
@@ -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
+206
View File
@@ -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)
+232
View File
@@ -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