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

+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))]