# 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 /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