cantabile_edge, cantabile_modbus, cantabile_eebus 0.1.1289: full source
This commit is contained in:
1 parent
165dda4479
commit
05802d6f87
57 files changed
+5928
-232
No files matched your search
@@ -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
|
||||
Reference in new issue
Block a user