From 05802d6f879349e32df828c22a0ca94db800306c Mon Sep 17 00:00:00 2001 From: "Setti Solutions S.R.L" Date: Sun, 8 Nov 2026 16:35:35 +0200 Subject: [PATCH] cantabile_edge, cantabile_modbus, cantabile_eebus 0.1.1289: full source --- README.md | 2 +- cantabile_edge/config.yaml | 2 +- cantabile_eebus/config.yaml | 2 +- cantabile_modbus/config.yaml | 2 +- src/edge/cantabile_edge/agent.py | 27 +- src/edge/cantabile_edge/backfill.py | 4 +- src/edge/cantabile_edge/boxtrain.py | 140 +++- src/edge/cantabile_edge/bundles.py | 91 ++- src/edge/cantabile_edge/controller.py | 84 ++- src/edge/cantabile_edge/controls.py | 435 +++++++++++- src/edge/cantabile_edge/costs.py | 41 +- src/edge/cantabile_edge/devpage.py | 231 ++++++- src/edge/cantabile_edge/devprofiles.py | 279 +++++++- src/edge/cantabile_edge/executor.py | 19 + src/edge/cantabile_edge/fcmodels.py | 9 +- src/edge/cantabile_edge/gridorder.py | 3 +- src/edge/cantabile_edge/guard.py | 1 + src/edge/cantabile_edge/i18n_de.py | 112 +++ src/edge/cantabile_edge/inputs.py | 530 +++++++++++++- src/edge/cantabile_edge/inventory.py | 51 +- src/edge/cantabile_edge/localml.py | 75 +- src/edge/cantabile_edge/mapping.py | 48 +- src/edge/cantabile_edge/names.py | 4 + src/edge/cantabile_edge/optimizer.py | 839 +++++++++++++++++++++-- src/edge/cantabile_edge/plansplit.py | 41 ++ src/edge/cantabile_edge/preferences.py | 72 +- src/edge/cantabile_edge/propose.py | 42 +- src/edge/cantabile_edge/storefit.py | 408 +++++++++++ src/edge/cantabile_edge/trainhist.py | 31 +- src/edge/cantabile_edge/trainlib.py | 116 +++- src/edge/link/main.go | 5 +- src/edge/link/sitecell_test.go | 39 ++ src/edge/tests/test_boxtrain_carriers.py | 185 +++++ src/edge/tests/test_carrier_inputs.py | 283 ++++++++ src/edge/tests/test_co2_plan.py | 121 ++++ src/edge/tests/test_devpage.py | 85 +++ src/edge/tests/test_devprofiles.py | 144 ++++ src/edge/tests/test_dhw.py | 132 ++++ src/edge/tests/test_heat_outlook.py | 227 ++++++ src/edge/tests/test_heating_oil.py | 84 +++ src/edge/tests/test_part_load.py | 147 ++++ src/edge/tests/test_plansplit.py | 49 ++ src/edge/tests/test_preferences.py | 29 + src/edge/tests/test_propose.py | 54 ++ src/edge/tests/test_storage.py | 313 +++++++++ src/edge/tests/test_tank_inputs.py | 338 +++++++++ src/edge/tests/test_thermostat.py | 2 +- src/profiles/README.md | 19 +- src/profiles/fronius-gen24.json | 6 +- src/profiles/ha-immersion-heater.json | 41 ++ src/profiles/ha-water-heater.json | 42 ++ src/profiles/ha-water-meter.json | 30 + src/profiles/hm8042-hybrid.json | 20 +- src/profiles/huawei-sun2000.json | 6 +- src/profiles/sma-sunny-boy.json | 6 +- src/profiles/solaredge-sunspec.json | 6 +- src/profiles/victron-gx.json | 6 +- 57 files changed, 5928 insertions(+), 232 deletions(-) create mode 100644 src/edge/cantabile_edge/plansplit.py create mode 100644 src/edge/cantabile_edge/storefit.py create mode 100644 src/edge/link/sitecell_test.go create mode 100644 src/edge/tests/test_boxtrain_carriers.py create mode 100644 src/edge/tests/test_carrier_inputs.py create mode 100644 src/edge/tests/test_co2_plan.py create mode 100644 src/edge/tests/test_dhw.py create mode 100644 src/edge/tests/test_heat_outlook.py create mode 100644 src/edge/tests/test_heating_oil.py create mode 100644 src/edge/tests/test_part_load.py create mode 100644 src/edge/tests/test_plansplit.py create mode 100644 src/edge/tests/test_storage.py create mode 100644 src/edge/tests/test_tank_inputs.py create mode 100644 src/profiles/ha-immersion-heater.json create mode 100644 src/profiles/ha-water-heater.json create mode 100644 src/profiles/ha-water-meter.json diff --git a/README.md b/README.md index b41a58d..65e0ae6 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ Settings → Add-ons → Add-on store → ⋮ → Repositories, add `https://git.setti.solutions/Daniel/cantabile-ha-addons`, then install the add-on. The Supervisor pulls the prebuilt images (`git.setti.solutions/daniel/cantabile-ha--:`, -named by `image:` in each `config.yaml`); this version: `0.1.1037`, arch amd64. +named by `image:` in each `config.yaml`); this version: `0.1.1289`, arch amd64. ## Layout diff --git a/cantabile_edge/config.yaml b/cantabile_edge/config.yaml index 3351ae0..3553c6a 100644 --- a/cantabile_edge/config.yaml +++ b/cantabile_edge/config.yaml @@ -3,7 +3,7 @@ # the Hub's, wrapped by addon-run (Dockerfile). The image is prebuilt, # per arch (README.md: building it from src/). name: Cantabile Edge Agent -version: "0.1.1037" +version: "0.1.1289" slug: cantabile_edge description: Plans your home's energy with Cantabile and, with your consent, runs the devices you choose. url: https://cantabile.cloud diff --git a/cantabile_eebus/config.yaml b/cantabile_eebus/config.yaml index 6d10ff0..c7c5e66 100644 --- a/cantabile_eebus/config.yaml +++ b/cantabile_eebus/config.yaml @@ -4,7 +4,7 @@ # Assistant that isn't a Cantabile Hub. Devices are paired on its page # (ingress), by their SKI. name: Cantabile EEBUS -version: "0.1.1037" +version: "0.1.1289" slug: cantabile_eebus description: Pairs with EEBUS devices (the grid operator's control box, heat pumps, wallboxes, inverters), shows them in Home Assistant under Cantabile's names and hands the grid operator's §14a limit to the Cantabile agent; every control with its protection. url: https://cantabile.cloud diff --git a/cantabile_modbus/config.yaml b/cantabile_modbus/config.yaml index e2cc264..417f491 100644 --- a/cantabile_modbus/config.yaml +++ b/cantabile_modbus/config.yaml @@ -4,7 +4,7 @@ # Home Assistant that isn't a Cantabile Hub. Devices come from the options; # the page (ingress) shows them and each control's protection. name: Cantabile Modbus bridge -version: "0.1.1037" +version: "0.1.1289" slug: cantabile_modbus description: Reads inverters, meters, relays and circuits by Cantabile's device profiles (Modbus, or Home Assistant's own entities) and shows them in Home Assistant, each control with its protection. url: https://cantabile.cloud diff --git a/src/edge/cantabile_edge/agent.py b/src/edge/cantabile_edge/agent.py index e2ed608..0941153 100644 --- a/src/edge/cantabile_edge/agent.py +++ b/src/edge/cantabile_edge/agent.py @@ -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) diff --git a/src/edge/cantabile_edge/backfill.py b/src/edge/cantabile_edge/backfill.py index f165e60..f733698 100644 --- a/src/edge/cantabile_edge/backfill.py +++ b/src/edge/cantabile_edge/backfill.py @@ -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 diff --git a/src/edge/cantabile_edge/boxtrain.py b/src/edge/cantabile_edge/boxtrain.py index c1b6eaf..29e0125 100644 --- a/src/edge/cantabile_edge/boxtrain.py +++ b/src/edge/cantabile_edge/boxtrain.py @@ -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..occupied and person..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..occupied, person..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., ev.., ev. (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 diff --git a/src/edge/cantabile_edge/bundles.py b/src/edge/cantabile_edge/bundles.py index 203dd63..966c950 100644 --- a/src/edge/cantabile_edge/bundles.py +++ b/src/edge/cantabile_edge/bundles.py @@ -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 diff --git a/src/edge/cantabile_edge/controller.py b/src/edge/cantabile_edge/controller.py index 60ba3f1..4a2997c 100644 --- a/src/edge/cantabile_edge/controller.py +++ b/src/edge/cantabile_edge/controller.py @@ -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..occupied, person..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 diff --git a/src/edge/cantabile_edge/controls.py b/src/edge/cantabile_edge/controls.py index 48f96d5..6555e7a 100644 --- a/src/edge/cantabile_edge/controls.py +++ b/src/edge/cantabile_edge/controls.py @@ -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_) 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_ # 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_ (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) diff --git a/src/edge/cantabile_edge/costs.py b/src/edge/cantabile_edge/costs.py index 74651b1..cf30142 100644 --- a/src/edge/cantabile_edge/costs.py +++ b/src/edge/cantabile_edge/costs.py @@ -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" + " ".join(notes) + "" return out diff --git a/src/edge/cantabile_edge/devpage.py b/src/edge/cantabile_edge/devpage.py index c076755..b28ab78 100644 --- a/src/edge/cantabile_edge/devpage.py +++ b/src/edge/cantabile_edge/devpage.py @@ -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'

{E(x)}

' 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'' + 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'
{E(T("Needed: the tank is not planned without it."))} ' + + E(", ".join(dict.fromkeys(words))) + ". " + E(T("Meanwhile it keeps its own thermostat.")) + "
") + elif x.get("refused") and x.get("why"): + body += f'
{E(T("Not planned: {why}.", why=x["why"]))}
' + 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'

{E(" · ".join(facts))}

' + 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'

{E(loss)}

