cantabile_edge, cantabile_modbus, cantabile_eebus 0.1.901: full source

This commit is contained in:
Setti Solutions S.R.L committed 2026-11-05 13:14:49 +02:00
1 parent d48b9aff87
commit e2c7085d2c
76 files changed
+5380 -330

No files matched your search

+94 -40
View File
@@ -13,9 +13,18 @@ Tariff v1 (agreed with the cloud side, 2026-10-28):
quarter hour>, "step_s": 900, "steps": 192, "expires", "currency": "EUR",
"unit": "ct/kWh", "import": [192 numbers|null], "export": [...],
"estimated": [indexes], "other": {...}, "sources": [...]}
After `expires` (or outside its steps): the last known flat price (the
mean of its import prices), and the plan says so. Without any tariff:
the configured default price.
Its prices are taken as they are, the steps fleet estimated (listed in
"estimated": the day-ahead before it is published) too; a step it has no
price for (null, or beyond its steps) has none here either. After
`expires`, or without any tariff, there is no price at all: no default,
no last price held (docs/parameters.md U1). prices() says so (status
"none" and the reason); the planner then plans without prices (comfort,
limits and the owner's musts only) and the box's panel says why and what
to do. A missing export price is no price, not 0 ct (optimizer.py).
Gas and heat (fleet heatprice.go, 2026-11-05): "gas" and "heat" per step
(ct/kWh gross: gas billed on Hs, heat delivered), null where none;
carrier_prices() reads them the same way (no default, nothing held past
the bundle's expiry). A bundle may price gas or heat alone.
Model v1 (the forecasts' data; the ML in ml/ is a placeholder, 2026-10-28):
{"v":1, "kind":"model", "id", "site" (or "*"), "issued", "expires"?,
@@ -115,12 +124,12 @@ def _check_tariff(d: dict):
raise ValueError("not a v1 tariff")
if int(d["step_s"]) != 900 or int(d["start"]) % 900:
raise ValueError("steps of 900 s from a quarter hour")
for k in ("import", "export"):
for k in ("import", "export", "gas", "heat"):
v = d.get(k) or []
if not isinstance(v, list) or not all(x is None or isinstance(x, (int, float)) for x in v):
raise ValueError(f"{k}: numbers or null")
if not [x for x in d.get("import") or [] if x is not None]:
raise ValueError("no import price")
if not [x for k in ("import", "gas", "heat") for x in d.get(k) or [] if x is not None]:
raise ValueError("no import, gas or heat price")
SERIES_MAX = 400 # a model's series: steps of 900 s (~4 days)
@@ -220,9 +229,28 @@ def _check_market(d: dict):
@dataclass
class Prices:
import_ct: list[float]
export_ct: list[float]
note: str # what the prices are ("tariff <id>", "flat fallback ...")
import_ct: list # per step ct/kWh, or None where the tariff has no price
export_ct: list # per step ct/kWh, or None (export unpriced: no value, not 0 ct)
note: str # what the prices are ("tariff <id>", "no tariff: ...")
status: str = "tariff" # tariff | none (no price to plan with)
reason: str = "" # none: never | expired | other_site | no_price_now
tariff_id: str = ""
expired_at: int = 0 # the tariff's expiry (reason expired)
priced_steps: int = 0 # the steps from the first with an import price, without a gap
NO_TARIFF = "no tariff: price optimisation off"
NO_TARIFF_WHY = {
"never": "no tariff received yet: the platform has none for this site, or has not delivered it",
"expired": "the tariff {id} expired at {at}",
"other_site": "the tariff file is another site's",
"no_price_now": "the tariff {id} has no import price for now",
}
def no_tariff_note(reason: str, tariff_id: str = "", expired_at: int = 0) -> str:
at = datetime.fromtimestamp(expired_at, timezone.utc).strftime("%Y-%m-%d %H:%M UTC") if expired_at else ""
return f"{NO_TARIFF} ({NO_TARIFF_WHY.get(reason, reason).format(id=tariff_id, at=at)})"
def _ahead_terms(ah, start: int, step_s: int, steps: int, terms) -> list | None:
@@ -262,13 +290,12 @@ def _ahead_terms(ah, start: int, step_s: int, steps: int, terms) -> list | None:
class Bundles:
def __init__(self, state_dir: str, site: str, default_price_ct: float = 30.0):
self.site, self.default = site, default_price_ct
def __init__(self, state_dir: str, site: str):
self.site = site
self.tariff = _File(os.path.join(state_dir, "tariff.json"), _check_tariff)
self.model = _File(os.path.join(state_dir, "model.json"), _check_model)
self.flats = _File(os.path.join(state_dir, "flats.json"), _check_flats)
self.market = _File(os.path.join(state_dir, "market.json"), _check_market)
self.flat: float | None = None # the last known tariff's mean import price
self._box_key, self._box, self.box_errors = None, {}, {}
self._box_cache: dict = {} # (series, start, model id) -> the box's forecast
@@ -278,39 +305,66 @@ class Bundles:
return (self.tariff.stamp(), self.model.stamp())
def prices(self, start: int, step_s: int, steps: int, now: float) -> Prices:
"""The tariff's prices for the horizon, as they are: None where it
has none. No tariff, another site's, an expired one or none for the
first step: status "none", no prices at all, and why."""
t = self.tariff.get()
if t is not None and t.get("site") not in (self.site, None, ""):
t = None # the link refuses these; a copied file must not count either
if t is not None:
imp = [x for x in t["import"] if x is not None]
self.flat = sum(imp) / len(imp)
flat = self.flat if self.flat is not None else self.default
# feed-in without a price is counted at 0 ct: the plan then values PV
# export at nothing (it may curtail or self-consume more), so its note says so
none = [None] * steps
if t is None:
note = "no tariff yet: default price" if self.flat is None else "no tariff: last known flat price"
return Prices([flat] * steps, [0.0] * steps, note + "; feed-in at 0 ct/kWh")
expired = now >= t.get("expires", 0)
out_i, out_e, outside, no_export = [], [], 0, 0
return Prices(none, list(none), no_tariff_note("never"), "none", "never")
if t.get("site") not in (self.site, None, ""):
return Prices(none, list(none), no_tariff_note("other_site"), "none", "other_site")
tid, exp = str(t.get("id") or ""), int(t.get("expires", 0) or 0)
if now >= exp:
return Prices(none, list(none), no_tariff_note("expired", tid, exp), "none", "expired", tid, exp)
imp, exs = t["import"], t.get("export") or []
out_i, out_e = [], []
for k in range(steps):
i = (start + k * step_s - t["start"]) // 900
pi = t["import"][i] if not expired and 0 <= i < len(t["import"]) else None
pe = (t.get("export") or [])[i] if not expired and 0 <= i < len(t.get("export") or []) else None
outside += pi is None
no_export += pe is None
out_i.append(pi if pi is not None else flat)
out_e.append(pe if pe is not None else 0.0)
if expired:
note = f"tariff {t.get('id')} expired: flat {flat:.1f} ct/kWh"
elif outside:
note = f"tariff {t.get('id')}; {outside} of {steps} steps at the flat {flat:.1f} ct/kWh"
else:
note = f"tariff {t.get('id')}"
if no_export == steps:
note += "; feed-in at 0 ct/kWh"
# a step after the tariff's expiry has no price either
live = start + k * step_s < exp
out_i.append(imp[i] if live and 0 <= i < len(imp) else None)
out_e.append(exs[i] if live and 0 <= i < len(exs) else None)
n = next((k for k, v in enumerate(out_i) if v is None), steps)
if n == 0:
return Prices(none, list(none), no_tariff_note("no_price_now", tid), "none", "no_price_now", tid, exp)
note = f"tariff {tid}"
if n < steps:
note += f"; prices for {n * step_s / 3600:g} h of {steps * step_s / 3600:g} h: the plan covers those"
no_export = sum(v is None for v in out_e[:n])
if no_export == n:
note += "; no export price: export unpriced (no value)"
elif no_export:
note += f"; feed-in at 0 ct/kWh in {no_export} of {steps} steps (no export price)"
return Prices(out_i, out_e, note)
note += f"; no export price in {no_export} of {n} steps: export unpriced there"
est = len([x for x in t.get("estimated") or [] if isinstance(x, int)])
if est:
note += f"; {est} steps estimated by the platform"
return Prices(out_i, out_e, note, "tariff", "", tid, exp, n)
def carrier_prices(self, carrier: str, start: int, step_s: int, steps: int, now: float) -> list:
"""The tariff's gas or heat prices for the horizon (ct/kWh gross),
None where it has none: no tariff, another site's, expired, a step
beyond it or a bundle without the series."""
t = self.tariff.get()
none = [None] * steps
if t is None or t.get("site") not in (self.site, None, "") or now >= int(t.get("expires", 0) or 0):
return none
xs, exp = t.get(carrier) or [], int(t.get("expires", 0) or 0)
out = []
for k in range(steps):
i = (start + k * step_s - t["start"]) // 900
out.append(xs[i] if start + k * step_s < exp and 0 <= i < len(xs) else None)
return out
def box_params(self, now: float) -> dict:
"""The Parameters page's values the box plans with (fleet heatprice.go
boxParams: the tariff bundle's "params", e.g. heat.hybrid_switch_eur),
{} without a valid tariff bundle: what needs one is refused."""
t = self.tariff.get()
if t is None or t.get("site") not in (self.site, None, "") or now >= int(t.get("expires", 0) or 0):
return {}
p = t.get("params")
return {k: v for k, v in p.items() if isinstance(k, str)} if isinstance(p, dict) else {}
def tariff_now(self, now: float) -> dict | None:
"""The tariff in force for HA: import now and next step, export now,
+6 -2
View File
@@ -21,8 +21,12 @@ from .mapping import Mapping, suggest
class _Json(logging.Formatter):
def format(self, r):
return json.dumps({"time": self.formatTime(r, "%Y-%m-%dT%H:%M:%S"), "level": r.levelname,
"logger": r.name, "msg": r.getMessage()})
out = {"time": self.formatTime(r, "%Y-%m-%dT%H:%M:%S"), "level": r.levelname,
"logger": r.name, "msg": r.getMessage()}
if r.exc_info:
# a logged exception's traceback (exc_info=True) in the same line
out["exc"] = self.formatException(r.exc_info)
return json.dumps(out)
def _logging():
+5 -1
View File
@@ -54,7 +54,6 @@ class Config:
replan_debounce_s: float = 3.0 # a pause after a change before planning again
solve_timeout_s: float = 60.0 # the optimiser's subprocess is killed after this
plan_stale_s: int = 1800 # older plans: the safe defaults
default_price_ct: float = 30.0 # ct/kWh when no tariff ever came
# The site's grid connection (W): the plan's import and export are at most
# this. 3 x 230 V x 63 A, a German house connection's usual main fuse;
# a site with a smaller fuse (or a building's larger one) sets its own.
@@ -90,6 +89,11 @@ def load(path: str | None, require_site: bool = True) -> Config:
sink = SinkConfig(**(raw.pop("sink", None) or {}))
ha = raw.pop("ha", None) or {}
token_file = os.environ.get("HA_TOKEN_FILE", ha.get("token_file", ""))
# a price without a tariff is no longer configurable (docs/parameters.md U1):
# an older file's default_price_ct is ignored, said once
if raw.pop("default_price_ct", None) is not None:
import logging
logging.getLogger(__name__).warning("config: default_price_ct is ignored: without a tariff the plan has no prices")
cfg = Config(sink=sink, ha_url=ha.get("url", Config.ha_url), **raw)
env = os.environ
cfg.site_id = env.get("CANTABILE_SITE_ID", cfg.site_id)
+35 -6
View File
@@ -90,7 +90,7 @@ class Controller:
self.mode = Mode(cfg.state_dir, cfg.mode)
self.col = Collector()
self.history = History(os.path.join(cfg.state_dir, "history.json"))
self.bundles = Bundles(cfg.state_dir, cfg.site_id, cfg.default_price_ct)
self.bundles = Bundles(cfg.state_dir, cfg.site_id)
self.guard = Guard(self.controls, consent, self.mode, override_hold_s=cfg.override_hold_s,
min_switch_s=cfg.min_switch_s, max_actions_per_hour=cfg.max_actions_per_hour, clock=clock)
self.saved_limits = self._load_limits() # the console's (limits.json)
@@ -256,8 +256,28 @@ class Controller:
return {c.kind for c in self.controls if c.kind in ("heating", "cooling", "ev")}
# -- plans ---------------------------------------------------------------
def owner_ratings(self):
"""The owner's ratings of each control's device (the panel's Devices
page: devices-specs.json, written by the Hub's devices tool) into
the controls (Control.rated, rated_device): a battery's capacity,
power and efficiency where the mapping and the device say none."""
try:
with open(os.path.join(self.cfg.state_dir, "devices-specs.json")) as f:
specs = json.load(f).get("devices") or {}
except (OSError, ValueError, AttributeError):
specs = {}
by = {}
for d in specs.values() if isinstance(specs, dict) else []:
if not isinstance(d, dict):
continue
for cid in d.get("controls") or []:
by.setdefault(cid, (d.get("ratings") or {}, str(d.get("name") or "")))
for c in self.controls:
c.rated, c.rated_device = by.get(c.id, ({}, ""))
def model_state(self) -> dict:
now = self.clock()
self.owner_ratings()
start = int(now // inputs_mod.STEP_S * inputs_mod.STEP_S)
# sealed devices are not planned at all
# and of a thermostat that heats and cools only its active side
@@ -314,9 +334,11 @@ class Controller:
self.executor.inputs_ok = self.inputs_fresh()
self.act_now.set() # carry out a new plan now
n = sum(len(v) for v in plan["devices"].values())
log.info("plan %s (%s, %.1f s): %d changes in 48 h, %.2f EUR vs %.2f EUR baseline; %s",
plan["id"], plan["status"], plan["solve_s"], n, plan["cost_eur"], plan["baseline_eur"],
plan.get("price_note", ""))
cost = (f"{plan['cost_eur']:.2f} EUR vs {plan['baseline_eur']:.2f} EUR baseline"
if plan.get("cost_eur") is not None and plan.get("baseline_eur") is not None else "no cost (no tariff)")
log.info("plan %s (%s, %.1f s): %d changes, %s; %s%s", plan["id"], plan["status"], plan["solve_s"], n, cost,
plan.get("price_note", ""),
"".join(f"; {k} not planned: {v['why']}" for k, v in (plan.get("refused") or {}).items()))
await self._publish("plan", self.public_plan(plan))
for cb in self.on_plan:
await cb(plan)
@@ -328,6 +350,9 @@ class Controller:
"mode": plan["mode"], "devices": plan["devices"], "cost_eur": plan["cost_eur"],
"baseline_eur": plan["baseline_eur"], "status": plan["status"],
"prices": plan.get("price_note", ""), "model": plan.get("model", ""),
# without a tariff: priced false, cost and baseline null (U1); controls not
# planned and why (U2); absent from older agents
"priced": plan.get("priced", True), "refused": plan.get("refused", {}),
"sources": plan.get("sources", {}),
# for the building (shed_w/grid_w per step, 24 h): absent from older agents
"flex": plan.get("flex", {}),
@@ -364,6 +389,8 @@ class Controller:
while not stop.is_set():
try:
n = self.prefs.take_inbox({c.id: c for c in self.controls}, self.tz)
while self.prefs.outbox: # the owner's own tariff to the cloud (link op own_tariff)
await self._publish("own_tariff", self.prefs.outbox.pop(0))
if n or self.prefs.prune(self.clock()):
await self._prefs_changed()
except Exception as e:
@@ -417,7 +444,8 @@ class Controller:
control at its safe default), and HA sends no update for an
unchanged value, so its age says nothing."""
for c in self.controls:
for role in ("temp", "soc"):
# a battery without its state of charge is not planned (inputs.battery_refusal), the rest is
for role in ("temp",):
if role in c.entities and self.col.value(c.entities[role]) is None:
return False
return True
@@ -518,7 +546,8 @@ class Controller:
try:
await self.make_plan()
except Exception as e:
log.warning("plan: %s", e)
# with its traceback: where it failed (the message alone did not say)
log.warning("plan: %s", e, exc_info=True)
self.wake.clear()
woken = False
try:
+199 -19
View File
@@ -16,7 +16,7 @@ that the owner's consent for the whole site must cover control
consent: false
entities: {charge_from_grid: switch.inverter_charge_from_grid,
setpoint: number.battery_power, soc: sensor.battery_soc}
params: {capacity_wh: 10000, max_charge_w: 3000, max_discharge_w: 3000}
params: {capacity_wh: 10000, max_charge_w: 3000, max_discharge_w: 3000, efficiency: 0.95}
limits: {soc_pct: {owner: [20, 100]}}
safe: {charge_from_grid: false}
@@ -30,7 +30,18 @@ Kinds, their entities (* needed) and what the executor sets (channels):
battery charge_from_grid (switch) and/or setpoint (number, W: + charge,
- discharge); mode (select: the inverter's own mode, set to
params.manual_option while the plan sets power, else to
params.auto_option); soc (sensor %), power (sensor W).
params.auto_option); soc (sensor %), power (sensor W);
the device's own ratings where it reports them: capacity
(sensor kWh or Wh), rated_power (sensor W or kW, charge and
discharge), efficiency (sensor %, round trip).
The battery's facts (battery_facts): capacity, charge and
discharge power and efficiency from the mapping's params, else
the device's reported ratings (those entities), else the owner's
ratings on the panel (devices-specs.json: battery_kwh,
battery_kw, battery_efficiency_pct). No default stands in for
any of them (docs/parameters.md U2): without one the battery is
not planned and the plan says which is missing and where to
enter it; without a state of charge from its sensor neither.
With a setpoint the agent sets the power there (and the mode)
and keeps charge_from_grid OFF: on many inverters (and the
simulated ones) the switch means "charge at full power" and would
@@ -38,7 +49,28 @@ Kinds, their entities (* needed) and what the executor sets (channels):
Only a battery without a setpoint (an HM8042 as the
profile has it: the switch alone) is driven through charge_from_grid.
heating climate* (target temperature) or switch* (on/off, a boiler);
temp (sensor °C, else the climate's current temperature)
temp (sensor °C, else the climate's current temperature);
source (select: a hybrid's heat source, its options named in
params.source_options {heat_pump: ..., boiler: ...}); efficiency
(sensor %, read only: a boiler's rated efficiency).
What makes the heat (params.heat_source; docs/methods.md E6):
electric (default) electricity at params.cop (a heat pump
~3, direct electric 1): its heat costs the import
price ÷ COP
heat_pump the same, with params.cop_curve [[°C outside, COP],
...] from its datasheet where given
boiler gas: heat costs the gas price ÷ the boiler's
efficiency (heat out per kWh of gas billed, Hs)
district the heat price per kWh (the heat meter's: the
site's heat tariff or its building's)
hybrid a heat pump and a boiler; the plan chooses one per
quarter-hour (the cheaper heat, in the comfort's
bounds) and sets the source select
The boiler's efficiency and max_heat_w (W of heat) are facts of
the device (FACTS: the mapping's params, else its efficiency
sensor, else the owner's ratings boiler_efficiency_pct and
heat_kw); without them, or without the gas or heat price, the
control is not planned and the panel says why (U2's rule).
cooling climate* (hvac_mode cool/off, target temperature); temp
A climate's own range (its min_temp..max_temp) narrows the
kind's range, and a target temperature is rounded to its
@@ -74,8 +106,14 @@ log = logging.getLogger(__name__)
# kind -> {entity role: allowed domains}; the roles the executor writes
ENTITIES = {
"battery": {"charge_from_grid": ("switch", "input_boolean"), "setpoint": ("number", "input_number"),
"mode": ("select", "input_select"), "soc": ("sensor", "input_number"), "power": ("sensor",)},
"heating": {"climate": ("climate",), "switch": ("switch", "input_boolean"), "temp": ("sensor",)},
"mode": ("select", "input_select"), "soc": ("sensor", "input_number"), "power": ("sensor",),
# read only: the device's own ratings (battery_facts)
"capacity": ("sensor", "input_number"), "rated_power": ("sensor", "input_number"),
"efficiency": ("sensor", "input_number")},
"heating": {"climate": ("climate",), "switch": ("switch", "input_boolean"), "temp": ("sensor",),
"source": ("select", "input_select"),
# read only: the boiler's own rated efficiency (%; heat_facts)
"efficiency": ("sensor", "input_number")},
"cooling": {"climate": ("climate",), "temp": ("sensor",)},
"ev": {"switch": ("switch", "input_boolean"), "current": ("number", "input_number"),
"connected": ("binary_sensor", "input_boolean"), "soc": ("sensor", "input_number"),
@@ -84,25 +122,34 @@ ENTITIES = {
"phases": ("sensor",), "power": ("sensor",), "current_measured": ("sensor",)},
"cover": {"cover": ("cover",)},
}
WRITES = {"charge_from_grid", "setpoint", "mode", "climate", "switch", "current", "cover"}
WRITES = {"charge_from_grid", "setpoint", "mode", "climate", "switch", "current", "cover", "source"}
NEEDED = {"battery": (("charge_from_grid", "setpoint"),), "heating": (("climate", "switch"),),
"cooling": (("climate",),), "ev": (("switch",),), "cover": (("cover",),)}
# defaults per kind (params may override each)
PARAMS = {
"battery": {"capacity_wh": 5000.0, "max_charge_w": 2500.0, "max_discharge_w": 2500.0, "efficiency": 0.95,
"soc_pct": 50.0, # soc_pct: the estimate when no sensor says
"manual_option": "manual", "auto_option": "self-consumption", "min_switch_s": 0.0,
# capacity_wh, max_charge_w, max_discharge_w, efficiency (one way, 0-1):
# facts of the device, no default (FACTS; battery_facts)
"battery": {"manual_option": "manual", "auto_option": "self-consumption", "min_switch_s": 0.0,
# steady.py: the least time between two changes of a mode / a setpoint, and
# the least gain (ct) a battery's change must bring over its hold
"hold_mode_s": 1800.0, "hold_set_s": 900.0, "min_gain_ct": 1.0},
"heating": {"r_k_per_kw": 10.0, "c_kwh_per_k": 3.0, "max_power_w": 2000.0, "comfort_c": 21.0,
"setback_c": 17.0, "cop": 1.0, # cop 1: electric; a heat pump ~3
# r_k_per_kw, c_kwh_per_k (the room), max_power_w, cop (the device): facts,
# no default (FACTS: without them the room is not optimised,
# inputs.room_refusal). comfort_c / setback_c / setup_c: the box's copy of
# the Parameters rows comfort.heating_setpoints / comfort.cooling_setpoints
# (docs/parameters.md C7) until the bundle carries them; the owner's
# schedule (preferences.py) and the mapping's win
"heating": {"comfort_c": 21.0, "setback_c": 17.0,
"min_switch_s": 600.0,
# the room's other heat (W; the model's fit, inputs._room_rc): internal
# (a number, or 24 by local hour) and the sun's per W/m² of irradiance
"internal_gain_w": 0.0, "solar_m2": 0.0, "hold_mode_s": 1800.0, "hold_set_s": 900.0, "min_gain_ct": 1.0},
"cooling": {"r_k_per_kw": 10.0, "c_kwh_per_k": 3.0, "max_power_w": 1500.0, "comfort_c": 25.0,
"setup_c": 28.0, "cop": 3.0, "min_switch_s": 600.0, "internal_gain_w": 0.0, "solar_m2": 0.0,
# (a number, or 24 by local hour) and the sun's per W/m² of irradiance;
# none modelled unless the fit or the mapping gives it
"internal_gain_w": 0.0, "solar_m2": 0.0, "hold_mode_s": 1800.0, "hold_set_s": 900.0, "min_gain_ct": 1.0,
# what makes the heat (docs/methods.md E6): electric | heat_pump | boiler | district | hybrid;
# a hybrid's source select options; a heat pump's datasheet COP by outside temperature
"heat_source": "electric", "source_options": {}, "cop_curve": []},
"cooling": {"comfort_c": 25.0,
"setup_c": 28.0, "min_switch_s": 600.0, "internal_gain_w": 0.0, "solar_m2": 0.0,
"hold_mode_s": 1800.0, "hold_set_s": 900.0, "min_gain_ct": 1.0},
"ev": {"need_wh": 10000.0, "departure": "07:00", "min_current_a": 6.0, "max_current_a": 16.0,
"phases": None, "voltage": 230.0, "min_switch_s": 0.0, # phases: None, not said (evphases.py)
@@ -113,6 +160,25 @@ PARAMS = {
}
# params a kind accepts without a default: facts of the device that come
# from the mapping, the device or its owner, or the feature refuses
FACTS = {"battery": ("capacity_wh", "max_charge_w", "max_discharge_w", "efficiency"),
# the room's R and C, the device's electric power and COP (room_refusal);
# a boiler's or a heat station's: its efficiency (heat per kWh of gas billed, Hs, 0-1)
# and its most heat (W); heat_facts
"heating": ("r_k_per_kw", "c_kwh_per_k", "max_power_w", "cop", "boiler_efficiency", "max_heat_w"),
"cooling": ("r_k_per_kw", "c_kwh_per_k", "max_power_w", "cop")}
HEAT_SOURCES = ("electric", "heat_pump", "boiler", "district", "hybrid")
# the owner's ratings of a heating device (devices-specs.json) and their labels
HEAT_RATINGS = {"boiler_efficiency": ("boiler_efficiency_pct", "Boiler efficiency, % (heat per kWh of gas billed)"),
"max_heat_w": ("heat_kw", "Most heat output, kW")}
# the owner's ratings (the panel's Devices page, devices-specs.json) and
# where to enter each: (rating, its label on the panel, the mapping's param)
BATTERY_RATINGS = {"capacity": ("battery_kwh", "Battery capacity, kWh", "capacity_wh"),
"power": ("battery_kw", "Battery power, kW", "max_charge_w and max_discharge_w"),
"efficiency": ("battery_efficiency_pct", "Battery round-trip efficiency, %", "efficiency")}
def ev_volts(params: dict, purpose: str) -> float:
"""A charger's volts x phases (W per A) for a purpose: "plan" (the
plan's power per A) or "order" (the grid order's current bound,
@@ -148,18 +214,83 @@ class Control:
entity_range: dict = field(default_factory=dict) # quantity -> (lo, hi) the device itself reports (a climate's)
switchover: dict = field(default_factory=dict) # heating/cooling pair on one climate (switchover.py)
name: str = "" # the owner's name for it (mapping `name`), else label() guesses
# the owner's ratings of its device (devices-specs.json: battery_kwh, ...)
# and that device's name, set by the controller; the device's own
# reported ratings (its capacity/rated_power/efficiency entities) by
# inputs.device_state
rated: dict = field(default_factory=dict)
rated_device: str = ""
reported: dict = field(default_factory=dict)
def label(self) -> str:
"""A name for people: the mapping's, else the id in words
("living_room_cooling": "Living room cooling")."""
return self.name or (self.id.replace("_", " ").strip().capitalize() or self.id)
def p(self, name: str) -> float | str:
return self.params.get(name, PARAMS[self.kind][name])
def p(self, name: str) -> float | str | None:
"""A param: the mapping's, else the kind's default; a fact without
a default (FACTS) is None when the mapping has none."""
if name in self.params:
return self.params[name]
if name in FACTS.get(self.kind, ()):
return None
return PARAMS[self.kind][name]
def battery_facts(self) -> tuple[dict, list[str], dict]:
"""A battery's capacity_wh, max_charge_w, max_discharge_w and
efficiency (one way): the mapping's params, else the device's
reported ratings, else the owner's (the panel); never a default.
(facts, the missing ones: "capacity", "power", "efficiency", per
fact where it came from: mapping | device | owner)."""
out, src, rep, own = {}, {}, self.reported or {}, self.rated or {}
def pick(key, device, owner):
for where, v in (("mapping", self.params.get(key)), ("device", device), ("owner", owner)):
x = _num(v)
if x is not None and x > 0:
out[key], src[key] = x, where
return
kwh, kw, eff_pct = (_num(own.get(k)) for k in ("battery_kwh", "battery_kw", "battery_efficiency_pct"))
pick("capacity_wh", rep.get("capacity_wh"), kwh * 1000.0 if kwh else None)
pick("max_charge_w", rep.get("rated_power_w"), kw * 1000.0 if kw else None)
pick("max_discharge_w", rep.get("rated_power_w"), kw * 1000.0 if kw else None)
# round trip -> one way: charging and discharging lose alike (the
# optimiser's eff x charge, discharge / eff: eff² round trip)
rt = rep.get("efficiency_pct")
pick("efficiency", _one_way(rt), _one_way(eff_pct))
missing = [m for m, keys in (("capacity", ("capacity_wh",)), ("power", ("max_charge_w", "max_discharge_w")),
("efficiency", ("efficiency",))) if any(k not in out for k in keys)]
return out, missing, src
def heat_facts(self) -> tuple[dict, list[str], dict]:
"""A heating control's boiler_efficiency (0-1, heat per kWh of gas
billed) and max_heat_w where its heat_source needs them (boiler,
hybrid: both; district: max_heat_w): the mapping's params, else the
device's (its efficiency sensor, in %), else the owner's ratings
(boiler_efficiency_pct, heat_kw); never a default. (facts, the
missing ones, per fact where it came from)."""
src = str(self.p("heat_source") or "electric")
need = {"boiler": ("boiler_efficiency", "max_heat_w"), "hybrid": ("boiler_efficiency", "max_heat_w"),
"district": ("max_heat_w",)}.get(src, ())
out, where, rep, own = {}, {}, self.reported or {}, self.rated or {}
eff_pct, kw = _num(own.get("boiler_efficiency_pct")), _num(own.get("heat_kw"))
cands = {"boiler_efficiency": (("mapping", self.params.get("boiler_efficiency")),
("device", _pct(rep.get("efficiency_pct"))), ("owner", _pct(eff_pct))),
"max_heat_w": (("mapping", self.params.get("max_heat_w")), ("owner", kw * 1000.0 if kw else None))}
for k in need:
for w, v in cands[k]:
x = _num(v)
if x is not None and x > 0 and (k != "boiler_efficiency" or x <= 1.0):
out[k], where[k] = x, w
break
return out, [k for k in need if k not in out], where
def device_range(self, q: str) -> tuple[float, float]:
if self.kind == "battery" and q == "power_w":
return (-float(self.p("max_discharge_w")), float(self.p("max_charge_w")))
# without its power known nothing but 0 may be set (no plan
# sets one then; a command is refused by the guard)
f, _, _ = self.battery_facts()
return (-float(f.get("max_discharge_w") or 0.0), float(f.get("max_charge_w") or 0.0))
if self.kind == "ev" and q == "current_a":
return (0.0, float(self.p("max_current_a")))
lo, hi = RANGE[self.kind][q]
@@ -203,6 +334,49 @@ def _num(v) -> float | None:
return x if x == x and abs(x) != float("inf") else None
def _pct(v) -> float | None:
"""A percentage as a share (0-1], or None."""
x = _num(v)
return x / 100.0 if x is not None and 0 < x <= 100 else None
def _one_way(round_trip_pct) -> float | None:
"""A round-trip efficiency in % as the one-way factor (its square root),
or None (not a number in 1..100)."""
x = _num(round_trip_pct)
return (x / 100.0) ** 0.5 if x is not None and 0 < x <= 100 else None
def _check_heat(cid: str, p: dict, ents: dict):
src = p.get("heat_source", "electric")
if src not in HEAT_SOURCES:
raise ValueError(f"control {cid}: heat_source is one of {', '.join(HEAT_SOURCES)}")
curve = p.get("cop_curve") or []
if not isinstance(curve, list) or not all(isinstance(x, (list, tuple)) and len(x) == 2 and _num(x[0]) is not None
and _num(x[1]) is not None and float(x[1]) > 0 for x in curve):
raise ValueError(f"control {cid}: cop_curve is [[outside °C, COP > 0], ...]")
opts = p.get("source_options") or {}
if not isinstance(opts, dict) or set(opts) - {"heat_pump", "boiler"}:
raise ValueError(f"control {cid}: source_options names the select's options for heat_pump and boiler")
if src == "hybrid" and ("source" not in ents or set(opts) != {"heat_pump", "boiler"}):
raise ValueError(f"control {cid}: a hybrid needs its source select and source_options for heat_pump and boiler")
def cop_at(params: dict, t_out: float) -> float:
"""A heat pump's COP at an outside temperature: its datasheet curve
(cop_curve, linear between the points, held beyond the ends), else
params cop."""
pts = sorted((float(a), float(b)) for a, b in (params.get("cop_curve") or []))
if not pts:
return float(params.get("cop") or PARAMS["heating"]["cop"])
if t_out <= pts[0][0]:
return pts[0][1]
for (t0, c0), (t1, c1) in zip(pts, pts[1:]):
if t_out <= t1:
return c0 + (c1 - c0) * (t_out - t0) / (t1 - t0) if t1 > t0 else c1
return pts[-1][1]
def _check_cover(cid: str, p: dict):
for k in ("open_pct", "shade_pct", "closed_pct"):
if k in p and (_num(p[k]) is None or not 0 <= float(p[k]) <= 100):
@@ -243,11 +417,17 @@ def parse(raw: list | None, reading_assets: set[str], rooms: set[str] | None = N
if not any(a in ents for a in alts):
raise ValueError(f"control {cid}: needs {' or '.join(alts)}")
params = dict(c.get("params") or {})
unknown = set(params) - set(PARAMS[kind])
unknown = set(params) - set(PARAMS[kind]) - set(FACTS.get(kind, ()))
if unknown:
raise ValueError(f"control {cid}: unknown params {', '.join(sorted(unknown))}")
if kind == "cover":
_check_cover(cid, params)
for k in FACTS.get(kind, ()):
if k in params and (_num(params[k]) is None or float(params[k]) <= 0 or
(k.endswith("efficiency") and float(params[k]) > 1)):
raise ValueError(f"control {cid}: {k} is a number above 0" + (" and at most 1" if k.endswith("efficiency") else ""))
if kind == "heating":
_check_heat(cid, params, ents)
sw = {}
if c.get("switchover") is not None:
if kind not in ("heating", "cooling") or "climate" not in ents:
+111 -11
View File
@@ -42,11 +42,24 @@ control are switched on here as on the Hub's Devices page (the agent starts
again, as the Hub's tool restarts it); without it the page points to the
add-on's configuration. Protection (protected / not, never sealed) and a thermostat's heating or
cooling choice are the owner's, here as on the Hub.
Remote Home Assistant for Cantabile support (item 19; the
add-on's option support_ha, off by default): while support has this Home
Assistant open (as its own HA user "Cantabile support", an administrator,
so it can open these pages too) both pages show it at the top with End
now, the add-on's own button: the link (edge/link/hatunnel.go) writes the
open sessions and its pid into its state directory (support-ha.json), End
now sends it SIGUSR1, as the Hub's panel does, and the link closes the
session and disables that user. What the Hub's panel keeps from support
stays the owner's here too: reading and control, protection, heating or
cooling, a shade's window, indoor or outdoor and the weather choice are
refused to the "Cantabile support" user.
"""
import asyncio
import json
import logging
import os
import signal
import time
import urllib.parse
@@ -61,6 +74,16 @@ from .joinpage import CSS, E, JoinPage
log = logging.getLogger(__name__)
PAGES = ("devices", "building")
# The Home Assistant user Cantabile support signs in as (edge/link/hauser.go
# haSupportUsername); HA's ingress names it in X-Remote-User-Name.
SUPPORT_USERNAME = "cantabile-support"
# Only the owner's (the Hub panel's post_devices refuses them to support).
OWNERS_ONLY = {"consent": M("Reading and control are the owner's to switch on."),
"protect": M("Protection is the owner's to change."),
"switchover": M("Heating or cooling is the owner's to choose."),
"shade": M("The shade's room and window are the owner's to set."),
"place": M("Indoor or outdoor is the owner's to choose."),
"weather": M("The weather forecast is the owner's to choose.")}
SWITCHOVER_WORDS = {"heating": M("Heating"), "cooling": M("Cooling"),
"season": M("By season (heating October to April, cooling May to September)"),
"outdoor": M("By outdoor temperature")}
@@ -118,6 +141,7 @@ section.set{border-top:1px solid #d5ded9;margin-top:1rem}section.set h3{margin:.
.row{display:flex;gap:.6rem}.row>div{flex:1}.right{text-align:right}
details.remove summary{color:#b3261e;cursor:pointer;padding:.8rem 0 .2rem}button.danger{background:none;color:#b3261e;box-shadow:inset 0 0 0 2px #b3261e}
details.more summary{cursor:pointer;margin:.6rem 0}
.box.support{background:#fbe9c9;border-color:#e8c37a}.box.support form{display:inline;margin:0 0 0 .4rem}.box.support button{margin:.3rem 0 0}
details.info{display:inline;position:relative}details.info>summary{display:inline-flex;align-items:center;justify-content:center;width:1.2rem;height:1.2rem;margin:0 .35rem;vertical-align:.1em;list-style:none;border:1px solid #5a6b62;border-radius:50%;color:#5a6b62;font:italic 600 .72rem/1 Georgia,serif;cursor:pointer}
details.info>summary::-webkit-details-marker{display:none}details.info>.info-body{position:absolute;left:0;z-index:3;width:min(22rem,80vw);margin-top:.4rem;padding:.7rem .9rem;background:#fff;color:#1d2a24;border:1px solid #d5ded9;border-radius:8px;box-shadow:0 6px 24px rgba(0,0,0,.18);font-size:.9rem;font-weight:normal}
@supports selector(:has(a)){form.changes .save{display:none}form.changes:has(input:default:not(:checked),input:checked:not(:default),option:checked:not(:default),input[value=outdoor]:checked) .save{display:inline-block}
@@ -126,7 +150,8 @@ form.changes:not(:has(input[value=outdoor]:checked)) .outdoor{display:none}}
.badge.quiet{background:none;box-shadow:inset 0 0 0 1px #2b3a32;color:#9fb0a6}.badge.warn{background:#3a2c12;color:#f3c77e}.pill.on{background:#19302a;color:#a6e0bf}
.dot.on{background:#5cc493}.add,section.set{border-color:#2b3a32}a.box.dev:hover{border-color:#5cc493}select{background:#18221d;color:#e3ebe6;border:1px solid #3a4b42}
details.remove summary{color:#f08a80}button.danger{background:none;color:#f08a80;box-shadow:inset 0 0 0 2px #f08a80}
details.info>.info-body{background:#18221d;color:#e3ebe6;border-color:#2b3a32}details.info>summary{border-color:#9fb0a6;color:#9fb0a6}}"""
details.info>.info-body{background:#18221d;color:#e3ebe6;border-color:#2b3a32}details.info>summary{border-color:#9fb0a6;color:#9fb0a6}
.box.support{background:#3a2c12;border-color:#6b5222}}"""
# HA's hash (#devices, #building: Cantabile's dashboard) to this page's ?p=
HASH_SCRIPT = ("(function(){try{var P=window.parent;if(P===window)return;var m=/^#(devices|building)$/.exec(P.location.hash||'');"
"if(m&&location.search.indexOf('p=')<0&&location.search.indexOf('code=')<0)location.replace('?p='+m[1])}"
@@ -844,10 +869,10 @@ def messages(msg: str, err: str) -> str:
return (f'<div class="box ok">{E(msg)}</div>' if msg else "") + (f'<div class="box err">{E(err)}</div>' if err else "")
def page_devices(v: dict, msg: str = "", err: str = "") -> str:
def page_devices(v: dict, msg: str = "", err: str = "", banner: str = "") -> str:
about = E(T("Home Assistant's devices that a Cantabile device profile knows. Use one with Cantabile to see it on "
"Cantabile's dashboard and to let Cantabile read it once you have given your consent."))
body = [f"<h2>{E(T('Devices'))}{info(about)}</h2>" + messages(msg, err)]
body = [banner + f"<h2>{E(T('Devices'))}{info(about)}</h2>" + messages(msg, err)]
rooms = v.get("rooms") or []
if v.get("devices"):
n = len(v["devices"])
@@ -872,15 +897,15 @@ def page_devices(v: dict, msg: str = "", err: str = "") -> str:
return html(T("Cantabile: devices"), "".join(body), "devices")
def page_device(v: dict, dev_id: str, msg: str = "", err: str = "") -> str:
def page_device(v: dict, dev_id: str, msg: str = "", err: str = "", banner: str = "") -> str:
"""One device in use: its state and values, then its settings, each
section saving on its own. The list when there is no such device."""
d = next((x for x in v.get("devices") or [] if x["id"] == dev_id), None)
if not d:
return page_devices(v, msg, err)
return page_devices(v, msg, err, banner)
rooms = v.get("rooms") or []
vals = device_values(d)
body = (f'<a class="back" href="?p=devices">‹ {E(T("Devices"))}</a><h2>{E(d["name"])}</h2>'
body = (banner + f'<a class="back" href="?p=devices">‹ {E(T("Devices"))}</a><h2>{E(d["name"])}</h2>'
f'<div class="model head">{model_line(d)} {status_badge(d.get("status"))}</div>{messages(msg, err)}'
f'<div class="box now"><span class="state">{device_state(d)}</span>'
+ (f'<span class="values">{E(vals)}</span>' if vals else "") + "</div>"
@@ -894,12 +919,57 @@ def page_refused(why: str, page: str = "devices") -> str:
return html("Cantabile", f"<h2>{E(head)}</h2><div class=\"box err\">{E(why)}</div>", page)
class SupportSessions:
"""Cantabile support's open Home Assistant session, as the link writes
it (<link state>/support-ha.json: its pid, the sessions), and End now."""
def __init__(self, link_state: str, proc: str = "/proc", kill=os.kill):
self.path = os.path.join(link_state, "support-ha.json")
self.proc, self.kill = proc, kill
def state(self) -> dict:
st = _read_json(self.path, {})
return st if isinstance(st, dict) else {}
def open(self) -> list[dict]:
return [x for x in self.state().get("sessions") or [] if isinstance(x, dict)]
def end(self) -> bool:
"""SIGUSR1 to the link (only to a process that is the link): True if sent."""
pid = self.state().get("pid")
if not isinstance(pid, int) or pid <= 1:
return False
try:
with open(os.path.join(self.proc, str(pid), "cmdline"), "rb") as f:
if b"cantabile-link" not in f.read().split(b"\0")[0]:
return False
self.kill(pid, signal.SIGUSR1)
except OSError:
return False
return True
def support_banner(sessions: list[dict], page: str) -> str:
"""While support has this Home Assistant open: who, how long, End now."""
if not sessions:
return ""
who = ", ".join(sorted({str(x.get("by") or T("Cantabile support")) for x in sessions}))
since = min((x.get("since") or 0) for x in sessions)
n = max(0, int((time.time() - since) // 60)) if since else 0
return (f'<div class="box warn support"><b>{E(T("Cantabile support has this Home Assistant open"))}</b> '
+ E(TN("({who}, for {n} minute), signed in as the user \"Cantabile support\". Everything they do is recorded.",
"({who}, for {n} minutes), signed in as the user \"Cantabile support\". Everything they do is recorded.",
n, who=who))
+ form("end-support", hidden(p=page), T("End now"), inline=True) + "</div>")
class App(JoinPage):
"""The add-on's pages: Devices (the first) and Building or community."""
def __init__(self, fleet, devices: Devices, location=None, admin=None):
super().__init__(fleet, **({"location": location} if location else {}))
self.devices = devices
self.support = SupportSessions(getattr(fleet, "link_state", "") or os.environ.get("CANTABILE_LINK_STATE", "/data/link"))
# admin(user_id) -> bool: the agent's HA client asks HA (ha.is_admin)
self.admin = admin or self._admin
@@ -924,21 +994,51 @@ class App(JoinPage):
return 200, page_refused(T("Cantabile could not ask Home Assistant who you are ({error}).", error=e), page)
if not ok:
return 200, page_refused(T("Only an administrator of Home Assistant can use this page."), page)
f = ({k: v[0] for k, v in urllib.parse.parse_qs(data.decode("utf-8", "replace")).items()}
if method == "POST" else {})
if f.get("do") == "end-support":
# the add-on's End now (any administrator: the owner, or support itself)
sent = await asyncio.to_thread(self.support.end)
msg, err = ((T("Ended. Cantabile support's session is closed and the user \"Cantabile support\" is disabled "
"again (a few seconds)."), "") if sent else
("", T("No session to end, or Cantabile's connection is not running.")))
if page == "building":
return 200, self.with_banner(await asyncio.to_thread(self.get, {}), "building", msg, err)
return 200, page_devices(await self.devices.view(), msg, err, self.banner("devices"))
if page == "building":
status, out = await super().respond(method, url, hdr, data, peer)
if status == 200:
out = out.replace("</style>", f"\n{MORE_CSS}</style><script>{HASH_SCRIPT}</script>", 1) \
.replace("<body>", "<body>" + nav("building"), 1)
out = self.with_banner(out, "building")
return status, out
if url.path not in ("/", "") or method not in ("GET", "POST"):
return 404, T("Not found")
dev_id = (q.get("d") or [""])[0]
banner = self.banner("devices")
if method == "GET":
v = await self.devices.view()
return 200, page_device(v, dev_id) if dev_id else page_devices(v)
f = {k: v[0] for k, v in urllib.parse.parse_qs(data.decode("utf-8", "replace")).items()}
return 200, page_device(v, dev_id, banner=banner) if dev_id else page_devices(v, banner=banner)
by = hdr.get("x-remote-user-display-name") or hdr.get("x-remote-user-name") or "owner"
return 200, await self.post_devices(f, by)
if self.is_support(hdr) and f.get("do") in OWNERS_ONLY:
err = T(OWNERS_ONLY[f["do"]])
v = await self.devices.view()
return 200, page_device(v, f.get("id", ""), err=err, banner=banner) if f.get("id") else \
page_devices(v, err=err, banner=banner)
return 200, (await self.post_devices(f, by)).replace("<body>" + nav("devices"), "<body>" + nav("devices") + banner, 1)
def is_support(self, hdr: dict) -> bool:
"""The request is the "Cantabile support" HA user's (HA's ingress
names it: its username, or its id while a session is open)."""
uid = hdr.get("x-remote-user-id", "")
return (hdr.get("x-remote-user-name", "") == SUPPORT_USERNAME
or bool(uid) and uid in {x.get("ha_user") for x in self.support.open()})
def banner(self, page: str) -> str:
return support_banner(self.support.open(), page)
def with_banner(self, out: str, page: str, msg: str = "", err: str = "") -> str:
"""JoinPage's page with this app's style, nav and support banner."""
return out.replace("</style>", f"\n{MORE_CSS}</style><script>{HASH_SCRIPT}</script>", 1) \
.replace("<body>", "<body>" + nav(page) + self.banner(page) + messages(msg, err), 1)
async def post_devices(self, f: dict, by: str = "owner") -> str:
dv, do, msg, err = self.devices, f.get("do", ""), "", ""
+13
View File
@@ -102,6 +102,12 @@ def actions_for(c, want, col, level="plan", why="") -> list[Action]:
act("climate", "set_temperature", {"temperature": float(v)}, float(v), "temp_c")
elif v in ("on", "off"):
switch("switch", v == "on")
# a hybrid's heat source (optimizer: the heat pump or the boiler, the cheaper heat now)
src = want.get("source") if isinstance(want, dict) else None
if c.kind == "heating" and src and "source" in e:
opt = (c.p("source_options") or {}).get(src)
if opt and col.state(e["source"]) != str(opt):
act("source", "select_option", {"option": str(opt)}, str(opt))
elif c.kind == "ev":
v = want.get("set") if isinstance(want, dict) else want
if v == "off":
@@ -166,6 +172,13 @@ class Executor:
if cmd:
self.commands.pop(c.id, None)
fresh = self.plan is not None and now - self.plan.get("made", 0) <= self.stale and self.inputs_ok
if fresh and c.id in (self.plan.get("refused") or {}):
# not planned: a room's fallback schedule (optimizer.fallback_entries),
# else its safe default (a battery without its facts, docs/parameters.md U2)
e = _plan_value(self.plan, c.id, now)
if e is not None:
return e, "plan", e.get("why", "")
return safe_want(c), "plan", "not planned: " + str(self.plan["refused"][c.id].get("why", ""))
if fresh:
e = _plan_value(self.plan, c.id, now)
return e, "plan", (e or {}).get("why", "")
+123 -28
View File
@@ -22,6 +22,16 @@ metered). The kinds:
with the Mieterstrom pricing) times the site's calibration
(pvcalib.py).
The series (SERIES_FEATURES; methods.md B1-B2, B13-B16): electric `load`,
`base_load`, `pv` (W); thermal `heat` (heat delivered for space heating,
W) and `dhw` (heat for hot water, W) with the weather, the wind, the room
model's heat loss (`loss`: the site's fitted UA times the indoor less the
outdoor temperature) and the expected occupancy (`occ`: the occupancy
series' hour-of-week profile); `occupancy` (the share of a site's presence
sensors that see someone, 0..1) and `ev_plug` (cars plugged in at the
site's chargers, 0..1 per charger) on the calendar alone. The same kinds
and the same code for each: a new series is data and features.
A model is a JSON-able dict ("params"); fit_* makes it, predict() uses it.
intraday() carries the last hours' error against the meter into the next
hours (the box every 15 minutes; methods.md B10).
@@ -54,6 +64,16 @@ MIN_GBM_SLOTS = 96 # a day of data at least
LOAD_FEATURES = ["hod", "dow", "off", "how", "lag7", "temp", "ghi", "cloud", "hdd", "special", "doy_sin", "doy_cos",
"daylight"]
PV_FEATURES = ["hod", "how", "lag7", "temp", "ghi", "cloud", "elev", "az", "phys", "doy_sin", "doy_cos", "daylight"]
HEAT_FEATURES = ["hod", "dow", "off", "how", "lag7", "temp", "ghi", "cloud", "hdd", "wind", "special", "doy_sin", "doy_cos",
"daylight", "loss", "occ"]
DHW_FEATURES = ["hod", "dow", "off", "how", "lag7", "temp", "special", "doy_sin", "doy_cos", "occ"]
PRESENCE_FEATURES = ["hod", "dow", "off", "how", "lag7", "special", "doy_sin", "doy_cos"]
SERIES_FEATURES = {"pv": PV_FEATURES, "heat": HEAT_FEATURES, "dhw": DHW_FEATURES, "occupancy": PRESENCE_FEATURES,
"ev_plug": PRESENCE_FEATURES}
# shares, not watts: occupancy 0..1, ev_plug the cars plugged in (0..1 per
# charger); their nMAE's floor and their profiles' digits differ (level_floor)
FRACTION_SERIES = ("occupancy", "ev_plug")
UPPER = {"occupancy": 1.0} # a share of the sensors: never above 1
FEATURES_V1 = {"load": ["hod", "dow", "off", "how", "lag7", "temp", "ghi", "cloud", "hdd"], # before 2026-11-04
"pv": ["hod", "how", "lag7", "temp", "ghi", "cloud", "elev", "az", "phys"]}
CATEGORICAL = ("special",)
@@ -63,13 +83,33 @@ CATEGORICAL = ("special",)
# (measured 2026-11-04, building's synthetic site: a cold snap 12 K below the
# coldest day trained on, held-out nMAE 29.5 % -> 6.4 %; an ordinary winter
# week 3.8 % -> 3.3 %; methods.md B10)
LINEAR_SERIES: tuple = ("load", "base_load")
LINEAR_SERIES: tuple = ("load", "base_load", "heat")
# ... but only with this much history (days between the first and last
# metered slot): on a few days linear leaves overfit (measured on the sim
# farm 2026-11-04, ~3.6 days: nMAE 1.07 with them, 0.58 without)
LINEAR_MIN_DAYS = 14.0
# recency (methods.md B10): a slot's weight max(0.5^(age/30 d), 0.25 x the
# season's likeness (cos of the age over a year, last year's same weeks
# count), 0.05)
HALF_LIFE_D, SEASON_W, FLOOR_W = 30.0, 0.25, 0.05
def feature_names(series: str) -> list[str]:
"""A series' current features (SERIES_FEATURES; the load's for the rest)."""
return list(SERIES_FEATURES.get(series, LOAD_FEATURES))
def level_floor(series: str) -> float:
"""The metered mean under which nMAE is not given (metrics): 1 W for
a power, 0.01 for a share (FRACTION_SERIES)."""
return 0.01 if series in FRACTION_SERIES else 1.0
def digits(series: str) -> int:
"""The decimals an hour-of-week profile keeps: 1 for watts, 3 for a share."""
return 3 if series in FRACTION_SERIES else 1
# ---- the calendar -------------------------------------------------------------
def _easter(y: int) -> date:
@@ -209,6 +249,14 @@ class Weather:
elev: np.ndarray
az: np.ndarray
hours: list = field(default_factory=list) # the records (pvforecast.Hour), for pvforecast
wind: np.ndarray | None = None # m/s, the record of the slot's hour (None: no record had it)
def slice(self, sl: slice) -> "Weather":
return Weather(self.temp[sl], self.ghi[sl], self.cloud[sl], self.elev[sl], self.az[sl], self.hours,
None if self.wind is None else self.wind[sl])
def wind_or_nan(self, n: int) -> np.ndarray:
return np.full(n, np.nan) if self.wind is None else self.wind
def sun(t: np.ndarray, lat: float | None, lon: float | None) -> tuple[np.ndarray, np.ndarray]:
@@ -228,7 +276,7 @@ def weather(t: np.ndarray, hours: list, lat: float | None, lon: float | None) ->
pvforecast.forecast does), else a clear sky dimmed by the cloud cover."""
n = len(t)
el, az = sun(t, lat, lon)
temp, ghi, cloud = np.full(n, np.nan), np.full(n, np.nan), np.full(n, np.nan)
temp, ghi, cloud, wind = np.full(n, np.nan), np.full(n, np.nan), np.full(n, np.nan), np.full(n, np.nan)
if not hours:
return Weather(temp, ghi, cloud, el, az, [])
by_end = {}
@@ -249,6 +297,8 @@ def weather(t: np.ndarray, hours: list, lat: float | None, lon: float | None) ->
continue
if h.cloud_pct is not None:
cloud[i] = h.cloud_pct
if getattr(h, "wind_ms", None) is not None:
wind[i] = h.wind_ms
if lat is None or lon is None:
if h.solar_kwh_m2 is not None:
ghi[i] = h.solar_kwh_m2 * 1000.0
@@ -264,14 +314,15 @@ def weather(t: np.ndarray, hours: list, lat: float | None, lon: float | None) ->
ghi[i] = h.solar_kwh_m2 * 1000.0 * (4 * mine / s) if s > 0 else 0.0
elif h.cloud_pct is not None:
ghi[i] = pvforecast.cloud_dimmed(pvforecast.clear_sky_ghi(el[i]), h.cloud_pct)
return Weather(temp, ghi, cloud, el, az, list(hours))
return Weather(temp, ghi, cloud, el, az, list(hours), wind if not np.isnan(wind).all() else None)
# ---- metrics ------------------------------------------------------------------
def metrics(y: np.ndarray, p: np.ndarray) -> dict:
def metrics(y: np.ndarray, p: np.ndarray, floor: float = 1.0) -> dict:
"""MAE and RMSE (W) and nMAE (MAE over the mean metered value) on the
slots where both exist; nMAE None when the metered mean is ~0 (a night)."""
slots where both exist; nMAE None when the metered mean is ~0 (a night;
under `floor`: level_floor)."""
m = ~(np.isnan(y) | np.isnan(p))
if not m.any():
return {"n": 0, "mae": None, "rmse": None, "nmae": None}
@@ -279,13 +330,14 @@ def metrics(y: np.ndarray, p: np.ndarray) -> dict:
mae = float(np.abs(e).mean())
level = float(np.abs(y[m]).mean())
return {"n": int(m.sum()), "mae": mae, "rmse": float(np.sqrt((e ** 2).mean())),
"nmae": mae / level if level > 1.0 else None}
"nmae": mae / level if level > floor else None}
# ---- how: the hour-of-week profile -----------------------------------------------
def fit_how(t: np.ndarray, y: np.ndarray, tz: str, weights: np.ndarray | None = None) -> dict:
"""weights: per slot (recency_weights); None: all alike."""
def fit_how(t: np.ndarray, y: np.ndarray, tz: str, weights: np.ndarray | None = None, ndigits: int = 1) -> dict:
"""weights: per slot (recency_weights); None: all alike. ndigits: the
values' decimals (digits(series): a share keeps 3)."""
cal = calendar(t, tz)
vals: list[float | None] = []
have = ~np.isnan(y)
@@ -299,7 +351,7 @@ def fit_how(t: np.ndarray, y: np.ndarray, tz: str, weights: np.ndarray | None =
if v is None: # the same hour on the other weekdays, else the mean
same = [vals[d * 24 + h % 24] for d in range(7) if vals[d * 24 + h % 24] is not None]
v = sum(same) / len(same) if same else overall
out.append(round(max(v, 0.0), 1))
out.append(round(max(v, 0.0), ndigits))
return {"kind": "how", "values": out, "tz": tz}
@@ -321,10 +373,13 @@ def _lag7(t: np.ndarray, y: np.ndarray, hist_t: np.ndarray | None, hist_y: np.nd
def features(series: str, t: np.ndarray, w: Weather, how_p: dict, tz: str, lag7: np.ndarray,
phys: np.ndarray | None, names: list[str] | None = None, lat: float | None = None,
state: str | None = None, kept: list | None = None) -> tuple[np.ndarray, list[str]]:
state: str | None = None, kept: list | None = None, room: dict | None = None,
occ: list | None = None) -> tuple[np.ndarray, list[str]]:
"""The feature matrix; names: a model's own list (default: the
series' current one). kept: the special days' types the model learnt
(the others count as normal)."""
(the others count as normal). room: {"ua_w_per_k", "t_in_c"} (the heat
loss UA x (indoor - outdoor), W; methods.md B13), occ: the occupancy's
168 hour-of-week values (the expected share present); NaN without them."""
cal = calendar(t, tz, state)
special = cal["special"]
if kept is not None:
@@ -334,11 +389,23 @@ def features(series: str, t: np.ndarray, w: Weather, how_p: dict, tz: str, lag7:
"how": how_values(how_p, t, tz), "lag7": lag7, "temp": w.temp, "ghi": w.ghi, "cloud": w.cloud,
"hdd": np.maximum(15.0 - w.temp, 0.0), "elev": w.elev, "az": w.az,
"phys": phys if phys is not None else np.full(len(t), np.nan), "special": special,
"doy_sin": np.sin(ang), "doy_cos": np.cos(ang), "daylight": daylight_h(cal["doy"], lat)}
names = list(names) if names is not None else (PV_FEATURES if series == "pv" else LOAD_FEATURES)
"doy_sin": np.sin(ang), "doy_cos": np.cos(ang), "daylight": daylight_h(cal["doy"], lat),
"wind": w.wind_or_nan(len(t)), "loss": heat_loss(room, w.temp),
"occ": how_values({"values": occ}, t, tz) if occ and len(occ) == 168 else np.full(len(t), np.nan)}
names = list(names) if names is not None else feature_names(series)
return np.column_stack([cols[c] for c in names]), names
def heat_loss(room: dict | None, temp: np.ndarray) -> np.ndarray:
"""The room model's heat loss per slot (W): UA (W/K) x (indoor -
outdoor), never below 0; NaN without a fitted UA or an indoor
temperature (methods.md B13.1)."""
ua, tin = (room or {}).get("ua_w_per_k"), (room or {}).get("t_in_c")
if not ua or tin is None:
return np.full(len(temp), np.nan)
return np.maximum(float(ua) * (float(tin) - temp), 0.0)
def special_kept(t: np.ndarray, y: np.ndarray, tz: str, state: str | None = None, at_least: int = 2) -> list[int]:
"""The special days' types with at least 2 metered days in (t, y)."""
cal = calendar(t, tz, state)
@@ -354,28 +421,41 @@ def special_kept(t: np.ndarray, y: np.ndarray, tz: str, state: str | None = None
def fit_gbm(series: str, t: np.ndarray, y: np.ndarray, w: Weather, tz: str, lag7: np.ndarray,
phys: np.ndarray | None, lat: float | None = None, state: str | None = None,
weights: np.ndarray | None = None, linear: bool | None = None,
names: list[str] | None = None) -> dict | None:
names: list[str] | None = None, base: np.ndarray | None = None, room: dict | None = None,
occ: list | None = None) -> dict | None:
"""weights: per slot (recency_weights; None: all alike); linear: leaves
with linear models (default: series in LINEAR_SERIES); names: the
features (default: the series' current list)."""
features (default: the series' current list); base: a forecast per slot
the trees learn the difference to (LightGBM's init_score: the cloud
teacher's, methods.md B11), then params["base"] and predict_gbm needs it.
room, occ: the heat series' room model and occupancy profile
(features), kept in the params where the features use them."""
import lightgbm as lgb
have = ~np.isnan(y)
have = ~np.isnan(y) if base is None else ~(np.isnan(y) | np.isnan(base))
if have.sum() < MIN_GBM_SLOTS:
return None
how_p = fit_how(t, y, tz, weights)
how_p = fit_how(t, y, tz, weights, digits(series))
kept = special_kept(t, y, tz, state)
X, names = features(series, t, w, how_p, tz, lag7, phys, names, lat, state, kept)
X, names = features(series, t, w, how_p, tz, lag7, phys, names, lat, state, kept, room, occ)
params = dict(GBM_PARAMS)
if linear if linear is not None else series in LINEAR_SERIES:
span_days = float(t[have][-1] - t[have][0]) / 86400.0 if have.any() else 0.0
if linear if linear is not None else (series in LINEAR_SERIES and span_days >= LINEAR_MIN_DAYS):
params["linear_tree"] = True
cat = [c for c in CATEGORICAL if c in names]
ds = lgb.Dataset(X[have], y[have], feature_name=names, categorical_feature=cat or "auto",
weight=None if weights is None else np.asarray(weights, dtype=float)[have])
weight=None if weights is None else np.asarray(weights, dtype=float)[have],
init_score=None if base is None else np.asarray(base, dtype=float)[have])
m = lgb.train(params, ds, num_boost_round=GBM_ROUNDS)
out = {"kind": "gbm", "model": m.model_to_string(), "features": names, "how": how_p["values"], "tz": tz,
"cap_w": float(np.nanpercentile(y[have], 99.9)) * 1.2 if have.any() else None}
if "special" in names:
out["special_kept"] = kept
if "loss" in names and room and room.get("ua_w_per_k") and room.get("t_in_c") is not None:
out["room"] = {"ua_w_per_k": round(float(room["ua_w_per_k"]), 3), "t_in_c": round(float(room["t_in_c"]), 2)}
if "occ" in names and occ and len(occ) == 168:
out["occ"] = [round(float(x), 3) for x in occ]
if base is not None:
out["base"] = "teacher"
if params.get("linear_tree"):
out["linear"] = True
return out
@@ -410,23 +490,30 @@ def box_params(params: dict) -> dict:
def predict_gbm(params: dict, series: str, t: np.ndarray, w: Weather, lag7: np.ndarray,
phys: np.ndarray | None, lat: float | None = None, state: str | None = None) -> np.ndarray:
phys: np.ndarray | None, lat: float | None = None, state: str | None = None,
base: np.ndarray | None = None) -> np.ndarray:
tz = params.get("tz", "UTC")
names = params["features"]
if not isinstance(names, list) or any(n not in FEATURE_NAMES for n in names):
raise ValueError("gbm: features this code does not know")
X, names = features(series, t, w, {"values": params["how"]}, tz, lag7, phys, names, lat, state,
params.get("special_kept"))
params.get("special_kept"), params.get("room"), params.get("occ"))
p = np.asarray(_predictor(params).predict(X), dtype=float)
if params.get("base"): # trees on a base forecast (fit_gbm's base): the sum is the difference
if base is None:
raise ValueError("gbm: trained on a base forecast, none given")
p = np.asarray(base, dtype=float) + p
p = np.maximum(p, 0.0)
if params.get("cap_w"):
p = np.minimum(p, params["cap_w"])
if series in UPPER:
p = np.minimum(p, UPPER[series])
if series == "pv":
p = np.where(w.elev <= 0, 0.0, p) if not np.isnan(w.elev).all() else p
return p
FEATURE_NAMES = frozenset(LOAD_FEATURES) | frozenset(PV_FEATURES) | {"doy"}
FEATURE_NAMES = frozenset(LOAD_FEATURES) | frozenset(PV_FEATURES) | frozenset(HEAT_FEATURES) | frozenset(DHW_FEATURES) | {"doy"}
# ---- one entry point -----------------------------------------------------------
@@ -443,6 +530,12 @@ class Site:
azimuth: float = 180.0
pvgis_monthly: list | None = None # PVGIS's kWh per kWp per month (pvcalib.pvgis_monthly)
state: str | None = None # the German state (NW, BY, ...): carnival, school holidays; None: unknown
# the heat series (methods.md B13): the room model's UA (W/K) and the
# indoor temperature (°C) its loss uses, the occupancy's hour-of-week
# profile (168 shares); kept in a gbm's params when it is fitted
ua_w_per_k: float | None = None
t_in_c: float | None = None
occ_how: list | None = None
def phys_prior(t: np.ndarray, w: Weather, s: Site) -> np.ndarray | None:
@@ -454,15 +547,17 @@ def phys_prior(t: np.ndarray, w: Weather, s: Site) -> np.ndarray | None:
def fit(kind: str, series: str, t: np.ndarray, y: np.ndarray, w: Weather, s: Site,
hist_t: np.ndarray | None = None, hist_y: np.ndarray | None = None) -> dict | None:
hist_t: np.ndarray | None = None, hist_y: np.ndarray | None = None, base: np.ndarray | None = None) -> dict | None:
"""A model of this kind on (t, y), or None where the kind cannot be made
(too little data, PV physics without a location or weather). Recent
slots weigh more (recency_weights; pvcalib has its own)."""
if kind == "how":
return fit_how(t, y, s.tz, recency_weights(t)) if (~np.isnan(y)).any() else None
return fit_how(t, y, s.tz, recency_weights(t), digits(series)) if (~np.isnan(y)).any() else None
if kind == "gbm":
prior = phys_prior(t, w, s) if series == "pv" else None
return fit_gbm(series, t, y, w, s.tz, _lag7(t, y, hist_t, hist_y), prior, s.lat, s.state, recency_weights(t))
room = {"ua_w_per_k": s.ua_w_per_k, "t_in_c": s.t_in_c} if s.ua_w_per_k else None
return fit_gbm(series, t, y, w, s.tz, _lag7(t, y, hist_t, hist_y), prior, s.lat, s.state, recency_weights(t),
base=base, room=room, occ=s.occ_how)
if kind == "pvphys":
if series != "pv":
return None
@@ -478,7 +573,7 @@ def fit(kind: str, series: str, t: np.ndarray, y: np.ndarray, w: Weather, s: Sit
def predict(params: dict, series: str, t: np.ndarray, w: Weather, s: Site,
hist_t: np.ndarray | None = None, hist_y: np.ndarray | None = None) -> np.ndarray:
hist_t: np.ndarray | None = None, hist_y: np.ndarray | None = None, base: np.ndarray | None = None) -> np.ndarray:
"""The model's forecast per slot (W). hist_*: metered history before t
(the week-ago lag; NaN where unknown)."""
kind = params["kind"]
@@ -487,7 +582,7 @@ def predict(params: dict, series: str, t: np.ndarray, w: Weather, s: Site,
if kind == "gbm":
prior = phys_prior(t, w, s) if series == "pv" else None
nan = np.full(len(t), np.nan)
return predict_gbm(params, series, t, w, _lag7(t, nan, hist_t, hist_y), prior, s.lat, s.state)
return predict_gbm(params, series, t, w, _lag7(t, nan, hist_t, hist_y), prior, s.lat, s.state, base)
if kind == "pvphys":
ss = Site(s.tz, s.lat, s.lon, s.kwp, params.get("tilt", s.tilt), params.get("azimuth", s.azimuth), state=s.state)
prior = phys_prior(t, w, ss)
+2 -1
View File
@@ -154,7 +154,8 @@ class Guard:
tr.commanded[a.entity] = (now, a.value)
c = self.controls.get(a.control)
boiler = c is not None and c.kind in ("heating", "cooling") and a.channel == "switch"
tr.changed["set" if a.quantity or boiler else "mode"] = now
# a hybrid's heat source: its own hold (steady.py _hold_source)
tr.changed["source" if a.channel == "source" else "set" if a.quantity or boiler else "mode"] = now
if a.domain == "cover":
tr.moved = now
if a.quantity == "":
+19
View File
@@ -424,4 +424,23 @@ MESSAGES = {
'heat delivered (thermal)': 'gelieferte Wärme (thermisch)',
'heat energy (thermal)': 'Wärmemenge (thermisch)',
'heat {v} (thermal)': 'Wärme {v} (thermisch)',
# remote Home Assistant for Cantabile support (devpage.py)
"Cantabile support has this Home Assistant open": "Der Cantabile-Support hat dieses Home Assistant geöffnet",
"Cantabile support": "Cantabile-Support",
("({who}, for {n} minute), signed in as the user \"Cantabile support\". Everything they do is recorded.",
"({who}, for {n} minutes), signed in as the user \"Cantabile support\". Everything they do is recorded."):
("({who}, seit {n} Minute), angemeldet als Benutzer „Cantabile support“. Alles, was er tut, wird aufgezeichnet.",
"({who}, seit {n} Minuten), angemeldet als Benutzer „Cantabile support“. Alles, was er tut, wird aufgezeichnet."),
"End now": "Jetzt beenden",
"Ended. Cantabile support's session is closed and the user \"Cantabile support\" is disabled again (a few seconds).":
"Beendet. Die Sitzung des Cantabile-Supports ist geschlossen und der Benutzer „Cantabile support“ wieder "
"deaktiviert (in wenigen Sekunden).",
"No session to end, or Cantabile's connection is not running.":
"Keine Sitzung zu beenden, oder Cantabiles Verbindung läuft nicht.",
"Reading and control are the owner's to switch on.": "Auslesen und Steuerung schaltet nur der Eigentümer ein.",
"Protection is the owner's to change.": "Den Schutz ändert nur der Eigentümer.",
"Heating or cooling is the owner's to choose.": "Heizen oder Kühlen wählt der Eigentümer.",
"The shade's room and window are the owner's to set.": "Raum und Fenster der Beschattung legt der Eigentümer fest.",
"Indoor or outdoor is the owner's to choose.": "Innen oder außen wählt der Eigentümer.",
"The weather forecast is the owner's to choose.": "Die Wettervorhersage wählt der Eigentümer.",
}
+255 -19
View File
@@ -3,8 +3,9 @@
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 model bundle's (its rooms), else
the defaults; sources.rooms says which per control.
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).
@@ -284,10 +285,11 @@ def device_state(c, col: Collector, now: float) -> dict:
e = c.entities
st = {}
if c.kind == "battery":
soc = col.value(e.get("soc", ""))
st["soc_pct"] = soc if soc is not None else float(c.p("soc_pct"))
st["soc_estimated"] = soc is None
# 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"):
@@ -298,6 +300,12 @@ def device_state(c, col: Collector, now: float) -> dict:
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
@@ -317,6 +325,105 @@ def device_state(c, col: Collector, now: float) -> dict:
return st
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
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 [])}
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) -> 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 ""))
if src in ("boiler", "hybrid") 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}
SET_POSITION = 4 # HA's CoverEntityFeature.SET_POSITION
@@ -350,6 +457,12 @@ def model_state(now: float, controls, inputs, col: Collector, bundles, history,
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
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
@@ -431,7 +544,11 @@ def model_state(now: float, controls, inputs, col: Collector, bundles, history,
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)
devices, rooms_src, phases_src = [], {}, {}
devices, rooms_src, phases_src, refused, battery_src, heat_src = [], {}, {}, {}, {}, {}
# 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 = {}, {}, []
one_room = sum(c.kind in ("heating", "cooling") for c in controls) == 1
for c in controls:
if hasattr(c, "learn_range"):
@@ -448,26 +565,87 @@ def model_state(now: float, controls, inputs, col: Collector, bundles, history,
{"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 in ("heating", "cooling"):
rooms_src[c.id] = _room_rc(c, params, bundles, one_room, now)
# 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
# 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
"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)]
if c.kind == "heating":
nos.append(heating_refusal(c, params, price_gas, price_heat, getattr(prices, "status", "tariff"),
box_params))
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 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)
battery_src[c.id] = fsrc
# 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]
devices.append({"id": c.id, "kind": c.kind, "params": params,
"state": device_state(c, col, now), "bounds": bounds,
"state": st, "bounds": bounds,
"channels": sorted(c.writable())})
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)
out = {"v": 1, "start": start, "step_s": STEP_S, "steps": STEPS, "tz": tz,
"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,
# 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,
"ghi_w_m2": ghi, "location": location or {},
"sources": {"load": load_src, "pv": pv_src, "t_out": t_src, "model": bundles.model_id(),
"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,
**({"battery": battery_src} if battery_src else {}),
**({"heating": heat_src} if heat_src else {}),
**({"intraday": intraday} if intraday 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 []}
if grid_max_w:
@@ -508,12 +686,21 @@ def irradiance(start: int, location: dict | None, sky: list[float],
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, else the
model's room (bundles.room_rc), else the defaults. A room fitted against
the electric power: C * cop and R / cop (the same RC; the optimiser's
heat is cop * P). Into params; where they came from."""
if "r_k_per_kw" in c.params or "c_kwh_per_k" in c.params:
return "mapping"
"""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 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
@@ -522,12 +709,17 @@ def _room_rc(c, params: dict, bundles, only_one: bool, now: float) -> str:
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 "defaults"
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
cop = number(params.get("cop")) or 1.0
if rc.get("power") == "electric" and cop > 0:
# fitted in electric equivalents: the heat is cop times (like C)
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
@@ -538,7 +730,51 @@ def _room_rc(c, params: dict, bundles, only_one: bool, now: float) -> str:
params["internal_gain_w"] = gain
if "solar_m2" not in c.params:
params["solar_m2"] = solar
return src
return src, ("electric" if rc.get("power") == "electric" else "thermal")
def room_refusal(c, st: dict, rc: str, power: str, source: str = "electric") -> 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") and power != "electric" and "cop" not in c.params:
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]:
+18 -1
View File
@@ -64,13 +64,29 @@ def battery_ratings(controls) -> dict:
if "capacity_wh" in c.params:
kwh += float(c.params["capacity_wh"]) / 1000
if "max_charge_w" in c.params or "max_discharge_w" in c.params:
kw += max(float(c.p("max_charge_w")), float(c.p("max_discharge_w"))) / 1000
kw += max(float(c.params.get("max_charge_w") or 0), float(c.params.get("max_discharge_w") or 0)) / 1000
out = {"battery_kwh": round(kwh, 3)} if kwh > 0 else {}
if out and kw > 0:
out["battery_kw"] = round(kw, 3)
return out
def heating_ratings(controls) -> dict:
"""A heating control's boiler efficiency as its mapping states it
(params boiler_efficiency, 0-1; controls.heat_facts' first source):
the cloud's gas forecast divides the heat forecast by it (methods.md
B14). Never a default."""
for c in controls:
if c.kind == "heating" and "boiler_efficiency" in c.params:
try:
v = float(c.params["boiler_efficiency"])
except (TypeError, ValueError):
continue
if 0 < v <= 1:
return {"boiler_efficiency": round(v, 4)}
return {}
def build(mapping, registries: dict, specs: dict, policy: dict, now: float, ev_phases: dict | None = None) -> dict:
"""ev_phases: per EV control its phase count and source (evphases.py),
told on the device of the control ("1 phase, learned" in the console)."""
@@ -129,6 +145,7 @@ def build(mapping, registries: dict, specs: dict, policy: dict, now: float, ev_p
hd = devs.get(d) or {}
mine = {control_of[e] for e in eids if e in control_of}
ratings = battery_ratings([controls[i] for i in sorted(mine - rated)])
ratings.update(heating_ratings([controls[i] for i in sorted(mine - rated)]))
rated |= mine
if not d and not ratings:
continue # entities without a device: nothing to tell but a battery's ratings
+12 -9
View File
@@ -40,11 +40,13 @@ from . import fcmodels, pvcalib, pvforecast
log = logging.getLogger(__name__)
SLOT_S = 900
SERIES = {"load_w": "load", "pv_w": "pv", "base_load_w": "base_load"} # the bundle's names: fcmodels'
SERIES = {"load_w": "load", "pv_w": "pv", "base_load_w": "base_load", # the bundle's names: fcmodels'
# the carriers' (methods.md B13-B16): the box carries their models, it plans on none of them yet
"heat_w": "heat", "dhw_w": "dhw", "occupancy": "occupancy", "ev_plug": "ev_plug"}
# the agent's history (inputs.History) a series' lag comes from: its load_w
# is the base load already (the house without the planned devices), which
# is the load where the box plans none (the only case its load_w is used)
HISTORY = {"load_w": "load_w", "base_load_w": "load_w", "pv_w": "pv_w"}
HISTORY = {"load_w": "load_w", "base_load_w": "load_w", "pv_w": "pv_w"} # the carriers': none kept (no lag)
SITE_FIELDS = {"tz": str, "lat": float, "lon": float, "kwp": float, "tilt": float, "azimuth": float, "state": str}
@@ -62,7 +64,7 @@ class Model:
def __init__(self, name: str, d: dict):
if name not in SERIES or not isinstance(d, dict) or not isinstance(d.get("params"), dict):
raise ValueError("a model: {params, site} for load_w, pv_w or base_load_w")
raise ValueError("a model: {params, site} for " + ", ".join(SERIES))
self.name, self.series = name, SERIES[name]
p, s = dict(d["params"]), d.get("site") or {}
if not isinstance(s, dict):
@@ -88,9 +90,10 @@ class Model:
elif self.kind == "gbm":
# the features it was trained with: today's, or those before the
# special days and the yearly rhythm (fcmodels.FEATURES_V1)
key = "pv" if self.series == "pv" else "load"
want = fcmodels.PV_FEATURES if key == "pv" else fcmodels.LOAD_FEATURES
if p.get("features") not in (want, fcmodels.FEATURES_V1[key]) or not _numbers(p.get("how"), 168) \
want = fcmodels.feature_names(self.series)
v1 = fcmodels.FEATURES_V1.get("pv" if self.series == "pv" else "load") if self.series in ("load", "base_load", "pv") \
else None
if p.get("features") not in (want, v1) or not _numbers(p.get("how"), 168) \
or "model" in p or not all(isinstance(k, int) for k in p.get("special_kept") or []):
raise ValueError(f"gbm: the features {', '.join(want)}, 168 hour-of-week values, trees")
if p.get("cap_w") is not None and not _num(p["cap_w"]):
@@ -148,12 +151,12 @@ def ha_hours(forecast: list[dict] | None) -> list:
def cloud_hours(recs) -> list:
"""The bundle's "weather": [{"end", "solar", "cloud", "temp"}]."""
"""The bundle's "weather": [{"end", "solar", "cloud", "temp", "wind"}]."""
out = []
for r in recs if isinstance(recs, list) else []:
if not isinstance(r, dict) or not isinstance(r.get("end"), int) or r["end"] % 3600:
continue
v = [float(r[k]) if _num(r.get(k)) else None for k in ("solar", "cloud", "temp")]
v = [float(r[k]) if _num(r.get(k)) else None for k in ("solar", "cloud", "temp", "wind")]
out.append(pvforecast.Hour(datetime.fromtimestamp(r["end"], timezone.utc), *v))
return out
@@ -211,7 +214,7 @@ def predict(model: Model, t: list[int], history, ha_forecast: list[dict] | None,
covered = [((ts // 3600 + 1) * 3600) in src for ts in t]
s = model.site
w = fcmodels.weather(ta, hours, s.lat, s.lon)
ht, hy = _history(history, HISTORY[model.name], int(ta[0]) - 7 * 86400, int(ta[0]))
ht, hy = _history(history, HISTORY.get(model.name, ""), int(ta[0]) - 7 * 86400, int(ta[0]))
p = fcmodels.predict(model.params, model.series, ta, w, s, ht, hy) if any(covered) else np.full(len(t), np.nan)
clim = model.climate(ta) if not all(covered) else None
out: list[float | None] = []
+505 -58
View File
@@ -6,7 +6,29 @@ every 15 minutes in a subprocess with a time limit (controller.py):
Objective: the grid's cost (the tariff's import and export prices) plus
penalties for comfort the plan gives up and for the floors and limits it
would cross. Floors and limits are soft here, with a penalty far above any
would cross.
Prices (docs/parameters.md U1; no price is ever made up):
- no tariff (none received, expired, none for now: state["prices"]
status "none"): the plan is made without prices, for comfort, the
limits and the owner's musts only. The meter's energy and the devices'
energy carry a tiny engineering weight (NO_PRICE_EUR_KWH: of plans
otherwise equal, the one that moves the least energy), so nothing is
shifted, pre-heated, stored or exported for a price; the battery stays
in its own mode unless a reserve the owner set needs charging; the
market's contracts are not planned (nothing to compare them with).
The plan's cost and baseline are None and its price_note says why.
- a tariff that prices only the first n steps (beyond its end, or a gap):
the plan covers those n steps only (_cut), never a step without a
price as if it were free.
- a step without an export price: export is unpriced there, it carries
no value (neither earned nor charged, coefficient 0) - not "0 ct" as a
fact: the plan exports what it cannot use, but never discharges a
battery or plans anything to export, and the meter's import/export
switch treats it as worth nothing. Curtailing (spill) has its own small
engineering cost (SPILL_EUR_KWH), so PV is never curtailed while the
meter can take it, whatever export is worth; a negative export price
(a real one) still curtails. Floors and limits are soft here, with a penalty far above any
price, so there is always a plan (a room already below its floor must be
able to come back); the executor's guard enforces them hard on every action.
@@ -19,7 +41,13 @@ Device models (one function each, small and replaceable):
(internal_gain_w, solar_m2 x the irradiance; the sun's only
where the room has no cover in the plan, which carries it));
comfort target when occupied, setback/setup otherwise; a
switched boiler is on/off (binary)
switched boiler is on/off (binary). Only with its R and C (the
mapping's both, or a fit: never built-in defaults), its electric
power (max_power_w), its COP where the model needs it and its
temperature now; else the room is not planned (inputs.
room_refusal): its thermostat follows the owner's
or installer's schedule within the room's limits
(fallback_entries), else keeps its own setpoint
ev the energy needed by the departure time, between min and max
current (binary), only while connected
cover the share of the sun's heat into its room (0 closed .. 1 open);
@@ -28,6 +56,22 @@ Device models (one function each, small and replaceable):
season, quiet hours) its positions are fixed to it and its plan
entries are the schedule's moves
Heat by its source (docs/methods.md E6; params.heat_source, the prices
state["price_gas"] and state["price_heat"] per step, fleet heatprice.go):
electric / heat_pump electric W through the meter at the import price; heat
= COP x W (params cop, or cop_curve at the step's
outside temperature)
boiler gas W (billed, Hs) at the gas price; heat = the
boiler's efficiency x W; up to max_heat_w of heat
district heat W at the heat price; up to max_heat_w
hybrid both, one at a time (a binary per step: the heat pump
or the boiler), each change of source costing the
Parameters page's heat.hybrid_switch_eur (state
"params", from the tariff bundle: no flapping)
The plan's cost then counts gas and heat too (gas_eur, heat_eur). A control
whose price or facts are missing never reaches the plan (inputs.py
heating_refusal: refused with the reason).
The grid operator's limit (gridorder.py, state["grid_order"]: §14a through
the EEBUS bridge): the controllable consumers may draw at most
limit_w from the grid beyond the household's own net load, i.e. the import
@@ -70,7 +114,7 @@ from zoneinfo import ZoneInfo
import highspy
from highspy.highs import highs_linear_expression as Lin
from .controls import ev_volts
from .controls import cop_at, ev_volts
from .evphases import words as phase_words
PENALTY_LIMIT = 5.0 # EUR per unit and step across a floor or limit (K, % of a battery, kWh)
@@ -91,6 +135,10 @@ CHANGE_EUR_KW = 0.002 # EUR per kW a device's power changes from one step to
# boiler must not be switched back and forth)
CLOSED_EUR = 0.00002 # EUR per step for a closed cover: open when nothing is at stake
MARKET_MAX_W = 100000.0 # W: a contract without a maximum, and the meter's import/export switch
NO_PRICE_EUR_KWH = 1e-4 # EUR per kWh through the meter and per kWh a device uses, without a tariff
# only (ENG: a tie-break toward the least energy, not a price)
SPILL_EUR_KWH = 1e-3 # EUR per kWh of PV curtailed (ENG: never curtail while the meter takes it;
# above NO_PRICE_EUR_KWH so export wins over spill without a tariff)
GRID_MAX_W = 43470.0 # W: the site's connection when the state does not say (state["grid_max_w"],
# config grid_max_w): a German house connection's usual 63 A main fuse,
# 3 x 230 V x 63 A
@@ -105,6 +153,11 @@ class Model:
self.flows = [[] for _ in range(self.T)] # (+1 into the house's balance | -1 out of it, var)
self.cost = [] # (coef, var)
self.devices = {} # id -> (kind, vars for the plan)
# False: no tariff, no prices (_prepare); a state not prepared: priced
# where it has a tariff and an import price for every step
self.priced = s["priced"] if "priced" in s else (
(s.get("prices") or {}).get("status", "tariff") != "none" and
all(v is not None for v in (s.get("price_import") or [None])[:self.T]))
def var(self, lo=0.0, hi=highspy.kHighsInf, cost=0.0, integer=False):
v = self.h.addVariable(lb=lo, ub=hi, type=highspy.HighsVarType.kInteger if integer else
@@ -121,9 +174,17 @@ class Model:
self.h.addConstr(d - b + a >= 0)
self.h.addConstr(d + b - a >= 0)
def eur_wh(self, t: int, price_ct: float) -> float:
"""EUR for one W held for one step at this price."""
return self.dt / 1000.0 * price_ct / 100.0
def eur_wh(self, t: int, price_ct: float | None) -> float:
"""EUR for one W held for one step at this price (None: no price, 0)."""
return 0.0 if price_ct is None else self.dt / 1000.0 * price_ct / 100.0
def use_cost(self, t: int = 0) -> float:
"""Without a tariff: a device's energy's tie-break weight per W and
step (NO_PRICE_EUR_KWH; rising a little over the horizon, so of
equal plans the earlier wins); with one 0 (its prices count)."""
if self.priced:
return 0.0
return self.dt / 1000.0 * NO_PRICE_EUR_KWH * (1.0 + t / max(1, self.T))
# -- the house -------------------------------------------------------
def grid(self):
@@ -143,9 +204,14 @@ class Model:
for t in range(self.T):
net = s["load_w"][t] - s["pv_w"][t]
hi_in, hi_out = max(cap, net), max(cap, -net)
gi = self.var(0.0, hi_in, cost=self.eur_wh(t, s["price_import"][t]))
go = self.var(0.0, hi_out, cost=-self.eur_wh(t, s["price_export"][t]))
spill = self.var(0.0, max(0.0, s["pv_w"][t]))
if self.priced:
gi = self.var(0.0, hi_in, cost=self.eur_wh(t, s["price_import"][t]))
# an unpriced export (None) carries no value: coefficient 0
go = self.var(0.0, hi_out, cost=-self.eur_wh(t, s["price_export"][t]))
else:
gi = self.var(0.0, hi_in, cost=self.dt / 1000.0 * NO_PRICE_EUR_KWH)
go = self.var(0.0, hi_out, cost=self.dt / 1000.0 * NO_PRICE_EUR_KWH)
spill = self.var(0.0, max(0.0, s["pv_w"][t]), cost=self.dt / 1000.0 * SPILL_EUR_KWH)
self.gin.append(gi)
self.gout.append(go)
self.gcap.append((hi_in, hi_out))
@@ -155,8 +221,11 @@ class Model:
"""The meter's import/export switch where the feed-in pays at least
the import price (grid), outside the steps in skip (market's own)."""
s = self.s
if not self.priced:
return # both carry the same tiny weight: doing both never pays
for t in range(self.T):
if t in skip or s["price_export"][t] < s["price_import"][t]:
pe = s["price_export"][t] if s["price_export"][t] is not None else 0.0 # unpriced: worth nothing
if t in skip or pe < s["price_import"][t]:
continue
hi_in, hi_out = self.gcap[t]
imp = self.var(0.0, 1.0, integer=True)
@@ -261,7 +330,7 @@ class Model:
max_ch = max(0.0, min(float(p["max_charge_w"]), phi))
max_dis = max(0.0, min(float(p["max_discharge_w"]), -plo))
soc0 = cap * min(max(float(st["soc_pct"]), 0.0), 100.0) / 100.0
mean_price = sum(self.s["price_import"]) / self.T
mean_price = sum(self.s["price_import"]) / self.T if self.priced else None
soc, prev, ch, dis = [], soc0, [], []
pref = d.get("pref") # the owner's reserve per step (preferences.py)
floors = []
@@ -270,8 +339,8 @@ class Model:
if pref and not (pref.get("off") is not None and pref["group"][t] == pref["off"]):
lo_t = min(max(lo_pct, pref["floor_pct"][t]), hi_pct)
floors.append(lo_t)
c = self.var(0.0, max_ch)
x = self.var(0.0, max_dis)
c = self.var(0.0, max_ch, cost=self.use_cost(t))
x = self.var(0.0, max_dis, cost=self.use_cost(t))
z = self.var(0.0, 1.0, integer=True)
self.h.addConstr(c - max_ch * z <= 0)
self.h.addConstr(x + max_dis * z <= max_dis)
@@ -286,17 +355,24 @@ class Model:
ch.append(c)
dis.append(x)
prev = e
# energy left at the end is worth the mean price: no draining at the horizon
short = self.var(cost=mean_price / 100.0 / 1000.0)
self.h.addConstr(prev + short >= min(soc0, hi_pct / 100.0 * cap))
# energy left at the end is worth the mean price: no draining at the
# horizon (without a tariff nothing is drained for a price anyway)
if mean_price is not None:
short = self.var(cost=mean_price / 100.0 / 1000.0)
self.h.addConstr(prev + short >= min(soc0, hi_pct / 100.0 * cap))
self.smooth([c - x for c, x in zip(ch, dis)])
self.devices[d["id"]] = ("battery", {"ch": ch, "dis": dis, "soc": soc, "cap": cap, "max_dis": max_dis,
"floor_wh": lo_pct / 100.0 * cap, "floors": floors})
"floor_wh": lo_pct / 100.0 * cap, "floors": floors,
"max_ch": max_ch, "eff": eff, "soc0": soc0, "hi_wh": hi_pct / 100.0 * cap})
def room(self, d, cooling: bool, gains):
p, st, b = d["params"], d["state"], d["bounds"]
r, c = float(p["r_k_per_kw"]), float(p["c_kwh_per_k"])
pmax, cop = float(p["max_power_w"]), float(p["cop"])
# the device's electric power and COP: facts (inputs.room_refusal / heating_refusal left out
# a room without them); a boiler or a heat station draws no electricity in the plan
elec = cooling or str(p.get("heat_source") or "electric") in ("electric", "heat_pump", "hybrid")
pmax = float(p["max_power_w"]) if elec else 0.0
cop = float(p["cop"]) if p.get("cop") is not None else 0.0 # 0: none (a curve alone, or no electricity)
lo, hi = b["temp_c"][0], b["temp_c"][1]
comfort = float(p["comfort_c"])
other = float(p["setup_c"] if cooling else p["setback_c"])
@@ -304,6 +380,21 @@ class Model:
t0 = float(t0) if t0 is not None else comfort
switched = not cooling and "switch" in d["channels"] and "climate" not in d["channels"]
temps, powers, prev = [], [], t0
band = [] # per step the owner's band (the shift envelope's: shift_envelope)
# what makes the heat (module docstring; inputs.py refused it where a price or fact is missing)
src = "electric" if cooling else str(p.get("heat_source") or "electric")
# facts and parameters, never defaults: inputs.heating_refusal left out a control without them
eff = float(p["boiler_efficiency"]) if src in ("boiler", "hybrid") else None
qmax = float(p["max_heat_w"]) if src in ("boiler", "hybrid", "district") else 0.0
gmax = qmax / eff if eff else 0.0
switch_eur = float((self.s.get("params") or {})["heat.hybrid_switch_eur"]) if src == "hybrid" else 0.0
gas = self.s.get("price_gas") or [None] * self.T
dhp = self.s.get("price_heat") or [None] * self.T
t_out = self.s["t_out"]
cops = [cop_at(p, t_out[t]) if p.get("cop_curve") else cop for t in range(self.T)]
els, gss, dhs, prev_u = [], [], [], None
if src == "hybrid" and st.get("source") in ("heat_pump", "boiler"):
prev_u = 1.0 if st["source"] == "heat_pump" else 0.0 # the source now: a change from it counts
a = self.dt / (r * c)
internal = self.hourly(p.get("internal_gain_w") or 0.0)
solar = float(p.get("solar_m2") or 0.0)
@@ -311,21 +402,52 @@ class Model:
pref = d.get("pref") # the owner's schedule and overrides (preferences.py)
cap = (self.s.get("building") or {}).get("thermostat_cap")
for t in range(self.T):
if switched:
u = self.var(0.0, 1.0, integer=True)
pw = self.var(0.0, pmax)
self.h.addConstr(pw - pmax * u == 0)
else:
pw = self.var(0.0, pmax)
self.flows[t].append((-1, pw))
terms = [] # (W of heat per W of input, the input)
pw = pg = ph = None
if src in ("electric", "heat_pump", "hybrid"):
if switched and src != "hybrid":
u = self.var(0.0, 1.0, integer=True)
pw = self.var(0.0, pmax, cost=self.use_cost(t))
self.h.addConstr(pw - pmax * u == 0)
else:
pw = self.var(0.0, pmax, cost=self.use_cost(t))
self.flows[t].append((-1, pw))
terms.append((cops[t], pw))
if src in ("boiler", "hybrid"):
cost = self.eur_wh(t, gas[t]) # the gas price per W of gas for the step
if switched and src == "boiler":
u = self.var(0.0, 1.0, integer=True)
pg = self.var(0.0, gmax, cost=cost)
self.h.addConstr(pg - gmax * u == 0)
else:
pg = self.var(0.0, gmax, cost=cost)
terms.append((eff, pg))
if src == "district":
ph = self.var(0.0, qmax, cost=self.eur_wh(t, dhp[t]))
terms.append((1.0, ph))
if src == "hybrid":
hu = self.var(0.0, 1.0, integer=True) # 1: the heat pump, 0: the boiler
self.h.addConstr(pw - pmax * hu <= 0)
self.h.addConstr(pg + gmax * hu <= gmax)
if prev_u is not None:
sw = self.var(cost=switch_eur)
self.h.addConstr(sw - hu + prev_u >= 0)
self.h.addConstr(sw + hu - prev_u >= 0)
prev_u = hu
els.append(pw)
gss.append(pg)
dhs.append(ph)
heat = sum((k * v for k, v in terms), start=Lin())
main = pw if pw is not None else pg if pg is not None else ph
tt = self.var(-50.0, 80.0)
sign = -1.0 if cooling else 1.0
covers = gains(t)
gain = sum((g * gx for g, gx in covers), start=Lin())
# the fit's (B6): its internal gain, and its sun where no cover carries it
fixed = internal[t] + (solar * ghi[t] if not covers and t < len(ghi) else 0.0)
# T[t+1] = T[t] (1 - a) + a T_out + dt/C (± cop P/1000 + sun gain/1000 + fixed gains/1000)
self.h.addConstr(tt - (1 - a) * prev - sign * self.dt / c * cop / 1000.0 * pw
# T[t+1] = T[t] (1 - a) + a T_out + dt/C (± heat/1000 + sun gain/1000 + fixed gains/1000);
# heat: COP x electric W, efficiency x gas W, district W (module docstring)
self.h.addConstr(tt - (1 - a) * prev - sign * self.dt / c / 1000.0 * heat
- self.dt / c / 1000.0 * gain == a * self.s["t_out"][t] + self.dt / c / 1000.0 * fixed)
occ = self.s["occupied"][t + 1] if t + 1 < self.T else self.s["occupied"][t]
want, must = (comfort if occ else other), None
@@ -335,6 +457,13 @@ class Model:
want, must = pref["base"][t], None # pref_costs: the plan without this group
target = min(max(want, lo), hi)
capped = bool(cap) and cap["from_step"] <= t < cap["to_step"]
# heating: from its target (and must) up to its upper bound (under a building's cap); cooling mirrored
if cooling:
b_hi = min(target, must) if must is not None else target
band.append((max(lo, cap["value"]) if capped else lo, max(min(b_hi, hi), lo)))
else:
b_lo = max(target, must) if must is not None else target
band.append((min(max(b_lo, lo), hi), min(hi, cap["value"]) if capped else hi))
if must is not None:
# a bound inside the bounds in force, and under a building's cap
mv = min(max(must, lo), hi)
@@ -361,11 +490,19 @@ class Model:
else:
self.h.addConstr(tt - miss_cap <= cap["value"]) # heating: not above it
temps.append(tt)
powers.append(pw)
powers.append(main)
prev = tt
self.smooth(powers)
self.smooth(powers if src != "hybrid" else [a_ + b_ for a_, b_ in zip(els, gss)])
# power: the electric input (None for gas and district heat: no electricity to shed or price);
# gas, district: their inputs; heat: per step the heat terms
self.devices[d["id"]] = ("cooling" if cooling else "heating",
{"temp": temps, "power": powers, "pmax": pmax, "switched": switched})
{"temp": temps, "power": els, "gas": gss, "district": dhs, "src": src,
"cops": cops, "eff": eff,
"pmax": {"electric": pmax, "heat_pump": pmax, "hybrid": pmax, "boiler": gmax,
"district": qmax}[src], "switched": switched,
# the shift envelope (electric sources only): Wh of electricity per K at the mean COP
"keep": 1 - a, "wh_per_k": 1000.0 * c / (sum(cops) / len(cops)) if cops and min(cops) > 0 else 0.0,
"band": band})
def hourly(self, v) -> list[float]:
"""A number, or 24 by local hour, per step."""
@@ -397,7 +534,7 @@ class Model:
powers.append(None)
continue
y = self.var(0.0, 1.0, integer=True)
pw = self.var(0.0, imax * volts)
pw = self.var(0.0, imax * volts, cost=self.use_cost(t))
self.h.addConstr(pw - imax * volts * y <= 0)
self.h.addConstr(pw - imin * volts * y >= 0)
self.flows[t].append((-1, pw))
@@ -417,7 +554,9 @@ class Model:
self.h.addConstr(total + short >= need)
self.smooth([p for p in powers if p is not None])
self.devices[d["id"]] = ("ev", {"power": powers, "volts": volts, "dep": dep,
"pmax": imax * volts if imax >= imin else 0.0})
"pmax": imax * volts if imax >= imin else 0.0, "need": need,
# the ready-by and the energy known (shift_envelope): not the defaults
"known": ev_known(st, pref)})
def cover(self, d, room_ids):
p, b = d["params"], d["bounds"]
@@ -488,6 +627,19 @@ class Model:
return self.h.modelStatusToString(status)
def ev_known(st: dict, pref: dict | None) -> bool:
"""A car's ready-by and energy are facts: the ready-by the owner's
preference or the car's (its charger's departure entity), the energy
the car's (energy-needed entity) or the owner's (kWh, or % with the
car's state of charge and capacity). The mapping's defaults (need_wh,
departure) are not; a preference in % without the car's charge falls
back to them (preferences.py), so it is not either."""
dep = bool(pref) or st.get("departure") is not None
need = st.get("need_wh") is not None or bool(pref) and (
pref.get("kwh") is not None or (pref.get("soc_pct") is not None and bool(pref.get("capacity_wh"))))
return dep and need
def departure_step(s: dict, hhmm: str) -> int:
"""The step of the next departure (local time), within the horizon."""
zone = ZoneInfo(s.get("tz") or "UTC")
@@ -503,8 +655,55 @@ def _round(v: float, step: float) -> float:
return round(v / step) * step
def _prepare(s: dict) -> dict:
"""The state as the plan takes it (U1): without a tariff (status none,
or no import price for the first step) priced False and no market; a
tariff that prices only the first n steps: the horizon cut to them."""
pi = s.get("price_import") or []
status = (s.get("prices") or {}).get("status", "tariff")
# gas and heat: a boiler's or district heat's steps only while their price lasts
n = s["steps"]
srcs = {str((d.get("params") or {}).get("heat_source") or "electric") for d in s.get("devices") or [] if d["kind"] == "heating"}
for key, need in (("price_gas", {"boiler", "hybrid"}), ("price_heat", {"district"})):
xs = s.get(key) or []
if srcs & need and xs:
n = min(n, next((k for k, v in enumerate(xs) if v is None), len(xs)))
if n == 0:
n = s["steps"] # refused upstream (inputs.heating_refusal): nothing to cut for
if status == "none" or not pi or pi[0] is None:
s = dict(s, priced=False, market=[])
return _cut(s, n) if n < s["steps"] else s
n = min(n, next((k for k, v in enumerate(pi) if v is None), len(pi)))
s = dict(s, priced=True)
return _cut(s, n) if n < s["steps"] else s
def _cut(s: dict, n: int) -> dict:
"""The state for its first n steps: every per-step list (any list of
the horizon's length, at any depth) cut to n, the step ranges (from_step,
to_step, dep_step) kept inside it (a car's ready-by beyond it: "beyond")."""
T = s["steps"]
def cut(x):
if isinstance(x, list):
return [cut(v) for v in (x[:n] if len(x) == T else x)]
if isinstance(x, dict):
y = {k: cut(v) for k, v in x.items()}
for k in ("from_step", "to_step"):
if isinstance(y.get(k), int):
y[k] = min(y[k], n)
if isinstance(y.get("dep_step"), int) and y["dep_step"] > n:
y["dep_step"], y["beyond"] = n, True
return y
return x
out = cut(s)
out["steps"] = n
return out
def plan(s: dict, time_limit: float = 30.0) -> dict:
t0 = time.time()
s = _prepare(s)
m = Model(s)
status = m.solve(time_limit)
val = m.h.getSolution().col_value
@@ -522,22 +721,46 @@ def plan(s: dict, time_limit: float = 30.0) -> dict:
devices[d["id"]] = entries
market = market_plan(s, m, x)
energy = energy_of(s, m, x, market)
heat_cost = carrier_costs(s, m, x)
if energy is not None:
energy += heat_cost["gas_eur"] + heat_cost["heat_eur"]
base = baseline(s, m, x)
out = {"v": 1, "made": int(time.time()), "start": start, "step_s": step, "status": status,
"solve_s": round(time.time() - t0, 2), "devices": devices, "flex": flexibility(m, x),
"cost_eur": round(energy, 2), "baseline_eur": round(baseline(s, m, x), 2),
# without a tariff no cost: None, never a cost at a made-up price
"cost_eur": round(energy, 2) if energy is not None else None,
"baseline_eur": round(base, 2) if base is not None else None,
"priced": m.priced, "steps": T, "price_state": s.get("prices") or {},
"price_note": s.get("price_note", ""), "sources": s.get("sources", {})}
if heat_cost["gas_eur"] or heat_cost["heat_eur"]:
out["gas_eur"], out["heat_eur"] = round(heat_cost["gas_eur"], 2), round(heat_cost["heat_eur"], 2)
# rooms not planned (inputs.room_refusal): the thermostat's
# fallback schedule, and which one in their refusal
refused = copy.deepcopy(s.get("refused") or {})
for d in s.get("fallback") or []:
entries = fallback_entries(s, d)
if entries:
devices[d["id"]] = entries
if d["id"] in refused:
refused[d["id"]]["fallback"] = ("schedule" if entries else
"own" if "climate" in d.get("channels", []) else "none")
if refused:
out["refused"] = refused # controls not planned, and why (U2, E6)
if market:
out["market"] = market
if any(d.get("pref") for d in s["devices"]):
out["prefs"] = pref_feedback(s, m, x)
if s.get("prefs_cost"):
if any(d.get("pref") for d in s["devices"]) or any(d.get("pref") for d in s.get("fallback") or []):
out["prefs"] = pref_feedback(s, m, x) + fallback_feedback(s)
if s.get("prefs_cost") and energy is not None:
out["prefs_cost"] = pref_costs(s, energy, t0 + time_limit)
return out
def energy_of(s, m, x, market=None) -> float:
"""The plan's cost for power (EUR): the grid's import less its feed-in,
and the market's contracts."""
"""The plan's cost for power (EUR): the grid's import less its feed-in
(an unpriced export counts nothing), and the market's contracts; None
without a tariff."""
if not m.priced:
return None
pi, pe = s["price_import"], s["price_export"]
e = sum(m.eur_wh(t, pi[t]) * x(m.gin[t]) - m.eur_wh(t, pe[t]) * x(m.gout[t]) for t in range(m.T))
return e + sum(c["cost_eur"] for c in (market if market is not None else market_plan(s, m, x)))
@@ -646,7 +869,7 @@ def _ev_feedback(s, d, pref, v, x, m) -> dict:
short = max(0.0, pref["need_wh"] - wh)
pi = s["price_import"]
f["planned_kwh"] = round(wh / 1000.0, 2)
f["charge_eur"] = round(sum(m.eur_wh(t, pi[t]) * pw[t] for t in range(dep)), 2)
f["charge_eur"] = round(sum(m.eur_wh(t, pi[t]) * pw[t] for t in range(dep)), 2) if m.priced else None
reached = ""
if pref.get("soc_pct") is not None and pref.get("capacity_wh"):
pct = min(100.0, float(pref["soc_pct"]) + 100.0 * wh / pref["capacity_wh"])
@@ -752,26 +975,34 @@ def market_plan(s, m, x) -> list[dict]:
vs += (e * pi[t] - pay * price) / 100.0
else:
cost -= e * price / 100.0
vs += e * (price - pe[t]) / 100.0
vs += e * (price - (pe[t] or 0.0)) / 100.0 # an unpriced export: worth nothing
out.append({"id": c["id"], "name": c.get("name", ""), "direction": c["direction"], "price_ct": c["price_ct"],
"steps": steps, "planned_kwh": round(kwh, 4), "paid_kwh": round(paid_kwh, 4),
"cost_eur": round(cost, 4), "vs_grid_eur": round(vs, 4)})
return out
FLEX_STEPS = 96 # 24 h at 15 min: what a building plans with
FLEX_STEPS = 96 # 24 h at 15 min: what a building plans with (shed_w, grid_w)
SHIFT_STEPS = 192 # 48 h: the shift envelope (the band prices' horizon)
SHIFT_DEVICES = 16 # devices in a shift envelope at most (the fleet's storage bound)
def flexibility(m, x) -> dict:
"""What the flat could do for its building (the building
asks for flexibility, it doesn't cap averages; building/README.md hole
3), per step for the next 24 h: grid_w, the planned import; shed_w, how
much of it the controllable devices (heating, cooling, EV, the battery's
charging) could drop in that step, plus what the battery could still
discharge (its spare power, bounded by the energy above its floor): what
a load_limit can take away without touching the household's own use."""
3), per step for the next 24 h: grid_w, the planned import through the
meter (the grid's and a market contract's: a flat supplied by its
building's pool imports through a contract, and its gin alone was 0, so
shed_w was 0 too: docs/methods.md A11); shed_w, how much of it the
controllable devices (heating, cooling, EV, the battery's charging)
could drop in that step, plus what the battery could still discharge
(its spare power, bounded by the energy above its floor): what a
load_limit can take away without touching the household's own use.
shift (48 h, shift_envelope): the energy the devices can move, for a
building's price bands; absent where no device's facts are known."""
n = min(m.T, FLEX_STEPS)
grid = [round(x(m.gin[t])) for t in range(n)]
bought = [x(m.gin[t]) + sum((x(v) for v in m.buy[t]), 0.0) for t in range(m.T)]
grid = [round(bought[t]) for t in range(n)]
shed = [0.0] * n
for kind, v in m.devices.values():
if v is None:
@@ -785,9 +1016,110 @@ def flexibility(m, x) -> dict:
for t in range(min(n, len(cols or []))):
if cols[t] is not None and hasattr(cols[t], "index"): # an EV's steps after departure are empty
shed[t] += max(x(cols[t]), 0.0)
# net_w: import less export, the member's draw as planned (the box's forecast of it upward, boxtrain.py)
return {"grid_w": grid, "shed_w": [round(min(sh, g)) for sh, g in zip(shed, grid)],
"net_w": [round(x(m.gin[t]) - x(m.gout[t])) for t in range(n)]}
out = {"grid_w": grid, "shed_w": [round(min(sh, g)) for sh, g in zip(shed, grid)],
"net_w": [round(bought[t] - x(m.gout[t]) - sum((x(v) for v in m.sell[t]), 0.0)) for t in range(n)]}
sh = shift_envelope(m, x)
if sh:
out["shift"] = sh
return out
def _x(x, v) -> float:
"""A step's value: a variable's, or 0 where there is none (an EV's steps after departure)."""
return x(v) if v is not None and hasattr(v, "index") else 0.0
def shift_envelope(m, x) -> dict | None:
"""The energy each controllable device can move over the next 48 h,
from what the plan already knows (docs/methods.md A11), for the
building's price bands (building/mieterstrom.py: the flats' agents
re-plan against the band prices; the building models that response
with this). Per device, per step (W, Wh; the step is step_s):
battery base_w (the planned grid-side power: charge > 0, discharge
< 0), soc_wh (the state of charge at the start), lo_wh per
step (its floor: the bounds and the owner's reserve), max_wh
(its ceiling), ch_w, dis_w (its power), eta (one way), end_wh (the planned
last state of charge: the building keeps at least it)
ev, heating, cooling
base_w (planned), up_w / down_w (the most it can draw above /
below base_w), lo_wh / hi_wh (the bounds of the moved energy
store S_t = keep * S_(t-1) + (p_t - base_t) * dt, S_(-1) = 0),
keep (1 a lossless store: a car; a room's heat decays toward
its plan: 1 - dt / (R C))
Published only from facts: a battery with its ratings (a battery
without them is not planned at all: U2); a car plugged in whose
ready-by and energy are the owner's preference or the car's own (never
the defaults); a room whose R and C are fitted (or the mapping's) with
the device's COP (the mapping's, or none needed: a fit against the
electric power) and the owner's band (preferences, or the mapping's
comfort temperatures); a room without them is not planned at all. None of them: None."""
s = m.s
n = min(m.T, SHIFT_STEPS)
if n <= 0:
return None
dt = m.dt
src = s.get("sources") or {}
rooms, cops, bands = src.get("rooms") or {}, src.get("rooms_cop") or {}, src.get("rooms_band") or {}
out = []
for d in s["devices"]:
kind, v = m.devices.get(d["id"], (d["kind"], None))
if v is None:
continue
if kind == "battery":
base = [_x(x, v["ch"][t]) - _x(x, v["dis"][t]) for t in range(n)]
out.append({"id": d["id"], "kind": "battery", "base_w": [round(b) for b in base],
"soc_wh": round(v["soc0"]), "lo_wh": [round(v["floors"][t] / 100.0 * v["cap"]) for t in range(n)],
"max_wh": round(v["hi_wh"]), "ch_w": round(v["max_ch"]), "dis_w": round(v["max_dis"]),
"eta": round(v["eff"], 4), "end_wh": round(_x(x, v["soc"][n - 1]))})
elif kind == "ev":
if not v.get("known") or v["pmax"] <= 0:
continue
p = [_x(x, v["power"][t]) for t in range(n)]
dep = min(v["dep"], n)
if dep <= 0 or sum(p) <= 0 and v["need"] <= 0:
continue
up = [max(0.0, v["pmax"] - p[t]) if t < dep else 0.0 for t in range(n)]
down = [p[t] if t < dep else 0.0 for t in range(n)]
lo, hi, cum = [], [], 0.0
for t in range(n):
cum += p[t] * dt
if t < dep - 1: # before the ready-by: between nothing and the need delivered
lo.append(-cum)
hi.append(max(0.0, v["need"] - cum))
else: # at and after it: what the plan delivers (a ready-by beyond the horizon: no less by its end)
end = v["need"] - cum
lo.append(min(0.0, end) if v["dep"] <= n else 0.0)
hi.append(max(0.0, end))
out.append({"id": d["id"], "kind": "ev", "base_w": [round(a) for a in p], "up_w": [round(a) for a in up],
"down_w": [round(a) for a in down], "lo_wh": [round(a) for a in lo], "hi_wh": [round(a) for a in hi],
"keep": 1.0})
elif kind in ("heating", "cooling"):
if v.get("switched"):
continue # an on/off boiler: all or nothing, not a band of power
if v.get("src", "electric") not in ("electric", "heat_pump"):
continue # gas, district heat or a hybrid's choice: no electricity to shift as planned
if rooms.get(d["id"]) not in ("mapping", "model", "box model") or \
cops.get(d["id"]) not in ("mapping", "electric fit", "electric heater") or v["wh_per_k"] <= 0:
continue # no fit or no COP: the heat it can hold is not known
if not d.get("pref") and bands.get(d["id"]) != "mapping":
continue # no band of the owner's
p = [_x(x, v["power"][t]) for t in range(n)]
temps = [_x(x, v["temp"][t]) for t in range(n)]
k, sign = v["wh_per_k"], (-1.0 if kind == "cooling" else 1.0)
lo, hi = [], []
for t in range(n):
blo, bhi = v["band"][t]
a, b = sorted((sign * (blo - temps[t]) * k, sign * (bhi - temps[t]) * k))
lo.append(min(a, 0.0)) # the plan's own temperature is always inside
hi.append(max(b, 0.0))
out.append({"id": d["id"], "kind": kind, "base_w": [round(a) for a in p],
"up_w": [round(max(0.0, v["pmax"] - a)) for a in p], "down_w": [round(a) for a in p],
"lo_wh": [round(a) for a in lo], "hi_wh": [round(a) for a in hi], "keep": round(v["keep"], 6)})
if not out:
return None
return {"v": 1, "start": s["start"], "step_s": s["step_s"], "steps": n, "devices": out[:SHIFT_DEVICES]}
def _charge_why(pi, t) -> str:
@@ -808,12 +1140,93 @@ def _charge_why(pi, t) -> str:
def _key(e) -> tuple:
"""What makes a plan entry a change: a battery's self-consumption is one
state whatever its power (it follows the house)."""
return ("auto",) if e.get("auto") else (e["set"], e.get("grid"))
state whatever its power (it follows the house); a hybrid's source."""
return ("auto",) if e.get("auto") else (e["set"], e.get("grid"), e.get("source"))
def carrier_costs(s, m, x) -> dict:
"""What the plan's gas and district heat cost (EUR), at their prices."""
gas, dh = s.get("price_gas") or [], s.get("price_heat") or []
out = {"gas_eur": 0.0, "heat_eur": 0.0}
for kind, v in m.devices.values():
if kind != "heating" or not v:
continue
for key, prices, col in (("gas_eur", gas, "gas"), ("heat_eur", dh, "district")):
for t, var in enumerate(v.get(col) or []):
if var is not None and t < len(prices) and prices[t] is not None:
out[key] += m.eur_wh(t, prices[t]) * x(var)
return out
def _inputs_w(v, t, x) -> float:
"""A heating or cooling device's input in step t (W: electric, gas or
district heat; a hybrid's both)."""
return sum(x(c[t]) for c in (v.get("power"), v.get("gas"), v.get("district")) if c and c[t] is not None)
GRID_ZERO_W = 50.0 # the meter's import and export below this: the battery balances the house
KEEP_OWN = "release" # executor.RELEASE: the thermostat keeps its own setpoint (nothing written)
def fallback_entries(s, d) -> list[dict]:
"""A room not planned (inputs.room_refusal): its
thermostat's fallback schedule, no optimisation. Per step the target of
the owner's (or installer's) schedule and overrides in force
(preferences.room_series: a block's temperature, a must at least it;
outside the blocks the setback (heating) / setup (cooling); a boost;
away at the setback), rounded to the half degree and held inside the
room's bounds (the owner's and installer's limits, the device's range).
Without blocks (an override alone) the steps outside the override keep
the thermostat's own setpoint (KEEP_OWN). No schedule, or a switched
heater without a thermostat: none (the executor's safe value: the
device as it is)."""
pref = d.get("pref")
if not pref or "climate" not in (d.get("channels") or []):
return []
cooling = d["kind"] == "cooling"
lo, hi = d["bounds"]["temp_c"][0], d["bounds"]["temp_c"][1]
lo_h = math.ceil(lo * 2) / 2 if lo is not None else None
hi_h = math.floor(hi * 2) / 2 if hi is not None else None
groups = pref["groups"]
blocks = any(g["kind"] == "block" for g in groups)
out = []
for t in range(min(s["steps"], len(pref["target"]))):
g = pref["group"][t]
if g == -1 and not blocks:
e = {"set": KEEP_OWN, "why": "fallback: the thermostat's own setpoint (room not optimised, no schedule)"}
else:
want = float(pref["target"][t])
must = pref["must"][t]
if must is not None:
want = min(want, float(must)) if cooling else max(want, float(must))
v = _round(want, 0.5)
if lo_h is not None:
v = max(v, lo_h)
if hi_h is not None:
v = min(v, hi_h)
what = groups[g]["text"] if g >= 0 else ("setup" if cooling else "setback") + " outside your schedule"
e = {"set": v, "why": f"fallback schedule (room not optimised): {what}"}
if not out or _key(out[-1]) != _key(e):
out.append({"t": s["start"] + t * s["step_s"], **e})
return out
def fallback_feedback(s) -> list[dict]:
"""A not-planned room's preferences (fallback_entries): not optimised,
the thermostat set to them; met unknown (no plan of the room to tell)."""
out = []
for d in s.get("fallback") or []:
pref = d.get("pref")
if not pref or "climate" not in (d.get("channels") or []):
continue
for gi, g in enumerate(pref["groups"]):
out.append({"control": d["id"], "group": g["group"], "kind": g["kind"], "how": g["how"],
"label": g["text"], "met": None,
"detail": "room not optimised: set as the thermostat's schedule"
if gi in pref["group"] else "not in the next 48 h"})
return out
def _entry(d, kind, v, t, x, s, pi, grid_w=(1e9, 1e9)):
"""What a device is to do in step t, and why (a few words). grid_w:
@@ -826,6 +1239,12 @@ def _entry(d, kind, v, t, x, s, pi, grid_w=(1e9, 1e9)):
net = _round(net, 50.0)
surplus = s["pv_w"][t] - s["load_w"][t]
grid = net > max(0.0, surplus) + 50
if not s.get("priced", True):
# no tariff: the battery in its own mode, unless the owner's
# reserve needs charging from the grid
if grid:
return {"set": net, "grid": True, "why": "charge to the reserve you set (no tariff)"}
return {"set": net, "grid": False, "auto": True, "why": "no tariff: the battery in its own mode"}
if net > 0:
why = _charge_why(pi, t) if grid else "PV surplus"
elif net < 0:
@@ -846,7 +1265,17 @@ def _entry(d, kind, v, t, x, s, pi, grid_w=(1e9, 1e9)):
return {"set": net, "grid": grid, "why": why}
if kind in ("heating", "cooling"):
temp = x(v["temp"][t])
pw = x(v["power"][t])
pw = _inputs_w(v, t, x)
src = v.get("src", "electric")
# the price that buys the heat now, for the words
pr = {"boiler": s.get("price_gas"), "district": s.get("price_heat")}.get(src) or pi
pr_t = pr[t] if t < len(pr) else None
source = None
if src == "hybrid":
hp_w, gas_w = x(v["power"][t]), x(v["gas"][t])
source = "heat_pump" if hp_w >= gas_w and hp_w > 50 else "boiler" if gas_w > 50 else None
if source == "boiler":
pr_t = (s.get("price_gas") or [None] * (t + 1))[t]
ahead = s["occupied"][min(t + 4, s["steps"] - 1)]
pref = d.get("pref")
if pref:
@@ -856,7 +1285,7 @@ def _entry(d, kind, v, t, x, s, pi, grid_w=(1e9, 1e9)):
tg, k0 = pref["target"], max(t - 1, 0)
occ = sign * (tg[k0] - pref["base"][k0]) > 0
ahead = any(sign * (tg[k] - tg[k0]) > 0 for k in range(t, min(t + 4, len(tg))))
if kind == "heating" and v["switched"]:
if kind == "heating" and v["switched"] and src != "hybrid":
on = pw > 0.5 * v["pmax"]
why = ("pre-heat before someone is home" if on and not occ and ahead else
"keep the room warm" if on else "off: warm enough or away")
@@ -885,8 +1314,13 @@ def _entry(d, kind, v, t, x, s, pi, grid_w=(1e9, 1e9)):
want = max(want, float(pref["must"][t]))
floor_t = min(max(math.floor(want * 2) / 2, math.ceil(lo * 2) / 2), math.floor(hi * 2) / 2)
return {"set": min(target, floor_t), "why": "setback: away or night" if not occ else "warm enough"}
return {"set": target, "why": f"pre-heat while power is cheap ({pi[t]:.1f} ct)" if not occ and ahead
else "keep the room warm"}
what = {"boiler": "gas", "district": "heat"}.get(src if src != "hybrid" else (source or ""), "power")
e = {"set": target, "why": f"pre-heat while {what} is cheap ({pr_t:.1f} ct)"
if not occ and ahead and pr_t is not None else "keep the room warm"}
if source:
e["source"] = source
e["why"] += "; " + ("the heat pump: its heat is cheaper now" if source == "heat_pump" else "the boiler: its heat is cheaper now")
return e
if kind == "ev":
p = v["power"][t]
if p is None:
@@ -894,6 +1328,10 @@ def _entry(d, kind, v, t, x, s, pi, grid_w=(1e9, 1e9)):
amps = round(x(p) / v["volts"])
ph = ((s.get("sources") or {}).get("ev_phases") or {}).get(d["id"])
ph = f"; {phase_words(ph)}" if ph else ""
if pi[t] is None:
if amps < 1:
return {"set": "off", "why": "not needed now (no tariff)" + ph}
return {"set": amps, "why": "charge for the departure (no tariff)" + ph}
if amps < 1:
return {"set": "off", "why": "wait for cheaper hours" + ph}
return {"set": amps, "why": f"cheapest hours before departure ({pi[t]:.1f} ct){ph}"}
@@ -918,7 +1356,10 @@ def _entry(d, kind, v, t, x, s, pi, grid_w=(1e9, 1e9)):
def baseline(s, m, x) -> float:
"""An estimate of the cost without the plan: the house's net load at its
prices, no battery, and the devices' energy (as the plan uses it) at the
mean import price, the EV's as soon as it is plugged in."""
mean import price, the EV's as soon as it is plugged in; None without
a tariff."""
if not m.priced:
return None
T, pi, pe = m.T, s["price_import"], s["price_export"]
cost = 0.0
for t in range(T):
@@ -929,7 +1370,13 @@ def baseline(s, m, x) -> float:
if not v:
continue
if kind in ("heating", "cooling"):
cost += sum(m.eur_wh(t, mean) * x(v["power"][t]) for t in range(T))
# each input as the plan uses it at its mean price (electricity, gas, district heat)
cost += sum(m.eur_wh(t, mean) * x(v["power"][t]) for t in range(T) if v["power"][t] is not None)
for col, key in (("gas", "price_gas"), ("district", "price_heat")):
ps = [p for p in (s.get(key) or [])[:T] if p is not None]
if ps and any(c is not None for c in v.get(col) or []):
mp = sum(ps) / len(ps)
cost += sum(m.eur_wh(t, mp) * x(c) for t, c in enumerate(v[col]) if c is not None)
elif kind == "ev":
wh = sum(m.dt * x(p) for p in v["power"] if p is not None)
asap = pi[:max(1, math.ceil(wh / max(1.0, v["volts"] * 16) / m.dt))]
+51 -2
View File
@@ -419,6 +419,13 @@ class Preferences:
self.costs: dict = {"at": 0, "of": 0.0, "eur_day": {}} # the musts' costs, as of a plan
self.feedback: list[dict] = []
self.errors: list[dict] = [] # the last refused changes (the panel shows them)
# the plan's state for the panel (docs/parameters.md U1, U2): planned with
# prices or not and why, the controls not planned and why
self.planning: dict = {}
# the owner's own tariff as on the bill, from the panel, for the cloud
# (the controller sends it through the link: op own_tariff) and its state
self.outbox: list[dict] = []
self.own_tariff: dict = {}
try:
with open(self.path) as f:
raw = json.load(f)
@@ -596,11 +603,42 @@ class Preferences:
os.remove(p)
except OSError:
pass
if isinstance(msg, dict):
if isinstance(msg, dict) and "own_tariff" in msg:
ok, why = self.take_own_tariff(msg)
log.info("own tariff from the panel: %s", why)
n += 1
elif isinstance(msg, dict):
self.apply_msg(msg, controls, tz, "owner", "panel:" + str(msg.get("by") or "owner")[:40])
n += 1
return n
def take_own_tariff(self, msg: dict) -> tuple[bool, str]:
"""The owner's own tariff as on the bill (the panel, when the box has
no tariff): {"own_tariff": {"import_ct", "export_ct"?, "valid_from"?},
"by"}: checked here, then sent to the cloud (outbox), which keeps it as
the site's own price (fleet site_tariffs) unless the site already has
a tariff chosen there, and sends the tariff bundle back. Gross ct/kWh."""
o = msg.get("own_tariff") or {}
now = int(self.clock())
def ct(v, lo, hi):
try:
x = float(v)
except (TypeError, ValueError):
return None
return x if lo <= x <= hi and x == x else None
imp = ct(o.get("import_ct"), 0.0, 1000.0)
exp = ct(o.get("export_ct"), -100.0, 1000.0) if o.get("export_ct") not in (None, "") else None
if imp is None or imp == 0:
self.own_tariff = {"state": "refused", "why": "import price: ct/kWh, above 0 and at most 1000", "at": now}
return False, self.own_tariff["why"]
out = {"v": 1, "import_ct": imp, "by": str(msg.get("by") or "owner")[:40], "at": now}
if exp is not None:
out["export_ct"] = exp
self.outbox.append(out)
self.own_tariff = {"state": "sent", "import_ct": imp, "export_ct": exp, "at": now}
return True, f"sent: {imp:g} ct/kWh" + (f", export {exp:g} ct/kWh" if exp is not None else "")
def apply_msg(self, msg: dict, controls: dict, tz: str, level: str, by: str) -> tuple[bool, str]:
"""One change in the inbox's form (the panel's, the console's)."""
now = self.clock()
@@ -663,6 +701,13 @@ class Preferences:
p = None
if p is not None:
d["pref"] = p
# rooms not planned (inputs.room_refusal): their schedule as the
# thermostat's fallback (optimizer.fallback_entries)
for d in state.get("fallback") or []:
if d["id"] in controls:
p = room_series(d, self.value(f"room:{d['id']}"), ovs, state, ends)
if p is not None:
d["pref"] = p
state["prefs_cost"] = bool(any(d.get("pref") for d in state["devices"])) and (
self.changed_at > self.costs.get("of", 0) or now - self.costs.get("at", 0) >= COST_EVERY_S)
return state
@@ -688,6 +733,9 @@ class Preferences:
f["text"] = feedback_words(f)
fb.append(f)
self.feedback = fb
self.planning = {"priced": plan.get("priced", True), "note": plan.get("price_note", ""),
"prices": plan.get("price_state") or {}, "refused": plan.get("refused") or {},
"made": plan.get("made")}
plan["prefs"] = fb
plan.pop("prefs_cost", None)
return fb
@@ -717,7 +765,8 @@ class Preferences:
b = c.bounds(q)
cl.append({"id": c.id, "kind": c.kind, "name": c.label(), "bounds": [b.lo, b.hi],
"setback_c": _p(c, "setback_c"), "setup_c": _p(c, "setup_c"), "comfort_c": _p(c, "comfort_c")})
v = dict(self.public(), controls=cl, mode=mode, errors=self.errors, ha=self.ha, made=int(self.clock()))
v = dict(self.public(), controls=cl, mode=mode, errors=self.errors, ha=self.ha, made=int(self.clock()),
planning=self.planning, own_tariff=self.own_tariff)
try:
tmp = self.view_path + ".tmp"
with open(tmp, "w") as f:
+1
View File
@@ -43,6 +43,7 @@ class Hour:
solar_kwh_m2: float | None = None
cloud_pct: float | None = None
temp_c: float | None = None
wind_ms: float | None = None # mean wind speed, m/s (DWD through Bright Sky; the heat forecast, methods.md B13)
def sun_position(t: datetime, lat: float, lon: float) -> tuple[float, float]:
+9 -4
View File
@@ -15,7 +15,8 @@ Per 15-minute step of the plan, for a shade with its window's orientation
cooling season the sun on the facade and the room warm (its
temperature within 1 K of the setpoint, or outside
24 °C or more) or the next 3 hours dear (their mean
price 10 % above the horizon's): close to shade_pct
price 10 % above the horizon's, priced steps only:
no price, no dear hours): close to shade_pct
(someone home: some daylight) or closed_pct (nobody
home); open again (open_pct) when the sun has left
heating season the sun on the facade (sunny, outside below 18 °C):
@@ -154,8 +155,12 @@ def schedule(d: dict, s: dict, ctx: dict | None = None) -> dict:
min_move = float(p.get("min_move_s", 1800))
night_ok = bool(float(p.get("night_moves", 0) or 0))
qf, qt = str(p.get("quiet_from", "22:00")), str(p.get("quiet_to", "07:00"))
prices = s.get("price_import") or [0.0] * T
mean = sum(prices) / len(prices) if prices else 0.0
# the tariff's prices as they are: None where it has none (no tariff, or
# the steps past its end, bundles.prices). The dear hours are judged on
# the priced steps only; without a price there are none (no stand-in)
prices = list(s.get("price_import") or [])
priced = [x for x in prices if x is not None]
mean = sum(priced) / len(priced) if priced else 0.0
sky = s.get("sky") or [1.0] * T
t_out = s.get("t_out") or [10.0] * T
occupied = s.get("occupied") or [1] * T
@@ -180,7 +185,7 @@ def schedule(d: dict, s: dict, ctx: dict | None = None) -> dict:
season = ctx.get("season") or season_of(local.month)
want, why, kind = None, "", None
if season == "cooling":
ahead = prices[k:k + 12]
ahead = [x for x in prices[k:k + 12] if x is not None]
dear = bool(ahead) and mean > 0 and sum(ahead) / len(ahead) > 1.1 * mean
warm = (temp is not None and setpoint is not None and temp >= setpoint - 1.0) or \
(k < len(t_out) and t_out[k] >= 24.0)
+37 -5
View File
@@ -89,7 +89,8 @@ def _val(c, e):
def _big(c, old, new) -> bool:
if c.kind == "battery":
top = max(float(c.p("max_charge_w")), float(c.p("max_discharge_w")))
f, _, _ = c.battery_facts()
top = max(f.get("max_charge_w") or 0.0, f.get("max_discharge_w") or 0.0)
return abs(new - old) >= max(MIN_BATTERY_W, BATTERY_SHARE * top) - 1e-9
if c.kind in ("heating", "cooling"):
return abs(new - old) >= TEMP_K - 1e-9
@@ -129,9 +130,10 @@ def stabilise(plan: dict, state: dict, controls, col, last_set=None, now: float
In place; returns the plan."""
now = plan.get("made", 0) if now is None else now
step = plan.get("step_s", 900)
end = plan.get("start", now) + step * state.get("steps", 192)
prices = state.get("price_import") or []
feed = state.get("price_export") or []
end = plan.get("start", now) + step * plan.get("steps", state.get("steps", 192))
# the prices the plan had (none without a tariff: no gain to weigh then)
prices = [x for x in state.get("price_import") or [] if x is not None]
feed = [x for x in state.get("price_export") or [] if x is not None]
spread = (max(prices) - min(prices + feed)) if prices else 0.0 # ct per kWh, at most
devs = {d["id"]: d for d in state.get("devices") or []}
kept_n = 0
@@ -158,6 +160,9 @@ def stabilise(plan: dict, state: dict, controls, col, last_set=None, now: float
out = []
for i, e in enumerate(raw):
new = _val(c, e)
if new == "release":
out.append(e) # nothing written (a room's fallback: its own setpoint)
continue
if _same(cur, new):
kind = None
elif isinstance(cur, str) or isinstance(new, str):
@@ -198,11 +203,13 @@ def stabilise(plan: dict, state: dict, controls, col, last_set=None, now: float
changed[kind] = t
if kind == "mode" and c.kind != "battery":
changed["set"] = t
_hold_source(c, out, col, hold["mode"], last_set, now)
# a plan lists changes only
merged = []
for e in out:
if merged and _same(_val(c, merged[-1]), _val(c, e)) and \
(merged[-1].get("grid") == e.get("grid") or _val(c, e) == AUTO):
(merged[-1].get("grid") == e.get("grid") or _val(c, e) == AUTO) and \
merged[-1].get("source") == e.get("source"):
continue
merged.append(e)
plan["devices"][c.id] = merged
@@ -210,6 +217,31 @@ def stabilise(plan: dict, state: dict, controls, col, last_set=None, now: float
return plan
def _hold_source(c, entries, col, hold_s, last_set, now):
"""A hybrid's heat source (a plan entry's "source") changes only after
the hold of a mode (params.hold_mode_s) since its last change: from the
agent's last command (the guard's record, kind "source"), then from the
plan's own changes. A held entry keeps the source in force, its why
says so. In place."""
if c.kind != "heating" or "source" not in c.entities:
return
opts = {str(v): k for k, v in (c.p("source_options") or {}).items()}
cur = opts.get(str(col.state(c.entities["source"])))
t_last = last_set(c.id, "source") if last_set else None
t_last = t_last if t_last is not None else -1e18
for e in entries:
new = e.get("source")
if new is None or new == cur:
continue
t = max(e["t"], now)
if cur is not None and t - t_last < hold_s:
e["planned_source"], e["source"] = new, cur
e["why"] = (e.get("why", "") + "; " if e.get("why") else "") + \
f"source kept: changed {int((t - t_last) // 60)} min ago (hold {hold_s / 60:.0f} min)"
continue
cur, t_last = new, t
def _amount(c, a, b) -> str:
unit = {"battery": "W", "heating": "K", "cooling": "K", "ev": "A"}[c.kind]
d = abs(b - a)
+4 -4
View File
@@ -92,7 +92,7 @@ class SeriesResult:
def wslice(w: fcmodels.Weather, sl: slice) -> fcmodels.Weather:
return fcmodels.Weather(w.temp[sl], w.ghi[sl], w.cloud[sl], w.elev[sl], w.az[sl], w.hours)
return w.slice(sl)
# ---- one series, champion against challengers -----------------------------------
@@ -136,13 +136,13 @@ def train_series(series: str, t: np.ndarray, y: np.ndarray, w: fcmodels.Weather,
res.runs.append(Run(series, kind, {}, None, note=f"not trained: {why}"))
continue
pred = fcmodels.predict(p, series, t[te], wslice(wt, te), site, hist_t, hist_y)
res.runs.append(Run(series, kind, fcmodels.metrics(y[te], pred), p))
res.runs.append(Run(series, kind, fcmodels.metrics(y[te], pred, fcmodels.level_floor(series)), p))
base = next((r for r in res.runs if r.kind == "how" and r.params), None)
res.baseline = base.metrics if base else None
if champion is not None:
try:
pred = fcmodels.predict(champion, series, t[te], wslice(wt, te), site, hist_t, hist_y)
res.champion = fcmodels.metrics(y[te], pred)
res.champion = fcmodels.metrics(y[te], pred, fcmodels.level_floor(series))
except Exception as e: # a champion that can no longer run is replaced
res.champion = None
res.note = f"the model in force could not be scored ({e}): replaced"
@@ -183,7 +183,7 @@ def score_params(params: dict, series: str, t: np.ndarray, y: np.ndarray, w: fcm
except Exception as e:
log.warning("benchmark %s: %s", series, e)
return None
return fcmodels.metrics(y[te], pred)
return fcmodels.metrics(y[te], pred, fcmodels.level_floor(series))
# ---- the rooms ---------------------------------------------------------------------