cantabile_edge, cantabile_modbus, cantabile_eebus 0.1.400: full source

This commit is contained in:
Setti Solutions S.R.L committed 2026-10-30 08:26:45 +02:00
1 parent 343331d234
commit d5fbcacaa4
176 files changed
+32511 -19

No files matched your search

+490
View File
@@ -0,0 +1,490 @@
# Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
"""The plan: a MILP over the next 48 h in 15-minute steps (HiGHS), re-made
every 15 minutes in a subprocess with a time limit (controller.py):
python -m cantabile_edge.optimizer < state.json > plan.json
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
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.
Device models (one function each, small and replaceable):
battery state of charge (estimated from params.soc_pct when no sensor),
charge/discharge power, efficiency, never both at once (binary)
heating a room's first-order thermal model (R in K/kW, C in kWh/K, the
cooling outside temperature, heat from the device and from the sun
through the room's covers); comfort target when occupied,
setback/setup otherwise; a switched boiler is on/off (binary)
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);
a small penalty for closing it while someone is home in daylight.
With a schedule (shades.py: rules on the sun on its facade, the
season, quiet hours) its positions are fixed to it and its plan
entries are the schedule's moves
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
at most max(0, load - pv) + limit_w per step, with a penalty far above any
building request (nobody overrides it).
The building's requests (building.py, state["building"]): a load limit on
the grid import and a thermostat cap are constraints with a penalty (binding
far above any price, flexible with a price), a shift request a soft target
(the window's import lowered by its kWh against the house's own net load).
"""
import json
import math
import sys
import time
from datetime import datetime, timedelta, timezone
from zoneinfo import ZoneInfo
import highspy
from highspy.highs import highs_linear_expression as Lin
PENALTY_LIMIT = 5.0 # EUR per unit and step across a floor or limit (K, % of a battery, kWh)
COMFORT_EUR_KH = 2.0 # EUR per K and hour below (heating) or above (cooling) the comfort target
# while someone is home: above any price (0.30 let a room cool by 1.3 K
# at a 40 ct peak); pre-heating in cheap hours still pays
EV_SHORT_EUR_KWH = 1.0 # EUR per kWh the car lacks at departure
LIGHT_EUR = 0.002 # EUR per step for a closed cover while someone is home in daylight
CHANGE_EUR_KW = 0.002 # EUR per kW a device's power changes from one step to the next: smooth
# plans (equal prices would otherwise give any order, and a charger or
# 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
class Model:
def __init__(self, s: dict):
self.s = s
self.T, self.dt = s["steps"], s["step_s"] / 3600.0
self.h = highspy.Highs()
self.h.setOptionValue("output_flag", False)
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)
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
highspy.HighsVarType.kContinuous)
if cost:
self.cost.append((cost, v))
return v
def smooth(self, series):
"""The cost of every change in a power series (W variables or
expressions), |p[t] - p[t-1]|."""
for a, b in zip(series, series[1:]):
d = self.var(cost=CHANGE_EUR_KW / 1000.0)
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
# -- the house -------------------------------------------------------
def grid(self):
s = self.s
self.gin, self.gout = [], []
for t in range(self.T):
gi = self.var(cost=self.eur_wh(t, s["price_import"][t]))
go = self.var(cost=-self.eur_wh(t, s["price_export"][t]))
spill = self.var(0.0, max(0.0, s["pv_w"][t]))
self.gin.append(gi)
self.gout.append(go)
self.flows[t] += [(1, gi), (-1, go), (-1, spill)]
def building(self):
"""The building's load limit and shift request (on the grid import)."""
req = self.s.get("building") or {}
lim = req.get("load_limit")
if lim:
for t in range(lim["from_step"], lim["to_step"]):
over = self.var(cost=lim["penalty"] * self.dt / 1000.0)
self.h.addConstr(self.gin[t] - over <= lim["value"])
sh = req.get("shift_request")
if sh:
a, b = sh["from_step"], sh["to_step"]
base = sum(max(0.0, self.s["load_w"][t] - self.s["pv_w"][t]) * self.dt for t in range(a, b))
target = max(0.0, base - sh["value"] * 1000.0)
miss = self.var(cost=sh["penalty"] / 1000.0)
imp = sum((self.dt * self.gin[t] for t in range(a, b)), start=Lin())
self.h.addConstr(imp - miss <= target)
def grid_order(self):
"""The grid operator's limit on the controllable consumers' draw."""
o = self.s.get("grid_order") or {}
if not o:
return
for t in range(o["from_step"], min(o["to_step"], self.T)):
base = max(0.0, self.s["load_w"][t] - self.s["pv_w"][t])
over = self.var(cost=o["penalty"] * self.dt / 1000.0)
self.h.addConstr(self.gin[t] - over <= base + o["limit_w"])
def balance(self):
s = self.s
for t in range(self.T):
expr = sum((sign * v for sign, v in self.flows[t]), start=Lin())
self.h.addConstr(expr == s["load_w"][t] - s["pv_w"][t])
# -- devices ---------------------------------------------------------
def battery(self, d):
p, st, b = d["params"], d["state"], d["bounds"]
cap = max(1.0, float(p["capacity_wh"]))
eff = float(p["efficiency"])
lo_pct, hi_pct = b["soc_pct"][0], b["soc_pct"][1]
plo, phi = b["power_w"][0], b["power_w"][1]
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
soc, prev, ch, dis = [], soc0, [], []
for t in range(self.T):
c = self.var(0.0, max_ch)
x = self.var(0.0, max_dis)
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)
e = self.var(0.0, cap)
under = self.var(cost=PENALTY_LIMIT / cap * 100) # Wh below the floor, per % of the battery
over = self.var(cost=PENALTY_LIMIT / cap * 100)
self.h.addConstr(e - prev - self.dt * eff * c + self.dt / eff * x == 0)
self.h.addConstr(e + under >= lo_pct / 100.0 * cap)
self.h.addConstr(e - over <= hi_pct / 100.0 * cap)
self.flows[t] += [(-1, c), (1, x)]
soc.append(e)
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))
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})
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"])
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"])
t0 = st.get("temp_c")
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
a = self.dt / (r * c)
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))
tt = self.var(-50.0, 80.0)
sign = -1.0 if cooling else 1.0
gain = sum((g * gx for g, gx in gains(t)), start=Lin())
# T[t+1] = T[t] (1 - a) + a T_out + dt/C (± cop P/1000 + sun gain/1000)
self.h.addConstr(tt - (1 - a) * prev - sign * self.dt / c * cop / 1000.0 * pw
- self.dt / c / 1000.0 * gain == a * self.s["t_out"][t])
occ = self.s["occupied"][t + 1] if t + 1 < self.T else self.s["occupied"][t]
target = min(max(comfort if occ else other, lo), hi)
miss = self.var(cost=COMFORT_EUR_KH * self.dt)
under = self.var(cost=PENALTY_LIMIT)
over = self.var(cost=PENALTY_LIMIT)
if cooling:
self.h.addConstr(tt - miss <= target)
else:
self.h.addConstr(tt + miss >= target)
self.h.addConstr(tt + under >= lo)
self.h.addConstr(tt - over <= hi)
cap = (self.s.get("building") or {}).get("thermostat_cap")
if cap and cap["from_step"] <= t < cap["to_step"]:
miss_cap = self.var(cost=cap["penalty"] * self.dt)
if cooling:
self.h.addConstr(tt + miss_cap >= cap["value"]) # cooling: not below the cap
else:
self.h.addConstr(tt - miss_cap <= cap["value"]) # heating: not above it
temps.append(tt)
powers.append(pw)
prev = tt
self.smooth(powers)
self.devices[d["id"]] = ("cooling" if cooling else "heating",
{"temp": temps, "power": powers, "pmax": pmax, "switched": switched})
def ev(self, d):
p, st, b = d["params"], d["state"], d["bounds"]
if not st.get("connected"):
self.devices[d["id"]] = ("ev", None)
return
volts = float(p["voltage"]) * float(p["phases"])
imax = min(float(p["max_current_a"]), b["current_a"][1])
imin = max(float(p["min_current_a"]), b["current_a"][0])
dep = departure_step(self.s, str(st.get("departure") or p["departure"]))
need = float(st["need_wh"]) if st.get("need_wh") is not None else float(p["need_wh"])
powers, total = [], Lin()
for t in range(self.T):
if t >= dep or imax < imin:
powers.append(None)
continue
y = self.var(0.0, 1.0, integer=True)
pw = self.var(0.0, imax * volts)
self.h.addConstr(pw - imax * volts * y <= 0)
self.h.addConstr(pw - imin * volts * y >= 0)
self.flows[t].append((-1, pw))
powers.append(pw)
total += self.dt * pw
short = self.var(cost=EV_SHORT_EUR_KWH / 1000.0)
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})
def cover(self, d, room_ids):
p, b = d["params"], d["bounds"]
lo, hi = b["position_pct"][0] / 100.0, b["position_pct"][1] / 100.0
sch = d.get("schedule")
if sch:
# the shade's moves by rules (shades.py): fixed here; the room
# gets the sun on its facade through them
room = p.get("room") if p.get("room") in room_ids else None
xs = [self.var(min(max(x / 100.0, 0.0), 1.0), min(max(x / 100.0, 0.0), 1.0)) for x in sch["pos"]] \
if room else []
sun = sch["sun"] if sch.get("facade") else self.s["sun"]
self.devices[d["id"]] = ("cover", {"pos": xs, "gain_w": float(p["gain_w"]), "room": room,
"schedule": sch, "sun": sun})
return
if p.get("room") not in room_ids:
self.devices[d["id"]] = ("cover", None)
return
xs = []
for t in range(self.T):
x = self.var(lo, hi)
closed_any = self.var(cost=CLOSED_EUR)
self.h.addConstr(closed_any + x >= hi)
daylight = self.s["sun"][t] > 0.05 and self.s["occupied"][t]
if daylight:
closed = self.var(cost=LIGHT_EUR)
self.h.addConstr(closed + x >= hi)
xs.append(x)
self.devices[d["id"]] = ("cover", {"pos": xs, "gain_w": float(p["gain_w"]), "room": p["room"]})
# -- solve -------------------------------------------------------------
def solve(self, time_limit: float):
s = self.s
self.grid()
covers = [d for d in s["devices"] if d["kind"] == "cover"]
rooms = {d["id"] for d in s["devices"] if d["kind"] in ("heating", "cooling")}
for d in covers:
self.cover(d, rooms)
for d in s["devices"]:
k = d["kind"]
if k == "battery":
self.battery(d)
elif k in ("heating", "cooling"):
def gains(t, room=d["id"]):
out = []
for cid, (kind, v) in self.devices.items():
if kind == "cover" and v and v["room"] == room:
out.append((v["gain_w"] * v.get("sun", s["sun"])[t], v["pos"][t]))
return out
self.room(d, k == "cooling", gains)
elif k == "ev":
self.ev(d)
self.building()
self.grid_order()
self.balance()
obj = sum((c * v for c, v in self.cost), start=Lin())
self.h.setOptionValue("time_limit", float(time_limit))
# tight: the differences between good plans are cents, the total
# cost euros (a 1 % gap left an EV charging at the evening price)
self.h.setOptionValue("mip_rel_gap", 1e-4)
self.h.setOptionValue("mip_abs_gap", 0.002)
self.h.minimize(obj)
status = self.h.getModelStatus()
info = self.h.getInfo()
if info.primal_solution_status != 2: # no feasible solution
raise RuntimeError(f"no plan: {self.h.modelStatusToString(status)}")
return self.h.modelStatusToString(status)
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")
start = datetime.fromtimestamp(s["start"], timezone.utc).astimezone(zone)
h, m = (int(x) for x in hhmm.split(":"))
dep = start.replace(hour=h, minute=m, second=0, microsecond=0)
if dep <= start:
dep += timedelta(days=1)
return min(s["steps"], int((dep.timestamp() - s["start"]) // s["step_s"]))
def _round(v: float, step: float) -> float:
return round(v / step) * step
def plan(s: dict, time_limit: float = 30.0) -> dict:
t0 = time.time()
m = Model(s)
status = m.solve(time_limit)
val = m.h.getSolution().col_value
x = lambda v: val[v.index] # noqa: E731
start, step, T = s["start"], s["step_s"], m.T
pi = s["price_import"]
devices = {}
for d in s["devices"]:
kind, v = m.devices.get(d["id"], (d["kind"], None))
entries = []
for t in range(T):
e = _entry(d, kind, v, t, x, s, pi)
if e is not None and (not entries or (entries[-1]["set"], entries[-1].get("grid")) !=
(e["set"], e.get("grid"))):
entries.append({"t": start + t * step, **e})
devices[d["id"]] = entries
energy = sum(m.eur_wh(t, pi[t]) * x(m.gin[t]) - m.eur_wh(t, s["price_export"][t]) * x(m.gout[t])
for t in range(T))
return {"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),
"price_note": s.get("price_note", ""), "sources": s.get("sources", {})}
FLEX_STEPS = 96 # 24 h at 15 min: what a building plans with
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."""
n = min(m.T, FLEX_STEPS)
grid = [round(x(m.gin[t])) for t in range(n)]
shed = [0.0] * n
for kind, v in m.devices.values():
if v is None:
continue
if kind == "battery":
for t in range(min(n, len(v["dis"]))):
stored = max(x(v["soc"][t - 1]) if t else x(v["soc"][0]), 0.0) - v["floor_wh"]
spare = max(v["max_dis"] - x(v["dis"][t]), 0.0)
shed[t] += max(min(spare, stored / m.dt if m.dt else 0.0), 0.0)
cols = v.get("ch") if kind == "battery" else v.get("power")
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)
return {"grid_w": grid, "shed_w": [round(min(sh, g)) for sh, g in zip(shed, grid)]}
def _entry(d, kind, v, t, x, s, pi):
"""What a device is to do in step t, and why (a few words)."""
occ = s["occupied"][t]
if v is None:
return None
if kind == "battery":
net = x(v["ch"][t]) - x(v["dis"][t])
net = _round(net, 50.0)
surplus = s["pv_w"][t] - s["load_w"][t]
grid = net > max(0.0, surplus) + 50
if net > 0:
why = f"cheap grid power ({pi[t]:.1f} ct)" if grid else "PV surplus"
elif net < 0:
mean = sum(pi) / len(pi)
# "peak" only well above the horizon's average (Sim Munich: a plain
# 28 ct hour was called a peak)
why = (f"price peak ({pi[t]:.1f} ct)" if pi[t] >= 1.2 * mean else
f"above the average price ({pi[t]:.1f} ct, average {mean:.1f})")
else:
why = "hold"
return {"set": net, "grid": grid, "why": why}
if kind in ("heating", "cooling"):
temp = x(v["temp"][t])
pw = x(v["power"][t])
ahead = s["occupied"][min(t + 4, s["steps"] - 1)]
if kind == "heating" and v["switched"]:
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")
return {"set": "on" if on else "off", "why": why}
# the room may dip below a floor in the model (soft, so there is always
# a plan), but a setpoint never asks for it: clamped into the bounds
# (the guard would refuse it; the sim's run showed 19.5 under a 20 floor)
lo, hi = d["bounds"]["temp_c"][0], d["bounds"]["temp_c"][1]
target = min(max(_round(temp, 0.5), math.ceil(lo * 2) / 2), math.floor(hi * 2) / 2)
if kind == "cooling":
if pw < 50:
return {"set": "off", "why": "off: cool enough or away"}
return {"set": target, "why": "pre-cool before someone is home" if not occ and ahead else "keep cool"}
if pw < 50:
return {"set": target, "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"}
if kind == "ev":
p = v["power"][t]
if p is None:
return {"set": "off", "why": "after departure"}
amps = round(x(p) / v["volts"])
if amps < 1:
return {"set": "off", "why": "wait for cheaper hours"}
return {"set": amps, "why": f"cheapest hours before departure ({pi[t]:.1f} ct)"}
if kind == "cover" and v.get("schedule"):
sch = v["schedule"]
return {"set": sch["set"][t], "why": sch["why"][t] if sch["set"][t] is not None else ""}
if kind == "cover":
pos = _round(100 * x(v["pos"][t]), 10.0)
sun = s["sun"][t]
if pos < 100 and sun > 0.05:
why = "shade: keep the sun's heat out"
elif sun > 0.05:
why = "open: daylight and the sun's heat"
elif pos < 100:
why = "closed: no sun"
else:
why = "open"
return {"set": pos, "why": why}
return None
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."""
T, pi, pe = m.T, s["price_import"], s["price_export"]
cost = 0.0
for t in range(T):
net = s["load_w"][t] - s["pv_w"][t]
cost += m.eur_wh(t, pi[t]) * max(net, 0) - m.eur_wh(t, pe[t]) * max(-net, 0)
mean = sum(pi) / T
for kind, v in m.devices.values():
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))
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))]
cost += wh / 1000.0 * (sum(asap) / len(asap)) / 100.0
return cost
def main():
s = json.load(sys.stdin)
limit = float(sys.argv[1]) if len(sys.argv) > 1 else 30.0
try:
out = plan(s, limit)
except Exception as e: # the caller keeps its last plan
json.dump({"v": 1, "error": str(e)}, sys.stdout)
sys.exit(1)
json.dump(out, sys.stdout)
if __name__ == "__main__":
main()