cantabile_edge, cantabile_modbus, cantabile_eebus 0.1.1289: full source

This commit is contained in:
Setti Solutions S.R.L committed 2026-11-08 16:35:35 +02:00
1 parent 165dda4479
commit 05802d6f87
57 files changed
+5928 -232

No files matched your search

+26 -1
View File
@@ -81,6 +81,9 @@ class Agent:
self.control.policy if self.control is not None else None)
if self.control is not None:
self.inventory.ev_phases = self.control.ev_phases
# the Parameters values a hot-water meter's factor may take (dhw.temperature_lift_k)
_pb = self.control.bundles if self.control is not None else Bundles(cfg.state_dir, cfg.site_id)
self.inventory.params = lambda: _pb.box_params(time.time())
# the household's own costs (costs.py, methods.md A12): its meters at the
# prices that applied, kept on the box, shown in HA only; with or
# without the share consent (nothing of it leaves the box)
@@ -220,7 +223,7 @@ class Agent:
v = number(raw)
if v is not None and not a.equals:
# an attribute is in HA's units (a climate's temperature): the asset's own
unit = a.unit if a.attribute else self.units.get(entity_id)
unit = a.ha_unit(self.units.get(entity_id)) # the installer's unit_in over HA's
v = scaled(convert(v, unit, a.unit), a)
if v is None:
log.warning("%s: unit %s cannot become %s; value dropped", a.asset, unit, a.unit)
@@ -317,8 +320,30 @@ class Agent:
log.warning("inventory: %s", e)
# -- windows and uplink -----------------------------------------------
def tank_draws(self, start: float):
"""A tank's draw measured from its own sensors (S.7, storefit) as
dhw.power where no hot-water meter gives it (docs/methods.md B16):
only with the owner's share consent and the tank's temperature
asset consented (the draw is made of it)."""
ctl = getattr(self, "control", None)
fit = getattr(ctl, "storefit", None)
if fit is None or not self.consent.share or "dhw.power" in self.mapping.by_asset:
return
for c in getattr(ctl, "controls", []):
if c.kind != "dhw_tank":
continue
temp = self.mapping.by_asset.get("dhw.temp_top") or self.mapping.by_asset.get("dhw.temp_bottom")
v = fit.draw_now(c.id)
if temp is not None and getattr(temp, "consent", False) and v is not None:
self.agg.sample("dhw.power", "gauge", float(v), start)
return # one tank: the site's draw
def close_window(self, end: float):
start = self.agg.start
try:
self.tank_draws(start)
except Exception as e:
log.warning("tank draws: %s", e)
records = self.agg.flush(end)
if self.train_agg is not None:
tstart, trecs = self.train_agg.start, self.train_agg.flush(end)
+2 -2
View File
@@ -44,7 +44,7 @@ async def backfill(client: HAClient, mapping, queue, since: datetime, until: dat
row = {"start": _ts(r["start"])}
for k in (("sum", "state") if a.kind == "counter" else ("mean", "min", "max")):
v = number(r.get(k))
row[k] = None if v is None else scaled(convert(v, unit, a.unit), a)
row[k] = None if v is None else scaled(convert(v, getattr(a, "unit_in", "") or unit, a.unit), a)
out.append(row)
records.append({"asset": a.asset, "kind": a.kind, "rows": out})
if records:
@@ -83,7 +83,7 @@ async def collect(client: HAClient, mapping, since: datetime, until: datetime, p
continue
for r in rows:
v = number(r.get("mean"))
v = None if v is None else scaled(convert(v, unit, a.unit), a)
v = None if v is None else scaled(convert(v, getattr(a, "unit_in", "") or unit, a.unit), a)
if v is not None:
out.setdefault(a.asset, []).append({"start": _ts(r["start"]), "mean": v})
start = end
+123 -17
View File
@@ -4,7 +4,12 @@ distributed models).
Nightly (cfg.train_at, default 03:30 in Home Assistant's time zone) from
the agent's own training history (trainhist.py, 13 months, recent weeks weighing more): per series
(load, pv, and base_load where the box plans devices) the cloud's own code
(load, pv, and base_load where the box plans devices; then the carriers
where the box records them, methods.md B13-B16: heat from heat.power, with
the box's own rooms' UA and the occupancy's hour-of-week as the cloud's
trainer has them; occupancy, the share of the presence sources seeing
someone, room.<r>.occupied and person.<slug>.home; ev_plug, the chargers'
plug state, else their charging; as building/carriers.py) the cloud's own code
(trainlib.train_series: how, gbm, pvphys; byte-identical copies of
building/'s trainlib.py, fcmodels.py, pvcalib.py, rcfit.py) fitted on the
window before the held-out one and scored on it, on the weather as it was
@@ -53,8 +58,13 @@ from . import fcmodels, localml, pvforecast, trainhist
log = logging.getLogger(__name__)
SLOT_S = 900
NAMES = {"load": "load_w", "pv": "pv_w", "base_load": "base_load_w"} # the bundle's names (boxmodel.NAMES)
NAMES = {"load": "load_w", "pv": "pv_w", "base_load": "base_load_w", # the bundle's names (boxmodel.NAMES)
"heat": "heat_w", "occupancy": "occupancy", "ev_plug": "ev_plug"}
SERIES = {v: k for k, v in NAMES.items()}
# the carriers the box trains after load, base_load and pv (methods.md B10):
# one at a time like them, each with the same rules and limits
CARRIERS = ("heat", "occupancy", "ev_plug")
CHARGING_W = 50.0 # a charger above this is charging: a car plugged in (building/carriers.py, engineering)
CTL_KINDS = ("heating", "cooling", "ev") # trainlib.CONTROLLED_POWER's keys
ROOM_DAYS = 42 # the rooms on the cloud's window (trainer: 6 weeks)
LIVE_DAYS = 7
@@ -126,11 +136,12 @@ def rss_mb(pid: int) -> float | None:
def hours_json(hours: list) -> list:
return [[int(h.end.timestamp()), h.solar_kwh_m2, h.cloud_pct, h.temp_c] for h in hours]
return [[int(h.end.timestamp()), h.solar_kwh_m2, h.cloud_pct, h.temp_c, getattr(h, "wind_ms", None)] for h in hours]
def hours_from(rows) -> list:
return [pvforecast.Hour(datetime.fromtimestamp(int(r[0]), timezone.utc), r[1], r[2], r[3]) for r in rows or []]
return [pvforecast.Hour(datetime.fromtimestamp(int(r[0]), timezone.utc), r[1], r[2], r[3], r[4] if len(r) > 4 else None)
for r in rows or []]
def arrays(series: dict[int, float], t: np.ndarray) -> np.ndarray:
@@ -152,6 +163,69 @@ def net_series(raw: dict[str, np.ndarray], n: int) -> np.ndarray | None:
return None
def presence_share(raw: dict[str, np.ndarray], n: int) -> np.ndarray | None:
"""The occupancy (B16.1, building/carriers.occupancy): per slot the
share of the presence sources (room.<r>.occupied, person.<slug>.home;
inputs.presence_asset) that see someone, over those with a value."""
from .inputs import presence_asset
srcs = [raw[a] for a in sorted(raw) if presence_asset(a)]
if not srcs:
return None
stack = np.clip(np.vstack(srcs), 0.0, 1.0)
have = ~np.isnan(stack)
with np.errstate(invalid="ignore"):
return np.where(have.any(axis=0), np.nansum(np.where(have, stack, 0.0), axis=0) / np.maximum(have.sum(axis=0), 1),
np.nan)
def _ev_channels(raw: dict, quantity: str) -> list[str]:
"""ev.<q>, ev.<n>.<q>, ev<n>.<q> (building/carriers._channels); a total
beside its parts: the parts."""
out = []
for a in raw:
p = a.split(".")
if p[-1] != quantity or not p[0].startswith("ev"):
continue
if a == f"ev.{quantity}" or (len(p) == 3 and p[0] == "ev" and p[1].isdigit()) \
or (len(p) == 2 and p[0][2:].isdigit() and p[0] != "ev"):
out.append(a)
out = sorted(out)
if f"ev.{quantity}" in out and len(out) > 1:
out.remove(f"ev.{quantity}")
return out
def _sum(arrs: list[np.ndarray]) -> np.ndarray:
stack = np.vstack(arrs)
have = ~np.isnan(stack)
return np.where(have.any(axis=0), np.nansum(np.where(have, stack, 0.0), axis=0), np.nan)
def plug_series(raw: dict[str, np.ndarray]) -> np.ndarray | None:
"""Cars plugged in per slot (B15.1, building/carriers.ev_plug): the
chargers' plug state, else their charging (power above CHARGING_W)."""
plug = _ev_channels(raw, "plugged")
if plug:
return _sum([np.clip(raw[a], 0.0, 1.0) for a in plug])
power = _ev_channels(raw, "power")
if not power:
return None
return _sum([np.where(np.isnan(raw[a]), np.nan, (raw[a] > CHARGING_W).astype(float)) for a in power])
def room_model(rooms: dict, raw: dict[str, np.ndarray]) -> dict | None:
"""The home's UA (W/K) and indoor temperature for the heat model's loss
(B13.1, building/carriers.room_model) from the box's own room fits
(fitted on thermal power): None without one."""
ua = [1000.0 / f["r_k_per_kw"] for f in (rooms or {}).values()
if f.get("status") == "fitted" and f.get("power") == "thermal" and f.get("r_k_per_kw")]
temps = [raw[a] for a in raw if a.startswith("room.") and a.endswith(".temp")]
if not ua or not temps or not any((~np.isnan(x)).any() for x in temps):
return None
t_in = float(np.nanmean(np.vstack(temps)))
return {"ua_w_per_k": float(np.median(ua)), "t_in_c": t_in} if math.isfinite(t_in) else None
def score(m: dict | None, key: str) -> float | None:
v = (m or {}).get(key)
return float(v) if isinstance(v, (int, float)) and math.isfinite(v) else None
@@ -167,7 +241,9 @@ def run_job(job: dict) -> dict:
t = np.asarray(job["t"], dtype=np.int64)
s = job["site"]
site = fcmodels.Site(s.get("tz") or "UTC", s.get("lat"), s.get("lon"), s.get("kwp"), s.get("tilt", 30.0),
s.get("azimuth", 180.0), s.get("pvgis_monthly"), s.get("state"))
s.get("azimuth", 180.0), s.get("pvgis_monthly"), s.get("state"),
# the heat model's room and occupancy (carrier_site)
ua_w_per_k=s.get("ua_w_per_k"), t_in_c=s.get("t_in_c"), occ_how=s.get("occ_how"))
w = fcmodels.weather(t, hours_from(job.get("hours")), site.lat, site.lon)
out: dict = {"series": job["series"]}
if job["series"] == "rooms":
@@ -286,7 +362,8 @@ class BoxTraining:
# -- what the planner asks -------------------------------------------------------
def model(self, name: str):
"""The box's own model for a bundle series name (load_w, pv_w,
base_load_w) as localml runs it, or None (none in force)."""
base_load_w, heat_w, occupancy, ev_plug) as localml runs it, or None
(none in force)."""
e = self.in_force(SERIES.get(name, ""))
if e is None:
return None
@@ -317,10 +394,11 @@ class BoxTraining:
self._hist_cache = {key: h}
return h
def forecast(self, name: str, start: int, steps: int, ha_forecast, weather_entity: str = ""):
def forecast(self, name: str, start: int, steps: int, ha_forecast, weather_entity: str = "", wind_unit=None):
"""The box's own forecast of a series (localml.predict on its own
model, HA's weather, else the cloud's bundle weather): (values with
None, info) or None without a model in force. Once per quarter hour."""
model, HA's weather with its wind unit, else the cloud's bundle
weather): (values with None, info) or None without a model in
force. Once per quarter hour."""
m = self.model(name)
if m is None:
return None
@@ -332,7 +410,7 @@ class BoxTraining:
b = b if isinstance(b, dict) and b.get("site") == getattr(self.bundles, "site", None) else {}
try:
hit = localml.predict(m, [start + k * SLOT_S for k in range(steps)], self.history_for(SERIES[name], start),
ha_forecast, b.get("weather"), weather_entity, b.get("issued"))
ha_forecast, b.get("weather"), weather_entity, b.get("issued"), wind_unit)
except Exception as ex: # never stops a plan: the next source then
log.warning("the box's own %s model: %s", name, ex)
hit = ([None] * steps, {"kind": m.kind, "weather": "", "steps": 0, "error": str(ex)[:200]})
@@ -375,15 +453,18 @@ class BoxTraining:
# -- the series and their actual values -------------------------------------------
def train_series_list(self) -> list[str]:
"""load, base_load where the box plans devices, pv; then the
carriers (those the history has no data for are left out by prepare)."""
out = ["load", "pv"]
if self.kinds():
out.insert(1, "base_load")
return out
return out + list(CARRIERS)
def actual(self, series: str, t: np.ndarray, raw: dict[str, np.ndarray]) -> np.ndarray | None:
"""What was metered for a series: load.power, pv.power, the base
load (trainlib.base_load with the planned devices' kinds), the
member's net draw; for "plan" the series the box plans on."""
member's net draw, the carriers' (heat.power, the presence share,
the cars plugged in); for "plan" the series the box plans on."""
from . import trainlib
if series == "plan":
series = "base_load" if self.kinds() else "load"
@@ -391,6 +472,12 @@ class BoxTraining:
return trainlib.base_load(raw, set(self.kinds()))
if series == "net":
return net_series(raw, len(t))
if series == "heat":
return np.maximum(raw["heat.power"], 0.0) if "heat.power" in raw else None
if series == "occupancy":
return presence_share(raw, len(t))
if series == "ev_plug":
return plug_series(raw)
a = trainlib.SITE_SERIES.get(series)
return raw.get(a) if a else None
@@ -497,10 +584,12 @@ class BoxTraining:
pv_since = self.metered_since()
jobs, info = [], {"slots": int(sum((~np.isnan(v)).sum() for v in raw.values())), "weather_hours": len(obs),
"forecast_hours": len(fc), "site": asdict(site)}
occ = self.actual("occupancy", t, raw)
for series in self.train_series_list():
y = self.actual(series, t, raw)
if y is None or not (~np.isnan(y)).any():
continue
ssite = self.carrier_site(series, site, t, raw, occ)
y = trainlib.cut_before(series, t, y, pv_since)
own = self.state["series"].get(series) or {}
champ = own.get("params")
@@ -511,7 +600,7 @@ class BoxTraining:
w_test, on = trainlib.held_out_weather(t, y, w, fc, site.lat, site.lon)
jobs.append({"series": series, "t": t.tolist(), "y": [None if math.isnan(v) else float(v) for v in y.tolist()],
"hours": hours_json(obs), "test_hours": hours_json(w_test.hours) if w_test is not None else None,
"site": asdict(site), "champion": champ, "scored_on": on,
"site": asdict(ssite), "champion": champ, "scored_on": on,
"cloud": _clean(cloud.params) if cloud is not None else None,
"cloud_model": ((self.bundles.model.get() or {}).get("models") or {}).get(NAMES[series], {}).get("model")
if cloud is not None else None})
@@ -525,6 +614,20 @@ class BoxTraining:
"assets": {a: [None if math.isnan(x) else float(x) for x in v.tolist()] for a, v in rooms_raw.items()}})
return jobs, info
def carrier_site(self, series: str, site: fcmodels.Site, t: np.ndarray, raw: dict, occ) -> fcmodels.Site:
"""The site as the heat model sees it (the cloud's trainer
carrier_site): the box's own rooms' UA and indoor temperature
(room_model) and the occupancy's hour-of-week profile where a day
of presence is recorded; the others' as it is."""
if series != "heat":
return site
from dataclasses import replace
rm = room_model(self.state.get("rooms") or {}, raw)
out = replace(site, ua_w_per_k=rm["ua_w_per_k"], t_in_c=rm["t_in_c"]) if rm else replace(site)
if occ is not None and (~np.isnan(occ)).sum() >= 96:
out.occ_how = fcmodels.fit_how(t, occ, site.tz, None, 3)["values"]
return out
async def child(self, job: dict) -> tuple[dict | None, dict]:
"""One job in a child process within the caps: (result or None, how
it went: seconds, peak_mb, killed)."""
@@ -748,7 +851,7 @@ class BoxTraining:
"held_out_box": e.get("score"), "held_out_cloud": e.get("cloud"), "scored_on": e.get("scored_on", ""),
"n_test": e.get("n_test"), "why": (e.get("why") or "")[:300]}
live = {}
for s in ("plan", "pv", "net"):
for s in ("plan", "pv", "net") + CARRIERS:
le = self.live_errors(s, now)
if le:
live[s] = le
@@ -782,7 +885,9 @@ def _runlog(summary: dict) -> dict:
def ha_history_hours(states: list[dict], spans: list[tuple[int, int]]) -> list:
"""A weather entity's recorded states → per hour end in the spans the
temperature and cloud cover in force then (the last state before)."""
temperature, cloud cover and wind (m/s from the state's own
wind_speed_unit: localml.wind_ms; an unknown unit: none) in force then
(the last state before)."""
pts = []
for s in states:
a = s.get("a") or s.get("attributes") or {}
@@ -793,7 +898,8 @@ def ha_history_hours(states: list[dict], spans: list[tuple[int, int]]) -> list:
continue
temp, cloud = a.get("temperature"), a.get("cloud_coverage")
pts.append((ts, float(temp) if isinstance(temp, (int, float)) else None,
float(cloud) if isinstance(cloud, (int, float)) else None))
float(cloud) if isinstance(cloud, (int, float)) else None,
localml.wind_ms(a.get("wind_speed"), a.get("wind_speed_unit"))))
pts.sort()
out, j = [], -1
for a, b in spans:
@@ -801,7 +907,7 @@ def ha_history_hours(states: list[dict], spans: list[tuple[int, int]]) -> list:
while j + 1 < len(pts) and pts[j + 1][0] <= end:
j += 1
if j >= 0 and (pts[j][1] is not None or pts[j][2] is not None) and end - pts[j][0] <= 3 * 3600:
out.append(pvforecast.Hour(datetime.fromtimestamp(end, timezone.utc), None, pts[j][2], pts[j][1]))
out.append(pvforecast.Hour(datetime.fromtimestamp(end, timezone.utc), None, pts[j][2], pts[j][1], pts[j][3]))
return out
+83 -8
View File
@@ -25,6 +25,11 @@ Tariff v1 (agreed with the cloud side, 2026-10-28):
(ct/kWh gross: gas billed on Hs, heat delivered), null where none;
carrier_prices() reads them the same way (no default, nothing held past
the bundle's expiry). A bundle may price gas or heat alone.
CO2 (fleet, 2026-11-06; an older agent ignores them): "co2_electricity"
(g/kWh per 900 s slot from "start", null where none) and "co2" {gas,
heat: g/kWh or null, basis: direct | lifecycle, electricity_source:
words}; co2() reads them (the planner weighs them by the Parameters
page's co2.planner_eur_per_t, docs/methods.md A2).
Model v1 (the forecasts' data; the ML in ml/ is a placeholder, 2026-10-28):
{"v":1, "kind":"model", "id", "site" (or "*"), "issued", "expires"?,
@@ -64,6 +69,12 @@ Model v1 (the forecasts' data; the ML in ml/ is a placeholder, 2026-10-28):
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.
- "ev_sessions" (2026-11-06, methods.md B15; fleet mlevsessions.go):
{"issued": unix, "sessions": [{"arrive": unix, "depart": unix|null
(beyond the forecast), "kwh": number|null}], "note"}: the sessions read
from the site's ev_plug forecast, the car's departure and energy where
it reports none (inputs.ev_session). Only from a model for this site;
malformed sessions are left out (ev_sessions_error), the rest stays.
A malformed series or room refuses the whole bundle.
"""
import json
@@ -124,12 +135,19 @@ def _check_tariff(d: dict):
raise ValueError("not a v1 tariff")
if int(d["step_s"]) != 900 or int(d["start"]) % 900:
raise ValueError("steps of 900 s from a quarter hour")
for k in ("import", "export", "gas", "heat"):
for k in ("import", "export", "gas", "heat", "oil"):
v = d.get(k) or []
if not isinstance(v, list) or not all(x is None or isinstance(x, (int, float)) for x in v):
raise ValueError(f"{k}: numbers or null")
if not [x for k in ("import", "gas", "heat") for x in d.get(k) or [] if x is not None]:
raise ValueError("no import, gas or heat price")
if not [x for k in ("import", "gas", "heat", "oil") for x in d.get(k) or [] if x is not None]:
raise ValueError("no import, gas, heat or oil price")
ce = d.get("co2_electricity") or []
if not isinstance(ce, list) or not all(x is None or (isinstance(x, (int, float)) and x >= 0) for x in ce):
raise ValueError("co2_electricity: g/kWh (0 or more) or null")
co2 = d.get("co2")
if co2 is not None and (not isinstance(co2, dict) or not all(
co2.get(k) is None or (isinstance(co2[k], (int, float)) and co2[k] >= 0) for k in ("gas", "heat", "oil"))):
raise ValueError("co2: {gas, heat, oil: g/kWh or null, basis, electricity_source}")
SERIES_MAX = 400 # a model's series: steps of 900 s (~4 days)
@@ -140,6 +158,8 @@ ROOM_SUFFIX = re.compile(r"_(heating|cooling|heat|cool)$")
# these the fit's artefact (a negative sun, a gain above any home's) is cut
ROOM_GAIN_W = (-2000.0, 5000.0) # W of heat, internal (people, appliances)
ROOM_SOLAR_M2 = (0.0, 50.0) # W of heat per W/m² of global irradiance
EV_SESSIONS_MAX = 20 # sessions read (fleet evSessionsMax): a broken bundle cannot grow the plan
EV_SESSION_KWH_MAX = 1000.0 # a session's kWh above this is no car's (a form check; fleet's the same)
def _clip(x: float, lo_hi) -> float:
@@ -321,6 +341,7 @@ class Bundles:
self.market = _File(os.path.join(state_dir, "market.json"), _check_market)
self._box_key, self._box, self.box_errors = None, {}, {}
self._box_cache: dict = {} # (series, start, model id) -> the box's forecast
self.ev_sessions_error = ""
def stamps(self):
"""The tariff's and the model's file identities: a change means a new
@@ -366,7 +387,8 @@ class Bundles:
return Prices(out_i, out_e, note, "tariff", "", tid, exp, n)
def carrier_prices(self, carrier: str, start: int, step_s: int, steps: int, now: float) -> list:
"""The tariff's gas or heat prices for the horizon (ct/kWh gross),
"""The tariff's gas, heat or heating-oil prices for the horizon
(ct/kWh gross; oil per kWh Heizwert, fleet heatprice.go oilEnergy),
None where it has none: no tariff, another site's, expired, a step
beyond it or a bundle without the series."""
t = self.tariff.get()
@@ -380,6 +402,25 @@ class Bundles:
out.append(xs[i] if start + k * step_s < exp and 0 <= i < len(xs) else None)
return out
def co2(self, start: int, step_s: int, steps: int, now: float) -> dict:
"""The CO2 factors the tariff bundle carries (fleet, methods E8; the
planner's CO2 term, A2): "electricity" per step (g/kWh, the bundle's
co2_electricity per 900 s slot, None where none), "gas" and "heat"
(g/kWh or None), "basis" (direct | lifecycle) and
"electricity_source" (words: where the electricity's came from);
{} without a valid tariff bundle (nothing held past its expiry)."""
t = self._valid(now)
if t is None:
return {}
xs, exp, out = t.get("co2_electricity") or [], int(t.get("expires", 0) or 0), []
for k in range(steps):
i = (start + k * step_s - t["start"]) // 900
out.append(xs[i] if start + k * step_s < exp and 0 <= i < len(xs) else None)
c = t.get("co2") if isinstance(t.get("co2"), dict) else {}
return {"electricity": out, "gas": c.get("gas"), "heat": c.get("heat"), "oil": c.get("oil"),
"basis": str(c.get("basis") or ""),
"electricity_source": str(c.get("electricity_source") or "")}
def box_params(self, now: float) -> dict:
"""The Parameters page's values the box plans with (fleet heatprice.go
boxParams: the tariff bundle's "params", e.g. heat.hybrid_switch_eur),
@@ -431,7 +472,7 @@ class Bundles:
el["own"] = imp
el["billed"] = bool(ten.get("billed"))
out = {"electricity": el}
for c in ("gas", "heat"):
for c in ("gas", "heat", "oil"):
p = at(t.get(c))
if p is not None:
out[c] = {"price": p, "own": p, "offer": False, "billed": True}
@@ -628,10 +669,11 @@ class Bundles:
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:
weather_entity: str = "", wind_unit=None) -> 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."""
with; None without a model for it. Made once per quarter hour.
wind_unit: the weather entity's wind_speed_unit (HA's wind)."""
mdl = self.box_model(name)
if mdl is None:
return None
@@ -641,7 +683,7 @@ class Bundles:
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"))
m.get("weather"), weather_entity, m.get("issued"), wind_unit)
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]})
@@ -649,6 +691,39 @@ class Bundles:
self._box_cache[key] = hit
return hit
def ev_sessions(self, now: float) -> dict | None:
"""The model bundle's EV sessions for this site (fleet
mlevsessions.go), checked: {"issued", "sessions": [{"arrive",
"depart" (None: beyond the forecast), "kwh" (None: unknown)}] by
arrival, "note"}; None without (no model for this site, expired, no
sessions, or not in the agreed form: ev_sessions_error says why).
A session that is not well-formed is left out."""
self.ev_sessions_error = ""
m = self.model.get()
if m is None or m.get("site") != self.site or (m.get("expires") and m["expires"] <= now):
return None
ev = m.get("ev_sessions")
if ev is None:
return None
if not isinstance(ev, dict) or not _finite(ev.get("issued")) or not isinstance(ev.get("sessions"), list):
self.ev_sessions_error = "ev_sessions: {issued, sessions: [...]}"
return None
out, bad = [], 0
for x in ev["sessions"][:EV_SESSIONS_MAX]:
a = x.get("arrive") if isinstance(x, dict) else None
d = x.get("depart") if isinstance(x, dict) else None
k = x.get("kwh") if isinstance(x, dict) else None
if not _finite(a) or (d is not None and (not _finite(d) or d <= a)) or \
(k is not None and (not _finite(k) or not 0 <= k <= EV_SESSION_KWH_MAX)):
bad += 1
continue
out.append({"arrive": int(a), "depart": int(d) if d is not None else None,
"kwh": float(k) if k is not None else None})
if bad:
self.ev_sessions_error = f"ev_sessions: {bad} malformed session(s) left out"
out.sort(key=lambda x: x["arrive"])
return {"issued": int(ev["issued"]), "sessions": out, "note": str(ev.get("note") or "")[:300]} if out else None
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
+79 -5
View File
@@ -55,6 +55,8 @@ from .guard import Guard
from .policy import Policy
from .preferences import Preferences
from .switchover import Switchover
from . import storefit as storefit_mod
from .storefit import StoreFit
from .inputs import Collector, History
from . import localml
@@ -113,6 +115,8 @@ class Controller:
self.saved_limits = self._load_limits() # the console's (limits.json)
self.gridorders = GridOrders(cfg.state_dir, clock) # the grid operator's, from the EEBUS bridge (3q)
self.evphases = EvPhases(cfg.state_dir) # each charger's phase count and its source
# what the box learns of its stores: a battery's idle loss, a tank's draw, UA, legionella (storefit.py)
self.storefit = StoreFit(os.path.join(cfg.state_dir, "storefit.json"), clock)
self.guard.extra_limits = self.saved_limits
self.policy = Policy(cfg.state_dir, cfg.site_id, clock)
self.guard.policy = self.policy
@@ -174,8 +178,19 @@ class Controller:
t_out = self.col.value(ent) if ent else None
return self.switchover.update(self.controls, self.clock(), self.tz, t_out)
def presence_entities(self) -> list[str]:
"""The presence sources (methods.md A1, B16): the inputs' presence
and the mapped presence assets (room.<r>.occupied, person.<slug>.home:
inputs.presence_asset), each once."""
out = list(getattr(self.inputs, "presence", None) or [])
for a in getattr(self.mapping, "assets", None) or []:
if inputs_mod.presence_asset(getattr(a, "asset", "")) and a.entity not in out:
out.append(a.entity)
return out
def entities(self) -> list[str]:
out = set(self.inputs.entities())
out.update(self.presence_entities())
if self.outside_entity() and any(c.switchover or c.kind == "cover" for c in self.controls):
out.add(self.outside_entity())
for c in self.controls:
@@ -277,7 +292,7 @@ class Controller:
metered (inputs.controlled_power), as the planner uses it."""
if not (getattr(self.inputs, "controlled_power", None) or []):
return set()
return {c.kind for c in self.controls if c.kind in ("heating", "cooling", "ev")}
return {c.kind for c in self.controls if c.kind in ("heating", "cooling", "ev", "dhw_tank")}
# -- plans ---------------------------------------------------------------
def owner_ratings(self):
@@ -313,7 +328,8 @@ class Controller:
location=self.location, shade_ctx=self.shade_ctx(),
grid_order=self.gridorders.for_model(start, inputs_mod.STEP_S, inputs_mod.STEPS),
grid_max_w=getattr(self.cfg, "grid_max_w", None),
ev_phases=self.ev_phases())
ev_phases=self.ev_phases(), presence=self.presence_entities(),
storefit=self.storefit)
# the owner's preferences per step (preferences.py)
return self.prefs.apply(state, {c.id: c for c in controls}, self.col, now)
@@ -379,14 +395,21 @@ class Controller:
"priced": plan.get("priced", True), "refused": plan.get("refused", {}),
# what the plan assumed for want of a fact (e.g. battery.end_value_pct missing)
"notes": plan.get("notes", []),
# cost_eur by carrier (its heat outlook a fixed term: the heat no room model plans),
# the plan's CO2 and its basis (methods A2): absent from older agents
**{k: plan[k] for k in ("cost_parts", "heat_outlook", "co2_kg", "co2_basis", "storage") if k in plan},
# the saving by carrier and lever (plansplit.py; the console's Savings page): absent from older agents
**({"saving_parts": plan["saving_parts"]} if plan.get("saving_parts") else {}),
"sources": plan.get("sources", {}),
# for the building (shed_w/grid_w per step, 24 h): absent from older agents
"flex": plan.get("flex", {}),
# the market's contracts in the plan (shadow): planned kWh and saving vs the grid
"market": plan.get("market", []),
# the owner's preferences: per level who set what and when, the
# overrides, and per preference met or not and each must's cost
"preferences": self.prefs.public(),
# overrides, and per preference met or not and each must's cost;
# builtin: the agent's own targets where none is set
"preferences": self.prefs.public(self.controls, bool(self.presence_entities()),
(plan.get("sources") or {}).get("occupancy")),
# the box's own models (boxtrain.py): held-out and live errors per source,
# hourly the forecasts it planned on; absent from older agents
**({"ml": plan["ml"]} if plan.get("ml") else {})}
@@ -437,7 +460,9 @@ class Controller:
b, now, start = self.boxml, self.clock(), int(state["start"])
st = b.store
if self.forecast:
st.put_weather("forecast", "ha", localml.ha_hours(self.forecast), now)
# with the wind in m/s where the weather entity says its unit (localml.ha_hours)
unit = self.col.attr(self.inputs.weather, "wind_speed_unit") if self.inputs.weather else None
st.put_weather("forecast", "ha", localml.ha_hours(self.forecast, unit), now)
m = self.bundles.model.get()
if isinstance(m, dict) and m.get("site") == self.cfg.site_id:
if m.get("weather"):
@@ -447,6 +472,9 @@ class Controller:
for key, series in (("load", "plan"), ("pv", "pv")):
if cands.get(key):
b.record(series, start, cands[key], now)
for key, c in cands.items(): # the carriers' (occupancy): under their own names
if key not in ("load", "pv") and c:
b.record(key, start, c, now)
auto = plan.get("mode") == "auto"
net = (plan.get("flex") or {}).get("net_w") if auto else \
([round(lo - pv) for lo, pv in zip(net_load, state["pv_w"])] if net_load else None)
@@ -592,6 +620,10 @@ class Controller:
self.history.add("pv_w", self.col.total(self.inputs.pv_power), now)
if self.sample_ev_phases(now) and self.gridorders.active():
self._merge_limits() # a learned count: the order's current bound again
try:
self.sample_stores(now)
except Exception as e: # never stops the actions
log.warning("stores: %s", e)
if int(now) % 900 < 60:
try:
self.history.save(now)
@@ -755,6 +787,48 @@ class Controller:
changed |= self.evphases.sample(c.id, p, a, float(c.p("voltage")), now)
return changed
# -- what the box learns of its stores (storefit.py) ---------------------------
def sample_stores(self, now: float):
"""A reading of each battery (its SoC, its own power, the PV, its
grid charging) and each tank (its mean temperature, the room, its
heater's heat) for the idle-loss fit, the tank's draw (S.7), UA and
legionella time; the fits once a day, saved each quarter-hour."""
bp = self.bundles.box_params(now) if hasattr(self.bundles, "box_params") else {}
caps = {}
bats = [c for c in self.controls if c.kind == "battery"]
for c in self.controls:
if c.kind == "battery":
e = c.entities
pw = inputs_mod.watts(self.col, e["power"]) if e.get("power") else None
if pw is None and len(bats) == 1 and hasattr(self.mapping, "by_asset"):
a = self.mapping.by_asset.get("battery.power")
pw = inputs_mod.watts(self.col, a.entity) if a else None
pv = self.col.total(self.inputs.pv_power) if self.inputs.pv_power else None
self.storefit.sample_battery(c.id, now, self.col.value(e.get("soc", "")), pw, pv,
self.col.state(e.get("charge_from_grid", "")) == "on")
f, _, _ = c.battery_facts()
if f.get("capacity_wh"):
caps[c.id] = f["capacity_wh"]
elif c.kind == "dhw_tank" and c.resolved:
st = inputs_mod.device_state(c, self.col, now)
f = c.resolved
temp = storefit_mod.mean_temp(st.get("temp_top"), st.get("temp_bottom"),
float(f.get("top_share") or 1.0))
room = st.get("room_c") if st.get("room_c") is not None else f.get("room_temp_c")
heat = st.get("heater_w")
if heat is not None and f.get("heater") == "heat_pump":
# its heat by its COP (a COP curve's is not known here: no heat, no draw then)
heat = heat * float(f["cop"]) if f.get("cop") else None
facts = dict(f, draw_detect_k=bp.get("dhw.draw_detect_k_per_15min"))
if room is not None:
self.storefit.sample_tank(c.id, now, temp, float(room), heat, facts)
if int(now) % 900 < 60:
self.storefit.fit_batteries(caps, bp, now)
for c in self.controls:
if c.kind == "dhw_tank" and c.resolved:
self.storefit.fit_tank(c.id, dict(c.resolved, label_ua_w_k=c.resolved.get("ua_w_k")), bp)
self.storefit.save()
# -- the grid operator's limit (EEBUS LPC, gridorder.py) -----------------
def _merge_limits(self):
"""The guard's limits: the console's, and over them the grid order's
+421 -14
View File
@@ -78,6 +78,28 @@ Kinds, their entities (* needed) and what the executor sets (channels):
ev switch* (charging on/off); current (number A); connected
(binary_sensor); soc (sensor %); energy_needed (sensor Wh/kWh)
and departure (sensor: a time) override params need_wh/departure
dhw_tank a hot-water tank (docs/methods.md A13): water_heater (target °C)
or switch (an element's relay) or power (number, W: a stepless
element) or sg_ready (select: a heat pump's SG-Ready state, its
options in params.sg_options) *; temp_top, temp_bottom (sensor
°C; a water heater's current temperature stands in), heater_power
(sensor W: off the house load, A2-a), room_temp; read only: volume
(L), standby_loss (W). Its facts (tank_facts): heater (element |
heat_pump | boiler | district), volume_l, the heater's power
(max_power_w; boiler, district: max_heat_w), a heat pump's cop or
cop_curve, a boiler's efficiency: the mapping's, the device's,
the owner's ratings, else refused; its standing loss (ua_w_k,
standby_w = ErP S at 65/20 °C, or erp_class), else the box's fit,
the owner's, else class D's limit (assumed); temperatures and
shares the mapping's, else the Parameters page's dhw.* rows;
legionella plan | device (default: its own program) | none
battery's idle loss (battery_idle_facts, S.2): standby_w and
self_discharge_pct_month from the mapping, the device's standby
entity, the box's fit (storefit.py), the owner's ratings
(battery_standby_w, battery_self_discharge_pct_month), the
Parameters rows battery.standby_w / .self_discharge_pct_month;
none: 0 (never refused); standby_in_load: the load holds its
grid-side standby (unknown: as true)
cover cover* (position %; open/close only where the cover cannot be
set to a position); room: the heating/cooling control whose
room it shades (params.room), area: the room's name (its
@@ -109,7 +131,9 @@ ENTITIES = {
"mode": ("select", "input_select"), "soc": ("sensor", "input_number"), "power": ("sensor",),
# read only: the device's own ratings (battery_facts)
"capacity": ("sensor", "input_number"), "rated_power": ("sensor", "input_number"),
"efficiency": ("sensor", "input_number")},
"efficiency": ("sensor", "input_number"),
# read only: the device's own report of its idle use (W; battery_idle_facts)
"standby": ("sensor", "input_number")},
"heating": {"climate": ("climate",), "switch": ("switch", "input_boolean"), "temp": ("sensor",),
"source": ("select", "input_select"),
# read only: the boiler's own rated efficiency (%; heat_facts)
@@ -121,10 +145,20 @@ ENTITIES = {
# read only, for its phase count (evphases.py): reported, or learned from power and current
"phases": ("sensor",), "power": ("sensor",), "current_measured": ("sensor",)},
"cover": {"cover": ("cover",)},
# a hot-water tank (docs/methods.md A13): its heater (a water_heater entity, an element's relay or
# stepless power, a heat pump's SG-Ready select), its temperatures, the heater's power, the room's
# temperature; read only: the device's own volume (L) and standing loss (W) where it reports them
"dhw_tank": {"water_heater": ("water_heater",), "switch": ("switch", "input_boolean"),
"power": ("number", "input_number"), "sg_ready": ("select", "input_select"),
"temp_top": ("sensor",), "temp_bottom": ("sensor",), "heater_power": ("sensor",),
"room_temp": ("sensor",), "volume": ("sensor", "input_number"),
"standby_loss": ("sensor", "input_number")},
}
WRITES = {"charge_from_grid", "setpoint", "mode", "climate", "switch", "current", "cover", "source"}
WRITES = {"charge_from_grid", "setpoint", "mode", "climate", "switch", "current", "cover", "source",
"water_heater", "power", "sg_ready"}
NEEDED = {"battery": (("charge_from_grid", "setpoint"),), "heating": (("climate", "switch"),),
"cooling": (("climate",),), "ev": (("switch",),), "cover": (("cover",),)}
"cooling": (("climate",),), "ev": (("switch",),), "cover": (("cover",),),
"dhw_tank": (("water_heater", "switch", "power", "sg_ready"),)}
# defaults per kind (params may override each)
PARAMS = {
# capacity_wh, max_charge_w, max_discharge_w, efficiency (one way, 0-1):
@@ -132,7 +166,10 @@ PARAMS = {
"battery": {"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},
"hold_mode_s": 1800.0, "hold_set_s": 900.0, "min_gain_ct": 1.0,
# the site's load.power already holds the system's grid-side standby (true | false;
# None: not said, treated as true and noted: optimizer.Model.battery, Finding A2-a)
"standby_in_load": None},
# r_k_per_kw, c_kwh_per_k (the room), max_power_w, cop (the device): facts,
# no default (FACTS: without them the room is not optimised,
# inputs.room_refusal). comfort_c / setback_c / setup_c: the box's copy of
@@ -146,8 +183,13 @@ PARAMS = {
# none modelled unless the fit or the mapping gives it
"internal_gain_w": 0.0, "solar_m2": 0.0, "hold_mode_s": 1800.0, "hold_set_s": 900.0, "min_gain_ct": 1.0,
# what makes the heat (docs/methods.md E6): electric | heat_pump | boiler | district | hybrid;
# a hybrid's source select options; a heat pump's datasheet COP by outside temperature
"heat_source": "electric", "source_options": {}, "cop_curve": []},
# a hybrid's source select options; a heat pump's datasheet COP by outside temperature;
# a boiler's part load (E6): its type (the Parameters page's boiler.part_load_<type>) or
# its datasheet's curve [[load share, efficiency relative to the rated], ...] (wins)
"heat_source": "electric", "source_options": {}, "cop_curve": [], "boiler_type": "",
"part_load_curve": [],
# a boiler's fuel (E15, branch heating-oil): gas | oil (heating oil EL); gas: every boiler before
"fuel": "gas"},
"cooling": {"comfort_c": 25.0,
"setup_c": 28.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},
@@ -157,18 +199,35 @@ PARAMS = {
"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},
# a hot-water tank's choices (its facts: FACTS, no default): the legionella run left to the
# device's own program unless the installer says "plan" (or "none"); a heating control whose
# compressor it shares; the SG-Ready select's option per state "1".."4"; anti-cycling as heating
"dhw_tank": {"legionella": "device", "shares_with": "", "sg_options": {}, "cop_curve": [],
"min_switch_s": 600.0, "hold_mode_s": 1800.0, "hold_set_s": 900.0, "min_gain_ct": 1.0},
}
# params a kind accepts without a default: facts of the device that come
# from the mapping, the device or its owner, or the feature refuses
FACTS = {"battery": ("capacity_wh", "max_charge_w", "max_discharge_w", "efficiency"),
FACTS = {"battery": ("capacity_wh", "max_charge_w", "max_discharge_w", "efficiency",
# its idle loss (docs/methods.md A2.3, S.2): never refuses the battery (battery_idle_facts)
"standby_w", "self_discharge_pct_month"),
# the room's R and C, the device's electric power and COP (room_refusal);
# a boiler's or a heat station's: its efficiency (heat per kWh of gas billed, Hs, 0-1)
# and its most heat (W); heat_facts
"heating": ("r_k_per_kw", "c_kwh_per_k", "max_power_w", "cop", "boiler_efficiency", "max_heat_w"),
"cooling": ("r_k_per_kw", "c_kwh_per_k", "max_power_w", "cop")}
"cooling": ("r_k_per_kw", "c_kwh_per_k", "max_power_w", "cop"),
# a hot-water tank's facts (tank_facts; docs/methods.md A13)
"dhw_tank": ("heater", "volume_l", "max_power_w", "max_heat_w", "cop", "boiler_efficiency", "standby_w",
"ua_w_k", "erp_class", "min_temp_c", "max_temp_c", "room_temp_c", "cold_water_c", "top_share",
"legionella_temp_c", "legionella_interval_h", "grossanlage")}
# facts that may be 0 (a battery without idle loss), facts that are no numbers
ZERO_OK = {"standby_w", "self_discharge_pct_month"}
TEXT_FACTS = {"heater", "erp_class", "grossanlage"}
TANK_HEATERS = ("element", "heat_pump", "boiler", "district")
ERP_CLASSES = ("A+", "A", "B", "C", "D", "E", "F") # Regulation (EU) 812/2013 Annex II, best first
HEAT_SOURCES = ("electric", "heat_pump", "boiler", "district", "hybrid")
BOILER_TYPES = ("condensing", "low_temperature", "standard") # the Parameters page's boiler.part_load_<type>
# the owner's ratings of a heating device (devices-specs.json) and their labels
HEAT_RATINGS = {"boiler_efficiency": ("boiler_efficiency_pct", "Boiler efficiency, % (heat per kWh of gas billed)"),
"max_heat_w": ("heat_kw", "Most heat output, kW")}
@@ -176,7 +235,51 @@ HEAT_RATINGS = {"boiler_efficiency": ("boiler_efficiency_pct", "Boiler efficienc
# where to enter each: (rating, its label on the panel, the mapping's param)
BATTERY_RATINGS = {"capacity": ("battery_kwh", "Battery capacity, kWh", "capacity_wh"),
"power": ("battery_kw", "Battery power, kW", "max_charge_w and max_discharge_w"),
"efficiency": ("battery_efficiency_pct", "Battery round-trip efficiency, %", "efficiency")}
"efficiency": ("battery_efficiency_pct", "Battery round-trip efficiency, %", "efficiency"),
# the idle loss: never refused for (battery_idle_facts), entered the same ways
"standby": ("battery_standby_w", "Battery idle loss, W", "standby_w"),
"self_discharge": ("battery_self_discharge_pct_month", "Battery self-discharge, %/month",
"self_discharge_pct_month")}
# the battery idle loss's Parameters rows (the tariff bundle's params): the last stand-in, marked assumed
STANDBY_KEY, SELF_DISCHARGE_KEY = "battery.standby_w", "battery.self_discharge_pct_month"
HOURS_PER_MONTH = 730.0 # 8760 h / 12: a %/month as a share per hour (calendar arithmetic)
# a hot-water tank's owner ratings (devices-specs.json): fact -> (rating, its label, the mapping's param)
TANK_RATINGS = {"volume_l": ("tank_volume_l", "Hot-water tank, litres", "volume_l"),
"heater_kw": ("tank_heater_kw", "Tank heater, kW", "max_power_w (element, heat pump) or max_heat_w"),
"cop": ("tank_cop", "Tank heat pump COP", "cop or cop_curve"),
"standby_w": ("tank_standby_w", "Tank standing loss (ErP S), W", "standby_w, ua_w_k or erp_class"),
"erp_class": ("tank_erp_class", "Tank ErP class (1 A+ .. 7 F)", "erp_class"),
"max_temp_c": ("tank_max_c", "Tank maximum, °C", "max_temp_c"),
"room_temp_c": ("tank_room_c", "Room temperature at the tank, °C", "room_temp_c"),
"grossanlage": ("tank_grossanlage", "Large system, DVGW W 551 (1: yes)", "grossanlage")}
# the tank's Parameters rows (the tariff bundle's params; docs/parameters.md, design note 10.6)
CLASS_LIMITS_KEY = "dhw.erp_class_limits" # law: Regulation (EU) 812/2013 Annex II, S ≤ a + b·V^0.4 (W)
CLASS_ASSUMED_KEY = "dhw.erp_class_assumed" # the class a tank without its loss is planned with (D)
GROSS_VOLUME_KEY = "de.dvgw_w551_volume_l" # law: a tank above it is a Großanlage
GROSS_FLOOR_KEY = "de.dvgw_w551_min_outlet_c" # law: a Großanlage's outlet at least this
SHORT_KEY = "dhw.short_eur_kwh" # EUR per kWh of hot water short of the comfort
# EN 15332 / EN 12897: the standing loss S is measured at 65 °C water in a 20 °C room, so UA = S / 45 K
# (the standard's test condition, not a tunable)
ERP_TEST_DT_K = 45.0
def _class_limits(raw) -> dict | None:
"""The ErP class table ({"A+": [a, b], ...}; its JSON text too) as
floats, or None when it is not one."""
if isinstance(raw, str):
try:
import json
raw = json.loads(raw)
except ValueError:
return None
if not isinstance(raw, dict) or not raw:
return None
out = {}
for k, v in raw.items():
if not isinstance(v, (list, tuple)) or len(v) != 2 or _num(v[0]) is None or _num(v[1]) is None:
return None
out[str(k)] = (float(v[0]), float(v[1]))
return out
def ev_volts(params: dict, purpose: str) -> float:
@@ -198,6 +301,9 @@ RANGE = {
"cooling": {"temp_c": (16.0, 32.0)},
"ev": {"current_a": (0.0, 32.0)},
"cover": {"position_pct": (0.0, 100.0)},
# a tank's water: the heaters' targets lie inside it (EN 16147's 65 °C heat pump and 70 °C element
# maxima); the device's own min_temp..max_temp narrows it (learn_range)
"dhw_tank": {"temp_c": (10.0, 75.0)},
}
@@ -221,6 +327,10 @@ class Control:
rated: dict = field(default_factory=dict)
rated_device: str = ""
reported: dict = field(default_factory=dict)
# a hot-water tank that is a Großanlage: the law's least temperature (DVGW W 551, the Parameters
# page's de.dvgw_w551_min_outlet_c), a floor of its device range nothing goes below (tank_facts)
law_floor_c: float | None = None
resolved: dict = field(default_factory=dict) # a tank's facts as the last plan resolved them
def label(self) -> str:
"""A name for people: the mapping's, else the id in words
@@ -285,6 +395,155 @@ class Control:
break
return out, [k for k in need if k not in out], where
def battery_idle_facts(self, learnt: dict | None = None, box_params: dict | None = None) -> tuple[dict, dict]:
"""A battery's idle loss (docs/methods.md A2.3, S.2): standby_w (W,
the system's standby) and self_discharge_pct_month (the cells'), each
from the mapping's params, else the device's report (its standby
entity; the standby only), else the box's own fit where it passed
its gate (learnt: storefit.BatteryIdleFit.in_force: standby_w,
loss_pct_h), else the owner's ratings (battery_standby_w,
battery_self_discharge_pct_month), else the Parameters page's rows
(battery.standby_w, battery.self_discharge_pct_month: assumed), else
0 (none: the plan notes it). Never refuses the battery. (facts, per
fact where it came from: mapping | device | learnt | owner |
parameter | none)."""
rep, own, bp, lr = self.reported or {}, self.rated or {}, box_params or {}, learnt or {}
sd_fit = _num(lr.get("loss_pct_h"))
chains = {
"standby_w": (("mapping", self.params.get("standby_w")), ("device", rep.get("standby_w")),
("learnt", lr.get("standby_w")), ("owner", own.get("battery_standby_w")),
("parameter", bp.get(STANDBY_KEY))),
"self_discharge_pct_month": (("mapping", self.params.get("self_discharge_pct_month")),
("learnt", sd_fit * HOURS_PER_MONTH if sd_fit is not None else None),
("owner", own.get("battery_self_discharge_pct_month")),
("parameter", bp.get(SELF_DISCHARGE_KEY)))}
out, src = {}, {}
for k, cands in chains.items():
out[k], src[k] = 0.0, "none"
for where, v in cands:
x = _num(v)
if x is not None and x >= 0:
out[k], src[k] = x, where
break
return out, src
def tank_facts(self, box_params: dict | None = None, learnt: dict | None = None) -> tuple[dict, list[str], dict]:
"""A hot-water tank's facts (docs/methods.md A13, design note 10.4):
each from the mapping's params, else the device's report (volume,
standing loss, its water_heater's max_temp), else the box's fit (UA),
else the owner's ratings (TANK_RATINGS), else the Parameters page's
row where one exists. No stand-in for the volume, the heater's kind
and power, a heat pump's COP and a boiler's efficiency: missing
(refused). The standing loss without any: class D's limit
(dhw.erp_class_assumed, source "assumed"). (facts, missing, per fact
where it came from)."""
p, rep, own, bp, lr = self.params, self.reported or {}, self.rated or {}, box_params or {}, learnt or {}
out, src, missing = {}, {}, []
def pick(key, *cands, ok=lambda x: x > 0):
for where, v in cands:
x = _num(v)
if x is not None and ok(x):
out[key], src[key] = x, where
return True
return False
heater = str(p.get("heater") or "")
if heater in TANK_HEATERS:
out["heater"], src["heater"] = heater, "mapping"
else:
missing.append("heater")
kw = _num(own.get("tank_heater_kw"))
if not pick("volume_l", ("mapping", p.get("volume_l")), ("device", rep.get("volume_l")),
("owner", own.get("tank_volume_l"))):
missing.append("volume_l")
if heater in ("element", "heat_pump"):
if not pick("max_power_w", ("mapping", p.get("max_power_w")), ("owner", kw * 1000.0 if kw else None)):
missing.append("max_power_w")
elif heater in ("boiler", "district"):
if not pick("max_heat_w", ("mapping", p.get("max_heat_w")), ("owner", kw * 1000.0 if kw else None)):
missing.append("max_heat_w")
if heater == "heat_pump":
if p.get("cop_curve"):
out["cop_curve"], src["cop"] = [list(map(float, x)) for x in p["cop_curve"]], "mapping"
elif not pick("cop", ("mapping", p.get("cop")), ("owner", own.get("tank_cop"))):
missing.append("cop")
if heater == "boiler":
eff = _num(own.get("boiler_efficiency_pct"))
if not pick("boiler_efficiency", ("mapping", p.get("boiler_efficiency")),
("owner", eff / 100.0 if eff else None), ok=lambda x: 0 < x <= 1):
missing.append("boiler_efficiency")
# the standing loss: UA (W/K) from what is known best; S is measured at 65 °C water in a 20 °C room
limits = _class_limits(bp.get(CLASS_LIMITS_KEY))
vol = out.get("volume_l")
def from_class(c):
if c not in ERP_CLASSES or limits is None or c not in limits or not vol:
return None
a, b = limits[c]
return (a + b * vol ** 0.4) / ERP_TEST_DT_K
own_cls = _num(own.get("tank_erp_class"))
own_cls = ERP_CLASSES[int(own_cls) - 1] if own_cls and 1 <= own_cls <= len(ERP_CLASSES) else None
assumed = str(bp.get(CLASS_ASSUMED_KEY) or "")
loss = (("mapping", _num(p.get("ua_w_k")), None),
("mapping", _num(p.get("standby_w")) / ERP_TEST_DT_K if _num(p.get("standby_w")) else None, None),
("mapping", from_class(str(p.get("erp_class") or "")), str(p.get("erp_class") or "") or None),
("device", _num(rep.get("standby_loss_w")) / ERP_TEST_DT_K if _num(rep.get("standby_loss_w")) else None, None),
("learnt", _num(lr.get("ua_w_k")), None),
("owner", _num(own.get("tank_standby_w")) / ERP_TEST_DT_K if _num(own.get("tank_standby_w")) else None, None),
("owner", from_class(own_cls or ""), own_cls),
("assumed", from_class(assumed), assumed or None))
for where, ua, cls in loss:
if ua is not None and ua > 0:
out["ua_w_k"], src["ua_w_k"] = ua, where
if cls:
out["erp_class"] = cls
break
else:
if vol:
# no loss and no class table or assumed class to fall back on: the parameters (fixable)
missing += [k for k in (CLASS_LIMITS_KEY, CLASS_ASSUMED_KEY) if not
(limits if k == CLASS_LIMITS_KEY else assumed in ERP_CLASSES)]
# temperatures and shares: the mapping's, the owner's where a rating exists, else the parameter
for key, own_key, par in (("min_temp_c", None, "dhw.min_temp_c"), ("max_temp_c", "tank_max_c", "dhw.max_temp_c"),
("room_temp_c", "tank_room_c", "dhw.room_temp_c"),
("cold_water_c", None, "dhw.cold_water_c"),
("top_share", None, "dhw.top_sensor_share"),
("legionella_temp_c", None, "dhw.legionella_temp_c"),
("legionella_interval_h", None, "dhw.legionella_interval_h")):
if key.startswith("legionella") and str(self.p("legionella")) != "plan":
continue
cands = [("mapping", p.get(key))] + ([("owner", own.get(own_key))] if own_key else []) + [("parameter", bp.get(par))]
if not pick(key, *cands, ok=lambda x: x >= 0 if key == "cold_water_c" else x > 0):
missing.append(par)
# the device's own maximum narrows the max (a water_heater's max_temp)
dev_hi = (self.entity_range.get("temp_c") or (None, None))[1]
if dev_hi is not None and out.get("max_temp_c") is not None and dev_hi < out["max_temp_c"]:
out["max_temp_c"], src["max_temp_c"] = dev_hi, "device"
# a Großanlage (DVGW W 551): the mapping's or the owner's word, else its volume above the law's
g = p.get("grossanlage")
if isinstance(g, bool):
out["grossanlage"], src["grossanlage"] = g, "mapping"
elif _num(own.get("tank_grossanlage")):
out["grossanlage"], src["grossanlage"] = True, "owner"
elif vol and _num(bp.get(GROSS_VOLUME_KEY)) is not None:
out["grossanlage"], src["grossanlage"] = vol > float(bp[GROSS_VOLUME_KEY]), "parameter"
elif vol:
missing.append(GROSS_VOLUME_KEY)
self.law_floor_c = None
if out.get("grossanlage"):
floor = _num(bp.get(GROSS_FLOOR_KEY))
if floor is None:
missing.append(GROSS_FLOOR_KEY)
else:
self.law_floor_c = floor
out["law_floor_c"], src["law_floor_c"] = floor, "parameter"
if _num(bp.get(SHORT_KEY)) is None:
missing.append(SHORT_KEY)
else:
out["short_eur_kwh"] = float(bp[SHORT_KEY])
return out, missing, src
def device_range(self, q: str) -> tuple[float, float]:
if self.kind == "battery" and q == "power_w":
# without its power known nothing but 0 may be set (no plan
@@ -293,16 +552,22 @@ class Control:
return (-float(f.get("max_discharge_w") or 0.0), float(f.get("max_charge_w") or 0.0))
if self.kind == "ev" and q == "current_a":
return (0.0, float(self.p("max_current_a")))
if self.kind == "dhw_tank" and q == "power_w":
# a stepless element's W: up to its power as resolved (tank_facts), else nothing
return (0.0, float((self.resolved or {}).get("max_power_w") or 0.0))
lo, hi = RANGE[self.kind][q]
own = self.entity_range.get(q)
if own and max(lo, own[0]) <= min(hi, own[1]):
lo, hi = max(lo, own[0]), min(hi, own[1])
if self.kind == "dhw_tank" and q == "temp_c" and self.law_floor_c is not None:
# a Großanlage: never a target below the law's (DVGW W 551), whoever asks
lo = min(max(lo, self.law_floor_c), hi)
return (lo, hi)
def learn_range(self, col):
"""A climate's own min_temp..max_temp (HA's attributes, from the
collector): the setpoint never goes outside it."""
ent = self.entities.get("climate")
"""A climate's (or a water heater's) own min_temp..max_temp (HA's
attributes, from the collector): the setpoint never goes outside it."""
ent = self.entities.get("climate") or self.entities.get("water_heater")
if not ent or col is None:
return
lo, hi = _num(col.attr(ent, "min_temp")), _num(col.attr(ent, "max_temp"))
@@ -360,6 +625,100 @@ def _check_heat(cid: str, p: dict, ents: dict):
raise ValueError(f"control {cid}: source_options names the select's options for heat_pump and boiler")
if src == "hybrid" and ("source" not in ents or set(opts) != {"heat_pump", "boiler"}):
raise ValueError(f"control {cid}: a hybrid needs its source select and source_options for heat_pump and boiler")
if p.get("fuel", "gas") not in FUELS:
raise ValueError(f"control {cid}: fuel is one of {', '.join(FUELS)} (a boiler's)")
_check_part_load(cid, p)
FUELS = ("gas", "oil") # a boiler's fuel (docs/methods.md E15)
def _check_part_load(cid: str, p: dict):
"""A boiler's part load (docs/methods.md E6): boiler_type one of
BOILER_TYPES (or none), part_load_curve [[load share in (0, 1],
efficiency relative to the rated > 0], ...]."""
if p.get("boiler_type") and p["boiler_type"] not in BOILER_TYPES:
raise ValueError(f"control {cid}: boiler_type is one of {', '.join(BOILER_TYPES)}")
if p.get("part_load_curve") and part_load_points(p["part_load_curve"]) is None:
raise ValueError(f"control {cid}: part_load_curve is [[load share 0-1, efficiency relative to the rated], ...]")
def part_load_points(raw) -> list[tuple[float, float]] | None:
"""A part-load curve as sorted (load share, relative efficiency) points:
from a list [[0.3, 1.094], [1.0, 1.0]] or its JSON text (the Parameters
page's value); None when it is not one (a share outside (0, 1], a
factor not above 0, no point)."""
if isinstance(raw, str):
try:
import json
raw = json.loads(raw)
except ValueError:
return None
if not isinstance(raw, (list, tuple)) or not raw:
return None
pts = []
for x in raw:
if not isinstance(x, (list, tuple)) or len(x) != 2:
return None
a, b = _num(x[0]), _num(x[1])
if a is None or b is None or not 0 < a <= 1 or b <= 0:
return None
pts.append((a, b))
return sorted(pts)
def part_load(params: dict, box_params: dict | None) -> tuple[list[tuple[float, float]] | None, str]:
"""A boiler's part-load curve (docs/methods.md E6): the mapping's own
part_load_curve (the datasheet's; wins), else the Parameters page's
boiler.part_load_<boiler_type> (the tariff bundle's params); (points,
where from) or (None, why none: the plan notes it, quietly, and keeps
one constant efficiency)."""
own = part_load_points(params.get("part_load_curve")) if params.get("part_load_curve") else None
if own:
return own, "the mapping's part_load_curve"
kind = str(params.get("boiler_type") or "")
if not kind:
return None, "no boiler_type or part_load_curve: one constant efficiency"
key = f"boiler.part_load_{kind}"
pts = part_load_points((box_params or {}).get(key))
if pts is None:
return None, f"{key} not received: one constant efficiency"
return pts, key
def relative_efficiency(pts: list[tuple[float, float]], share: float) -> float:
"""The curve's factor at a load share: linear between its points, held
flat outside them."""
if share <= pts[0][0]:
return pts[0][1]
for (a0, b0), (a1, b1) in zip(pts, pts[1:]):
if share <= a1:
return b0 + (b1 - b0) * (share - a0) / (a1 - a0) if a1 > a0 else b1
return pts[-1][1]
def gas_segments(qmax: float, eta: float, pts: list[tuple[float, float]]) -> tuple[list[tuple[float, float]], bool, bool]:
"""A boiler's gas input as a piecewise-linear function of its heat
(docs/methods.md E6.4): breakpoints at 0 and the curve's load shares
(and full load), the efficiency there eta x the curve's factor (at most
1: no boiler gives more heat than the gas's gross calorific value, Hs),
the gas there heat / efficiency, linear between. ([(heat W of the
segment, gas W per W of heat in it)], convex: the slopes never fall (an
LP takes the cheap ones first by itself), capped: an efficiency was
held at 1)."""
shares = sorted({a for a, _ in pts if 0 < a < 1} | {1.0})
segs, q0, g0, capped = [], 0.0, 0.0, False
for a in shares:
e = eta * relative_efficiency(pts, a)
if e > 1.0:
e, capped = 1.0, True
q = a * qmax
g = q / e
if q > q0:
segs.append((q - q0, (g - g0) / (q - q0)))
q0, g0 = q, g
convex = all(s1 >= s0 - 1e-12 for (_, s0), (_, s1) in zip(segs, segs[1:]))
return segs, convex, capped
def cop_at(params: dict, t_out: float) -> float:
@@ -377,6 +736,30 @@ def cop_at(params: dict, t_out: float) -> float:
return pts[-1][1]
def _check_tank(cid: str, p: dict):
"""A hot-water tank's params (docs/methods.md A13): its heater one of
TANK_HEATERS, its class one of ERP_CLASSES, the top sensor's share in
(0, 1], grossanlage true or false, legionella plan | device | none, the
SG-Ready options for states "1".."4", a COP curve as heating's."""
if "heater" in p and p["heater"] not in TANK_HEATERS:
raise ValueError(f"control {cid}: heater is one of {', '.join(TANK_HEATERS)}")
if "erp_class" in p and p["erp_class"] not in ERP_CLASSES:
raise ValueError(f"control {cid}: erp_class is one of {', '.join(ERP_CLASSES)}")
if "top_share" in p and not 0 < float(p["top_share"]) <= 1:
raise ValueError(f"control {cid}: top_share is the top sensor's share of the volume, above 0 and at most 1")
if "grossanlage" in p and not isinstance(p["grossanlage"], bool):
raise ValueError(f"control {cid}: grossanlage is true or false")
if p.get("legionella", "device") not in ("plan", "device", "none"):
raise ValueError(f"control {cid}: legionella is plan, device or none")
opts = p.get("sg_options") or {}
if not isinstance(opts, dict) or set(map(str, opts)) - {"1", "2", "3", "4"}:
raise ValueError(f"control {cid}: sg_options names the select's option for the SG-Ready states 1-4")
curve = p.get("cop_curve") or []
if not isinstance(curve, list) or not all(isinstance(x, (list, tuple)) and len(x) == 2 and _num(x[0]) is not None
and _num(x[1]) is not None and float(x[1]) > 0 for x in curve):
raise ValueError(f"control {cid}: cop_curve is [[outside °C, COP > 0], ...]")
def _check_cover(cid: str, p: dict):
for k in ("open_pct", "shade_pct", "closed_pct"):
if k in p and (_num(p[k]) is None or not 0 <= float(p[k]) <= 100):
@@ -423,11 +806,19 @@ def parse(raw: list | None, reading_assets: set[str], rooms: set[str] | None = N
if kind == "cover":
_check_cover(cid, params)
for k in FACTS.get(kind, ()):
if k in params and (_num(params[k]) is None or float(params[k]) <= 0 or
(k.endswith("efficiency") and float(params[k]) > 1)):
if k in TEXT_FACTS or k not in params:
continue
if k in ZERO_OK:
if _num(params[k]) is None or float(params[k]) < 0:
raise ValueError(f"control {cid}: {k} is a number, 0 or more")
elif _num(params[k]) is None or float(params[k]) <= 0 or (k.endswith("efficiency") and float(params[k]) > 1):
raise ValueError(f"control {cid}: {k} is a number above 0" + (" and at most 1" if k.endswith("efficiency") else ""))
if kind == "battery" and params.get("standby_in_load") is not None and not isinstance(params["standby_in_load"], bool):
raise ValueError(f"control {cid}: standby_in_load is true or false")
if kind == "heating":
_check_heat(cid, params, ents)
if kind == "dhw_tank":
_check_tank(cid, params)
sw = {}
if c.get("switchover") is not None:
if kind not in ("heating", "cooling") or "climate" not in ents:
@@ -464,6 +855,11 @@ class Inputs:
# mapping's assets (mapping.controlled_power); an empty list: load_power
# has none of them in it.
controlled_power: list[str] | None = None
# the site's heat where no heating control plans it (a district-heated or
# gas-heated home without a room control: the plan's heat_outlook,
# docs/methods.md A2): {source: boiler | district, boiler_efficiency
# (0-1, Hs), max_heat_w, boiler_type, part_load_curve}; facts, no default
heat: dict = field(default_factory=dict)
def entities(self) -> list[str]:
one = [self.outside_temp, self.weather, self.sun]
@@ -479,4 +875,15 @@ def parse_inputs(raw: dict | None) -> Inputs:
unknown = set(raw) - set(Inputs.__dataclass_fields__)
if unknown:
raise ValueError(f"inputs: unknown keys {', '.join(sorted(unknown))}")
if raw.get("heat") is not None:
h = raw["heat"]
if not isinstance(h, dict) or set(h) - {"source", "boiler_efficiency", "max_heat_w", "boiler_type",
"part_load_curve", "fuel"} or h.get("source") not in ("boiler", "district") \
or h.get("fuel", "gas") not in FUELS:
raise ValueError("inputs.heat: {source: boiler | district, boiler_efficiency, max_heat_w, boiler_type, "
"part_load_curve, fuel: gas | oil}")
for k in ("boiler_efficiency", "max_heat_w"):
if k in h and (_num(h[k]) is None or float(h[k]) <= 0 or k == "boiler_efficiency" and float(h[k]) > 1):
raise ValueError(f"inputs.heat.{k}: a number above 0" + (" and at most 1" if k == "boiler_efficiency" else ""))
_check_part_load("inputs.heat", h)
return Inputs(**raw)
+35 -6
View File
@@ -49,12 +49,21 @@ log = logging.getLogger(__name__)
SLOT_S = 900
KEEP_DAYS = 400 # slots: this month and last, and a year back for a later view
KEEP_PRICE_DAYS = 3
CARRIERS = ("electricity", "gas", "heat")
CARRIERS = ("electricity", "gas", "heat", "oil")
# the meters the costs are read from: carrier, kind (a part, grid.1.import_energy, counts as its quantity)
ASSETS = {"grid.import_energy": ("electricity", "counter"), "grid.import_power": ("electricity", "gauge"),
"grid.power": ("electricity", "gauge"), # signed (import +): its positive part
"gas.energy": ("gas", "counter"), "heat.energy": ("heat", "counter")}
"gas.energy": ("gas", "counter"), "heat.energy": ("heat", "counter"),
# a boiler's own gas counter (simulated boilers map it; before 2026-11-08 not booked)
"boiler.gas_energy": ("gas", "counter"),
# heating oil (methods.md E15): kWh (Hi) where the device reports energy, else its oil meter's
# litres × the Parameters row de.heizoel_kwh_per_l (the tariff bundle's params)
"oil.energy": ("oil", "counter"), "oil.volume": ("oil", "litres"),
"boiler.oil_energy": ("oil", "counter"), "boiler.oil_volume": ("oil", "litres")}
OIL_KWH_PER_L = "de.heizoel_kwh_per_l"
PREFER = ("grid.import_energy", "grid.import_power", "grid.power") # electricity: the counter first
# gas and oil: the house's meter before the boiler's own (one of them, never both: the same fuel)
PREFER_FUEL = ("gas.energy", "boiler.gas_energy", "oil.energy", "oil.volume", "boiler.oil_energy", "boiler.oil_volume")
PARAM_FORECAST = "costs.forecast_days" # the Parameters page (fleet), in the tariff bundle's params
FORECAST_DAYS = (1, 62) # the parameter's valid range
REPORT_EVERY_S = 60 # HA's figures made again at most this often (announce.py)
@@ -86,7 +95,7 @@ def _finite(v) -> bool:
return isinstance(v, (int, float)) and not isinstance(v, bool) and math.isfinite(v)
def amounts(records: list[dict], span_s: float) -> dict[str, float | None]:
def amounts(records: list[dict], span_s: float, oil_kwh_per_l: float | None = None) -> dict[str, float | None]:
"""A closed window's kWh per carrier from the cost aggregator's records
(telemetry.Aggregator): the counters' deltas (Wh) where the carrier has
a counter that has a reading, else its power's mean (W) over the
@@ -101,13 +110,18 @@ def amounts(records: list[dict], span_s: float) -> dict[str, float | None]:
if kind == "counter":
v = r.get("delta") if r.get("last") is not None else None
v = v / 1000.0 if _finite(v) else None
elif kind == "litres":
# litres of oil: kWh only with the conversion row (none: no value, never litres as kWh)
v = r.get("delta") if r.get("last") is not None else None
v = v * oil_kwh_per_l if _finite(v) and _finite(oil_kwh_per_l) and oil_kwh_per_l > 0 else None
else:
m = r.get("mean")
v = (max(m, 0.0) if q == "grid.power" else m) * span_s / 3600.0 / 1000.0 if _finite(m) else None
by.setdefault(carrier, {}).setdefault(q, []).append(v)
out = {}
for carrier, qs in by.items():
order = [q for q in PREFER if q in qs] if carrier == "electricity" else list(qs)
order = [q for q in PREFER if q in qs] if carrier == "electricity" else \
[q for q in PREFER_FUEL if q in qs] + [q for q in qs if q not in PREFER_FUEL]
got = None
for q in order:
vals = qs[q]
@@ -140,6 +154,7 @@ class Ledger:
"offer INTEGER NOT NULL DEFAULT 0) WITHOUT ROWID")
self.pending: dict[int, dict] = {} # slot -> the latest plan's estimate for it (step 0)
self._booked = 0 # the last slot whose plan estimate is booked
self.outlook: dict | None = None # the last plan's heat outlook: carrier, eur, input_kwh, hours
def close(self):
with self.lock:
@@ -191,7 +206,11 @@ class Ledger:
estimate of slots that ended. Returns the kWh booked per carrier."""
span = max(0.0, end - start)
slot = int(start // SLOT_S * SLOT_S)
got = amounts(records, span)
try:
kwh_l = float(self.bundles.box_params(self.clock()).get(OIL_KWH_PER_L))
except (TypeError, ValueError, AttributeError):
kwh_l = None
got = amounts(records, span, kwh_l)
sp = self.bundles.slot_prices(start, self.clock())
fixed = self.bundles.fixed_charges(start)
with self.lock:
@@ -234,6 +253,10 @@ class Ledger:
optimizer.step_costs), booked when the quarter-hour ends; a later
plan in the same quarter-hour replaces it."""
se, start, step = plan.get("steps_eur"), plan.get("start"), plan.get("step_s") or SLOT_S
# the heat no room model plans: its expected bill over the plan's horizon (methods A2.16, A12)
ho = plan.get("heat_outlook")
self.outlook = {k: ho.get(k) for k in ("carrier", "eur", "input_kwh")} | {
"hours": round((plan.get("steps") or 0) * step / 3600.0)} if isinstance(ho, dict) else None
if not isinstance(se, dict) or not _finite(start):
return
now = self.clock()
@@ -301,7 +324,7 @@ class Ledger:
with self.lock:
kept = {c for (c,) in self.db.execute("SELECT DISTINCT carrier FROM months")}
sp = self.bundles.slot_prices(now, now) or {}
for c in ("gas", "heat"):
for c in ("gas", "heat", "oil"):
if c in kept or (sp.get(c) or {}).get("price") is not None:
out.append(c)
return out
@@ -504,6 +527,12 @@ def costs_section(ledger: Ledger, now: float, lang: str, meters: dict[str, bool]
notes += [r["note"] for r in out["carriers"].values() if r.get("note")]
if days is not None:
notes.append(names.name("cs_forecast_how", lang, int(days)))
ho = getattr(ledger, "outlook", None)
if ho and _finite(ho.get("eur")):
# the heat no room model plans: what the last plan expects it to cost (methods A2.16)
out["heat_outlook"] = ho
notes.append(names.name("cs_heat_outlook", lang, names.name("carrier_" + str(ho.get("carrier")), lang),
ho.get("hours"), _eur(ho["eur"], lang), names.number(ho.get("input_kwh") or 0.0, lang, 1)))
out["md"] = hdr + "\n".join(rows) + "\n\n<small>" + " ".join(notes) + "</small>"
return out
+221 -10
View File
@@ -41,7 +41,13 @@ control, the texts' version, source). With it, each device's reading and
control are switched on here as on the Hub's Devices page (the agent starts
again, as the Hub's tool restarts it); without it the page points to the
add-on's configuration. Protection (protected / not, never sealed) and a thermostat's heating or
cooling choice are the owner's, here as on the Hub.
cooling choice are the owner's, here as on the Hub; so are a device's Ratings (its profile's
rating fields: a battery's capacity, power, efficiency and idle loss; a hot-water tank's volume,
heater power, COP and standing loss; each a number above 0, into devices-specs.json, which the
agent reads at every plan) and a hot-water tank's heater (element, heat pump, boiler, district
heat: params.heater in its fragment). A battery's idle loss and a tank's facts show with their
source from the agent's latest plan (its preferences view's "planning": storage, refused;
docs/design/storage-losses.md 10.5).
Remote Home Assistant for Cantabile support (item 19; the
add-on's option support_ha, off by default): while support has this Home
@@ -52,8 +58,8 @@ open sessions and its pid into its state directory (support-ha.json), End
now sends it SIGUSR1, as the Hub's panel does, and the link closes the
session and disables that user. What the Hub's panel keeps from support
stays the owner's here too: reading and control, protection, heating or
cooling, a shade's window, indoor or outdoor and the weather choice are
refused to the "Cantabile support" user.
cooling, a shade's window, indoor or outdoor, the weather choice, the
ratings and a tank's heater are refused to the "Cantabile support" user.
"""
import asyncio
import json
@@ -83,7 +89,9 @@ OWNERS_ONLY = {"consent": M("Reading and control are the owner's to switch on.")
"switchover": M("Heating or cooling is the owner's to choose."),
"shade": M("The shade's room and window are the owner's to set."),
"place": M("Indoor or outdoor is the owner's to choose."),
"weather": M("The weather forecast is the owner's to choose.")}
"weather": M("The weather forecast is the owner's to choose."),
"ratings": M("The ratings are the owner's to enter."),
"tank": M("The tank's heater is the owner's to choose.")}
SWITCHOVER_WORDS = {"heating": M("Heating"), "cooling": M("Cooling"),
"season": M("By season (heating October to April, cooling May to September)"),
"outdoor": M("By outdoor temperature")}
@@ -94,7 +102,7 @@ PROFILE_STATUS = {"verified": (M("checked"), "ok", M("Checked on a device: its v
"device. Look at its values before you turn reading on.")),
"draft": (M("draft"), "warn", M("A draft profile: check the values before you turn reading on."))}
CONTROL_WORDS = {"battery": M("battery"), "heating": M("heating"), "cooling": M("cooling"), "ev": M("charging"),
"cover": M("blinds and curtains")}
"cover": M("blinds and curtains"), "dhw_tank": M("hot-water tank")}
# What a device reads, by meaning (the devices tool gives the keys:
# devprofiles.reads); never the asset ids.
QUANTITY_WORDS = {
@@ -113,16 +121,22 @@ QUANTITY_WORDS = {
"heat.power": M("heat delivered (thermal)"), "heat.energy": M("heat energy (thermal)"), "heatpump.flow_temp": M("flow temperature"),
"heatpump.dhw_temp": M("hot water temperature"), "outside.temp": M("outdoor temperature"),
"outside.humidity": M("outdoor humidity"), "gas.energy": M("gas"), "ev.power": M("charging power"),
"ev.energy": M("energy charged"), "circuit.power": M("power"), "circuit.energy": M("energy")}
"ev.energy": M("energy charged"), "circuit.power": M("power"), "circuit.energy": M("energy"),
"dhw.power": M("hot water heat (thermal)"), "dhw.energy": M("hot water heat energy (thermal)"),
"dhw.volume": M("hot water drawn"), "battery.standby_power": M("battery idle use"),
"dhw.temp_top": M("tank temperature (top)"), "dhw.temp_bottom": M("tank temperature (bottom)"),
"dhw.heater_power": M("tank heater power"), "dhw.tank_energy": M("heat stored in the tank")}
# A device's main values now (devprofiles.live) on the list.
LIVE_WORDS = {"room.setpoint": M("set to {v}"), "room.setpoint_range": M("set to {low}–{high}"),
"pv.power": M("solar {v}"), "battery.soc": M("battery {v}"), "battery.power": M("battery {v}"),
"grid.power": M("grid {v}"), "load.power": M("home {v}"), "ev.power": M("charging {v}"),
"heatpump.power": M("heat pump {v}"), "heat.power": M("heat {v} (thermal)"), "heatpump.flow_temp": M("flow {v}"),
"outside.temp": M("outside {v}"), "room.humidity": M("humidity {v}"), "room.shade_position": M("{v} open")}
"outside.temp": M("outside {v}"), "room.humidity": M("humidity {v}"), "room.shade_position": M("{v} open"),
"dhw.temp_top": M("tank {v}"), "dhw.heater_power": M("heater {v}")}
HVAC_WORDS = {"heating": M("heating"), "cooling": M("cooling"), "idle": M("idle")}
LIVE_UNITS = {"room.temp": "°C", "room.setpoint": "°C", "room.setpoint_range": "°C", "heatpump.flow_temp": "°C",
"outside.temp": "°C", "battery.soc": "%", "room.humidity": "%", "room.shade_position": "%"}
"outside.temp": "°C", "battery.soc": "%", "room.humidity": "%", "room.shade_position": "%",
"dhw.temp_top": "°C"}
MORE_CSS = """nav{display:flex;gap:1rem;margin:0 0 1rem;border-bottom:1px solid #d5ded9;padding-bottom:.5rem}
nav a{color:inherit;text-decoration:none}nav a.on{font-weight:600;border-bottom:2px solid #2f6f55}
a{color:#2f6f55}.muted,.model{color:#5a6b62;font-size:.85rem}
@@ -239,6 +253,12 @@ class Devices:
def profile(self, pid: str) -> dict | None:
return next((p for p in self.profiles if p.get("id") == pid), None)
def planning(self) -> dict:
"""The agent's latest plan on its stores and refusals (its
preferences view, as the Hub's panel reads it: "planning")."""
p = _read_json(os.path.join(self.state_dir, "preferences-view.json"), {}).get("planning")
return p if isinstance(p, dict) else {}
def write_specs(self, devs: dict):
"""Each device's specs for the agent's inventory (as the Hub's tool)."""
policy, out = self.policy(), {}
@@ -312,6 +332,7 @@ class Devices:
ha_error = ""
except Exception as e:
reg, states, ha_error = {}, {}, str(e)
planning = self.planning()
used = []
for d in sorted(devs.values(), key=lambda d: d.get("added", 0)):
frag, p = self.frag(d["id"]), self.profile(d["profile"]) or {}
@@ -323,7 +344,9 @@ class Devices:
assumed=dp.reads([a for a in assets if a.get("assumed")]), lacks=dp.lacks(d.get("missing")),
switchover=dp.switchover_of(frag), shade=dp.shade_of(frag), place=dp.place_of(frag),
weather=dp.weather_of(frag), policy={t: policy[t] for t in targets if t in policy},
protection=dp.level_of(policy, [f"device:{d['id']}"])[0]))
protection=dp.level_of(policy, [f"device:{d['id']}"])[0],
rating_fields=dp.rating_fields(p, d), tank=dp.tank_of(frag),
storage=dp.storage_of(frag, d.get("ratings") or {}, planning)))
if ha_error:
return {"devices": used, "offers": [], "rest": [], "ha_error": ha_error, "site": self.site(), "rooms": []}
main = self.main()
@@ -503,6 +526,35 @@ class Devices:
log.info("place: %s: %s %s", dev["name"], pl["place"], pl["area"])
await self._done(devs, restart=True)
async def ratings(self, dev_id: str, data: dict):
"""The owner's ratings (the profile's rating fields: a battery's
capacity, power, efficiency, idle loss; a tank's volume, heater,
loss), as the Hub's devices tool takes them: each a number above 0,
an empty field removes it. Into the device's specs, which the agent
reads at every plan (controller.owner_ratings)."""
async with self.lock:
devs = self.load()
dev = self._dev(devs, dev_id)
p = self.profile(dev["profile"]) or {}
dev["ratings"] = dp.ratings_of(p, dp.rating_values(p, data))
frag = self.frag(dev_id)
meter = bool(frag) and dp.meter_unit(frag, dev["ratings"])
if meter:
self.write_frag(dev_id, frag)
self.save(devs)
log.info("ratings: %s: %s", dev["name"],
", ".join(f"{k} {v:g}" for k, v in sorted(dev["ratings"].items())) or "none")
await self._done(devs)
async def tank(self, dev_id: str, data: dict):
"""A hot-water tank's heater (element, heat_pump, boiler, district)."""
async with self.lock:
devs, dev, frag = await self._setting(dev_id)
t = dp.set_tank_heater(frag, data)
self.write_frag(dev_id, frag)
log.info("tank: %s: heater %s", dev["name"], t["heater"])
await self._done(devs, restart=True)
async def weather(self, dev_id: str):
"""This weather service's forecast plans; the others are kept, unused."""
async with self.lock:
@@ -772,6 +824,158 @@ def weather_html(d: dict) -> str:
+ form("weather", hidden(id=d["id"]), T("Plan with this forecast"), "secondary"))
# The owner's ratings (the profile's rating fields), in this page's words
# where it has them, as the Hub panel's Ratings.
RATING_WORDS = {
"battery_kwh": M("Battery capacity, kWh"), "battery_kw": M("Battery power, kW"),
"battery_efficiency_pct": M("Battery round-trip efficiency, % (datasheet)"),
"battery_standby_w": M("Battery idle loss, W (optional; datasheet or measured; leave empty and the box learns it)"),
"battery_self_discharge_pct_month": M("Battery self-discharge, %/month (optional; datasheet)"),
"tank_volume_l": M("Hot-water tank, litres (the type plate; needed: the tank is not planned without it)"),
"tank_heater_kw": M("Tank heater, kW (electric for an element or heat pump, heat for a boiler or district heat; "
"needed)"),
"tank_cop": M("Tank heat pump COP (datasheet, EN 16147; a heat pump only)"),
"tank_standby_w": M("Tank standing loss (ErP S), W (the label or datasheet; kWh per 24 h ÷ 0.024)"),
"tank_erp_class": M("Tank ErP class (1 A+, 2 A, 3 B, 4 C, 5 D, 6 E, 7 F; where the standing loss is not known)"),
"tank_max_c": M("Tank maximum, °C (optional)"), "tank_room_c": M("Room temperature at the tank, °C (optional)"),
"tank_grossanlage": M("Large system, DVGW W 551 (1: yes; optional, else from the volume)"),
# a hot-water meter's (devprofiles.dhw_factor, meter_unit)
"dhw_litres_per_unit": M("Hot-water meter: litres per unit it counts (1 for L, 1000 for m³; only where Home "
"Assistant shows no unit or a wrong one)"),
"dhw_kwh_per_m3": M("Hot water: kWh of heat per m³ drawn (optional; else from the two temperatures)"),
"dhw_cold_c": M("Cold water temperature, °C (optional)"),
"dhw_hot_c": M("Hot water temperature at the tap, °C (optional)"),
}
METER_RATINGS = ("dhw_litres_per_unit", "dhw_kwh_per_m3", "dhw_cold_c", "dhw_hot_c")
# Storage with losses (docs/design/storage-losses.md 2.3, 10.4, 10.5): where
# a battery's idle loss and a tank's facts come from (devprofiles.storage_of).
# A missing idle loss is no alarm: a quiet line.
STORE_SOURCE = {"mapping": M("the installer's setting"), "device": M("reported by the device"),
"learnt": M("learnt by the box"), "owner": M("your rating")}
TANK_LOSS_SOURCE = {"mapping": M("the installer's setting"), "device": M("reported by the tank"),
"learnt": M("learnt by the box"), "owner": M("from the label (your rating)")}
TANK_HEATERS = {"element": M("Immersion heater (element)"), "heat_pump": M("Heat pump"),
"boiler": M("Boiler (gas or oil)"), "district": M("District heat")}
TANK_MISSING = {"volume_l": M("the tank's volume (Ratings)"), "heater": M("its heater (above)"),
"max_power_w": M("the heater's power (Ratings)"), "max_heat_w": M("the heater's power (Ratings)"),
"cop": M("the heat pump's COP (Ratings)"),
"temp_sensor": M("a tank temperature (the water heater's own, or a sensor)"),
"boiler_efficiency": M("the boiler's efficiency"), "gas_price": M("a gas price"),
"heat_price": M("a heat price")}
def _assumed(src) -> bool:
return src in ("parameter", "assumed")
def battery_store_lines(x: dict) -> list:
"""A battery's idle loss and self-discharge, each with its source, one line each."""
out = []
w, src = x.get("standby_w"), x.get("standby_src")
if w is not None and src in STORE_SOURCE:
line = T("Idle loss {w} W ({source})", w=_num(w, 0), source=T(STORE_SOURCE[src]))
elif w is not None and _assumed(src):
line = T("Idle loss {w} W assumed (Parameters): enter the datasheet's value below.", w=_num(w, 0))
elif src == "none":
line = T("Idle loss not modelled yet: enter the datasheet's value below, or the box learns it.")
else:
line = ""
if line and x.get("idle_loss_kwh_24h") is not None:
line += " · " + T("about {kwh} kWh a day", kwh=_num(x["idle_loss_kwh_24h"], 2))
if line:
out.append(line)
pct, psrc = x.get("self_discharge_pct_month"), x.get("self_discharge_src")
if pct is not None and psrc in STORE_SOURCE:
out.append(T("Self-discharge {pct} %/month ({source})", pct=_num(pct), source=T(STORE_SOURCE[psrc])))
elif pct is not None and _assumed(psrc):
out.append(T("Self-discharge {pct} %/month assumed (Parameters)", pct=_num(pct)))
return out
def ratings_html(d: dict) -> str:
"""The owner's ratings, a battery's idle loss from the agent's plan
above them (quiet: the box learns it, the Parameters row stands in)."""
fs = [f for f in d.get("rating_fields") or [] if isinstance(f, dict) and f.get("name")]
if not fs:
return ""
kinds = {f.get("rating") for f in fs}
lines = [x for s in d.get("storage") or [] if isinstance(s, dict) and s.get("kind") == "battery"
for x in battery_store_lines(s)]
head = "".join(f'<p class="note">{E(x)}</p>' for x in lines)
if kinds & set(METER_RATINGS):
about = T("From the meter and the installation. The heat of the hot water drawn is the volume times the kWh "
"per m³ given here, else 1.163 kWh per m³ and kelvin times the hot less the cold water's temperature; "
"with neither, Cantabile's suggested temperature rise (the Parameters page), and it says so. An empty "
"field: not known.")
elif any(str(k).startswith("tank_") for k in kinds):
about = T("From the tank's type plate, label or datasheet. Cantabile plans the tank only when it knows its "
"volume, its heater's power and, for a heat pump, its COP; it never guesses them. Without the "
"standing loss or the ErP class it takes class D's limit (the Parameters page) until it has learnt "
"the tank's own. An empty field: not known.")
else:
about = T("From the device's datasheet or nameplate. Cantabile plans a battery only when it knows its capacity, "
"power and efficiency; it never guesses them. An empty field: not known.")
inner = hidden(id=d["id"]) + "".join(
f'<label for="r-{E(f["name"])}">{E(T(RATING_WORDS[f["rating"]]) if f.get("rating") in RATING_WORDS else f.get("label", ""))}'
f'</label><input id="r-{E(f["name"])}" name="f_{E(f["name"])}" type="number" step="any" '
f'value="{E("" if f.get("value") is None else format(float(f["value"]), "g"))}" autocomplete="off">'
for f in fs)
return section(T("Ratings"), head + form("ratings", inner, T("Save")), info(E(about)))
def tank_html(d: dict) -> str:
"""A hot-water tank: its heater (the owner's choice where the profile
cannot know it), what it is not planned without (user-fixable: a
warning), its facts and the standing loss's source."""
t = d.get("tank")
if not t:
return ""
x = next((s for s in d.get("storage") or [] if isinstance(s, dict) and s.get("kind") == "dhw_tank"), {})
heater = t.get("heater") or ""
body = ""
miss = [str(m) for m in x.get("missing") or []]
if miss:
words = [T(TANK_MISSING[m]) if m in TANK_MISSING else T("the Parameters row {key}", key=m) if m.startswith("dhw.")
else m for m in miss]
body += (f'<div class="box warn"><b>{E(T("Needed: the tank is not planned without it."))}</b> '
+ E(", ".join(dict.fromkeys(words))) + ". " + E(T("Meanwhile it keeps its own thermostat.")) + "</div>")
elif x.get("refused") and x.get("why"):
body += f'<div class="box warn">{E(T("Not planned: {why}.", why=x["why"]))}</div>'
facts = []
if x.get("volume_l") is not None:
facts.append(T("{l} L", l=_num(x["volume_l"], 0)))
if x.get("heater_kw") is not None:
facts.append(T("heater {kw} kW", kw=_num(x["heater_kw"], 2)))
if x.get("cop") is not None and heater == "heat_pump":
facts.append(T("COP {cop}", cop=_num(x["cop"], 2)))
if x.get("temp_c") is not None:
facts.append(T("now {c} °C", c=_num(x["temp_c"])))
if x.get("usable_kwh") is not None:
facts.append(T("{kwh} kWh usable", kwh=_num(x["usable_kwh"])))
if facts:
body += f'<p class="note">{E(" · ".join(facts))}</p>'
w, src, cls = x.get("standby_w"), x.get("loss_src"), x.get("erp_class")
if w is not None:
if _assumed(src):
loss = (T("Standing loss {w} W assumed: class {cls}'s limit (Parameters). Enter the label's value below.",
w=_num(w, 0), cls=cls) if cls else
T("Standing loss {w} W assumed (Parameters). Enter the label's value below.", w=_num(w, 0)))
else:
loss = (T("Standing loss {w} W ({source})", w=_num(w, 0), source=T(TANK_LOSS_SOURCE[src]))
if src in TANK_LOSS_SOURCE else T("Standing loss {w} W", w=_num(w, 0)))
loss += " · " + T("class {cls}", cls=cls) if cls else ""
body += f'<p class="note">{E(loss)}</p>'
opts = (f'<option value=""{" selected" if not heater else ""} disabled>{E(T("Choose its heater"))}</option>'
+ "".join(f'<option value="{k}"{" selected" if k == heater else ""}>{E(T(w))}</option>'
for k, w in TANK_HEATERS.items()))
inner = (hidden(id=d["id"]) + f'<label for="heater-{E(d["id"])}">{E(T("Its heater"))}</label>'
f'<select id="heater-{E(d["id"])}" name="heater">{opts}</select>')
about = info(E(T("Cantabile heats the tank when heat is cheap (solar surplus, a low price) and keeps it above your "
"minimum; the tank's own thermostat stays the last limit. Its heater says what the heat costs: "
"electricity for an element or a heat pump, gas or district heat for the others.")))
return section(T("Hot-water tank"), body + form("tank", inner, T("Save"), "save", form_cls="changes"), about)
def protection_html(d: dict) -> str:
"""Per target a switch for the owner; sealed ones locked with their
custodian."""
@@ -910,7 +1114,8 @@ def page_device(v: dict, dev_id: str, msg: str = "", err: str = "", banner: str
f'<div class="box now"><span class="state">{device_state(d)}</span>'
+ (f'<span class="values">{E(vals)}</span>' if vals else "") + "</div>"
+ consent_html(d, v.get("site") or {}) + reads_html(d, rooms) + switchover_html(d) + shade_html(d, rooms)
+ place_html(d, rooms) + weather_html(d) + protection_html(d) + remove_html(d))
+ place_html(d, rooms) + weather_html(d) + tank_html(d) + ratings_html(d) + protection_html(d)
+ remove_html(d))
return html(f'Cantabile: {d["name"]}', body, "devices")
@@ -1067,6 +1272,12 @@ class App(JoinPage):
elif do == "weather":
await dv.weather(f.get("id", ""))
msg = T("Saved. Cantabile starts again to apply it (a few seconds).")
elif do == "ratings":
await dv.ratings(f.get("id", ""), {k[2:]: v for k, v in f.items() if k.startswith("f_")})
msg = T("Saved. The next plan uses them.")
elif do == "tank":
await dv.tank(f.get("id", ""), {"heater": f.get("heater", "")})
msg = T("Saved. Cantabile starts again to apply it (a few seconds).")
elif do == "switchover":
data = {"mode": f.get("mode", "")}
if data["mode"] == "outdoor":
+272 -7
View File
@@ -43,6 +43,16 @@ QUANTITIES = {
"room.setpoint_low": ("°C", "gauge"), "room.setpoint_high": ("°C", "gauge"),
"room.shade_position": ("%", "gauge"), "room.shade_tilt": ("%", "gauge"), "circuit.power": ("W", "gauge"),
"circuit.energy": ("Wh", "counter"),
# a hot-water meter (heat for hot water, the water drawn: docs/methods.md B16)
"dhw.power": ("W", "gauge"), "dhw.energy": ("Wh", "counter"), "dhw.volume": ("L", "counter"),
# storage with losses (docs/design/storage-losses.md 10.3): a battery's own report of its idle use; a
# hot-water tank's temperatures, its heater's power and the heat it holds above the cold water (S.4)
"battery.standby_power": ("W", "gauge"),
"dhw.temp_top": ("°C", "gauge"), "dhw.temp_bottom": ("°C", "gauge"), "dhw.heater_power": ("W", "gauge"),
"dhw.tank_energy": ("Wh", "gauge"),
# an oil boiler's fuel (branch heating-oil, 2026-11-08; methods.md E15): the litres its oil meter
# counts, or the kWh (Heizwert) where the device reports energy
"oil.volume": ("L", "counter"), "oil.energy": ("Wh", "counter"),
}
# room.* and circuit.* are per place: room.<area>.temp (the device's area).
PER_PLACE = ("room", "circuit")
@@ -50,8 +60,51 @@ PER_PLACE = ("room", "circuit")
# them (pv.1.power, pv.2.power) and sums their total (edge mapping.py).
SUMMED = ("grid", "pv", "battery", "load", "heatpump", "heat", "ev", "gas")
PART_RE = re.compile(r"^(" + "|".join(SUMMED) + r")\.(\d{1,3})\.([a-z_]+)$")
# A control's roles that write to the device.
WRITE_ROLES = {"charge_from_grid", "setpoint", "mode", "climate", "switch", "current", "cover"}
# A control's roles that write to the device (a hot-water tank's
# water_heater: its target temperature; sg_ready: its SG-Ready state).
WRITE_ROLES = {"charge_from_grid", "setpoint", "mode", "climate", "switch", "current", "cover", "water_heater", "sg_ready"}
# Roles that write only on some kinds: a tank's "power" is a stepless
# heater's watts (a number); a battery's or a car's "power" is a reading.
KIND_WRITE_ROLES = {"dhw_tank": {"power"}}
def is_write(kind, role) -> bool:
"""Does this role of a control of this kind write to the device?"""
return role in WRITE_ROLES or role in KIND_WRITE_ROLES.get(kind, ())
# The owner's ratings of a device (the inventory): from the
# profile, the owner's answers (a profile field with "rating", the Devices
# pages' Ratings) or HA; the agent's plans, the cloud's planners and model
# training read them (devices-specs.json). Each is a number above 0.
RATINGS = {"inverter_kw": "Inverter power, kW", "pv_kwp": "Solar panels, kWp", "battery_kwh": "Battery capacity, kWh",
"battery_kw": "Battery power, kW", "battery_efficiency_pct": "Battery round-trip efficiency, %",
"heatpump_kw": "Heat pump, kW (electric)", "heat_kw": "Heating power, kW",
# a gas boiler's efficiency: heat per kWh of gas billed (Brennwert Hs; edge controls.heat_facts)
"boiler_efficiency_pct": "Boiler efficiency, % (heat per kWh of gas billed)",
"ev_kw": "Charging power, kW", "circuit_a": "Circuit breaker, A", "grid_connection_kw": "Grid connection, kW",
"phases": "Phases",
# a hot-water meter counting the water drawn (dhw_factor, meter_unit): its unit where HA gives
# none or a wrong one (1: L, 1000: m³), kWh of heat per m³, or the two temperatures
"dhw_litres_per_unit": "Hot-water meter: litres per unit it counts (1: L, 1000: m³)",
"dhw_kwh_per_m3": "Hot water: kWh of heat per m³", "dhw_cold_c": "Cold water, °C",
"dhw_hot_c": "Hot water at the tap, °C",
# storage with losses (docs/design/storage-losses.md 10.2): the battery's idle loss and
# self-discharge; a hot-water tank's facts (its ErP class as a number: ratings are above 0)
"battery_standby_w": "Battery idle loss, W",
"battery_self_discharge_pct_month": "Battery self-discharge, %/month",
"tank_volume_l": "Hot-water tank, litres",
"tank_heater_kw": "Tank heater, kW (electric for an element or heat pump, heat for a boiler or district heat)",
"tank_cop": "Tank heat pump COP", "tank_standby_w": "Tank standing loss (ErP S), W",
"tank_erp_class": "Tank ErP class (1 A+, 2 A, 3 B, 4 C, 5 D, 6 E, 7 F)", "tank_max_c": "Tank maximum, °C",
"tank_room_c": "Room temperature at the tank, °C", "tank_grossanlage": "Large system, DVGW W 551 (1: yes)"}
# The ErP classes by the rating tank_erp_class (1-7).
ERP_CLASSES = ("A+", "A", "B", "C", "D", "E", "F")
# A hot-water tank's heater (the mapping's params.heater, edge controls.py
# dhw_tank): the installer's choice on the Devices page where the profile
# cannot know it (any HA water_heater); a profile may set it (a relay's
# element).
HEATERS = ("element", "heat_pump", "boiler", "district")
# Heating or cooling for a thermostat that does both (the agent's
# switchover.py): the owner's choice; by season at first.
SWITCHOVER_MODES = ("heating", "cooling", "season", "outdoor")
@@ -65,6 +118,65 @@ RANK = {"none": 0, "protected": 1, "sealed": 2}
IDS_RE = re.compile(r"""(?:^|[\s{,-])["']?(?:asset|id)["']?\s*:\s*["']?([A-Za-z0-9_.-]+)""", re.M)
# A hot-water meter that counts the water drawn (dhw.volume, litres): its
# heat is the volume times kWh per m³, the installer's (the device's
# ratings on the Devices page, or the mapping asset's own): kwh_per_m3, or
# 1.163 x (hot_c - cold_c); else the Parameters row dhw.temperature_lift_k
# (the tariff bundle's params) x 1.163; else not converted. 1.163 kWh per
# m³ and K: water's heat capacity (physics).
WATER_KWH_PER_M3_K = 1.163
DHW_LIFT_KEY = "dhw.temperature_lift_k"
# the meter's unit where Home Assistant gives none or a wrong one (the
# rating dhw_litres_per_unit: litres per unit the entity counts)
LITRES_UNIT = {1.0: "L", 1000.0: "m³"}
def _f(v):
try:
x = float(v)
except (TypeError, ValueError):
return None
return x if x == x and abs(x) != float("inf") else None
def dhw_factor(facts: dict, params: dict | None) -> tuple:
"""A hot-water meter's kWh of heat per m³ drawn: (factor or None,
source "installer" | "parameter" | "", a note where it is not the
installer's). facts: dhw_kwh_per_m3, else dhw_cold_c and dhw_hot_c
(the device's ratings or the mapping asset's); params: the box's
Parameters values (dhw.temperature_lift_k)."""
k = _f((facts or {}).get("dhw_kwh_per_m3"))
if k is not None and k > 0:
return round(k, 3), "installer", ""
cold, hot = _f((facts or {}).get("dhw_cold_c")), _f((facts or {}).get("dhw_hot_c"))
if cold is not None and hot is not None and hot > cold:
return round(WATER_KWH_PER_M3_K * (hot - cold), 3), "installer", ""
lift = _f((params or {}).get(DHW_LIFT_KEY))
if lift is not None and lift > 0:
return (round(WATER_KWH_PER_M3_K * lift, 3), "parameter",
f"dhw.volume: no installer's kWh per m³ or temperatures: the Parameters row {DHW_LIFT_KEY} ({lift:g} K)")
return None, "", (f"dhw.volume: not converted to heat (no installer's kWh per m³ or temperatures, "
f"no {DHW_LIFT_KEY})")
def meter_unit(frag: dict, ratings: dict) -> bool:
"""The unit a device's hot-water volume meter counts in, from its
rating dhw_litres_per_unit (1: L, 1000: m³) into its fragment's
dhw.volume asset (unit_in: over Home Assistant's unit); no rating: HA's
unit. In place; True where it changed."""
want = LITRES_UNIT.get(_f((ratings or {}).get("dhw_litres_per_unit")))
changed = False
for a in frag.get("assets") or []:
if not isinstance(a, dict) or not str(a.get("asset", "")).startswith("dhw.volume"):
continue
if want and a.get("unit_in") != want:
a["unit_in"], changed = want, True
elif not want and "unit_in" in a:
a.pop("unit_in")
changed = True
return changed
def part_of(asset: str):
"""pv.2.power -> ("pv.power", 2); None for anything else."""
m = PART_RE.match(asset)
@@ -280,9 +392,11 @@ def mapping_for(dev_id, p, s, ents, area, taken, main=()):
for c in s.get("controls", []):
ents_c, lost = {}, []
for role, m in c["entities"].items():
e = find(m)
e = find({k: v for k, v in m.items() if k != "optional"})
if e:
ents_c[role] = e["entity_id"]
elif m.get("optional"):
continue # a role the control has where the device has it (a tank's bottom sensor)
elif m.get("supports") and find({k: v for k, v in m.items() if k != "supports"}):
lost.append(None) # the device has no such mode (a cooling-only A/C: no heating)
else:
@@ -292,7 +406,7 @@ def mapping_for(dev_id, p, s, ents, area, taken, main=()):
if lost:
missing.append(f"{c['kind']} control ({', '.join(lost)})")
continue
writes = {e for r, e in ents_c.items() if r in WRITE_ROLES}
writes = {e for r, e in ents_c.items() if is_write(c["kind"], r)}
ctl = {"id": free_id(c["kind"], taken) if not writes & set(written) else None, "kind": c["kind"],
"consent": False, "entities": ents_c}
if writes & set(written):
@@ -333,7 +447,7 @@ def leave_out(frag: dict, entities=(), written=()) -> tuple[list, list]:
frag["assets"] = [a for a in frag.get("assets", []) if a["entity"] not in entities]
gone_c, keep = [], []
for c in frag.get("controls", []):
writes = {e for r, e in (c.get("entities") or {}).items() if r in WRITE_ROLES}
writes = {e for r, e in (c.get("entities") or {}).items() if is_write(c.get("kind"), r)}
(gone_c.append(c["kind"]) if writes & written else keep.append(c))
frag["controls"] = keep
return gone_a, gone_c
@@ -341,7 +455,7 @@ def leave_out(frag: dict, entities=(), written=()) -> tuple[list, list]:
def control_writes(controls) -> set:
"""The entities some control writes to."""
return {e for c in controls or [] for r, e in (c.get("entities") or {}).items() if r in WRITE_ROLES}
return {e for c in controls or [] for r, e in (c.get("entities") or {}).items() if is_write(c.get("kind"), r)}
def switchover_of(frag: dict) -> dict | None:
@@ -444,6 +558,43 @@ def ratings_of(p: dict, vals: dict) -> dict:
return out
def rating_fields(p: dict, dev: dict) -> list:
"""The profile's rating fields with the device's value of each (None: not given)."""
have = dev.get("ratings") or {}
return [{"name": f["name"], "label": f["label"], "rating": f["rating"], "value": have.get(f["rating"])}
for f in p.get("fields") or [] if f.get("rating")]
def rating_value(f: dict, v):
"""One rating field's answer: None (empty: not known), else a number
above 0 within the field's min and max (Fail with the field's label)."""
v = str(v).strip() if v is not None else ""
if v == "":
return None
try:
n = float(v) if f.get("type") == "number" else int(v)
except ValueError:
raise Fail(f"{f['label']}: a number") from None
lo, hi = f.get("min", -2 ** 31), f.get("max", 2 ** 31)
if not (lo <= n <= hi) or n != n:
raise Fail(f"{f['label']}: {lo} to {hi}")
if n <= 0:
raise Fail(f"{f['label']}: a number above 0 (empty: not known)")
return n
def rating_values(p: dict, given: dict) -> dict:
"""The owner's ratings from a Ratings form ({field name: text}): the
profile's rating fields only, each checked; an empty one left out."""
out = {}
for f in p.get("fields") or []:
if f.get("rating"):
n = rating_value(f, (given or {}).get(f["name"]))
if n is not None:
out[f["name"]] = n
return out
# --- protection -------------------------------------------------------------
# Targets: "device:<id here>", "control:<the agent's control id>",
# "entity:<HA entity id>". An entry: {level: none|protected|sealed,
@@ -697,6 +848,119 @@ def one_weather(frag: dict, others) -> None:
frag.pop("inputs", None)
# --- storage with losses (docs/design/storage-losses.md, sections 2.3, 3, 10) ---------------
# A hot-water tank (control kind dhw_tank): its heater, the installer's
# choice where the profile does not know it.
def tank_of(frag: dict) -> dict | None:
"""A hot-water tank's settings (its first dhw_tank control): {heater:
one of HEATERS or ""}."""
c = next((c for c in frag.get("controls", []) if c.get("kind") == "dhw_tank"), None)
if c is None:
return None
h = (c.get("params") or {}).get("heater")
return {"heater": h if h in HEATERS else ""}
def set_tank_heater(frag: dict, data: dict) -> dict:
"""The tank's heater (element, heat_pump, boiler, district) into its
dhw_tank controls' params.heater (in place)."""
tanks = [c for c in frag.get("controls", []) if c.get("kind") == "dhw_tank"]
if not tanks:
raise Fail("this device is no hot-water tank")
h = str((data or {}).get("heater") or "")
if h not in HEATERS:
raise Fail(f"the heater is one of {', '.join(HEATERS)}")
for c in tanks:
c.setdefault("params", {})["heater"] = h
return tank_of(frag)
def _pos(v):
x = _f(v)
return x if x is not None and x > 0 else None
def tank_given(c: dict, ratings: dict) -> dict:
"""What a tank's control and its device's ratings give before any plan:
volume_l, heater, heater_kw, cop (None: not given), cop_curve (the
installer's curve); the mapping's params first, then the owner's
ratings (the agent's fact order, 10.4; the device's own entities are the
agent's to read)."""
p, r = c.get("params") or {}, ratings or {}
w = _pos(p.get("max_power_w")) or _pos(p.get("max_heat_w"))
return {"volume_l": _pos(p.get("volume_l")) or _pos(r.get("tank_volume_l")),
"heater": p.get("heater") if p.get("heater") in HEATERS else None,
"heater_kw": round(w / 1000.0, 3) if w else _pos(r.get("tank_heater_kw")),
"cop": _pos(p.get("cop")) or _pos(r.get("tank_cop")), "cop_curve": bool(p.get("cop_curve"))}
def tank_missing(c: dict, given: dict) -> list:
"""The facts a tank is not planned without (the agent's refusal codes,
design 10.5), from what the installer and the owner gave."""
ents = c.get("entities") or {}
out = []
if not given.get("volume_l") and "volume" not in ents:
out.append("volume_l")
if not given.get("heater"):
out.append("heater")
elif not given.get("heater_kw"):
out.append("max_heat_w" if given["heater"] in ("boiler", "district") else "max_power_w")
if given.get("heater") == "heat_pump" and not given.get("cop") and not given.get("cop_curve"):
out.append("cop")
if not set(ents) & {"water_heater", "temp_top"}:
out.append("temp_sensor")
return out
def storage_of(frag: dict, ratings: dict, planning: dict | None) -> list:
"""A device's stores, for both Devices pages: per battery or tank
control what the agent's latest plan says (its preferences view's
"planning": storage, refused; design 10.5), else what is known here.
battery: {id, kind, planned, standby_w, standby_src,
self_discharge_pct_month, self_discharge_src,
idle_loss_kwh_24h, idle_loss_eur_24h} (the plan's; absent
values: not in a plan yet)
dhw_tank: {id, kind, planned, refused, missing: [codes], volume_l,
heater, heater_kw, cop, standby_w, loss_src, erp_class,
temp_c, stored_kwh, usable_kwh, max_temp_c}
Sources are the plan's words: mapping | device | learnt | owner |
parameter | assumed | none."""
pl = planning if isinstance(planning, dict) else {}
st = pl.get("storage") if isinstance(pl.get("storage"), dict) else {}
ref = pl.get("refused") if isinstance(pl.get("refused"), dict) else {}
out = []
for c in frag.get("controls", []):
kind, cid = c.get("kind"), c.get("id")
if kind not in ("battery", "dhw_tank") or not cid:
continue
s = st.get(cid) if isinstance(st.get(cid), dict) and st[cid].get("kind", kind) == kind else {}
r = ref.get(cid) if isinstance(ref.get(cid), dict) else None
x = {"id": cid, "kind": kind, "planned": bool(s) and not r}
if kind == "battery":
for k in ("standby_w", "standby_src", "self_discharge_pct_month", "self_discharge_src", "idle_loss_kwh_24h",
"idle_loss_eur_24h"):
if s.get(k) is not None:
x[k] = s[k]
else:
given = tank_given(c, ratings)
for k in ("volume_l", "heater", "standby_w", "loss_src", "erp_class", "temp_c", "stored_kwh", "usable_kwh",
"max_temp_c"):
if s.get(k) is not None:
x[k] = s[k]
for k in ("volume_l", "heater", "heater_kw", "cop", "cop_curve"):
if x.get(k) is None and given.get(k) is not None:
x[k] = given[k]
x["refused"] = bool(r)
if r:
miss = r.get("missing")
x["missing"] = [str(m) for m in miss] if isinstance(miss, list) else []
x["why"] = str(r.get("why") or "")
else:
x["missing"] = [] if s else tank_missing(c, given)
out.append(x)
return out
# --- what a device reads, in the pages' words (both Devices pages) -------------------------
# The Hub panel and the add-on's page show a device's values by their
# meaning, never by asset id: room.living_room.setpoint_low and _high are
@@ -707,7 +971,8 @@ RANGE, HVAC = "room.setpoint_range", "heating_cooling.state"
# A device's main values on the list, in this order (at most a few).
HEADLINE = ("room.temp", "room.setpoint", RANGE, HVAC, "heating.state", "cooling.state", "pv.power", "battery.soc",
"battery.power", "grid.power", "load.power", "ev.power", "heatpump.power", "heat.power",
"heatpump.flow_temp", "outside.temp", "room.humidity", "room.shade_position", "circuit.power")
"heatpump.flow_temp", "dhw.temp_top", "dhw.heater_power", "outside.temp", "room.humidity",
"room.shade_position", "circuit.power")
def base_quantity(q: str) -> tuple[str, str]:
+19
View File
@@ -115,6 +115,25 @@ def actions_for(c, want, col, level="plan", why="") -> list[Action]:
elif number(v) is not None:
setnum("current", float(v), "current_a")
switch("switch", True)
elif c.kind == "dhw_tank":
# a hot-water tank's heater (optimizer._tank_entry): a water heater's target °C, a relay's
# on/off, a stepless element's W, an SG-Ready state ("sg:3": its option from params.sg_options)
v = want.get("set") if isinstance(want, dict) else want
if isinstance(v, str) and v.startswith("sg:") and "sg_ready" in e:
opt = (c.p("sg_options") or {}).get(v[3:])
if opt and col.state(e["sg_ready"]) != str(opt):
act("sg_ready", "select_option", {"option": str(opt)}, str(opt))
elif v in ("on", "off"):
switch("switch", v == "on")
elif number(v) is not None and "water_heater" in e:
c.learn_range(col)
cur = number(col.attr(e["water_heater"], "temperature"))
if cur is None or abs(cur - float(v)) > 0.25:
act("water_heater", "set_temperature", {"temperature": float(v)}, float(v), "temp_c")
elif number(v) is not None and "power" in e:
setnum("power", float(v), "power_w")
elif number(v) is not None and "switch" in e:
switch("switch", float(v) > 0)
elif c.kind == "cover":
v = number(want.get("set") if isinstance(want, dict) else want)
if v is not None:
+6 -3
View File
@@ -594,14 +594,17 @@ def predict(params: dict, series: str, t: np.ndarray, w: Weather, s: Site,
# ---- held-out window and the choice ----------------------------------------------
def holdout(t: np.ndarray, y: np.ndarray, max_days: float = 7.0) -> int:
def holdout(t: np.ndarray, y: np.ndarray, max_days: float = 7.0, min_days: float | None = None) -> 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)."""
less data the last quarter of what was metered, at least min_days (the
cloud: forecast.trainer.min_holdout_days, trainlib.Selection; without
it 6 hours, as the box still cuts)."""
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))
least = 6 * 3600 if min_days is None else min_days * 86400
h = min(max(max_days * 86400, least), max(0.25 * span_s, least))
cut = t[have[-1]] + SLOT_S - h
return int(np.searchsorted(t, cut))
+2 -1
View File
@@ -259,6 +259,7 @@ class GridOrders:
volts = ev_volts({**c.params, "phases": n}, "order")
# down to 0.1 A: never above the ordered power (6.1 A x 690 V = 4209 W)
out[c.id] = {"current_a": (None, math.floor(w / volts * 10 + 1e-9) / 10)}
elif c.kind == "battery":
elif c.kind == "battery" or c.kind == "dhw_tank" and "power" in c.entities:
# a battery's charging; a tank's stepless element (its relay: the plan's limit on the meter)
out[c.id] = {"power_w": (None, w)}
return out
+1
View File
@@ -69,6 +69,7 @@ SERVICES = {
"cover": {"set_cover_position", "open_cover", "close_cover"},
"select": {"select_option"},
"input_select": {"select_option"},
"water_heater": {"set_temperature"},
}
+112
View File
@@ -365,6 +365,9 @@ MESSAGES = {
'heat pump energy': 'Energie der Wärmepumpe',
'flow temperature': 'Vorlauftemperatur',
'hot water temperature': 'Warmwassertemperatur',
'hot water heat (thermal)': 'Wärme für Warmwasser (thermisch)',
'hot water heat energy (thermal)': 'Wärmemenge für Warmwasser (thermisch)',
'hot water drawn': 'gezapftes Warmwasser',
'outdoor temperature': 'Außentemperatur',
'outdoor humidity': 'Außenluftfeuchte',
'gas': 'Gas',
@@ -452,4 +455,113 @@ MESSAGES = {
"The shade's room and window are the owner's to set.": "Raum und Fenster der Beschattung legt der Eigentümer fest.",
"Indoor or outdoor is the owner's to choose.": "Innen oder außen wählt der Eigentümer.",
"The weather forecast is the owner's to choose.": "Die Wettervorhersage wählt der Eigentümer.",
# Ratings, the battery's idle loss, the hot-water tank (docs/design/storage-losses.md)
"The ratings are the owner's to enter.": "Die Nenndaten trägt der Eigentümer ein.",
"The tank's heater is the owner's to choose.": "Die Heizung des Speichers wählt der Eigentümer.",
"Ratings": "Nenndaten",
"Saved. The next plan uses them.": "Gespeichert. Der nächste Plan verwendet sie.",
"hot-water tank": "Warmwasserspeicher",
"Hot-water tank": "Warmwasserspeicher",
"battery idle use": "Eigenverbrauch des Speichers",
"tank temperature (top)": "Speichertemperatur (oben)",
"tank temperature (bottom)": "Speichertemperatur (unten)",
"tank heater power": "Heizleistung des Speichers",
"heat stored in the tank": "im Speicher gespeicherte Wärme",
"tank {v}": "Speicher {v}",
"heater {v}": "Heizung {v}",
"Battery capacity, kWh": "Speicherkapazität, kWh",
"Battery power, kW": "Speicherleistung, kW",
"Battery round-trip efficiency, % (datasheet)": "Wirkungsgrad des Speichers (Lade-Entlade-Zyklus), % (Datenblatt)",
"Battery idle loss, W (optional; datasheet or measured; leave empty and the box learns it)":
"Ruheverlust des Speichers, W (optional; Datenblatt oder gemessen; leer lassen, dann lernt die Box ihn)",
"Battery self-discharge, %/month (optional; datasheet)": "Selbstentladung des Speichers, %/Monat (optional; Datenblatt)",
"Hot-water tank, litres (the type plate; needed: the tank is not planned without it)":
"Warmwasserspeicher, Liter (Typenschild; nötig: ohne dies wird der Speicher nicht geplant)",
"Tank heater, kW (electric for an element or heat pump, heat for a boiler or district heat; needed)":
"Speicherheizung, kW (elektrisch bei Heizstab oder Wärmepumpe, Wärme bei Kessel oder Fernwärme; nötig)",
"Tank heat pump COP (datasheet, EN 16147; a heat pump only)":
"COP der Speicher-Wärmepumpe (Datenblatt, EN 16147; nur bei einer Wärmepumpe)",
"Tank standing loss (ErP S), W (the label or datasheet; kWh per 24 h ÷ 0.024)":
"Warmhalteverlust des Speichers (ErP S), W (Label oder Datenblatt; kWh je 24 h ÷ 0,024)",
"Tank ErP class (1 A+, 2 A, 3 B, 4 C, 5 D, 6 E, 7 F; where the standing loss is not known)":
"ErP-Klasse des Speichers (1 A+, 2 A, 3 B, 4 C, 5 D, 6 E, 7 F; wo der Warmhalteverlust nicht bekannt ist)",
"Tank maximum, °C (optional)": "Höchsttemperatur des Speichers, °C (optional)",
"Room temperature at the tank, °C (optional)": "Raumtemperatur am Speicher, °C (optional)",
"Large system, DVGW W 551 (1: yes; optional, else from the volume)":
"Großanlage nach DVGW W 551 (1: ja; optional, sonst aus dem Volumen)",
"From the tank's type plate, label or datasheet. Cantabile plans the tank only when it knows its volume, its "
"heater's power and, for a heat pump, its COP; it never guesses them. Without the standing loss or the ErP class "
"it takes class D's limit (the Parameters page) until it has learnt the tank's own. An empty field: not known.":
"Vom Typenschild, Label oder Datenblatt des Speichers. Cantabile plant den Speicher nur, wenn es sein Volumen, "
"die Leistung seiner Heizung und bei einer Wärmepumpe ihren COP kennt; es rät sie nie. Ohne Warmhalteverlust "
"oder ErP-Klasse nimmt es den Grenzwert der Klasse D (Seite Parameter), bis es den eigenen des Speichers "
"gelernt hat. Ein leeres Feld: nicht bekannt.",
"From the device's datasheet or nameplate. Cantabile plans a battery only when it knows its capacity, power and "
"efficiency; it never guesses them. An empty field: not known.":
"Aus dem Datenblatt oder vom Typenschild des Geräts. Cantabile plant einen Speicher nur, wenn es seine "
"Kapazität, Leistung und seinen Wirkungsgrad kennt; es rät sie nie. Ein leeres Feld: nicht bekannt.",
"the installer's setting": "Einstellung des Installateurs",
"reported by the device": "vom Gerät gemeldet",
"learnt by the box": "von der Box gelernt",
"your rating": "Ihre Nenndaten",
"reported by the tank": "vom Speicher gemeldet",
"from the label (your rating)": "vom Label (Ihre Nenndaten)",
"Immersion heater (element)": "Heizstab",
"Heat pump": "Wärmepumpe",
"Boiler (gas or oil)": "Kessel (Gas oder Öl)",
"District heat": "Fernwärme",
"the tank's volume (Ratings)": "das Volumen des Speichers (Nenndaten)",
"its heater (above)": "seine Heizung (oben)",
"the heater's power (Ratings)": "die Leistung der Heizung (Nenndaten)",
"the heat pump's COP (Ratings)": "der COP der Wärmepumpe (Nenndaten)",
"a tank temperature (the water heater's own, or a sensor)":
"eine Speichertemperatur (die des Warmwasserbereiters oder ein Fühler)",
"the boiler's efficiency": "der Wirkungsgrad des Kessels",
"a gas price": "ein Gaspreis",
"a heat price": "ein Wärmepreis",
"the Parameters row {key}": "die Zeile {key} der Seite Parameter",
"Idle loss {w} W ({source})": "Ruheverlust {w} W ({source})",
"Idle loss {w} W assumed (Parameters): enter the datasheet's value below.":
"Ruheverlust {w} W angenommen (Parameter): Tragen Sie unten den Wert aus dem Datenblatt ein.",
"Idle loss not modelled yet: enter the datasheet's value below, or the box learns it.":
"Ruheverlust noch nicht berücksichtigt: Tragen Sie unten den Wert aus dem Datenblatt ein, oder die Box lernt ihn.",
"about {kwh} kWh a day": "etwa {kwh} kWh am Tag",
"Self-discharge {pct} %/month ({source})": "Selbstentladung {pct} %/Monat ({source})",
"Self-discharge {pct} %/month assumed (Parameters)": "Selbstentladung {pct} %/Monat angenommen (Parameter)",
"Standing loss {w} W assumed: class {cls}'s limit (Parameters). Enter the label's value below.":
"Warmhalteverlust {w} W angenommen: Grenzwert der Klasse {cls} (Parameter). Tragen Sie unten den Wert vom Label ein.",
"Standing loss {w} W assumed (Parameters). Enter the label's value below.":
"Warmhalteverlust {w} W angenommen (Parameter). Tragen Sie unten den Wert vom Label ein.",
"Standing loss {w} W ({source})": "Warmhalteverlust {w} W ({source})",
"Standing loss {w} W": "Warmhalteverlust {w} W",
"class {cls}": "Klasse {cls}",
"Needed: the tank is not planned without it.": "Nötig: Ohne dies wird der Speicher nicht geplant.",
"Meanwhile it keeps its own thermostat.": "Bis dahin regelt er mit seinem eigenen Thermostat.",
"Not planned: {why}.": "Nicht geplant: {why}.",
"{l} L": "{l} L",
"heater {kw} kW": "Heizung {kw} kW",
"COP {cop}": "COP {cop}",
"now {c} °C": "jetzt {c} °C",
"{kwh} kWh usable": "{kwh} kWh nutzbar",
"Cantabile heats the tank when heat is cheap (solar surplus, a low price) and keeps it above your minimum; the "
"tank's own thermostat stays the last limit. Its heater says what the heat costs: electricity for an element or a "
"heat pump, gas or district heat for the others.":
"Cantabile heizt den Speicher, wenn Wärme günstig ist (Solarüberschuss, ein niedriger Preis), und hält ihn über "
"Ihrem Minimum; der eigene Thermostat des Speichers bleibt die letzte Grenze. Seine Heizung bestimmt, was die "
"Wärme kostet: Strom bei Heizstab oder Wärmepumpe, Gas oder Fernwärme bei den anderen.",
"Choose its heater": "Heizung wählen",
"Its heater": "Seine Heizung",
"Hot-water meter: litres per unit it counts (1 for L, 1000 for m³; only where Home Assistant shows no unit or a wrong one)":
"Warmwasserzähler: Liter je gezählter Einheit (1 für L, 1000 für m³; nur wo Home Assistant keine oder eine "
"falsche Einheit zeigt)",
"Hot water: kWh of heat per m³ drawn (optional; else from the two temperatures)":
"Warmwasser: kWh Wärme je gezapftem m³ (optional; sonst aus den beiden Temperaturen)",
"Cold water temperature, °C (optional)": "Kaltwassertemperatur, °C (optional)",
"Hot water temperature at the tap, °C (optional)": "Warmwassertemperatur an der Zapfstelle, °C (optional)",
"From the meter and the installation. The heat of the hot water drawn is the volume times the kWh per m³ given here, "
"else 1.163 kWh per m³ and kelvin times the hot less the cold water's temperature; with neither, Cantabile's "
"suggested temperature rise (the Parameters page), and it says so. An empty field: not known.":
"Vom Zähler und der Anlage. Die Wärme des gezapften Warmwassers ist das Volumen mal die hier angegebenen kWh je "
"m³, sonst 1,163 kWh je m³ und Kelvin mal die Warm- weniger die Kaltwassertemperatur; ohne beides die von "
"Cantabile vorgeschlagene Temperaturerhöhung (Seite Parameter), und es sagt das. Ein leeres Feld: nicht bekannt.",
}
+492 -38
View File
@@ -9,10 +9,14 @@ control.
None of this leaves the site; only the plan does (controller.py).
Placeholders (quality is not a goal yet):
- occupancy beyond the next hour: the presence now for one hour, then
06:00-22:00 local as "occupied" (a learned schedule comes later);
- sun: the PV forecast scaled to its peak, else the sun's elevation.
Occupancy (methods.md A1, B16): the presence now for the first hour,
then the learnt weekly presence (the occupancy forecast, a step occupied
from the Parameters page's comfort.occupied_min_share), else 06:00-22:00
local, noted (occupancy). A car's departure and energy where the car says
none: the EV session forecast (ev_session, B15).
Placeholder (quality is not a goal yet): the sun:
the PV forecast scaled to its peak, else the sun's elevation.
"""
import json
import logging
@@ -27,6 +31,9 @@ log = logging.getLogger(__name__)
STEP_S = 900
STEPS = 192 # 48 h
HISTORY_S = 8 * 86400 # a day back (the fallback) and a week back (the box's models' lag)
# a room's occupied hours (local, from..to) without the owner's schedule: its
# comfort target then, its setback/setup otherwise (preferences.builtin says so)
OCCUPIED_HOURS = (6, 22)
def number(v) -> float | None:
@@ -168,24 +175,34 @@ FC_SOURCES = {"own": "the box's own model", "cloud": "the cloud's series", "box"
"hour_of_week": "the hour-of-week profile"}
def _model_series(m, start, bundles, history, tz, box) -> tuple[list[float], dict] | None:
def _box_weather(box) -> tuple:
"""The box's weather for its models (model_state's box): HA's hourly
forecast, its weather entity, and, where the entity has one, its
wind_speed_unit (localml.ha_hours)."""
return tuple(box[:2]) + ((box[2],) if len(box) > 2 and box[2] else ())
def _model_series(m, start, bundles, history, tz, box, labels: list | None = None) -> tuple[list[float], dict] | None:
"""A model series m for the horizon, per step the best fresh source
(methods.md B10): the box's own model where it is in force and has a
value (boxtrain.py: bundles.own), else the cloud's forecast where its
series covers the step, else the cloud's model on the box (localml.py;
box: HA's weather forecast and its entity) where it has a value, else
the hour-of-week profile; how many steps each gave, the source that
gave most ("source"), and every source's values ("_cands": the live
error per source, taken out before the plan)."""
box: HA's weather forecast, its entity and its wind unit) where it has
a value, else the hour-of-week profile; how many steps each gave, the
source that gave most ("source"), and every source's values ("_cands":
the live error per source, taken out before the plan). labels (a list):
filled with each step's source (own | cloud | box | hour_of_week)."""
trainer = getattr(bundles, "own", None) if bundles is not None else None
mine = None
if trainer is not None and box is not None:
try:
mine = trainer.forecast(m, start, STEPS, box[0], box[1])
mine = trainer.forecast(m, start, STEPS, *_box_weather(box))
except Exception as e: # never stops a plan
log.warning("the box's own %s model: %s", m, e)
if not hasattr(bundles, "forecast_parts"):
s = bundles.forecast(m, start, STEP_S, STEPS, tz)
if s is not None and labels is not None:
labels[:] = ["cloud"] * len(s)
return None if s is None else (s, {})
parts = bundles.forecast_parts(m, start, STEP_S, STEPS, tz)
if parts is None:
@@ -193,6 +210,8 @@ def _model_series(m, start, bundles, history, tz, box) -> tuple[list[float], dic
if mine is None or any(v is None for v in mine[0]):
return None
vals = [float(v) for v in mine[0]]
if labels is not None:
labels[:] = ["own"] * STEPS
return vals, {"series": m, "own": STEPS, "cloud": 0, "box": 0, "hour_of_week": 0, "own_model": mine[1].get("kind"),
"source": "own", "_cands": {"own": vals}}
vals = [v for v, _ in parts]
@@ -200,20 +219,24 @@ def _model_series(m, start, bundles, history, tz, box) -> tuple[list[float], dic
cloud_series = [v if src == "series" else None for v, src in parts]
own = None
if box is not None and (trainer is not None or not all(v is not None for v in cloud_series)):
own = bundles.box_forecast(m, start, STEPS, history, box[0], box[1])
own = bundles.box_forecast(m, start, STEPS, history, *_box_weather(box))
lab = []
for k, (v, src) in enumerate(parts):
o = mine[0][k] if mine is not None else None
b = own[0][k] if own is not None else None
if o is not None:
vals[k] = o
info["own"] += 1
lab.append("own")
elif src == "series":
info["cloud"] += 1
lab.append("cloud")
elif b is not None:
vals[k] = b
info["box"] += 1
lab.append("box")
else:
info["hour_of_week"] += 1
lab.append("hour_of_week")
info[lab[-1]] += 1
if labels is not None:
labels[:] = lab
if mine is not None:
info["own_model"] = mine[1].get("kind")
if mine[1].get("weather"):
@@ -267,6 +290,163 @@ def _series(name, start, bundles, history, tz, now_value, default, model_names=N
return out, ("history" if have else ("now" if now_value is not None else "default"))
OCC_SHARE_KEY = "comfort.occupied_min_share" # the Parameters page's (via the tariff bundle)
PRESENT = ("on", "home") # a presence sensor on, a person or device_tracker home
NO_VALUE = (None, "", "unavailable", "unknown")
def presence_asset(asset: str) -> bool:
"""A mapped presence source (B16.1, building/carriers.presence_source):
a room's presence sensor (room.<r>.occupied) or a person's home/away
(person.<slug>.home)."""
p = str(asset).split(".")
return len(p) == 3 and ((p[0] == "room" and p[2] == "occupied") or (p[0] == "person" and p[2] == "home"))
def presence_now(col: Collector, entities) -> bool | None:
"""Someone at home now: any presence source on or home (HA's person
and device_tracker: state "home"); None while none has a value."""
vals = [col.state(p) for p in entities or []]
known = [v for v in vals if v not in NO_VALUE]
return any(v in PRESENT for v in known) if known else None
def occupancy(start: int, tz: str, col: Collector, presence, bundles, history, box, box_params: dict,
hours=OCCUPIED_HOURS, fc_src: dict | None = None) -> tuple[list[int], dict, list[str]]:
"""Per step occupied (1) or not (methods.md A1, B16): the presence now
for the first hour (4 steps) where a presence source has a value; then
the learnt weekly presence, the occupancy forecast through the load's
sources (_model_series: the box's own model in force, the cloud's
series, the cloud's model on the box, the hour-of-week profile), a step
occupied where the forecast share of the presence sources seeing
someone is at least the Parameters page's comfort.occupied_min_share;
without a forecast (no presence source, or none learnt yet), without
the parameter or with a forecast never occupied over the horizon, the
fixed hours (06:00-22:00 local), and a quiet note
why (no alarm: nothing for anyone to enter, except the parameter).
The owner's schedule still wins (preferences.apply). (occupied,
sources.occupancy: steps per source and why, notes)."""
zone = ZoneInfo(tz or "UTC")
present = presence_now(col, presence)
labels: list = []
got = _model_series("occupancy", start, bundles, history, tz, box, labels) if bundles else None
raw = (box_params or {}).get(OCC_SHARE_KEY)
share = number(raw) if not isinstance(raw, bool) else None
share = share if share is not None and 0.0 <= share <= 1.0 else None
notes, src = [], {"presence_now": 0, "fixed_hours": 0}
learnt = None
if got is not None:
vals, info = got
if fc_src is not None:
fc_src["occupancy"] = info # the forecast's steps per source, its live error (_cands)
if share is None:
src["why"] = "no_parameter"
notes.append(f"occupancy: the learnt presence is not used, parameter {OCC_SHARE_KEY} "
+ ("not received" if raw is None else f"not a share 0..1 ({raw!r})")
+ " (the admin Parameters page; it reaches the box with its tariff): "
+ f"{hours[0]:02d}:00-{hours[1]:02d}:00 instead")
else:
learnt = [1 if float(v) >= share else 0 for v in vals]
src["min_share"] = share
if not any(learnt):
# never occupied over the whole horizon (a learnt profile of 0 all day): every room
# at setback for 48 h is not a plan anyone wants; the fixed hours, said quietly
learnt = None
src["why"] = "never_occupied"
notes.append(f"occupancy: the learnt presence is never occupied over the next 48 h (share "
f"{share} not reached): {hours[0]:02d}:00-{hours[1]:02d}:00 instead")
elif not presence:
src["why"] = "no_presence_source"
notes.append(f"occupancy: no presence source and no presence forecast: {hours[0]:02d}:00-{hours[1]:02d}:00 "
"(map a presence sensor or the people's home/away to learn it)")
else:
src["why"] = "no_forecast"
notes.append(f"occupancy: no presence forecast yet (learnt from the presence history): the presence now for the "
f"first hour, then {hours[0]:02d}:00-{hours[1]:02d}:00")
out = []
for k in range(STEPS):
if k < 4 and present is not None:
out.append(1 if present else 0)
src["presence_now"] += 1
elif learnt is not None:
out.append(learnt[k])
lab = labels[k] if k < len(labels) else "cloud"
src[lab] = src.get(lab, 0) + 1
else:
h = datetime.fromtimestamp(start + k * STEP_S, timezone.utc).astimezone(zone).hour
out.append(1 if hours[0] <= h < hours[1] else 0)
src["fixed_hours"] += 1
src["source"] = ("learnt" if learnt is not None else "fixed_hours")
src["presence_sources"] = len(presence or [])
return out, src, notes
def _when_utc(ts) -> str:
return datetime.fromtimestamp(int(ts), timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
def ev_session(c, st: dict, sessions: dict | None, start: int, now: float) -> tuple[dict, str]:
"""A car's departure and energy where neither the car nor (in the
optimiser) its owner gives them (methods.md A1, B15): the EV session
forecast (bundles.ev_sessions). Plugged in: the forecast session that
covers now gives the departure (st["session"]["dep_step"]; beyond the
horizon: its end) and the kWh (need_wh) where the car reports none.
Not plugged in: the next forecast session in the horizon becomes an
expected load (st["expected"]: from_step its arrival, to_step its
departure, need_wh its kWh), which the plan sees (prices, the battery)
but never acts on: no charger command until the car is plugged in. A
forecast need is not a known one (optimizer.ev_known). Without
sessions: as before (the car's, else the mapping's need_wh and
departure). (sources.ev for the control, a note or "")."""
own_dep, own_need = st.get("departure") is not None, st.get("need_wh") is not None
src = {"departure": "car" if own_dep else "mapping", "energy": "car" if own_need else "mapping"}
if not sessions or not sessions.get("sessions"):
return src, ""
issued = _when_utc(sessions["issued"])
src["issued"] = int(sessions["issued"])
end = start + STEPS * STEP_S
def step_of(ts, up):
k = (ts - start) / STEP_S
k = math.ceil(k - 1e-9) if up else math.floor(k + 1e-9)
return int(min(STEPS, max(0, k)))
name = c.label() if hasattr(c, "label") else c.id
if st.get("connected"):
cover = next((s for s in sessions["sessions"] if s["arrive"] <= now and (s["depart"] is None or now < s["depart"])),
None)
if cover is None or (own_dep and own_need):
return src, ""
sess, used = {}, []
if not own_dep:
sess["dep_step"] = step_of(cover["depart"], False) if cover["depart"] is not None else STEPS
src["departure"] = "session forecast"
used.append("departure")
if not own_need and cover["kwh"] is not None:
sess["need_wh"] = float(cover["kwh"]) * 1000.0
src["energy"] = "session forecast"
used.append("energy")
if not used:
return src, ""
st["session"] = sess
return src, f"car {name}: {' and '.join(used)} from the session forecast (issued {issued})"
nxt = next((s for s in sessions["sessions"] if now < s["arrive"] < end), None)
if nxt is None:
return src, ""
if nxt["kwh"] is None:
return src, (f"car {name}: not plugged in; the session forecast (issued {issued}) expects it at "
f"{_when_utc(nxt['arrive'])} but has no kWh: not planned")
a = step_of(nxt["arrive"], True)
b = step_of(nxt["depart"], False) if nxt["depart"] is not None else STEPS
if b <= a:
return src, ""
st["expected"] = {"from_step": a, "to_step": b, "need_wh": float(nxt["kwh"]) * 1000.0}
src.update(expected={"arrive": int(nxt["arrive"]), "depart": nxt["depart"], "kwh": float(nxt["kwh"])},
departure="session forecast", energy="session forecast")
return src, (f"car {name}: not plugged in; an expected session from the session forecast (issued {issued}): "
f"{_when_utc(nxt['arrive'])} to {_when_utc(nxt['depart']) if nxt['depart'] else 'beyond the plan'}, "
f"{float(nxt['kwh']):.1f} kWh, planned as a load; no charger command until it is plugged in")
def _hhmm(v: str, device_class) -> str | None:
"""A departure as HH:MM: from "07:00(:00)" or a timestamp (local time
of the timestamp as given)."""
@@ -322,9 +502,42 @@ def device_state(c, col: Collector, now: float) -> dict:
elif c.kind == "cover":
st["position_pct"] = cover_position(col, e["cover"])
st["set_position"] = cover_positions(col, e["cover"])
elif c.kind == "dhw_tank":
# its temperatures (a water heater's current one stands in for the top sensor), the heater's power,
# the room's temperature, what is set now; its own ratings (tank_reported)
wh = e.get("water_heater")
top = col.value(e.get("temp_top", "")) if e.get("temp_top") else None
if top is None and wh:
top = number(col.attr(wh, "current_temperature"))
st["temp_top"] = top
st["temp_bottom"] = col.value(e["temp_bottom"]) if e.get("temp_bottom") else None
st["heater_w"] = watts(col, e["heater_power"]) if e.get("heater_power") else None
st["room_c"] = col.value(e["room_temp"]) if e.get("room_temp") else None
if wh:
st["target_c"] = number(col.attr(wh, "temperature"))
st["mode"] = col.state(wh)
if e.get("switch"):
st["on"] = col.state(e["switch"]) == "on"
if e.get("sg_ready"):
st["sg"] = col.state(e["sg_ready"])
if hasattr(c, "reported"):
c.reported = tank_reported(c, col)
return st
def tank_reported(c, col: Collector) -> dict:
"""A tank's own ratings where its device reports them: volume_l (its
volume entity, L or m³), standby_loss_w (its standing loss, W or
kWh/24 h)."""
e, out = c.entities, {}
vol = _scaled(col, e.get("volume", ""), {"L": 1.0, "l": 1.0, "m³": 1000.0})
loss = _scaled(col, e.get("standby_loss", ""), {"W": 1.0, "kWh": 1000.0 / 24.0})
for k, v in (("volume_l", vol), ("standby_loss_w", loss)):
if v is not None and v > 0:
out[k] = v
return out
def _scaled(col: Collector, eid: str, units: dict) -> float | None:
"""An entity's value converted by its unit (units: unit -> factor; a
unit not in it: None, never a guess at the scale)."""
@@ -346,6 +559,10 @@ def battery_reported(c, col: Collector) -> dict:
for k, v in (("capacity_wh", cap), ("rated_power_w", pw), ("efficiency_pct", eff)):
if v is not None and v > 0:
out[k] = v
# its own idle use (0 is a value here: a battery that says it has none)
sb = _scaled(col, e.get("standby", ""), {"kW": 1000.0, "W": 1.0})
if sb is not None and sb >= 0:
out["standby_w"] = sb
return out
@@ -379,7 +596,7 @@ HYBRID_SWITCH_KEY = "heat.hybrid_switch_eur" # the Parameters page's (via t
def heating_refusal(c, params: dict, price_gas: list, price_heat: list, prices_status: str,
box_params: dict | None = None) -> dict | None:
box_params: dict | None = None, price_oil: list | None = None) -> dict | None:
"""Why a heating control is not planned (docs/methods.md E6, the
owner's rule: refuse, never guess), or None: a boiler's efficiency or
a boiler's / heat station's most heat unknown, no gas price (boiler,
@@ -407,7 +624,18 @@ def heating_refusal(c, params: dict, price_gas: list, price_heat: list, prices_s
dev = getattr(c, "rated_device", "") or ""
where.append(f"on the panel: Devices, {dev or 'the heating device'}, Ratings ({labels}); or in the mapping's params "
f"({', '.join(rated)})" + ("; or map the boiler's efficiency sensor" if "boiler_efficiency" in rated else ""))
if src in ("boiler", "hybrid") and (not price_gas or price_gas[0] is None):
fuel = str(params.get("fuel") or "gas")
if src in ("boiler", "hybrid") and fuel not in ("gas", "oil"):
# a boiler burns gas or heating oil (methods E15): another fuel is not priced, never taken for one
why.append(f"boiler fuel {fuel!r} not known (gas or oil)")
where.append("the mapping's params: fuel (gas or oil)")
missing = missing + ["fuel"]
elif src in ("boiler", "hybrid") and fuel == "oil" and (not price_oil or price_oil[0] is None):
why.append("no heating oil price for now")
where.append("the site's heating oil price (console: the site's tariff, Heating oil: the last delivery's "
"price per litre, or the weekly reference)")
missing = missing + ["oil_price"]
elif src in ("boiler", "hybrid") and fuel == "gas" and (not price_gas or price_gas[0] is None):
why.append("no gas price for now")
where.append("the site's gas tariff (console: the site's tariff, Gas)")
missing = missing + ["gas_price"]
@@ -424,6 +652,188 @@ def heating_refusal(c, params: dict, price_gas: list, price_heat: list, prices_s
return {"why": "; ".join(why), "where": "; ".join(where), "missing": missing}
TANK_WORDS = {"heater": ("the tank's heater (element, heat pump, boiler or district heat) unknown",
"the mapping's params: heater (the device profile asks for it on the panel)"),
"volume_l": ("the tank's volume unknown", "volume_l"),
"max_power_w": ("the tank heater's power unknown", "heater_kw"),
"max_heat_w": ("the tank heater's most heat unknown", "heater_kw"),
"cop": ("the tank heat pump's COP unknown", "cop"),
"boiler_efficiency": ("the tank boiler's efficiency unknown", None)}
def tank_refusal(c, st: dict, missing: list[str], price_gas: list, price_heat: list) -> dict | None:
"""Why a hot-water tank is not planned (docs/methods.md A13; design
note 3.6, 10.5), or None: only what a person can enter or connect (the
alarm box): its volume, heater kind and power, a heat pump's COP, a
boiler's efficiency, a temperature sensor, the gas or heat price, a
Parameters row. {"why", "where", "missing"}."""
from .controls import TANK_RATINGS
why, where, miss = [], [], []
rated = []
for m in missing:
if m in TANK_WORDS:
why.append(TANK_WORDS[m][0])
if m == "heater":
where.append(TANK_WORDS[m][1])
elif m == "boiler_efficiency":
where.append("on the panel: Devices, the tank, Ratings (Boiler efficiency, %); or the mapping's "
"params (boiler_efficiency)")
else:
rated.append(TANK_WORDS[m][1])
else:
why.append(f"parameter {m} not received")
where.append("the admin Parameters page (Hot water); it reaches the box with its tariff")
miss.append(m)
if rated:
dev = getattr(c, "rated_device", "") or "the tank's device"
labels = ", ".join(TANK_RATINGS[r][1] for r in dict.fromkeys(rated))
params = ", ".join(TANK_RATINGS[r][2] for r in dict.fromkeys(rated))
where.append(f"on the panel: Devices, {dev}, Ratings ({labels}); or in the mapping's params ({params})")
if st.get("temp_top") is None and st.get("temp_bottom") is None:
has = c.entities.get("temp_top") or c.entities.get("temp_bottom") or c.entities.get("water_heater")
why.append("tank temperature unknown" + (" (its sensor has no value)" if has else " (no tank temperature sensor)"))
where.append("map the tank's temperature sensor (temp_top, temp_bottom) or its water_heater")
miss.append("temp_sensor")
heater = str((c.params or {}).get("heater") or "")
if heater == "boiler" and (not price_gas or price_gas[0] is None):
why.append("no gas price for now")
where.append("the site's gas tariff (console: the site's tariff, Gas)")
miss.append("gas_price")
if heater == "district" and (not price_heat or price_heat[0] is None):
why.append("no heat price for now")
where.append("the site's heat tariff, or its building's heat price (console: Buildings, rules)")
miss.append("heat_price")
if not why:
return None
return {"why": "; ".join(why), "where": "; ".join(where), "missing": miss}
def tank_due(learnt: dict, facts: dict, start: int) -> dict:
"""A tank's legionella run where the mapping plans it (docs/methods.md
A13): its last time at the legionella temperature (the box's, storefit),
due an interval later; due_step: the step it falls due (0: now or
overdue; None: beyond the horizon, or no run planned)."""
out = {"last": learnt.get("legionella")}
iv = facts.get("legionella_interval_h")
if iv is None:
return out
last = learnt.get("legionella")
due = (last + iv * 3600.0) if last else float(start) # never seen at the temperature: due now
out["due"] = int(due)
k = int((due - start) // STEP_S)
out["due_step"] = max(0, k) if k < STEPS else None
return out
DRAW_DAYS_KEY = "dhw.draw_history_min_days"
def _tank_state(c, st: dict, params: dict, start: int, now: float, tz: str, bundles, history, box,
box_params: dict, storefit, price_gas: list, price_heat: list, only_tank: bool) -> dict:
"""A hot-water tank for the plan (docs/methods.md A13): its facts
(Control.tank_facts: the mapping's, the device's, the box's fit, the
owner's, the Parameters page's), its mean temperature now (S.4), its
legionella run's due time and the hot water it will give per step: the
site's dhw forecast (the cloud's or the box's model; the site's only
tank), else the box's own profile of the draws it measured (S.7, after
dhw.draw_history_min_days). {"refused": ...} for what a person can enter
(the alarm box); {"note": ...} while the draw history builds up (not a
refusal: its own thermostat meanwhile); else {"draw_w", "src"} with
params and state filled in."""
from . import storefit as storefit_mod
lt = storefit.tank_learnt(c.id) if storefit is not None else {}
facts, missing, fsrc = c.tank_facts(box_params, lt)
c.resolved = facts
no = tank_refusal(c, st, missing, price_gas, price_heat)
if no is not None:
return {"refused": no}
draw, dsrc = None, "none"
if only_tank and bundles:
got = _model_series("dhw_w", start, bundles, history, tz, box)
if got is not None:
draw, dsrc = [max(0.0, float(v)) for v in got[0]], "forecast (" + str(got[1].get("source", "model")) + ")"
if draw is None and storefit is not None:
draw = storefit.draw_profile(c.id, start, STEPS, tz, storefit_mod._num((box_params or {}).get(DRAW_DAYS_KEY)))
dsrc = "the box's measured draws (S.7)" if draw is not None else dsrc
if draw is None:
days = lt.get("draw_days") or 0.0
return {"note": f"{c.id}: hot-water tank not planned yet: no hot-water forecast and {days:.1f} days of its own "
f"draws measured (it needs {box_params.get(DRAW_DAYS_KEY, '?')}); its own thermostat meanwhile"}
params.update(facts)
st["temp_c"] = storefit_mod.mean_temp(st.get("temp_top"), st.get("temp_bottom"), float(facts["top_share"]))
st["legionella"] = tank_due(lt, facts, start) if str(c.p("legionella")) == "plan" else {"last": lt.get("legionella")}
params["legionella"] = str(c.p("legionella"))
params["shares_with"] = str(c.p("shares_with") or "")
params["cop_curve"] = facts.get("cop_curve") or []
for k in ("boiler_type", "part_load_curve"):
if (c.params or {}).get(k):
params[k] = c.params[k]
src = dict(fsrc, draw=dsrc)
if lt.get("ua") and not lt["ua"].get("kept"):
src["ua_fit"] = (f"learnt UA {lt['ua']['ua_w_k']:g} W/K is {lt['ua']['ua_w_k'] / max(lt['ua'].get('label_ua_w_k') or 1e-9, 1e-9):.1f}x "
"the label's: kept off (check the circulation pump and the insulation)")
return {"draw_w": draw, "src": src}
def heat_site(controls, devices: list, inputs, price_gas: list, price_heat: list, price_oil: list | None = None) -> dict:
"""What makes the site's heat no room model plans (docs/methods.md
A2.16, the heat outlook; backlog 45.3): the space heat where every
heating control is refused or there is none, and the hot water (an
unshiftable demand today; a tank between it and its heater is backlog
329). Its source: a heating control's boiler or district heat (its
facts: the efficiency and most heat, the part load), else the mapping's
inputs.heat, else district heat where the site is priced for heat and
not for gas. {"from", "source", facts..., "space": the space heat too
(no room planned)}; {} where nothing is known or the heat is
electricity (in the metered load already); {"note": why} where no
outlook can be made."""
heating = [c for c in controls if c.kind == "heating"]
planned = {d["id"] for d in devices if d["kind"] == "heating"}
fuel = [c for c in heating if str(c.p("heat_source") or "electric") in ("boiler", "district")]
if fuel:
c = fuel[0]
facts, _, _ = c.heat_facts()
return {"from": c.id, "source": str(c.p("heat_source")), **facts, "space": not planned,
**{k: c.p(k) for k in ("boiler_type", "part_load_curve", "fuel") if c.p(k)}}
if heating:
hybrid = [c for c in heating if c.p("heat_source") == "hybrid" and c.id not in planned]
if hybrid and not planned:
return {"note": f"heat outlook: {hybrid[0].id} is a hybrid: its plan chooses its source, none while it "
"is not planned"}
return {}
h = dict(getattr(inputs, "heat", None) or {})
if h.get("source"):
return {"from": "inputs.heat", **h, "space": True}
if any(v is not None for v in price_heat or []) and not any(v is not None for v in (price_gas or []) + (price_oil or [])):
return {"from": "the site's heat price", "source": "district", "space": True}
return {}
def carrier_inputs(start: int, now: float, site: dict, bundles, history, tz: str, box) -> dict:
"""The model state's carriers (docs/methods.md A2): the heat demands the
heat outlook costs where it has a source (heat_w, the space heat, only
where no room is planned; dhw_w, the hot water drawn: W of heat; None:
no forecast, the plan says so quietly), each through the model chain
(_model_series), the tariff bundle's CO2 factors (co2), and where each
came from (sources)."""
out, src = {"heat_site": site}, {}
wanted = [m for m, need in (("heat_w", bool(site.get("source")) and bool(site.get("space"))),
("dhw_w", bool(site.get("source")))) if need]
for m in wanted:
got = _model_series(m, start, bundles, history, tz, box) if bundles else None
if got is None:
out[m], src[m] = None, "none"
continue
out[m] = [max(0.0, float(v)) for v in got[0]]
info = {k: v for k, v in got[1].items() if k != "_cands"}
src[m] = info.get("source", "model")
co2 = bundles.co2(start, STEP_S, STEPS, now) if hasattr(bundles, "co2") else {}
if co2:
out["co2"] = co2
out["sources"] = src
return out
SET_POSITION = 4 # HA's CoverEntityFeature.SET_POSITION
@@ -445,15 +855,18 @@ def cover_position(col: Collector, ent: str) -> float | None:
def model_state(now: float, controls, inputs, col: Collector, bundles, history, tz: str,
weather_forecast: list[dict] | None, extra_limits: dict | None = None,
occupied_hours=(6, 22), building: dict | None = None, location: dict | None = None,
occupied_hours=OCCUPIED_HOURS, building: dict | None = None, location: dict | None = None,
shade_ctx: dict | None = None, grid_order: dict | None = None,
grid_max_w: float | None = None, ev_phases: dict | None = None) -> dict:
grid_max_w: float | None = None, ev_phases: dict | None = None, presence: list | None = None,
storefit=None) -> dict:
"""The 48 h, 15-minute input for the optimiser (JSON: it runs in a
subprocess). location: the site's latitude and longitude (HA's
configuration); shade_ctx: per cover control its room (temp_c,
setpoint_c, season: shades.py); grid_max_w: the site's connection (W,
config; the optimiser's default without it); ev_phases: per EV control
its phase count and source (evphases.EvPhases.all), else the mapping's."""
its phase count and source (evphases.EvPhases.all), else the mapping's;
presence: the presence sources' entities (the inputs' presence and the
mapped room.<r>.occupied and person.<slug>.home; None: the inputs')."""
start = int(now // STEP_S * STEP_S)
zone = ZoneInfo(tz or "UTC")
prices = bundles.prices(start, STEP_S, STEPS, now)
@@ -461,6 +874,8 @@ def model_state(now: float, controls, inputs, col: Collector, bundles, history,
cp = getattr(bundles, "carrier_prices", None)
price_gas = cp("gas", start, STEP_S, STEPS, now) if cp else [None] * STEPS
price_heat = cp("heat", start, STEP_S, STEPS, now) if cp else [None] * STEPS
# heating oil per kWh (Hi), an oil boiler's (methods E15)
price_oil = cp("oil", start, STEP_S, STEPS, now) if cp else [None] * STEPS
bp = getattr(bundles, "box_params", None)
box_params = bp(now) if bp else {}
# the base load: the house without the planned devices (Finding A2-a), so
@@ -471,14 +886,20 @@ def model_state(now: float, controls, inputs, col: Collector, bundles, history,
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 "")
wx = getattr(inputs, "weather", "") or ""
box = (weather_forecast or [], wx, col.attr(wx, "wind_speed_unit") if wx else None)
fc_src: dict = {"load": {}, "pv": {}}
notes: list[str] = [] # what the plan assumed for want of a fact (quiet: the plan's notes)
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"), 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, None, box, fc_src["pv"])
# occupied per step: the presence now, then the learnt weekly presence, else 06-22 (occupancy)
occupied, occ_src, occ_notes = occupancy(start, tz, col, inputs.presence if presence is None else presence,
bundles, history, box, box_params, occupied_hours, fc_src)
notes += occ_notes
# the forecasts per source for the live error (boxtrain.py), not for the plan
cands = {k: v.pop("_cands") for k, v in fc_src.items() if "_cands" in v}
net_load = None
@@ -533,18 +954,10 @@ def model_state(now: float, controls, inputs, col: Collector, bundles, history,
# the sun's elevation now, held: a placeholder until a forecast says
elev = number(col.attr(inputs.sun, "elevation")) if inputs.sun else None
sun = [max(0.0, math.sin(math.radians(elev))) if elev is not None else 0.0] * STEPS
present = None
if inputs.presence:
vals = [col.state(p) for p in inputs.presence]
present = any(v in ("on", "home") for v in vals) if any(v is not None for v in vals) else None
occupied = []
for k in range(STEPS):
if k < 4 and present is not None:
occupied.append(1 if present else 0)
continue
h = datetime.fromtimestamp(start + k * STEP_S, timezone.utc).astimezone(zone).hour
occupied.append(1 if occupied_hours[0] <= h < occupied_hours[1] else 0)
sessions = bundles.ev_sessions(now) if hasattr(bundles, "ev_sessions") else None
ev_src: dict = {}
devices, rooms_src, phases_src, refused, battery_src, heat_src = [], {}, {}, {}, {}, {}
battery_fit, tank_src = {}, {} # the box's idle fits in force, a tank's facts by source
# a room's COP and comfort temperatures: the mapping's (the device's facts, the owner's), or the
# defaults (optimizer.shift_envelope publishes no shift from defaults); rooms not planned
# (room_refusal) with what their fallback schedule needs
@@ -566,6 +979,11 @@ def model_state(now: float, controls, inputs, col: Collector, bundles, history,
params["phases"] = info["phases"]
phases_src[c.id] = {"phases": info["phases"], "source": info["source"]}
st = device_state(c, col, now)
if c.kind == "ev":
# the car's departure and energy from the session forecast where it says none (B15)
ev_src[c.id], note = ev_session(c, st, sessions, start, now)
if note:
notes.append(note)
if c.kind in ("heating", "cooling"):
# the room's and the device's facts the mapping gives (no defaults: controls.FACTS)
params.update({k: float(c.params[k]) for k in ("r_k_per_kw", "c_kwh_per_k", "max_power_w", "cop")
@@ -586,7 +1004,7 @@ def model_state(now: float, controls, inputs, col: Collector, bundles, history,
nos = [room_refusal(c, st, src, power, source)]
if c.kind == "heating":
nos.append(heating_refusal(c, params, price_gas, price_heat, getattr(prices, "status", "tariff"),
box_params))
box_params, price_oil))
nos = [n for n in nos if n is not None]
if nos:
# not planned: its limits and a fallback schedule (the owner's or
@@ -610,19 +1028,47 @@ def model_state(now: float, controls, inputs, col: Collector, bundles, history,
continue
facts, _, fsrc = c.battery_facts()
params.update(facts)
battery_src[c.id] = fsrc
battery_src[c.id] = dict(fsrc)
# its idle loss (A2.3, S.2): never refuses it; without any value 0, a quiet note
if hasattr(c, "battery_idle_facts"):
fit = storefit.battery_in_force(c.id) if storefit is not None else None
idle, isrc = c.battery_idle_facts(fit, box_params)
params.update(idle)
battery_src[c.id].update(isrc)
if fit:
battery_fit[c.id] = fit
if isrc["standby_w"] == "none":
notes.append(f"{c.id}: battery idle loss not modelled: parameter battery.standby_w unset")
# the battery's power from its facts (device_range ran before them in bounds)
b = c.bounds("power_w", (extra_limits or {}).get(c.id))
bounds["power_w"] = [b.lo, b.hi, b.lo_by, b.hi_by]
extra = {}
if c.kind == "dhw_tank":
got = _tank_state(c, st, params, start, now, tz, bundles, history, box, box_params, storefit,
price_gas, price_heat, len([x for x in controls if x.kind == "dhw_tank"]) == 1)
if "refused" in got:
refused[c.id] = dict(got["refused"], kind="dhw_tank", name=c.label() if hasattr(c, "label") else c.id)
continue
if "note" in got:
notes.append(got["note"])
continue
tank_src[c.id] = got["src"]
extra = {"draw_w": got["draw_w"]}
b = c.bounds("temp_c", (extra_limits or {}).get(c.id)) # with a Großanlage's floor (tank_facts)
bounds["temp_c"] = [b.lo, b.hi, b.lo_by, b.hi_by]
devices.append({"id": c.id, "kind": c.kind, "params": params,
"state": st, "bounds": bounds,
"channels": sorted(c.writable())})
"channels": sorted(c.writable()), **extra})
clouds = _hourly(weather_forecast or [], "cloud_coverage", start, STEPS)
sky = [max(0.0, min(1.0, 1 - c / 100.0)) for c in clouds] if clouds else [1.0] * STEPS
ghi, ghi_src = irradiance(start, location, sky, sun if peak > 100 else None)
# the heat outlook (space heat no room plans, hot water), CO2 (methods A2): the forecasts and factors
carriers = carrier_inputs(start, now, heat_site(controls, devices, inputs, price_gas, price_heat, price_oil),
bundles, history, tz, box)
out = {"v": 1, "start": start, "step_s": STEP_S, "steps": STEPS, "tz": tz,
**{k: v for k, v in carriers.items() if k != "sources"},
"price_import": prices.import_ct, "price_export": prices.export_ct, "price_note": prices.note,
"price_gas": price_gas, "price_heat": price_heat, "params": box_params,
"price_gas": price_gas, "price_heat": price_heat, "price_oil": price_oil, "params": box_params,
# the tariff's state (bundles.Prices): status tariff | none, why none, the steps it prices
"prices": {"status": getattr(prices, "status", "tariff"), "reason": getattr(prices, "reason", ""),
"tariff": getattr(prices, "tariff_id", ""), "expired_at": getattr(prices, "expired_at", 0),
@@ -633,9 +1079,15 @@ def model_state(now: float, controls, inputs, col: Collector, bundles, history,
"sky": "weather forecast" if clouds else "clear", "rooms": rooms_src, "ghi": ghi_src,
"rooms_cop": cop_src, "rooms_band": band_src,
"ev_phases": phases_src,
# occupied steps per source (presence now, learnt, fixed hours) and why (B16)
"occupancy": occ_src,
**({"ev": ev_src} if ev_src else {}),
**({"battery": battery_src} if battery_src else {}),
**({"battery_fit": battery_fit} if battery_fit else {}),
**({"dhw_tank": tank_src} if tank_src else {}),
**({"heating": heat_src} if heat_src else {}),
**({"intraday": intraday} if intraday else {}),
**({"carriers": carriers["sources"]} if carriers["sources"] else {}),
# 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}},
@@ -647,7 +1099,9 @@ def model_state(now: float, controls, inputs, col: Collector, bundles, history,
# (preferences.apply gives their schedule, optimizer.fallback_entries the setpoints)
"fallback": fallback,
# 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 []}
"market": bundles.market_for_model(start, STEP_S, STEPS, now) if hasattr(bundles, "market_for_model") else [],
# quiet notes (the plan's "notes"): no presence source, a parameter missing, the car's forecast session
"notes": notes}
if grid_max_w:
out["grid_max_w"] = float(grid_max_w)
if cands or net_load is not None:
@@ -779,7 +1233,7 @@ def room_refusal(c, st: dict, rc: str, power: str, source: str = "electric") ->
def _quantities(c) -> list[str]:
return {"battery": ["soc_pct", "power_w"], "heating": ["temp_c"], "cooling": ["temp_c"],
"ev": ["current_a"], "cover": ["position_pct"]}[c.kind]
"ev": ["current_a"], "cover": ["position_pct"], "dhw_tank": ["temp_c"]}[c.kind]
def _param_names(c) -> list[str]:
+47 -4
View File
@@ -16,6 +16,8 @@ entities belong to), and on a Hub the devices tool's specs
{"v":1, "made", "devices": [{"id", "source": "devices"|"ha",
"manufacturer", "model", "model_id", "sw_version", "hw_version",
"eebus_ski" (EEBUS devices), "category", "profile", "profile_version", "ratings": {...},
"rating_sources" (a hot-water volume meter's: {"dhw_kwh_per_m3": "installer" | "parameter"}),
"facts" (a boiler's: {"boiler_type", "part_load_curve": [[load share, factor], ...]}),
"assets": [...], "assumed": [...], "controls": [...], "protection",
"custodian"}],
"protection": [{"target", "level", "custodian", "source", "set_by",
@@ -29,6 +31,7 @@ import os
import re
import time
from .devprofiles import dhw_factor
from .policy import Policy
log = logging.getLogger(__name__)
@@ -87,9 +90,12 @@ def heating_ratings(controls) -> dict:
return {}
def build(mapping, registries: dict, specs: dict, policy: dict, now: float, ev_phases: dict | None = None) -> dict:
def build(mapping, registries: dict, specs: dict, policy: dict, now: float, ev_phases: dict | None = None,
box_params: dict | None = None) -> dict:
"""ev_phases: per EV control its phase count and source (evphases.py),
told on the device of the control ("1 phase, learned" in the console)."""
told on the device of the control ("1 phase, learned" in the console).
box_params: the Parameters page's values on the box (the tariff
bundle's: dhw.temperature_lift_k for a hot-water volume meter)."""
ents = {e["entity_id"]: e for e in registries.get("entities") or []}
devs = {d["id"]: d for d in registries.get("devices") or []}
asset_of = {a.entity: a.asset for a in mapping.assets}
@@ -169,7 +175,43 @@ def build(mapping, registries: dict, specs: dict, policy: dict, now: float, ev_p
for c in d.get("controls") or [] if c in (ev_phases or {})}
if ph:
d["ev_phases"] = ph
return {"v": 1, "made": int(now), "devices": out, "protection": prot}
# a hot-water volume meter's kWh per m³ (devprofiles.dhw_factor): the installer's (the device's
# ratings, else the mapping asset's), else the Parameters row's; the trainer and Insights take it
notes = []
by_asset = {a.asset: a for a in mapping.assets}
for d in out:
vol = [by_asset[x] for x in d.get("assets") or [] if x.startswith("dhw.volume") and x in by_asset]
if not vol:
continue
a = vol[0]
facts = {**{f"dhw_{k}": getattr(a, k, None) for k in ("kwh_per_m3", "cold_c", "hot_c")
if getattr(a, k, None) is not None}, **(d.get("ratings") or {})}
k, src, note = dhw_factor(facts, box_params)
d["ratings"] = dict(d.get("ratings") or {})
if k is not None:
# ratings stay numbers (fleet's map of numbers); where it came from beside them
d["ratings"]["dhw_kwh_per_m3"] = k
d["rating_sources"] = {"dhw_kwh_per_m3": src}
if note:
notes.append(note)
# a boiler's part load (methods E6.4): the mapping's boiler_type and part_load_curve as facts (text and
# lists, not ratings: fleet keeps them in the device's spec; the trainer's gas forecast reads them)
for d in out:
facts = {}
for cid in d.get("controls") or []:
c = controls.get(cid)
if c is None or c.kind != "heating":
continue
for k in ("boiler_type", "part_load_curve"):
v = (c.params or {}).get(k)
if v and k not in facts:
facts[k] = [list(x) for x in v] if k == "part_load_curve" else str(v)
if facts:
d["facts"] = facts
inv = {"v": 1, "made": int(now), "devices": out, "protection": prot}
if notes:
inv["notes"] = sorted(set(notes)) # quiet: what the inventory says for want of a fact
return inv
class Inventory:
@@ -182,6 +224,7 @@ class Inventory:
self.sent_digest, self.sent_at = "", 0.0
self.waiting = False # the link was not connected: try again soon (agent.inventory_loop)
self.ev_phases = None # () -> per EV control its phases and source (the controller's; agent.py)
self.params = None # () -> the box's Parameters values (the tariff bundle's; agent.py)
def specs(self) -> dict:
try:
@@ -212,7 +255,7 @@ class Inventory:
if self.sent_at and now - self.sent_at < MIN_GAP_S:
return False
inv = build(self.mapping, reg, self.specs(), self.policy.entries(), now,
self.ev_phases() if self.ev_phases else None)
self.ev_phases() if self.ev_phases else None, self.params() if self.params else None)
body = {k: v for k, v in inv.items() if k != "made"}
digest = hashlib.sha256(json.dumps(body, sort_keys=True).encode()).hexdigest()
if digest == self.sent_digest and now - self.sent_at < RESEND_S:
+61 -14
View File
@@ -19,7 +19,9 @@ decision rule, the same sums), so the box needs numpy, not 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
mapping's weather entity: temperature, cloud cover and the wind, in m/s
from the entity's wind_speed_unit; an unknown unit: no wind, noted, never
a guess; 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
@@ -41,12 +43,22 @@ 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 carriers' (methods.md B13-B16): the box carries their models, it plans on none of them yet
# the carriers' (methods.md B13-B16): the planner takes the occupancy
# (inputs.occupancy) and the heat (the optimiser's outlook)
"heat_w": "heat", "dhw_w": "dhw", "occupancy": "occupancy", "ev_plug": "ev_plug"}
# 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"} # the carriers': none kept (no lag)
# is the load where the box plans none (the only case its load_w is used);
# the carriers' own names (the agent's History keeps none of them: no lag;
# the box's own models read theirs from the training history, boxtrain)
HISTORY = {"load_w": "load_w", "base_load_w": "load_w", "pv_w": "pv_w", "heat_w": "heat_w", "dhw_w": "dhw_w",
"occupancy": "occupancy", "ev_plug": "ev_plug"}
# the features that need the weather (a series on the calendar alone,
# occupancy and ev_plug, is forecast for every step without any)
WEATHER_FEATURES = frozenset({"temp", "ghi", "cloud", "hdd", "wind", "elev", "az", "phys", "loss"})
# Home Assistant's wind speed units (its weather entity's wind_speed_unit,
# HA's UnitOfSpeed for weather) in m/s: unit definitions, not tunables
WIND_UNITS = {"m/s": 1.0, "km/h": 1.0 / 3.6, "mph": 0.44704, "kn": 1852.0 / 3600.0, "ft/s": 0.3048}
SITE_FIELDS = {"tz": str, "lat": float, "lon": float, "kwp": float, "tilt": float, "azimuth": float, "state": str}
@@ -130,10 +142,19 @@ class Model:
# ---- the weather on the box ---------------------------------------------------
def ha_hours(forecast: list[dict] | None) -> list:
def wind_ms(v, unit) -> float | None:
"""A wind speed in Home Assistant's unit (its weather entity's
wind_speed_unit) in m/s; None for a unit not in WIND_UNITS (never a
guess at the scale) or no number."""
f = WIND_UNITS.get(str(unit).strip()) if unit is not None else None
return float(v) * f if f is not None and _num(v) and v >= 0 else None
def ha_hours(forecast: list[dict] | None, wind_unit=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)."""
(pvforecast.Hour): the temperature, the cloud cover and the wind (m/s,
from wind_unit: the weather entity's wind_speed_unit; unknown: none) at
each record's time, as the cloud's records give them (no irradiation)."""
out = {}
for f in forecast or []:
try:
@@ -145,11 +166,22 @@ def ha_hours(forecast: list[dict] | None) -> list:
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
wind = wind_ms(f.get("wind_speed"), wind_unit)
if temp is not None or cloud is not None:
out[ts] = pvforecast.Hour(datetime.fromtimestamp(ts, timezone.utc), None, cloud, temp)
out[ts] = pvforecast.Hour(datetime.fromtimestamp(ts, timezone.utc), None, cloud, temp, wind)
return [out[k] for k in sorted(out)]
def wind_note(forecast: list[dict] | None, wind_unit) -> str:
"""Why HA's forecast gave no wind although it has one: its unit is
unknown (none, or not one of HA's: WIND_UNITS)."""
if wind_unit is not None and str(wind_unit).strip() in WIND_UNITS:
return ""
if not any(_num((f or {}).get("wind_speed")) for f in forecast or []):
return ""
return f"HA's wind not used: unit {wind_unit!r} unknown"
def cloud_hours(recs) -> list:
"""The bundle's "weather": [{"end", "solar", "cloud", "temp", "wind"}]."""
out = []
@@ -197,11 +229,19 @@ def _history(history, name: str, t0: int, t1: int) -> tuple[np.ndarray, np.ndarr
# ---- the box's forecast ------------------------------------------------------
def needs_weather(model: Model) -> bool:
"""A gbm with a weather feature (a calendar-only series, occupancy or
ev_plug, has none: forecast for every step)."""
return model.kind != "gbm" or bool(set(model.params.get("features") or []) & WEATHER_FEATURES)
def predict(model: Model, t: list[int], history, ha_forecast: list[dict] | None, cloud_weather,
entity: str = "", issued=None) -> tuple[list[float | None], dict]:
entity: str = "", issued=None, wind_unit=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"}."""
publishes it): per slot a value (W; a share for occupancy, never above
fcmodels.UPPER) or None (no weather for a model that needs it: the
hour-of-week then), and {"kind", "weather", "steps"}. wind_unit: the
weather entity's wind_speed_unit (HA's wind in m/s)."""
ta = np.asarray(t, dtype=np.int64)
info = {"kind": model.kind, "weather": "", "steps": 0}
if model.kind == "how":
@@ -209,9 +249,15 @@ def predict(model: Model, t: list[int], history, ha_forecast: list[dict] | None,
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))
hours, src = merge_hours(ha_hours(ha_forecast, wind_unit), cloud_hours(cloud_weather))
info["weather"] = describe(src, t, entity, issued)
covered = [((ts // 3600 + 1) * 3600) in src for ts in t]
wn = wind_note(ha_forecast, wind_unit)
if wn:
info["weather"] += f"; {wn}"
if needs_weather(model):
covered = [((ts // 3600 + 1) * 3600) in src for ts in t]
else:
covered = [True] * len(t)
s = model.site
w = fcmodels.weather(ta, hours, s.lat, s.lon)
ht, hy = _history(history, HISTORY.get(model.name, ""), int(ta[0]) - 7 * 86400, int(ta[0]))
@@ -219,9 +265,10 @@ def predict(model: Model, t: list[int], history, ha_forecast: list[dict] | None,
clim = model.climate(ta) if not all(covered) else None
out: list[float | None] = []
n_clim = 0
top = fcmodels.UPPER.get(model.series)
for k, v in enumerate(p.tolist()):
if covered[k] and not math.isnan(v):
out.append(max(0.0, v))
out.append(min(max(0.0, v), top) if top is not None else 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
+44 -4
View File
@@ -58,12 +58,18 @@ UNITS = {
"Wh": ("Wh", 1.0), "kWh": ("Wh", 1e3), "MWh": ("Wh", 1e6),
"°C": ("°C", 1.0), "%": ("%", 1.0), "V": ("V", 1.0), "A": ("A", 1.0),
"Hz": ("Hz", 1.0), "lx": ("lx", 1.0), "ppm": ("ppm", 1.0),
# water drawn (a hot-water meter's dhw.volume): litres; HA's water sensors count L or m³
"L": ("L", 1.0), "m³": ("L", 1e3),
}
ROLE = {"power": "power", "energy": "energy", "temperature": "temp", "humidity": "humidity",
"battery": "soc", "voltage": "voltage", "current": "current", "frequency": "frequency",
"illuminance": "illuminance", "carbon_dioxide": "co2"}
"illuminance": "illuminance", "carbon_dioxide": "co2", "water": "volume", "volume": "volume"}
# Words in an entity's name that say which part of the system it measures.
SYSTEMS = [("pv", ("pv", "solar", "photovoltaic")), ("battery", ("battery", "batt")),
# Hot water first (a "boiler hot water" meter is the hot water's); never a
# water heater's own electricity (its "heater"): that is no hot-water meter.
DHW_WORDS = ("hot water", "hotwater", "warmwasser", "dhw", "domestic water")
NOT_DHW = re.compile(r"(?:^|[^a-z])(heater|heizstab|element|temperature|temp)(?:[^a-z]|$)") # whole words
SYSTEMS = [("dhw", DHW_WORDS), ("pv", ("pv", "solar", "photovoltaic")), ("battery", ("battery", "batt")),
("grid", ("grid", "import", "export", "feed")), ("load", ("load", "consumption")),
("heatpump", ("heat pump", "heatpump", "boiler", "combi")), ("ev", ("wallbox", "charger", "ev "))]
@@ -96,6 +102,19 @@ class Asset:
equals: str = "" # 1 while the value is this text, else 0
assumed: bool = False # the device does not report back: what HA last sent, not measured
fallback: bool = False # a stand-in (the weather service's outside.temp): a measured one takes its id
# the entity's unit as the installer says it, over Home Assistant's (none, or a wrong one: a
# hot-water meter counting m³ or L; devprofiles.meter_unit from the device's rating)
unit_in: str = ""
# a hot-water volume meter's facts, the installer's (devprofiles.dhw_factor): kWh of heat per m³
# drawn, or the cold and the hot water's temperatures (°C)
kwh_per_m3: float | None = None
cold_c: float | None = None
hot_c: float | None = None
def ha_unit(self, unit: str | None) -> str | None:
"""The unit a value of the entity is in: the installer's (unit_in),
else an attribute's (the asset's own), else Home Assistant's."""
return self.unit_in or (self.unit if self.attribute else unit)
class Mapping:
@@ -270,6 +289,13 @@ def _assets(raw: list) -> list[Asset]:
raise ValueError(f"{a.entity}: attribute and equals are text; equals only on a gauge")
if not isinstance(a.assumed, bool):
raise ValueError(f"{a.entity}: assumed is true or false")
if a.unit_in and (a.unit_in not in UNITS or UNITS[a.unit_in][0] != a.unit):
raise ValueError(f"{a.entity}: unit_in is a unit that becomes {a.unit}")
for k in ("kwh_per_m3", "cold_c", "hot_c"):
v = getattr(a, k)
if v is not None and (not isinstance(v, (int, float)) or isinstance(v, bool) or not -50 < v < 200
or k == "kwh_per_m3" and v <= 0):
raise ValueError(f"{a.entity}: {k} is a number" + (" above 0" if k == "kwh_per_m3" else " (°C)"))
seen.add(a.asset)
return assets
@@ -294,6 +320,8 @@ def convert(value: float, unit: str | None, target: str) -> float | None:
return (value - 32) * 5 / 9
if unit == "K" and target == "°C":
return value - 273.15
if (unit or "") == target:
return value
canon = UNITS.get(unit or "")
if canon is None:
return value if (unit or "") == target else None
@@ -321,8 +349,13 @@ def suggest(states: list[dict], registries: dict) -> dict:
reg = entities.get(eid, {})
area_id = reg.get("area_id") or devices.get(reg.get("device_id"), {}).get("area_id")
name = (attrs.get("friendly_name") or eid).lower()
system = next((s for s, words in SYSTEMS if any(w in name for w in words)), None)
role = ROLE[dc]
# a hot-water meter (dhw.energy, dhw.volume, dhw.power): only where it
# clearly is one; water drawn is read for hot water only
dhw = role in ("power", "energy", "volume") and not NOT_DHW.search(name)
system = next((s for s, words in SYSTEMS if (s != "dhw" or dhw) and any(w in name for w in words)), None)
if role == "volume" and system != "dhw":
continue
if system == "grid" and dc in ("power", "energy"):
role = ("export_" if "export" in name or "feed" in name else "import_") + role
prefix = system or (f"room.{_slug(areas[area_id])}" if area_id in areas else "site")
@@ -344,7 +377,9 @@ def suggest(states: list[dict], registries: dict) -> dict:
# own meters come off the load (inputs.base_load). Not the battery: a house
# load never includes its charging.
CONTROLLED_POWER = {"heating": ("heatpump.power", "heating.power"), "cooling": ("ac.power", "cooling.power"),
"ev": ("ev.power",)}
"ev": ("ev.power",),
# a hot-water tank's heater (an element, a heat-pump water heater) inside the house load
"dhw_tank": ("dhw.heater_power",)}
def controlled_power(m: "Mapping") -> list[str]:
@@ -364,4 +399,9 @@ def controlled_power(m: "Mapping") -> list[str]:
else:
ents = []
out += [e for e in ents if e not in out]
# a tank's own heater-power sensor (its control's heater_power role), where no asset names it
for c in m.controls:
e = c.entities.get("heater_power") if c.kind == "dhw_tank" else None
if e and e not in out:
out.append(e)
return out
+4
View File
@@ -227,6 +227,10 @@ NAMES = {
"cs_incomplete": {"en": "* at least: some kWh had no price.", "de": "* mindestens: einige kWh hatten keinen Preis."},
"cs_forecast_how": {"en": "Forecast: the cost per hour of the last {0} days for the rest of the month.",
"de": "Prognose: die Kosten je Stunde der letzten {0} Tage für den Rest des Monats."},
"cs_heat_outlook": {"en": "Expected for heat ({0}) over the next {1} h: {2} for {3} kWh (Cantabile's forecast; "
"not optimised).",
"de": "Erwartet für Wärme ({0}) in den nächsten {1} h: {2} für {3} kWh (Prognose von "
"Cantabile; nicht optimiert)."},
"cs_unbilled_note": {"en": "At your own supplier's price (what is billed now): {0}.",
"de": "Zum Preis Ihres eigenen Lieferanten (was jetzt abgerechnet wird): {0}."},
"cs_offer_saved": {"en": "Building offer vs your own supplier: **{0} saved** this month ({1} kWh)",
File diff suppressed because it is too large. Load diff
+41
View File
@@ -0,0 +1,41 @@
# Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
"""The plan's saving split by carrier and lever (docs/methods.md A12, E14):
for the console's Savings page, which shows per carrier what the household
paid with Cantabile and would have paid without, and the levers load
shifting / off-peak buying and heating apart.
From the plan's own per-step costs (optimizer.step_costs: per carrier what
each step costs with the plan and without it, at the same prices), summed
over the horizon, and the heating's share of the electricity saving: the
heating and cooling devices' electric draw at the horizon's mean import
price (as the baseline counts it) against the step's own price, i.e. the
saving from moving the heat pump's or heater's electricity in time. The rest
of the electricity saving is load shifting and off-peak buying (battery,
car, appliances). Gas and district heat are the heating's alone.
{"electricity": {"plan_eur", "base_eur", "heating_eur"},
"gas": {"plan_eur", "base_eur"}, "heat": {"plan_eur", "base_eur"}}
base_eur − plan_eur summed over the carriers is the plan's saving without
the market's contracts (cost_eur carries them, step_costs does not). None
without a tariff (no step costs)."""
def saving_parts(s: dict, m, x, steps: dict | None) -> dict | None:
if steps is None:
return None
out = {}
for carrier, d in steps.items():
out[carrier] = {"plan_eur": round(sum(d["plan"]), 4), "base_eur": round(sum(d["base"]), 4)}
if "electricity" in out:
pi = s["price_import"]
mean = sum(pi) / m.T
heating = 0.0
for kind, v in m.devices.values():
if not v or kind not in ("heating", "cooling"):
continue
for t, p in enumerate(v["power"]):
if p is not None:
heating += m.eur_wh(t, mean - pi[t]) * x(p)
out["electricity"]["heating_eur"] = round(heating, 4)
return out
+66 -6
View File
@@ -733,26 +733,86 @@ class Preferences:
f["text"] = feedback_words(f)
fb.append(f)
self.feedback = fb
# storage: per battery and hot-water tank its idle loss and facts with their sources
# (docs/design/storage-losses.md 10.5), for both Devices pages (devprofiles.storage_of)
self.planning = {"priced": plan.get("priced", True), "note": plan.get("price_note", ""),
"prices": plan.get("price_state") or {}, "refused": plan.get("refused") or {},
"made": plan.get("made")}
"made": plan.get("made"), "storage": plan.get("storage") or {}}
plan["prefs"] = fb
plan.pop("prefs_cost", None)
return fb
# -- out ---------------------------------------------------------------------------
def public(self) -> dict:
def public(self, controls=None, presence: bool = False, occupancy: dict | None = None) -> dict:
"""For the cloud (with the plan) and the panel: the settings per
level with who and when, the overrides in force, the feedback, the
last changes."""
last changes; with the controls, builtin(): the agent's own targets
where no setting gives the plan any (absent from older agents)."""
items = {}
for key, per in self.items.items():
top = self.effective(key)
items[key] = {"in_force": top["level"] if top else None,
"levels": {lvl: {"value": e["value"], "by": e["by"], "at": e["at"],
"text": text_of(key, e["value"])} for lvl, e in per.items()}}
return {"v": 1, "items": items, "overrides": self.active_overrides(), "feedback": self.feedback,
"log": self.log[-20:], "changed_at": int(self.changed_at)}
out = {"v": 1, "items": items, "overrides": self.active_overrides(), "feedback": self.feedback,
"log": self.log[-20:], "changed_at": int(self.changed_at)}
if controls is not None:
out["builtin"] = self.builtin(controls, presence, occupancy)
return out
def builtin(self, controls, presence: bool = False, occupancy: dict | None = None) -> dict:
"""Per control whose setting in force gives the plan nothing (none
set at any level, or one without rows): the agent's built-in targets
that the plan uses instead, keyed like items:
room:<id> {kind: heat|cool, comfort_c, setback_c | setup_c,
from, to, occupied}: the comfort target while
occupied, the setback/setup otherwise; occupied
"learnt" (the learnt weekly presence: the plan's
sources.occupancy, inputs.occupancy) or "hours"
(from..to, inputs.OCCUPIED_HOURS) with
occupied_why where the plan says why (no presence
source, none learnt yet, the parameter missing,
the learnt presence never occupied);
the first hour follows presence where the box has
a presence source (presence true)
ev:<id> {kind: car, need_kwh, ready_by, car: [roles]}: the
mapping's need_wh by its departure; the car's own
entities (departure, energy_needed) win when mapped
battery:<id> {kind: battery, reserve_pct, by}: the lowest state of
charge the limits allow (no reserve of the owner's)"""
from .inputs import OCCUPIED_HOURS
out = {}
for c in controls:
if c.kind not in KINDS:
continue
key = f"{KINDS[c.kind]}:{c.id}"
v = self.value(key) or {}
if c.kind in ("heating", "cooling"):
if v.get("blocks"):
continue
cool = c.kind == "cooling"
b = {"kind": "cool" if cool else "heat", "comfort_c": _p(c, "comfort_c"),
("setup_c" if cool else "setback_c"): _p(c, "setup_c" if cool else "setback_c"),
"from": f"{OCCUPIED_HOURS[0]:02d}:00", "to": f"{OCCUPIED_HOURS[1]:02d}:00",
"occupied": "learnt" if (occupancy or {}).get("source") == "learnt" else "hours"}
if b["occupied"] == "hours" and (occupancy or {}).get("why"):
b["occupied_why"] = str(occupancy["why"])
if presence:
b["presence"] = True
elif c.kind == "ev":
if v.get("ready"):
continue
need = _p(c, "need_wh")
b = {"kind": "car", "need_kwh": round(need / 1000.0, 2) if need is not None else None,
"ready_by": str(c.p("departure") or ""),
"car": [r for r in ("departure", "energy_needed") if c.entities.get(r)]}
else:
if v and (float(v.get("reserve_pct") or 0) > 0 or v.get("blocks")):
continue
lim = c.bounds("soc_pct")
b = {"kind": "battery", "reserve_pct": lim.lo, "by": lim.lo_by}
out[key] = b
return out
def write_view(self, controls, mode: str = ""):
"""preferences-view.json for the Hub's panel: the controls (id,
@@ -765,7 +825,7 @@ class Preferences:
b = c.bounds(q)
cl.append({"id": c.id, "kind": c.kind, "name": c.label(), "bounds": [b.lo, b.hi],
"setback_c": _p(c, "setback_c"), "setup_c": _p(c, "setup_c"), "comfort_c": _p(c, "comfort_c")})
v = dict(self.public(), controls=cl, mode=mode, errors=self.errors, ha=self.ha, made=int(self.clock()),
v = dict(self.public(controls), controls=cl, mode=mode, errors=self.errors, ha=self.ha, made=int(self.clock()),
planning=self.planning, own_tariff=self.own_tariff)
try:
tmp = self.view_path + ".tmp"
+41 -1
View File
@@ -22,7 +22,14 @@ owner's choice):
2. HA devices a profile recognises (manufacturer, model, integration):
the profile's value matchers on their entities, as the Hub's devices
tool does for "Use with Cantabile";
3. the rest by name (mapping.suggest): only Cantabile's own quantities
3. the presence sources (methods.md B16): each HA person as
person.<id>.home (1 while "home", else 0; <id> a short hash of the
entity, not the person's name: an asset id leaves the site once
consented) and one occupancy or presence binary_sensor per area as
room.<area>.occupied (1 while "on"), for the occupancy the box and
the cloud learn; device trackers are left to the persons they make
up (or mapped by hand);
4. the rest by name (mapping.suggest): only Cantabile's own quantities
(pv, grid, battery, load, heat pump, EV) and one temperature and
humidity per area, from sensors that have a value now; marked
unverified by `source: proposed`.
@@ -267,6 +274,33 @@ def from_profiles(r: Registry, profiles: list[dict]) -> list[tuple[str, dict, fl
return out
PRESENCE_CLASSES = ("occupancy", "presence") # a binary_sensor's device classes that say someone is there
def person_id(entity_id: str) -> str:
"""A person's id in its asset (person.<id>.home): stable, not the name."""
return "p" + hashlib.sha256(entity_id.encode()).hexdigest()[:6]
def presence_sources(r: Registry) -> list[tuple[str, str, dict, bool]]:
"""(asset, entity, read, unique) of the presence sources: HA's persons
(person.<id>.home, equals home) and per area one occupancy or presence
binary_sensor (room.<area>.occupied, equals on)."""
out = []
for eid in sorted(r.states):
if eid.startswith("person."):
out.append((f"person.{person_id(eid)}.home", eid, {"equals": "home"}, False))
for e in r.entities:
eid = e["entity_id"]
if not eid.startswith("binary_sensor."):
continue
dc = (r.attrs(e) or {}).get("device_class") or e.get("device_class") or e.get("original_device_class")
area = r.area_name(e)
if dc in PRESENCE_CLASSES and area:
out.append((f"room.{slug(area)}.occupied", eid, {"equals": "on"}, True))
return out
def place(q: str, r: Registry, e: dict) -> str:
"""room.{area}.temp -> room.kitchen.temp: the entity's area, else its name."""
if "{area}" not in q:
@@ -328,6 +362,12 @@ def propose(states: list[dict], reg: dict, profiles: list[dict], keep: list[dict
if got:
out.append(got)
skip = u_ents | {e["entity_id"] for e in r.entities if e.get("device_id") in u_devs}
for q, eid, read, unique in presence_sources(r):
if eid in skip:
continue
got = taken.add(eid, q, "gauge", "", unique=unique, read=read)
if got:
out.append(got)
return out + kept + by_name(states, reg, r, taken, skip)
+408
View File
@@ -0,0 +1,408 @@
# Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
"""What the box learns about its stores from their own telemetry
(docs/methods.md A13, design note docs/design/storage-losses.md 2.4, 3.5):
battery its idle loss (the standby W, the cells' self-discharge) from
the quarter-hours it sat still: the power method (the median of
the battery's own power while idle: P⁰ = -median) and the SoC
drift method (ΔE/Δt = -P⁰ - λ·E over idle runs of at least
battery.idle_fit_min_run_h, by least squares where runs at
several charge levels exist, else P⁰ alone). Gated: at least
battery.idle_fit_min_hours idle in the last 14 days, the two
methods within battery.idle_fit_agree_pct where both exist,
P⁰ ≥ 0. A fit a day; the one in force is the median of the last
FITS_KEPT (a bad night does not move it).
dhw_tank the draw from the tank's own sensors (S.7: D = (φE_{t-1} - E_t)/Δt
+ Q - P⁰), kept per quarter-hour, as the box's own hour-of-week
profile where no hot-water forecast exists (after
dhw.draw_history_min_days); its UA from cooling curves (heater
off, no draw: ln(T̄ - T_room) falls by UA/(c_w V) per hour)
after dhw.ua_fit_min_hours, kept only within dhw.ua_fit_band of
the label's (else noted: the tank loses more than its label);
and the last time it was at the legionella temperature.
Every threshold is a Parameters row (the tariff bundle's params); without
one nothing is fitted (the plan keeps the owner's or the Parameters' value).
State in <state_dir>/storefit.json.
"""
import json
import logging
import math
import os
import statistics
import time
from datetime import datetime, timezone
from zoneinfo import ZoneInfo
log = logging.getLogger(__name__)
SLOT_S = 900
KEEP_S = 14 * 86400 # ENG: the window a fit looks at (two weeks: two of each weekday)
FITS_KEPT = 4 # ENG: the fits whose median is in force
REFIT_S = 86400 # ENG: a fit a day
WATER_WH_PER_L_K = 1.163 # physics: water's heat capacity, Wh per litre and kelvin
# the Parameters rows (docs/parameters.md; design note 10.6)
P_MIN_RUN_H = "battery.idle_fit_min_run_h"
P_MIN_HOURS = "battery.idle_fit_min_hours"
P_DEAD_BAND = "battery.idle_dead_band_w"
P_IDLE_MAX = "battery.idle_max_w"
P_AGREE = "battery.idle_fit_agree_pct"
P_DRAW_K = "dhw.draw_detect_k_per_15min"
P_UA_HOURS = "dhw.ua_fit_min_hours"
P_UA_BAND = "dhw.ua_fit_band"
P_DRAW_DAYS = "dhw.draw_history_min_days"
def _num(v):
try:
x = float(v)
except (TypeError, ValueError):
return None
return x if math.isfinite(x) else None
# -- the battery ---------------------------------------------------------------
def idle_slot(power_w: list[float], pv_w: float | None, grid_charge: bool, soc: float | None,
dead_band: float, idle_max: float) -> bool:
"""A quarter-hour the battery sat still: its power steady (max - min
within the dead band: a standby is constant, a battery following the
house is not) between -idle_max and +dead_band W, no PV on its side
(pv below the dead band, or none mapped), its grid charging off, its
charge neither empty nor full (a full battery's BMS may top it up)."""
if not power_w or grid_charge or soc is None or not 0 < soc < 100:
return False
if pv_w is not None and pv_w > dead_band:
return False
mean = sum(power_w) / len(power_w)
return -idle_max <= mean <= dead_band and max(power_w) - min(power_w) <= dead_band
def fit_battery(slots: list[dict], cap_wh: float, params: dict) -> dict | None:
"""One fit from quarter-hours [{"t", "idle", "p" (mean W, + charge),
"soc0", "soc1" (% at its start and end)}] (the last 14 days): {"standby_w",
"loss_pct_h" (None: one charge level only), "n_hours", "method", "power_w",
"soc_w"}, or None (gate not passed, or a parameter missing)."""
min_run_h, min_hours, agree = (_num(params.get(k)) for k in (P_MIN_RUN_H, P_MIN_HOURS, P_AGREE))
if min_run_h is None or min_hours is None or agree is None or not cap_wh:
return None
idle = sorted((s for s in slots if s.get("idle")), key=lambda s: s["t"])
n_hours = len(idle) * SLOT_S / 3600.0
if n_hours < min_hours:
return None
pw = [s["p"] for s in idle if s.get("p") is not None]
p_power = -statistics.median(pw) if pw else None
# runs of consecutive idle quarter-hours, at least min_run_h long: the SoC's drift over each
runs, cur = [], []
for s in idle:
if cur and s["t"] - cur[-1]["t"] != SLOT_S:
runs.append(cur)
cur = []
cur.append(s)
if cur:
runs.append(cur)
pts = [] # (stored Wh at the run's middle, loss W)
for r in runs:
h = len(r) * SLOT_S / 3600.0
if h < min_run_h or r[0].get("soc0") is None or r[-1].get("soc1") is None:
continue
de = (r[-1]["soc1"] - r[0]["soc0"]) / 100.0 * cap_wh
pts.append(((r[0]["soc0"] + r[-1]["soc1"]) / 200.0 * cap_wh, -de / h))
p_soc = lam = None
if pts:
es = [e for e, _ in pts]
if len(pts) >= 2 and max(es) - min(es) >= 0.1 * cap_wh:
# loss = P⁰ + λ·E by least squares (λ per hour, as a share of the stored energy)
me, ml = sum(es) / len(es), sum(w for _, w in pts) / len(pts)
sxx = sum((e - me) ** 2 for e in es)
slope = sum((e - me) * (w - ml) for e, w in pts) / sxx if sxx else 0.0
if slope >= 0:
lam, p_soc = slope, ml - slope * me
else:
p_soc = statistics.median(w for _, w in pts)
else:
p_soc = statistics.median(w for _, w in pts)
if p_power is None and p_soc is None:
return None
if p_power is not None and p_soc is not None:
ref = max(abs(p_power), abs(p_soc), 1e-9)
if abs(p_power - p_soc) / ref * 100.0 > agree:
return None # the two disagree: no fit this time
p0 = p_power if p_power is not None else p_soc
if p0 is None or p0 < 0:
return None
return {"standby_w": round(p0, 1), "loss_pct_h": round(lam * 100.0, 5) if lam is not None else None,
"n_hours": round(n_hours, 1), "method": "power" if p_power is not None else "soc",
"power_w": None if p_power is None else round(p_power, 1),
"soc_w": None if p_soc is None else round(p_soc, 1)}
# -- the tank --------------------------------------------------------------------
def tank_energy_wh(volume_l: float, temp_c: float, cold_c: float) -> float:
"""S.4: the stored heat above the cold water (Wh)."""
return WATER_WH_PER_L_K * volume_l * (temp_c - cold_c)
def mean_temp(top: float | None, bottom: float | None, top_share: float) -> float | None:
"""S.4: the tank's mean temperature from its sensors (both: weighted by
the top sensor's share of the volume; one: that one)."""
if top is not None and bottom is not None:
return top_share * top + (1 - top_share) * bottom
return top if top is not None else bottom
def draw_w(e_prev: float, e_now: float, heat_w: float, ua_w_k: float, volume_l: float, room_c: float,
cold_c: float, dt_h: float) -> float:
"""S.7: the hot water drawn in a step (W of heat): what the tank lost
beyond its standing loss and the heat put in, never below 0. The loss
UA(T̄ - T_room) in E: λ·E + P⁰ with λ = UA/(c_w V), P⁰ = UA(T_cw - T_room)."""
lam = ua_w_k / (WATER_WH_PER_L_K * volume_l)
phi = 1.0 - lam * dt_h
p0 = ua_w_k * (cold_c - room_c)
return max(0.0, (phi * e_prev - e_now) / dt_h + heat_w - p0)
def fit_ua(curves: list[list[tuple[float, float]]], volume_l: float) -> tuple[float, float] | None:
"""UA (W/K) from cooling runs [[(hours, T̄ - T_room), ...], ...] (heater
off, no draw): the slope of ln(ΔT) against time, pooled over the runs
(each run's own intercept); (UA, hours used) or None."""
num = den = 0.0
hours = 0.0
for run in curves:
pts = [(t, math.log(d)) for t, d in run if d > 1.0]
if len(pts) < 3:
continue
mt = sum(t for t, _ in pts) / len(pts)
my = sum(y for _, y in pts) / len(pts)
num += sum((t - mt) * (y - my) for t, y in pts)
den += sum((t - mt) ** 2 for t, _ in pts)
hours += pts[-1][0] - pts[0][0]
if den <= 0:
return None
slope = num / den # 1/h, negative while cooling
if slope >= 0:
return None
return -slope * WATER_WH_PER_L_K * volume_l, hours
class StoreFit:
"""The box's samples and fits for its batteries and tanks (one file)."""
def __init__(self, path: str, clock=time.time):
self.path, self.clock = path, clock
self.bat: dict = {} # cid -> {"slots": {t: {...}}, "fits": [...], "at": last fit time}
self.tank: dict = {} # cid -> {"draw": {t: W}, "cool": [[t, T̄ - T_room], ...] runs, "ua": {...},
# "legionella": last ts, "last": {t, e, heat}}
try:
with open(path) as f:
raw = json.load(f)
self.bat = {k: {"slots": {int(t): v for t, v in d.get("slots", {}).items()},
"fits": d.get("fits", []), "at": d.get("at", 0)} for k, d in raw.get("battery", {}).items()}
self.tank = {k: {"draw": {int(t): v for t, v in d.get("draw", {}).items()}, "cool": d.get("cool", []),
"ua": d.get("ua"), "legionella": d.get("legionella"), "last": d.get("last"),
"since": d.get("since")} for k, d in raw.get("tank", {}).items()}
except (OSError, ValueError, AttributeError):
pass
self._cur: dict = {} # (cid, slot) -> samples in the open quarter-hour
# -- battery ------------------------------------------------------------------
def sample_battery(self, cid: str, now: float, soc: float | None, power_w: float | None, pv_w: float | None,
grid_charge: bool):
"""A reading of a battery (once a minute or so): closed into its
quarter-hour when the next one starts."""
slot = int(now // SLOT_S * SLOT_S)
cur = self._cur.get(("b", cid))
if cur is not None and cur["t"] != slot:
self._close_battery(cid, cur)
cur = None
if cur is None:
cur = self._cur[("b", cid)] = {"t": slot, "p": [], "soc": [], "pv": [], "grid": False}
if power_w is not None:
cur["p"].append(float(power_w))
if soc is not None:
cur["soc"].append(float(soc))
if pv_w is not None:
cur["pv"].append(float(pv_w))
cur["grid"] = cur["grid"] or bool(grid_charge)
def _close_battery(self, cid, cur):
if not cur["p"] and not cur["soc"]:
return
d = self.bat.setdefault(cid, {"slots": {}, "fits": [], "at": 0})
d["slots"][cur["t"]] = {"p": sum(cur["p"]) / len(cur["p"]) if cur["p"] else None,
"pmin": min(cur["p"]) if cur["p"] else None, "pmax": max(cur["p"]) if cur["p"] else None,
"soc0": cur["soc"][0] if cur["soc"] else None, "soc1": cur["soc"][-1] if cur["soc"] else None,
"pv": max(cur["pv"]) if cur["pv"] else None, "grid": cur["grid"]}
def fit_batteries(self, caps: dict, params: dict, now: float | None = None) -> dict:
"""A fit a day per battery (caps: cid -> capacity Wh in force): the
new fits; old slots dropped."""
now = self.clock() if now is None else now
dead, idle_max = _num(params.get(P_DEAD_BAND)), _num(params.get(P_IDLE_MAX))
out = {}
for cid, d in self.bat.items():
d["slots"] = {t: v for t, v in d["slots"].items() if t >= now - KEEP_S}
if now - d.get("at", 0) < REFIT_S or dead is None or idle_max is None or not caps.get(cid):
continue
d["at"] = now
slots = []
for t, v in sorted(d["slots"].items()):
ps = [x for x in (v.get("pmin"), v.get("pmax")) if x is not None]
soc = v.get("soc0") if v.get("soc0") is not None else v.get("soc1")
idle = bool(ps) and idle_slot(ps, v.get("pv"), v.get("grid", False), soc, dead, idle_max)
slots.append({"t": t, "idle": idle, "p": v.get("p"), "soc0": v.get("soc0"), "soc1": v.get("soc1")})
f = fit_battery(slots, caps[cid], params)
if f is not None:
f["at"] = int(now)
d["fits"] = (d.get("fits") or [])[-(FITS_KEPT - 1):] + [f]
out[cid] = f
return out
def battery_in_force(self, cid: str) -> dict | None:
"""The fit in force: the median of the last fits' standby (and
self-discharge, where fitted), with the newest's hours, method and
time; None without a fit."""
fits = (self.bat.get(cid) or {}).get("fits") or []
if not fits:
return None
lams = [f["loss_pct_h"] for f in fits if f.get("loss_pct_h") is not None]
last = fits[-1]
return {"standby_w": round(statistics.median(f["standby_w"] for f in fits), 1),
"loss_pct_h": statistics.median(lams) if lams else None,
"n_hours": last["n_hours"], "method": last["method"], "at": last["at"], "fits": len(fits)}
# -- tank ---------------------------------------------------------------------
def sample_tank(self, cid: str, now: float, temp_c: float | None, room_c: float, heat_w: float | None,
facts: dict):
"""A reading of a tank (its mean temperature, the room, the heat put
in: W of heat): per quarter-hour the draw (S.7) and, while it cools
alone, the cooling curve; the last time it held the legionella
temperature."""
if temp_c is None or not facts.get("volume_l"):
return
d = self.tank.setdefault(cid, {"draw": {}, "cool": [], "ua": None, "legionella": None, "last": None,
"since": None})
d["since"] = d.get("since") or int(now)
lt = _num(facts.get("legionella_temp_c"))
if lt is not None and temp_c >= lt:
d["legionella"] = int(now)
slot = int(now // SLOT_S * SLOT_S)
cur = self._cur.get(("t", cid))
if cur is not None and cur["t"] != slot:
self._close_tank(cid, cur, facts)
cur = None
if cur is None:
cur = self._cur[("t", cid)] = {"t": slot, "temp": [], "heat": [], "room": room_c}
cur["temp"].append(float(temp_c))
cur["heat"].append(float(heat_w or 0.0))
cur["room"] = room_c
def _close_tank(self, cid, cur, facts):
d = self.tank[cid]
temp, heat = cur["temp"][-1], sum(cur["heat"]) / len(cur["heat"])
vol, cold = float(facts["volume_l"]), _num(facts.get("cold_water_c"))
ua = _num(facts.get("ua_w_k"))
last = d.get("last")
if cold is not None and ua and last and cur["t"] - last["t"] == SLOT_S:
e0, e1 = tank_energy_wh(vol, last["temp"], cold), tank_energy_wh(vol, temp, cold)
d["draw"][cur["t"]] = round(draw_w(e0, e1, heat, ua, vol, cur["room"], cold, SLOT_S / 3600.0), 1)
# cooling alone: heater off and the fall no faster than the draw threshold allows
k = _num(facts.get("draw_detect_k"))
alone = heat < 1.0 and k is not None and -k <= last["temp"] - temp <= k
runs = d["cool"]
if alone:
if runs and runs[-1] and runs[-1][-1][0] == last["t"]:
runs[-1].append([cur["t"], temp - cur["room"]])
else:
runs.append([[last["t"], last["temp"] - cur["room"]], [cur["t"], temp - cur["room"]]])
d["last"] = {"t": cur["t"], "temp": temp}
cut = cur["t"] - KEEP_S
d["draw"] = {t: v for t, v in d["draw"].items() if t >= cut}
d["cool"] = [r for r in d["cool"] if r and r[-1][0] >= cut]
def fit_tank(self, cid: str, facts: dict, params: dict) -> dict | None:
"""UA from the cooling runs, where the hours are enough: {"ua_w_k",
"hours", "label_ua_w_k", "kept": within the band of the label's, "at"}."""
d = self.tank.get(cid)
hours_min, band = _num(params.get(P_UA_HOURS)), params.get(P_UA_BAND)
if not d or hours_min is None or not facts.get("volume_l"):
return None
curves = [[((t - r[0][0]) / 3600.0, dlt) for t, dlt in r] for r in d["cool"] if len(r) >= 3]
got = fit_ua(curves, float(facts["volume_l"]))
if got is None or got[1] < hours_min:
return d.get("ua")
ua, hours = got
label = _num(facts.get("label_ua_w_k"))
lo, hi = _band(band)
kept = label is None or (lo is not None and lo * label <= ua <= hi * label)
d["ua"] = {"ua_w_k": round(ua, 3), "hours": round(hours, 1), "label_ua_w_k": label, "kept": bool(kept),
"at": int(self.clock())}
return d["ua"]
def tank_learnt(self, cid: str) -> dict:
"""What the plan takes from the box's fits: ua_w_k where kept; the
last legionella time; the draw history's days."""
d = self.tank.get(cid) or {}
out = {"legionella": d.get("legionella"), "ua": d.get("ua")}
if d.get("ua") and d["ua"].get("kept"):
out["ua_w_k"] = d["ua"]["ua_w_k"]
if d.get("draw"):
out["draw_days"] = round((max(d["draw"]) - min(d["draw"]) + SLOT_S) / 86400.0, 2)
return out
def draw_profile(self, cid: str, start: int, steps: int, tz: str, min_days: float | None) -> list[float] | None:
"""The box's own draw forecast: per step the mean of the same
quarter-hour of the week in the history, else of the day; None
before min_days of history (or without the parameter)."""
d = self.tank.get(cid) or {}
draw = d.get("draw") or {}
if min_days is None or not draw or (max(draw) - min(draw) + SLOT_S) / 86400.0 < min_days:
return None
zone = ZoneInfo(tz or "UTC")
def keys(t):
lt = datetime.fromtimestamp(t, timezone.utc).astimezone(zone)
q = lt.hour * 4 + lt.minute // 15
return lt.weekday() * 96 + q, q
week, day = {}, {}
for t, w in draw.items():
kw, kd = keys(t)
week.setdefault(kw, []).append(w)
day.setdefault(kd, []).append(w)
out = []
for k in range(steps):
kw, kd = keys(start + k * SLOT_S)
xs = week.get(kw) or day.get(kd) or []
out.append(sum(xs) / len(xs) if xs else 0.0)
return out
def draw_now(self, cid: str) -> float | None:
"""The last quarter-hour's draw (W; published as dhw.power)."""
draw = (self.tank.get(cid) or {}).get("draw") or {}
return draw[max(draw)] if draw else None
def save(self):
raw = {"battery": {k: {"slots": d["slots"], "fits": d.get("fits", []), "at": d.get("at", 0)}
for k, d in self.bat.items()},
"tank": self.tank}
tmp = self.path + ".tmp"
try:
with open(tmp, "w") as f:
json.dump(raw, f)
os.replace(tmp, self.path)
except OSError as e:
log.warning("storefit: %s", e)
def _band(raw) -> tuple[float | None, float | None]:
"""dhw.ua_fit_band: {"min": 0.5, "max": 3} (or [0.5, 3], or its JSON)."""
if isinstance(raw, str):
try:
raw = json.loads(raw)
except ValueError:
return None, None
if isinstance(raw, dict):
return _num(raw.get("min")), _num(raw.get("max"))
if isinstance(raw, (list, tuple)) and len(raw) == 2:
return _num(raw[0]), _num(raw[1])
return None, None
+20 -11
View File
@@ -6,7 +6,9 @@ the agent's SQLite (<state dir>/training.db), rolling.
slots 15-minute means per asset the trainer uses (load.power,
pv.power, the planned devices' power, room.<r>.temp, the
heating's power, the outdoor thermometer, the grid meter and
the battery), from the agent's own 1-minute windows: per slot
the battery; the carriers': heat.power, the presence sources
room.<r>.occupied and person.<slug>.home, the chargers' plug
state, 0/1 each), from the agent's own 1-minute windows: per slot
the mean of the windows' means, as the cloud's trainer reads
telemetry (time_bucket('15 minutes') of avg(mean)). A slot the
agent did not see can be filled once from Home Assistant's
@@ -43,8 +45,11 @@ KEEP_FC_DAYS = 14
# the assets the trainer reads (building/trainlib.py: SITE_SERIES, ROOM_INPUTS,
# CONTROLLED; trainer.load_site), and the meter for the member's net draw
ASSETS = {"load.power", "pv.power", "weather.outside_temp", "heat.power", "heatpump.power", "heating.power",
"ac.power", "cooling.power", "ev.power", "grid.import_power", "grid.export_power", "battery.power"}
ASSET_RE = re.compile(r"^(room\.[^.]+\.temp|(heatpump|heating|ac|cooling|ev)\.[0-9]+\.power)$")
"ac.power", "cooling.power", "ev.power", "grid.import_power", "grid.export_power", "battery.power",
"ev.plugged", "dhw.heater_power"}
# a room's temperature and presence, a person at home, a part's power, a charger's plug state and power
ASSET_RE = re.compile(r"^(room\.[^.]+\.(temp|occupied)|person\.[^.]+\.home|(heatpump|heating|ac|cooling|ev)\.[0-9]+\.power"
r"|ev\.[0-9]+\.plugged|ev[0-9]+\.(plugged|power))$")
OBSERVED_PREF = ("cloud", "ha") # an observed hour: DWD's (with irradiation) before HA's entity
FORECAST_PREF = ("ha", "cloud") # a forecast hour: as the box forecasts (localml.merge_hours: HA's first)
@@ -74,6 +79,9 @@ class Store:
self._ids = {name: i for i, name in self.db.execute("SELECT id, name FROM assets")}
self.db.execute("CREATE TABLE IF NOT EXISTS weather (end_ts INTEGER NOT NULL, kind TEXT NOT NULL, source TEXT NOT NULL, "
"solar REAL, cloud REAL, temp REAL, issued INTEGER, PRIMARY KEY (end_ts, kind, source))")
# the wind (m/s; the heat model's, methods.md B13), 2026-11-06: an older file gets the column
if "wind" not in {r[1] for r in self.db.execute("PRAGMA table_info(weather)")}:
self.db.execute("ALTER TABLE weather ADD COLUMN wind REAL")
self.db.execute("CREATE TABLE IF NOT EXISTS fc_slots (series TEXT NOT NULL, slot INTEGER NOT NULL, source TEXT NOT NULL, "
"value REAL NOT NULL, issued INTEGER NOT NULL, PRIMARY KEY (series, slot, source))")
self.db.execute("CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT NOT NULL)")
@@ -145,8 +153,8 @@ class Store:
# -- the weather -------------------------------------------------------------
def put_weather(self, kind: str, source: str, hours: list, issued: float | None = None) -> int:
"""Hourly records (pvforecast.Hour: end, solar_kwh_m2, cloud_pct,
temp_c). A forecast only for hours not over when it was made, the
newest such kept; an observation replaces what was there."""
temp_c, wind_ms). A forecast only for hours not over when it was
made, the newest such kept; an observation replaces what was there."""
rows = []
for h in hours:
end = int(h.end.timestamp())
@@ -156,10 +164,11 @@ class Store:
continue
if h.solar_kwh_m2 is None and h.cloud_pct is None and h.temp_c is None:
continue
rows.append((end, kind, source, h.solar_kwh_m2, h.cloud_pct, h.temp_c, int(issued) if issued else None))
rows.append((end, kind, source, h.solar_kwh_m2, h.cloud_pct, h.temp_c, int(issued) if issued else None,
getattr(h, "wind_ms", None)))
with self.lock:
self.db.executemany("INSERT OR REPLACE INTO weather (end_ts, kind, source, solar, cloud, temp, issued) "
"VALUES (?, ?, ?, ?, ?, ?, ?)", rows)
self.db.executemany("INSERT OR REPLACE INTO weather (end_ts, kind, source, solar, cloud, temp, issued, wind) "
"VALUES (?, ?, ?, ?, ?, ?, ?, ?)", rows)
return len(rows)
def weather_hours(self, since: int, until: int, kind: str) -> list:
@@ -168,13 +177,13 @@ class Store:
from .pvforecast import Hour
pref = OBSERVED_PREF if kind == "observed" else FORECAST_PREF
with self.lock:
rows = self.db.execute("SELECT end_ts, source, solar, cloud, temp FROM weather WHERE kind = ? AND end_ts > ? "
rows = self.db.execute("SELECT end_ts, source, solar, cloud, temp, wind FROM weather WHERE kind = ? AND end_ts > ? "
"AND end_ts <= ?", (kind, int(since), int(until))).fetchall()
by: dict[int, tuple] = {}
for end, src, sol, cl, tc in rows:
for end, src, sol, cl, tc, wd in rows:
rank = pref.index(src) if src in pref else len(pref)
if end not in by or rank < by[end][0]:
by[end] = (rank, sol, cl, tc)
by[end] = (rank, sol, cl, tc, wd)
return [Hour(datetime.fromtimestamp(e, timezone.utc), *by[e][1:]) for e in sorted(by)]
def training_hours(self, since: int, until: int) -> list:
+106 -10
View File
@@ -8,7 +8,9 @@ LightGBM (through fcmodels.fit), no database, no network.
train_series per series the challengers (how, gbm, pvphys) fitted on
the window before the held-out one, scored on it with the
model in force (the champion), the best put in force only
if it beats the champion (fcmodels.choose)
if it beats the champion (fcmodels.choose) and, in the
cloud, the hour-of-week baseline by a margin (Selection,
floored: methods.md B5.2)
fit_rooms each room's R and C (rcfit.py)
base_load load.power less the planned devices' power (methods.md A2-a)
held_out_weather, scored_on
@@ -18,6 +20,7 @@ LightGBM (through fcmodels.fit), no database, no network.
from __future__ import annotations
import logging
import math
from dataclasses import dataclass, field
from datetime import datetime
@@ -42,11 +45,73 @@ SITE_SERIES = {"load": "load.power", "pv": "pv.power"}
# metered: the coordinator's B7 uses it).
BASE = "base_load"
CONTROLLED_POWER = {"heating": ("heatpump.power", "heating.power"), "cooling": ("ac.power", "cooling.power"),
"ev": ("ev.power",)}
"ev": ("ev.power",), "dhw_tank": ("dhw.heater_power",)}
CONTROLLED = tuple(a for names in CONTROLLED_POWER.values() for a in names)
ROOM_INPUTS = ["weather.outside_temp", "heat.power", "heatpump.power"]
MIN_SLOTS = 16 # a series with less metered is not trained
SINCE_SERIES = ("pv",) # the series PV_METERED_SINCE cuts
PV_SERIES = ("pv",) # Selection.min_holdout_days_pv
@dataclass(frozen=True)
class Selection:
"""How the cloud's trainer chooses (methods.md B5.2): rows
"forecast.trainer.<name>" on the admin Parameters page (trainer.selection;
fleet migrations-teacher.sql seeds them). None (the box today): the old
rule, a held-out window of at least 6 hours and no floor.
min_holdout_days the held-out window is at least this long; a history
too short for it and a day to train on gets the
hour-of-week baseline only
min_holdout_days_pv the same for PV (its physical model starts from a
prior: a shorter window starves it less)
baseline_margin a model other than the hour-of-week goes in force
(and stays there) only when its held-out score is
below the baseline's by this fraction"""
min_holdout_days: float
min_holdout_days_pv: float
baseline_margin: float
def min_days(self, series: str) -> float:
return self.min_holdout_days_pv if series in PV_SERIES else self.min_holdout_days
def cut_for(t: np.ndarray, y: np.ndarray, sel: Selection | None = None, series: str = "") -> tuple[int, bool]:
"""Where the held-out window starts, as train_series cuts it, and
whether the history is too short for sel's minimum window and a day to
train on (fcmodels.MIN_GBM_SLOTS): then the old cut (a quarter, at
least 6 hours) and the baseline only."""
if sel is None:
return fcmodels.holdout(t, y), False
cut = fcmodels.holdout(t, y, min_days=sel.min_days(series))
if int((~np.isnan(y[:cut])).sum()) >= fcmodels.MIN_GBM_SLOTS:
return cut, False
return fcmodels.holdout(t, y), True
def floored(scores: dict, champ: float | None, champ_kind: str | None, sel: Selection | None
) -> tuple[dict, float | None, str]:
"""The baseline as a floor (methods.md B5.2): of the challengers'
held-out scores only the hour-of-week ("how") and those below it by
sel.baseline_margin may go in force; a model in force other than the
hour-of-week that is not below it so is no longer defended (champ None:
the best allowed replaces it); an hour-of-week in force is the baseline
itself (refitted on all the data, refit_how: in-sample on the window),
so it is judged by the challenger's score. Returns (scores allowed,
champ, note)."""
base = scores.get("how")
if sel is None or base is None or not math.isfinite(base):
return scores, champ, ""
if champ is not None and champ_kind == "how":
champ = base
bar = base * (1.0 - sel.baseline_margin)
ok = {k: v for k, v in scores.items() if k == "how" or (v is not None and math.isfinite(v) and v < bar)}
out = sorted(k for k, v in scores.items() if k not in ok and v is not None)
notes = [f"{', '.join(out)} not below the baseline by {100 * sel.baseline_margin:g} % (hour-of-week {base:.3g})"] if out else []
if champ is not None and champ_kind not in (None, "how") and not champ < bar:
notes.append(f"the model in force ({champ_kind} {champ:.3g}) is not below the baseline by "
f"{100 * sel.baseline_margin:g} %: replaced")
champ = None
return ok, champ, "; ".join(notes)
def cut_before(series: str, t: np.ndarray, y: np.ndarray, since: datetime | None) -> np.ndarray:
@@ -98,21 +163,23 @@ def wslice(w: fcmodels.Weather, sl: slice) -> fcmodels.Weather:
# ---- one series, champion against challengers -----------------------------------
def train_series(series: str, t: np.ndarray, y: np.ndarray, w: fcmodels.Weather, site: fcmodels.Site,
champion: dict | None, kinds=None, w_test: fcmodels.Weather | None = None) -> SeriesResult:
champion: dict | None, kinds=None, w_test: fcmodels.Weather | None = None,
sel: Selection | None = None) -> SeriesResult:
"""t, y: the series over the training weeks (and the week before, for
the lag), w: the weather on the same slots (observed: what the models
learn from). Fits each kind on the window before the held-out one,
scores it and the champion's params on the held-out window, picks
(fcmodels.choose). w_test: the weather the held-out window is scored
on, as it was forecast (methods.md B5-a: the published forecasts run on
forecasts, so the choice and the drift baseline should too); else w."""
forecasts, so the choice and the drift baseline should too); else w.
sel: the cloud's minimum window and baseline floor (Selection)."""
wt = w_test if w_test is not None else w
res = SeriesResult(series)
have = np.flatnonzero(~np.isnan(y))
if len(have) < MIN_SLOTS:
res.note = f"{len(have)} metered slots (at least {MIN_SLOTS})"
return res
cut = fcmodels.holdout(t, y)
cut, short = cut_for(t, y, sel, series)
first = int(have[0])
tr, te = slice(first, cut), slice(cut, len(t))
res.window = (int(t[first]), int(t[cut - 1]) + SLOT_S if cut > first else int(t[first]), int(t[cut]) if cut < len(t) else None,
@@ -123,6 +190,10 @@ def train_series(series: str, t: np.ndarray, y: np.ndarray, w: fcmodels.Weather,
res.note = f"too little data to hold a window out ({res.n_train} slots to train, {res.n_test} to test)"
return res
kinds = kinds or (["how", "gbm", "pvphys"] if series == "pv" else ["how", "gbm"])
if short:
kinds = [k for k in kinds if k == "how"]
res.note = (f"under {sel.min_days(series):g} days held out and a day to train on: "
"the hour-of-week baseline only")
hist_t, hist_y = t[:cut], y[:cut]
for kind in kinds:
try:
@@ -150,17 +221,41 @@ def train_series(series: str, t: np.ndarray, y: np.ndarray, w: fcmodels.Weather,
key = score_key(res)
scores = {r.kind: r.metrics.get(key) for r in res.runs if r.params}
champ = res.champion.get(key) if res.champion else None
scores, champ, fnote = floored(scores, champ, (champion or {}).get("kind"), sel)
if fnote:
res.note = (res.note + "; " if res.note else "") + fnote
best = fcmodels.choose(scores, champ)
if best is None and champion is None and scores:
if best is None and champ is None and scores:
best = min((k for k in scores if scores[k] is not None), key=lambda k: scores[k], default=None)
if best:
res.chosen = next(r for r in res.runs if r.kind == best and r.params)
res.chosen.chosen = True
elif champ is not None:
res.note = (res.note + "; " if res.note else "") + f"the model in force stays ({key} {champ:.3g})"
if sel is not None:
refit_how(res, series, t, y, w, site, first)
return res
def refit_how(res: SeriesResult, series: str, t: np.ndarray, y: np.ndarray, w: fcmodels.Weather,
site: fcmodels.Site, first: int) -> None:
"""The hour-of-week's params refitted on all the metered data, the
held-out window included (with a Selection: the window only chose it;
the profile has nothing to tune, and with days of history the last
days are much of what it knows). Its scores stay the window's."""
run = next((r for r in res.runs if r.kind == "how" and r.params), None)
if run is None:
return
try:
p = fcmodels.fit("how", series, t[first:], y[first:], wslice(w, slice(first, len(t))), site, t[:first], y[:first])
except Exception as e: # the window's fit stays
log.warning("refit how %s: %s", series, e)
return
if p is not None:
run.params = p
run.note = (run.note + "; " if run.note else "") + "refitted on all the data, the held-out window included"
def score_key(res: SeriesResult) -> str:
"""The metric a choice is made on: nMAE where the metered mean of the
held-out window is not ~0, else MAE (a held-out night of PV)."""
@@ -168,14 +263,14 @@ def score_key(res: SeriesResult) -> str:
def score_params(params: dict, series: str, t: np.ndarray, y: np.ndarray, w: fcmodels.Weather, site: fcmodels.Site,
w_test: fcmodels.Weather | None = None) -> dict | None:
w_test: fcmodels.Weather | None = None, sel: Selection | None = None) -> dict | None:
"""Another model's metrics on the same held-out window as train_series
cuts it (a benchmark: the cloud's model on the box), or None where it
cannot run or there is no window."""
have = np.flatnonzero(~np.isnan(y))
if len(have) < MIN_SLOTS:
return None
cut = fcmodels.holdout(t, y)
cut = cut_for(t, y, sel, series)[0]
wt = w_test if w_test is not None else w
te = slice(cut, len(t))
try:
@@ -257,14 +352,15 @@ def base_load(raw: dict[str, np.ndarray], kinds: set[str]) -> np.ndarray | None:
# ---- the weather the held-out window is scored on -----------------------------------
def held_out_weather(t: np.ndarray, y: np.ndarray, w: fcmodels.Weather, fc_hours: list, lat: float | None,
lon: float | None) -> tuple[fcmodels.Weather | None, str]:
lon: float | None, sel: Selection | None = None, series: str = ""
) -> tuple[fcmodels.Weather | None, str]:
"""The weather the held-out window (fcmodels.holdout, as train_series
cuts it) is scored on: the observed hours with every hour that was
forecast put in their place, and what that was (scored_on). None where
nothing was forecast: the observed weather."""
if not fc_hours or lat is None or lon is None or (~np.isnan(y)).sum() < MIN_SLOTS:
return None, scored_on(0, 0)
cut = fcmodels.holdout(t, y)
cut = cut_for(t, y, sel, series)[0]
test_ends = {(int(ts) // 3600 + 1) * 3600 for ts in t[cut:].tolist()}
fc = {int(h.end.timestamp()): h for h in fc_hours}
n_fc = len(test_ends & set(fc))