' + opts = (f'' + + "".join(f'' + for k, w in TANK_HEATERS.items())) + inner = (hidden(id=d["id"]) + f'' + f'') + 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'
{device_state(d)}' + (f'{E(vals)}' if vals else "") + "
" + 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": diff --git a/src/edge/cantabile_edge/devprofiles.py b/src/edge/cantabile_edge/devprofiles.py index 3535e99..61cbac8 100644 --- a/src/edge/cantabile_edge/devprofiles.py +++ b/src/edge/cantabile_edge/devprofiles.py @@ -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..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:", "control:", # "entity:". 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]: diff --git a/src/edge/cantabile_edge/executor.py b/src/edge/cantabile_edge/executor.py index 1933fc7..5d7d81b 100644 --- a/src/edge/cantabile_edge/executor.py +++ b/src/edge/cantabile_edge/executor.py @@ -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: diff --git a/src/edge/cantabile_edge/fcmodels.py b/src/edge/cantabile_edge/fcmodels.py index d51d589..deb78cd 100644 --- a/src/edge/cantabile_edge/fcmodels.py +++ b/src/edge/cantabile_edge/fcmodels.py @@ -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)) diff --git a/src/edge/cantabile_edge/gridorder.py b/src/edge/cantabile_edge/gridorder.py index d333c89..4e3943f 100644 --- a/src/edge/cantabile_edge/gridorder.py +++ b/src/edge/cantabile_edge/gridorder.py @@ -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 diff --git a/src/edge/cantabile_edge/guard.py b/src/edge/cantabile_edge/guard.py index 25ea56e..4c1c8a4 100644 --- a/src/edge/cantabile_edge/guard.py +++ b/src/edge/cantabile_edge/guard.py @@ -69,6 +69,7 @@ SERVICES = { "cover": {"set_cover_position", "open_cover", "close_cover"}, "select": {"select_option"}, "input_select": {"select_option"}, + "water_heater": {"set_temperature"}, } diff --git a/src/edge/cantabile_edge/i18n_de.py b/src/edge/cantabile_edge/i18n_de.py index 83a5f34..20b07c3 100644 --- a/src/edge/cantabile_edge/i18n_de.py +++ b/src/edge/cantabile_edge/i18n_de.py @@ -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.", } diff --git a/src/edge/cantabile_edge/inputs.py b/src/edge/cantabile_edge/inputs.py index bd06bfa..b1088ce 100644 --- a/src/edge/cantabile_edge/inputs.py +++ b/src/edge/cantabile_edge/inputs.py @@ -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..occupied) or a person's home/away + (person..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..occupied and person..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]: diff --git a/src/edge/cantabile_edge/inventory.py b/src/edge/cantabile_edge/inventory.py index 4574de3..4b317c0 100644 --- a/src/edge/cantabile_edge/inventory.py +++ b/src/edge/cantabile_edge/inventory.py @@ -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: diff --git a/src/edge/cantabile_edge/localml.py b/src/edge/cantabile_edge/localml.py index ba3b6ac..3a615bc 100644 --- a/src/edge/cantabile_edge/localml.py +++ b/src/edge/cantabile_edge/localml.py @@ -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 diff --git a/src/edge/cantabile_edge/mapping.py b/src/edge/cantabile_edge/mapping.py index 152aa3d..a113005 100644 --- a/src/edge/cantabile_edge/mapping.py +++ b/src/edge/cantabile_edge/mapping.py @@ -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 diff --git a/src/edge/cantabile_edge/names.py b/src/edge/cantabile_edge/names.py index 4f0995a..7229b4e 100644 --- a/src/edge/cantabile_edge/names.py +++ b/src/edge/cantabile_edge/names.py @@ -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)", diff --git a/src/edge/cantabile_edge/optimizer.py b/src/edge/cantabile_edge/optimizer.py index bb96800..df14466 100644 --- a/src/edge/cantabile_edge/optimizer.py +++ b/src/edge/cantabile_edge/optimizer.py @@ -38,7 +38,14 @@ Device models (one function each, small and replaceable): the last charge free within its bounds, each kWh left worth V (end_value: the Parameters page's battery.end_value_pct of the mean feed-in price, under the cheapest import price; missing: - 0, noted in the plan's "notes") + 0, noted in the plan's "notes"); its idle loss (S.2): the + standby W taken from the cells while they hold charge (the grid + only as a valve), the cells' self-discharge as a factor per step + dhw_tank a hot-water tank's stored heat above the cold water (one node, + S.5): its standing loss UA (T - T_room), its heater's heat by + carrier, the hot water drawn (the dhw forecast), comfort between + min and max temperature, a legionella run where planned; the + plan's "storage" reports what each store loses heating a room's first-order thermal model (R in K/kW, C in kWh/K, the cooling outside temperature, heat from the device, from the sun through the room's covers, and the fit's internal gain and sun @@ -74,7 +81,14 @@ state["price_gas"] and state["price_heat"] per step, fleet heatprice.go): "params", from the tariff bundle: no flapping) The plan's cost then counts gas and heat too (gas_eur, heat_eur). A control whose price or facts are missing never reaches the plan (inputs.py -heating_refusal: refused with the reason). +heating_refusal: refused with the reason). A boiler's gas follows its +part-load curve (E6.4: the mapping's boiler_type or part_load_curve; LP +segments where convex, binaries where not); a source's heat and its cost +are HeatSupply's, the heat no model decides (the space heat where no room +is planned, the hot water drawn) heat_demand's: the heat outlook (A2.16), a +fixed labelled term of the cost (cost_parts.heat_outlook_eur). CO2 (A2.15): +the Parameters page's co2.planner_eur_per_t on the grid import, gas and +district heat at the tariff bundle's factors; the plan reports co2_kg. The grid operator's limit (gridorder.py, state["grid_order"]: §14a through the EEBUS bridge): the controllable consumers may draw at most @@ -124,8 +138,10 @@ from zoneinfo import ZoneInfo import highspy from highspy.highs import highs_linear_expression as Lin -from .controls import cop_at, ev_volts +from .controls import ERP_TEST_DT_K, HOURS_PER_MONTH, cop_at, ev_volts, gas_segments, part_load, relative_efficiency from .evphases import words as phase_words +from .storefit import WATER_WH_PER_L_K +from .plansplit import saving_parts PENALTY_LIMIT = 5.0 # EUR per unit and step across a floor or limit (K, % of a battery, kWh) COMFORT_EUR_KH = 2.0 # EUR per K and hour below (heating) or above (cooling) the comfort target @@ -156,6 +172,19 @@ END_VALUE_GAP_CT = 0.5 # ct/kWh: the end value at least this far below the ch GRID_MAX_W = 43470.0 # W: the site's connection when the state does not say (state["grid_max_w"], # config grid_max_w): a German house connection's usual 63 A main fuse, # 3 x 230 V x 63 A +CO2_KEY = "co2.planner_eur_per_t" # the Parameters page's (via the tariff bundle's params): EUR per t of CO2 the + # plan weighs on its grid import, gas and district heat (0: cost only) +CO2_BASIS_KEY = "co2.basis" # the Parameters page's: direct | lifecycle (the plan reports which) +LEGIONELLA_EVERY = 4 # steps: a tank's legionella run is checked on the hour (ENG: a binary per hour, not + # per step: solve time) +RELAY_STEPS = 4 # steps: a tank element's relay is on or off for a whole hour in the plan (ENG: solve + # time; the guard's min_switch_s keeps it from cycling faster anyway) +STORE_TIE_EUR_WH = 1e-8 # EUR per Wh held above the floor per step, only for a battery with a standby (ENG: a + # tie-break, 0.1 ct per kWh and day: with a flat price, charging the standby ahead or + # step by step costs the same; the plan holds the floor instead of a buffer) +STANDBY_GRID_EUR_KWH = 1.0 # EUR per kWh of a battery's standby drawn from the grid where the battery could give it + # (ENG, A2.3 S.2: above any price, so the standby comes from the cells while they hold + # charge, as it does physically; the grid only where the battery cannot: a valve) class Model: @@ -172,6 +201,103 @@ class Model: self.priced = s["priced"] if "priced" in s else ( (s.get("prices") or {}).get("status", "tariff") != "none" and all(v is not None for v in (s.get("price_import") or [None])[:self.T])) + self.notes: list[str] = [] # what the plan assumed or left out, quietly (no alarm) + self.co2w = self.co2_weight() + + def note(self, text: str): + if text and text not in self.notes: + self.notes.append(text) + + # -- CO2 (docs/methods.md A2.15) ------------------------------------------- + def co2_weight(self) -> float: + """w, EUR per t of CO2 in the objective: the Parameters page's + co2.planner_eur_per_t (the tariff bundle's params); 0 (cost only) + without a tariff, without the parameter (noted) or without any CO2 + factor in the bundle (noted while w > 0; the parameter's absence is + noted where the bundle has factors to weigh).""" + if not self.priced: + return 0.0 + raw = (self.s.get("params") or {}).get(CO2_KEY) + try: + w = float(raw) + except (TypeError, ValueError): + w = None + if w is None or not math.isfinite(w) or w < 0: + if self.s.get("co2"): + self.note(f"{CO2_KEY} missing: CO2 not weighed (cost only)") + return 0.0 + if w > 0 and not self.s.get("co2"): + self.note("no CO2 factors in the tariff: CO2 not weighed") + return 0.0 + return w + + def co2_factor(self, carrier: str, t: int) -> float | None: + """g CO2 per kWh of a carrier in step t (the bundle's), or None.""" + c = self.s.get("co2") or {} + if carrier == "electricity": + xs = c.get("electricity") or [] + v = xs[t] if t < len(xs) else None + else: + v = c.get(carrier) + return float(v) if isinstance(v, (int, float)) and math.isfinite(v) and v >= 0 else None + + def co2_wh(self, carrier: str, t: int) -> float: + """The CO2 term per W held for one step of a carrier's input: w x + f x dt / 1000 kWh / 1e6 g per t (A2.15); 0 with no weight, and 0 + where the carrier has no factor (that carrier unweighed, noted).""" + if not self.co2w: + return 0.0 + f = self.co2_factor(carrier, t) + if f is None: + self.note(f"no CO2 factor for {carrier}" + (" in some steps" if carrier == "electricity" else "") + + f": {carrier} unweighed there") + return 0.0 + return self.co2w * f * self.dt / 1000.0 / 1e6 + + # -- a boiler's part load (docs/methods.md E6.4) ---------------------------------- + def boiler_curve(self, cid: str, p: dict, qmax: float, eff: float) -> dict: + """A boiler's gas against its heat: its part-load curve (the + mapping's part_load_curve, else the Parameters page's + boiler.part_load_) as segments, the full-load point + for an on/off one; none: one constant efficiency (noted). {segs, + convex, gmax (gas W at full heat), full (the full-load efficiency)}.""" + pts, why = part_load(p, self.s.get("params")) + if pts is None or qmax <= 0: + why = why if pts is None else "no max_heat_w: one constant efficiency" + self.note(f"{cid}: {why}") + return {"segs": None, "convex": True, "gmax": qmax / eff if eff else 0.0, "full": eff, "from": why} + segs, convex, capped = gas_segments(qmax, eff, pts) + if capped: + self.note(f"{cid}: the part-load efficiency held at 1 (no more heat than the gas's Hs)") + full = min(1.0, eff * relative_efficiency(pts, 1.0)) + return {"segs": segs, "convex": convex, "gmax": sum(dq * sl for dq, sl in segs), "full": full, "from": why} + + def boiler_step(self, bc: dict, cost: float, switched: bool, qmax: float) -> tuple: + """One step's gas input of a boiler and its heat terms ((W of heat + per W of the variable, variable), ...): on its curve (convex: an LP's + segments; efficiency rising with load: one binary per segment beyond + the first, so a segment is used only once the one before is full), + at its full-load point when switched on/off, else at the one + efficiency. (gas var, terms).""" + if switched: + gmax = qmax / bc["full"] if bc["full"] else 0.0 + u = self.var(0.0, 1.0, integer=True) + pg = self.var(0.0, gmax, cost=cost) + self.h.addConstr(pg - gmax * u == 0) + return pg, [(bc["full"], pg)] + if not bc["segs"]: + pg = self.var(0.0, bc["gmax"], cost=cost) + return pg, [(bc["full"], pg)] + segs = bc["segs"] + ds = [self.var(0.0, dq) for dq, _ in segs] + pg = self.var(0.0, bc["gmax"], cost=cost) + self.h.addConstr(pg - sum((sl * d for (_, sl), d in zip(segs, ds)), start=Lin()) == 0) + if not bc["convex"]: + for k in range(1, len(segs)): + y = self.var(0.0, 1.0, integer=True) + self.h.addConstr(ds[k] - segs[k][0] * y <= 0) + self.h.addConstr(ds[k - 1] - segs[k - 1][0] * y >= 0) + return pg, [(1.0, d) for d in ds] def var(self, lo=0.0, hi=highspy.kHighsInf, cost=0.0, integer=False): v = self.h.addVariable(lb=lo, ub=hi, type=highspy.HighsVarType.kInteger if integer else @@ -219,7 +345,8 @@ class Model: net = s["load_w"][t] - s["pv_w"][t] hi_in, hi_out = max(cap, net), max(cap, -net) if self.priced: - gi = self.var(0.0, hi_in, cost=self.eur_wh(t, s["price_import"][t])) + # the import's price, and its CO2 at the weight (A2.15; no credit for export) + gi = self.var(0.0, hi_in, cost=self.eur_wh(t, s["price_import"][t]) + self.co2_wh("electricity", t)) # an unpriced export (None) carries no value: coefficient 0 go = self.var(0.0, hi_out, cost=-self.eur_wh(t, s["price_export"][t])) else: @@ -402,6 +529,15 @@ class Model: soc, prev, ch, dis = [], soc0, [], [] pref = d.get("pref") # the owner's reserve per step (preferences.py) floors = [] + # the idle loss (A2.3, S.2): the system's standby p0 (W) from the battery while it holds charge + # (lb), from the grid only where it cannot (lg: a valve at STANDBY_GRID_EUR_KWH, into the house's + # balance only where the mapping says the load does not hold it); the cells' self-discharge as + # phi per step. Facts with their source (inputs.model_state); none: 0 (noted there) + p0 = max(0.0, float(p.get("standby_w") or 0.0)) + lam_h = max(0.0, float(p.get("self_discharge_pct_month") or 0.0)) / 100.0 / HOURS_PER_MONTH + phi = (1.0 - lam_h) ** self.dt + grid_side = p.get("standby_in_load") is False + lbs, lgs = [], [] for t in range(self.T): lo_t = lo_pct if pref and not (pref.get("off") is not None and pref["group"][t] == pref["off"]): @@ -412,10 +548,20 @@ class Model: z = self.var(0.0, 1.0, integer=True) self.h.addConstr(c - max_ch * z <= 0) self.h.addConstr(x + max_dis * z <= max_dis) - e = self.var(0.0, cap) + e = self.var(0.0, cap, cost=STORE_TIE_EUR_WH if p0 > 0 else 0.0) under = self.var(cost=PENALTY_LIMIT / cap * 100) # Wh below the floor, per % of the battery over = self.var(cost=PENALTY_LIMIT / cap * 100) - self.h.addConstr(e - prev - self.dt * eff * c + self.dt / eff * x == 0) + if p0 > 0: + lb = self.var(0.0, p0) + lg = self.var(0.0, p0, cost=STANDBY_GRID_EUR_KWH * self.dt / 1000.0) + self.h.addConstr(lb + lg == p0) + if grid_side: + self.flows[t].append((-1, lg)) + self.h.addConstr(e - phi * prev - self.dt * eff * c + self.dt / eff * x + self.dt * lb == 0) + lbs.append(lb) + lgs.append(lg) + else: + self.h.addConstr(e - phi * prev - self.dt * eff * c + self.dt / eff * x == 0) self.h.addConstr(e + under >= lo_t / 100.0 * cap) self.h.addConstr(e - over <= hi_pct / 100.0 * cap) self.flows[t] += [(-1, c), (1, x)] @@ -432,7 +578,9 @@ class Model: self.smooth([c - x for c, x in zip(ch, dis)]) self.devices[d["id"]] = ("battery", {"ch": ch, "dis": dis, "soc": soc, "cap": cap, "max_dis": max_dis, "floor_wh": lo_pct / 100.0 * cap, "floors": floors, - "max_ch": max_ch, "eff": eff, "soc0": soc0, "hi_wh": hi_pct / 100.0 * cap}) + "max_ch": max_ch, "eff": eff, "soc0": soc0, "hi_wh": hi_pct / 100.0 * cap, + "p0": p0, "phi": phi, "lam_h": lam_h, "lb": lbs, "lg": lgs, + "grid_side": grid_side, "in_load": p.get("standby_in_load")}) def room(self, d, cooling: bool, gains): p, st, b = d["params"], d["state"], d["bounds"] @@ -455,10 +603,11 @@ class Model: # facts and parameters, never defaults: inputs.heating_refusal left out a control without them eff = float(p["boiler_efficiency"]) if src in ("boiler", "hybrid") else None qmax = float(p["max_heat_w"]) if src in ("boiler", "hybrid", "district") else 0.0 - gmax = qmax / eff if eff else 0.0 + # a boiler's gas or a heat station's heat against the room's heat, at its carrier's price and CO2 (E6) + sup = HeatSupply(self, d["id"], p, "district" if src == "district" else "boiler", + switched and src == "boiler") if src in ("boiler", "hybrid", "district") else None + gmax = sup.gmax if sup and src != "district" else 0.0 switch_eur = float((self.s.get("params") or {})["heat.hybrid_switch_eur"]) if src == "hybrid" else 0.0 - gas = self.s.get("price_gas") or [None] * self.T - dhp = self.s.get("price_heat") or [None] * self.T t_out = self.s["t_out"] cops = [cop_at(p, t_out[t]) if p.get("cop_curve") else cop for t in range(self.T)] els, gss, dhs, prev_u = [], [], [], None @@ -483,17 +632,11 @@ class Model: self.flows[t].append((-1, pw)) terms.append((cops[t], pw)) if src in ("boiler", "hybrid"): - cost = self.eur_wh(t, gas[t]) # the gas price per W of gas for the step - if switched and src == "boiler": - u = self.var(0.0, 1.0, integer=True) - pg = self.var(0.0, gmax, cost=cost) - self.h.addConstr(pg - gmax * u == 0) - else: - pg = self.var(0.0, gmax, cost=cost) - terms.append((eff, pg)) + pg, bterms = sup.variables(t) + terms += bterms if src == "district": - ph = self.var(0.0, qmax, cost=self.eur_wh(t, dhp[t])) - terms.append((1.0, ph)) + ph, hterms = sup.variables(t) + terms += hterms if src == "hybrid": hu = self.var(0.0, 1.0, integer=True) # 1: the heat pump, 0: the boiler self.h.addConstr(pw - pmax * hu <= 0) @@ -566,6 +709,7 @@ class Model: # gas, district: their inputs; heat: per step the heat terms self.devices[d["id"]] = ("cooling" if cooling else "heating", {"temp": temps, "power": els, "gas": gss, "district": dhs, "src": src, + "fuel": boiler_fuel(p) if src in ("boiler", "hybrid") else None, "cops": cops, "eff": eff, "pmax": {"electric": pmax, "heat_pump": pmax, "hybrid": pmax, "boiler": gmax, "district": qmax}[src], "switched": switched, @@ -584,22 +728,38 @@ class Model: def ev(self, d): p, st, b = d["params"], d["state"], d["bounds"] - if not st.get("connected"): + pref = d.get("pref") # the owner's ready-by (preferences.py) + # not plugged in: nothing, or the session forecast's next session as an + # expected load (inputs.ev_session; no owner's ready-by): the plan sees + # it (prices, the battery), nothing acts on it (_entry: no commands) + exp = st.get("expected") if not st.get("connected") and not pref else None + if not st.get("connected") and not (exp and exp.get("need_wh") is not None and + int(exp.get("to_step", 0)) > int(exp.get("from_step", 0))): self.devices[d["id"]] = ("ev", None) return volts = ev_volts(p, "plan") imax = min(float(p["max_current_a"]), b["current_a"][1]) imin = max(float(p["min_current_a"]), b["current_a"][0]) - dep = departure_step(self.s, str(st.get("departure") or p["departure"])) - need = float(st["need_wh"]) if st.get("need_wh") is not None else float(p["need_wh"]) - pref = d.get("pref") # the owner's ready-by (preferences.py) + sess = st.get("session") or {} # the session forecast's, where the car says none + first = 0 + if exp: + first, dep, need = int(exp["from_step"]), int(exp["to_step"]), float(exp["need_wh"]) + else: + if st.get("departure"): + dep = departure_step(self.s, str(st["departure"])) + elif sess.get("dep_step") is not None: + dep = min(self.T, int(sess["dep_step"])) + else: + dep = departure_step(self.s, str(p["departure"])) + need = float(st["need_wh"]) if st.get("need_wh") is not None else \ + float(sess["need_wh"]) if sess.get("need_wh") is not None else float(p["need_wh"]) if pref: dep, need = int(pref["dep_step"]), float(pref["need_wh"]) if pref.get("off"): need = 0.0 powers, total = [], Lin() for t in range(self.T): - if t >= dep or imax < imin: + if t < first or t >= dep or imax < imin: powers.append(None) continue y = self.var(0.0, 1.0, integer=True) @@ -624,8 +784,116 @@ class Model: self.smooth([p for p in powers if p is not None]) self.devices[d["id"]] = ("ev", {"power": powers, "volts": volts, "dep": dep, "pmax": imax * volts if imax >= imin else 0.0, "need": need, - # the ready-by and the energy known (shift_envelope): not the defaults - "known": ev_known(st, pref)}) + # the ready-by and the energy known (shift_envelope): not the + # defaults, not a forecast session (expected: not plugged in yet) + "known": ev_known(st, pref) and not exp, "expected": bool(exp)}) + + def dhw_tank(self, d): + """A hot-water tank (docs/methods.md A13; design S.4-S.6): its stored + heat above the cold water E_t = phi E_(t-1) + dt (Q_t - D_t + u_t - P0) + with phi = 1 - UA dt / (c_w V), P0 = UA (T_cw - T_room) (the standing + loss UA (T - T_room) in E); Q its heater's heat (an element's W, a + heat pump's COP x W, a boiler's gas by its efficiency, district heat); + D the hot water drawn (the dhw forecast); u the draw it could not + give (at dhw.short_eur_kwh: never infeasible). Between the comfort's + E_min (min_temp_c; a Großanlage at least the law's 60 °C, soft here, + hard in the guard) and E_max (max_temp_c, the device's own maximum). + A legionella run where the mapping says "plan" and it falls due in + the horizon: one step at legionella_temp_c, the cheapest (binaries + over the steps before its due time).""" + p, st, b = d["params"], d["state"], d["bounds"] + cw = WATER_WH_PER_L_K * float(p["volume_l"]) # Wh per K + t_cw = float(p["cold_water_c"]) + room = st.get("room_c") if st.get("room_c") is not None else float(p["room_temp_c"]) + ua = float(p["ua_w_k"]) + phi = 1.0 - ua * self.dt / cw + p0 = ua * (t_cw - room) + lo_c = float(p["min_temp_c"]) + if p.get("law_floor_c") is not None: + lo_c = max(lo_c, float(p["law_floor_c"])) + hi_c = min(float(p["max_temp_c"]), b["temp_c"][1]) + lo_c = min(lo_c, hi_c) + emin, emax = cw * (lo_c - t_cw), cw * (hi_c - t_cw) + e0 = cw * (float(st["temp_c"]) - t_cw) + short = float(p["short_eur_kwh"]) / 1000.0 * self.dt # EUR per W short for a step + draw = [max(0.0, float(v)) for v in (d.get("draw_w") or [0.0] * self.T)[:self.T]] + draw += [0.0] * (self.T - len(draw)) + heater = str(p["heater"]) + switched = heater == "element" and not ({"water_heater", "power"} & set(d.get("channels") or [])) + pmax = float(p.get("max_power_w") or 0.0) if heater in ("element", "heat_pump") else 0.0 + cops = [1.0] * self.T + if heater == "heat_pump": + cops = [cop_at(p, self.s["t_out"][t]) if p.get("cop_curve") else float(p["cop"]) for t in range(self.T)] + sup = HeatSupply(self, d["id"], p, heater) if heater in ("boiler", "district") else None + shared = None + if heater == "heat_pump" and p.get("shares_with"): + kind, rv = self.devices.get(p["shares_with"], (None, None)) + if kind == "heating" and rv and rv.get("power"): + shared = (rv["power"], rv["pmax"]) + else: + self.note(f"{d['id']}: its heat pump's room control {p['shares_with']} is not planned: " + "the tank's heat pump planned alone") + # legionella (the mapping's "plan"): the due step from its last run (inputs: storefit's) + leg = st.get("legionella") or {} + e_leg, window = None, [] + if str(p.get("legionella") or "device") == "plan" and leg.get("due_step") is not None: + t_leg = float(p["legionella_temp_c"]) + if t_leg > hi_c + 1e-9: + self.note(f"{d['id']}: legionella run at {t_leg:g} °C above the tank's maximum {hi_c:g} °C: not planned") + else: + e_leg = cw * (t_leg - t_cw) + due = int(leg["due_step"]) + window = list(range(0, min(self.T, due if due > 0 else self.T))) + es, pws, gss, dhs, heats, unmet, prev = [], [], [], [], [], [], e0 + lsum = Lin() + for t in range(self.T): + terms, pw, pg, ph = [], None, None, None + if heater in ("element", "heat_pump"): + pw = self.var(0.0, pmax, cost=self.use_cost(t)) + if switched: + # a relay: on or off for a whole hour (RELAY_STEPS: 48 binaries, not 192) + if t % RELAY_STEPS == 0: + y = self.var(0.0, 1.0, integer=True) + self.h.addConstr(pw - pmax * y == 0) + self.flows[t].append((-1, pw)) + terms.append((cops[t], pw)) + if shared is not None and shared[0][t] is not None: + self.h.addConstr(pw + shared[0][t] <= max(shared[1], pmax)) + elif heater == "boiler": + pg, terms = sup.variables(t) + else: + ph, terms = sup.variables(t) + q = sum((k * v for k, v in terms), start=Lin()) + # never below the cold water's (or a colder room's) temperature + e_lb = min(0.0, e0, cw * (room - t_cw)) + e = self.var(e_lb, highspy.kHighsInf) + u = self.var(0.0, max(draw[t], 0.0), cost=short) # the draw not given + w = self.var(cost=short) # Wh under the comfort + over = self.var(cost=PENALTY_LIMIT / cw) # Wh above the maximum (a hot start) + self.h.addConstr(e - phi * prev - self.dt * q - self.dt * u == -self.dt * (draw[t] + p0)) + self.h.addConstr(e + w >= emin) + self.h.addConstr(e - over <= emax) + if e_leg is not None and t in window and t % LEGIONELLA_EVERY == 0: + lt = self.var(0.0, 1.0, integer=True) + self.h.addConstr(e - (e_leg - e_lb) * lt >= e_lb) + lsum += lt + es.append(e) + pws.append(pw) + gss.append(pg) + dhs.append(ph) + heats.append(terms) + unmet.append(u) + prev = e + if e_leg is not None and window: + miss = self.var(cost=PENALTY_LIMIT) + self.h.addConstr(lsum + miss >= 1) + self.smooth([v for v in (pws if heater in ("element", "heat_pump") else gss if heater == "boiler" else dhs)]) + self.devices[d["id"]] = ("dhw_tank", { + "e": es, "power": pws, "gas": gss, "district": dhs, "heat": heats, "unmet": unmet, "draw": draw, + "cw": cw, "t_cw": t_cw, "room": room, "ua": ua, "phi": phi, "p0": p0, "e0": e0, "emin": emin, "emax": emax, + "lo_c": lo_c, "hi_c": hi_c, "heater": heater, "pmax": pmax, "cops": cops, "switched": switched, + "eff": sup.curve["full"] if heater == "boiler" else None, "e_leg": e_leg, "window": window, + "src": "electric" if heater in ("element", "heat_pump") else heater}) def cover(self, d, room_ids): p, b = d["params"], d["bounds"] @@ -679,6 +947,9 @@ class Model: self.room(d, k == "cooling", gains) elif k == "ev": self.ev(d) + for d in s["devices"]: + if d["kind"] == "dhw_tank": + self.dhw_tank(d) # after the rooms: a heat pump it shares with is planned self.building() self.battery_plan() self.grid_order() @@ -697,6 +968,111 @@ class Model: return self.h.modelStatusToString(status) +# -- heat: what is demanded, and what a source's heat costs (docs/methods.md A2.16, E6) ------- +# Two clean halves, so a store can later sit between them (backlog 329: the +# hot-water tank, demand -> tank -> heater): heat_demand says what heat a +# site needs per step that no model in the plan decides; HeatSupply says +# what one W of heat from a source takes as input and costs (price, CO2, +# part load). Today the demand is met when it is demanded: +# HeatSupply.delivered is the one place that says so. +HEAT_DEMANDS = {"space": "heat_w", "dhw": "dhw_w"} # the model bundle's series (B13, B16) + + +def heat_demand(s: dict, kind: str, steps: int) -> list[float] | None: + """The heat (W per step) of a demand the plan takes as it comes: "space" + the site's heat forecast (heat_w), "dhw" its hot water drawn (dhw_w); + None without a forecast.""" + xs = s.get(HEAT_DEMANDS[kind]) + if not xs: + return None + return [max(0.0, float(v)) for v in xs[:steps]] + + +class HeatSupply: + """One heat source's heat in the plan (E6): a boiler's gas (its part + load, E6.4; on/off at its full-load point when switched) or district + heat, each W of input at its carrier's price and CO2 (A2.15). facts: + boiler_efficiency, max_heat_w, boiler_type, part_load_curve (a heating + control's params, or the site's: inputs.heat_site). variables(t): its + input and heat as the MILP's (a room's heat); delivered(demand): a fixed + heat as numbers (the heat outlook).""" + + def __init__(self, m: "Model", cid: str, facts: dict, source: str, switched: bool = False): + self.m, self.cid, self.source, self.switched = m, cid, source, switched + # a boiler's fuel: gas or heating oil (the control's "fuel", E15); district heat: heat + self.carrier = boiler_fuel(facts) if source == "boiler" else "heat" + self.prices = (m.s.get("price_" + self.carrier) or [None] * m.T) + self.qmax = float(facts.get("max_heat_w") or 0.0) + self.eff = float(facts["boiler_efficiency"]) if source == "boiler" else None + self.curve = m.boiler_curve(cid, facts, self.qmax, self.eff) if source == "boiler" else None + + @property + def gmax(self) -> float: + """The most input (W): a boiler's gas at full heat, a heat station's heat.""" + if self.source != "boiler": + return self.qmax + return self.qmax / self.curve["full"] if self.switched else self.curve["gmax"] + + def cost_wh(self, t: int) -> float: + """EUR per W of input held for step t: the carrier's price and its CO2 at the weight.""" + p = self.prices[t] if t < len(self.prices) else None + return self.m.eur_wh(t, p) + self.m.co2_wh(self.carrier, t) + + def variables(self, t: int) -> tuple: + """Step t's input variable and its heat terms ((W of heat per W of + the variable, variable), ...) for the MILP.""" + if self.source == "boiler": + return self.m.boiler_step(self.curve, self.cost_wh(t), self.switched, self.qmax) + ph = self.m.var(0.0, self.qmax, cost=self.cost_wh(t)) + return ph, [(1.0, ph)] + + def input_w(self, heat_w: float) -> float: + """The input (W) for a heat (W): district heat as it is; a boiler's + gas on its curve (beyond its most heat at the full-load efficiency), + else at its one efficiency.""" + q = max(0.0, heat_w) + if self.source != "boiler": + return q + segs = self.curve["segs"] + if not segs: + return q / self.eff + g, left = 0.0, q + for dq, sl in segs: + take = min(left, dq) + g, left = g + take * sl, left - take + return g + left / self.curve["full"] + + def delivered(self, demand: list[float]) -> dict: + """A demand met when it is demanded (the one place it is said: the + heat in step t is the demand of step t), as numbers: per step the + heat and the input (W), and in all the kWh, the cost at the + carrier's price (steps without one: unpriced_kwh) and the CO2 at its + factor (None where a step has none).""" + m = self.m + heat = [max(0.0, q) for q in demand[:m.T]] + inputs = [self.input_w(q) for q in heat] + eur = unpriced = kg = 0.0 + no_factor = False + for t, w in enumerate(inputs): + kwh = w * m.dt / 1000.0 + p = self.prices[t] if t < len(self.prices) else None + if p is None: + unpriced += kwh + else: + eur += kwh * p / 100.0 + f = m.co2_factor(self.carrier, t) + if f is None: + no_factor = no_factor or kwh > 0 + else: + kg += kwh * f / 1000.0 + out = {"heat_w": [round(w) for w in heat], "input_w": [round(w) for w in inputs], + "heat_kwh": round(sum(heat) * m.dt / 1000.0, 2), "input_kwh": round(sum(inputs) * m.dt / 1000.0, 2), + "eur": round(eur, 2), "co2_kg": None if no_factor else round(kg, 2)} + if unpriced: + out["unpriced_kwh"] = round(unpriced, 2) + return out + + def ev_known(st: dict, pref: dict | None) -> bool: """A car's ready-by and energy are facts: the ready-by the owner's preference or the car's (its charger's departure entity), the energy @@ -733,8 +1109,17 @@ def _prepare(s: dict) -> dict: status = (s.get("prices") or {}).get("status", "tariff") # gas and heat: a boiler's or district heat's steps only while their price lasts n = s["steps"] - srcs = {str((d.get("params") or {}).get("heat_source") or "electric") for d in s.get("devices") or [] if d["kind"] == "heating"} - for key, need in (("price_gas", {"boiler", "hybrid"}), ("price_heat", {"district"})): + srcs = {str((d.get("params") or {}).get("heat_source") or "electric") for d in s.get("devices") or [] + if d["kind"] == "heating"} + fuels = {boiler_fuel(d.get("params") or {}) for d in s.get("devices") or [] + if d["kind"] == "heating" and str((d.get("params") or {}).get("heat_source") or "") in ("boiler", "hybrid")} + # a hot-water tank's heater: a tank's boiler is on gas (inputs.tank_refusal asks for the gas price) + tanks = {str((d.get("params") or {}).get("heater") or "") for d in s.get("devices") or [] if d["kind"] == "dhw_tank"} + srcs |= tanks + if "boiler" in tanks: + fuels.add("gas") + for key, need in (("price_gas", {"boiler", "hybrid"} if "gas" in fuels else set()), + ("price_oil", {"boiler", "hybrid"} if "oil" in fuels else set()), ("price_heat", {"district"})): xs = s.get(key) or [] if srcs & need and xs: n = min(n, next((k for k, v in enumerate(xs) if v is None), len(xs))) @@ -792,9 +1177,21 @@ def plan(s: dict, time_limit: float = 30.0) -> dict: market = market_plan(s, m, x) energy = energy_of(s, m, x, market) heat_cost = carrier_costs(s, m, x) + # the heat no room model plans (a district-heated or gas home): its expected cost, a fixed term (A2.16) + outlook = heat_outlook(s, m) + parts = None if energy is not None: - energy += heat_cost["gas_eur"] + heat_cost["heat_eur"] + parts = {"electricity_eur": round(energy, 2), "gas_eur": round(heat_cost["gas_eur"], 2), + "heat_eur": round(heat_cost["heat_eur"], 2)} + if heat_cost["oil_eur"]: + parts["oil_eur"] = round(heat_cost["oil_eur"], 2) + energy += heat_cost["gas_eur"] + heat_cost["heat_eur"] + heat_cost["oil_eur"] + if outlook is not None: + parts["heat_outlook_eur"] = round(outlook["eur"], 2) + energy += outlook["eur"] base = baseline(s, m, x) + if base is not None and outlook is not None: + base += outlook["eur"] # the same heat with or without the plan out = {"v": 1, "made": int(time.time()), "start": start, "step_s": step, "status": status, "solve_s": round(time.time() - t0, 2), "devices": devices, "flex": flexibility(m, x), # without a tariff no cost: None, never a cost at a made-up price @@ -808,13 +1205,34 @@ def plan(s: dict, time_limit: float = 30.0) -> dict: v_ct = m.end_value() out["battery_end"] = {"value_ct": round(v_ct, 2), "store_eur": round(sum( v_ct / 100.0 * (x(b["soc"][-1]) - b["soc0"]) / 1000.0 for b in bats), 2)} + if parts is not None: + out["cost_parts"] = parts # cost_eur by carrier, the heat outlook a fixed term of its own + if outlook is not None: + out["heat_outlook"] = outlook + # what the stores lose while they hold energy, their facts' sources (design note 10.5) + storage = storage_report(s, m, x) + if storage: + out["storage"] = storage + co2 = co2_report(s, m, x, outlook) + if co2 is not None: + out["co2_kg"] = co2 + out["co2_basis"] = (s.get("co2") or {}).get("basis") or str((s.get("params") or {}).get(CO2_BASIS_KEY) or "") + # what the plan assumed for want of a fact, or left out (also published; quiet: no alarm): the inputs' + # notes (inputs.model_state: occupancy, the car's forecast session), the battery's end value, the model's + notes = [str(n) for n in s.get("notes") or []] if getattr(m, "end_note", ""): - out["notes"] = [m.end_note] # what the plan assumed for want of a fact (also published) + notes.append(m.end_note) + notes += m.notes + if notes: + out["notes"] = notes steps_eur = step_costs(s, m, x) if steps_eur is not None: out["steps_eur"] = steps_eur # per step and carrier: with and without the plan (costs.py) - if heat_cost["gas_eur"] or heat_cost["heat_eur"]: + out["saving_parts"] = saving_parts(s, m, x, steps_eur) # by carrier and lever (plansplit.py, E14) + if heat_cost["gas_eur"] or heat_cost["heat_eur"] or heat_cost["oil_eur"]: out["gas_eur"], out["heat_eur"] = round(heat_cost["gas_eur"], 2), round(heat_cost["heat_eur"], 2) + if heat_cost["oil_eur"]: + out["oil_eur"] = round(heat_cost["oil_eur"], 2) # rooms not planned (inputs.room_refusal): the thermostat's # fallback schedule, and which one in their refusal refused = copy.deepcopy(s.get("refused") or {}) @@ -1090,7 +1508,9 @@ def flexibility(m, x) -> dict: continue if kind == "battery": for t in range(min(n, len(v["dis"]))): - stored = max(x(v["soc"][t - 1]) if t else x(v["soc"][0]), 0.0) - v["floor_wh"] + # what it holds above its floor after this step's idle loss (S.2) + stored = (max(v.get("phi", 1.0) * x(v["soc"][t - 1]) - m.dt * v.get("p0", 0.0), 0.0) if t else + max(x(v["soc"][0]), 0.0)) - v["floor_wh"] spare = max(v["max_dis"] - x(v["dis"][t]), 0.0) shed[t] += max(min(spare, stored / m.dt if m.dt else 0.0), 0.0) cols = v.get("ch") if kind == "battery" else v.get("power") @@ -1155,7 +1575,10 @@ def shift_envelope(m, x) -> dict | None: "soc_wh": round(v["soc0"]), "lo_wh": [round(v["floors"][t] / 100.0 * v["cap"]) for t in range(n)], "max_wh": round(v["hi_wh"]), "cap_wh": round(v["cap"]), "ch_w": round(v["max_ch"]), "dis_w": round(v["max_dis"]), - "eta": round(v["eff"], 4), "end_wh": round(_x(x, v["soc"][n - 1]))}) + "eta": round(v["eff"], 4), "end_wh": round(_x(x, v["soc"][n - 1])), + # its idle loss (S.2) and where it came from, for the building's own plan (C2.7) + "standby_w": round(v.get("p0", 0.0), 1), "loss_pct_h": round(v.get("lam_h", 0.0) * 100.0, 6), + "standby_src": ((src.get("battery") or {}).get(d["id"]) or {}).get("standby_w", "none")}) elif kind == "ev": if not v.get("known") or v["pmax"] <= 0: continue @@ -1200,6 +1623,20 @@ def shift_envelope(m, x) -> dict | None: out.append({"id": d["id"], "kind": kind, "base_w": [round(a) for a in p], "up_w": [round(max(0.0, v["pmax"] - a)) for a in p], "down_w": [round(a) for a in p], "lo_wh": [round(a) for a in lo], "hi_wh": [round(a) for a in hi], "keep": round(v["keep"], 6)}) + elif kind == "dhw_tank": + if v["heater"] not in ("element", "heat_pump") or v["switched"] or v["pmax"] <= 0: + continue # gas, district heat or a relay: no band of electric power + p = [_x(x, v["power"][t]) for t in range(n)] + cop = sum(v["cops"][:n]) / n + lo, hi = [], [] + for t in range(n): + e = _x(x, v["e"][t]) + # the heat it can hold more or less than planned, in Wh of electricity at the mean COP + lo.append(min(0.0, (v["emin"] - e) / cop)) + hi.append(max(0.0, (v["emax"] - e) / cop)) + out.append({"id": d["id"], "kind": "dhw_tank", "base_w": [round(a) for a in p], + "up_w": [round(max(0.0, v["pmax"] - a)) for a in p], "down_w": [round(a) for a in p], + "lo_wh": [round(a) for a in lo], "hi_wh": [round(a) for a in hi], "keep": round(v["phi"], 6)}) if not out: return None return {"v": 1, "start": s["start"], "step_s": s["step_s"], "steps": n, "devices": out[:SHIFT_DEVICES]} @@ -1227,14 +1664,25 @@ def _key(e) -> tuple: return ("auto",) if e.get("auto") else (e["set"], e.get("grid"), e.get("source")) +def boiler_fuel(p: dict) -> str: + """A boiler's fuel (docs/methods.md E15): "oil" where its control says + fuel: oil (heating oil EL), else "gas": a boiler before branch + heating-oil was a gas boiler by definition (the schema's meaning, not a + guess; inputs.heating_refusal refuses any other fuel).""" + return "oil" if str((p or {}).get("fuel") or "gas") == "oil" else "gas" + + def carrier_costs(s, m, x) -> dict: - """What the plan's gas and district heat cost (EUR), at their prices.""" - gas, dh = s.get("price_gas") or [], s.get("price_heat") or [] - out = {"gas_eur": 0.0, "heat_eur": 0.0} + """What the plan's gas, heating oil and district heat cost (EUR), at + their prices (the rooms'); a boiler's input (column "gas") at its + fuel's price.""" + dh = s.get("price_heat") or [] + out = {"gas_eur": 0.0, "heat_eur": 0.0, "oil_eur": 0.0} for kind, v in m.devices.values(): - if kind != "heating" or not v: + if kind not in ("heating", "dhw_tank") or not v: continue - for key, prices, col in (("gas_eur", gas, "gas"), ("heat_eur", dh, "district")): + fuel = v.get("fuel") or "gas" + for key, prices, col in ((fuel + "_eur", s.get("price_" + fuel) or [], "gas"), ("heat_eur", dh, "district")): for t, var in enumerate(v.get(col) or []): if var is not None and t < len(prices) and prices[t] is not None: out[key] += m.eur_wh(t, prices[t]) * x(var) @@ -1319,6 +1767,10 @@ def _entry(d, kind, v, t, x, s, pi, grid_w=(1e9, 1e9)): return None if kind == "battery": net = x(v["ch"][t]) - x(v["dis"][t]) + if 0 < net <= v.get("p0", 0.0) / v["eff"] + 1.0: + # a charge no larger than the idle loss: the plan holds the battery (at its floor, its + # standby taken from the grid, as the inverter does itself): no grid charging for it + net = 0.0 net = _round(net, 50.0) surplus = s["pv_w"][t] - s["load_w"][t] grid = net > max(0.0, surplus) + 50 @@ -1359,14 +1811,15 @@ def _entry(d, kind, v, t, x, s, pi, grid_w=(1e9, 1e9)): pw = _inputs_w(v, t, x) src = v.get("src", "electric") # the price that buys the heat now, for the words - pr = {"boiler": s.get("price_gas"), "district": s.get("price_heat")}.get(src) or pi + fuel = v.get("fuel") or "gas" + pr = {"boiler": s.get("price_" + fuel), "district": s.get("price_heat")}.get(src) or pi pr_t = pr[t] if t < len(pr) else None source = None if src == "hybrid": hp_w, gas_w = x(v["power"][t]), x(v["gas"][t]) source = "heat_pump" if hp_w >= gas_w and hp_w > 50 else "boiler" if gas_w > 50 else None if source == "boiler": - pr_t = (s.get("price_gas") or [None] * (t + 1))[t] + pr_t = (s.get("price_" + fuel) or [None] * (t + 1))[t] ahead = s["occupied"][min(t + 4, s["steps"] - 1)] pref = d.get("pref") if pref: @@ -1405,14 +1858,19 @@ def _entry(d, kind, v, t, x, s, pi, grid_w=(1e9, 1e9)): want = max(want, float(pref["must"][t])) floor_t = min(max(math.floor(want * 2) / 2, math.ceil(lo * 2) / 2), math.floor(hi * 2) / 2) return {"set": min(target, floor_t), "why": "setback: away or night" if not occ else "warm enough"} - what = {"boiler": "gas", "district": "heat"}.get(src if src != "hybrid" else (source or ""), "power") + what = {"boiler": "heating oil" if fuel == "oil" else "gas", "district": "heat"}.get( + src if src != "hybrid" else (source or ""), "power") e = {"set": target, "why": f"pre-heat while {what} is cheap ({pr_t:.1f} ct)" if not occ and ahead and pr_t is not None else "keep the room warm"} if source: e["source"] = source e["why"] += "; " + ("the heat pump: its heat is cheaper now" if source == "heat_pump" else "the boiler: its heat is cheaper now") return e + if kind == "dhw_tank": + return _tank_entry(d, v, t, x, s, pi) if kind == "ev": + if v.get("expected"): + return None # not plugged in: a forecast load, no command (inputs.ev_session) p = v["power"][t] if p is None: return {"set": "off", "why": "after departure"} @@ -1448,6 +1906,277 @@ def _entry(d, kind, v, t, x, s, pi, grid_w=(1e9, 1e9)): return None +TANK_HEAT_W = 50.0 # W of heat below which a tank's heater counts as off in a step (ENG: rounding) + + +def tank_heat(v, t, x) -> float: + """A tank's planned heat in step t (W).""" + return sum(k * x(var) for k, var in v["heat"][t]) + + +def tank_temp(v, t, x) -> float: + """A tank's planned mean temperature at the end of step t (S.4 backwards).""" + return v["t_cw"] + x(v["e"][t]) / v["cw"] + + +def _tank_entry(d, v, t, x, s, pi): + """What a tank's heater is to do in step t (docs/methods.md A13): a + water heater's target °C (heating: the planned temperature, rounded up + to the degree; else the comfort's least, which its thermostat keeps), a + relay's on/off, a stepless element's W, an SG-Ready state (3: store + above the comfort, 2: normal); and why.""" + q = tank_heat(v, t, x) + temp = tank_temp(v, t, x) + on = q > TANK_HEAT_W + chans = set(d.get("channels") or []) + lo, hi = v["lo_c"], v["hi_c"] + leg = v["e_leg"] is not None and t in v["window"] and x(v["e"][t]) >= v["e_leg"] - 1.0 + price = {"boiler": s.get("price_gas"), "district": s.get("price_heat")}.get(v["heater"]) or pi + pr = price[t] if t < len(price) else None + if not on: + why = "off: warm enough" + elif leg: + why = f"legionella run ({(v['e_leg'] / v['cw'] + v['t_cw']):.0f} °C)" + elif v["heater"] in ("element", "heat_pump") and s["pv_w"][t] - s["load_w"][t] > 0.5 * q / max(v["cops"][t], 1.0): + why = "store PV surplus as hot water" + elif temp > lo + 1.0 and pr is not None: + why = f"store heat while it is cheap ({pr:.1f} ct)" + else: + why = f"keep the tank at {lo:.0f} °C" + if "water_heater" in chans: + target = min(max(math.ceil(temp), math.ceil(lo)), math.floor(hi)) if on else math.ceil(lo) + return {"set": float(target), "why": why} + if "power" in chans and v["heater"] in ("element", "heat_pump"): + return {"set": _round(x(v["power"][t]), 50.0) if on else 0.0, "why": why} + if "switch" in chans: + return {"set": "on" if on else "off", "why": why} + if "sg_ready" in chans: + return {"set": "sg:3" if on and temp > lo + 1.0 else "sg:2", "why": why} + return None + + +def _carrier_price(s, carrier: str, t: int): + xs = s.get({"electricity": "price_import", "gas": "price_gas", "heat": "price_heat"}[carrier]) or [] + return xs[t] if t < len(xs) else None + + +def _tank_input_w(v, t, heat_w: float) -> tuple[str, float]: + """The carrier and its input (W) for a tank's heat (W): an element's + electricity, a heat pump's by its COP, a boiler's gas by its full-load + efficiency, district heat as it is.""" + if v["heater"] in ("element", "heat_pump"): + return "electricity", heat_w / max(v["cops"][t], 1e-9) + if v["heater"] == "boiler": + return "gas", heat_w / (v["eff"] or 1.0) + return "heat", heat_w + + +def tank_baseline(m, v) -> float: + """The tank without the plan (EUR): its own thermostat holding the + comfort's least, the same draw and the standing loss there, each W of + heat at its carrier's mean price over the horizon.""" + s = m.s + eur = 0.0 + for carrier in ("electricity", "gas", "heat"): + ps = [p for p in [_carrier_price(s, carrier, t) for t in range(m.T)] if p is not None] + if not ps: + continue + mean = sum(ps) / len(ps) + for t in range(m.T): + heat = v["draw"][t] + v["ua"] * (v["lo_c"] - v["room"]) + c, w = _tank_input_w(v, t, max(0.0, heat)) + if c == carrier: + eur += m.eur_wh(t, mean) * w + return eur + + +def storage_report(s, m, x) -> dict: + """Per store what it loses while it holds energy (design note 10.5): + the battery's idle loss (its standby and the cells' self-discharge, + S.2) and the tank's standing loss (S.5), over the horizon and its first + 24 h, each kWh at the step's price of what replaces it (the import + price; a tank's heat by its carrier); the facts with their source; a + tank's planned temperatures and heat per hour, its draw, the comfort it + missed and its legionella run.""" + out = {} + src = s.get("sources") or {} + n24 = min(m.T, FLEX_STEPS) + for d in s["devices"]: + kind, v = m.devices.get(d["id"], (d["kind"], None)) + if v is None or kind not in ("battery", "dhw_tank"): + continue + if kind == "battery": + loss = [] + for t in range(m.T): + prev = x(v["soc"][t - 1]) if t else v["soc0"] + loss.append((1.0 - v["phi"]) * prev + m.dt * v["p0"]) # Wh in the step + fsrc = (src.get("battery") or {}).get(d["id"]) or {} + eur = sum(loss[t] / 1000.0 * (s["price_import"][t] or 0.0) / 100.0 for t in range(n24)) if m.priced else None + r = {"kind": "battery", "standby_w": round(v["p0"], 1), "standby_src": fsrc.get("standby_w", "none"), + "self_discharge_pct_month": round(v["lam_h"] * HOURS_PER_MONTH * 100.0, 3), + "self_discharge_src": fsrc.get("self_discharge_pct_month", "none"), "standby_in_load": v["in_load"], + "idle_loss_kwh": round(sum(loss) / 1000.0, 3), "idle_loss_kwh_24h": round(sum(loss[:n24]) / 1000.0, 3), + "idle_loss_eur_24h": None if eur is None else round(eur, 3), + "from_grid_kwh": round(sum(m.dt * x(g) for g in v["lg"]) / 1000.0, 3)} + fit = (src.get("battery_fit") or {}).get(d["id"]) + if fit: + r["fit"] = fit + if r["from_grid_kwh"] > 0.001 and v["in_load"] is None: + m.note(f"{d['id']}: the battery's standby drawn from the grid at times; whether the house load holds " + "it is not said (mapping standby_in_load): not added to the load") + out[d["id"]] = r + continue + p, st = d["params"], d["state"] + loss, eur = [], 0.0 + for t in range(m.T): + prev = x(v["e"][t - 1]) if t else v["e0"] + lw = v["ua"] * (v["t_cw"] + prev / v["cw"] - v["room"]) # W, UA (T - T_room) + loss.append(lw * m.dt) + if t < n24 and m.priced: + c, w = _tank_input_w(v, t, max(0.0, lw)) + pr = _carrier_price(s, c, t) + eur += m.eur_wh(t, pr) * w if pr is not None else 0.0 + heat = [tank_heat(v, t, x) for t in range(m.T)] + temps = [tank_temp(v, t, x) for t in range(m.T)] + hours = range(0, m.T, 4) + r = {"kind": "dhw_tank", "heater": v["heater"], "volume_l": float(p["volume_l"]), "ua_w_k": round(v["ua"], 3), + "standby_w": round(v["ua"] * ERP_TEST_DT_K, 1), "loss_src": ((src.get("dhw_tank") or {}).get(d["id"]) or {}).get( + "ua_w_k", "none"), + "temp_c": round(float(st["temp_c"]), 1), "stored_kwh": round(v["e0"] / 1000.0, 2), + "usable_kwh": round(max(0.0, v["e0"] - v["emin"]) / 1000.0, 2), "min_temp_c": round(v["lo_c"], 1), + "max_temp_c": round(v["hi_c"], 1), "grossanlage": bool(p.get("grossanlage")), + "idle_loss_kwh": round(sum(loss) / 1000.0, 3), "idle_loss_kwh_24h": round(sum(loss[:n24]) / 1000.0, 3), + "idle_loss_eur_24h": round(eur, 3) if m.priced else None, + "draw_kwh_24h": round(sum(v["draw"][:n24]) * m.dt / 1000.0, 3), + "heat_kwh_24h": round(sum(heat[:n24]) * m.dt / 1000.0, 3), + "short_kwh": round(sum(x(u) for u in v["unmet"]) * m.dt / 1000.0, 3), + "temp_plan_c": [round(temps[min(k + 3, m.T - 1)], 1) for k in hours], + "heat_w": [round(sum(heat[k:k + 4]) / len(heat[k:k + 4])) for k in hours], + "legionella": {"mode": str(p.get("legionella") or "device"), "last": (st.get("legionella") or {}).get("last"), + "due": (st.get("legionella") or {}).get("due"), "planned": None}} + if p.get("erp_class"): + r["erp_class"] = p["erp_class"] + if v["e_leg"] is not None: + hit = next((t for t in v["window"] if x(v["e"][t]) >= v["e_leg"] - 1.0), None) + r["legionella"]["planned"] = s["start"] + (hit + 1) * s["step_s"] if hit is not None else None + if r["short_kwh"] > 0.05: + m.note(f"{d['id']}: the tank cannot give {r['short_kwh']:.1f} kWh of the hot water forecast " + "(its heater's power or maximum temperature)") + out[d["id"]] = r + return out + + +def heat_outlook(s, m) -> dict | None: + """The heat no model in the plan decides (docs/methods.md A2.16; + backlog 45.3, the box's part): the site's space heat where no room + model plans it (every heating control refused, or none) and its hot + water (an unshiftable demand today; a tank between it and its heater: + backlog 329), each a heat_demand delivered when demanded by the site's + source (state["heat_site"], inputs.heat_site: a boiler's gas by its + efficiency at the load, E6.4; district heat as it is), at the carrier's + price and CO2. A fixed term of the plan's cost (nothing in it is + decided). {source, from, carrier, eur, co2_kg, heat_kwh, input_kwh, + efficiency, part_load, lines: {space, dhw: HeatSupply.delivered}}; None + where none can be made (the reason noted, quietly: a control's refusal + says what to enter; no hot-water meter is nobody's fault).""" + site = s.get("heat_site") or {} + if site.get("note"): + m.note(site["note"]) + return None + src = site.get("source") + if src not in ("boiler", "district"): + return None + if src == "boiler" and not site.get("boiler_efficiency"): + m.note("heat outlook: the boiler's efficiency unknown") + return None + sup = HeatSupply(m, site.get("from") or "heat", site, src) + if not any(p is not None for p in sup.prices[:m.T]): + m.note(f"heat outlook: no {sup.carrier} price") + return None + lines = {} + # hot water a planned tank stores and heats is the tank's (Model.dhw_tank): not here again + tanked = any(k == "dhw_tank" and v for k, v in m.devices.values()) + for kind in (("space",) if site.get("space") else ()) + (() if tanked else ("dhw",)): + q = heat_demand(s, kind, m.T) + if q is None: + m.note("heat outlook: no heat forecast for this site" if kind == "space" else + "heat outlook: no hot-water forecast (no hot-water meter at this site yet): hot water not in it") + continue + lines[kind] = sup.delivered(q) + if not lines: + return None + co2 = [ln["co2_kg"] for ln in lines.values()] + out = {"source": src, "from": site.get("from", ""), "carrier": sup.carrier, + "eur": round(sum(ln["eur"] for ln in lines.values()), 2), + "co2_kg": None if None in co2 else round(sum(co2), 2), + "heat_kwh": round(sum(ln["heat_kwh"] for ln in lines.values()), 2), + "input_kwh": round(sum(ln["input_kwh"] for ln in lines.values()), 2), "lines": lines} + unpriced = sum(ln.get("unpriced_kwh", 0.0) for ln in lines.values()) + if unpriced: + out["unpriced_kwh"] = round(unpriced, 2) + if src == "boiler": + out["efficiency"] = sup.eff + out["part_load"] = sup.curve["from"] + return out + + +def co2_report(s, m, x, outlook) -> dict | None: + """The plan's CO2 (kg) by carrier, and the baseline's (A2.15): the + meter's import at each step's factor (feed-in earns no credit), the + rooms' gas and district heat at theirs, the heat outlook's; + the baseline as baseline() (the house's net import without a battery, + the devices' electricity at the horizon's mean factor, the same gas and + heat). Steps or carriers without a factor are left out (incomplete: + true). None where the bundle has no CO2 factor at all.""" + c = s.get("co2") or {} + if not c: + return None + T = m.T + kwh = m.dt / 1000.0 + out, base, incomplete = {"electricity": 0.0}, {"electricity": 0.0}, False + fe = [m.co2_factor("electricity", t) for t in range(T)] + known = [f for f in fe if f is not None] + mean = sum(known) / len(known) if known else None + for t in range(T): + if fe[t] is None: + incomplete = True + continue + out["electricity"] += x(m.gin[t]) * kwh * fe[t] / 1000.0 + net = s["load_w"][t] - s["pv_w"][t] + base["electricity"] += max(net, 0.0) * kwh * fe[t] / 1000.0 + for kind, v in m.devices.values(): + if not v or kind not in ("heating", "cooling", "ev", "dhw_tank"): + continue + if mean is not None: + base["electricity"] += sum(x(p) * kwh * mean / 1000.0 for p in v.get("power") or [] if p is not None + and hasattr(p, "index")) + for col, carrier in (("gas", v.get("fuel") or "gas"), ("district", "heat")): + e = sum(x(g) * kwh for g in v.get(col) or [] if g is not None) + if e <= 0: + continue + f = m.co2_factor(carrier, 0) + if f is None: + incomplete = True + continue + out[carrier] = out.get(carrier, 0.0) + e * f / 1000.0 + base[carrier] = base.get(carrier, 0.0) + e * f / 1000.0 + if outlook is not None: + if outlook.get("co2_kg") is None: + incomplete = True + else: + out[outlook["carrier"]] = out.get(outlook["carrier"], 0.0) + outlook["co2_kg"] + base[outlook["carrier"]] = base.get(outlook["carrier"], 0.0) + outlook["co2_kg"] + r = {"plan": round(sum(out.values()), 2), "baseline": round(sum(base.values()), 2), + "carriers": {k: round(v, 2) for k, v in out.items()}} + if incomplete: + r["incomplete"] = True + if m.co2w: + r["weight_eur_per_t"] = m.co2w + if c.get("electricity_source"): + r["electricity_source"] = c["electricity_source"] + return r + + def baseline(s, m, x) -> float: """An estimate of the cost without the plan: the house's net load at its prices, no battery, and the devices' energy (as the plan uses it) at the @@ -1464,17 +2193,24 @@ def baseline(s, m, x) -> float: for kind, v in m.devices.values(): if not v: continue + if kind == "battery": + # its idle loss is there with or without the plan: replaced at the mean import price (S.2) + cost += sum(m.eur_wh(t, mean) for t in range(T)) * v.get("p0", 0.0) + elif kind == "dhw_tank": + cost += tank_baseline(m, v) if kind in ("heating", "cooling"): # each input as the plan uses it at its mean price (electricity, gas, district heat) cost += sum(m.eur_wh(t, mean) * x(v["power"][t]) for t in range(T) if v["power"][t] is not None) - for col, key in (("gas", "price_gas"), ("district", "price_heat")): + for col, key in (("gas", "price_" + (v.get("fuel") or "gas")), ("district", "price_heat")): ps = [p for p in (s.get(key) or [])[:T] if p is not None] if ps and any(c is not None for c in v.get(col) or []): mp = sum(ps) / len(ps) cost += sum(m.eur_wh(t, mp) * x(c) for t, c in enumerate(v[col]) if c is not None) elif kind == "ev": wh = sum(m.dt * x(p) for p in v["power"] if p is not None) - asap = pi[:max(1, math.ceil(wh / max(1.0, v["volts"] * 16) / m.dt))] + # as soon as it can charge: from now, an expected session from its arrival + a = next((t for t, p in enumerate(v["power"]) if p is not None), 0) + asap = pi[a:a + max(1, math.ceil(wh / max(1.0, v["volts"] * 16) / m.dt))] or pi[:1] cost += wh / 1000.0 * (sum(asap) / len(asap)) / 100.0 return cost @@ -1503,7 +2239,7 @@ def step_costs(s, m, x) -> dict | None: el_base.append(m.eur_wh(t, pi[t]) * max(net, 0) - m.eur_wh(t, pe[t]) * max(-net, 0)) mean = sum(pi) / T out = {"electricity": {"plan": el_plan, "base": el_base}} - for carrier, col, key in (("gas", "gas", "price_gas"), ("heat", "district", "price_heat")): + for carrier, col, key in (("gas", "gas", "price_gas"), ("oil", "gas", "price_oil"), ("heat", "district", "price_heat")): prices = (s.get(key) or [])[:T] ps = [p for p in prices if p is not None] if not ps: @@ -1511,8 +2247,10 @@ def step_costs(s, m, x) -> dict | None: mp = sum(ps) / len(ps) plan_c, base_c, used = [0.0] * T, [0.0] * T, False for kind, v in m.devices.values(): - if kind != "heating" or not v: + if kind not in ("heating", "dhw_tank") or not v: continue + if col == "gas" and (v.get("fuel") or "gas") != carrier: + continue # a boiler's input at its own fuel's price only for t, var in enumerate(v.get(col) or []): if var is not None and t < len(prices) and prices[t] is not None: used = True @@ -1523,13 +2261,18 @@ def step_costs(s, m, x) -> dict | None: for kind, v in m.devices.values(): if not v: continue - if kind in ("heating", "cooling"): + if kind == "battery" and v.get("p0"): + for t in range(T): + el_base[t] += m.eur_wh(t, mean) * v["p0"] + if kind in ("heating", "cooling", "dhw_tank"): for t in range(T): if v["power"][t] is not None: el_base[t] += m.eur_wh(t, mean) * x(v["power"][t]) elif kind == "ev": wh = sum(m.dt * x(p) for p in v["power"] if p is not None) - asap = pi[:max(1, math.ceil(wh / max(1.0, v["volts"] * 16) / m.dt))] + # as soon as it can charge: from now, an expected session from its arrival + a = next((t for t, p in enumerate(v["power"]) if p is not None), 0) + asap = pi[a:a + max(1, math.ceil(wh / max(1.0, v["volts"] * 16) / m.dt))] or pi[:1] amean = sum(asap) / len(asap) for t, p in enumerate(v["power"]): if p is not None: diff --git a/src/edge/cantabile_edge/plansplit.py b/src/edge/cantabile_edge/plansplit.py new file mode 100644 index 0000000..d5686be --- /dev/null +++ b/src/edge/cantabile_edge/plansplit.py @@ -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 diff --git a/src/edge/cantabile_edge/preferences.py b/src/edge/cantabile_edge/preferences.py index f62ee15..531e0c8 100644 --- a/src/edge/cantabile_edge/preferences.py +++ b/src/edge/cantabile_edge/preferences.py @@ -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: {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: {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: {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" diff --git a/src/edge/cantabile_edge/propose.py b/src/edge/cantabile_edge/propose.py index 1310810..f33d8bd 100644 --- a/src/edge/cantabile_edge/propose.py +++ b/src/edge/cantabile_edge/propose.py @@ -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..home (1 while "home", else 0; 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..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..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..home, equals home) and per area one occupancy or presence + binary_sensor (room..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) diff --git a/src/edge/cantabile_edge/storefit.py b/src/edge/cantabile_edge/storefit.py new file mode 100644 index 0000000..d09fd96 --- /dev/null +++ b/src/edge/cantabile_edge/storefit.py @@ -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 /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 diff --git a/src/edge/cantabile_edge/trainhist.py b/src/edge/cantabile_edge/trainhist.py index 2f158fe..12e10f7 100644 --- a/src/edge/cantabile_edge/trainhist.py +++ b/src/edge/cantabile_edge/trainhist.py @@ -6,7 +6,9 @@ the agent's SQLite (/training.db), rolling. slots 15-minute means per asset the trainer uses (load.power, pv.power, the planned devices' power, room..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..occupied and person..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: diff --git a/src/edge/cantabile_edge/trainlib.py b/src/edge/cantabile_edge/trainlib.py index 4c253b6..6a8ac32 100644 --- a/src/edge/cantabile_edge/trainlib.py +++ b/src/edge/cantabile_edge/trainlib.py @@ -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." 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)) diff --git a/src/edge/link/main.go b/src/edge/link/main.go index 8de4fcb..eb811d7 100644 --- a/src/edge/link/main.go +++ b/src/edge/link/main.go @@ -788,7 +788,8 @@ func (l *link) heartbeat() map[string]any { } // siteCell: [lat, lon] rounded to 0.1° from the agent's site_cell.json -// (written from HA's configuration), or nil (none, malformed, out of range). +// (written from HA's configuration), or nil (none, malformed, out of range, +// or 0,0: an HA without a location set). func siteCell(path string) []float64 { var c struct{ Lat, Lon *float64 } b, err := os.ReadFile(path) @@ -796,7 +797,7 @@ func siteCell(path string) []float64 { return nil } lat, lon := math.Round(*c.Lat*10)/10, math.Round(*c.Lon*10)/10 - if math.Abs(lat) > 90 || math.Abs(lon) > 180 { + if math.Abs(lat) > 90 || math.Abs(lon) > 180 || (lat == 0 && lon == 0) { return nil } return []float64{lat, lon} diff --git a/src/edge/link/sitecell_test.go b/src/edge/link/sitecell_test.go new file mode 100644 index 0000000..f0aeb47 --- /dev/null +++ b/src/edge/link/sitecell_test.go @@ -0,0 +1,39 @@ +// Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved. + +package main + +import ( + "os" + "path/filepath" + "reflect" + "testing" +) + +// The heartbeat's cell: rounded to 0.1°, none for 0,0 (an HA without a +// location set) or out of range. +func TestSiteCell(t *testing.T) { + dir := t.TempDir() + for _, c := range []struct { + body string + want []float64 + }{ + {`{"lat": 47.04, "lon": 28.86}`, []float64{47.0, 28.9}}, + {`{"lat": 0, "lon": 0}`, nil}, + {`{"lat": 0.04, "lon": -0.03}`, nil}, + {`{"lat": -0.3, "lon": 0}`, []float64{-0.3, 0}}, + {`{"lat": 95, "lon": 10}`, nil}, + {`{"lat": 47}`, nil}, + {`not json`, nil}, + } { + p := filepath.Join(dir, "site_cell.json") + if err := os.WriteFile(p, []byte(c.body), 0o600); err != nil { + t.Fatal(err) + } + if got := siteCell(p); !reflect.DeepEqual(got, c.want) { + t.Errorf("%s: %v, want %v", c.body, got, c.want) + } + } + if siteCell(filepath.Join(dir, "missing.json")) != nil { + t.Error("a missing file: a cell") + } +} diff --git a/src/edge/tests/test_boxtrain_carriers.py b/src/edge/tests/test_boxtrain_carriers.py new file mode 100644 index 0000000..05d5a23 --- /dev/null +++ b/src/edge/tests/test_boxtrain_carriers.py @@ -0,0 +1,185 @@ +# Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved. +"""The box trains the carriers too (45.4, methods.md B10, +B13-B16): heat (heat.power), occupancy (the presence sources: rooms' +sensors and people at home) and ev_plug (the chargers' plug state, else +their charging), after load, base load and PV, one at a time with the same +rules; the planner takes the box's own occupancy where it is in force. +And Home Assistant's wind on the box (localml, trainhist): m/s from the +weather entity's wind_speed_unit, an unknown unit no wind, never a guess.""" +import math +import sqlite3 +from datetime import datetime, timezone +from types import SimpleNamespace +from zoneinfo import ZoneInfo + +import numpy as np +import pytest + +from cantabile_edge import boxtrain, fcmodels, localml, pvforecast, trainhist +from cantabile_edge.bundles import Bundles +from cantabile_edge.inputs import Collector, model_state + +from test_control_parts import SITE + +DAY = 86400 +START = 1_800_000_000 // 3600 * 3600 # 2027-01-15 08:00 UTC, a Friday +LAT, LON = 51.34, 12.37 + + +def cfg(tmp_path, **kw): + d = dict(state_dir=str(tmp_path), train=True, train_at="03:30", train_series_s=120.0, train_mem_mb=900, + train_min_free_mb=0, train_days=28, pv_metered_since="") + d.update(kw) + return SimpleNamespace(**d) + + +def home(tmp_path, days=28): + """A synthetic home's training history: two people (home evenings and + nights), a room's presence sensor, a car plugged in on weekday evenings, + heat from the outdoor temperature and the wind.""" + st = trainhist.Store(str(tmp_path / "training.db")) + t = np.arange(START - days * DAY, START, 900, dtype=np.int64) + rnd = np.random.default_rng(7) + h = (t % DAY) // 3600 + wd = np.array([datetime.fromtimestamp(int(x), timezone.utc).weekday() for x in t]) + anna = ((h >= 17) | (h < 8)).astype(float) + ben = ((h >= 19) | (h < 7) | (wd >= 5)).astype(float) + room = ((h >= 18) & (h < 23)).astype(float) + plug = ((wd < 5) & ((h >= 18) | (h < 7))).astype(float) + temp = 3.0 + 4.0 * np.sin(2 * np.pi * (t % DAY) / DAY) + rnd.normal(0, 0.5, len(t)) + wind = 4.0 + 2.0 * np.cos(2 * np.pi * t / (3 * DAY)) + heat = np.maximum(250.0 * (20.0 - temp) * (1 + 0.03 * wind), 0.0) + for name, y in (("load.power", 400.0 + 300.0 * room), ("person.p1a2b3c.home", anna), ("person.pd4e5f6.home", ben), + ("room.living.occupied", room), ("ev.plugged", plug), ("heat.power", heat)): + st.fill(name, {int(a): float(b) for a, b in zip(t.tolist(), y.tolist())}, "agent") + hours = [pvforecast.Hour(datetime.fromtimestamp(e, timezone.utc), None, 50.0, + float(temp[min(len(t) - 1, (e - int(t[0])) // 900 - 1)]), + float(wind[min(len(t) - 1, (e - int(t[0])) // 900 - 1)])) + for e in range(int(t[0]) + 3600, START + 3600, 3600)] + st.put_weather("observed", "cloud", hours) + return st, t, {"anna": anna, "ben": ben, "room": room, "plug": plug, "heat": heat} + + +# -- the history --------------------------------------------------------------------- +def test_the_history_keeps_the_presence_and_plug_assets(): + for a in ("room.living.occupied", "person.p1a2b3c.home", "ev.plugged", "ev.2.plugged", "ev2.plugged", "ev2.power", + "heat.power", "room.living.temp"): + assert trainhist.wanted(a), a + for a in ("room.living.occupied_2", "person.anna.away", "ev.plugged.x", "room.living", "sensor.x"): + assert not trainhist.wanted(a), a + + +def test_actual_carrier_series(tmp_path): + st, t, y = home(tmp_path, days=3) + b = boxtrain.BoxTraining(cfg(tmp_path), st, None) + raw = {a: boxtrain.arrays(v, t) for a, v in st.series(int(t[0]), START).items()} + occ = b.actual("occupancy", t, raw) + assert np.allclose(occ, (y["anna"] + y["ben"] + y["room"]) / 3) # B16.1 over all three sources + assert np.array_equal(b.actual("ev_plug", t, raw), y["plug"]) + assert np.allclose(b.actual("heat", t, raw), y["heat"]) + # no plug state: the chargers charging (as building/carriers.py) + raw2 = {"ev.power": np.where(y["plug"] > 0, 11000.0, 0.0)} + assert np.array_equal(boxtrain.plug_series(raw2), y["plug"]) + two = {"ev.1.plugged": y["plug"], "ev.2.plugged": y["plug"], "ev.plugged": np.minimum(2 * y["plug"], 1)} + assert float(boxtrain.plug_series(two).max()) == 2.0 # the parts, not the total + assert boxtrain.presence_share({"room.a.temp": np.ones(3)}, 3) is None + + +# -- the nightly jobs ----------------------------------------------------------------- +def test_carriers_trained_after_load_and_pv(tmp_path): + st, t, y = home(tmp_path) + b = boxtrain.BoxTraining(cfg(tmp_path), st, None, kinds=lambda: {"ev"}) + b.state["rooms"] = {"living": {"status": "fitted", "power": "thermal", "r_k_per_kw": 4.0, "c_kwh_per_k": 5.0}} + st.fill("room.living.temp", {int(a): 20.5 for a in t.tolist()}, "agent") + b.site = lambda tz, loc: fcmodels.Site(tz, LAT, LON) + jobs, info = b.prepare(START, "UTC", {}) + assert [j["series"] for j in jobs if j["series"] != "rooms"] == ["load", "base_load", "heat", "occupancy", "ev_plug"] + heat = next(j for j in jobs if j["series"] == "heat") + assert heat["site"]["ua_w_per_k"] == pytest.approx(250.0) and heat["site"]["t_in_c"] == pytest.approx(20.5) + assert len(heat["site"]["occ_how"]) == 168 # the occupancy's hour-of-week + assert next(j for j in jobs if j["series"] == "occupancy")["site"].get("occ_how") is None + assert any(len(r) == 5 and r[4] is not None for r in heat["hours"]) # the wind travels with the weather + # each in the child's code, as the cloud trains it; in force without a cloud model when it beats the hour-of-week + for name in ("occupancy", "ev_plug", "heat"): + job = next(j for j in jobs if j["series"] == name) + res = boxtrain.run_job(job) + assert res["chosen"] in ("how", "gbm") and res["params"], (name, res.get("note")) + out = b.take(name, job, res, {"seconds": res["seconds"]}, START) + assert ("in force" in out["result"]) or ("not in force" in out["result"]), out + gbm_feats = b.state["series"]["heat"]["params"].get("features") or [] + if b.state["series"]["heat"]["kind"] == "gbm": + assert "wind" in gbm_feats and "occ" in gbm_feats + st_ = b.status(START) + assert set(st_["series"]) >= {"occupancy", "ev_plug", "heat"} + + +def test_the_planner_takes_the_box_own_occupancy(tmp_path): + st, t, y = home(tmp_path) + b = boxtrain.BoxTraining(cfg(tmp_path), st, Bundles(str(tmp_path), SITE)) + b.site = lambda tz, loc: fcmodels.Site(tz, LAT, LON) + jobs, _ = b.prepare(START, "UTC", {}) + job = next(j for j in jobs if j["series"] == "occupancy") + b.take("occupancy", job, boxtrain.run_job(job), {}, START) + e = b.state["series"]["occupancy"] + e["in_force"] = True # whichever kind won: in force for the planner + fc, info = b.forecast("occupancy", START, 192, [], "") + assert len(fc) == 192 and all(v is not None and 0.0 <= v <= 1.0 for v in fc) # no weather needed, a share + # evenings at home: the forecast share higher at 20:00 than at 11:00 (UTC here) + k20, k11 = (20 - 8) * 4, (11 - 8 + 24) * 4 + assert fc[k20] > fc[k11] + bd = b.bundles + bd.own = b + tariff = {"v": 1, "kind": "tariff", "id": "t", "site": SITE, "issued": START, "start": START, "step_s": 900, + "steps": 192, "expires": START + 2 * DAY, "import": [30.0] * 192, "export": [8.0] * 192, + "params": {"comfort.occupied_min_share": 0.5}} + import json + (tmp_path / "tariff.json").write_text(json.dumps(tariff)) + s = model_state(START, [], SimpleNamespace(load_power="", outside_temp="", weather="", sun="", presence=[]), + Collector(), bd, None, "UTC", None) + occ = s["sources"]["occupancy"] + assert occ["source"] == "learnt" and occ["own"] == 192 + assert s["occupied"] == [1 if v >= 0.5 else 0 for v in fc] + + +# -- Home Assistant's wind ---------------------------------------------------------------- +@pytest.mark.parametrize("unit,factor", [("m/s", 1.0), ("km/h", 1 / 3.6), ("mph", 0.44704), ("kn", 0.514444), + ("ft/s", 0.3048)]) +def test_ha_wind_units(unit, factor): + fc = [{"datetime": datetime.fromtimestamp(START + 3600, timezone.utc).isoformat(), "temperature": 4.0, + "cloud_coverage": 80, "wind_speed": 36.0}] + h = localml.ha_hours(fc, unit) + assert h[0].wind_ms == pytest.approx(36.0 * factor, rel=1e-5) and localml.wind_note(fc, unit) == "" + + +def test_unknown_wind_unit_no_wind_noted(): + fc = [{"datetime": datetime.fromtimestamp(START + 3600, timezone.utc).isoformat(), "temperature": 4.0, + "wind_speed": 3.0}] + for unit in (None, "Beaufort", "furlong/fortnight"): + assert localml.ha_hours(fc, unit)[0].wind_ms is None + assert "unknown" in localml.wind_note(fc, unit) + assert localml.wind_note([{"datetime": "x", "temperature": 1.0}], None) == "" # no wind at all: nothing to say + assert localml.ha_hours(fc)[0].temp_c == 4.0 # the rest as before + + +def test_the_box_records_and_trains_on_the_wind(tmp_path): + # an older training.db without the wind column gets it + db = sqlite3.connect(str(tmp_path / "training.db")) + db.execute("CREATE TABLE 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))") + db.execute("INSERT INTO weather VALUES (?, 'observed', 'ha', NULL, 50, 3, NULL)", (START,)) + db.commit() + db.close() + st = trainhist.Store(str(tmp_path / "training.db")) + H = lambda end, w: pvforecast.Hour(datetime.fromtimestamp(end, timezone.utc), None, 40.0, 5.0, w) # noqa: E731 + st.put_weather("observed", "ha", [H(START + 3600, 4.2)]) + got = st.weather_hours(START - 3600, START + 3600, "observed") + assert [h.wind_ms for h in got] == [None, 4.2] + # HA's recorded weather: the state's own unit + states = [{"a": {"temperature": 3.0, "cloud_coverage": 40, "wind_speed": 18.0, "wind_speed_unit": "km/h"}, "lu": START + 100}, + {"a": {"temperature": 2.0, "cloud_coverage": 90, "wind_speed": 7.0, "wind_speed_unit": "Beaufort"}, "lu": START + 3700}] + hs = boxtrain.ha_history_hours(states, [(START, START + 2 * 3600)]) + assert [h.wind_ms for h in hs] == [pytest.approx(5.0), None] + # the job's weather carries it to the child, and back + back = boxtrain.hours_from(boxtrain.hours_json(hs)) + assert back[0].wind_ms == pytest.approx(5.0) and back[1].wind_ms is None + assert boxtrain.hours_from([[START, None, 1.0, 2.0]])[0].wind_ms is None # an older job: none diff --git a/src/edge/tests/test_carrier_inputs.py b/src/edge/tests/test_carrier_inputs.py new file mode 100644 index 0000000..577e6d1 --- /dev/null +++ b/src/edge/tests/test_carrier_inputs.py @@ -0,0 +1,283 @@ +# Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved. +"""The carriers' forecasts in the box's plan (45; +methods.md A1, B15, B16): the learnt weekly presence for comfort and +setback (inputs.occupancy), the EV session forecast for a car that says +no departure or energy (bundles.ev_sessions, inputs.ev_session, +optimizer.ev), the presence sources from the mapping (controller).""" +import json +from types import SimpleNamespace + +import pytest + +from cantabile_edge import inputs +from cantabile_edge.bundles import Bundles +from cantabile_edge.controls import Control +from cantabile_edge.inputs import Collector, model_state + +SITE = "ab" * 16 +START = 1_800_000_000 // 3600 * 3600 # 2027-01-15 08:00 UTC, a Friday +STEPS = inputs.STEPS +INPUTS = SimpleNamespace(load_power="", outside_temp="", weather="", sun="", presence=[]) + + +def write(tmp_path, model=None, params=None, tariff=True): + if model is not None: + (tmp_path / "model.json").write_text(json.dumps(model)) + if tariff: + t = {"v": 1, "kind": "tariff", "id": "t1", "site": SITE, "issued": START, "start": START, "step_s": 900, + "steps": STEPS, "expires": START + STEPS * 900, "currency": "EUR", "unit": "ct/kWh", + "import": [30.0] * STEPS, "export": [8.0] * STEPS, "estimated": [], "other": {}, "sources": []} + if params is not None: + t["params"] = params + (tmp_path / "tariff.json").write_text(json.dumps(t)) + return Bundles(str(tmp_path), SITE) + + +def model(occ_values=None, occ_start=START, sessions=None, **kw): + m = {"v": 1, "kind": "model", "id": "m1", "site": SITE, "issued": START - 3600, + "forecasts": {"load_w": {"profile": "hour_of_week", "values": [400.0] * 168}}} + if occ_values is not None: + m["forecasts"]["occupancy"] = {"profile": "hour_of_week", "values": [0.0] * 168, + "series": {"start": occ_start, "step_s": 900, "values": occ_values}} + if sessions is not None: + m["ev_sessions"] = sessions + m.update(kw) + return m + + +def collector(states: dict) -> Collector: + col = Collector() + col.on_entities({"a": {e: {"s": s, "a": {}} for e, s in states.items()}}) + return col + + +def state(b, controls=(), col=None, presence=None, inp=INPUTS, now=START): + return model_state(now, list(controls), inp, col or Collector(), b, None, "UTC", None, presence=presence) + + +def fixed(k, start=START): + h = ((start + k * 900) // 3600) % 24 + return 1 if 6 <= h < 22 else 0 + + +# -- occupancy ------------------------------------------------------------------- +def test_learnt_presence_after_the_presence_now(tmp_path): + occ = [0.0] * 40 + [0.5] * 40 + [0.1] * 112 # 400 values at most; 192 here + b = write(tmp_path, model(occ), {"comfort.occupied_min_share": 0.2}) + s = state(b, col=collector({"person.anna": "not_home", "device_tracker.ben": "home"}), + presence=["person.anna", "device_tracker.ben"]) + assert s["occupied"][:4] == [1, 1, 1, 1] # someone is home now (ben's tracker) + assert s["occupied"][4:40] == [0] * 36 and s["occupied"][40:80] == [1] * 40 and s["occupied"][80:] == [0] * 112 + src = s["sources"]["occupancy"] + assert (src["presence_now"], src["cloud"], src["fixed_hours"], src["source"], src["min_share"]) == (4, 188, 0, "learnt", 0.2) + assert "why" not in src and not [n for n in s["notes"] if n.startswith("occupancy")] + # nobody home now: the first hour unoccupied, then the forecast + s = state(b, col=collector({"person.anna": "not_home"}), presence=["person.anna"]) + assert s["occupied"][:4] == [0] * 4 + # a presence source without a value: the forecast from the start + s = state(b, col=collector({"person.anna": "unavailable"}), presence=["person.anna"]) + assert s["occupied"][:4] == [0] * 4 and s["sources"]["occupancy"]["presence_now"] == 0 + assert s["sources"]["occupancy"]["cloud"] == STEPS + # the series ends: the hour-of-week profile (all 0 here) for the rest + b = write(tmp_path, model([0.9] * 96), {"comfort.occupied_min_share": 0.2}) + s = state(b) + assert s["occupied"] == [1] * 96 + [0] * 96 + assert (s["sources"]["occupancy"]["cloud"], s["sources"]["occupancy"]["hour_of_week"]) == (96, 96) + assert s["sources"]["forecast"]["occupancy"]["cloud"] == 96 # with the load's and PV's + + +def test_no_presence_source_keeps_the_fixed_hours_and_says_so(tmp_path): + b = write(tmp_path, model(), {"comfort.occupied_min_share": 0.2}) + s = state(b) + assert s["occupied"] == [fixed(k) for k in range(STEPS)] + src = s["sources"]["occupancy"] + assert (src["source"], src["why"], src["fixed_hours"], src["presence_sources"]) == ("fixed_hours", "no_presence_source", STEPS, 0) + assert any("no presence source" in n and "06:00-22:00" in n for n in s["notes"]) + assert "refused" not in s or not s["refused"] # a quiet note, never an alarm + # a presence source without a learnt forecast yet: the presence now, then the fixed hours + s = state(b, col=collector({"binary_sensor.hall": "on"}), presence=["binary_sensor.hall"]) + assert s["occupied"][:4] == [1] * 4 and s["occupied"][4:] == [fixed(k) for k in range(4, STEPS)] + assert s["sources"]["occupancy"]["why"] == "no_forecast" + assert any("no presence forecast yet" in n for n in s["notes"]) + + +@pytest.mark.parametrize("params", [{}, {"comfort.occupied_min_share": 1.5}, {"comfort.occupied_min_share": "x"}, + {"comfort.occupied_min_share": True}, None]) +def test_a_missing_parameter_keeps_the_fixed_hours_and_names_it(tmp_path, params): + b = write(tmp_path, model([0.9] * STEPS), params, tariff=params is not None) + s = state(b) + assert s["occupied"] == [fixed(k) for k in range(STEPS)] + assert s["sources"]["occupancy"]["why"] == "no_parameter" + assert any("comfort.occupied_min_share" in n and "Parameters page" in n for n in s["notes"]) + + +def test_a_learnt_presence_never_occupied_keeps_the_fixed_hours(tmp_path): + """A learnt presence that never reaches the share over the horizon (three + test sites publish occupancy 0 all day) would hold every room at + setback for 48 h: the fixed hours instead, with a quiet note.""" + b = write(tmp_path, model([0.0] * STEPS), {"comfort.occupied_min_share": 0.2}) + s = state(b, col=collector({"person.anna": "not_home"}), presence=["person.anna"]) + assert s["occupied"][:4] == [0] * 4 # nobody home now: the presence now still first + assert s["occupied"][4:] == [fixed(k) for k in range(4, STEPS)] + src = s["sources"]["occupancy"] + assert (src["source"], src["why"]) == ("fixed_hours", "never_occupied") + assert any("never occupied" in n and "06:00-22:00" in n for n in s["notes"]) + + +def test_the_box_own_occupancy_model_first(tmp_path): + class Own: + def forecast(self, name, start, steps, ha, entity="", wind_unit=None): + if name != "occupancy": + return None + return [0.6] * 50 + [None] * (steps - 50), {"kind": "gbm"} + + def correct(self, series, start, values): + return list(values), 0.0 + b = write(tmp_path, model([0.0] * STEPS), {"comfort.occupied_min_share": 0.5}) + b.own = Own() + s = state(b) + assert s["occupied"][:50] == [1] * 50 and s["occupied"][50:] == [0] * (STEPS - 50) + assert (s["sources"]["occupancy"]["own"], s["sources"]["occupancy"]["cloud"]) == (50, STEPS - 50) + assert s["_cands"]["occupancy"]["own"][:50] == [0.6] * 50 # the live error per source (boxtrain) + + +def test_presence_entities_from_the_mapping(tmp_path): + """The controller's presence sources: the inputs' and the mapped + room..occupied and person..home, subscribed and planned on.""" + from cantabile_edge.controller import Controller + assert inputs.presence_asset("person.anna.home") and inputs.presence_asset("room.living.occupied") + assert not inputs.presence_asset("person.anna.away") and not inputs.presence_asset("room.living.temp") + ctl = Controller.__new__(Controller) + ctl.inputs = SimpleNamespace(presence=["binary_sensor.hall"], entities=lambda: ["binary_sensor.hall"], + outside_temp="") + ctl.mapping = SimpleNamespace(assets=[SimpleNamespace(asset="person.anna.home", entity="person.anna"), + SimpleNamespace(asset="room.bed.occupied", entity="binary_sensor.bed"), + SimpleNamespace(asset="room.bed.temp", entity="sensor.bed"), + SimpleNamespace(asset="person.ben.home", entity="binary_sensor.hall")], + by_asset={}) + ctl.controls = [] + assert ctl.presence_entities() == ["binary_sensor.hall", "person.anna", "binary_sensor.bed"] + assert {"person.anna", "binary_sensor.bed"} <= set(ctl.entities()) + + +# -- the EV session forecast --------------------------------------------------------- +def car(**params): + return Control("car", "ev", {"switch": "switch.car", "current": "number.car", "connected": "binary_sensor.car"}, True, + {"phases": 1, **params}) + + +def sessions(*rows, issued=START - 1800): + return {"issued": issued, "sessions": [{"arrive": a, "depart": d, "kwh": k} for a, d, k in rows], + "note": "from the plug state"} + + +def test_bundle_ev_sessions_checked(tmp_path): + good = sessions((START + 7200, START + 50400, 9.5), (START - 3600, None, None)) + b = write(tmp_path, model(sessions=good)) + ev = b.ev_sessions(START) + assert [s["arrive"] for s in ev["sessions"]] == [START - 3600, START + 7200] # by arrival + assert ev["sessions"][0] == {"arrive": START - 3600, "depart": None, "kwh": None} and ev["issued"] == START - 1800 + bad = dict(good, sessions=good["sessions"] + [{"arrive": "x"}, {"arrive": START, "depart": START - 1}, + {"arrive": START, "kwh": -2}, [1, 2]]) + b = write(tmp_path, model(sessions=bad)) + assert len(b.ev_sessions(START)["sessions"]) == 2 and "4 malformed" in b.ev_sessions_error + assert b.model_id() == "m1" # the rest of the bundle stays + for broken in ([1], {"issued": "x", "sessions": []}, {"issued": START, "sessions": {}}): + b = write(tmp_path, model(sessions=broken)) + assert b.ev_sessions(START) is None and b.ev_sessions_error and b.model_id() == "m1" + assert write(tmp_path, model(sessions=good, site="*")).ev_sessions(START) is None # a shared model: none + assert write(tmp_path, model(sessions=good, expires=START)).ev_sessions(START) is None # expired + assert write(tmp_path, model()).ev_sessions(START) is None + + +def ev_dev(s): + return next(d for d in s["devices"] if d["id"] == "car") + + +def test_plugged_in_car_takes_the_covering_session(tmp_path): + b = write(tmp_path, model(sessions=sessions((START - 3600, START + 10 * 3600 + 600, 12.0)))) + s = state(b, [car()], collector({"binary_sensor.car": "on", "switch.car": "off"})) + st = ev_dev(s)["state"] + assert st["session"] == {"dep_step": 40, "need_wh": 12000.0} # 18:10 -> the step before it ends + assert "need_wh" not in st and "departure" not in st # not the car's: not a known need + assert s["sources"]["ev"]["car"]["departure"] == "session forecast" and s["sources"]["ev"]["car"]["energy"] == "session forecast" + assert any("car" in n and "departure and energy from the session forecast (issued 2027-01-15 07:30 UTC)" in n + for n in s["notes"]) + # the car's own need wins; the departure still from the forecast + col = collector({"binary_sensor.car": "on", "sensor.need": "5"}) + col.states["sensor.need"]["a"] = {"unit_of_measurement": "kWh"} + c = Control("car", "ev", {"switch": "switch.car", "current": "number.car", "connected": "binary_sensor.car", + "energy_needed": "sensor.need"}, True, {"phases": 1}) + s = state(b, [c], col) + st = ev_dev(s)["state"] + assert st["need_wh"] == 5000.0 and st["session"] == {"dep_step": 40} + assert s["sources"]["ev"]["car"] == {"departure": "session forecast", "energy": "car", "issued": START - 1800} + # beyond the horizon: the plan's end + b = write(tmp_path, model(sessions=sessions((START - 3600, None, 30.0)))) + assert ev_dev(state(b, [car()], collector({"binary_sensor.car": "on"})))["state"]["session"]["dep_step"] == STEPS + # no session covers now: as before (the mapping's), no note + b = write(tmp_path, model(sessions=sessions((START + 3600, START + 7200, 5.0)))) + s = state(b, [car()], collector({"binary_sensor.car": "on"})) + assert "session" not in ev_dev(s)["state"] and s["sources"]["ev"]["car"]["departure"] == "mapping" + # no sessions at all: as today + s = state(write(tmp_path, model()), [car()], collector({"binary_sensor.car": "on"})) + assert "session" not in ev_dev(s)["state"] and "expected" not in ev_dev(s)["state"] + assert s["sources"]["ev"]["car"] == {"departure": "mapping", "energy": "mapping"} + + +def test_unplugged_car_gets_the_next_session_as_an_expected_load(tmp_path): + b = write(tmp_path, model(sessions=sessions((START - 7200, START - 3600, 3.0), (START + 9 * 3600 + 300, START + 23 * 3600, 9.5)))) + s = state(b, [car()], collector({"binary_sensor.car": "off"})) + st = ev_dev(s)["state"] + assert st["expected"] == {"from_step": 37, "to_step": 92, "need_wh": 9500.0} # from the step after it arrives + assert s["sources"]["ev"]["car"]["expected"]["kwh"] == 9.5 + assert any("not plugged in; an expected session" in n and "no charger command" in n for n in s["notes"]) + # a session without kWh: not planned, said + b = write(tmp_path, model(sessions=sessions((START + 3600, START + 7200, None)))) + s = state(b, [car()], collector({"binary_sensor.car": "off"})) + assert "expected" not in ev_dev(s)["state"] and any("has no kWh" in n for n in s["notes"]) + + +# -- the optimiser ------------------------------------------------------------------ +highspy = pytest.importorskip("highspy") + + +def house(devices, steps=96, price=None): + from cantabile_edge import optimizer # noqa: F401 + price = price or [12.0 if k < 24 else 40.0 if k >= 72 else 28.0 for k in range(steps)] + return {"v": 1, "start": START, "step_s": 900, "steps": steps, "tz": "UTC", + "price_import": price, "price_export": [8.0] * steps, "price_note": "test", + "load_w": [400.0] * steps, "pv_w": [0.0] * steps, "t_out": [5.0] * steps, + "sun": [0.0] * steps, "occupied": [1] * steps, "devices": devices, + "notes": ["occupancy: no presence source and no presence forecast: 06:00-22:00"]} + + +def ev(state): + return {"id": "car", "kind": "ev", "channels": ["switch", "current"], + "params": {"need_wh": 20000, "departure": "07:00", "min_current_a": 6, "max_current_a": 16, + "phases": 1, "voltage": 230}, + "state": state, "bounds": {"current_a": [0, 16, "device", "device"]}} + + +def test_session_departure_and_energy_in_the_plan(): + from cantabile_edge import optimizer + p = optimizer.plan(house([ev({"connected": True, "session": {"dep_step": 20, "need_wh": 6000.0}})]), 20) + on = [e for e in p["devices"]["car"] if e["set"] != "off"] + assert on and all(e["t"] < START + 20 * 900 for e in on) # before the forecast departure + assert p["notes"][0].startswith("occupancy:") # the inputs' notes in the plan's + # an expected session is not a known need: nothing to shift for the building + assert not [f for f in (p["flex"].get("shift") or {}).get("devices", []) if f.get("id") == "car"] + + +def test_expected_session_is_a_load_without_commands(): + from cantabile_edge import optimizer + exp = {"from_step": 40, "to_step": 80, "need_wh": 7000.0} + with_car = optimizer.plan(house([ev({"connected": False, "expected": exp})]), 20) + without = optimizer.plan(house([ev({"connected": False})]), 20) + assert with_car["devices"]["car"] == [] and without["devices"]["car"] == [] # no charger command + assert with_car["cost_eur"] > without["cost_eur"] + 1.5 # ~7 kWh at 28 ct seen + assert not [f for f in (with_car["flex"].get("shift") or {}).get("devices", []) if f.get("id") == "car"] + # the owner's ready-by: the expected session is not planned (it applies once plugged in) + s = house([dict(ev({"connected": False, "expected": exp}), pref={"dep_step": 60, "need_wh": 5000.0, "how": "must", "group": "car:ready", + "text": "ready by 23:00", "at": START + 60 * 900})]) + assert optimizer.plan(s, 20)["cost_eur"] == pytest.approx(without["cost_eur"], abs=0.01) diff --git a/src/edge/tests/test_co2_plan.py b/src/edge/tests/test_co2_plan.py new file mode 100644 index 0000000..74deb74 --- /dev/null +++ b/src/edge/tests/test_co2_plan.py @@ -0,0 +1,121 @@ +# Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved. +"""CO2 in the box's objective (docs/methods.md A2.15; backlog 47.7): the +tariff bundle's co2_electricity (g/kWh per slot) and co2 {gas, heat, +basis, electricity_source} (bundles.co2); the Parameters page's +co2.planner_eur_per_t weighs the grid import, gas and district heat (no +credit for export). Weight 0: cost only, as before, the plan still reports +its kg; the parameter missing: not weighed, a quiet note; a carrier +without a factor: unweighed, noted.""" +import json + +import pytest + +from cantabile_edge import bundles as bundles_mod + +highspy = pytest.importorskip("highspy") +from cantabile_edge import optimizer # noqa: E402 + +from test_optimizer import START # noqa: E402 + +SITE = "s1" + + +def ev(need=6000): + return {"id": "ev", "kind": "ev", "channels": ["switch", "current"], + "params": {"need_wh": need, "departure": "07:00", "min_current_a": 6, "max_current_a": 16, + "phases": 1, "voltage": 230}, + "state": {"connected": True}, "bounds": {"current_a": [0, 16, "device", "device"]}} + + +def flat_house(devices, steps=96, co2=None, weight=None, gas_f=181.4, heat_f=None): + """One import price all day (30 ct): nothing to shift for cost; the + grid's CO2 low 02:00-04:00 local (200 g), high otherwise (450 g).""" + hour = lambda k: (k // 4 + 1) % 24 # noqa: E731 (Berlin, winter) + s = {"v": 1, "start": START, "step_s": 900, "steps": steps, "tz": "Europe/Berlin", + "price_import": [30.0] * steps, "price_export": [8.0] * steps, "price_note": "test", + "load_w": [400.0] * steps, "pv_w": [0.0] * steps, "t_out": [5.0] * steps, + "sun": [0.0] * steps, "occupied": [1 if 6 <= hour(k) < 22 else 0 for k in range(steps)], + "devices": devices, "params": {}} + if co2 is not False: + s["co2"] = {"electricity": co2 or [200.0 if 2 <= hour(k) < 4 else 450.0 for k in range(steps)], + "gas": gas_f, "heat": heat_f, "basis": "direct", "electricity_source": "ENTSO-E hourly mix"} + if weight is not None: + s["params"]["co2.planner_eur_per_t"] = weight + return s + + +def charging(p): + hour = lambda t: ((t - START) // 3600 + 1) % 24 # noqa: E731 + return {hour(e["t"]) for e in p["devices"]["ev"] if e["set"] != "off"} + + +def test_the_bundle_carries_the_factors(tmp_path): + b = {"v": 1, "kind": "tariff", "id": "t1", "site": SITE, "issued": START, "start": START, "step_s": 900, + "steps": 192, "expires": START + 192 * 900, "import": [30.0] * 192, "export": [8.0] * 192, + "co2_electricity": [400.0] * 100 + [None] * 92, + "co2": {"gas": 181.4, "heat": None, "basis": "direct", "electricity_source": "UBA yearly 2024"}} + (tmp_path / "tariff.json").write_text(json.dumps(b)) + bd = bundles_mod.Bundles(str(tmp_path), SITE) + c = bd.co2(START, 900, 192, START + 10) + assert c["electricity"][0] == 400.0 and c["electricity"][99] == 400.0 and c["electricity"][100] is None + assert c["gas"] == 181.4 and c["heat"] is None and c["basis"] == "direct" + assert c["electricity_source"] == "UBA yearly 2024" + assert bd.co2(START, 900, 192, START + 192 * 900) == {} # expired: nothing held + b["co2_electricity"] = [-1.0] + (tmp_path / "tariff.json").write_text(json.dumps(b)) + assert bundles_mod.Bundles(str(tmp_path), SITE).co2(START, 900, 192, START + 10) == {} # refused bundle + + +def test_a_weight_shifts_load_to_the_low_co2_hours_at_equal_prices(): + p = optimizer.plan(flat_house([ev()], weight=100.0), 20) + assert charging(p) <= {2, 3}, p["devices"]["ev"] # 6 kWh in the 200 g hours + assert p["co2_kg"]["weight_eur_per_t"] == 100.0 and p["co2_basis"] == "direct" + # without a weight the same plan costs the same, its CO2 is higher + p0 = optimizer.plan(flat_house([ev()], weight=0.0), 20) + assert p0["cost_eur"] == pytest.approx(p["cost_eur"], abs=0.01) + assert p0["co2_kg"]["plan"] >= p["co2_kg"]["plan"] + # the weighed plan's CO2: 400 W all day at 450 g (200 g 02-04) and the car's 6 kWh at 200 g + base = sum(0.1 * (200.0 if 2 <= ((k // 4 + 1) % 24) < 4 else 450.0) for k in range(96)) / 1000.0 + assert p["co2_kg"]["plan"] == pytest.approx(base + 6.0 * 0.2, abs=0.05) + assert p["co2_kg"]["electricity_source"] == "ENTSO-E hourly mix" + + +def test_weight_zero_changes_nothing(): + s = flat_house([ev()], weight=0.0) + a = optimizer.plan(s, 20) + b = optimizer.plan(flat_house([ev()], co2=False), 20) # no factors at all: as before + assert a["devices"] == b["devices"] and a["cost_eur"] == b["cost_eur"] and a["baseline_eur"] == b["baseline_eur"] + assert "co2_kg" in a and "co2_kg" not in b + assert not any("co2" in n.lower() for n in a.get("notes") or []) + # the planned kg: the meter's import at each step's factor (400 W + the car's 6 kWh) + assert a["co2_kg"]["plan"] > 0 and a["co2_kg"]["carriers"]["electricity"] == a["co2_kg"]["plan"] + + +def test_the_parameter_missing_is_noted_and_not_weighed(): + p = optimizer.plan(flat_house([ev()]), 20) + assert "co2.planner_eur_per_t missing: CO2 not weighed (cost only)" in p["notes"] + assert "weight_eur_per_t" not in p["co2_kg"] + + +def test_a_carrier_without_a_factor_is_unweighed_and_noted(): + room = {"id": "heating", "kind": "heating", "channels": ["climate"], + "params": {"r_k_per_kw": 10, "c_kwh_per_k": 3, "comfort_c": 21, "setback_c": 17, "heat_source": "district", + "max_heat_w": 6000, "cop_curve": [], "source_options": {}}, + "state": {"temp_c": 19.0}, "bounds": {"temp_c": [16, 26, "owner", "owner"]}} + s = flat_house([room], weight=100.0, heat_f=None) + s["price_heat"] = [9.0] * 96 + p = optimizer.plan(s, 20) + assert any(n.startswith("no CO2 factor for heat") for n in p["notes"]) + assert p["co2_kg"].get("incomplete") is True and p["heat_eur"] > 0 + # with a factor: the district heat's CO2 counts, the same heat in plan and baseline + s = flat_house([room], weight=100.0, heat_f=150.0) + s["price_heat"] = [9.0] * 96 + p = optimizer.plan(s, 20) + assert p["co2_kg"]["carriers"]["heat"] > 0 and not p["co2_kg"].get("incomplete") + + +def test_export_earns_no_credit(): + s = flat_house([], weight=1000.0) + s["pv_w"] = [3000.0] * 96 + p = optimizer.plan(s, 20) + assert p["co2_kg"]["plan"] == 0.0 # exporting all day: no negative CO2 diff --git a/src/edge/tests/test_devpage.py b/src/edge/tests/test_devpage.py index 47f92ea..c925b7e 100644 --- a/src/edge/tests/test_devpage.py +++ b/src/edge/tests/test_devpage.py @@ -373,6 +373,91 @@ def test_support_session_banner_end_and_owners_choices(tmp_path): assert "Ended." in s.req("POST", "p=devices", {"do": "end-support"}, sup, ingress) +def test_hot_water_tank_ratings_and_idle_loss(tmp_path): + """Backlog 329 (docs/design/storage-losses.md): any HA water heater + used as a hot-water tank (control dhw_tank, consent off); its heater the + owner's choice; its ratings entered here as on the Hub (each above 0); + what it is not planned without as a warning; the loss's and a battery's + idle loss's source from the agent's latest plan; support may not change + them.""" + s = Site(tmp_path) + s.ha.reg["devices"].append({"id": "dev-tank", "name": "Tank", "manufacturer": "Stiebel Eltron", "model": "WWK 300", + "config_entries": ["e4"]}) + s.ha.reg["entities"].append(ent("water_heater.tank", "dev-tank", "wh1", "stiebel")) + s.ha.states.append(st("water_heater.tank", "eco", current_temperature=51.5, temperature=55, min_temp=35, max_temp=65)) + out = s.req() + assert "It could control: hot-water tank." in out + out = s.post(do="use", ha_device="dev-tank", profile="ha-water-heater", name="Tank") + dev_id = next(i for i, d in s.devices().items() if d["profile"] == "ha-water-heater") + tank = s.frag(dev_id)["controls"][0] + assert (tank["kind"], tank["consent"], tank["entities"]) == ("dhw_tank", False, {"water_heater": "water_heater.tank"}) + page = s.req(query=f"p=devices&d={dev_id}") + assert "Hot-water tank" in page and 'name="heater"' in page and "Choose its heater" in page + assert "Needed: the tank is not planned without it." in page + assert "the tank's volume (Ratings), its heater (above)" in page + assert 'name="f_rated_tank_volume_l"' in page and 'value="ratings"' in page and "tank 51.5 °C" in page + # the heater and the ratings: the owner's + assert "Saved." in s.post(do="tank", id=dev_id, heater="heat_pump") + assert s.frag(dev_id)["controls"][0]["params"]["heater"] == "heat_pump" + assert "the heater is one of" in s.post(do="tank", id=dev_id, heater="gas") + s.post(do="ratings", id=dev_id, f_rated_tank_volume_l="300", f_rated_tank_heater_kw="0.6", f_rated_tank_cop="") + assert s.devices()[dev_id]["ratings"] == {"tank_volume_l": 300.0, "tank_heater_kw": 0.6} + specs = json.loads((s.state / "devices-specs.json").read_text())["devices"][dev_id] + assert specs["ratings"]["tank_volume_l"] == 300.0 and specs["controls"] == [tank["id"]] + assert "0.01 to 1000" in s.post(do="ratings", id=dev_id, f_rated_tank_heater_kw="0", f_rated_tank_volume_l="300") + assert s.devices()[dev_id]["ratings"]["tank_heater_kw"] == 0.6 # refused: kept as it was + page = s.req(query=f"p=devices&d={dev_id}") + assert "the heat pump's COP (Ratings)" in page and "300 L · heater 0.6 kW" in page + assert 'value="300"' in page + # the agent's plan: the loss assumed at class D's limit (quiet, no alarm) + (s.state / "preferences-view.json").write_text(json.dumps({"v": 1, "planning": {"refused": {}, "storage": { + tank["id"]: {"kind": "dhw_tank", "heater": "heat_pump", "volume_l": 300, "standby_w": 122.0, "loss_src": "assumed", + "erp_class": "D", "temp_c": 51.5, "usable_kwh": 2.2}}}})) + page = s.req(query=f"p=devices&d={dev_id}") + assert "Needed:" not in page and "now 51.5 °C · 2.2 kWh usable" in page + assert "Standing loss 122 W assumed: class D's limit (Parameters). Enter the label's value below." in page + # support may not change what is the owner's + sup = {"x-remote-user-name": "cantabile-support"} + for form, why in (({"do": "tank", "id": dev_id, "heater": "element"}, "The tank's heater is the owner"), + ({"do": "ratings", "id": dev_id, "f_rated_tank_volume_l": "200"}, "The ratings are the owner")): + out = s.req("POST", f"p=devices&d={dev_id}", form, sup) + assert why in out, form + assert s.devices()[dev_id]["ratings"]["tank_volume_l"] == 300.0 + assert s.frag(dev_id)["controls"][0]["params"]["heater"] == "heat_pump" + + def german(): + i18n.use("de") + return s.req(query=f"p=devices&d={dev_id}") + import contextvars + out = contextvars.copy_context().run(german) + assert "Warmwasserspeicher" in out and "Warmhalteverlust 122 W angenommen" in out and "Nenndaten" in out + + +def test_battery_idle_loss_line(): + """A battery's idle loss with its source (design 2.3): learnt, the + owner's, assumed (a quiet line with what to do, never an alarm).""" + from cantabile_edge.devpage import battery_store_lines, ratings_html + assert battery_store_lines({"standby_w": 49.2, "standby_src": "learnt", "idle_loss_kwh_24h": 1.18, + "self_discharge_pct_month": 2, "self_discharge_src": "parameter"}) == [ + "Idle loss 49 W (learnt by the box) · about 1.18 kWh a day", "Self-discharge 2 %/month assumed (Parameters)"] + assert battery_store_lines({"standby_w": 13, "standby_src": "parameter"}) == [ + "Idle loss 13 W assumed (Parameters): enter the datasheet's value below."] + assert battery_store_lines({"standby_w": 30, "standby_src": "owner"}) == ["Idle loss 30 W (your rating)"] + assert battery_store_lines({"planned": False}) == [] + d = {"id": "hm8042-hybrid-1", "rating_fields": [ + {"name": "rated_battery_standby_w", "label": "x", "rating": "battery_standby_w", "value": None}], + "storage": [{"id": "battery", "kind": "battery", "standby_w": 13, "standby_src": "assumed"}]} + out = ratings_html(d) + assert out.index("Idle loss 13 W assumed") < out.index('name="f_rated_battery_standby_w"') + assert "box warn" not in out and "leave empty and the box learns it" in out + # a hot-water meter's ratings too (the add-on had no form for them) + out = ratings_html({"id": "ha-water-meter-1", "rating_fields": [ + {"name": "rated_dhw_kwh_per_m3", "label": "x", "rating": "dhw_kwh_per_m3", "value": 58.2}]}) + assert "From the meter and the installation" in out and 'value="58.2"' in out + assert "Hot water: kWh of heat per m³ drawn" in out + assert ratings_html({"id": "x", "rating_fields": []}) == "" + + @pytest.fixture(autouse=True) def english(): i18n.use("en") diff --git a/src/edge/tests/test_devprofiles.py b/src/edge/tests/test_devprofiles.py index 608257d..da24d71 100644 --- a/src/edge/tests/test_devprofiles.py +++ b/src/edge/tests/test_devprofiles.py @@ -142,3 +142,147 @@ def test_services_and_cantabile_not_offered(): {"id": "t", "name": "MD Thermostat", "manufacturer": "Realtek", "model": "wr3", "domains": ["esphome"]}], "entities": []} assert [o["id"] for o in dp.offers(reg, [])] == ["t"] + + +# --- storage with losses (docs/design/storage-losses.md 10.1-10.3) ------------------------ + +def water_heater(eid="water_heater.tank", **attrs): + return {"entity_id": eid, "device_id": "d", "unique_id": eid, + "attributes": dict({"current_temperature": 52, "temperature": 55, "min_temp": 35, "max_temp": 65}, **attrs)} + + +def test_storage_quantities_write_roles_and_ratings(): + for q, want in (("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")), ("dhw.energy", ("Wh", "counter"))): + assert dp.quantity_of(q) == want, q + assert {"water_heater", "sg_ready", "switch"} <= dp.WRITE_ROLES + # a tank's power is a diverter's watts (written); a battery's or a car's power is a reading + assert dp.is_write("dhw_tank", "power") and not dp.is_write("battery", "power") and not dp.is_write("ev", "power") + assert not dp.is_write("dhw_tank", "temp_top") and not dp.is_write("battery", "standby") + new = ("battery_standby_w", "battery_self_discharge_pct_month", "tank_volume_l", "tank_heater_kw", "tank_cop", + "tank_standby_w", "tank_erp_class", "tank_max_c", "tank_room_c", "tank_grossanlage") + assert all(k in dp.RATINGS for k in new) and len(dp.ERP_CLASSES) == 7 and dp.ERP_CLASSES[4] == "D" + assert dp.HEATERS == ("element", "heat_pump", "boiler", "district") + + +def test_battery_profiles_ask_for_the_idle_loss(): + for pid in ("hm8042-hybrid", "solaredge-sunspec", "huawei-sun2000", "victron-gx", "sma-sunny-boy", "fronius-gen24"): + rated = {f["rating"]: f for f in PROFILES[pid]["fields"] if f.get("rating")} + assert {"battery_standby_w", "battery_self_discharge_pct_month"} <= set(rated), pid + assert rated["battery_standby_w"]["optional"] and rated["battery_standby_w"]["min"] > 0, pid + assert "learns" in rated["battery_standby_w"]["label"], pid + + +def test_water_heater_fragment_consent_off_heater_chosen_after(): + """Any HA water_heater (ha-water-heater): a dhw_tank control on it, + consent off; its current temperature as the tank's; optional roles only + where the device has them; the heater the installer's choice.""" + p = PROFILES["ha-water-heater"] + ps = list(PROFILES.values()) + assert [x["id"] for x in dp.fitting(ps, {"manufacturer": "Stiebel", "model": "WWK"}, ["mqtt"], ["water_heater"])] \ + == ["ha-water-heater"] + s = dp.setup_for(p, ["mqtt"]) + power = {"entity_id": "sensor.tank_heater_power", "device_id": "d", "unique_id": "p", "device_class": "power"} + frag, missing = dp.mapping_for("tank-1", p, s, [water_heater(), power], "Cellar", set()) + tank = frag["controls"][0] + assert (tank["kind"], tank["consent"]) == ("dhw_tank", False) + assert tank["entities"] == {"water_heater": "water_heater.tank", "heater_power": "sensor.tank_heater_power"} + assert "heater" not in (tank.get("params") or {}) # never a guess + got = {a["asset"]: a for a in frag["assets"]} + assert got["dhw.temp_top"]["attribute"] == "current_temperature" and got["dhw.temp_top"]["unit"] == "°C" + assert got["dhw.heater_power"]["entity"] == "sensor.tank_heater_power" + assert "dhw.temp_bottom" in missing and not any("control" in m for m in missing) + assert not any(a["consent"] for a in frag["assets"]) + assert dp.tank_of(frag) == {"heater": ""} + assert dp.set_tank_heater(frag, {"heater": "heat_pump"}) == {"heater": "heat_pump"} + assert frag["controls"][0]["params"]["heater"] == "heat_pump" + for bad in ({"heater": "gas"}, {}): + with pytest.raises(dp.Fail): + dp.set_tank_heater(frag, bad) + with pytest.raises(dp.Fail): + dp.set_tank_heater({"controls": [{"kind": "battery"}]}, {"heater": "element"}) + # one writer per entity: the water heater's control writes it, not its power sensor + assert "water_heater.tank" in dp.control_writes(frag["controls"]) + assert "sensor.tank_heater_power" not in dp.control_writes(frag["controls"]) + + +def test_immersion_heater_on_a_relay_with_tank_sensors(): + """A tank without a water_heater entity: a relay and its sensors, found + by their names across HA (ha-immersion-heater; never offered by itself).""" + p = PROFILES["ha-immersion-heater"] + assert dp.fitting([p], {"manufacturer": "Shelly", "model": "Plus 1PM"}, ["shelly"], ["switch", "sensor.temperature"]) == [] + s = dp.setup_for(p, []) + ents = [{"entity_id": "switch.keller_heizstab", "unique_id": "r"}, + {"entity_id": "sensor.speicher_oben", "unique_id": "t1", "device_class": "temperature"}, + {"entity_id": "sensor.speicher_unten", "unique_id": "t2", "device_class": "temperature"}, + {"entity_id": "sensor.heizstab_power", "unique_id": "w", "device_class": "power"}, + {"entity_id": "switch.fridge", "unique_id": "f"}] + frag, missing = dp.mapping_for("tank-2", p, s, ents, None, set()) + c = frag["controls"][0] + assert c["kind"] == "dhw_tank" and c["params"] == {"heater": "element"} + assert c["entities"] == {"switch": "switch.keller_heizstab", "temp_top": "sensor.speicher_oben", + "temp_bottom": "sensor.speicher_unten", "heater_power": "sensor.heizstab_power"} + assert {a["asset"] for a in frag["assets"]} == {"dhw.temp_top", "dhw.temp_bottom", "dhw.heater_power"} + assert missing == [] + # without the bottom sensor and the power sensor: the control still, those roles left out + frag2, _ = dp.mapping_for("tank-3", p, s, ents[:2], None, set()) + assert frag2["controls"][0]["entities"] == {"switch": "switch.keller_heizstab", "temp_top": "sensor.speicher_oben"} + # without the top sensor: no control (a tank temperature is needed), reported + frag3, missing3 = dp.mapping_for("tank-4", p, s, ents[:1], None, set()) + assert frag3["controls"] == [] and "dhw_tank control (temp_top)" in missing3 + + +def test_rating_values_above_zero(): + p = PROFILES["ha-water-heater"] + got = dp.rating_values(p, {"rated_tank_volume_l": "300", "rated_tank_erp_class": "3", "rated_tank_cop": " ", + "nope": "5"}) + assert got == {"rated_tank_volume_l": 300.0, "rated_tank_erp_class": 3} + assert dp.ratings_of(p, got) == {"tank_volume_l": 300.0, "tank_erp_class": 3} + for bad in ({"rated_tank_volume_l": "0"}, {"rated_tank_volume_l": "-5"}, {"rated_tank_erp_class": "8"}, + {"rated_tank_cop": "abc"}, {"rated_tank_grossanlage": "0"}): + with pytest.raises(dp.Fail): + dp.rating_values(p, bad) + f = {"name": "x", "label": "X", "type": "number", "rating": "battery_kwh", "min": 0} + with pytest.raises(dp.Fail, match="above 0"): + dp.rating_value(f, "0") + fields = dp.rating_fields(p, {"ratings": {"tank_volume_l": 300.0}}) + assert next(x["value"] for x in fields if x["rating"] == "tank_volume_l") == 300.0 + assert next(x["value"] for x in fields if x["rating"] == "tank_cop") is None + + +def test_storage_from_the_plan(): + """Both Devices pages: a battery's idle loss with its source, a tank's + facts, what it is not planned without (design 10.5).""" + frag = {"controls": [{"id": "battery", "kind": "battery", "entities": {"charge_from_grid": "switch.x"}}, + {"id": "dhw_tank", "kind": "dhw_tank", "entities": {"water_heater": "water_heater.t"}, + "params": {"heater": "heat_pump"}}, + {"id": "heating", "kind": "heating", "entities": {"climate": "climate.y"}}]} + # no plan yet: the tank's gaps from what the installer and the owner gave + out = dp.storage_of(frag, {"tank_volume_l": 300}, {}) + assert [x["kind"] for x in out] == ["battery", "dhw_tank"] + assert out[0] == {"id": "battery", "kind": "battery", "planned": False} + assert out[1]["missing"] == ["max_power_w", "cop"] and out[1]["volume_l"] == 300 and not out[1]["planned"] + out = dp.storage_of(frag, {"tank_volume_l": 300, "tank_heater_kw": 1.2, "tank_cop": 2.8}, None) + assert out[1]["missing"] == [] and out[1]["heater_kw"] == 1.2 and out[1]["cop"] == 2.8 + # the plan's word + planning = {"storage": {"battery": {"kind": "battery", "standby_w": 49.0, "standby_src": "learnt", + "self_discharge_pct_month": 2.0, "self_discharge_src": "parameter", + "idle_loss_kwh_24h": 1.18, "standby_in_load": None}, + "dhw_tank": {"kind": "dhw_tank", "heater": "heat_pump", "volume_l": 300, "standby_w": 122.0, + "loss_src": "assumed", "erp_class": "D", "temp_c": 51.5, "usable_kwh": 2.2}}, + "refused": {}} + bat, tank = dp.storage_of(frag, {}, planning) + assert bat == {"id": "battery", "kind": "battery", "planned": True, "standby_w": 49.0, "standby_src": "learnt", + "self_discharge_pct_month": 2.0, "self_discharge_src": "parameter", "idle_loss_kwh_24h": 1.18} + assert tank["planned"] and tank["missing"] == [] and (tank["loss_src"], tank["erp_class"]) == ("assumed", "D") + # refused by the plan: its missing facts + planning = {"storage": {}, "refused": {"dhw_tank": {"why": "tank volume unknown", "missing": ["volume_l"]}}} + tank = dp.storage_of(frag, {}, planning)[1] + assert tank["refused"] and tank["missing"] == ["volume_l"] and not tank["planned"] + # a mapping's facts count as given; a device's volume entity too + frag["controls"][1]["params"] = {"heater": "element", "max_power_w": 3000} + frag["controls"][1]["entities"]["volume"] = "sensor.v" + assert dp.storage_of(frag, {}, {})[1]["missing"] == [] and dp.storage_of(frag, {}, {})[1]["heater_kw"] == 3.0 + frag["controls"][1]["entities"] = {"switch": "switch.r"} + assert dp.storage_of(frag, {"tank_volume_l": 200}, {})[1]["missing"] == ["temp_sensor"] diff --git a/src/edge/tests/test_dhw.py b/src/edge/tests/test_dhw.py new file mode 100644 index 0000000..3c28345 --- /dev/null +++ b/src/edge/tests/test_dhw.py @@ -0,0 +1,132 @@ +# Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved. +"""A hot-water meter (the owner, 2026-11-06; docs/methods.md B16): its +assets (dhw.energy, dhw.volume in litres from L or m³, dhw.power) in the +mapping, the proposal (the sim's entities too) and the panel's words; the +installer's unit and kWh per m³ (or the cold and hot water's +temperatures), else the Parameters row dhw.temperature_lift_k, sent in +the inventory with its source; a boiler's part load as the inventory's +facts. The hot water's cost in the plan: test_heat_outlook.py (a tank +between the demand and its heater is backlog 329).""" +import pytest + +from cantabile_edge import controls, devpage, mapping, propose + +START = 1793232000 # 2026-10-29 00:00 UTC (01:00 in Berlin) + + +# -- the meter: mapping, proposal, words ------------------------------------------------- +def test_volume_in_litres_from_l_and_m3(): + assert mapping.convert(120.0, "L", "L") == 120.0 + assert mapping.convert(0.25, "m³", "L") == 250.0 + assert mapping.convert(3.0, "gal", "L") is None # never a guess at the scale + assert mapping.convert(5.0, "m³", "m³") == 5.0 # a unit kept as it is stays as it was + + +def test_suggest_maps_a_hot_water_meter_only_where_it_clearly_is_one(): + states = [ + {"entity_id": "sensor.hot_water_volume", "state": "1234.5", + "attributes": {"device_class": "water", "unit_of_measurement": "m³", "state_class": "total_increasing", + "friendly_name": "Hot water volume"}}, + {"entity_id": "sensor.warmwasser_waerme", "state": "812", + "attributes": {"device_class": "energy", "unit_of_measurement": "kWh", "state_class": "total_increasing", + "friendly_name": "Warmwasser Wärmemenge"}}, + {"entity_id": "sensor.cold_water", "state": "88", + "attributes": {"device_class": "water", "unit_of_measurement": "m³", "state_class": "total_increasing", + "friendly_name": "Cold water meter"}}, + {"entity_id": "sensor.water_heater_power", "state": "2000", + "attributes": {"device_class": "power", "unit_of_measurement": "W", "friendly_name": "Hot water heater power"}}, + {"entity_id": "sensor.dhw_temp", "state": "52", + "attributes": {"device_class": "temperature", "unit_of_measurement": "°C", "friendly_name": "DHW temperature"}}, + ] + got = {a["entity"]: a for a in mapping.suggest(states, {})["assets"]} + assert got["sensor.hot_water_volume"]["asset"] == "dhw.volume" + assert got["sensor.hot_water_volume"]["unit"] == "L" and got["sensor.hot_water_volume"]["kind"] == "counter" + assert got["sensor.warmwasser_waerme"]["asset"] == "dhw.energy" and got["sensor.warmwasser_waerme"]["unit"] == "Wh" + assert "sensor.cold_water" not in got # water drawn: hot water only + assert got["sensor.water_heater_power"]["asset"] != "dhw.power" # a heater's electricity is no hot-water meter + assert not got["sensor.dhw_temp"]["asset"].startswith("dhw.") + # the proposal keeps Cantabile's quantities: the meter's two are among them + out = propose.by_name(states, {}, propose.Registry(states, {}), propose.Taken()) + assert {a["asset"] for a in out} >= {"dhw.volume", "dhw.energy"} + + +def test_the_quantities_and_their_words(): + for q, (unit, kind) in {"dhw.energy": ("Wh", "counter"), "dhw.volume": ("L", "counter"), + "dhw.power": ("W", "gauge")}.items(): + assert propose.QUANTITIES[q] == (unit, kind) + assert q in devpage.QUANTITY_WORDS + + +def test_a_mapped_volume_meter_reads_litres(tmp_path): + p = tmp_path / "mapping.yaml" + p.write_text("version: 3\nassets:\n - {entity: sensor.hw, asset: dhw.volume, kind: counter, unit: L, consent: true}\n" + " - {entity: sensor.hw2, asset: dhw.volume_2, kind: counter, unit: L, unit_in: m³, kwh_per_m3: 52}\n") + m = mapping.Mapping.load(str(p)) + a, b = m.by_asset["dhw.volume"], m.by_asset["dhw.volume_2"] + assert a.unit == "L" and a.ha_unit("m³") == "m³" and mapping.convert(1.5, a.ha_unit("m³"), a.unit) == 1500.0 + # the installer's unit over HA's (none, or a wrong one) + assert b.ha_unit(None) == "m³" and b.ha_unit("L") == "m³" and b.kwh_per_m3 == 52 + p.write_text("version: 3\nassets:\n - {entity: sensor.hw, asset: dhw.volume, kind: counter, unit: L, unit_in: kWh}\n") + with pytest.raises(ValueError): + mapping.Mapping.load(str(p)) # kWh never becomes litres + + +def test_the_sims_hot_water_entities_are_proposed(): + states = [{"entity_id": "sensor.sim_munich_3_dhw_energy", "state": "1520.4", + "attributes": {"device_class": "energy", "unit_of_measurement": "kWh", "state_class": "total_increasing", + "friendly_name": "Sim Munich 3 DHW energy"}}, + {"entity_id": "sensor.sim_munich_4_dhw_volume", "state": "12.31", + "attributes": {"device_class": "water", "unit_of_measurement": "m³", "state_class": "total_increasing"}}] + out = {a["entity"]: a["asset"] for a in propose.by_name(states, {}, propose.Registry(states, {}), propose.Taken())} + assert out == {"sensor.sim_munich_3_dhw_energy": "dhw.energy", "sensor.sim_munich_4_dhw_volume": "dhw.volume"} + + +def test_the_meters_factor_installer_parameter_or_none(): + from cantabile_edge import devprofiles as dp + assert dp.dhw_factor({"dhw_kwh_per_m3": 50.0}, {"dhw.temperature_lift_k": 40}) == (50.0, "installer", "") + k, src, note = dp.dhw_factor({"dhw_cold_c": 10, "dhw_hot_c": 55}, {}) + assert (k, src, note) == (pytest.approx(52.335), "installer", "") + k, src, note = dp.dhw_factor({}, {"dhw.temperature_lift_k": 40}) + assert k == pytest.approx(46.52) and src == "parameter" and "dhw.temperature_lift_k (40 K)" in note + k, src, note = dp.dhw_factor({}, {}) + assert k is None and src == "" and "not converted" in note + # the unit the owner gives (1: L, 1000: m³) into the device's fragment + frag = {"assets": [{"entity": "sensor.w", "asset": "dhw.volume", "unit": "L"}]} + assert dp.meter_unit(frag, {"dhw_litres_per_unit": 1000}) and frag["assets"][0]["unit_in"] == "m³" + assert not dp.meter_unit(frag, {"dhw_litres_per_unit": 1000}) + assert dp.meter_unit(frag, {}) and "unit_in" not in frag["assets"][0] + + +def test_the_inventory_carries_the_factor_and_its_source(): + from cantabile_edge import inventory + m = mapping.Mapping(3, [mapping.Asset("sensor.hw", "dhw.volume", "counter", "L", consent=True, cold_c=10.0, + hot_c=50.0)]) + reg = {"devices": [{"id": "d1", "manufacturer": "Itron", "model": "Hydrus"}], + "entities": [{"entity_id": "sensor.hw", "device_id": "d1"}]} + inv = inventory.build(m, reg, {}, {}, START, None, {"dhw.temperature_lift_k": 40}) + d = inv["devices"][0] + assert d["ratings"]["dhw_kwh_per_m3"] == pytest.approx(46.52) and d["rating_sources"] == {"dhw_kwh_per_m3": "installer"} + assert "notes" not in inv + # a device's ratings (the Devices page) over the asset's, the parameter's as the last word + spec = {"devices": {"meter-1": {"entities": ["sensor.hw"], "ratings": {"dhw_kwh_per_m3": 48.0}}}} + d = inventory.build(m, reg, spec, {}, START, None, {})["devices"][0] + assert d["ratings"]["dhw_kwh_per_m3"] == 48.0 + m = mapping.Mapping(3, [mapping.Asset("sensor.hw", "dhw.volume", "counter", "L")]) + inv = inventory.build(m, reg, {}, {}, START, None, {"dhw.temperature_lift_k": 40}) + assert inv["devices"][0]["rating_sources"] == {"dhw_kwh_per_m3": "parameter"} and inv["notes"] + inv = inventory.build(m, reg, {}, {}, START, None, {}) + assert "dhw_kwh_per_m3" not in inv["devices"][0]["ratings"] and "not converted" in inv["notes"][0] + + +def test_the_inventory_carries_a_boilers_part_load_as_facts(): + from cantabile_edge import inventory + c = controls.parse([{"id": "heating", "kind": "heating", "entities": {"climate": "climate.b"}, + "params": {"heat_source": "boiler", "boiler_type": "condensing", + "part_load_curve": [[0.3, 1.09], [1.0, 1.0]]}}], set()) + m = mapping.Mapping(3, [], c) + reg = {"devices": [{"id": "d1", "manufacturer": "Vaillant"}], "entities": [{"entity_id": "climate.b", "device_id": "d1"}]} + d = inventory.build(m, reg, {}, {}, START)["devices"][0] + assert d["facts"] == {"boiler_type": "condensing", "part_load_curve": [[0.3, 1.09], [1.0, 1.0]]} + assert "boiler_type" not in d["ratings"] + + diff --git a/src/edge/tests/test_heat_outlook.py b/src/edge/tests/test_heat_outlook.py new file mode 100644 index 0000000..6c31701 --- /dev/null +++ b/src/edge/tests/test_heat_outlook.py @@ -0,0 +1,227 @@ +# Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved. +"""The heat outlook (docs/methods.md A2.16; backlog 45.3, the box's part, +and the hot water): the heat no model in the plan decides, the site's +space heat where no room model plans it (every heating control refused, +or none) and its hot water drawn (an unshiftable demand today: a tank +between it and its heater is backlog 329), each a heat_demand delivered +when demanded by the site's source (HeatSupply: a boiler's gas by its +efficiency at the load, district heat as it is) at the carrier's price +and CO2; a fixed labelled term of cost_eur (cost_parts.heat_outlook_eur) +and of the baseline; the household's costs view says it. Rooms planned by +their model are unchanged; their hot water is costed by their boiler.""" +import json +from types import SimpleNamespace + +import pytest + +from cantabile_edge import costs as costs_mod +from cantabile_edge.bundles import Bundles +from cantabile_edge.controls import parse as parse_controls, parse_inputs +from cantabile_edge.inputs import Collector, heat_site, model_state + +highspy = pytest.importorskip("highspy") +from cantabile_edge import optimizer # noqa: E402 + +from test_heat_sources import START, house, room # noqa: E402 + +SITE = "ab" * 16 +TZ = "Europe/Berlin" + + +def heat_forecast(steps=96): + return [3000.0 if k < 24 else 1500.0 for k in range(steps)] # 6 h at 3 kW, then 1.5 kW: 45 kWh + + +def hot_water(steps=96): + """A synthetic hot-water forecast: 3 kW drawn 19:00-20:00 local, 200 W + 06:00-08:00: 3.4 kWh a day.""" + hour = lambda k: (k // 4 + 1) % 24 # noqa: E731 + return [3000.0 if 19 <= hour(k) < 20 else 200.0 if 6 <= hour(k) < 8 else 0.0 for k in range(steps)] + + +def outlook_state(site, steps=96, gas=None, heat=None, rooms=(), dhw=None): + s = house(list(rooms), steps=steps, gas=gas, heat=heat) + s["heat_site"] = dict({"space": True}, **site) + s["heat_w"] = heat_forecast(steps) + if dhw is not None: + s["dhw_w"] = dhw + return s + + +def test_a_refused_boiler_room_gets_the_gas_outlook(): + s = outlook_state({"from": "heating", "source": "boiler", "boiler_efficiency": 0.9}, gas=12.0) + p = optimizer.plan(s, 20) + o = p["heat_outlook"] + heat_kwh = (24 * 3000 + 72 * 1500) * 0.25 / 1000 # 45 kWh + assert o["carrier"] == "gas" and o["heat_kwh"] == pytest.approx(heat_kwh) + assert o["input_kwh"] == pytest.approx(heat_kwh / 0.9, abs=0.01) + assert o["eur"] == pytest.approx(heat_kwh / 0.9 * 0.12, abs=0.01) + assert set(o["lines"]) == {"space"} and o["lines"]["space"]["heat_w"][:2] == [3000, 3000] + # a fixed term of the plan's cost and of its baseline, labelled + assert p["cost_parts"]["heat_outlook_eur"] == o["eur"] + house_eur = 400 * 24 / 1000 * 0.30 + assert p["cost_eur"] == pytest.approx(house_eur + o["eur"], abs=0.02) + assert p["baseline_eur"] == pytest.approx(house_eur + o["eur"], abs=0.02) + assert "no boiler_type or part_load_curve: one constant efficiency" in o["part_load"] + # no hot-water meter at this site: quietly said, never an alarm + assert any(n.startswith("heat outlook: no hot-water forecast") for n in p["notes"]) + + +def test_the_hot_water_is_a_line_of_its_own(): + s = outlook_state({"from": "heating", "source": "boiler", "boiler_efficiency": 0.9}, gas=12.0, dhw=hot_water()) + s["co2"] = {"electricity": [400.0] * 96, "gas": 181.4, "heat": None, "basis": "direct"} + o = optimizer.plan(s, 20)["heat_outlook"] + w = o["lines"]["dhw"] + assert w["heat_kwh"] == pytest.approx(3.4) and w["input_kwh"] == pytest.approx(3.4 / 0.9, abs=0.01) + assert w["eur"] == pytest.approx(3.4 / 0.9 * 0.12, abs=0.01) + assert w["co2_kg"] == pytest.approx(3.4 / 0.9 * 0.1814, abs=0.01) + assert o["eur"] == pytest.approx(o["lines"]["space"]["eur"] + w["eur"], abs=0.011) + assert o["heat_kwh"] == pytest.approx(48.4) + + +def test_a_planned_rooms_hot_water_by_its_boiler(): + # the room's model makes the space heat; its boiler's hot water is costed apart, the space heat not again + s = house([room("boiler", boiler_efficiency=0.9, max_heat_w=9000)], gas=12.0) + s["heat_site"] = {"from": "heating", "source": "boiler", "boiler_efficiency": 0.9, "max_heat_w": 9000.0, + "space": False} + s["dhw_w"] = hot_water() + p = optimizer.plan(s, 20) + o = p["heat_outlook"] + assert set(o["lines"]) == {"dhw"} and o["eur"] == pytest.approx(3.4 / 0.9 * 0.12, abs=0.01) + assert p["cost_parts"]["heat_outlook_eur"] == o["eur"] and p["gas_eur"] > 0 + assert p["cost_eur"] == pytest.approx(sum(p["cost_parts"].values()), abs=0.03) + # without the forecast: no outlook, a quiet note + del s["dhw_w"] + p = optimizer.plan(s, 20) + assert "heat_outlook" not in p and any("no hot-water forecast" in n for n in p["notes"]) + + +def test_the_outlook_uses_the_part_load_curve(): + site = {"from": "heating", "source": "boiler", "boiler_efficiency": 0.88, "max_heat_w": 10000.0, + "boiler_type": "condensing"} + s = outlook_state(site, gas=12.0) + s["params"]["boiler.part_load_condensing"] = [[0.3, 1.094], [1.0, 1.0]] + o = optimizer.plan(s, 20)["heat_outlook"] + # 3 kW and 1.5 kW are both at or below 30 % of 10 kW: 0.88 x 1.094 + assert o["input_kwh"] == pytest.approx(45.0 / (0.88 * 1.094), abs=0.02) + assert o["part_load"] == "boiler.part_load_condensing" + + +def test_one_supply_for_a_room_and_the_outlook(): + """The heat a room's boiler makes and the heat the outlook costs come from + the same HeatSupply: its input for a given heat is the same.""" + s = outlook_state({"from": "h", "source": "boiler", "boiler_efficiency": 0.88, "max_heat_w": 10000.0, + "boiler_type": "standard"}, gas=12.0) + s["params"]["boiler.part_load_standard"] = [[0.3, 0.969], [1.0, 1.0]] + m = optimizer.Model(optimizer._prepare(s)) + sup = optimizer.HeatSupply(m, "h", s["heat_site"], "boiler") + assert sup.input_w(2000.0) == pytest.approx(2000.0 / (0.88 * 0.969)) + assert sup.input_w(10000.0) == pytest.approx(10000.0 / 0.88) + assert sup.input_w(12000.0) == pytest.approx(10000.0 / 0.88 + 2000.0 / 0.88) # beyond its most: full load + assert sup.cost_wh(0) == pytest.approx(0.25 / 1000 * 0.12) + assert optimizer.heat_demand(s, "space", 4) == [3000.0] * 4 and optimizer.heat_demand(s, "dhw", 4) is None + + +def test_district_heat_by_its_price_and_co2(): + s = outlook_state({"from": "the site's heat price", "source": "district"}, heat=10.0) + s["co2"] = {"electricity": [400.0] * 96, "gas": 181.4, "heat": 200.0, "basis": "direct"} + p = optimizer.plan(s, 20) + o = p["heat_outlook"] + assert o["carrier"] == "heat" and o["eur"] == pytest.approx(4.5, abs=0.01) + assert o["co2_kg"] == pytest.approx(45.0 * 0.2, abs=0.01) + assert p["co2_kg"]["carriers"]["heat"] == pytest.approx(9.0, abs=0.01) + + +def test_no_outlook_without_a_fact_quietly(): + p = optimizer.plan(outlook_state({"from": "heating", "source": "boiler"}, gas=12.0), 20) + assert "heat_outlook" not in p and "heat outlook: the boiler's efficiency unknown" in p["notes"] + p = optimizer.plan(outlook_state({"from": "heating", "source": "boiler", "boiler_efficiency": 0.9}), 20) + assert "heat_outlook" not in p and "heat outlook: no gas price" in p["notes"] + s = outlook_state({"from": "heating", "source": "district"}, heat=10.0) + s["heat_w"] = None + p = optimizer.plan(s, 20) + assert "heat_outlook" not in p and "heat outlook: no heat forecast for this site" in p["notes"] + assert "heat_outlook_eur" not in p["cost_parts"] + + +def test_the_sites_heat_source(): + c = parse_controls([{"id": "heating", "kind": "heating", "entities": {"climate": "climate.heating"}, + "params": {"heat_source": "boiler", "boiler_efficiency": 0.9, "max_heat_w": 9000, + "r_k_per_kw": 10, "c_kwh_per_k": 3}}], set())[0] + # planned: its model makes the space heat; its boiler still heats the hot water + site = heat_site([c], [{"id": "heating", "kind": "heating"}], None, [12.0], [None]) + assert site["source"] == "boiler" and site["space"] is False + # refused: its source and facts, the space heat too + site = heat_site([c], [], None, [12.0], [None]) + assert site["source"] == "boiler" and site["boiler_efficiency"] == 0.9 and site["from"] == "heating" and site["space"] + # no heating control: the mapping's inputs.heat, else district heat where only heat is priced + inp = parse_inputs({"heat": {"source": "boiler", "boiler_efficiency": 0.92}}) + assert heat_site([], [], inp, [12.0], [None])["boiler_efficiency"] == 0.92 + assert heat_site([], [], None, [None], [9.0]) == {"from": "the site's heat price", "source": "district", "space": True} + assert heat_site([], [], None, [12.0], [None]) == {} + with pytest.raises(ValueError): + parse_inputs({"heat": {"source": "coal"}}) + # a heat pump's heat is electricity, in the metered load already: none + hp = parse_controls([{"id": "hp", "kind": "heating", "entities": {"climate": "climate.hp"}, + "params": {"heat_source": "heat_pump", "cop": 3}}], set())[0] + assert heat_site([hp], [], None, [None], [None]) == {} + # a planned room's plan without a heat_site: as before + p = optimizer.plan(house([room("boiler", boiler_efficiency=0.9, max_heat_w=9000)], gas=12.0), 20) + assert "heat_outlook" not in p + + +INPUTS = SimpleNamespace(load_power="", outside_temp="", weather="", sun="", presence=[]) + + +def bundles(tmp_path): + m = {"v": 1, "kind": "model", "id": "m1", "site": SITE, "issued": 1, + "forecasts": {"load_w": {"profile": "hour_of_week", "values": [400] * 168}, + "heat_w": {"profile": "hour_of_week", "values": [2000] * 168}, + "dhw_w": {"profile": "hour_of_week", "values": [150] * 168}}} + (tmp_path / "model.json").write_text(json.dumps(m)) + t = {"v": 1, "kind": "tariff", "id": "t1", "site": SITE, "issued": START, "start": START, "step_s": 900, + "steps": 192, "expires": START + 192 * 900, "import": [30.0] * 192, "export": [8.0] * 192, + "gas": [12.0] * 192, "params": {}} + (tmp_path / "tariff.json").write_text(json.dumps(t)) + return Bundles(str(tmp_path), SITE) + + +def test_the_model_state_fetches_the_heat_forecasts(tmp_path): + b = bundles(tmp_path) + col = Collector() + col.on_entities({"a": {"climate.heating": {"s": "heat", "a": {"current_temperature": 20.0, "temperature": 20.0}}}}) + # no R/C: the room is refused; its boiler's facts give the outlook of the space heat and the hot water + c = parse_controls([{"id": "heating", "kind": "heating", "entities": {"climate": "climate.heating"}, + "params": {"heat_source": "boiler", "boiler_efficiency": 0.9, "max_heat_w": 9000}}], set())[0] + s = model_state(START + 10, [c], INPUTS, col, b, None, TZ, None) + assert "heating" in s["refused"] + assert s["heat_site"]["source"] == "boiler" and s["heat_w"][:3] == [2000.0] * 3 and s["dhw_w"][:3] == [150.0] * 3 + p = optimizer.plan(s, 20) + assert p["heat_outlook"]["eur"] == pytest.approx((2000 + 150) * 192 * 0.25 / 1000 / 0.9 * 0.12, abs=0.02) + # planned (the mapping's R and C): the hot water only, the space heat is the room's model's + c = parse_controls([{"id": "heating", "kind": "heating", "entities": {"climate": "climate.heating"}, + "params": {"heat_source": "boiler", "boiler_efficiency": 0.9, "max_heat_w": 9000, + "r_k_per_kw": 10, "c_kwh_per_k": 3}}], set())[0] + s = model_state(START + 10, [c], INPUTS, col, b, None, TZ, None) + assert not s["refused"] and "heat_w" not in s and s["dhw_w"][:1] == [150.0] + + +def test_the_costs_view_says_the_expected_heat(tmp_path): + class B: + def box_params(self, now): + return {"costs.forecast_days": 7} + + def fixed_charges(self, now): + return None + + def slot_prices(self, ts, now=None): + return None + led = costs_mod.Ledger(str(tmp_path), B(), clock=lambda: START + 60) + led.take_plan({"start": START, "step_s": 900, "steps": 192, + "heat_outlook": {"carrier": "gas", "eur": 6.0, "input_kwh": 50.0}}) + out = costs_mod.costs_section(led, START + 60, "en", {}, lambda *a: None) + assert out["heat_outlook"]["eur"] == 6.0 + assert "Expected for heat (Gas) over the next 48 h: " in out["md"] and "50.0 kWh" in out["md"] + de = costs_mod.costs_section(led, START + 60, "de", {}, lambda *a: None) + assert "Erwartet für Wärme (Gas) in den nächsten 48 h" in de["md"] + led.close() diff --git a/src/edge/tests/test_heating_oil.py b/src/edge/tests/test_heating_oil.py new file mode 100644 index 0000000..5bcdeb7 --- /dev/null +++ b/src/edge/tests/test_heating_oil.py @@ -0,0 +1,84 @@ +# Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved. +"""An oil boiler (docs/methods.md E15, branch heating-oil): its fuel priced +and weighed at heating oil's price and CO2 (never gas's), refused without an +oil price or with an unknown fuel; the bundle's oil series; the household's +costs from an oil meter's litres.""" +import json + +import pytest + +from cantabile_edge import bundles as bundles_mod +from cantabile_edge import costs, inputs +from test_heat_sources import START, house, parse, room + +highspy = pytest.importorskip("highspy") +from cantabile_edge import optimizer # noqa: E402 + + +def test_oil_boiler_is_priced_by_oil_not_gas(): + s = house([room("boiler", boiler_efficiency=0.9, max_heat_w=9000, fuel="oil")], gas=99.0) + s["price_oil"] = [11.0] * s["steps"] + p = optimizer.plan(s, 20) + assert p["oil_eur"] > 0 and p["gas_eur"] == 0 + assert p["saving_parts"] is None or "gas" not in (p.get("saving_parts") or {}) + m = optimizer.Model(optimizer._prepare(s)) + m.solve(20) + val = m.h.getSolution().col_value + v = m.devices["heating"][1] + assert v["fuel"] == "oil" + oil_wh = sum(val[g.index] for g in v["gas"]) * 0.25 + assert abs(p["oil_eur"] - round(oil_wh / 1000 * 0.11, 2)) < 0.02 + + +def test_gas_boiler_unchanged_without_a_fuel(): + s = house([room("boiler", boiler_efficiency=0.9, max_heat_w=9000)], gas=12.0) + s["price_oil"] = [1.0] * s["steps"] # an oil price never prices a gas boiler + p = optimizer.plan(s, 20) + assert p["gas_eur"] > 0 and "oil_eur" not in p + + +def test_oil_co2_weighed_with_its_factor(): + s = house([room("boiler", boiler_efficiency=0.9, max_heat_w=9000, fuel="oil")]) + s["price_oil"] = [11.0] * s["steps"] + s["co2"] = {"electricity": [400.0] * s["steps"], "gas": 1000.0, "oil": 266.4, "heat": None, "basis": "direct"} + m = optimizer.Model(optimizer._prepare(s)) + assert m.co2_factor("oil", 0) == 266.4 + sup = optimizer.HeatSupply(m, "heating", s["devices"][0]["params"], "boiler") + assert sup.carrier == "oil" and sup.prices[0] == 11.0 + + +def test_refused_without_an_oil_price_or_with_another_fuel(): + c = parse({"heat_source": "boiler", "boiler_efficiency": 0.9, "max_heat_w": 9000, "fuel": "oil"}) + no = inputs.heating_refusal(c, {"heat_source": "boiler", "fuel": "oil"}, [12.0], [None], "tariff", {}, [None]) + assert no and "no heating oil price" in no["why"] and "oil_price" in no["missing"] + assert inputs.heating_refusal(c, {"heat_source": "boiler", "fuel": "oil"}, [None], [None], "tariff", {}, [10.5]) is None + no = inputs.heating_refusal(c, {"heat_source": "boiler", "fuel": "coal"}, [12.0], [None], "tariff", {}, [10.5]) + assert no and "fuel" in no["missing"] + + +def test_bundle_oil_series(tmp_path): + b = {"v": 1, "kind": "tariff", "id": "t1", "site": "s1", "issued": START, "start": START, "step_s": 900, "steps": 192, + "expires": START + 192 * 900, "currency": "EUR", "unit": "ct/kWh", "import": [None] * 192, "export": [None] * 192, + "gas": [None] * 192, "heat": [None] * 192, "oil": [17.09] * 192, "estimated": [], "other": {"oil": 17.09}, + "sources": [], "co2": {"gas": None, "heat": None, "oil": 266.4, "basis": "direct", "electricity_source": ""}} + (tmp_path / "tariff.json").write_text(json.dumps(b)) + bd = bundles_mod.Bundles(str(tmp_path), "s1") + assert bd.carrier_prices("oil", START, 900, 4, START + 10) == [17.09] * 4 + assert bd.co2(START, 900, 4, START + 10)["oil"] == 266.4 + assert bd.slot_prices(START, START + 10)["oil"]["price"] == 17.09 + + +def test_costs_litres_into_kwh_only_with_the_row(): + recs = [{"asset": "boiler.oil_volume", "delta": 2.0, "last": 100.0}] + assert costs.amounts(recs, 900, 10.046)["oil"] == pytest.approx(20.092) + assert costs.amounts(recs, 900, None)["oil"] is None + assert costs.amounts([{"asset": "oil.energy", "delta": 5000.0, "last": 1.0}], 900)["oil"] == 5.0 + + +def test_costs_book_a_boilers_own_gas_counter(): + # simulated gas boilers map boiler.gas_energy (no house meter): booked as gas (was not before) + assert costs.amounts([{"asset": "boiler.gas_energy", "delta": 3000.0, "last": 1.0}], 900)["gas"] == 3.0 + # with a house meter too: the house meter's, never both + both = [{"asset": "boiler.gas_energy", "delta": 3000.0, "last": 1.0}, {"asset": "gas.energy", "delta": 3500.0, "last": 1.0}] + assert costs.amounts(both, 900)["gas"] == 3.5 + assert costs.meters_of(type("M", (), {"assets": [type("A", (), {"asset": "boiler.gas_energy"})()]})())["gas"] is True diff --git a/src/edge/tests/test_part_load.py b/src/edge/tests/test_part_load.py new file mode 100644 index 0000000..f47a588 --- /dev/null +++ b/src/edge/tests/test_part_load.py @@ -0,0 +1,147 @@ +# Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved. +"""A boiler's part-load efficiency (docs/methods.md E6.4; backlog 47.2): +its gas input piecewise-linear in its heat by its curve, the Parameters +page's boiler.part_load_ picked by the mapping's boiler_type, or the +mapping's own part_load_curve (wins); the rated efficiency is the +full-load value the curve's factor multiplies. A condensing boiler burns +less gas per kWh of heat at part load (convex: LP segments), a standard +one more (binaries); an on/off boiler at its full-load point; neither a +type nor a curve: one efficiency, a quiet note.""" +import pytest + +from cantabile_edge import controls + +highspy = pytest.importorskip("highspy") +from cantabile_edge import optimizer # noqa: E402 + +from test_heat_sources import START, house # noqa: E402 + +# the suggested rows (docs/parameters.md; fleet seeds them): EN 15316-4-1 / DIN V 4701-10 ratios for 20 kW +PARAMS = {"heat.hybrid_switch_eur": 0.05, + "boiler.part_load_condensing": [[0.3, 1.094], [1.0, 1.0]], + "boiler.part_load_low_temperature": [[0.3, 1.0], [1.0, 1.0]], + "boiler.part_load_standard": [[0.3, 0.969], [1.0, 1.0]]} + + +def boiler(kind="", curve=None, switched=False, eff=0.88, qmax=10000.0, temp=19.0): + p = {"r_k_per_kw": 10, "c_kwh_per_k": 3, "comfort_c": 21, "setback_c": 17, "heat_source": "boiler", + "source_options": {}, "cop_curve": [], "boiler_efficiency": eff, "max_heat_w": qmax, + "boiler_type": kind, "part_load_curve": curve or []} + return {"id": "heating", "kind": "heating", "channels": ["switch"] if switched else ["climate"], + "params": p, "state": {"temp_c": temp}, "bounds": {"temp_c": [16, 26, "owner", "owner"]}} + + +def run(dev, params=PARAMS, gas=10.0, steps=96): + s = house([dev], steps=steps, gas=gas) + s["params"] = dict(params) + m = optimizer.Model(optimizer._prepare(s)) + m.solve(30) + val = m.h.getSolution().col_value + x = lambda v: val[v.index] # noqa: E731 + v = m.devices["heating"][1] + # the heat per step from the room's own balance (A2.6): C/dt (T_t - (1-a) T_t-1 - a T_out) x 1000 + p = dev["params"] + a = 0.25 / (p["r_k_per_kw"] * p["c_kwh_per_k"]) + temps = [x(t) for t in v["temp"]] + prev, heat = dev["state"]["temp_c"], [] + for t, tt in enumerate(temps): + heat.append(p["c_kwh_per_k"] / 0.25 * (tt - (1 - a) * prev - a * s["t_out"][t]) * 1000.0) + prev = tt + gas_w = [x(g) for g in v["gas"]] + return s, m, heat, gas_w + + +# -- the curve ------------------------------------------------------------------------------ +def test_the_curve_from_the_type_or_the_mapping(): + assert controls.part_load({"boiler_type": "condensing"}, PARAMS)[0] == [(0.3, 1.094), (1.0, 1.0)] + assert controls.part_load({"boiler_type": "condensing"}, {"boiler.part_load_condensing": "[[0.3, 1.094], [1.0, 1.0]]"})[0] \ + == [(0.3, 1.094), (1.0, 1.0)] # the Parameters page's value as text + own = [[0.2, 1.08], [0.6, 1.03], [1.0, 1.0]] + pts, why = controls.part_load({"boiler_type": "condensing", "part_load_curve": own}, PARAMS) + assert pts == [(0.2, 1.08), (0.6, 1.03), (1.0, 1.0)] and "mapping" in why + assert controls.part_load({}, PARAMS) == (None, "no boiler_type or part_load_curve: one constant efficiency") + pts, why = controls.part_load({"boiler_type": "standard"}, {}) + assert pts is None and "boiler.part_load_standard not received" in why + with pytest.raises(ValueError): + controls.parse([{"id": "h", "kind": "heating", "entities": {"climate": "climate.h"}, + "params": {"boiler_type": "wood"}}], set()) + with pytest.raises(ValueError): + controls.parse([{"id": "h", "kind": "heating", "entities": {"climate": "climate.h"}, + "params": {"part_load_curve": [[1.5, 1.0]]}}], set()) + + +def test_the_segments_condensing_convex_standard_not(): + segs, convex, capped = controls.gas_segments(10000.0, 0.88, [(0.3, 1.094), (1.0, 1.0)]) + assert convex and not capped + # 0..3 kW at 0.88 x 1.094 = 0.9627: 1.0387 W of gas per W of heat; then (10000/0.88 - 3000/0.9627) / 7000 + assert segs[0] == pytest.approx((3000.0, 1 / (0.88 * 1.094))) + assert segs[1][1] == pytest.approx((10000 / 0.88 - 3000 / (0.88 * 1.094)) / 7000.0) + assert segs[1][1] > segs[0][1] + segs, convex, _ = controls.gas_segments(10000.0, 0.85, [(0.3, 0.969), (1.0, 1.0)]) + assert not convex and segs[1][1] < segs[0][1] + # no boiler gives more heat than the gas's Hs: an efficiency above 1 is held at 1 + _, _, capped = controls.gas_segments(10000.0, 0.96, [(0.3, 1.094), (1.0, 1.0)]) + assert capped + + +# -- the plan ------------------------------------------------------------------------------------ +def test_a_condensing_boiler_burns_less_gas_per_kwh_at_part_load(): + s, m, heat, gas_w = run(boiler("condensing")) + # the room is held with a little heat most of the time: part load + part = [k for k, q in enumerate(heat) if 200 < q < 2900] + assert part, heat + for k in part: + assert gas_w[k] / heat[k] == pytest.approx(1 / (0.88 * 1.094), rel=2e-3) # 0.963 of the gas, not 0.88 + # the same room without a type: one efficiency, more gas, and the plan says so + _, _, heat0, gas0 = run(boiler("")) + assert sum(gas0) > sum(gas_w) * 1.05 + p = optimizer.plan(dict(s, params=dict(PARAMS)), 30) + assert not any("constant efficiency" in n for n in p.get("notes") or []) + p0 = optimizer.plan(house([boiler("")], gas=10.0), 30) + assert "heating: no boiler_type or part_load_curve: one constant efficiency" in p0["notes"] + + +def test_the_plans_gas_eur_matches_the_curve(): + s, m, heat, gas_w = run(boiler("condensing")) + segs, _, _ = controls.gas_segments(10000.0, 0.88, [(0.3, 1.094), (1.0, 1.0)]) + + def gas_of(q): + g, left = 0.0, max(0.0, q) + for dq, sl in segs: + take = min(left, dq) + g, left = g + take * sl, left - take + return g + want = sum(gas_of(q) for q in heat) * 0.25 / 1000 * 0.10 # kWh x 10 ct + p = optimizer.plan(dict(s, params=dict(PARAMS)), 30) + assert p["gas_eur"] == pytest.approx(want, abs=0.02) + + +def test_a_standard_boiler_on_its_curve(): + s, m, heat, gas_w = run(boiler("standard", eff=0.85)) + lo = 1 / (0.85 * 0.969) # 1.214 W of gas per W of heat up to 30 % + for k, q in enumerate(heat): + if 200 < q < 2900: + assert gas_w[k] / q == pytest.approx(lo, rel=2e-3) # no cheaper slope taken at low load + elif q > 3100: + hi = (10000 / 0.85 - 3000 / (0.85 * 0.969)) / 7000.0 + assert gas_w[k] == pytest.approx(3000 * lo + (q - 3000) * hi, rel=2e-3) + + +def test_an_on_off_boiler_at_its_full_load_point(): + s, m, heat, gas_w = run(boiler("condensing", switched=True)) + on = [k for k, g in enumerate(gas_w) if g > 1] + assert on + for k in on: + assert gas_w[k] == pytest.approx(10000.0 / 0.88, rel=1e-6) # the rated (full-load) efficiency + + +def test_a_hybrids_boiler_uses_the_curve(): + dev = boiler("condensing") + dev["params"].update(heat_source="hybrid", max_power_w=3000, cop=3.0, source_options={"heat_pump": "HP", "boiler": "Gas"}) + dev["channels"] = ["climate", "source"] + s = house([dev], imp=60.0, gas=10.0) # dear power: the boiler + s["params"] = dict(PARAMS) + p = optimizer.plan(s, 30) + assert p["gas_eur"] > 0 + assert {e.get("source") for e in p["devices"]["heating"] if e.get("source")} == {"boiler"} + assert p["devices"]["heating"][0]["t"] == START diff --git a/src/edge/tests/test_plansplit.py b/src/edge/tests/test_plansplit.py new file mode 100644 index 0000000..71fde3d --- /dev/null +++ b/src/edge/tests/test_plansplit.py @@ -0,0 +1,49 @@ +# Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved. +"""The plan's saving by carrier and lever (plansplit.py; docs/methods.md +E14): the parts add up to the plan's cost and baseline, the heating's share +of the electricity saving is the heater's draw moved in time, gas and +district heat are the heating's alone, a plan without a tariff has none.""" +import pytest + +highspy = pytest.importorskip("highspy") +from cantabile_edge import optimizer # noqa: E402 +from test_heat_sources import house as heat_house, room # noqa: E402 +from test_optimizer import battery, heating, house # noqa: E402 + + +def saved(part): + return part["base_eur"] - part["plan_eur"] + + +def test_parts_add_up_to_the_plan_and_its_baseline(): + p = optimizer.plan(house([battery(), heating()]), 20) + sp = p["saving_parts"] + assert set(sp) == {"electricity"} + assert sum(x["plan_eur"] for x in sp.values()) == pytest.approx(p["cost_eur"], abs=0.02) + assert sum(x["base_eur"] for x in sp.values()) == pytest.approx(p["baseline_eur"], abs=0.02) + el = sp["electricity"] + # the heater runs where power is cheap: its share is a saving, and part of the electricity's + assert el["heating_eur"] > 0 + assert saved(el) > el["heating_eur"] # the battery's shifting is the rest + + +def test_battery_alone_has_no_heating_share(): + sp = optimizer.plan(house([battery()]), 20)["saving_parts"] + assert sp["electricity"]["heating_eur"] == 0 + assert saved(sp["electricity"]) > 0 + + +def test_gas_is_the_heatings_and_a_flat_gas_price_saves_nothing_in_time(): + p = optimizer.plan(heat_house([room("boiler", boiler_efficiency=0.9, max_heat_w=9000)], gas=12.0), 20) + sp = p["saving_parts"] + assert sp["gas"]["plan_eur"] == pytest.approx(p["gas_eur"], abs=0.02) + assert saved(sp["gas"]) == pytest.approx(0, abs=0.001) # the same price every quarter-hour + assert sum(x["base_eur"] for x in sp.values()) == pytest.approx(p["baseline_eur"], abs=0.02) + + +def test_no_tariff_no_parts(): + s = house([battery()]) + s["price_import"] = [None] * len(s["price_import"]) + s["price_export"] = [None] * len(s["price_export"]) + p = optimizer.plan(s, 20) + assert p.get("saving_parts") is None diff --git a/src/edge/tests/test_preferences.py b/src/edge/tests/test_preferences.py index 6054971..3e58dcc 100644 --- a/src/edge/tests/test_preferences.py +++ b/src/edge/tests/test_preferences.py @@ -365,6 +365,35 @@ def test_persists_across_a_restart_and_the_panels_inbox(tmp_path): assert q.value("battery:battery")["reserve_pct"] == 30 and q.active_overrides()[0]["c"] == 22.5 +def test_public_builtin_targets_where_no_setting_is_in_force(tmp_path): + """Backlog 109: per control without a setting that gives the plan + anything, the targets the agent uses instead (for the console card).""" + cs = controls() + p = pm.Preferences(str(tmp_path), Clock(START)) + assert "builtin" not in p.public() # without the controls: as before + b = p.public(list(cs.values()))["builtin"] + assert b["room:living"] == {"kind": "heat", "comfort_c": 21.0, "setback_c": 17.0, "from": "06:00", "to": "22:00", + "occupied": "hours"} + assert b["room:ac"] == {"kind": "cool", "comfort_c": 25.0, "setup_c": 28.0, "from": "06:00", "to": "22:00", + "occupied": "hours"} + assert b["ev:car"] == {"kind": "car", "need_kwh": 10.0, "ready_by": "07:00", "car": []} + assert b["battery:battery"] == {"kind": "battery", "reserve_pct": 10.0, "by": "owner"} + assert p.public(list(cs.values()), presence=True)["builtin"]["room:living"]["presence"] is True + # the plan's occupancy (inputs.occupancy, backlog 45.1): learnt from presence, or the fixed hours and why + b = p.public(list(cs.values()), True, {"source": "learnt", "cloud": 188, "presence_now": 4})["builtin"] + assert b["room:living"]["occupied"] == "learnt" and "occupied_why" not in b["room:living"] + b = p.public(list(cs.values()), False, {"source": "fixed_hours", "why": "no_presence_source"})["builtin"] + assert (b["room:ac"]["occupied"], b["room:ac"]["occupied_why"]) == ("hours", "no_presence_source") + # a setting in force with rows: no built-in targets for that control + p.set("room:living", pm.parse_room_text("daily 22:00-06:00 21 must", "heating"), "ha", "owner", cs["living"]) + p.set("ev:car", pm.parse_ev_text("Mo-Fr 07:30 80% must"), "ha", "owner", cs["car"]) + p.set("battery:battery", {"reserve_pct": 30, "blocks": []}, "ha", "owner", cs["battery"]) + p.set("room:ac", {"blocks": []}, "ha", "owner", cs["ac"]) # set but empty: the built-in still + b = p.public(list(cs.values()))["builtin"] + assert set(b) == {"room:ac"} + json.dumps(p.public(list(cs.values()))) # the plan's JSON + + def test_costs_made_again_only_when_due(tmp_path): cs = controls() clock = Clock(START) diff --git a/src/edge/tests/test_propose.py b/src/edge/tests/test_propose.py index 43c62b5..89ed9b2 100644 --- a/src/edge/tests/test_propose.py +++ b/src/edge/tests/test_propose.py @@ -67,6 +67,39 @@ def home(): return states, reg +def test_presence_sources_proposed(tmp_path): + """Backlog 45.1: HA's persons and an area's presence sensor become the + presence sources the occupancy is learnt from, consent off; a person's + asset id is not the person's name.""" + states, reg = home() + states = states + [{"entity_id": "person.anna", "state": "home", "attributes": {"friendly_name": "Anna"}}, + {"entity_id": "person.ben", "state": "not_home", "attributes": {"friendly_name": "Ben"}}, + {"entity_id": "device_tracker.phone", "state": "home", "attributes": {}}, + st("binary_sensor.living_presence", "on", "occupancy", None, "Living presence", None), + st("binary_sensor.living_motion", "off", "motion", None, "Living motion", None)] + reg = dict(reg, entities=reg["entities"] + [ + {"entity_id": "binary_sensor.living_presence", "unique_id": "pr1", "platform": "zha", "area_id": "living_room"}, + {"entity_id": "binary_sensor.living_motion", "unique_id": "mo1", "platform": "zha", "area_id": "living_room"}, + {"entity_id": "person.anna", "unique_id": "anna", "platform": "person"}, + {"entity_id": "person.ben", "unique_id": "ben", "platform": "person"}]) + got = {a["asset"]: a for a in propose.propose(states, reg, PROFILES)} + persons = sorted(a for a in got if a.startswith("person.")) + assert len(persons) == 2 and not [a for a in persons if "anna" in a or "ben" in a] + a = got[f"person.{propose.person_id('person.anna')}.home"] + assert a == {"entity": "person.anna", "asset": a["asset"], "kind": "gauge", "unit": "", "consent": False, "equals": "home"} + assert got["room.living_room.occupied"]["entity"] == "binary_sensor.living_presence" + assert got["room.living_room.occupied"]["equals"] == "on" + assert not [a for a in got.values() if a["entity"] in ("binary_sensor.living_motion", "device_tracker.phone")] + # the agent's parser takes it, and the agent reads a person home as 1 + from cantabile_edge.mapping import value_of + (tmp_path / "m.yaml").write_text(yaml.safe_dump({"version": 2, "assets": list(got.values())})) + pa = next(x for x in Mapping.load(str(tmp_path / "m.yaml")).assets if x.asset == a["asset"]) + assert value_of(pa, "home", {}) == 1.0 and value_of(pa, "not_home", {}) == 0.0 + # proposed again: the same ids + again = {a["asset"] for a in propose.propose(states, reg, PROFILES, keep=list(got.values()))} + assert set(persons) <= again + + def test_proposal_from_the_bridge_profiles_and_names(): states, reg = home() got = {a["asset"]: a for a in propose.propose(states, reg, PROFILES)} @@ -192,6 +225,27 @@ def test_a_second_inverter_makes_parts(): assert "pv.power" not in second.values() +def test_a_water_heater_proposes_its_tank_values(): + """Backlog 329: any HA water_heater (ha-water-heater): its current + temperature as the tank's (dhw.temp_top), its power sensor as the + heater's; consent off; the tank's control is never proposed (the owner + uses the device on the Devices page).""" + states, reg = home() + reg = dict(reg, devices=reg["devices"] + [{"id": "wh", "name": "Tank", "model": "WWK 300", "manufacturer": "Stiebel", + "identifiers": [["mqtt", "x"]], "area_id": "living_room"}], + entities=reg["entities"] + [ + {"entity_id": "water_heater.tank", "unique_id": "wh1", "device_id": "wh", "platform": "mqtt"}, + {"entity_id": "sensor.tank_heater_power", "unique_id": "wh2", "device_id": "wh", "platform": "mqtt"}]) + states = states + [{"entity_id": "water_heater.tank", "state": "eco", + "attributes": {"current_temperature": 51.5, "temperature": 55, "min_temp": 35, "max_temp": 65}}, + st("sensor.tank_heater_power", "1200", "power", "W", "Tank heater power")] + got = {a["asset"]: a for a in propose.propose(states, reg, PROFILES)} + assert got["dhw.temp_top"] == {"entity": "water_heater.tank", "asset": "dhw.temp_top", "kind": "gauge", "unit": "°C", + "consent": False, "attribute": "current_temperature"} + assert got["dhw.heater_power"]["entity"] == "sensor.tank_heater_power" + assert not any(a["consent"] for a in got.values()) + + def test_eebus_bridge_devices_by_their_profiles(): """The EEBUS bridge's devices (cantabile_eebus_*): their profile's eebus.values say the quantities; the dashboard's view finds diff --git a/src/edge/tests/test_storage.py b/src/edge/tests/test_storage.py new file mode 100644 index 0000000..7941ca2 --- /dev/null +++ b/src/edge/tests/test_storage.py @@ -0,0 +1,313 @@ +# Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved. +"""Stores with losses in the box's plan (docs/methods.md A2.3 S.2, A13; +design note docs/design/storage-losses.md 5): the battery's idle loss (its +standby and the cells' self-discharge) and the hot-water tank (one node, +its standing loss, its heater by carrier, comfort, legionella).""" +import math + +import pytest + +highspy = pytest.importorskip("highspy") + +from cantabile_edge import optimizer # noqa: E402 +from test_optimizer import START, at, battery, heating, house # noqa: E402 + + +def solved(s): + m = optimizer.Model(optimizer._prepare(s)) + m.solve(30) + val = m.h.getSolution().col_value + return m, (lambda v: val[v.index]) + + +def still(s, load=None): + """A flat price, no PV, no end value: nothing to gain from moving energy + (load 0: nothing to discharge into either).""" + s["price_import"] = [30.0] * s["steps"] + s["price_export"] = [None] * s["steps"] + if load is not None: + # nothing to discharge into, and the charge kept is worth the feed-in (no tie to drain it at 0) + s["load_w"] = [float(load)] * s["steps"] + s["price_export"] = [8.0] * s["steps"] + s["params"] = {"battery.end_value_pct": 100} + return s + + +# -- the battery's idle loss (S.2) ------------------------------------------------------------ +def test_a_still_battery_loses_its_standby_every_step(): + # design test 1: P0 50 W, lambda 0: 12.5 Wh per step, 2.4 kWh in 48 h (a small home battery's) + b = battery(soc=80, floor=10) + b["params"]["standby_w"] = 50.0 + m, x = solved(still(house([b]), load=0)) + v = m.devices["battery"][1] + soc = [x(e) for e in v["soc"]] + assert soc[0] == pytest.approx(8000 - 12.5, abs=0.5) + assert soc[-1] == pytest.approx(8000 - 2400, abs=1.0) + p = optimizer.plan(still(house([b]), load=0), 30) + st = p["storage"]["battery"] + assert st["idle_loss_kwh"] == pytest.approx(2.4, abs=0.01) + assert st["idle_loss_kwh_24h"] == pytest.approx(1.2, abs=0.01) + assert st["idle_loss_eur_24h"] == pytest.approx(0.36, abs=0.01) # 1.2 kWh at 30 ct + assert st["standby_w"] == 50.0 and st["from_grid_kwh"] == 0 + # holding, not charging: no entry asks for power + assert all(e["set"] == 0 for e in p["devices"]["battery"]) + + +def test_self_discharge_alone_decays_by_phi_per_step(): + # design test 4: (1 - lambda)^dt per step to 1e-9 (relative) + b = battery(soc=80, floor=10) + b["params"]["self_discharge_pct_month"] = 73.0 # 0.1 %/h: large enough to see + m, x = solved(still(house([b]), load=0)) + v = m.devices["battery"][1] + phi = (1 - 0.001) ** 0.25 + assert v["phi"] == pytest.approx(phi, rel=1e-12) + soc = [x(e) for e in v["soc"]] + for t in (0, 10, 100, 191): + assert soc[t] == pytest.approx(8000 * phi ** (t + 1), rel=1e-9) + + +def test_an_empty_battery_with_standby_is_feasible_and_holds_its_floor(): + # design test 2: at the floor the standby is made good from the grid; never infeasible + b = battery(soc=10, floor=10) + b["params"]["standby_w"] = 50.0 + p = optimizer.plan(still(house([b])), 30) + assert p["status"] + soc0 = 1000 + m, x = solved(still(house([b]))) + soc = [x(e) for e in m.devices["battery"][1]["soc"]] + assert min(soc) >= soc0 - 1.0 + # the plan's import: the house plus about the standby (by charging it at the floor or the valve) + imp = [x(g) for g in m.gin] + assert sum(imp) / len(imp) == pytest.approx(400 + 50 / 0.95, abs=5) + # no grid charging asked of the inverter for it: the entries hold + assert all(e["set"] == 0 and not e["grid"] for e in p["devices"]["battery"]) + + +def test_at_zero_with_no_charging_the_standby_comes_from_the_grid_valve(): + b = battery(soc=0, floor=0) + b["params"]["standby_w"] = 50.0 + b["params"]["standby_in_load"] = False + b["bounds"]["power_w"] = [-3000, 0, "device", "grid"] # charging not allowed now + m, x = solved(still(house([b]))) + v = m.devices["battery"][1] + assert sum(x(g) for g in v["lg"]) / len(v["lg"]) == pytest.approx(50.0, abs=0.5) + imp = [x(g) for g in m.gin] + assert sum(imp) / len(imp) == pytest.approx(450.0, abs=1) # in the balance: not in the load + + +def test_standby_in_load_not_added_twice(): + b = battery(soc=0, floor=0) + b["params"]["standby_w"] = 50.0 + b["params"]["standby_in_load"] = True + b["bounds"]["power_w"] = [-3000, 0, "device", "grid"] + m, x = solved(still(house([b]))) + imp = [x(g) for g in m.gin] + assert sum(imp) / len(imp) == pytest.approx(400.0, abs=1) # the load already holds it + + +def spread(s): + """A cheap night (20 ct, 00-06), 20.4 ct after it (2 % dearer); the house's load only in the + evening (17-21): the night's charge can only serve it after 11 hours.""" + hour = lambda k: (k // 4 + 1) % 24 # noqa: E731 + s["price_import"] = [20.0 if hour(k) < 6 else 20.4 for k in range(s["steps"])] + s["price_export"] = [None] * s["steps"] + s["load_w"] = [1500.0 if 17 <= hour(k) < 21 else 0.0 for k in range(s["steps"])] + return s + + +def night_charge(b): + m, x = solved(spread(house([b]))) + return max(x(e) for e in m.devices["battery"][1]["soc"][:24]) - 2000 + + +def test_a_spread_smaller_than_the_holding_loss_is_not_stored_for(): + # design test 3, as built: a loss that grows with the charge held (the cells' self-discharge) makes + # holding cost; above the spread, the night's charge for the evening stops. A constant standby does + # not: it is lost whether the battery holds charge or not (from the grid at its floor), so it does + # not change the choice, only the energy the evening really finds (test 1) + lossless = battery(soc=20, floor=20) + lossless["params"]["efficiency"] = 1.0 + assert night_charge(lossless) > 1000 # without a loss the 2 % spread pays + leaky = battery(soc=20, floor=20) + leaky["params"].update(efficiency=1.0, self_discharge_pct_month=150.0) # 0.2 %/h: 3 % over 15 h + assert night_charge(leaky) < 100 # only what holds its floor + standby = battery(soc=20, floor=20) + standby["params"].update(efficiency=1.0, standby_w=49.0) + assert night_charge(standby) > 1000 + + +def test_flex_spare_discharge_counts_the_idle_loss_and_the_envelope_carries_it(): + b = battery(soc=21, floor=20) + b["params"]["standby_w"] = 50.0 + s = still(house([b])) + s["sources"] = {"battery": {"battery": {"standby_w": "learnt"}}} + p = optimizer.plan(s, 30) + # 100 Wh above the floor, 12.5 Wh lost per step: the spare falls step by step + assert p["flex"]["shed_w"][1] < 400 + sh = next(d for d in p["flex"]["shift"]["devices"] if d["kind"] == "battery") + assert sh["standby_w"] == 50.0 and sh["standby_src"] == "learnt" and sh["loss_pct_h"] == 0 + + +# -- the hot-water tank (A13) ------------------------------------------------------------------ +def tank(heater="element", temp=50.0, volume=300.0, ua=70.0 / 45.0, power=3000.0, channels=("switch",), **kw): + p = {"heater": heater, "volume_l": volume, "ua_w_k": ua, "min_temp_c": 45.0, "max_temp_c": 60.0, + "room_temp_c": 18.0, "cold_water_c": 10.0, "short_eur_kwh": 1.0, "legionella": "device"} + if heater in ("element", "heat_pump"): + p["max_power_w"] = power + if heater == "heat_pump": + p["cop"] = 3.0 + if heater in ("boiler", "district"): + p["max_heat_w"] = power + if heater == "boiler": + p["boiler_efficiency"] = 0.9 + p.update(kw) + return {"id": "tank", "kind": "dhw_tank", "channels": list(channels), "params": p, + "state": {"temp_c": temp}, "bounds": {"temp_c": [10.0, 75.0, "device", "device"]}} + + +def evening_draw(s, w=1500.0): + """A shower hour every evening (19-20 Berlin): 1.5 kWh of heat.""" + hour = lambda k: (k // 4 + 1) % 24 # noqa: E731 + return [w if hour(k) == 19 else 0.0 for k in range(s["steps"])] + + +def test_s4_energy_by_hand(): + # design test 9: 300 L, top 60 / bottom 40, f 0.5, T_cw 10: 13.96 kWh + from cantabile_edge import storefit + t = storefit.mean_temp(60.0, 40.0, 0.5) + assert storefit.tank_energy_wh(300.0, t, 10.0) == pytest.approx(13957.0, abs=1) + assert storefit.mean_temp(60.0, None, 0.5) == 60.0 + + +def test_s5_standing_loss_in_the_first_step(): + # design test 10: class B 300 L: S 70 W -> UA 1.56 W/K; at 55 °C in an 18 °C room: -58 W (+-1) + s = still(house([tank(temp=55.0, ua=70.0 / 45.0)])) + m, x = solved(s) + v = m.devices["tank"][1] + # nothing drawn, warm enough: no heat; the loss UA (T - T_room) + first = (v["e0"] - x(v["e"][0])) / 0.25 + assert first == pytest.approx(70.0 / 45.0 * 37.0, abs=1.0) + assert first == pytest.approx(57.6, abs=1.0) + p = optimizer.plan(s, 30) + st = p["storage"]["tank"] + assert st["standby_w"] == pytest.approx(70.0, abs=0.1) and st["idle_loss_kwh_24h"] > 1.0 + + +def test_an_element_stores_pv_surplus_at_noon_not_at_night(): + # design test 11: PV surplus at noon, draw in the evening: heats at noon, not at night + s = house([tank(temp=47.0)]) + hour = lambda k: (k // 4 + 1) % 24 # noqa: E731 + s["pv_w"] = [4000.0 if 11 <= hour(k) < 14 else 0.0 for k in range(s["steps"])] + s["price_import"] = [30.0] * s["steps"] + s["price_export"] = [8.0] * s["steps"] + s["draw_w"] = evening_draw(s) + s["devices"][0]["draw_w"] = s["draw_w"] + m, x = solved(s) + v = m.devices["tank"][1] + heat = [optimizer.tank_heat(v, t, x) for t in range(s["steps"])] + noon = sum(heat[t] for t in range(s["steps"]) if 11 <= hour(t) < 14) + night = sum(heat[t] for t in range(s["steps"]) if hour(t) < 6) + assert noon > 4 * night + 1000 + assert sum(x(u) for u in v["unmet"]) * 0.25 < 5.0 # Wh + p = optimizer.plan(s, 30) + assert any(e["set"] == "on" and "PV" in e["why"] for e in p["devices"]["tank"]) + + +def test_a_heat_pump_prefers_the_warm_afternoon_and_shares_its_compressor(): + # design test 12: a COP curve by outside temperature; P_room + P_tank within the compressor + s = still(house([heating(temp=21.0, power=3000), tank(heater="heat_pump", temp=46.0, channels=("water_heater",), + shares_with="heating", cop_curve=[[0, 2.0], [20, 4.0]])])) + hour = lambda k: (k // 4 + 1) % 24 # noqa: E731 + s["t_out"] = [15.0 if 12 <= hour(k) < 17 else 0.0 for k in range(s["steps"])] + s["devices"][0]["params"]["cop"] = 3.0 + s["devices"][1]["draw_w"] = evening_draw(s) + m, x = solved(s) + v = m.devices["tank"][1] + room = m.devices["heating"][1] + for t in range(s["steps"]): + assert x(v["power"][t]) + x(room["power"][t]) <= 3000 + 1e-6 + e_heat = [x(v["power"][t]) for t in range(s["steps"])] + warm = sum(e_heat[t] for t in range(s["steps"]) if 12 <= hour(t) < 17) + assert warm > 0.5 * sum(e_heat) + + +@pytest.mark.parametrize("heater,price_key", [("boiler", "price_gas"), ("district", "price_heat")]) +def test_gas_and_district_heat_at_their_price_and_late_on_a_flat_price(heater, price_key): + # design test 13: priced at its own carrier; flat price: heats as late as it can (least loss) + s = still(house([tank(heater=heater, temp=47.0, power=10000.0, channels=("water_heater",))])) + s[price_key] = [10.0] * s["steps"] + s["devices"][0]["draw_w"] = evening_draw(s) + p = optimizer.plan(s, 30) + assert p["cost_parts"]["gas_eur" if heater == "boiler" else "heat_eur"] > 0 + m, x = solved(s) + v = m.devices["tank"][1] + hour = lambda k: (k // 4 + 1) % 24 # noqa: E731 + heat = [optimizer.tank_heat(v, t, x) for t in range(s["steps"])] + first_day = [t for t in range(96) if heat[t] > 50] + assert first_day and all(hour(t) >= 12 for t in first_day if t > 4), first_day + + +def test_a_draw_larger_than_the_heater_is_short_never_infeasible(): + # design test 14 + s = still(house([tank(temp=45.0, power=500.0)])) + s["devices"][0]["draw_w"] = evening_draw(s, 30000.0) + p = optimizer.plan(s, 30) + assert p["storage"]["tank"]["short_kwh"] > 1.0 + assert any("cannot give" in n for n in p["notes"]) + + +def test_grossanlage_holds_60_in_the_plan(): + # design test 15 (the plan's half; the guard's: test_tank_inputs) + s = still(house([tank(temp=61.0, volume=800.0, grossanlage=True, law_floor_c=60.0, max_temp_c=65.0, + channels=("water_heater",), power=6000.0)])) + s["devices"][0]["draw_w"] = evening_draw(s) + m, x = solved(s) + v = m.devices["tank"][1] + assert min(optimizer.tank_temp(v, t, x) for t in range(s["steps"])) >= 60.0 - 0.05 + p = optimizer.plan(s, 30) + assert all(e["set"] >= 60.0 for e in p["devices"]["tank"]) + + +def test_legionella_plan_takes_the_cheapest_step_once(): + # design test 16: due within the horizon: one >= 60 °C step, the cheapest (the night's 12 ct) + t = tank(temp=50.0, legionella="plan", legionella_temp_c=60.0, legionella_interval_h=168.0) + t["state"]["legionella"] = {"due_step": 120, "last": START - 6 * 86400, "due": START + 30 * 3600} + s = house([t]) + s["devices"][0]["draw_w"] = evening_draw(s) + m, x = solved(s) + v = m.devices["tank"][1] + hot = [k for k in range(120) if optimizer.tank_temp(v, k, x) >= 60.0 - 0.01] + assert hot + hour = lambda k: (k // 4 + 1) % 24 # noqa: E731 + assert all(hour(k) < 7 for k in hot), hot # heated in the cheap night + p = optimizer.plan(s, 30) + assert p["storage"]["tank"]["legionella"]["planned"] is not None + # "device": no constraint: never at 60 within the window + t2 = tank(temp=50.0) + t2["state"]["legionella"] = {"due_step": 120} + s2 = house([t2]) + s2["devices"][0]["draw_w"] = evening_draw(s2) + m2, x2 = solved(s2) + v2 = m2.devices["tank"][1] + assert max(optimizer.tank_temp(v2, k, x2) for k in range(120)) < 60.0 - 0.01 + + +def test_a_planned_tank_takes_the_hot_water_out_of_the_heat_outlook(): + s = still(house([tank(heater="district", temp=50.0, power=10000.0, channels=("water_heater",))])) + s["price_heat"] = [10.0] * s["steps"] + s["dhw_w"] = evening_draw(s) + s["devices"][0]["draw_w"] = s["dhw_w"] + s["heat_site"] = {"source": "district", "from": "the site's heat price", "space": False} + p = optimizer.plan(s, 30) + assert "heat_outlook" not in p # its hot water is the tank's now + assert p["storage"]["tank"]["draw_kwh_24h"] == pytest.approx(1.5, abs=0.01) + + +def test_tank_baseline_and_shift_envelope(): + s = still(house([tank(temp=50.0, channels=("power",))])) + s["devices"][0]["draw_w"] = evening_draw(s) + p = optimizer.plan(s, 30) + assert p["baseline_eur"] >= p["cost_eur"] - 0.05 + sh = next(d for d in p["flex"]["shift"]["devices"] if d["kind"] == "dhw_tank") + assert 0 < sh["keep"] < 1 and max(sh["hi_wh"]) > 0 + assert all(math.isfinite(w) for w in sh["base_w"]) diff --git a/src/edge/tests/test_tank_inputs.py b/src/edge/tests/test_tank_inputs.py new file mode 100644 index 0000000..b985b40 --- /dev/null +++ b/src/edge/tests/test_tank_inputs.py @@ -0,0 +1,338 @@ +# Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved. +"""The stores' facts, their refusals and what the box learns of them +(docs/methods.md A2.3, A13; design note docs/design/storage-losses.md 5, +10): the battery's idle loss by source (never a refusal), the hot-water +tank's facts (the volume, heater and its power, a heat pump's COP refused; +no loss: class D assumed), the Großanlage's floor in the guard, the box's +idle and UA fits and the draw (S.7), the tank's executor actions, and +Finding A2-a (the tank's heater inside the house load counted once).""" +import math +import random + +import pytest + +from cantabile_edge import storefit +from cantabile_edge.bundles import Bundles +from cantabile_edge.controls import Control, parse +from cantabile_edge.executor import actions_for +from cantabile_edge.inputs import Collector, base_load, model_state + +from test_control_parts import SITE +from test_refuse import START, _mapping, col_with + +PARAMS = {"battery.standby_w": 13, "battery.self_discharge_pct_month": 2, + "dhw.erp_class_limits": {"A+": [5.5, 3.16], "A": [8.5, 4.25], "B": [12, 5.93], "C": [16.66, 8.33], + "D": [21, 10.33], "E": [26, 13.66], "F": [31, 16.66]}, + "dhw.erp_class_assumed": "D", "dhw.min_temp_c": 45, "dhw.max_temp_c": 60, "dhw.short_eur_kwh": 1.0, + "dhw.legionella_temp_c": 60, "dhw.legionella_interval_h": 168, "de.dvgw_w551_min_outlet_c": 60, + "de.dvgw_w551_volume_l": 400, "dhw.top_sensor_share": 0.5, "dhw.room_temp_c": 18, "dhw.cold_water_c": 10, + "dhw.draw_detect_k_per_15min": 0.5, "dhw.ua_fit_min_hours": 12, "dhw.ua_fit_band": {"min": 0.5, "max": 3}, + "dhw.draw_history_min_days": 7, "battery.idle_fit_min_run_h": 3, "battery.idle_fit_min_hours": 24, + "battery.idle_dead_band_w": 20, "battery.idle_max_w": 100, "battery.idle_fit_agree_pct": 30} + + +# -- the mapping --------------------------------------------------------------------------- +def test_a_tank_control_parses_and_its_facts_are_checked(): + c = parse([{"id": "tank", "kind": "dhw_tank", "entities": {"switch": "switch.heizstab", "temp_top": "sensor.t_top", + "heater_power": "sensor.heizstab_w"}, + "params": {"heater": "element", "volume_l": 120, "max_power_w": 2000, "erp_class": "B"}}], set())[0] + assert c.kind == "dhw_tank" and c.p("legionella") == "device" + for bad, why in (({"heater": "solar"}, "heater"), ({"erp_class": "G"}, "erp_class"), ({"volume_l": 0}, "volume_l"), + ({"legionella": "weekly"}, "legionella"), ({"sg_options": {"5": "x"}}, "sg_options")): + with pytest.raises(ValueError, match=why): + parse([{"id": "t", "kind": "dhw_tank", "entities": {"switch": "switch.x"}, "params": bad}], set()) + with pytest.raises(ValueError, match="needs"): + parse([{"id": "t", "kind": "dhw_tank", "entities": {"temp_top": "sensor.x"}}], set()) + + +def test_battery_standby_params_may_be_zero_and_in_load_is_a_bool(): + c = parse([{"id": "b", "kind": "battery", "entities": {"setpoint": "number.b", "standby": "sensor.b_idle"}, + "params": {"standby_w": 0, "self_discharge_pct_month": 0, "standby_in_load": False}}], set())[0] + assert c.p("standby_in_load") is False + with pytest.raises(ValueError, match="standby_in_load"): + parse([{"id": "b", "kind": "battery", "entities": {"setpoint": "number.b"}, + "params": {"standby_in_load": "yes"}}], set()) + + +# -- the battery's idle loss: the order of its sources (design test 5) --------------------- +def test_idle_facts_order_mapping_device_learnt_owner_parameter_none(): + c = Control("b", "battery", {"setpoint": "number.b"}, True, {}) + fit = {"standby_w": 48.7, "loss_pct_h": 0.004} + assert c.battery_idle_facts(None, {}) == ({"standby_w": 0.0, "self_discharge_pct_month": 0.0}, + {"standby_w": "none", "self_discharge_pct_month": "none"}) + f, s = c.battery_idle_facts(None, PARAMS) + assert f["standby_w"] == 13 and s["standby_w"] == "parameter" and s["self_discharge_pct_month"] == "parameter" + c.rated = {"battery_standby_w": 30} + assert c.battery_idle_facts(None, PARAMS)[1]["standby_w"] == "owner" + f, s = c.battery_idle_facts(fit, PARAMS) + assert (f["standby_w"], s["standby_w"]) == (48.7, "learnt") # the fit beats the datasheet + assert f["self_discharge_pct_month"] == pytest.approx(0.004 * 730) and s["self_discharge_pct_month"] == "learnt" + c.reported = {"standby_w": 21.0} + assert c.battery_idle_facts(fit, PARAMS)[1]["standby_w"] == "device" + c.params["standby_w"] = 0 + assert c.battery_idle_facts(fit, PARAMS) [0]["standby_w"] == 0 and c.battery_idle_facts(fit, PARAMS)[1]["standby_w"] == "mapping" + + +def bat_state(tmp_path, params, extra_params=None): + col = col_with(sensor__soc=(60, "%"), sensor__load=(500, "W")) + b = Control("battery", "battery", {"setpoint": "number.bat", "soc": "sensor.soc"}, True, + {"capacity_wh": 5000, "max_charge_w": 2500, "max_discharge_w": 2500, "efficiency": 0.95, + **(extra_params or {})}) + bundles = Bundles(str(tmp_path), SITE) + bundles.box_params = lambda now: params + from cantabile_edge.mapping import Mapping + m = Mapping.load(_mapping(tmp_path)) + return model_state(START, [b], m.inputs, col, bundles, None, "UTC", None) + + +def test_a_battery_without_any_idle_loss_is_planned_with_a_quiet_note(tmp_path): + s = bat_state(tmp_path, {}) + assert [d["id"] for d in s["devices"]] == ["battery"] and "battery" not in s["refused"] + assert any("idle loss not modelled" in n for n in s["notes"]) + assert s["sources"]["battery"]["battery"]["standby_w"] == "none" + s = bat_state(tmp_path, PARAMS) + assert s["devices"][0]["params"]["standby_w"] == 13 + assert s["sources"]["battery"]["battery"]["standby_w"] == "parameter" + assert not any("idle loss" in n for n in s["notes"]) + + +# -- the tank's facts -------------------------------------------------------------------------- +def tank(params=None, ents=None, rated=None): + c = Control("tank", "dhw_tank", ents or {"switch": "switch.heizstab", "temp_top": "sensor.t_top", + "temp_bottom": "sensor.t_bot"}, True, dict(params or {})) + c.rated = rated or {} + return c + + +def test_tank_facts_refuse_what_has_no_stand_in(): + f, missing, _ = tank().tank_facts(PARAMS) + assert {"heater", "volume_l"} <= set(missing) + f, missing, _ = tank({"heater": "heat_pump", "volume_l": 300}).tank_facts(PARAMS) + assert "max_power_w" in missing and "cop" in missing + f, missing, src = tank({"heater": "heat_pump", "volume_l": 300}, rated={"tank_heater_kw": 0.5, "tank_cop": 3.1}).tank_facts(PARAMS) + assert missing == [] and f["max_power_w"] == 500 and f["cop"] == 3.1 and src["cop"] == "owner" + f, missing, _ = tank({"heater": "boiler", "volume_l": 150}).tank_facts(PARAMS) + assert "max_heat_w" in missing and "boiler_efficiency" in missing + + +def test_no_loss_entered_plans_with_class_d_assumed(): + f, missing, src = tank({"heater": "element", "volume_l": 300, "max_power_w": 3000}).tank_facts(PARAMS) + assert missing == [] + assert src["ua_w_k"] == "assumed" and f["erp_class"] == "D" + assert f["ua_w_k"] == pytest.approx((21 + 10.33 * 300 ** 0.4) / 45, rel=1e-6) # 122 W / 45 K + # the label's class from the owner (3 = B), the installer's S, the device's report, the box's fit + f, _, src = tank({"heater": "element", "volume_l": 300, "max_power_w": 3000}, rated={"tank_erp_class": 3}).tank_facts(PARAMS) + assert (src["ua_w_k"], f["erp_class"]) == ("owner", "B") and f["ua_w_k"] == pytest.approx(70.1 / 45, rel=0.01) + c = tank({"heater": "element", "volume_l": 300, "max_power_w": 3000, "standby_w": 90}) + c.reported = {"standby_loss_w": 60} + assert c.tank_facts(PARAMS, {"ua_w_k": 1.7})[0]["ua_w_k"] == pytest.approx(2.0) # the mapping first + c.params.pop("standby_w") + assert c.tank_facts(PARAMS, {"ua_w_k": 1.7})[2]["ua_w_k"] == "device" + c.reported = {} + assert c.tank_facts(PARAMS, {"ua_w_k": 1.7})[2]["ua_w_k"] == "learnt" + # without the class table or the assumed class: the parameters are missing (fixable) + _, missing, _ = tank({"heater": "element", "volume_l": 300, "max_power_w": 3000}).tank_facts( + {k: v for k, v in PARAMS.items() if k != "dhw.erp_class_limits"}) + assert "dhw.erp_class_limits" in missing + + +def test_grossanlage_by_volume_and_its_floor_in_the_guard(): + c = tank({"heater": "element", "volume_l": 800, "max_power_w": 6000}, + ents={"water_heater": "water_heater.central", "temp_top": "sensor.t_top"}) + f, missing, _ = c.tank_facts(PARAMS) + assert f["grossanlage"] is True and f["law_floor_c"] == 60 and missing == [] + assert c.device_range("temp_c") == (60.0, 75.0) + assert not c.bounds("temp_c").holds(55.0) and c.bounds("temp_c").holds(60.0) + small = tank({"heater": "element", "volume_l": 300, "max_power_w": 3000}) + small.tank_facts(PARAMS) + assert small.device_range("temp_c") == (10.0, 75.0) + + +def tank_state(tmp_path, c, col, params=PARAMS, fit=None, dhw=None): + bundles = Bundles(str(tmp_path), SITE) + bundles.box_params = lambda now: params + if dhw is not None: + bundles.forecast_parts = lambda m, *a, **k: [(v, "series") for v in dhw] if m == "dhw_w" else None + from cantabile_edge.mapping import Mapping + m = Mapping.load(_mapping(tmp_path)) + return model_state(START, [c], m.inputs, col, bundles, None, "UTC", None, storefit=fit) + + +def test_a_tank_without_volume_is_refused_with_where_to_enter_it(tmp_path): + # design test 17: the user-fixable refusals reach the alarm box (the plan's refused) + col = col_with(sensor__t_top=(55, "°C"), sensor__t_bot=(40, "°C"), sensor__load=(500, "W")) + s = tank_state(tmp_path, tank({"heater": "element", "max_power_w": 2000}), col) + r = s["refused"]["tank"] + assert r["kind"] == "dhw_tank" and "volume_l" in r["missing"] and "Hot-water tank, litres" in r["where"] + col2 = col_with(sensor__load=(500, "W")) + s = tank_state(tmp_path, tank({"heater": "element", "max_power_w": 2000, "volume_l": 120}), col2) + assert "temp_sensor" in s["refused"]["tank"]["missing"] + + +def test_a_tank_waiting_for_its_draw_history_is_a_note_not_a_refusal(tmp_path): + col = col_with(sensor__t_top=(55, "°C"), sensor__t_bot=(40, "°C"), sensor__load=(500, "W")) + fit = storefit.StoreFit(str(tmp_path / "sf.json")) + s = tank_state(tmp_path, tank({"heater": "element", "max_power_w": 2000, "volume_l": 120}), col, fit=fit) + assert "tank" not in s["refused"] and not s["devices"] + assert any("not planned yet" in n for n in s["notes"]) + + +def test_a_tank_with_a_forecast_is_planned_with_its_mean_temperature(tmp_path): + col = col_with(sensor__t_top=(60, "°C"), sensor__t_bot=(40, "°C"), sensor__load=(500, "W")) + s = tank_state(tmp_path, tank({"heater": "element", "max_power_w": 2000, "volume_l": 120}), col, + dhw=[300.0] * 192) + d = s["devices"][0] + assert d["kind"] == "dhw_tank" and d["state"]["temp_c"] == 50.0 and len(d["draw_w"]) == 192 + assert s["sources"]["dhw_tank"]["tank"]["ua_w_k"] == "assumed" + + +# -- what the box learns ------------------------------------------------------------------------- +def idle_days(fit, cid, w=49.0, days=14, cap=5000.0, noise=3.0, levels=(80.0,), seed=1): + """Synthetic nights: idle from 00:00 to 07:00 at a few charge levels, the battery's own power + -w W (+- noise), its SoC falling w Wh per hour in 1 % steps; working in the day.""" + rnd = random.Random(seed) + t0 = START - days * 86400 + for d in range(days): + soc = levels[d % len(levels)] + e = soc / 100 * cap + for k in range(96): + t = t0 + d * 86400 + k * 900 + hour = (k // 4) + idle = hour < 7 + for m in range(15): + now = t + m * 60 + if idle: + e -= w / 60.0 + fit.sample_battery(cid, now, math.floor(e / cap * 100), -w + rnd.uniform(-noise, noise), 0.0, False) + else: + fit.sample_battery(cid, now, 50.0, -800.0 + rnd.uniform(-300, 300), 0.0, False) + fit.sample_battery(cid, START, 50.0, 0.0, 0.0, False) # closes the last quarter-hour + + +def test_idle_fit_finds_the_standby_within_5_w(tmp_path): + # design test 6: 14 days, 49 W, 1 % SoC steps, noise + fit = storefit.StoreFit(str(tmp_path / "sf.json")) + idle_days(fit, "battery", levels=(80.0, 40.0)) + got = fit.fit_batteries({"battery": 5000.0}, PARAMS, START)["battery"] + assert got["standby_w"] == pytest.approx(49.0, abs=5.0) and got["method"] == "power" + assert got["soc_w"] == pytest.approx(49.0, abs=10.0) # the two methods agree + assert fit.battery_in_force("battery")["standby_w"] == got["standby_w"] + fit.save() + again = storefit.StoreFit(str(tmp_path / "sf.json")) + assert again.battery_in_force("battery")["standby_w"] == got["standby_w"] + + +def test_idle_fit_one_level_no_lambda_and_too_few_hours_no_fit(tmp_path): + fit = storefit.StoreFit(str(tmp_path / "sf.json")) + idle_days(fit, "b", levels=(70.0,)) + got = fit.fit_batteries({"b": 5000.0}, PARAMS, START)["b"] + assert got["loss_pct_h"] is None + few = storefit.StoreFit(str(tmp_path / "sf2.json")) + idle_days(few, "b", days=3) # 3 nights x 7 h = 21 h < 24 h + assert few.fit_batteries({"b": 5000.0}, PARAMS, START) == {} + # charging and discharging quarter-hours are never idle + assert not storefit.idle_slot([-800.0, -500.0], 0.0, False, 50.0, 20.0, 100.0) + assert not storefit.idle_slot([1500.0, 1500.0], 0.0, False, 50.0, 20.0, 100.0) + assert storefit.idle_slot([-49.0, -47.0], 0.0, False, 50.0, 20.0, 100.0) + assert not storefit.idle_slot([-49.0, -47.0], 0.0, True, 50.0, 20.0, 100.0) # grid charging on + + +def test_ua_fit_on_cooling_curves_with_draws_excluded(tmp_path): + # design test 18: UA within 10 %; a fit far off its label kept off + vol, ua, room, cold = 300.0, 1.56, 18.0, 10.0 + fit = storefit.StoreFit(str(tmp_path / "sf.json")) + facts = {"volume_l": vol, "cold_water_c": cold, "ua_w_k": ua, "draw_detect_k": 0.5, "legionella_temp_c": 60} + temp, t = 60.0, START - 5 * 86400 + rnd = random.Random(2) + for k in range(5 * 96): + if k % 96 in (28, 76): # a shower: 6 K off the mean + temp -= 6.0 + temp -= ua * (temp - room) * 0.25 / (1.163 * vol) + if k % 96 == 60: + temp = 60.0 # heated back (the sample says 0 heat: a jump up) + fit.sample_tank("tank", t + k * 900, round(temp + rnd.uniform(-0.05, 0.05), 1), room, 0.0, facts) + got = fit.fit_tank("tank", dict(facts, label_ua_w_k=ua), PARAMS) + assert got is not None and got["ua_w_k"] == pytest.approx(ua, rel=0.10) and got["kept"] + far = fit.fit_tank("tank", dict(facts, label_ua_w_k=ua / 5), PARAMS) + assert far["kept"] is False + assert fit.tank_learnt("tank").get("legionella") is not None + + +def test_s7_draw_recovered_and_its_profile_after_a_week(tmp_path): + # design test 19: synthetic draws recovered within 10 % per hour + vol, ua, room, cold = 200.0, 1.4, 18.0, 10.0 + fit = storefit.StoreFit(str(tmp_path / "sf.json")) + facts = {"volume_l": vol, "cold_water_c": cold, "ua_w_k": ua, "draw_detect_k": 0.5} + temp, t0 = 55.0, START - 8 * 86400 + drawn = {} + for k in range(8 * 96): + t = t0 + k * 900 + d = 2000.0 if k % 96 in (28, 29, 30, 31) else 0.0 # 07:00-08:00 UTC: 2 kW of hot water + heat = 2000.0 if k % 96 in (40, 41, 42, 43) else 0.0 + e = storefit.tank_energy_wh(vol, temp, cold) + e = (1 - ua * 0.25 / (1.163 * vol)) * e + 0.25 * (heat - d - ua * (cold - room)) + temp = cold + e / (1.163 * vol) + drawn[t] = d + # the sensors read after the step; the heat the step had + fit.sample_tank("tank", t + 1, temp, room, heat, facts) + fit.sample_tank("tank", t0 + 8 * 96 * 900 + 1, temp, room, 0.0, facts) + got = fit.tank["tank"]["draw"] + hits = [got[t] for t in got if drawn.get(t) == 2000.0] + assert hits and all(v == pytest.approx(2000.0, rel=0.10) for v in hits) + prof = fit.draw_profile("tank", START, 96, "UTC", 7) + assert prof is not None and max(prof) == pytest.approx(2000.0, rel=0.10) + assert fit.draw_profile("tank", START, 96, "UTC", 9) is None + + +# -- the executor (design test 20) ------------------------------------------------------------- +def test_tank_actions_water_heater_relay_and_sg_ready(): + col = Collector() + col.on_entities({"a": {"water_heater.wh": {"s": "eco", "a": {"temperature": 50, "min_temp": 40, "max_temp": 65}}, + "switch.heizstab": {"s": "off", "a": {}}, + "select.sg": {"s": "normal", "a": {}}}}) + wh = Control("tank", "dhw_tank", {"water_heater": "water_heater.wh"}, True, {}) + a = actions_for(wh, {"set": 58.0}, col) + assert [(x.service, x.data, x.quantity) for x in a] == [("set_temperature", {"temperature": 58.0}, "temp_c")] + relay = Control("tank", "dhw_tank", {"switch": "switch.heizstab"}, True, {}) + assert [x.service for x in actions_for(relay, {"set": "on"}, col)] == ["turn_on"] + sg = Control("tank", "dhw_tank", {"sg_ready": "select.sg"}, True, {"sg_options": {"2": "normal", "3": "boost"}}) + assert [x.data for x in actions_for(sg, {"set": "sg:3"}, col)] == [{"option": "boost"}] + assert actions_for(sg, {"set": "sg:2"}, col) == [] + + +# -- Finding A2-a: the tank's heater inside the house load counts once ---------------------- +def test_the_tank_heater_comes_off_the_house_load(): + from cantabile_edge.controls import Inputs + col = col_with(sensor__load=(3500, "W"), sensor__heizstab_w=(2000, "W")) + inp = Inputs(load_power="sensor.load", controlled_power=["sensor.heizstab_w"]) + assert base_load(col, inp) == 1500.0 + + +def test_the_mapping_names_the_tank_heater_as_controlled_power(tmp_path): + import yaml + from cantabile_edge.mapping import Mapping + p = tmp_path / "m.yaml" + p.write_text(yaml.safe_dump({"version": 3, "assets": [ + {"entity": "sensor.load", "asset": "load.power", "kind": "gauge", "unit": "W", "consent": True}], + "inputs": {"load_power": "sensor.load"}, + "controls": [{"id": "tank", "kind": "dhw_tank", "entities": {"switch": "switch.h", + "heater_power": "sensor.heizstab_w"}}]})) + m = Mapping.load(str(p)) + assert "sensor.heizstab_w" in (m.inputs.controlled_power or []) + + +def test_from_the_mapping_to_the_plan(tmp_path): + pytest.importorskip("highspy") + from cantabile_edge import optimizer + col = col_with(sensor__t_top=(52, "°C"), sensor__t_bot=(44, "°C"), sensor__load=(500, "W")) + c = tank({"heater": "element", "max_power_w": 2000, "volume_l": 120, "legionella": "plan"}, + rated={"tank_erp_class": 2}) + s = tank_state(tmp_path, c, col, dhw=[400.0 if k % 96 in range(76, 80) else 0.0 for k in range(192)]) + s["price_import"] = [30.0] * 192 + s["price_export"] = [8.0] * 192 + s["prices"]["status"] = "tariff" + p = optimizer.plan(s, 30) + st = p["storage"]["tank"] + assert st["erp_class"] == "A" and st["loss_src"] == "owner" and st["temp_c"] == 48.0 + assert st["legionella"]["mode"] == "plan" and st["legionella"]["planned"] is not None # never seen at 60: due now + assert p["devices"]["tank"] and all(e["set"] in ("on", "off") for e in p["devices"]["tank"]) diff --git a/src/edge/tests/test_thermostat.py b/src/edge/tests/test_thermostat.py index 9c8f3c8..ce48477 100644 --- a/src/edge/tests/test_thermostat.py +++ b/src/edge/tests/test_thermostat.py @@ -37,7 +37,7 @@ def ac_home(r): "temperature": 24, "min_temp": 18, "max_temp": 30, "target_temp_step": 0.5, "fan_mode": "auto"}, name="Living room A/C") r.areas.append({"area_id": "bedroom", "name": "Bedroom"}) - climate(r, "ir", "climate.bedroom_split", "heat", + climate(r, "irsplit", "climate.bedroom_split", "heat", {"hvac_modes": ["off", "heat", "cool", "dry"], "current_temperature": None, "temperature": 22, "min_temp": 17, "max_temp": 30, "target_temp_step": 1}, area="bedroom", name="Bedroom split") diff --git a/src/profiles/README.md b/src/profiles/README.md index e6a6f31..068d912 100644 --- a/src/profiles/README.md +++ b/src/profiles/README.md @@ -8,7 +8,7 @@ How a vendor's device becomes what Cantabile understands. One JSON file per devi { "id": "huawei-sun2000", "version": "1.0.0", "manufacturer": "Huawei", "name": "SUN2000 inverter (...)", "models": ["SUN2000-*KTL-M1"], - "category": "inverter|battery|meter|heat-pump|ev-charger|climate|sensor|shade|weather|other", + "category": "inverter|battery|meter|heat-pump|ev-charger|climate|sensor|shade|weather|hot-water|other", "status": "verified|documented|draft", "source": "where the register map and names come from", "recognise": {"ha": [{"manufacturer": "Huawei*", "model": "SUN2000*", "domain": "huawei_solar"}]}, @@ -26,7 +26,7 @@ How a vendor's device becomes what Cantabile understands. One JSON file per devi ### Ratings and protection -- **ratings**: `{"inverter_kw", "pv_kwp", "battery_kwh", "battery_kw", "heatpump_kw", "heat_kw", "ev_kw", "circuit_a", "grid_connection_kw", "phases": number}`, what the profile knows for every device of it. A field with `"rating": ` (type `int` or `number`, `optional`) asks the owner; it is asked on every path. The ratings go to the cloud with the inventory. +- **ratings**: `{"inverter_kw", "pv_kwp", "battery_kwh", "battery_kw", "battery_efficiency_pct", "battery_standby_w", "battery_self_discharge_pct_month", "heatpump_kw", "heat_kw", "ev_kw", "circuit_a", "grid_connection_kw", "phases", "boiler_efficiency_pct", "dhw_litres_per_unit", "dhw_kwh_per_m3", "dhw_cold_c", "dhw_hot_c", "tank_volume_l", "tank_heater_kw", "tank_cop", "tank_standby_w", "tank_erp_class", "tank_max_c", "tank_room_c", "tank_grossanlage": number}`, what the profile knows for every device of it (the list and its labels: `RATINGS` in `edge/cantabile_edge/devprofiles.py`, shared by the Hub's tool and the HA add-on). A field with `"rating": ` (type `int` or `number`, `optional`) asks the owner; it is asked on every path, and again later on the device's Ratings (the Hub's panel and the add-on's Devices page). A rating is a number above 0: a profile's, and every answer (0 or less is refused; an empty field: not known), hence `tank_erp_class` 1–7 for A+…F and `tank_grossanlage` 1 for yes. The ratings go to the agent (`devices-specs.json`, read at every plan) and to the cloud with the inventory. - **protection** (device): `{"level": "protected"|"sealed", "custodian": "metering_operator"|"grid_operator"|"community_operator"|"building_operator" (sealed only), "why"}`. - **register_protection** (Modbus profiles): `{"": {"level": "none"|"protected"|"sealed", "refuse"?: [values], "note"?}}`: the bridge's default per writable register; protected refuses switching off and the values listed, sealed every write. The owner's changes come from the box's policy (or, in the HA add-on, its policy file); sealed only signed. - **protect** (a setup path): `[{"match": matcher, "level", "custodian"?, "why"}]`: entities the path finds that get this level (e.g. an inverter's output switch). A control's `"protection": "protected"|"sealed"` (and `custodian`) protects that control. @@ -52,17 +52,28 @@ Each path: `{"path", "fields": [field names], "note", ...}`. - **`fallback`**: `true` marks a stand-in (the weather service's `outside.temp`): the agent gives its id to a measured value of the same quantity (an outdoor thermometer's `outside.temp_2` becomes `outside.temp`). - **inputs** (a setup path, the HA paths): `{"weather" | "outside_temp": matcher}`, the agent's mapping inputs the device gives (`ha-weather`: `inputs.weather`, its hourly forecast). One weather service plans: a second one's is kept unused until the owner picks it (`devices weather ID`). - **Assumed state:** a device without feedback (HA's `assumed_state`, or a climate without `hvac_action`: ESPHome's infrared climates, `climate_ir`: coolix, daikin, mitsubishi, heatpumpir, ...) shows what HA last sent it. A value found by a matcher with `"assumed": true` is marked `assumed` in the agent's mapping: read and sent like any other, listed as assumed in the inventory and on the panel ("Assumed, not measured"), and never feedback. The thermostat profile reads such a device's heating and cooling state from its mode (`equals` `heat` / `cool`), never from `hvac_action`. -- **controls**: `[{"kind": "battery|heating|cooling|ev|cover", "entities": {role: matcher}, "params": {...}, "safe": {...}}]`, the roles and params of the agent's mapping v3 (`edge/cantabile_edge/controls.py`). One control per entity: a later control that would write an entity an earlier one writes is left out, with one exception: a heating and a cooling control on one climate (a thermostat that heats and cools) are both mapped as a pair with `"switchover": {"mode": "season"}`, and the agent uses only one of them at a time (`edge/cantabile_edge/switchover.py`). The owner chooses on the Devices page (`devices switchover ID`): **Heating**, **Cooling**, **By season** (the default: heating October to April, cooling May to September, the site's local month) or **By outdoor temperature** (`heat_below_c`, `cool_above_c`: heating below the first, cooling above the second, and between them the side it was on, so a mild day does not flip it; the outdoor temperature is the mapping's `inputs.outside_temp`, else its `outside.temp`; without a reading it stays, and by season when it never had a side). The inactive control is not planned, never acts (the guard refuses it), and a command to it is refused; protection is per control, as before. A control whose matcher's `supports` the device lacks is left out, not reported missing. A climate control's setpoint stays inside the thermostat's own `min_temp`..`max_temp` (with the kind's range) and is rounded to its `target_temp_step` by the agent. +- **controls**: `[{"kind": "battery|heating|cooling|ev|cover|dhw_tank", "entities": {role: matcher}, "params": {...}, "safe": {...}}]`, the roles and params of the agent's mapping v3 (`edge/cantabile_edge/controls.py`; `dhw_tank`: docs/design/storage-losses.md 10.1). A control's entity matcher (the HA paths) may say **`"optional": true`**: a role the control has where the device has it (a tank's bottom sensor, its heater's power, a battery's own `standby` report), left out without a word where it has not; every other role must be found, else the control is reported missing; at least one role is not optional. The roles that write (one writer per entity, below): `charge_from_grid`, `setpoint`, `mode`, `climate`, `switch`, `current`, `cover`, `water_heater`, `sg_ready`, and a tank's `power` (a stepless heater's W; a battery's or a car's `power` is a reading). One control per entity: a later control that would write an entity an earlier one writes is left out, with one exception: a heating and a cooling control on one climate (a thermostat that heats and cools) are both mapped as a pair with `"switchover": {"mode": "season"}`, and the agent uses only one of them at a time (`edge/cantabile_edge/switchover.py`). The owner chooses on the Devices page (`devices switchover ID`): **Heating**, **Cooling**, **By season** (the default: heating October to April, cooling May to September, the site's local month) or **By outdoor temperature** (`heat_below_c`, `cool_above_c`: heating below the first, cooling above the second, and between them the side it was on, so a mild day does not flip it; the outdoor temperature is the mapping's `inputs.outside_temp`, else its `outside.temp`; without a reading it stays, and by season when it never had a side). The inactive control is not planned, never acts (the guard refuses it), and a command to it is refused; protection is per control, as before. A control whose matcher's `supports` the device lacks is left out, not reported missing. A climate control's setpoint stays inside the thermostat's own `min_temp`..`max_temp` (with the kind's range) and is rounded to its `target_temp_step` by the agent. ### Shades, temperature sensors, weather (the generic profiles) - **`ha-cover`** (any blind, curtain, shutter, awning): reads `room.{area}.shade_position` (and `.shade_tilt`; assumed for a cover without feedback); its `cover` control (position 0 closed .. 100 open; `set_cover_position`, or `open_cover`/`close_cover` for one without positions) is **protected by default**: a protected cover is not moved by Cantabile at all (it has no "off"), until the owner lifts that. The owner sets on the Devices page the room it shades (`params.area`; at first the device's area; the room's heating or cooling control, from another device in that room, becomes `params.room`) and the window's orientation (`params.facing`: N … NW or degrees; -1 not known) (`devices shade ID`). The agent moves it by rules on the sun (`edge/cantabile_edge/shades.py`): quiet hours `quiet_from`..`quiet_to` (22:00-07:00; `night_moves` 1 allows), `min_move_s` (1800) between moves, `override_hold_s` (4 h) off it after the owner moved it by hand. - **`ha-climate-sensor`** (any temperature and humidity sensor): `room.{area}.temp` and `.humidity` (a room that has one already: `temp_2`), matched by `device_class`; the sensor's battery is shown, not mapped. Indoor (a room) or outdoor (`outside.temp`, `outside.humidity` and the agent's `inputs.outside_temp`, before the main mapping's; the forecast is moved to what it measures now): `devices place ID`. +- **`ha-water-meter`** (any device with a water sensor; 2026-11-06): a hot-water meter: `dhw.volume` (litres drawn; HA's L or m³), `dhw.energy` (heat for hot water, Wh), `dhw.power` (W), each matched by device class and a hot-water name (hot water, Warmwasser, DHW). Its Ratings (the installer's): `dhw_litres_per_unit` (1 or 1000: the unit where HA shows none or a wrong one; written into the fragment as the asset's `unit_in`), `dhw_kwh_per_m3`, or `dhw_cold_c` and `dhw_hot_c` (kWh per m³ = 1.163 × (hot − cold)); without them the agent takes the Parameters row `dhw.temperature_lift_k` and says so (edge `devprofiles.dhw_factor`, the inventory's `dhw_kwh_per_m3` and `rating_sources`). - **`ha-weather`** (any weather service): `outside.temp` and `outside.humidity` as stand-ins (`fallback`), its forecast as `inputs.weather`. View card `weather`: HA's forecast card. +### Hot-water tanks and the battery's idle loss (2026-11-06) + +The plan treats a hot-water tank as a store of heat and counts a battery's and a tank's losses while they stand idle (docs/design/storage-losses.md; the names: its section 10). + +- **Battery profiles** (`hm8042-hybrid`, `solaredge-sunspec`, `huawei-sun2000`, `victron-gx`, `sma-sunny-boy`, `fronius-gen24`) ask, next to capacity, power and efficiency, for the idle loss (`battery_standby_w`, W: datasheet or measured; empty: the box learns it) and the self-discharge (`battery_self_discharge_pct_month`). Unlike the other three facts a missing idle loss never refuses the battery: the agent's order is mapping → device → learnt → owner → the Parameters row `battery.standby_w` (13 W, assumed). The battery's read-only `standby` role (a device's own report of its idle use, quantity `battery.standby_power`) is mapped by none of them: none of these integrations or register maps names such a value. +- **`ha-water-heater`** (any HA device with a `water_heater` entity, category `hot-water`): a `dhw_tank` control on its water heater (target temperature by the plan; **protected by default**: never switched off by Cantabile), with a bottom temperature sensor and a power sensor on the device where it has them (optional roles); values `dhw.temp_top` (the water heater's `current_temperature`), `dhw.temp_bottom`, `dhw.heater_power`. Its heater (`element`, `heat_pump`, `boiler`, `district`: the mapping's `params.heater`, which says what the heat costs) is the installer's choice on the device's page (`devices tank ID` `{"heater"}`); a profile cannot know it, so the fragment has none until then and the agent does not plan the tank without it. Ratings: `tank_volume_l`, `tank_heater_kw` (electric for an element or a heat pump, heat for a boiler or district heat), `tank_cop` (a heat pump), `tank_standby_w` (ErP S from the label, W) or `tank_erp_class`, `tank_max_c`, `tank_room_c`, `tank_grossanlage`. Volume, heater power and a heat pump's COP have no stand-in: without them the tank is not planned and the Devices page says what is needed; a missing loss is planned at class D's limit (assumed, a quiet line). +- **`ha-immersion-heater`** (a tank without a water heater entity: an immersion heater on a relay with the tank's sensors): `switch` (the relay) and `temp_top` needed, `temp_bottom` and `heater_power` optional, `params.heater` `element`. A relay alone says nothing about a tank, so the profile recognises no device by itself: it is added under Add device → Home Assistant (the Hub), and finds its entities across Home Assistant by their names (the relay `…immersion…` / `…heizstab…` / `…heating_rod…` / `…tank_heater…`, the sensors `…tank|speicher|boiler|warmwasser|hot_water|dhw…` with `top|oben|upper` and `bottom|unten|lower`); rename them in HA to fit. +- **The Devices pages** (the Hub's panel and the add-on's) show the battery's idle loss with its source in one line above its Ratings ("Idle loss 49 W (learnt by the box)", "13 W assumed (Parameters): enter the datasheet's value below"), and for a tank its heater, its facts, the standing loss's source (the label, the installer's, learnt, or assumed at a class's limit) and what it is not planned without. The source is the agent's latest plan (`storage`, `refused`: its preferences view's `planning`, `devprofiles.storage_of`); before a plan, what the installer and the owner gave. +- **Not expressible today:** the heater kind as a field of the Add device form (a field is a host, port, number or text; it is a setting on the device's page instead); a device made of entities of several HA devices offered by itself (`recognise` matches one HA device by maker, model, integration and entity domains, never entity names); a tank's SG-Ready select (its option names, `params.sg_options`, differ per device) and a diverter's `power` number in the generic profiles (they need the installer's mapping, or a vendor's profile). + ### Quantities -Cantabile's names (the agent's asset ids, the dashboards', the cloud's), with their unit and sign: `grid.power` (W, import +), `grid.import_power`, `grid.export_power`, `grid.import_energy`, `grid.export_energy` (Wh, counters), `pv.power`, `pv.energy`, `battery.power` (W, charge +), `battery.soc` (%), `battery.charge_energy`, `battery.discharge_energy`, `load.power`, `load.energy`, `heatpump.power`, `heatpump.energy`, `heat.power`, `heat.energy`, `heatpump.flow_temp`, `heatpump.dhw_temp`, `outside.temp` (°C), `heating.state`, `cooling.state` (1 while heating or cooling, else 0: a climate's hvac_action; for a device without feedback its mode, assumed), `gas.energy`, `ev.power`, `ev.energy`; per place: `room.{area}.temp`, `room.{area}.humidity`, `room.{area}.setpoint`, `room.{area}.setpoint_low`, `room.{area}.setpoint_high` (°C: a thermostat's target temperature; low and high in heat/cool), `room.{area}.shade_position`, `room.{area}.shade_tilt` (%, 0 closed), `outside.humidity` (%), `circuit.{area}.power`, `circuit.{area}.energy` (`{area}`: the HA device's area). +Cantabile's names (the agent's asset ids, the dashboards', the cloud's), with their unit and sign: `grid.power` (W, import +), `grid.import_power`, `grid.export_power`, `grid.import_energy`, `grid.export_energy` (Wh, counters), `pv.power`, `pv.energy`, `battery.power` (W, charge +), `battery.soc` (%), `battery.charge_energy`, `battery.discharge_energy`, `load.power`, `load.energy`, `heatpump.power`, `heatpump.energy`, `heat.power`, `heat.energy`, `heatpump.flow_temp`, `heatpump.dhw_temp`, `outside.temp` (°C), `heating.state`, `cooling.state` (1 while heating or cooling, else 0: a climate's hvac_action; for a device without feedback its mode, assumed), `gas.energy`, `ev.power`, `ev.energy`, `dhw.power` (W, heat for hot water), `dhw.energy` (Wh, the hot-water meter's counter), `dhw.volume` (L, hot water drawn), `battery.standby_power` (W, a battery's own report of its idle use), `dhw.temp_top`, `dhw.temp_bottom` (°C, a tank's temperatures), `dhw.heater_power` (W, a tank's heater), `dhw.tank_energy` (Wh, gauge: the heat a tank holds above the cold water); per place: `room.{area}.temp`, `room.{area}.humidity`, `room.{area}.setpoint`, `room.{area}.setpoint_low`, `room.{area}.setpoint_high` (°C: a thermostat's target temperature; low and high in heat/cool), `room.{area}.shade_position`, `room.{area}.shade_tilt` (%, 0 closed), `outside.humidity` (%), `circuit.{area}.power`, `circuit.{area}.energy` (`{area}`: the HA device's area). ### Modbus registers diff --git a/src/profiles/fronius-gen24.json b/src/profiles/fronius-gen24.json index ef9440f..50d217b 100644 --- a/src/profiles/fronius-gen24.json +++ b/src/profiles/fronius-gen24.json @@ -1,6 +1,6 @@ { "id": "fronius-gen24", - "version": "1.0.3", + "version": "1.0.4", "manufacturer": "Fronius", "name": "Symo / Primo GEN24 (with Smart Meter and BYD battery)", "models": ["Symo GEN24*", "Primo GEN24*", "Symo*", "Primo*"], @@ -14,7 +14,9 @@ {"name": "rated_pv_kwp", "label": "Solar panels, kWp (optional)", "type": "number", "rating": "pv_kwp", "optional": true, "min": 0, "max": 1000}, {"name": "rated_battery_kwh", "label": "Battery capacity, kWh (optional)", "type": "number", "rating": "battery_kwh", "optional": true, "min": 0, "max": 1000}, {"name": "rated_battery_kw", "label": "Battery power, kW (optional)", "type": "number", "rating": "battery_kw", "optional": true, "min": 0, "max": 1000}, - {"name": "rated_battery_efficiency_pct", "label": "Battery round-trip efficiency, % (optional; datasheet)", "type": "number", "rating": "battery_efficiency_pct", "optional": true, "min": 1, "max": 100} + {"name": "rated_battery_efficiency_pct", "label": "Battery round-trip efficiency, % (optional; datasheet)", "type": "number", "rating": "battery_efficiency_pct", "optional": true, "min": 1, "max": 100}, + {"name": "rated_battery_standby_w", "label": "Battery idle loss, W (optional; datasheet or measured; leave empty and the box learns it)", "type": "number", "rating": "battery_standby_w", "optional": true, "min": 0.1, "max": 1000}, + {"name": "rated_battery_self_discharge_pct_month", "label": "Battery self-discharge, %/month (optional; datasheet)", "type": "number", "rating": "battery_self_discharge_pct_month", "optional": true, "min": 0.01, "max": 50} ], "setup": [ {"path": "ha", "domain": "fronius", "fields": ["host"], diff --git a/src/profiles/ha-immersion-heater.json b/src/profiles/ha-immersion-heater.json new file mode 100644 index 0000000..3292f26 --- /dev/null +++ b/src/profiles/ha-immersion-heater.json @@ -0,0 +1,41 @@ +{ + "id": "ha-immersion-heater", + "version": "1.0.0", + "manufacturer": "Home Assistant", + "name": "Immersion heater on a relay, with tank sensors", + "models": ["*"], + "category": "hot-water", + "status": "documented", + "source": "A hot-water tank without a water_heater entity: an immersion heater (Heizstab) switched by a relay (any HA switch) and the tank's temperature sensors (top, optionally bottom), with the heater's power where a sensor measures it. Found by the entities' names, across Home Assistant (not offered by itself: add it under Add device, Home Assistant): the relay switch.<...>immersion / heizstab / heating_rod / tank_heater, the sensors <...>tank / speicher / boiler / warmwasser / hot_water / dhw with top / oben / upper (bottom / unten / lower), the power sensor like the relay. Rename the entities in Home Assistant to fit. Cantabile plans the tank as a store of heat (docs/design/storage-losses.md, control kind dhw_tank, heater element).", + "recognise": {}, + "fields": [ + {"name": "rated_tank_volume_l", "label": "Hot-water tank, litres (the type plate; needed: the tank is not planned without it)", "type": "number", "rating": "tank_volume_l", "optional": true, "min": 1, "max": 20000}, + {"name": "rated_tank_heater_kw", "label": "Immersion heater, kW (its type plate; needed)", "type": "number", "rating": "tank_heater_kw", "optional": true, "min": 0.01, "max": 100}, + {"name": "rated_tank_standby_w", "label": "Tank standing loss (ErP S), W (the label or datasheet; kWh per 24 h ÷ 0.024)", "type": "number", "rating": "tank_standby_w", "optional": true, "min": 0.1, "max": 2000}, + {"name": "rated_tank_erp_class", "label": "Tank ErP class (1 A+, 2 A, 3 B, 4 C, 5 D, 6 E, 7 F; where the standing loss is not known)", "type": "int", "rating": "tank_erp_class", "optional": true, "min": 1, "max": 7}, + {"name": "rated_tank_max_c", "label": "Tank maximum, °C (optional)", "type": "number", "rating": "tank_max_c", "optional": true, "min": 30, "max": 95}, + {"name": "rated_tank_room_c", "label": "Room temperature at the tank, °C (optional)", "type": "number", "rating": "tank_room_c", "optional": true, "min": 1, "max": 40}, + {"name": "rated_tank_grossanlage", "label": "Large system, DVGW W 551 (1: yes; optional, else from the volume)", "type": "int", "rating": "tank_grossanlage", "optional": true, "min": 1, "max": 1} + ], + "setup": [ + {"path": "existing", "note": "In Home Assistant already: the immersion heater's relay and the tank's sensors, found by their names (see the profile's source). Enter the tank's volume, the heater's power and the standing loss from its label under Ratings.", + "values": { + "dhw.temp_top": {"entity_id": "^sensor\\..*(tank|speicher|boiler|warmwasser|hot_?water|dhw).*(top|oben|upper)", "device_class": "temperature"}, + "dhw.temp_bottom": {"entity_id": "^sensor\\..*(tank|speicher|boiler|warmwasser|hot_?water|dhw).*(bottom|unten|lower)", "device_class": "temperature"}, + "dhw.heater_power": {"entity_id": "^sensor\\..*(immersion|heizstab|heating_rod|tank_heater)", "device_class": "power"} + }, + "controls": [ + {"kind": "dhw_tank", + "entities": {"switch": {"entity_id": "^switch\\..*(immersion|heizstab|heating_rod|tank_heater)"}, + "temp_top": {"entity_id": "^sensor\\..*(tank|speicher|boiler|warmwasser|hot_?water|dhw).*(top|oben|upper)", "device_class": "temperature"}, + "temp_bottom": {"entity_id": "^sensor\\..*(tank|speicher|boiler|warmwasser|hot_?water|dhw).*(bottom|unten|lower)", "device_class": "temperature", "optional": true}, + "heater_power": {"entity_id": "^sensor\\..*(immersion|heizstab|heating_rod|tank_heater)", "device_class": "power", "optional": true}}, + "params": {"heater": "element"}, + "note": "The relay on and off by the plan (an element, COP 1), at least min_switch_s apart; the element's own thermostat stays the last limit."} + ]} + ], + "view": { + "card": "sensor", + "headline": ["dhw.temp_top", "dhw.temp_bottom", "dhw.heater_power"] + } +} diff --git a/src/profiles/ha-water-heater.json b/src/profiles/ha-water-heater.json new file mode 100644 index 0000000..c486cfa --- /dev/null +++ b/src/profiles/ha-water-heater.json @@ -0,0 +1,42 @@ +{ + "id": "ha-water-heater", + "version": "1.0.0", + "manufacturer": "Home Assistant", + "name": "Hot-water tank (any water heater)", + "models": ["*"], + "category": "hot-water", + "status": "documented", + "source": "Home Assistant's water_heater entity (current_temperature, temperature, min_temp, max_temp, operation_mode; actions set_temperature, set_operation_mode, turn_on/off). Generic: any HA device with a water_heater entity that no specific profile recognises. Cantabile plans the tank as a store of heat (docs/design/storage-losses.md, control kind dhw_tank): its current temperature is the tank's temperature; a temperature sensor named bottom/unten and a power sensor on the device are read where it has them. The heater (an element, a heat pump, a boiler, district heat) is the installer's choice on the Devices page; the volume, the heater's power, a heat pump's COP and the standing loss (ErP label) are the Ratings.", + "recognise": {"ha": [{"entity_domain": "water_heater"}], "fallback": true}, + "fields": [ + {"name": "rated_tank_volume_l", "label": "Hot-water tank, litres (the type plate; needed: the tank is not planned without it)", "type": "number", "rating": "tank_volume_l", "optional": true, "min": 1, "max": 20000}, + {"name": "rated_tank_heater_kw", "label": "Tank heater, kW (electric for an element or heat pump, heat for a boiler or district heat; needed)", "type": "number", "rating": "tank_heater_kw", "optional": true, "min": 0.01, "max": 1000}, + {"name": "rated_tank_cop", "label": "Tank heat pump COP (datasheet, EN 16147; a heat pump only)", "type": "number", "rating": "tank_cop", "optional": true, "min": 1, "max": 10}, + {"name": "rated_tank_standby_w", "label": "Tank standing loss (ErP S), W (the label or datasheet; kWh per 24 h ÷ 0.024)", "type": "number", "rating": "tank_standby_w", "optional": true, "min": 0.1, "max": 2000}, + {"name": "rated_tank_erp_class", "label": "Tank ErP class (1 A+, 2 A, 3 B, 4 C, 5 D, 6 E, 7 F; where the standing loss is not known)", "type": "int", "rating": "tank_erp_class", "optional": true, "min": 1, "max": 7}, + {"name": "rated_tank_max_c", "label": "Tank maximum, °C (optional)", "type": "number", "rating": "tank_max_c", "optional": true, "min": 30, "max": 95}, + {"name": "rated_tank_room_c", "label": "Room temperature at the tank, °C (optional)", "type": "number", "rating": "tank_room_c", "optional": true, "min": 1, "max": 40}, + {"name": "rated_tank_grossanlage", "label": "Large system, DVGW W 551 (1: yes; optional, else from the volume)", "type": "int", "rating": "tank_grossanlage", "optional": true, "min": 1, "max": 1} + ], + "setup": [ + {"path": "existing", "note": "In Home Assistant already (any integration): a water heater. Choose its heater on the device's page and enter the tank's volume, the heater's power (a heat pump: its COP) and the standing loss from its label under Ratings. Protected: Cantabile sets its target temperature, never switches it off, until the owner lifts that.", + "values": { + "dhw.temp_top": [{"entity_id": "^water_heater\\.", "attribute": "current_temperature"}, + {"entity_id": "^sensor\\..*(top|oben|upper)", "device_class": "temperature"}], + "dhw.temp_bottom": {"entity_id": "^sensor\\..*(bottom|unten|lower)", "device_class": "temperature"}, + "dhw.heater_power": {"entity_id": "^sensor\\.", "device_class": "power"} + }, + "controls": [ + {"kind": "dhw_tank", "protection": "protected", + "entities": {"water_heater": {"entity_id": "^water_heater\\."}, + "temp_bottom": {"entity_id": "^sensor\\..*(bottom|unten|lower)", "device_class": "temperature", "optional": true}, + "heater_power": {"entity_id": "^sensor\\.", "device_class": "power", "optional": true}}, + "note": "The water heater's target temperature by the plan, within its own min_temp..max_temp and the owner's limits; its current temperature is the tank's. The heater (params.heater) is the installer's choice on the Devices page."} + ]} + ], + "view": { + "card": "sensor", + "values": {"tank": {"domain": "water_heater"}, "heater": {"domain": "sensor", "device_class": "power"}}, + "headline": ["tank", "heater"] + } +} diff --git a/src/profiles/ha-water-meter.json b/src/profiles/ha-water-meter.json new file mode 100644 index 0000000..37a7749 --- /dev/null +++ b/src/profiles/ha-water-meter.json @@ -0,0 +1,30 @@ +{ + "id": "ha-water-meter", + "version": "1.0.0", + "manufacturer": "Home Assistant", + "name": "Hot-water meter (any)", + "models": ["*"], + "category": "meter", + "status": "documented", + "source": "Home Assistant's water sensors (device class water: L or m³) and energy or power sensors named for hot water (hot water, Warmwasser, DHW). Generic: any HA device with a water sensor that no specific profile recognises. Cantabile reads the heat for hot water (dhw.energy, dhw.power) or the hot water drawn (dhw.volume, litres); a volume becomes heat by the installer's kWh per m³, else 1.163 x (hot - cold water temperature), else the Parameters row dhw.temperature_lift_k (docs/methods.md B16, A2).", + "recognise": {"ha": [{"entity_domain": "sensor.water"}], "fallback": true, + "exclude": [{"entity_domain": "climate"}, {"entity_domain": "water_heater"}]}, + "fields": [ + {"name": "rated_dhw_litres_per_unit", "label": "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)", "type": "number", "rating": "dhw_litres_per_unit", "optional": true, "min": 1, "max": 1000}, + {"name": "rated_dhw_kwh_per_m3", "label": "Hot water: kWh of heat per m³ drawn (optional; else from the two temperatures)", "type": "number", "rating": "dhw_kwh_per_m3", "optional": true, "min": 1, "max": 100}, + {"name": "rated_dhw_cold_c", "label": "Cold water temperature, °C (optional)", "type": "number", "rating": "dhw_cold_c", "optional": true, "min": 1, "max": 30}, + {"name": "rated_dhw_hot_c", "label": "Hot water temperature at the tap, °C (optional)", "type": "number", "rating": "dhw_hot_c", "optional": true, "min": 20, "max": 95} + ], + "setup": [ + {"path": "existing", "note": "In Home Assistant already (any integration): a meter of the hot water drawn, or of the heat for hot water. Its unit, kWh per m³ or the cold and hot water's temperatures: the installer's, on the device's Ratings.", + "values": { + "dhw.volume": {"entity_id": "^sensor\\..*(hot_?water|warm_?wasser|dhw)", "device_class": "water"}, + "dhw.energy": {"entity_id": "^sensor\\..*(hot_?water|warm_?wasser|dhw)", "device_class": "energy"}, + "dhw.power": {"entity_id": "^sensor\\..*(hot_?water|warm_?wasser|dhw)", "device_class": "power"} + }} + ], + "view": { + "card": "meter", + "headline": ["dhw.volume", "dhw.energy", "dhw.power"] + } +} diff --git a/src/profiles/hm8042-hybrid.json b/src/profiles/hm8042-hybrid.json index aefdc4b..8e43f74 100644 --- a/src/profiles/hm8042-hybrid.json +++ b/src/profiles/hm8042-hybrid.json @@ -1,6 +1,6 @@ { "id": "hm8042-hybrid", - "version": "0.3.2", + "version": "0.3.3", "manufacturer": "HM", "name": "HM8042 hybrid inverter (EPEVER protocol)", "models": [ @@ -80,6 +80,24 @@ "optional": true, "min": 1, "max": 100 + }, + { + "name": "rated_battery_standby_w", + "label": "Battery idle loss, W (optional; datasheet or measured; leave empty and the box learns it)", + "type": "number", + "rating": "battery_standby_w", + "optional": true, + "min": 0.1, + "max": 1000 + }, + { + "name": "rated_battery_self_discharge_pct_month", + "label": "Battery self-discharge, %/month (optional; datasheet)", + "type": "number", + "rating": "battery_self_discharge_pct_month", + "optional": true, + "min": 0.01, + "max": 50 } ], "setup": [ diff --git a/src/profiles/huawei-sun2000.json b/src/profiles/huawei-sun2000.json index 8487cf1..1aab13d 100644 --- a/src/profiles/huawei-sun2000.json +++ b/src/profiles/huawei-sun2000.json @@ -1,6 +1,6 @@ { "id": "huawei-sun2000", - "version": "1.0.3", + "version": "1.0.4", "manufacturer": "Huawei", "name": "SUN2000 inverter (with LUNA2000 battery and DTSU666 meter)", "models": ["SUN2000-*KTL-L1", "SUN2000-*KTL-M1", "SUN2000-*KTL-M0", "SUN2000-*K-MAP0", "SUN2000-*K-MB0"], @@ -18,7 +18,9 @@ {"name": "rated_pv_kwp", "label": "Solar panels, kWp (optional)", "type": "number", "rating": "pv_kwp", "optional": true, "min": 0, "max": 1000}, {"name": "rated_battery_kwh", "label": "Battery capacity, kWh (optional)", "type": "number", "rating": "battery_kwh", "optional": true, "min": 0, "max": 1000}, {"name": "rated_battery_kw", "label": "Battery power, kW (optional)", "type": "number", "rating": "battery_kw", "optional": true, "min": 0, "max": 1000}, - {"name": "rated_battery_efficiency_pct", "label": "Battery round-trip efficiency, % (optional; datasheet)", "type": "number", "rating": "battery_efficiency_pct", "optional": true, "min": 1, "max": 100} + {"name": "rated_battery_efficiency_pct", "label": "Battery round-trip efficiency, % (optional; datasheet)", "type": "number", "rating": "battery_efficiency_pct", "optional": true, "min": 1, "max": 100}, + {"name": "rated_battery_standby_w", "label": "Battery idle loss, W (optional; datasheet or measured; leave empty and the box learns it)", "type": "number", "rating": "battery_standby_w", "optional": true, "min": 0.1, "max": 1000}, + {"name": "rated_battery_self_discharge_pct_month", "label": "Battery self-discharge, %/month (optional; datasheet)", "type": "number", "rating": "battery_self_discharge_pct_month", "optional": true, "min": 0.01, "max": 50} ], "setup": [ {"path": "ha-integration", "addon": "huawei-solar", "domain": "huawei_solar", "fields": ["host", "port", "unit_id"], diff --git a/src/profiles/sma-sunny-boy.json b/src/profiles/sma-sunny-boy.json index 93ea86f..68df93b 100644 --- a/src/profiles/sma-sunny-boy.json +++ b/src/profiles/sma-sunny-boy.json @@ -1,6 +1,6 @@ { "id": "sma-sunny-boy", - "version": "1.0.3", + "version": "1.0.4", "manufacturer": "SMA", "name": "Sunny Boy / Sunny Tripower (with SMA Energy Meter)", "models": ["SB*", "STP*", "Sunny Boy*", "Sunny Tripower*"], @@ -17,7 +17,9 @@ {"name": "rated_pv_kwp", "label": "Solar panels, kWp (optional)", "type": "number", "rating": "pv_kwp", "optional": true, "min": 0, "max": 1000}, {"name": "rated_battery_kwh", "label": "Battery capacity, kWh (optional)", "type": "number", "rating": "battery_kwh", "optional": true, "min": 0, "max": 1000}, {"name": "rated_battery_kw", "label": "Battery power, kW (optional)", "type": "number", "rating": "battery_kw", "optional": true, "min": 0, "max": 1000}, - {"name": "rated_battery_efficiency_pct", "label": "Battery round-trip efficiency, % (optional; datasheet)", "type": "number", "rating": "battery_efficiency_pct", "optional": true, "min": 1, "max": 100} + {"name": "rated_battery_efficiency_pct", "label": "Battery round-trip efficiency, % (optional; datasheet)", "type": "number", "rating": "battery_efficiency_pct", "optional": true, "min": 1, "max": 100}, + {"name": "rated_battery_standby_w", "label": "Battery idle loss, W (optional; datasheet or measured; leave empty and the box learns it)", "type": "number", "rating": "battery_standby_w", "optional": true, "min": 0.1, "max": 1000}, + {"name": "rated_battery_self_discharge_pct_month", "label": "Battery self-discharge, %/month (optional; datasheet)", "type": "number", "rating": "battery_self_discharge_pct_month", "optional": true, "min": 0.01, "max": 50} ], "setup": [ {"path": "ha", "domain": "sma", "fields": ["host", "password"], diff --git a/src/profiles/solaredge-sunspec.json b/src/profiles/solaredge-sunspec.json index ff7e94b..5754948 100644 --- a/src/profiles/solaredge-sunspec.json +++ b/src/profiles/solaredge-sunspec.json @@ -1,6 +1,6 @@ { "id": "solaredge-sunspec", - "version": "1.0.3", + "version": "1.0.4", "manufacturer": "SolarEdge", "name": "SE inverter over Modbus TCP (SunSpec, with SolarEdge meter)", "models": ["SE*"], @@ -16,7 +16,9 @@ {"name": "rated_pv_kwp", "label": "Solar panels, kWp (optional)", "type": "number", "rating": "pv_kwp", "optional": true, "min": 0, "max": 1000}, {"name": "rated_battery_kwh", "label": "Battery capacity, kWh (optional)", "type": "number", "rating": "battery_kwh", "optional": true, "min": 0, "max": 1000}, {"name": "rated_battery_kw", "label": "Battery power, kW (optional)", "type": "number", "rating": "battery_kw", "optional": true, "min": 0, "max": 1000}, - {"name": "rated_battery_efficiency_pct", "label": "Battery round-trip efficiency, % (optional; datasheet)", "type": "number", "rating": "battery_efficiency_pct", "optional": true, "min": 1, "max": 100} + {"name": "rated_battery_efficiency_pct", "label": "Battery round-trip efficiency, % (optional; datasheet)", "type": "number", "rating": "battery_efficiency_pct", "optional": true, "min": 1, "max": 100}, + {"name": "rated_battery_standby_w", "label": "Battery idle loss, W (optional; datasheet or measured; leave empty and the box learns it)", "type": "number", "rating": "battery_standby_w", "optional": true, "min": 0.1, "max": 1000}, + {"name": "rated_battery_self_discharge_pct_month", "label": "Battery self-discharge, %/month (optional; datasheet)", "type": "number", "rating": "battery_self_discharge_pct_month", "optional": true, "min": 0.01, "max": 50} ], "setup": [ {"path": "modbus", "fields": ["host", "port", "unit_id"]} diff --git a/src/profiles/victron-gx.json b/src/profiles/victron-gx.json index 31ee507..295c83e 100644 --- a/src/profiles/victron-gx.json +++ b/src/profiles/victron-gx.json @@ -1,6 +1,6 @@ { "id": "victron-gx", - "version": "1.0.3", + "version": "1.0.4", "manufacturer": "Victron Energy", "name": "GX device (Cerbo GX, Venus GX) with ESS", "models": ["Cerbo GX*", "Venus GX*", "Ekrano GX*", "Color Control GX*"], @@ -14,7 +14,9 @@ {"name": "unit_id", "label": "Modbus unit id (the system: 100)", "type": "int", "default": 100, "min": 0, "max": 247}, {"name": "rated_battery_kwh", "label": "Battery capacity, kWh (optional)", "type": "number", "rating": "battery_kwh", "optional": true, "min": 0, "max": 1000}, {"name": "rated_battery_kw", "label": "Battery power, kW (optional)", "type": "number", "rating": "battery_kw", "optional": true, "min": 0, "max": 1000}, - {"name": "rated_battery_efficiency_pct", "label": "Battery round-trip efficiency, % (optional; datasheet)", "type": "number", "rating": "battery_efficiency_pct", "optional": true, "min": 1, "max": 100} + {"name": "rated_battery_efficiency_pct", "label": "Battery round-trip efficiency, % (optional; datasheet)", "type": "number", "rating": "battery_efficiency_pct", "optional": true, "min": 1, "max": 100}, + {"name": "rated_battery_standby_w", "label": "Battery idle loss, W (optional; datasheet or measured; leave empty and the box learns it)", "type": "number", "rating": "battery_standby_w", "optional": true, "min": 0.1, "max": 1000}, + {"name": "rated_battery_self_discharge_pct_month", "label": "Battery self-discharge, %/month (optional; datasheet)", "type": "number", "rating": "battery_self_discharge_pct_month", "optional": true, "min": 0.01, "max": 50} ], "setup": [ {"path": "modbus", "fields": ["host", "port", "unit_id"]}