Files
cantabile-ha-addons/src/edge/cantabile_edge/optimizer.py
T

1400 lines
73 KiB
Python

# 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.
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.
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, from the sun
through the room's covers, and the fit's internal gain and sun
(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). 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);
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
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
at most max(0, load - pv) + limit_w per step, with a penalty far above any
building request (nobody overrides it).
The market's contracts in force (state["market"], from the market bundle;
the market's step 2, minimal, shadow: the plan only, no commands): a contract
the home buys on is an import source at its price, one it sells on an
export sink, through the same meter as the grid (which keeps the tariff's
import and feed-in prices), so the plan exchanges where the contract beats
the grid. Each step uses its own slot's terms (window, amounts, price) when
the bundle carries the coming slots (a contract's "terms", term_at). The
plan's "market" lists per contract the planned kWh and the saving against
the grid (vs_grid_eur).
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).
The owner's preferences (preferences.py, a device's "pref"): a room's
target per step from its schedule (in place of the occupied hours) at the
comfort cost, and a "must" as a floor (heating) or limit (cooling) with the
penalty MUST_EUR_K, inside the bounds and under a building's thermostat cap; a
car's ready-by time and energy (a must at EV_MUST_EUR_KWH, a prefer valued
at its max_ct per kWh with min_kwh at EV_SHORT_EUR_KWH); a battery's
reserve as its floor per step. The plan's "prefs" says per preference
whether it is met; with state["prefs_cost"] its "prefs_cost" the cost of
each must (pref_costs: the plan made again without it).
"""
import copy
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
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)
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
EV_MUST_EUR_KWH = 5.0 # EUR per kWh a car lacks at a "must" ready-by (preferences.py): above any price,
# below a building's binding load limit (50) and the grid operator's (500)
MUST_EUR_K = 20.0 # EUR per K and slot across a room's "must" (preferences.py): 80 EUR per K·h, so the
# heat a room holds (C kWh/K) is not worth letting it fall even at 3 EUR/kWh; it stays
# inside the bounds and under a building's cap, so those still win
COST_SOLVE_S = 8.0 # s at most per extra plan for a must's cost (pref_costs)
COST_MAX = 6 # musts costed per plan at most
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
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
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)
# 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
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 | 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):
"""Import and export through the meter, each at most the site's
connection (grid_max_w; never below the house's own net load or
surplus, so there is always a plan). The meter either imports or
exports in a step: a binary where the feed-in pays at least the
import price (else importing to export at once would earn money and
the plan would run to the bound). Elsewhere none is needed: doing
both costs more than doing less of each, which keeps the balance and
only loosens every other constraint on the import (all are upper
bounds: the building's, the grid order's); steps with a market
contract have their own switch (market)."""
s = self.s
cap = float(s.get("grid_max_w") or GRID_MAX_W)
self.gin, self.gout, self.gcap = [], [], []
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)
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))
self.flows[t] += [(1, gi), (-1, go), (-1, spill)]
def grid_switch(self, skip):
"""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):
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)
self.h.addConstr(self.gin[t] - hi_in * imp <= 0)
self.h.addConstr(self.gout[t] + hi_out * imp <= hi_out)
def market(self):
"""The market's contracts in force (state["market"], bundles.py
market_for_model; shadow, the market's step 2): a contract the home
buys on is an import source at its price, one it sells on an export
sink, both through the same meter as the grid. Bounds per step: the
best-effort maximum; a firm amount (bought: at least that much; sold:
a shortfall costs the contract's price again, a stand-in for its
penalty); take-or-pay (the minimum is paid whether used or not). The
meter either imports or exports in a step (a binary where a contract
applies), so nothing bought is resold."""
self.buy = [[] for _ in range(self.T)] # contract import vars per step
self.sell = [[] for _ in range(self.T)]
self.contracts = [] # (contract, {step: var}, {step: paid var})
steps = set()
for c in self.s.get("market") or []:
vars_, paid_ = {}, {}
for t in range(max(0, c["from_step"]), min(self.T, c["to_step"])):
k = term_at(c, t) # this step's terms (the coming slots), else the contract's
if k is None:
continue
hi = k["max_w"] if k.get("max_w") else MARKET_MAX_W
eur = self.eur_wh(t, k["price_ct"])
if c["direction"] == "buys":
lo = min(k.get("guaranteed_w") or 0.0, hi)
mwh = k.get("minimum_wh") or 0.0
if mwh > 0: # take-or-pay: what is paid covers at least the minimum
v = self.var(lo, hi)
paid = self.var(mwh / self.dt, cost=eur)
self.h.addConstr(paid - v >= 0)
paid_[t] = paid
else:
v = self.var(lo, hi, cost=eur)
self.buy[t].append(v)
self.flows[t].append((1, v))
else:
v = self.var(0.0, hi, cost=-eur)
g = min(k.get("guaranteed_w") or 0.0, hi)
if g > 0:
short = self.var(cost=eur)
self.h.addConstr(v + short >= g)
self.sell[t].append(v)
self.flows[t].append((-1, v))
vars_[t] = v
steps.add(t)
self.contracts.append((c, vars_, paid_))
for t in steps:
imp = self.var(0.0, 1.0, integer=True)
self.h.addConstr(sum(self.buy[t], start=Lin()) + self.gin[t] - MARKET_MAX_W * imp <= 0)
self.h.addConstr(sum(self.sell[t], start=Lin()) + self.gout[t] + MARKET_MAX_W * imp <= MARKET_MAX_W)
self.grid_switch(steps)
def meter_in(self, t):
"""The meter's import in step t: the grid's and the contracts' bought."""
return self.gin[t] + sum(self.buy[t], start=Lin()) if self.buy[t] else self.gin[t]
def building(self):
"""The building's load limit and shift request (on the meter's 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.meter_in(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.meter_in(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.meter_in(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 if self.priced else None
soc, prev, ch, dis = [], soc0, [], []
pref = d.get("pref") # the owner's reserve per step (preferences.py)
floors = []
for t in range(self.T):
lo_t = lo_pct
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, 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)
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_t / 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 (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,
"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"])
# 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"])
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
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)
ghi = self.s.get("ghi_w_m2") or [0.0] * self.T
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):
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 (± 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
if pref:
want, must = pref["target"][t], pref["must"][t]
if pref.get("off") is not None and pref["group"][t] == pref["off"]:
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)
if capped:
mv = max(mv, cap["value"]) if cooling else min(mv, cap["value"])
cross = self.var(cost=MUST_EUR_K)
if cooling:
self.h.addConstr(tt - cross <= mv)
else:
self.h.addConstr(tt + cross >= mv)
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)
if capped:
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(main)
prev = tt
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": 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."""
if not isinstance(v, list):
return [float(v)] * self.T
zone = ZoneInfo(self.s.get("tz") or "UTC")
start, step = self.s["start"], self.s["step_s"]
return [float(v[datetime.fromtimestamp(start + t * step, timezone.utc).astimezone(zone).hour % len(v)])
for t in range(self.T)]
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 = ev_volts(p, "plan")
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"])
pref = d.get("pref") # the owner's ready-by (preferences.py)
if pref:
dep, need = int(pref["dep_step"]), float(pref["need_wh"])
if pref.get("off"):
need = 0.0
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, 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))
powers.append(pw)
total += self.dt * pw
if pref and pref["how"] == "prefer":
# a kWh is worth max_ct to the owner (without one: today's), min_kwh at any price
worth = EV_SHORT_EUR_KWH if pref.get("max_ct") is None else max(0.0, pref["max_ct"]) / 100.0
short = self.var(cost=worth / 1000.0)
self.h.addConstr(total + short >= need)
mwh = min(float(pref.get("min_wh") or 0.0), need)
if mwh > 0:
short_min = self.var(cost=EV_SHORT_EUR_KWH / 1000.0)
self.h.addConstr(total + short_min >= mwh)
else:
short = self.var(cost=(EV_MUST_EUR_KWH if pref else 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,
"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"]
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()
self.market()
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 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")
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 _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
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, (x(m.gin[t]), x(m.gout[t])))
if e is not None and (not entries or _key(entries[-1]) != _key(e)):
entries.append({"t": start + t * step, **e})
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),
# 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"]) 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
(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)))
def _when(s, ts: float) -> str:
return datetime.fromtimestamp(ts, timezone.utc).astimezone(ZoneInfo(s.get("tz") or "UTC")).strftime("%a %H:%M")
TOL_K = 0.3 # a room's target counts as met within this
TOL_PCT = 0.5 # a battery's reserve
TOL_WH = 50.0 # a car's energy
def pref_feedback(s, m, x) -> list[dict]:
"""Per preference (a room's block, boost or away; a car's next ready-by;
a battery's reserve): met or not in the plan, and in a few words why.
Fields: control, group, kind, how, label, met (None: not in the
plan's 48 h, or not plugged in), detail, and per kind the numbers."""
out = []
start, step, T = s["start"], s["step_s"], m.T
for d in s["devices"]:
pref = d.get("pref")
if not pref:
continue
kind, v = m.devices.get(d["id"], (d["kind"], None))
if kind in ("heating", "cooling") and v:
out += _room_feedback(s, d, pref, v, x, kind == "cooling")
elif kind == "battery" and v:
for gi, g in enumerate(pref["groups"]):
ts = [t for t in range(T) if pref["group"][t] == gi]
f = {"control": d["id"], "group": g["group"], "kind": "battery", "how": "must", "label": g["text"]}
if not ts:
out.append(dict(f, met=None, detail="not in the next 48 h"))
continue
soc = [100.0 * x(v["soc"][t]) / v["cap"] for t in ts]
worst = min(range(len(ts)), key=lambda k: soc[k] - v["floors"][ts[k]])
miss = v["floors"][ts[worst]] - soc[worst]
met = miss <= TOL_PCT
f.update(met=met, min_pct=round(min(soc), 1), floor_pct=round(v["floors"][ts[worst]], 1))
if not met:
f["detail"] = f"{soc[worst]:.0f} % at {_when(s, start + (ts[worst] + 1) * step)}"
if d["state"].get("soc_pct") is not None and float(d["state"]["soc_pct"]) < v["floors"][ts[0]]:
f["detail"] += f" (starts at {float(d['state']['soc_pct']):.0f} %)"
out.append(f)
elif kind == "ev":
out.append(_ev_feedback(s, d, pref, v, x, m))
return out
def _room_feedback(s, d, pref, v, x, cooling) -> list[dict]:
out = []
start, step, T = s["start"], s["step_s"], len(pref["target"])
lo, hi, lo_by, hi_by = (d["bounds"]["temp_c"] + ["device", "device"])[:4]
cap = (s.get("building") or {}).get("thermostat_cap")
sign = -1.0 if cooling else 1.0
for gi, g in enumerate(pref["groups"]):
ts = [t for t in range(T) if pref["group"][t] == gi]
f = {"control": d["id"], "group": g["group"], "kind": g["kind"], "how": g["how"], "label": g["text"]}
if not ts:
out.append(dict(f, met=None, detail="not in the next 48 h"))
continue
notes = []
want = []
for t in ts:
w0 = pref["must"][t] if g["how"] == "must" and pref["must"][t] is not None else pref["target"][t]
w = min(max(w0, lo), hi)
by = (hi_by if not cooling else lo_by) if sign * (w0 - w) > 1e-9 else None
if cap and cap["from_step"] <= t < cap["to_step"]:
wc = max(w, cap["value"]) if cooling else min(w, cap["value"])
if wc != w:
by, w = "building", wc
if by and by not in notes:
notes.append(by)
want.append(w)
temps = [x(v["temp"][t]) for t in ts]
gap = [sign * (w - tt) for w, tt in zip(want, temps)]
k = max(range(len(ts)), key=lambda i: gap[i])
met = gap[k] <= TOL_K
f.update(met=met, first=start + ts[0] * step, worst_c=round(temps[k], 1), want_c=round(want[k], 1))
bits = []
if notes:
held = min(want) if not cooling else max(want)
bits.append(f"held at {held:g} °C by the {notes[0]}'s limit")
f["held_by"] = notes[0]
if not met:
bits.append(f"{temps[k]:.1f} °C at {_when(s, start + (ts[k] + 1) * step)}")
if bits:
f["detail"] = "; ".join(bits)
out.append(f)
return out
def _ev_feedback(s, d, pref, v, x, m) -> dict:
start, step = s["start"], s["step_s"]
f = {"control": d["id"], "group": pref["group"], "kind": "ev", "how": pref["how"],
"label": f"car {pref['text']}", "at": pref["at"], "need_kwh": round(pref["need_wh"] / 1000.0, 2)}
plug = f"; plugged in at {_when(s, pref['plugged_at'])}" if pref.get("plugged_at") else ""
if pref.get("note"):
f["note"] = pref["note"]
if v is None:
return dict(f, met=None if pref["how"] == "prefer" else False, detail="not plugged in")
pw = [x(p) if p is not None else 0.0 for p in v["power"]]
dep = min(v["dep"], len(pw))
wh = sum(m.dt * p for p in pw[:dep])
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) 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"])
f["reached_pct"] = round(pct, 0)
reached = f"{pct:.0f} %"
else:
reached = f"{wh / 1000.0:.1f} kWh"
when = _when(s, pref["at"])
if pref.get("beyond"):
f.update(met=None, detail=f"{reached} by the end of the plan (the ready-by is later){plug}")
return f
if pref["how"] == "prefer":
f["met"] = short <= max(TOL_WH, 0.01 * pref["need_wh"])
f["detail"] = f"{reached} by {when}" + ("" if f["met"] else
f" ({short / 1000.0:.1f} kWh less: dearer than the price wanted)") + plug
return f
f["met"] = short <= max(TOL_WH, 0.01 * pref["need_wh"])
if f["met"]:
f["detail"] = f"{reached} by {when}{plug}"
return f
# a must it cannot meet: by how much, and when it could be ready at full power from now
f["short_kwh"] = round(short / 1000.0, 2)
rate = v.get("pmax") or 0.0
if rate > 0:
n = math.ceil(pref["need_wh"] / (rate * m.dt) - 1e-9)
f["ready_at"] = int(start + n * step)
can = f"; ready at full power by {_when(s, f['ready_at'])}"
else:
can = "; it may not charge now (a limit holds it at 0 A)"
f["detail"] = f"{reached} by {when}, short by {short / 1000.0:.1f} kWh{can}{plug}"
return f
def pref_costs(s, energy: float, deadline: float) -> dict:
"""Each must's cost (EUR a day): the plan's cost for power less that of
the plan made again without it (a room's block at its setback, a
battery's reserve at its floor before); a car's must: what its charging
costs (no second plan). At most COST_MAX, each within COST_SOLVE_S and
the time left."""
out = {}
days = s["steps"] * s["step_s"] / 86400.0
n = 0
for i, d in enumerate(s["devices"]):
pref = d.get("pref")
if not pref or d["kind"] not in ("heating", "cooling", "battery"):
continue
for gi, g in enumerate(pref["groups"]):
if g["how"] != "must" or gi not in pref["group"]:
continue
left = deadline - time.time() - 1.0
if n >= COST_MAX or left < 1.0:
return out
n += 1
s2 = copy.deepcopy(s)
s2["prefs_cost"] = False
s2["devices"][i]["pref"]["off"] = gi
try:
m2 = Model(s2)
m2.solve(min(COST_SOLVE_S, left))
val = m2.h.getSolution().col_value
e2 = energy_of(s2, m2, lambda v: val[v.index])
except Exception: # noqa: BLE001 - a cost is not worth failing the plan
continue
c = (energy - e2) / days
out[g["group"]] = round(c if abs(c) >= 0.005 else 0.0, 2)
return out
def term_at(c: dict, t: int) -> dict | None:
"""A market contract's terms in plan step t: its per-step terms when the
bundle told the coming slots (None: it does not apply then), else the
contract's own (held over from_step .. to_step)."""
per = c.get("terms")
if per is None:
return c
return per[t] if 0 <= t < len(per) else None
def market_plan(s, m, x) -> list[dict]:
"""Per contract in the plan (shadow): the planned energy per step and in
all (kWh), what is paid, and what it saves against the grid: bought,
import price x kWh used - contract price x kWh paid; sold, (contract
price - feed-in) x kWh (EUR; < 0: dearer than the grid). A take-or-pay
contract's paid energy is at least its minimum, used or not (what the
optimisation pays). Fields: id, name, direction, price_ct, steps [{t,
kwh, paid_kwh}] (steps with energy used or paid only), planned_kwh,
paid_kwh, cost_eur (> 0 paid, < 0 received), vs_grid_eur."""
out = []
pi, pe = s["price_import"], s["price_export"]
for c, vars_, paid_ in getattr(m, "contracts", []):
steps, kwh, paid_kwh, cost, vs = [], 0.0, 0.0, 0.0, 0.0
for t, v in sorted(vars_.items()):
e = max(x(v), 0.0) * m.dt / 1000.0
pay = max(x(paid_[t]) * m.dt / 1000.0, e) if t in paid_ else e
if pay < 1e-6:
continue
price = (term_at(c, t) or c)["price_ct"]
steps.append({"t": s["start"] + t * s["step_s"], "kwh": round(e, 4), "paid_kwh": round(pay, 4)})
kwh += e
paid_kwh += pay
if c["direction"] == "buys":
cost += pay * price / 100.0
vs += (e * pi[t] - pay * price) / 100.0
else:
cost -= e * price / 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 (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 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)
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:
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)
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:
"""Why the battery charges from the grid: "cheap grid power" only in the
cheapest quarter of the horizon's prices and 10 % below their mean
(sim-munich-1 called 47.6 ct cheap: an evening day-ahead price under a
50 ct flat); else what it is for, the dearer hours later."""
p25 = sorted(pi)[len(pi) // 4]
mean = sum(pi) / len(pi)
if pi[t] <= p25 + 1e-9 and pi[t] < 0.9 * mean:
return f"cheap grid power ({pi[t]:.1f} ct)"
later = pi[t + 1:]
if later and max(later) > pi[t]:
k = t + 1 + later.index(max(later))
return f"charge for dearer hours later ({pi[t]:.1f} ct now, {pi[k]:.1f} ct in {(k - t) * 15 // 60} h)"
return f"charge from the grid ({pi[t]:.1f} ct)"
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); 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:
the meter's planned import and export in t."""
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 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:
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"
if grid_w[0] < GRID_ZERO_W and grid_w[1] < GRID_ZERO_W and not grid:
# what the battery does is what its own self-consumption mode does:
# the inverter follows the house (no setpoint to chase the PV or
# the load every quarter hour)
return {"set": net, "grid": False, "auto": True,
"why": "self-consumption: the battery covers the house" if net <= 0 else
"self-consumption: PV surplus into the battery"}
return {"set": net, "grid": grid, "why": why}
if kind in ("heating", "cooling"):
temp = x(v["temp"][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:
# a schedule: "someone home" is a target above the setback ahead
# (below the setup, cooling); its target in place of comfort/setback
sign = -1 if kind == "cooling" else 1
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"] 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")
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:
# no heat planned: the thermostat at what the room must keep (the
# comfort or setback target in the bounds), not at the room's
# predicted temperature, which a thermostat holds by heating; the
# room never cooled as planned, every next plan started from it
# again (a replay of a munich-1 day: kept at 24 °C all evening)
occ1 = s["occupied"][min(t + 1, s["steps"] - 1)]
p = d["params"]
want = float(p["comfort_c"]) if occ1 else float(p["setback_c"])
if pref:
want = float(pref["target"][t])
if pref["must"][t] is not None:
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"}
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:
return {"set": "off", "why": "after departure"}
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}"}
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; 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):
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"):
# 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))]
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()