# Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved. """Inputs for the optimiser: the latest states of the controls' and the inputs' entities (presence, temperatures, humidity, outside temperature, sun, weather), a short local history of load and PV (the fallback when no model bundle says), and the 15-minute model state for the horizon. A room's R and C: the mapping's, else the box's or the cloud's fit (the model bundle's rooms); none: the room is not planned (room_refusal) and keeps a fallback schedule; sources.rooms says which per control. None of this leaves the site; only the plan does (controller.py). 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 import math import os import time from datetime import datetime, timezone from zoneinfo import ZoneInfo 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: try: x = float(v) except (TypeError, ValueError): return None return x if x == x and abs(x) != math.inf else None class Collector: """States of the entities the agent watches, in HA's compact subscribe_entities form. Observers (the guard) see every change.""" def __init__(self): self.states: dict[str, dict] = {} self.observers = [] def on_entities(self, ev: dict, now: float | None = None): now = time.time() if now is None else now for eid, s in (ev.get("a") or {}).items(): self.states[eid] = {"s": s.get("s"), "a": dict(s.get("a") or {}), "t": s.get("lc") or now, "c": s.get("c")} for eid, c in (ev.get("c") or {}).items(): cur = self.states.setdefault(eid, {"s": None, "a": {}, "t": now}) plus, minus = c.get("+") or {}, c.get("-") or {} if "s" in plus: cur["s"] = plus["s"] # the change's context (HA: an id alone, or {"id", "user_id", "parent_id"}): who made it (guard.changed_by) cur["c"] = plus.get("c") cur["a"].update(plus.get("a") or {}) for k in minus.get("a") or []: cur["a"].pop(k, None) cur["t"] = plus.get("lc") or plus.get("lu") or now for obs in self.observers: obs(eid, cur, now) def state(self, eid: str): return (self.states.get(eid) or {}).get("s") def attr(self, eid: str, name: str): return ((self.states.get(eid) or {}).get("a") or {}).get(name) def value(self, eid: str) -> float | None: return number(self.state(eid)) if eid else None def total(self, eids: str | list) -> float | None: """One entity's value, or the sum of several (parts: pv.1.power, ...); None while any of them has none.""" if isinstance(eids, str): return self.value(eids) vals = [self.value(e) for e in eids or []] return None if not vals or None in vals else sum(vals) def age(self, eid: str, now: float) -> float: st = self.states.get(eid) return now - float(st["t"]) if st and st.get("t") else math.inf class History: """Quarter-hour means of load and PV (W) for the last 8 days, kept on disk, for "the same quarter hour yesterday" and the box's models' "the same slot a week before" (localml.py); since 2026-11-12 (methods.md G2, G5 in the plan) also the outdoor temperature ("t_out", °C: the comfort band's running mean) and each planned room's temperature ("room:", °C: the flat's mass now, inputs.mass_start).""" def __init__(self, path: str): self.path = path self.slots: dict[str, dict[int, list[float]]] = {"load_w": {}, "pv_w": {}} try: with open(path) as f: raw = json.load(f) keys = set(self.slots) | {k for k in raw if k in ("t_out",) or k.startswith("room:")} self.slots = {k: {int(t): v for t, v in raw.get(k, {}).items()} for k in keys} except (OSError, ValueError, AttributeError): pass def add(self, name: str, value: float | None, now: float): if value is None: return slot = int(now // STEP_S * STEP_S) s, n = self.slots.setdefault(name, {}).get(slot, [0.0, 0]) self.slots[name][slot] = [s + value, n + 1] def mean(self, name: str, slot: int) -> float | None: s = self.slots.get(name, {}).get(slot) return s[0] / s[1] if s and s[1] else None def series(self, name: str, start: int, n: int) -> list[float | None]: """The quarter-hour means of n slots from start (None where none).""" return [self.mean(name, start + k * STEP_S) for k in range(n)] def save(self, now: float): cut = now - HISTORY_S for k in self.slots: self.slots[k] = {t: v for t, v in self.slots[k].items() if t >= cut} tmp = self.path + ".tmp" with open(tmp, "w") as f: json.dump(self.slots, f) os.replace(tmp, self.path) def _hourly(forecast: list[dict], key: str, start: int, steps: int) -> list[float] | None: """A weather forecast's hourly value, held for each quarter hour.""" pts = [] for f in forecast or []: v = number(f.get(key)) try: ts = datetime.fromisoformat(str(f["datetime"]).replace("Z", "+00:00")).timestamp() except (KeyError, ValueError): continue if v is not None: pts.append((ts, v)) if not pts: return None pts.sort() out, j = [], 0 for k in range(steps): t = start + k * STEP_S while j + 1 < len(pts) and pts[j + 1][0] <= t: j += 1 out.append(pts[j][1]) return out def outdoor_temperature(start: int, col: Collector, inputs, ha_forecast: list[dict] | None, fleet_forecast: list[dict] | None) -> tuple[list[float] | None, str]: """The outdoor temperature per step and where it is from (the plan's sources.outdoor, methods.md A1.4): "ha_entity" (the mapping's weather entity's forecast), else "fleet_forecast" (fleet's DWD forecast for the site's cell, bundles.weather_forecast), either "+sensor_bias" where an outdoor sensor reads now (the forecast moved by the difference, fading over 6 hours); else "sensor_now" or "ha_entity_now" (that value held); else (None, "none"): no stand-in.""" measured = col.value(inputs.outside_temp) if inputs.outside_temp else None t_out, src = _hourly(ha_forecast or [], "temperature", start, STEPS), "ha_entity" if t_out is None: t_out, src = _hourly(fleet_forecast or [], "temperature", start, STEPS), "fleet_forecast" if t_out is not None: if measured is not None: # a thermometer outside says better than the forecast what it is now bias = measured - t_out[0] t_out = [v + bias * max(0.0, 1 - k / 24) for k, v in enumerate(t_out)] src += "+sensor_bias" return t_out, src if measured is not None: return [measured] * STEPS, "sensor_now" now_out = number(col.attr(inputs.weather, "temperature")) if inputs.weather else None if now_out is not None: return [now_out] * STEPS, "ha_entity_now" return None, "none" def outdoor_now(col: Collector, inputs) -> float | None: """The outdoor temperature now for the history (the comfort band's running mean, G5): the outdoor sensor, else the weather entity's temperature, else None.""" v = col.value(inputs.outside_temp) if getattr(inputs, "outside_temp", None) else None if v is None and getattr(inputs, "weather", None): v = number(col.attr(inputs.weather, "temperature")) return v if v is not None and -60.0 < v < 60.0 else None def watts(col: Collector, eid: str) -> float | None: """A power sensor's value in W (HA's kW converted).""" v = col.value(eid) if v is not None and col.attr(eid, "unit_of_measurement") == "kW": v *= 1000.0 return v def base_load(col: Collector, inputs) -> float | None: """The house's load without the devices the plan plans itself (Finding A2-a): load_power less the planned devices' own meters (inputs.controlled_power: heat pump, A/C, charger), never below 0. A device meter without a value counts 0 (a charger's sensor goes unavailable while idle). None while the load has none.""" eids = [inputs.load_power] if isinstance(inputs.load_power, str) else list(inputs.load_power or []) vals = [watts(col, e) for e in eids if e] if not vals or None in vals: return None ctl = sum(watts(col, e) or 0.0 for e in getattr(inputs, "controlled_power", None) or []) return max(0.0, sum(vals) - ctl) FC_SOURCES = {"own": "the box's own model", "cloud": "the cloud's series", "box": "the cloud's model on the box", "hour_of_week": "the hour-of-week profile"} 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, 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_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: # no cloud model for it: the box's own alone, where it covers the horizon 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] info = {"series": m, "own": 0, "cloud": 0, "box": 0, "hour_of_week": 0} 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_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 lab.append("own") elif src == "series": lab.append("cloud") elif b is not None: vals[k] = b lab.append("box") else: 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"): info["own_weather"] = mine[1]["weather"] if own is not None: info["box_model"] = own[1].get("kind") if own[1].get("weather"): info["box_weather"] = own[1]["weather"] if own[1].get("error"): info["box_error"] = own[1]["error"] info["source"] = max(("own", "cloud", "box", "hour_of_week"), key=lambda k: info[k]) if trainer is not None: info["_cands"] = {"own": list(mine[0]) if mine is not None else None, "cloud": cloud_series, "cloud_model": list(own[0]) if own is not None else None, "hour_of_week": (bundles.profile(m, start, STEP_S, STEPS, tz) if hasattr(bundles, "profile") else [v if src == "profile" else None for v, src in parts])} if not info["own"]: info.pop("own") return vals, info def _series(name, start, bundles, history, tz, now_value, default, model_names=None, box=None, info=None): """A series for the horizon: the model bundle's (the first of model_names it has, default name: _model_series), else the same quarter hour 1 or 2 days back, else the value now, else the default. info (a dict): filled with the model's steps by source.""" for m in (model_names if model_names is not None else (name,)): got = _model_series(m, start, bundles, history, tz, box) if bundles else None if got is not None: s, n = got src = "model" if m == name else f"model ({m})" if n.get("own"): src += (f"; the box's own {n.get('own_model')} model (trained on the box) for {n['own']} of {STEPS} steps" f" (weather: {n.get('own_weather') or 'none'})") if n.get("box"): src += (f"; the box's own {n.get('box_model')} model for {n['box']} of {STEPS} steps" f" (weather: {n.get('box_weather') or 'none'})") if info is not None: info.update(n) return s, src out, have = [], 0 for k in range(STEPS): t = start + k * STEP_S v = None for back in (86400, 2 * 86400): # the same quarter hour yesterday (or the day before) v = history.mean(name, t - back) if history else None if v is not None: break have += v is not None out.append(v if v is not None else (now_value if now_value is not None else default)) 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 []) if learnt is not None: # the forecast's share per step (the presence now for the first hour): the comfort band's # weight (comfort.presence_weight, G5); taken out by model_state vals = got[0] src["_share"] = [None if (k < 4 and present is not None) or k >= len(vals) else min(1.0, max(0.0, float(vals[k]))) for k in range(STEPS)] 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).""" v = str(v) if len(v) in (5, 8) and v[2] == ":": return v[:5] try: d = datetime.fromisoformat(v.replace("Z", "+00:00")) except ValueError: return None return d.strftime("%H:%M") def device_state(c, col: Collector, now: float) -> dict: """What the optimiser needs to know about a control now.""" e = c.entities st = {} if c.kind == "battery": # the state of charge from its sensor only (no estimate: docs/parameters.md U2) st["soc_pct"] = col.value(e.get("soc", "")) st["charge_from_grid"] = col.state(e.get("charge_from_grid", "")) == "on" if hasattr(c, "reported"): c.reported = battery_reported(c, col) elif c.kind in ("heating", "cooling"): t = col.value(e.get("temp", "")) if t is None and e.get("climate"): t = number(col.attr(e["climate"], "current_temperature")) st["temp_c"] = t if e.get("climate"): st["target_c"] = number(col.attr(e["climate"], "temperature")) st["hvac"] = col.state(e["climate"]) else: st["on"] = col.state(e.get("switch", "")) == "on" if c.kind == "heating" and e.get("source"): # a hybrid's source now, in the plan's words (heat_pump | boiler) opts = {str(v): k for k, v in (c.p("source_options") or {}).items()} st["source"] = opts.get(str(col.state(e["source"]))) if c.kind == "heating" and e.get("efficiency") and hasattr(c, "reported"): c.reported = {"efficiency_pct": col.value(e["efficiency"])} elif c.kind == "ev": conn = e.get("connected") st["connected"] = col.state(conn) == "on" if conn else True st["on"] = col.state(e.get("switch", "")) == "on" st["current_a"] = col.value(e.get("current", "")) st["soc_pct"] = col.value(e.get("soc", "")) need = col.value(e.get("energy_needed", "")) if need is not None: unit = col.attr(e["energy_needed"], "unit_of_measurement") st["need_wh"] = need * 1000.0 if unit == "kWh" else need dep = col.state(e.get("departure", "")) if e.get("departure") else None if dep: st["departure"] = _hhmm(dep, col.attr(e["departure"], "device_class")) 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).""" v = col.value(eid) if eid else None if v is None: return None f = units.get(col.attr(eid, "unit_of_measurement")) return v * f if f is not None else None def battery_reported(c, col: Collector) -> dict: """The battery's own ratings where its device reports them (the control's capacity, rated_power and efficiency entities): capacity_wh, rated_power_w, efficiency_pct (round trip); absent where it does not.""" e, out = c.entities, {} cap = _scaled(col, e.get("capacity", ""), {"kWh": 1000.0, "Wh": 1.0}) pw = _scaled(col, e.get("rated_power", ""), {"kW": 1000.0, "W": 1.0}) eff = _scaled(col, e.get("efficiency", ""), {"%": 1.0}) 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 def battery_refusal(c, st: dict) -> dict | None: """Why a battery is not planned (docs/parameters.md U2), or None: its capacity, power or efficiency unknown (the mapping, the device and its owner's ratings have none), or no state of charge from its sensor. {"why": the reasons, "where": where to enter what is missing, "missing": [...]}.""" from .controls import BATTERY_RATINGS _, missing, _ = c.battery_facts() why = [f"battery {m} unknown" for m in missing] if st.get("soc_pct") is None: why.append("SoC unknown (no state-of-charge sensor)" if not c.entities.get("soc") else "SoC unknown (the state-of-charge sensor has no value)") if not why: return None where = "" if missing: labels = ", ".join(BATTERY_RATINGS[m][1] for m in missing) params = ", ".join(BATTERY_RATINGS[m][2] for m in missing) dev = getattr(c, "rated_device", "") or "" where = (f"on the panel: Devices, {dev}, Ratings ({labels})" if dev else f"on the panel: Devices, the battery's device, Ratings ({labels}); or in the mapping's params ({params})") if st.get("soc_pct") is None: where = (where + "; " if where else "") + "map the battery's state-of-charge sensor (soc)" return {"why": "; ".join(why), "where": where, "missing": missing + (["soc"] if st.get("soc_pct") is None else [])} # The owner's battery algorithm on the box (2026-11-12; docs/methods.md A2.3a, D17): the Parameters page's rows for a # home's (a house's, a flat's) own battery, resolved for the site and sent in its tariff bundle's params (fleet # heatprice.go boxParamKeys). battery.pv_share_pct is not one: it caps a building battery's storing of PV its flats # could use; a household's own PV kept for its own later use is the plan's own business. BATTERY_WEAR_KEY = "battery.wear_ct" BATTERY_RESERVE_KEY = "battery.plan_reserve_pct" BATTERY_TOP_KEY = "battery.plan_max_soc_pct" BATTERY_RATIO_KEY = "battery.discharge_ratio_pct" def battery_rows(params: dict, fsrc: dict, box_params: dict | None, priced: bool) -> dict: """The rows a battery is planned with (the owner's rule: no number stands in for a missing one): its wear (unless the device has its own wear_ct), the plan's reserve and top, and the discharge power as battery.discharge_ratio_pct of the one rated power where its facts give only one (the device's rated power or the owner's battery kW: the mapping's max_discharge_w is its own). With a tariff, a row missing from the bundle takes its suggested value (battery_core.SUGGESTED_ROWS) and {"gap": {why, where, missing, fallback}} names it (the owner, 2026-11-12); without one (nothing priced) the battery's own window and power, noted. Else {"params": what the plan uses, "src": per fact where it came from, "notes": [...]}. The shared rules (battery_core.discharge_kw, window: the building's own copy) make the numbers.""" from . import battery_core bp = box_params or {} one_power = fsrc.get("max_discharge_w") != "mapping" need = [BATTERY_RESERVE_KEY, BATTERY_TOP_KEY] + ([BATTERY_WEAR_KEY] if number(params.get("wear_ct")) is None else []) \ + ([BATTERY_RATIO_KEY] if one_power else []) vals = {k: number(bp.get(k)) for k in need} missing = [k for k in need if vals[k] is None] out, src, notes, gap = {}, {}, [], None if missing and priced: # the owner (2026-11-12): fall back to the suggested values, with an alarm naming the rows gap = battery_core.suggested_gap(missing) for k in missing: vals[k] = battery_core.SUGGESTED_ROWS[k] if BATTERY_WEAR_KEY in missing: out["wear_ct"], src["wear_ct"] = vals[BATTERY_WEAR_KEY], "suggested" missing = [] if missing: notes.append("battery: " + ", ".join(missing) + " not on the box (no tariff): its own window and power") ratio = vals.get(BATTERY_RATIO_KEY) if one_power and ratio is not None and number(params.get("max_charge_w")): ch_kw = float(params["max_charge_w"]) / 1000.0 out["max_discharge_w"] = round(battery_core.discharge_kw(ch_kw, None, ratio) * 1000.0, 1) src["max_discharge_w"] = "ratio" for key, name in ((BATTERY_RESERVE_KEY, "plan_reserve_pct"), (BATTERY_TOP_KEY, "plan_max_soc_pct")): if vals.get(key) is not None: out[name], src[name] = vals[key], ("suggested" if gap and key in gap["missing"] else "parameter") if gap and BATTERY_RATIO_KEY in gap["missing"] and "max_discharge_w" in src: src["max_discharge_w"] = "suggested" return {"params": out, "src": src, "notes": notes, **({"gap": gap} if gap else {})} HYBRID_SWITCH_KEY = "heat.hybrid_switch_eur" # the Parameters page's (via the tariff bundle) def heating_refusal(c, params: dict, price_gas: list, price_heat: list, prices_status: str, 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, hybrid) or heat price (district) for now, a hybrid without an electricity price to compare with. {"why", "where", "missing"}.""" from .controls import HEAT_RATINGS src = str(params.get("heat_source") or "electric") if src == "electric": return None _, missing, _ = c.heat_facts() why = [f"{HEAT_RATINGS[m][1].split(',')[0].lower()} unknown" for m in missing] where = [] if src in ("heat_pump", "hybrid") and "cop" not in (c.params or {}) and not (c.params or {}).get("cop_curve"): # a heat pump's COP is the device's (its datasheet): no default stands in why.append("heat pump COP unknown") where.append("the mapping's params: cop_curve (the datasheet's COP by outside temperature) or cop") missing = missing + ["cop"] if src == "hybrid" and (box_params or {}).get(HYBRID_SWITCH_KEY) is None: why.append(f"parameter {HYBRID_SWITCH_KEY} not received") where.append("the admin Parameters page (Gas and heat); it reaches the box with its tariff") missing = missing + [HYBRID_SWITCH_KEY] rated = [m for m in missing if m in HEAT_RATINGS] if rated: labels = ", ".join(HEAT_RATINGS[m][1] for m in rated) 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 "")) 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"] if src == "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)") missing = missing + ["heat_price"] if src == "hybrid" and prices_status == "none": why.append("no electricity price to compare the heat pump with") where.append("the site's electricity tariff") missing = missing + ["electricity_price"] if not why: return None 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] # hot water as a reserve (hotwater.py, G7): the floor per step (the draw temperature where a draw is # expected, else the idle floor; a Großanlage the law's at every step), the heat pump's COP by the tank's # temperature from . import hotwater hw, hw_missing = hotwater.rows(box_params) params["hp_cop_drop_pct_per_k"] = hw["dhw.hp_cop_drop_pct_per_k"] params["hp_cop_ref_c"] = hw["dhw.hp_cop_ref_c"] if (c.params or {}).get("cop_tank_curve"): params["cop_tank_curve"] = c.params["cop_tank_curve"] floor_c = hotwater.floors(draw, float(facts["min_temp_c"]), hw["dhw.idle_min_temp_c"], facts.get("law_floor_c"), hw) src = dict(fsrc, draw=dsrc, floor="the law's (DVGW W 551)" if facts.get("law_floor_c") is not None else f"{float(facts['min_temp_c']):g} °C at draws, {min(hw['dhw.idle_min_temp_c'], float(facts['min_temp_c'])):g} °C between") 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, "floor_c": floor_c, **({"hw_missing": hw_missing} if hw_missing else {})} 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", "combi") 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 def cover_positions(col: Collector, ent: str) -> bool: """Can the cover be set to a position (else only opened and closed)? True while HA has not said (the guard and the executor check again).""" f = number(col.attr(ent, "supported_features")) return True if f is None else bool(int(f) & SET_POSITION) def cover_position(col: Collector, ent: str) -> float | None: """A cover's position (0 closed, 100 open): its current_position, else from its state (open 100, closed 0) for one that has no position.""" v = number(col.attr(ent, "current_position")) if v is not None: return v return {"open": 100.0, "closed": 0.0}.get(col.state(ent)) 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=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, presence: list | None = None, storefit=None, comfort_ctx: dict | None = 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; 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) # gas and heat per step (fleet heatprice.go): what a boiler's and district heat cost 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 # the plan, the building's shift and the grid order's base (optimizer) # do not count them twice. The model's base_load_w is that; its load_w # (load.power as metered) is too only where no planned device has a meter # inside it, else the history of the base load stands in. ctl = getattr(inputs, "controlled_power", None) or [] # the box's own models where the cloud's forecast no longer covers a step # (localml.py), on HA's weather forecast where the mapping has one 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) occ_share = occ_src.pop("_share", None) 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 intraday = {} trainer = getattr(bundles, "own", None) if trainer is not None: # the intraday correction (fcmodels.intraday, methods.md B10): the last # 3 hours' error of what was planned on against the meter, carried into # the next hours and fading (half-life 2 h); load in W, PV as a ratio for key, series in (("load", "plan"), ("pv", "pv")): base = load if key == "load" else pv c = cands.setdefault(key, {}) c["used"] = list(base) try: new, e = trainer.correct(series, start, base) except Exception as ex: # never stops a plan log.warning("intraday correction %s: %s", key, ex) continue c["corrected"] = list(new) intraday[key] = round(float(e), 3) if key == "load": load = new else: pv = new if trainer is not None: # the house as metered (devices in), for the member's net draw the box # publishes upward where it does not act itself (controller.forecasts_up) if ctl: nl: dict = {} got = _series("load_w", start, bundles, history, tz, None, 500.0, ("load_w",), box, nl) net_load = got[0] if got[1].startswith("model") else None else: net_load = load # the outdoor temperature (methods.md A1.4): the mapping's weather entity's forecast, else # fleet's forecast for the site's own cell (the tariff bundle's "weather", DWD MOSMIX), each # moved by an outdoor sensor where there is one; else the sensor's (or the entity's) value # now, held; else none: no number stands in (rooms are not planned, a quiet note) fwx = bundles.weather_forecast(now) if hasattr(bundles, "weather_forecast") else [] t_out, t_src = outdoor_temperature(start, col, inputs, weather_forecast, fwx) if t_out is None: notes.append("no outdoor temperature (no weather entity, no forecast from the platform for the site's " "location, no outdoor sensor): rooms are not planned, they follow their schedule") peak = max(pv) if pv else 0.0 if peak > 100: sun = [max(0.0, p / peak) for p in pv] else: # 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 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 cop_src, band_src, fallback, zone_src = {}, {}, [], {} one_room = sum(c.kind in ("heating", "cooling") for c in controls) == 1 for c in controls: if c.kind == "heat_pump_sg": continue # its building's schedule sets it (sgready.py), not this plan if hasattr(c, "learn_range"): c.learn_range(col) # a climate's own min_temp..max_temp bounds = {} for q in _quantities(c): b = c.bounds(q, (extra_limits or {}).get(c.id)) bounds[q] = [b.lo, b.hi, b.lo_by, b.hi_by] params = {k: c.p(k) for k in _param_names(c)} if c.kind == "ev": # the count from the best evidence (evphases.py); None: the plan assumes 1 info = (ev_phases or {}).get(c.id) or \ ({"phases": float(c.params["phases"]), "source": "mapping"} if c.params.get("phases") else {"phases": None, "source": "assumed"}) params["phases"] = info["phases"] phases_src[c.id] = {"phases": info["phases"], "source": info["source"]} st = device_state(c, col, now) if c.kind == "cover": # its window's facts (G3 in the plan: the installer's, the device's, the owner's; never assumed) from .controls import FACTS params.update({k: float(c.params[k]) for k in FACTS["cover"] if number(c.params.get(k)) is not None}) 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") if k in c.params}) source = "electric" if c.kind == "cooling" else str(params.get("heat_source") or "electric") if c.kind == "heating" and source == "electric" and "cop" not in params: params["cop"] = 1.0 # a resistive heater: all its electricity becomes heat (physics) src, power = _room_rc(c, params, bundles, one_room, now) rooms_src[c.id] = src if params.get("_zone_note"): notes.append(f"{c.id}: {params.pop('_zone_note')}: its own R and C instead") if params.get("zone"): # the flat's mass now: observed on the room's history (B17.5), else the steady state past = start - 96 * STEP_S hist = history if hasattr(history, "series") else None m0, msrc = mass_start(params, hist.series(f"room:{c.id}", past, 96) if hist else [], hist.series("t_out", past, 96) if hist else [], st.get("temp_c") if st.get("temp_c") is not None else None) if m0 is None and t_out is not None and st.get("temp_c") is not None: m0, msrc = mass_start(params, [], [t_out[0]], st["temp_c"]) if m0 is not None: params["zone"]["theta_m0"], params["zone"]["theta_m0_src"] = round(m0, 3), msrc zone_src[c.id] = {"share": params["zone"]["share"], "share_from": params["zone"]["share_src"], "mass_now_c": params["zone"].get("theta_m0"), "mass_from": msrc or "none"} zone_eer = None if c.kind == "cooling" and params.get("zone") and params["zone"].get("cool_eer") and power != "electric" \ and "cop" not in c.params and not c.params.get("cop_curve"): # an A/C without its datasheet: the flat model's fitted EER (B17, G4; the device's curve wins) params["cop"] = zone_eer = float(params["zone"]["cool_eer"]) # an electric fit runs in electric equivalents: the COP cancels (_room_rc) cop_src[c.id] = ("mapping" if "cop" in c.params or c.params.get("cop_curve") else "zone fit" if zone_eer else "electric heater" if c.kind == "heating" and source == "electric" else "electric fit" if power == "electric" and "cop" in params else "none") # comfort/setback/setup: the mapping's, else the box's copy of the Parameters rows # comfort.heating_setpoints / comfort.cooling_setpoints (docs/parameters.md C7) band_src[c.id] = "mapping" if any(k in c.params for k in ("comfort_c", "setback_c", "setup_c")) else "defaults" # what is missing for the room and for its heat source (methods E6) nos = [room_refusal(c, st, src, power, source, cop_known=zone_eer is not None)] if c.kind == "heating": nos.append(heating_refusal(c, params, price_gas, price_heat, getattr(prices, "status", "tariff"), 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 # installer's preferences: optimizer.fallback_entries) no = {"why": "; ".join(n["why"] for n in nos if n.get("why")), "where": "; ".join(n["where"] for n in nos if n.get("where")), "missing": [m for n in nos for m in n.get("missing") or []]} refused[c.id] = dict(no, kind=c.kind, name=c.label() if hasattr(c, "label") else c.id) fallback.append({"id": c.id, "kind": c.kind, "params": params, "state": st, "bounds": bounds, "channels": sorted(c.writable())}) continue if t_out is None: # no outdoor temperature: the room model has no outside to lose heat to. Not a # refusal (nothing to enter in the mapping): its fallback schedule, the plan's note fallback.append({"id": c.id, "kind": c.kind, "params": params, "state": st, "bounds": bounds, "channels": sorted(c.writable())}) continue if c.kind == "heating" and hasattr(c, "heat_facts"): facts, _, fsrc = c.heat_facts() params.update(facts) if facts: heat_src[c.id] = fsrc if c.kind == "battery": no = battery_refusal(c, st) if no is not None: refused[c.id] = dict(no, kind="battery", name=c.label() if hasattr(c, "label") else c.id) continue facts, _, fsrc = c.battery_facts() params.update(facts) # the owner's battery algorithm (A2.3a): the reserve, the top, the discharge power, the wear's row (the # mapping's own wear_ct first: the device's ageing per kWh where its owner knows it) own_wear = number((getattr(c, "params", None) or {}).get("wear_ct")) if own_wear is not None and own_wear >= 0: params["wear_ct"] = own_wear rows = battery_rows(params, fsrc, box_params, prices.status != "none") if "gap" in rows: # planned with the suggested values: reported like a refusal, marked fallback refused[c.id] = dict(rows["gap"], kind="battery", name=c.label() if hasattr(c, "label") else c.id) params.update(rows["params"]) notes += rows["notes"] battery_src[c.id] = dict(fsrc, **rows["src"]) # 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 if t_out is None and params.get("cop_curve") and str(params.get("heater")) == "heat_pump": # its COP by the outside temperature: none known. The device's one COP where it # has one, else not planned (its own thermostat) if params.get("cop") is None: notes.append(f"{c.id}: hot-water tank not planned: its heat pump's COP follows the outdoor " "temperature and there is none; its own thermostat meanwhile") continue params["cop_curve"] = [] got["src"] = dict(got["src"], cop="its one COP (no outdoor temperature for the curve)") tank_src[c.id] = got["src"] extra = {"draw_w": got["draw_w"], "floor_c": got["floor_c"]} if got.get("hw_missing") and box_params: from . import hotwater refused["hot_water"] = hotwater.gap(got["hw_missing"]) 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()), **extra}) comfort_info, presence_w = comfort_bands(devices, controls, start, now, tz, t_out, history, box_params, occupied, occ_share, band_src, refused, notes, comfort_ctx or {}) # a combi boiler's comfort mode (hotwater.combi_comfort, G7): off at night and while nobody is home for d in devices: if d["kind"] == "heating" and "dhw_comfort" in d["channels"] and \ str(d["params"].get("combi") or "").lower() in ("true", "yes", "1"): from . import comfort, hotwater sleep = comfort.rows(box_params)[0]["comfort.sleep"] d["dhw_comfort"] = hotwater.combi_comfort(start, tz, STEPS, presence_w, sleep) clouds = _hourly(weather_forecast or [], "cloud_coverage", start, STEPS) sky_src = "weather forecast" if clouds is None and fwx: clouds, sky_src = _hourly(fwx, "cloud_coverage", start, STEPS), "fleet forecast" 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, "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), "priced_steps": getattr(prices, "priced_steps", STEPS)}, "load_w": load, "pv_w": pv, "t_out": t_out, "sun": sun, "occupied": occupied, "sky": sky, # the probability someone is home per step (comfort.presence_weight: the band's weight, the zone's gain) "presence_w": presence_w, "ghi_w_m2": ghi, "location": location or {}, "sources": {"load": load_src, "pv": pv_src, "outdoor": t_src, "model": bundles.model_id(), "sky": sky_src if clouds else "clear", "rooms": rooms_src, "ghi": ghi_src, "rooms_cop": cop_src, "rooms_band": band_src, **({"rooms_zone": zone_src} if zone_src else {}), **({"comfort": comfort_info} if comfort_info else {}), "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}}, "devices": devices, "building": building or {}, "grid_order": grid_order or {}, # controls not planned and why (docs/parameters.md U2: a battery without its facts; # a room without its R/C fit, power, COP or temperature) "refused": refused, # the rooms among them: their limits and params for a fallback schedule # (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 [], # 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: out["_cands"] = cands # taken out by the controller before the plan out["_net_load"] = net_load # a shade's moves by rules on the sun and its room (shades.py); the # optimiser takes them as they are from . import shades for d in devices: if d["kind"] == "cover": # with its window's facts the plan places it (G3); else A7's rules on the sun wp = shades.window_plan(d, out, (shade_ctx or {}).get(d["id"])) if wp is not None: d["window"] = wp else: d["schedule"] = shades.schedule(d, out, (shade_ctx or {}).get(d["id"])) return out def irradiance(start: int, location: dict | None, sky: list[float], pv_sun: list[float] | None) -> tuple[list[float], str]: """Global irradiance per step (W/m²) for a room's fitted sun (solar_m2): Haurwitz's clear sky, 1098 cos z exp(-0.057 / cos z), at the step's middle where the site's location is known, times the sky (1 - the forecast's cloud cover); else the PV forecast scaled to its peak (pv_sun, A1.2) times 1000 W/m², a rough stand-in; else none (the sun's elevation now, held, would shine all night).""" from .shades import sun_position lat, lon = (location or {}).get("latitude"), (location or {}).get("longitude") if lat is None or lon is None: if pv_sun is None: return [0.0] * STEPS, "none (no location, no PV forecast)" return [1000.0 * max(0.0, x) for x in pv_sun], "PV forecast" out = [] for k in range(STEPS): elev, _ = sun_position(start + k * STEP_S + STEP_S / 2, float(lat), float(lon)) cz = math.sin(math.radians(elev)) clear = 1098.0 * cz * math.exp(-0.057 / cz) if cz > 0.01 else 0.0 out.append(round(clear * max(0.0, min(1.0, sky[k] if k < len(sky) else 1.0)), 1)) return out, "clear sky x the sky" def _room_rc(c, params: dict, bundles, only_one: bool, now: float) -> str: """A heating or cooling control's R and C: the mapping's own (both), else the model's room (the box's fit in force, else the cloud's: bundles.room_rc), else none (never the built-in defaults: the room is not planned, room_refusal). A room fitted against the electric power: C * cop and R / cop (the same RC; the optimiser's heat is cop * P): the COP cancels, so without the mapping's cop the model runs in electric equivalents (cop 1 by construction, not a default). Into params; (where they came from: mapping | box model | model | partial (the mapping sets one of the two) | none, the power the fit is against: thermal | electric | "").""" has = [k for k in ("r_k_per_kw", "c_kwh_per_k") if k in c.params] if len(has) == 2: return "mapping", "thermal" if has: return "partial", "" # the flat's 2R2C (air and mass, B17) where the cloud's daily check passed, scaled to the room # (G2 in the plan, backlog 473): pre-heating and pre-cooling are stored in the mass zget = getattr(bundles, "zone_rc", None) z, zwhy = zget(c.id, str(c.params.get("area") or ""), only_one, now) if zget else (None, "") if z is not None: return _zone_params(c, params, z), ("electric" if z["power"] == "electric" else "thermal") if zwhy: params["_zone_note"] = zwhy # the box's own fit where it is in force (boxtrain.py), else the cloud's own = getattr(bundles, "own", None) rc = own.room_rc(c.id, str(c.params.get("area") or ""), only_one) if own is not None else None src = "box model" if rc is not None else "model" if rc is None: get = getattr(bundles, "room_rc", None) rc = get(c.id, str(c.params.get("area") or ""), only_one, now) if get else None if rc is None: return "none", "" r, cap = rc["r_k_per_kw"], rc["c_kwh_per_k"] gain, solar = rc.get("gain_w") or 0.0, rc.get("solar_m2") or 0.0 electric = str(params.get("heat_source") or "electric") in ("electric", "heat_pump") if rc.get("power") == "electric" and electric: # fitted in electric equivalents: the heat is cop times (like C); without # the mapping's COP (a cooler, or a heat pump with its curve alone) the # model stays in electric equivalents (cop 1) cop = number(params.get("cop")) or 1.0 if c.kind == "cooling" or "cop" in params: params["cop"] = cop r, cap = r / cop, cap * cop gain = [g * cop for g in gain] if isinstance(gain, list) else gain * cop solar *= cop params["r_k_per_kw"], params["c_kwh_per_k"] = r, cap # the fit's internal gain and sun (Finding B6-a): R and C were fitted # with them; the mapping's own, where it sets them, win if "internal_gain_w" not in c.params: params["internal_gain_w"] = gain if "solar_m2" not in c.params: params["solar_m2"] = solar return src, ("electric" if rc.get("power") == "electric" else "thermal") def _zone_params(c, params: dict, z: dict) -> str: """The room as its share of the flat's 2R2C (bundles.zone_rc): the resistances divided by the share, the capacities and gains times it (a room that is that share of the flat, with the flat's time constants: methods.md G2 in the plan). Fitted against the electric power: R / cop, C x cop as a room's (_room_rc). Into params["zone"] {r_i, r_e, c_a, c_m, gain_w, solar_m2, el_gain_share, occ_gain_w, share, ...}; params' R and C the one-node equivalent (R_i + R_e, C_eff: the shift envelope and the heating levers, which run one node). The mapping's own gains win.""" sh = z["share"] k = 1.0 electric = str(params.get("heat_source") or "electric") in ("electric", "heat_pump") if z["power"] == "electric" and electric: cop = number(params.get("cop")) or 1.0 if c.kind == "cooling" or "cop" in params: params["cop"] = cop k = cop ri, re_ = z["r_i"] / sh / k, z["r_e"] / sh / k ca, cm = z["c_a"] * sh * k, z["c_m"] * sh * k zone = {"r_i": ri, "r_e": re_, "c_a": ca, "c_m": cm, "share": sh, "share_src": z.get("share_src", ""), "power": z["power"], "gain_w": z["gain_w"] * sh * k, "solar_m2": z["solar_m2"] * sh * k, "solar_kind": z.get("solar_kind", "ghi"), "el_gain_share": z["el_gain_share"] * sh * k, "occ_gain_w": z["occ_gain_w"] * sh * k, "cool_eer": z.get("cool_eer")} params["zone"] = zone params["r_k_per_kw"] = ri + re_ params["c_kwh_per_k"] = ca + cm * re_ / (ri + re_) if "internal_gain_w" not in c.params: params["internal_gain_w"] = zone["gain_w"] if "solar_m2" not in c.params: params["solar_m2"] = zone["solar_m2"] return "zone 2r2c" def comfort_bands(devices: list, controls, start: int, now: float, tz: str, t_out: list | None, history, box_params: dict, occupied: list, occ_share: list | None, band_src: dict, refused: dict, notes: list, ctx: dict) -> tuple[dict | None, list[float]]: """Each planned room's comfort band per step (comfort.py, methods.md G5 in the plan) into d["band"]: EN 16798-1's band for the household's choice (ctx "mode": comfort | balanced | saving, the preferences' "comfort"; else the Parameters page's default), on the running mean outdoor temperature (the box's history "t_out" and the forecast), the household's tolerance from its overrides (ctx "tolerance"), weighted by the probability someone is home. The owner's schedule still wins (preferences.apply; the optimizer takes the band only without one). Rows missing: their suggested values and refused["comfort_band"] names them. (the plan's sources.comfort, the presence weight per step).""" from . import comfort raw = (box_params or {}).get(OCC_SHARE_KEY) weights = comfort.presence_weight(occupied, occ_share, number(raw) if not isinstance(raw, bool) else None) rooms = [d for d in devices if d["kind"] in ("heating", "cooling")] if not rooms: return None, weights r, missing = comfort.rows(box_params) if missing and box_params: # the bundle carries the Parameters but not these: the alarm (the owner's rule, as the battery's rows) refused["comfort_band"] = comfort.gap(missing) elif missing: notes.append("comfort band: no Parameters on the box yet (no tariff bundle): EN 16798-1's suggested values") mode = ctx.get("mode") if ctx.get("mode") in comfort.MODES else r["comfort.default_mode"] past_n = 7 * 96 past = history.series("t_out", start - past_n * STEP_S, past_n) if hasattr(history, "series") else [] days = comfort.daily_means(start, tz, past, start - past_n * STEP_S, t_out) zone = ZoneInfo(tz or "UTC") horizon_days = sorted({datetime.fromtimestamp(start + k * STEP_S, timezone.utc).astimezone(zone).date().isoformat() for k in range(STEPS + 1)}) alpha = float(r["comfort.running_mean_alpha"]) rm = {d: comfort.running_mean(days, d, alpha) for d in horizon_days} if any(v is None for v in rm.values()): notes.append("comfort band: no running mean outdoor temperature for " + ", ".join(d for d, v in rm.items() if v is None) + " (under a day of the box's outdoor history): EN 16798-1's fixed values there") cooled = any(getattr(c, "kind", "") == "cooling" for c in controls) tol = ctx.get("tolerance") info = {"mode": mode, "category": r["comfort.mode_categories"].get(mode), "rows": "suggested" if missing else "parameters", "running_mean_c": {d: (round(v, 2) if v is not None else None) for d, v in rm.items()}, "history_days": sum(1 for d in days if d < horizon_days[0]), "tolerance": {}} for d in rooms: kind = d["kind"] p = d["params"] back = p.get("setup_c" if kind == "cooling" else "setback_c") if back is None: continue shift, n = tol.shift(d["id"], kind, now, r) if tol is not None else (0.0, 0) d["band"] = comfort.room_band(r, kind, mode, start, tz, STEPS, weights, rm, float(back), cooled, shift) band_src[d["id"]] = f"en16798 {d['band']['category']}" if n: info["tolerance"][d["id"]] = {"shift_k": round(shift, 2), "overrides": n} return info, weights def mass_start(params: dict, temps: list, t_out: list, now_c: float | None) -> tuple[float | None, str]: """The zone's mass temperature now (methods.md B17.5, the fit's observer): the mass equation driven by the room's measured air over the last 24 h (temps, t_out: oldest first, None where missing: the last value held), from the steady state at the first value; without a day of history the steady state now (R_e theta_a + R_i T_out) / (R_i + R_e).""" z = params.get("zone") if not z or now_c is None: return None, "" ri, re_, cm = z["r_i"], z["r_e"], z["c_m"] pairs = [(a, o) for a, o in zip(temps, t_out)] have = [p for p in pairs if p[0] is not None and p[1] is not None] if len(have) < 48: if not t_out or t_out[-1] is None: return None, "" return (re_ * now_c + ri * t_out[-1]) / (ri + re_), "steady state now (under 12 h of the room's history)" a = math.exp(-STEP_S / 3600.0 * (1.0 / ri + 1.0 / re_) / cm) ta, to = have[0] m = (re_ * ta + ri * to) / (ri + re_) for x, y in pairs: ta = x if x is not None else ta to = y if y is not None else to m = a * m + (1 - a) * (re_ * ta + ri * to) / (ri + re_) return m, f"observed over {len(have) // 4} h of the room's history" def room_refusal(c, st: dict, rc: str, power: str, source: str = "electric", cop_known: bool = False) -> dict | None: """Why a heating or cooling room is not planned (docs/parameters.md E3: R/C measured, power and COP the device's), or None: no R/C (no fit, the mapping sets neither, or only one of the two), the heater's or cooler's electric power unknown (max_power_w), the COP unknown where the model needs it (the mapping's R/C or a fit against the heat; an electric fit needs none), or no room temperature now. {"why", "where", "missing": [...]} (the plan adds "fallback": schedule | own | none). The room keeps its limits, and its thermostat follows the owner's or installer's schedule (preferences) meanwhile, else its own setpoint (optimizer.fallback_entries).""" why, where, missing = [], [], [] if rc == "partial": have = "r_k_per_kw" if "r_k_per_kw" in c.params else "c_kwh_per_k" lack = "c_kwh_per_k" if have == "r_k_per_kw" else "r_k_per_kw" why.append(f"the mapping sets {have} but not {lack}") where.append("the mapping's params: both r_k_per_kw and c_kwh_per_k, or neither (the room's fit is used)") missing.append(lack) elif rc == "none": why.append("no R/C fit for this room yet (no room model)") where.append("nothing to do: the box fits the room from its measured temperature and heating (nightly, once " "there are a few days of history); or the installer enters r_k_per_kw and c_kwh_per_k in the " "mapping's params") missing += ["r_k_per_kw", "c_kwh_per_k"] # the electric power: a cooler's, and a heater's that runs on electricity (a boiler's or a heat # station's heat is its max_heat_w: heating_refusal) if "max_power_w" not in c.params and (c.kind == "cooling" or source in ("electric", "heat_pump", "hybrid")): why.append(f"the {'heating' if c.kind == 'heating' else 'cooling'}'s electric power unknown") where.append("the mapping's params (max_power_w, W)") missing.append("max_power_w") # a cooler's COP (a heater's: electric 1, a heat pump's or hybrid's: heating_refusal) if c.kind == "cooling" and rc in ("mapping", "model", "box model", "zone 2r2c") and power != "electric" \ and "cop" not in c.params and not cop_known: why.append("COP unknown (heat per kWh of electricity)") where.append("the mapping's params (cop)") missing.append("cop") if st.get("temp_c") is None: why.append("room temperature unknown" + (" (no temperature sensor)" if not c.entities.get("temp") and not c.entities.get("climate") else " (no value now)")) where.append("map the room's temperature sensor (temp), or a thermostat that reports its temperature") missing.append("temp") if not why: return None return {"why": "; ".join(why), "where": "; ".join(where), "missing": missing} def _quantities(c) -> list[str]: return {"battery": ["soc_pct", "power_w"], "heating": ["temp_c"], "cooling": ["temp_c"], "ev": ["current_a"], "cover": ["position_pct"], "dhw_tank": ["temp_c"]}.get(c.kind, []) def _param_names(c) -> list[str]: from .controls import PARAMS return list(PARAMS[c.kind])