cantabile_edge, cantabile_modbus, cantabile_eebus 0.1.1289: full source

This commit is contained in:
Setti Solutions S.R.L committed 2026-11-08 16:35:35 +02:00
1 parent 165dda4479
commit 05802d6f87
57 files changed
+5928 -232

No files matched your search

+492 -38
View File
@@ -9,10 +9,14 @@ control.
None of this leaves the site; only the plan does (controller.py).
Placeholders (quality is not a goal yet):
- occupancy beyond the next hour: the presence now for one hour, then
06:00-22:00 local as "occupied" (a learned schedule comes later);
- sun: the PV forecast scaled to its peak, else the sun's elevation.
Occupancy (methods.md A1, B16): the presence now for the first hour,
then the learnt weekly presence (the occupancy forecast, a step occupied
from the Parameters page's comfort.occupied_min_share), else 06:00-22:00
local, noted (occupancy). A car's departure and energy where the car says
none: the EV session forecast (ev_session, B15).
Placeholder (quality is not a goal yet): the sun:
the PV forecast scaled to its peak, else the sun's elevation.
"""
import json
import logging
@@ -27,6 +31,9 @@ log = logging.getLogger(__name__)
STEP_S = 900
STEPS = 192 # 48 h
HISTORY_S = 8 * 86400 # a day back (the fallback) and a week back (the box's models' lag)
# a room's occupied hours (local, from..to) without the owner's schedule: its
# comfort target then, its setback/setup otherwise (preferences.builtin says so)
OCCUPIED_HOURS = (6, 22)
def number(v) -> float | None:
@@ -168,24 +175,34 @@ FC_SOURCES = {"own": "the box's own model", "cloud": "the cloud's series", "box"
"hour_of_week": "the hour-of-week profile"}
def _model_series(m, start, bundles, history, tz, box) -> tuple[list[float], dict] | None:
def _box_weather(box) -> tuple:
"""The box's weather for its models (model_state's box): HA's hourly
forecast, its weather entity, and, where the entity has one, its
wind_speed_unit (localml.ha_hours)."""
return tuple(box[:2]) + ((box[2],) if len(box) > 2 and box[2] else ())
def _model_series(m, start, bundles, history, tz, box, labels: list | None = None) -> tuple[list[float], dict] | None:
"""A model series m for the horizon, per step the best fresh source
(methods.md B10): the box's own model where it is in force and has a
value (boxtrain.py: bundles.own), else the cloud's forecast where its
series covers the step, else the cloud's model on the box (localml.py;
box: HA's weather forecast and its entity) where it has a value, else
the hour-of-week profile; how many steps each gave, the source that
gave most ("source"), and every source's values ("_cands": the live
error per source, taken out before the plan)."""
box: HA's weather forecast, its entity and its wind unit) where it has
a value, else the hour-of-week profile; how many steps each gave, the
source that gave most ("source"), and every source's values ("_cands":
the live error per source, taken out before the plan). labels (a list):
filled with each step's source (own | cloud | box | hour_of_week)."""
trainer = getattr(bundles, "own", None) if bundles is not None else None
mine = None
if trainer is not None and box is not None:
try:
mine = trainer.forecast(m, start, STEPS, box[0], box[1])
mine = trainer.forecast(m, start, STEPS, *_box_weather(box))
except Exception as e: # never stops a plan
log.warning("the box's own %s model: %s", m, e)
if not hasattr(bundles, "forecast_parts"):
s = bundles.forecast(m, start, STEP_S, STEPS, tz)
if s is not None and labels is not None:
labels[:] = ["cloud"] * len(s)
return None if s is None else (s, {})
parts = bundles.forecast_parts(m, start, STEP_S, STEPS, tz)
if parts is None:
@@ -193,6 +210,8 @@ def _model_series(m, start, bundles, history, tz, box) -> tuple[list[float], dic
if mine is None or any(v is None for v in mine[0]):
return None
vals = [float(v) for v in mine[0]]
if labels is not None:
labels[:] = ["own"] * STEPS
return vals, {"series": m, "own": STEPS, "cloud": 0, "box": 0, "hour_of_week": 0, "own_model": mine[1].get("kind"),
"source": "own", "_cands": {"own": vals}}
vals = [v for v, _ in parts]
@@ -200,20 +219,24 @@ def _model_series(m, start, bundles, history, tz, box) -> tuple[list[float], dic
cloud_series = [v if src == "series" else None for v, src in parts]
own = None
if box is not None and (trainer is not None or not all(v is not None for v in cloud_series)):
own = bundles.box_forecast(m, start, STEPS, history, box[0], box[1])
own = bundles.box_forecast(m, start, STEPS, history, *_box_weather(box))
lab = []
for k, (v, src) in enumerate(parts):
o = mine[0][k] if mine is not None else None
b = own[0][k] if own is not None else None
if o is not None:
vals[k] = o
info["own"] += 1
lab.append("own")
elif src == "series":
info["cloud"] += 1
lab.append("cloud")
elif b is not None:
vals[k] = b
info["box"] += 1
lab.append("box")
else:
info["hour_of_week"] += 1
lab.append("hour_of_week")
info[lab[-1]] += 1
if labels is not None:
labels[:] = lab
if mine is not None:
info["own_model"] = mine[1].get("kind")
if mine[1].get("weather"):
@@ -267,6 +290,163 @@ def _series(name, start, bundles, history, tz, now_value, default, model_names=N
return out, ("history" if have else ("now" if now_value is not None else "default"))
OCC_SHARE_KEY = "comfort.occupied_min_share" # the Parameters page's (via the tariff bundle)
PRESENT = ("on", "home") # a presence sensor on, a person or device_tracker home
NO_VALUE = (None, "", "unavailable", "unknown")
def presence_asset(asset: str) -> bool:
"""A mapped presence source (B16.1, building/carriers.presence_source):
a room's presence sensor (room.<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 [])
return out, src, notes
def _when_utc(ts) -> str:
return datetime.fromtimestamp(int(ts), timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
def ev_session(c, st: dict, sessions: dict | None, start: int, now: float) -> tuple[dict, str]:
"""A car's departure and energy where neither the car nor (in the
optimiser) its owner gives them (methods.md A1, B15): the EV session
forecast (bundles.ev_sessions). Plugged in: the forecast session that
covers now gives the departure (st["session"]["dep_step"]; beyond the
horizon: its end) and the kWh (need_wh) where the car reports none.
Not plugged in: the next forecast session in the horizon becomes an
expected load (st["expected"]: from_step its arrival, to_step its
departure, need_wh its kWh), which the plan sees (prices, the battery)
but never acts on: no charger command until the car is plugged in. A
forecast need is not a known one (optimizer.ev_known). Without
sessions: as before (the car's, else the mapping's need_wh and
departure). (sources.ev for the control, a note or "")."""
own_dep, own_need = st.get("departure") is not None, st.get("need_wh") is not None
src = {"departure": "car" if own_dep else "mapping", "energy": "car" if own_need else "mapping"}
if not sessions or not sessions.get("sessions"):
return src, ""
issued = _when_utc(sessions["issued"])
src["issued"] = int(sessions["issued"])
end = start + STEPS * STEP_S
def step_of(ts, up):
k = (ts - start) / STEP_S
k = math.ceil(k - 1e-9) if up else math.floor(k + 1e-9)
return int(min(STEPS, max(0, k)))
name = c.label() if hasattr(c, "label") else c.id
if st.get("connected"):
cover = next((s for s in sessions["sessions"] if s["arrive"] <= now and (s["depart"] is None or now < s["depart"])),
None)
if cover is None or (own_dep and own_need):
return src, ""
sess, used = {}, []
if not own_dep:
sess["dep_step"] = step_of(cover["depart"], False) if cover["depart"] is not None else STEPS
src["departure"] = "session forecast"
used.append("departure")
if not own_need and cover["kwh"] is not None:
sess["need_wh"] = float(cover["kwh"]) * 1000.0
src["energy"] = "session forecast"
used.append("energy")
if not used:
return src, ""
st["session"] = sess
return src, f"car {name}: {' and '.join(used)} from the session forecast (issued {issued})"
nxt = next((s for s in sessions["sessions"] if now < s["arrive"] < end), None)
if nxt is None:
return src, ""
if nxt["kwh"] is None:
return src, (f"car {name}: not plugged in; the session forecast (issued {issued}) expects it at "
f"{_when_utc(nxt['arrive'])} but has no kWh: not planned")
a = step_of(nxt["arrive"], True)
b = step_of(nxt["depart"], False) if nxt["depart"] is not None else STEPS
if b <= a:
return src, ""
st["expected"] = {"from_step": a, "to_step": b, "need_wh": float(nxt["kwh"]) * 1000.0}
src.update(expected={"arrive": int(nxt["arrive"]), "depart": nxt["depart"], "kwh": float(nxt["kwh"])},
departure="session forecast", energy="session forecast")
return src, (f"car {name}: not plugged in; an expected session from the session forecast (issued {issued}): "
f"{_when_utc(nxt['arrive'])} to {_when_utc(nxt['depart']) if nxt['depart'] else 'beyond the plan'}, "
f"{float(nxt['kwh']):.1f} kWh, planned as a load; no charger command until it is plugged in")
def _hhmm(v: str, device_class) -> str | None:
"""A departure as HH:MM: from "07:00(:00)" or a timestamp (local time
of the timestamp as given)."""
@@ -322,9 +502,42 @@ def device_state(c, col: Collector, now: float) -> dict:
elif c.kind == "cover":
st["position_pct"] = cover_position(col, e["cover"])
st["set_position"] = cover_positions(col, e["cover"])
elif c.kind == "dhw_tank":
# its temperatures (a water heater's current one stands in for the top sensor), the heater's power,
# the room's temperature, what is set now; its own ratings (tank_reported)
wh = e.get("water_heater")
top = col.value(e.get("temp_top", "")) if e.get("temp_top") else None
if top is None and wh:
top = number(col.attr(wh, "current_temperature"))
st["temp_top"] = top
st["temp_bottom"] = col.value(e["temp_bottom"]) if e.get("temp_bottom") else None
st["heater_w"] = watts(col, e["heater_power"]) if e.get("heater_power") else None
st["room_c"] = col.value(e["room_temp"]) if e.get("room_temp") else None
if wh:
st["target_c"] = number(col.attr(wh, "temperature"))
st["mode"] = col.state(wh)
if e.get("switch"):
st["on"] = col.state(e["switch"]) == "on"
if e.get("sg_ready"):
st["sg"] = col.state(e["sg_ready"])
if hasattr(c, "reported"):
c.reported = tank_reported(c, col)
return st
def tank_reported(c, col: Collector) -> dict:
"""A tank's own ratings where its device reports them: volume_l (its
volume entity, L or m³), standby_loss_w (its standing loss, W or
kWh/24 h)."""
e, out = c.entities, {}
vol = _scaled(col, e.get("volume", ""), {"L": 1.0, "l": 1.0, "m³": 1000.0})
loss = _scaled(col, e.get("standby_loss", ""), {"W": 1.0, "kWh": 1000.0 / 24.0})
for k, v in (("volume_l", vol), ("standby_loss_w", loss)):
if v is not None and v > 0:
out[k] = v
return out
def _scaled(col: Collector, eid: str, units: dict) -> float | None:
"""An entity's value converted by its unit (units: unit -> factor; a
unit not in it: None, never a guess at the scale)."""
@@ -346,6 +559,10 @@ def battery_reported(c, col: Collector) -> dict:
for k, v in (("capacity_wh", cap), ("rated_power_w", pw), ("efficiency_pct", eff)):
if v is not None and v > 0:
out[k] = v
# its own idle use (0 is a value here: a battery that says it has none)
sb = _scaled(col, e.get("standby", ""), {"kW": 1000.0, "W": 1.0})
if sb is not None and sb >= 0:
out["standby_w"] = sb
return out
@@ -379,7 +596,7 @@ HYBRID_SWITCH_KEY = "heat.hybrid_switch_eur" # the Parameters page's (via t
def heating_refusal(c, params: dict, price_gas: list, price_heat: list, prices_status: str,
box_params: dict | None = None) -> dict | None:
box_params: dict | None = None, price_oil: list | None = None) -> dict | None:
"""Why a heating control is not planned (docs/methods.md E6, the
owner's rule: refuse, never guess), or None: a boiler's efficiency or
a boiler's / heat station's most heat unknown, no gas price (boiler,
@@ -407,7 +624,18 @@ def heating_refusal(c, params: dict, price_gas: list, price_heat: list, prices_s
dev = getattr(c, "rated_device", "") or ""
where.append(f"on the panel: Devices, {dev or 'the heating device'}, Ratings ({labels}); or in the mapping's params "
f"({', '.join(rated)})" + ("; or map the boiler's efficiency sensor" if "boiler_efficiency" in rated else ""))
if src in ("boiler", "hybrid") and (not price_gas or price_gas[0] is None):
fuel = str(params.get("fuel") or "gas")
if src in ("boiler", "hybrid") and fuel not in ("gas", "oil"):
# a boiler burns gas or heating oil (methods E15): another fuel is not priced, never taken for one
why.append(f"boiler fuel {fuel!r} not known (gas or oil)")
where.append("the mapping's params: fuel (gas or oil)")
missing = missing + ["fuel"]
elif src in ("boiler", "hybrid") and fuel == "oil" and (not price_oil or price_oil[0] is None):
why.append("no heating oil price for now")
where.append("the site's heating oil price (console: the site's tariff, Heating oil: the last delivery's "
"price per litre, or the weekly reference)")
missing = missing + ["oil_price"]
elif src in ("boiler", "hybrid") and fuel == "gas" and (not price_gas or price_gas[0] is None):
why.append("no gas price for now")
where.append("the site's gas tariff (console: the site's tariff, Gas)")
missing = missing + ["gas_price"]
@@ -424,6 +652,188 @@ def heating_refusal(c, params: dict, price_gas: list, price_heat: list, prices_s
return {"why": "; ".join(why), "where": "; ".join(where), "missing": missing}
TANK_WORDS = {"heater": ("the tank's heater (element, heat pump, boiler or district heat) unknown",
"the mapping's params: heater (the device profile asks for it on the panel)"),
"volume_l": ("the tank's volume unknown", "volume_l"),
"max_power_w": ("the tank heater's power unknown", "heater_kw"),
"max_heat_w": ("the tank heater's most heat unknown", "heater_kw"),
"cop": ("the tank heat pump's COP unknown", "cop"),
"boiler_efficiency": ("the tank boiler's efficiency unknown", None)}
def tank_refusal(c, st: dict, missing: list[str], price_gas: list, price_heat: list) -> dict | None:
"""Why a hot-water tank is not planned (docs/methods.md A13; design
note 3.6, 10.5), or None: only what a person can enter or connect (the
alarm box): its volume, heater kind and power, a heat pump's COP, a
boiler's efficiency, a temperature sensor, the gas or heat price, a
Parameters row. {"why", "where", "missing"}."""
from .controls import TANK_RATINGS
why, where, miss = [], [], []
rated = []
for m in missing:
if m in TANK_WORDS:
why.append(TANK_WORDS[m][0])
if m == "heater":
where.append(TANK_WORDS[m][1])
elif m == "boiler_efficiency":
where.append("on the panel: Devices, the tank, Ratings (Boiler efficiency, %); or the mapping's "
"params (boiler_efficiency)")
else:
rated.append(TANK_WORDS[m][1])
else:
why.append(f"parameter {m} not received")
where.append("the admin Parameters page (Hot water); it reaches the box with its tariff")
miss.append(m)
if rated:
dev = getattr(c, "rated_device", "") or "the tank's device"
labels = ", ".join(TANK_RATINGS[r][1] for r in dict.fromkeys(rated))
params = ", ".join(TANK_RATINGS[r][2] for r in dict.fromkeys(rated))
where.append(f"on the panel: Devices, {dev}, Ratings ({labels}); or in the mapping's params ({params})")
if st.get("temp_top") is None and st.get("temp_bottom") is None:
has = c.entities.get("temp_top") or c.entities.get("temp_bottom") or c.entities.get("water_heater")
why.append("tank temperature unknown" + (" (its sensor has no value)" if has else " (no tank temperature sensor)"))
where.append("map the tank's temperature sensor (temp_top, temp_bottom) or its water_heater")
miss.append("temp_sensor")
heater = str((c.params or {}).get("heater") or "")
if heater == "boiler" and (not price_gas or price_gas[0] is None):
why.append("no gas price for now")
where.append("the site's gas tariff (console: the site's tariff, Gas)")
miss.append("gas_price")
if heater == "district" and (not price_heat or price_heat[0] is None):
why.append("no heat price for now")
where.append("the site's heat tariff, or its building's heat price (console: Buildings, rules)")
miss.append("heat_price")
if not why:
return None
return {"why": "; ".join(why), "where": "; ".join(where), "missing": miss}
def tank_due(learnt: dict, facts: dict, start: int) -> dict:
"""A tank's legionella run where the mapping plans it (docs/methods.md
A13): its last time at the legionella temperature (the box's, storefit),
due an interval later; due_step: the step it falls due (0: now or
overdue; None: beyond the horizon, or no run planned)."""
out = {"last": learnt.get("legionella")}
iv = facts.get("legionella_interval_h")
if iv is None:
return out
last = learnt.get("legionella")
due = (last + iv * 3600.0) if last else float(start) # never seen at the temperature: due now
out["due"] = int(due)
k = int((due - start) // STEP_S)
out["due_step"] = max(0, k) if k < STEPS else None
return out
DRAW_DAYS_KEY = "dhw.draw_history_min_days"
def _tank_state(c, st: dict, params: dict, start: int, now: float, tz: str, bundles, history, box,
box_params: dict, storefit, price_gas: list, price_heat: list, only_tank: bool) -> dict:
"""A hot-water tank for the plan (docs/methods.md A13): its facts
(Control.tank_facts: the mapping's, the device's, the box's fit, the
owner's, the Parameters page's), its mean temperature now (S.4), its
legionella run's due time and the hot water it will give per step: the
site's dhw forecast (the cloud's or the box's model; the site's only
tank), else the box's own profile of the draws it measured (S.7, after
dhw.draw_history_min_days). {"refused": ...} for what a person can enter
(the alarm box); {"note": ...} while the draw history builds up (not a
refusal: its own thermostat meanwhile); else {"draw_w", "src"} with
params and state filled in."""
from . import storefit as storefit_mod
lt = storefit.tank_learnt(c.id) if storefit is not None else {}
facts, missing, fsrc = c.tank_facts(box_params, lt)
c.resolved = facts
no = tank_refusal(c, st, missing, price_gas, price_heat)
if no is not None:
return {"refused": no}
draw, dsrc = None, "none"
if only_tank and bundles:
got = _model_series("dhw_w", start, bundles, history, tz, box)
if got is not None:
draw, dsrc = [max(0.0, float(v)) for v in got[0]], "forecast (" + str(got[1].get("source", "model")) + ")"
if draw is None and storefit is not None:
draw = storefit.draw_profile(c.id, start, STEPS, tz, storefit_mod._num((box_params or {}).get(DRAW_DAYS_KEY)))
dsrc = "the box's measured draws (S.7)" if draw is not None else dsrc
if draw is None:
days = lt.get("draw_days") or 0.0
return {"note": f"{c.id}: hot-water tank not planned yet: no hot-water forecast and {days:.1f} days of its own "
f"draws measured (it needs {box_params.get(DRAW_DAYS_KEY, '?')}); its own thermostat meanwhile"}
params.update(facts)
st["temp_c"] = storefit_mod.mean_temp(st.get("temp_top"), st.get("temp_bottom"), float(facts["top_share"]))
st["legionella"] = tank_due(lt, facts, start) if str(c.p("legionella")) == "plan" else {"last": lt.get("legionella")}
params["legionella"] = str(c.p("legionella"))
params["shares_with"] = str(c.p("shares_with") or "")
params["cop_curve"] = facts.get("cop_curve") or []
for k in ("boiler_type", "part_load_curve"):
if (c.params or {}).get(k):
params[k] = c.params[k]
src = dict(fsrc, draw=dsrc)
if lt.get("ua") and not lt["ua"].get("kept"):
src["ua_fit"] = (f"learnt UA {lt['ua']['ua_w_k']:g} W/K is {lt['ua']['ua_w_k'] / max(lt['ua'].get('label_ua_w_k') or 1e-9, 1e-9):.1f}x "
"the label's: kept off (check the circulation pump and the insulation)")
return {"draw_w": draw, "src": src}
def heat_site(controls, devices: list, inputs, price_gas: list, price_heat: list, price_oil: list | None = None) -> dict:
"""What makes the site's heat no room model plans (docs/methods.md
A2.16, the heat outlook; backlog 45.3): the space heat where every
heating control is refused or there is none, and the hot water (an
unshiftable demand today; a tank between it and its heater is backlog
329). Its source: a heating control's boiler or district heat (its
facts: the efficiency and most heat, the part load), else the mapping's
inputs.heat, else district heat where the site is priced for heat and
not for gas. {"from", "source", facts..., "space": the space heat too
(no room planned)}; {} where nothing is known or the heat is
electricity (in the metered load already); {"note": why} where no
outlook can be made."""
heating = [c for c in controls if c.kind == "heating"]
planned = {d["id"] for d in devices if d["kind"] == "heating"}
fuel = [c for c in heating if str(c.p("heat_source") or "electric") in ("boiler", "district")]
if fuel:
c = fuel[0]
facts, _, _ = c.heat_facts()
return {"from": c.id, "source": str(c.p("heat_source")), **facts, "space": not planned,
**{k: c.p(k) for k in ("boiler_type", "part_load_curve", "fuel") if c.p(k)}}
if heating:
hybrid = [c for c in heating if c.p("heat_source") == "hybrid" and c.id not in planned]
if hybrid and not planned:
return {"note": f"heat outlook: {hybrid[0].id} is a hybrid: its plan chooses its source, none while it "
"is not planned"}
return {}
h = dict(getattr(inputs, "heat", None) or {})
if h.get("source"):
return {"from": "inputs.heat", **h, "space": True}
if any(v is not None for v in price_heat or []) and not any(v is not None for v in (price_gas or []) + (price_oil or [])):
return {"from": "the site's heat price", "source": "district", "space": True}
return {}
def carrier_inputs(start: int, now: float, site: dict, bundles, history, tz: str, box) -> dict:
"""The model state's carriers (docs/methods.md A2): the heat demands the
heat outlook costs where it has a source (heat_w, the space heat, only
where no room is planned; dhw_w, the hot water drawn: W of heat; None:
no forecast, the plan says so quietly), each through the model chain
(_model_series), the tariff bundle's CO2 factors (co2), and where each
came from (sources)."""
out, src = {"heat_site": site}, {}
wanted = [m for m, need in (("heat_w", bool(site.get("source")) and bool(site.get("space"))),
("dhw_w", bool(site.get("source")))) if need]
for m in wanted:
got = _model_series(m, start, bundles, history, tz, box) if bundles else None
if got is None:
out[m], src[m] = None, "none"
continue
out[m] = [max(0.0, float(v)) for v in got[0]]
info = {k: v for k, v in got[1].items() if k != "_cands"}
src[m] = info.get("source", "model")
co2 = bundles.co2(start, STEP_S, STEPS, now) if hasattr(bundles, "co2") else {}
if co2:
out["co2"] = co2
out["sources"] = src
return out
SET_POSITION = 4 # HA's CoverEntityFeature.SET_POSITION
@@ -445,15 +855,18 @@ def cover_position(col: Collector, ent: str) -> float | None:
def model_state(now: float, controls, inputs, col: Collector, bundles, history, tz: str,
weather_forecast: list[dict] | None, extra_limits: dict | None = None,
occupied_hours=(6, 22), building: dict | None = None, location: dict | None = None,
occupied_hours=OCCUPIED_HOURS, building: dict | None = None, location: dict | None = None,
shade_ctx: dict | None = None, grid_order: dict | None = None,
grid_max_w: float | None = None, ev_phases: dict | None = None) -> dict:
grid_max_w: float | None = None, ev_phases: dict | None = None, presence: list | None = None,
storefit=None) -> dict:
"""The 48 h, 15-minute input for the optimiser (JSON: it runs in a
subprocess). location: the site's latitude and longitude (HA's
configuration); shade_ctx: per cover control its room (temp_c,
setpoint_c, season: shades.py); grid_max_w: the site's connection (W,
config; the optimiser's default without it); ev_phases: per EV control
its phase count and source (evphases.EvPhases.all), else the mapping's."""
its phase count and source (evphases.EvPhases.all), else the mapping's;
presence: the presence sources' entities (the inputs' presence and the
mapped room.<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)
@@ -461,6 +874,8 @@ def model_state(now: float, controls, inputs, col: Collector, bundles, history,
cp = getattr(bundles, "carrier_prices", None)
price_gas = cp("gas", start, STEP_S, STEPS, now) if cp else [None] * STEPS
price_heat = cp("heat", start, STEP_S, STEPS, now) if cp else [None] * STEPS
# heating oil per kWh (Hi), an oil boiler's (methods E15)
price_oil = cp("oil", start, STEP_S, STEPS, now) if cp else [None] * STEPS
bp = getattr(bundles, "box_params", None)
box_params = bp(now) if bp else {}
# the base load: the house without the planned devices (Finding A2-a), so
@@ -471,14 +886,20 @@ def model_state(now: float, controls, inputs, col: Collector, bundles, history,
ctl = getattr(inputs, "controlled_power", None) or []
# the box's own models where the cloud's forecast no longer covers a step
# (localml.py), on HA's weather forecast where the mapping has one
box = (weather_forecast or [], getattr(inputs, "weather", "") or "")
wx = getattr(inputs, "weather", "") or ""
box = (weather_forecast or [], wx, col.attr(wx, "wind_speed_unit") if wx else None)
fc_src: dict = {"load": {}, "pv": {}}
notes: list[str] = [] # what the plan assumed for want of a fact (quiet: the plan's notes)
load, load_src = _series("load_w", start, bundles, history, tz, base_load(col, inputs), 500.0,
("base_load_w",) if ctl else ("base_load_w", "load_w"), box, fc_src["load"])
if ctl and not load_src.startswith("model") and bundles and \
bundles.forecast("load_w", start, STEP_S, 1, tz) is not None:
load_src += " (the model's load_w includes the planned devices: not used)"
pv, pv_src = _series("pv_w", start, bundles, history, tz, None, 0.0, None, box, fc_src["pv"])
# occupied per step: the presence now, then the learnt weekly presence, else 06-22 (occupancy)
occupied, occ_src, occ_notes = occupancy(start, tz, col, inputs.presence if presence is None else presence,
bundles, history, box, box_params, occupied_hours, fc_src)
notes += occ_notes
# the forecasts per source for the live error (boxtrain.py), not for the plan
cands = {k: v.pop("_cands") for k, v in fc_src.items() if "_cands" in v}
net_load = None
@@ -533,18 +954,10 @@ def model_state(now: float, controls, inputs, col: Collector, bundles, history,
# the sun's elevation now, held: a placeholder until a forecast says
elev = number(col.attr(inputs.sun, "elevation")) if inputs.sun else None
sun = [max(0.0, math.sin(math.radians(elev))) if elev is not None else 0.0] * STEPS
present = None
if inputs.presence:
vals = [col.state(p) for p in inputs.presence]
present = any(v in ("on", "home") for v in vals) if any(v is not None for v in vals) else None
occupied = []
for k in range(STEPS):
if k < 4 and present is not None:
occupied.append(1 if present else 0)
continue
h = datetime.fromtimestamp(start + k * STEP_S, timezone.utc).astimezone(zone).hour
occupied.append(1 if occupied_hours[0] <= h < occupied_hours[1] else 0)
sessions = bundles.ev_sessions(now) if hasattr(bundles, "ev_sessions") else None
ev_src: dict = {}
devices, rooms_src, phases_src, refused, battery_src, heat_src = [], {}, {}, {}, {}, {}
battery_fit, tank_src = {}, {} # the box's idle fits in force, a tank's facts by source
# a room's COP and comfort temperatures: the mapping's (the device's facts, the owner's), or the
# defaults (optimizer.shift_envelope publishes no shift from defaults); rooms not planned
# (room_refusal) with what their fallback schedule needs
@@ -566,6 +979,11 @@ def model_state(now: float, controls, inputs, col: Collector, bundles, history,
params["phases"] = info["phases"]
phases_src[c.id] = {"phases": info["phases"], "source": info["source"]}
st = device_state(c, col, now)
if c.kind == "ev":
# the car's departure and energy from the session forecast where it says none (B15)
ev_src[c.id], note = ev_session(c, st, sessions, start, now)
if note:
notes.append(note)
if c.kind in ("heating", "cooling"):
# the room's and the device's facts the mapping gives (no defaults: controls.FACTS)
params.update({k: float(c.params[k]) for k in ("r_k_per_kw", "c_kwh_per_k", "max_power_w", "cop")
@@ -586,7 +1004,7 @@ def model_state(now: float, controls, inputs, col: Collector, bundles, history,
nos = [room_refusal(c, st, src, power, source)]
if c.kind == "heating":
nos.append(heating_refusal(c, params, price_gas, price_heat, getattr(prices, "status", "tariff"),
box_params))
box_params, price_oil))
nos = [n for n in nos if n is not None]
if nos:
# not planned: its limits and a fallback schedule (the owner's or
@@ -610,19 +1028,47 @@ def model_state(now: float, controls, inputs, col: Collector, bundles, history,
continue
facts, _, fsrc = c.battery_facts()
params.update(facts)
battery_src[c.id] = fsrc
battery_src[c.id] = dict(fsrc)
# its idle loss (A2.3, S.2): never refuses it; without any value 0, a quiet note
if hasattr(c, "battery_idle_facts"):
fit = storefit.battery_in_force(c.id) if storefit is not None else None
idle, isrc = c.battery_idle_facts(fit, box_params)
params.update(idle)
battery_src[c.id].update(isrc)
if fit:
battery_fit[c.id] = fit
if isrc["standby_w"] == "none":
notes.append(f"{c.id}: battery idle loss not modelled: parameter battery.standby_w unset")
# the battery's power from its facts (device_range ran before them in bounds)
b = c.bounds("power_w", (extra_limits or {}).get(c.id))
bounds["power_w"] = [b.lo, b.hi, b.lo_by, b.hi_by]
extra = {}
if c.kind == "dhw_tank":
got = _tank_state(c, st, params, start, now, tz, bundles, history, box, box_params, storefit,
price_gas, price_heat, len([x for x in controls if x.kind == "dhw_tank"]) == 1)
if "refused" in got:
refused[c.id] = dict(got["refused"], kind="dhw_tank", name=c.label() if hasattr(c, "label") else c.id)
continue
if "note" in got:
notes.append(got["note"])
continue
tank_src[c.id] = got["src"]
extra = {"draw_w": got["draw_w"]}
b = c.bounds("temp_c", (extra_limits or {}).get(c.id)) # with a Großanlage's floor (tank_facts)
bounds["temp_c"] = [b.lo, b.hi, b.lo_by, b.hi_by]
devices.append({"id": c.id, "kind": c.kind, "params": params,
"state": st, "bounds": bounds,
"channels": sorted(c.writable())})
"channels": sorted(c.writable()), **extra})
clouds = _hourly(weather_forecast or [], "cloud_coverage", start, STEPS)
sky = [max(0.0, min(1.0, 1 - c / 100.0)) for c in clouds] if clouds else [1.0] * STEPS
ghi, ghi_src = irradiance(start, location, sky, sun if peak > 100 else None)
# the heat outlook (space heat no room plans, hot water), CO2 (methods A2): the forecasts and factors
carriers = carrier_inputs(start, now, heat_site(controls, devices, inputs, price_gas, price_heat, price_oil),
bundles, history, tz, box)
out = {"v": 1, "start": start, "step_s": STEP_S, "steps": STEPS, "tz": tz,
**{k: v for k, v in carriers.items() if k != "sources"},
"price_import": prices.import_ct, "price_export": prices.export_ct, "price_note": prices.note,
"price_gas": price_gas, "price_heat": price_heat, "params": box_params,
"price_gas": price_gas, "price_heat": price_heat, "price_oil": price_oil, "params": box_params,
# the tariff's state (bundles.Prices): status tariff | none, why none, the steps it prices
"prices": {"status": getattr(prices, "status", "tariff"), "reason": getattr(prices, "reason", ""),
"tariff": getattr(prices, "tariff_id", ""), "expired_at": getattr(prices, "expired_at", 0),
@@ -633,9 +1079,15 @@ def model_state(now: float, controls, inputs, col: Collector, bundles, history,
"sky": "weather forecast" if clouds else "clear", "rooms": rooms_src, "ghi": ghi_src,
"rooms_cop": cop_src, "rooms_band": band_src,
"ev_phases": phases_src,
# occupied steps per source (presence now, learnt, fixed hours) and why (B16)
"occupancy": occ_src,
**({"ev": ev_src} if ev_src else {}),
**({"battery": battery_src} if battery_src else {}),
**({"battery_fit": battery_fit} if battery_fit else {}),
**({"dhw_tank": tank_src} if tank_src else {}),
**({"heating": heat_src} if heat_src else {}),
**({"intraday": intraday} if intraday else {}),
**({"carriers": carriers["sources"]} if carriers["sources"] else {}),
# per series the steps from the cloud's forecast, the box's own model
# (its kind and weather) and the hour-of-week profile (methods.md B9)
"forecast": {k: v for k, v in fc_src.items() if v}},
@@ -647,7 +1099,9 @@ def model_state(now: float, controls, inputs, col: Collector, bundles, history,
# (preferences.apply gives their schedule, optimizer.fallback_entries the setpoints)
"fallback": fallback,
# the market's contracts in force as sources and sinks (shadow, the market's step 2)
"market": bundles.market_for_model(start, STEP_S, STEPS, now) if hasattr(bundles, "market_for_model") else []}
"market": bundles.market_for_model(start, STEP_S, STEPS, now) if hasattr(bundles, "market_for_model") else [],
# quiet notes (the plan's "notes"): no presence source, a parameter missing, the car's forecast session
"notes": notes}
if grid_max_w:
out["grid_max_w"] = float(grid_max_w)
if cands or net_load is not None:
@@ -779,7 +1233,7 @@ def room_refusal(c, st: dict, rc: str, power: str, source: str = "electric") ->
def _quantities(c) -> list[str]:
return {"battery": ["soc_pct", "power_w"], "heating": ["temp_c"], "cooling": ["temp_c"],
"ev": ["current_a"], "cover": ["position_pct"]}[c.kind]
"ev": ["current_a"], "cover": ["position_pct"], "dhw_tank": ["temp_c"]}[c.kind]
def _param_names(c) -> list[str]: