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
@@ -22,7 +22,7 @@ Settings → Add-ons → Add-on store → ⋮ → Repositories, add
|
||||
`https://git.setti.solutions/Daniel/cantabile-ha-addons`, then install the
|
||||
add-on. The Supervisor pulls the prebuilt images
|
||||
(`git.setti.solutions/daniel/cantabile-ha-<edge|modbus|eebus>-<arch>:<version>`,
|
||||
named by `image:` in each `config.yaml`); this version: `0.1.629`, arch amd64.
|
||||
named by `image:` in each `config.yaml`); this version: `0.1.650`, arch amd64.
|
||||
|
||||
## Layout
|
||||
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
# the Hub's, wrapped by addon-run (Dockerfile). The image is prebuilt,
|
||||
# per arch (README.md: building it from src/).
|
||||
name: Cantabile Edge Agent
|
||||
version: "0.1.629"
|
||||
version: "0.1.650"
|
||||
slug: cantabile_edge
|
||||
description: Plans your home's energy with Cantabile and, with your consent, runs the devices you choose.
|
||||
url: https://cantabile.cloud
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
# Assistant that isn't a Cantabile Hub. Devices are paired on its page
|
||||
# (ingress), by their SKI.
|
||||
name: Cantabile EEBUS
|
||||
version: "0.1.629"
|
||||
version: "0.1.650"
|
||||
slug: cantabile_eebus
|
||||
description: Pairs with EEBUS devices (the grid operator's control box, heat pumps, wallboxes, inverters), shows them in Home Assistant under Cantabile's names and hands the grid operator's §14a limit to the Cantabile agent; every control with its protection.
|
||||
url: https://cantabile.cloud
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
# Home Assistant that isn't a Cantabile Hub. Devices come from the options;
|
||||
# the page (ingress) shows them and each control's protection.
|
||||
name: Cantabile Modbus bridge
|
||||
version: "0.1.629"
|
||||
version: "0.1.650"
|
||||
slug: cantabile_modbus
|
||||
description: Reads inverters, meters, relays and circuits by Cantabile's device profiles (Modbus, or Home Assistant's own entities) and shows them in Home Assistant, each control with its protection.
|
||||
url: https://cantabile.cloud
|
||||
|
||||
@@ -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