# 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()