1555 lines
85 KiB
Python
1555 lines
85 KiB
Python
# 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:<id>",
|
|
°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.<r>.occupied) or a person's home/away
|
|
(person.<slug>.home)."""
|
|
p = str(asset).split(".")
|
|
return len(p) == 3 and ((p[0] == "room" and p[2] == "occupied") or (p[0] == "person" and p[2] == "home"))
|
|
|
|
|
|
def presence_now(col: Collector, entities) -> bool | None:
|
|
"""Someone at home now: any presence source on or home (HA's person
|
|
and device_tracker: state "home"); None while none has a value."""
|
|
vals = [col.state(p) for p in entities or []]
|
|
known = [v for v in vals if v not in NO_VALUE]
|
|
return any(v in PRESENT for v in known) if known else None
|
|
|
|
|
|
def occupancy(start: int, tz: str, col: Collector, presence, bundles, history, box, box_params: dict,
|
|
hours=OCCUPIED_HOURS, fc_src: dict | None = None) -> tuple[list[int], dict, list[str]]:
|
|
"""Per step occupied (1) or not (methods.md A1, B16): the presence now
|
|
for the first hour (4 steps) where a presence source has a value; then
|
|
the learnt weekly presence, the occupancy forecast through the load's
|
|
sources (_model_series: the box's own model in force, the cloud's
|
|
series, the cloud's model on the box, the hour-of-week profile), a step
|
|
occupied where the forecast share of the presence sources seeing
|
|
someone is at least the Parameters page's comfort.occupied_min_share;
|
|
without a forecast (no presence source, or none learnt yet), without
|
|
the parameter or with a forecast never occupied over the horizon, the
|
|
fixed hours (06:00-22:00 local), and a quiet note
|
|
why (no alarm: nothing for anyone to enter, except the parameter).
|
|
The owner's schedule still wins (preferences.apply). (occupied,
|
|
sources.occupancy: steps per source and why, notes)."""
|
|
zone = ZoneInfo(tz or "UTC")
|
|
present = presence_now(col, presence)
|
|
labels: list = []
|
|
got = _model_series("occupancy", start, bundles, history, tz, box, labels) if bundles else None
|
|
raw = (box_params or {}).get(OCC_SHARE_KEY)
|
|
share = number(raw) if not isinstance(raw, bool) else None
|
|
share = share if share is not None and 0.0 <= share <= 1.0 else None
|
|
notes, src = [], {"presence_now": 0, "fixed_hours": 0}
|
|
learnt = None
|
|
if got is not None:
|
|
vals, info = got
|
|
if fc_src is not None:
|
|
fc_src["occupancy"] = info # the forecast's steps per source, its live error (_cands)
|
|
if share is None:
|
|
src["why"] = "no_parameter"
|
|
notes.append(f"occupancy: the learnt presence is not used, parameter {OCC_SHARE_KEY} "
|
|
+ ("not received" if raw is None else f"not a share 0..1 ({raw!r})")
|
|
+ " (the admin Parameters page; it reaches the box with its tariff): "
|
|
+ f"{hours[0]:02d}:00-{hours[1]:02d}:00 instead")
|
|
else:
|
|
learnt = [1 if float(v) >= share else 0 for v in vals]
|
|
src["min_share"] = share
|
|
if not any(learnt):
|
|
# never occupied over the whole horizon (a learnt profile of 0 all day): every room
|
|
# at setback for 48 h is not a plan anyone wants; the fixed hours, said quietly
|
|
learnt = None
|
|
src["why"] = "never_occupied"
|
|
notes.append(f"occupancy: the learnt presence is never occupied over the next 48 h (share "
|
|
f"{share} not reached): {hours[0]:02d}:00-{hours[1]:02d}:00 instead")
|
|
elif not presence:
|
|
src["why"] = "no_presence_source"
|
|
notes.append(f"occupancy: no presence source and no presence forecast: {hours[0]:02d}:00-{hours[1]:02d}:00 "
|
|
"(map a presence sensor or the people's home/away to learn it)")
|
|
else:
|
|
src["why"] = "no_forecast"
|
|
notes.append(f"occupancy: no presence forecast yet (learnt from the presence history): the presence now for the "
|
|
f"first hour, then {hours[0]:02d}:00-{hours[1]:02d}:00")
|
|
out = []
|
|
for k in range(STEPS):
|
|
if k < 4 and present is not None:
|
|
out.append(1 if present else 0)
|
|
src["presence_now"] += 1
|
|
elif learnt is not None:
|
|
out.append(learnt[k])
|
|
lab = labels[k] if k < len(labels) else "cloud"
|
|
src[lab] = src.get(lab, 0) + 1
|
|
else:
|
|
h = datetime.fromtimestamp(start + k * STEP_S, timezone.utc).astimezone(zone).hour
|
|
out.append(1 if hours[0] <= h < hours[1] else 0)
|
|
src["fixed_hours"] += 1
|
|
src["source"] = ("learnt" if learnt is not None else "fixed_hours")
|
|
src["presence_sources"] = len(presence or [])
|
|
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.<r>.occupied and person.<slug>.home; None: the inputs')."""
|
|
start = int(now // STEP_S * STEP_S)
|
|
zone = ZoneInfo(tz or "UTC")
|
|
prices = bundles.prices(start, STEP_S, STEPS, now)
|
|
# 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])
|