Files
goodwe-addon/goodwe_controller/app/ctl_trade.py
T
glenn schrooyenandClaude 07d23d2eed
checks / unit (pull_request) Successful in 27m27s
infra-pin / fresh (pull_request) Successful in 2s
MAINT-28 fix-forward round 4: the paused pack's cap is its own part of the guard's floor, the largest of the period, per unit
Owner 2026-11-13 ("ok max", relayed by the manager): while the pause holds,
the pack in maintenance CHARGE gives at most the largest floor the guard
claimed in the quarter. The cap is now that pack's own part of the floor
(the floor less what the other units are placed at, split without the cap),
the largest in the 15-minute period, kept per unit (`_m28_hi`). 0 W while
the guard holds it at its reserve. test_maint28b: SoC check stated against
the owner-accepted give (0.70 point, measured 0.64); both-packs-able tests
(B on Cheap hours, B on Solar first); per-unit state and the one-slot
arbitrate. test_maint28 unchanged (5925 W). Pins: test_safety84
n2_charge_banked, test_packshare's one-resolve AST pin (a second call with
the same weights).

Co-Authored-By: Claude <noreply@anthropic.com>
2026-11-13 23:42:23 +01:00

1349 lines
66 KiB
Python

"""Controller methods for trading: mode runs, peak floors, pack actions.
Moved unchanged from app/main.py (MAINT-21). DECISIONS/MAIN-orchestration.md."""
import collections
import dataclasses
import logging
from datetime import datetime, timedelta, timezone
from . import arbitrage
from .arbiter import (
ACTUATOR_SITE, Claim, P_MAINTENANCE, P_MAINT_SHAPE, P_PEAK, SET,
pre_resolve, resolve,
)
from . import allocator
from . import dayplan
from . import modetrade
from . import packmode
from . import priceruns
from . import solarfc
from . import control as _ctl
from . import freshness
from . import messages
from .maintenance import CHARGE, DRAIN, HOLD, IDLE, MaintConfig, POWER_MOVING
from .mqtt import MODE_LABELS, USE_OFF, USE_ON, unit_slugs, unit_state_key
from . import peakguard
from . import packshare
from .price import Absence
from .price import required_spread as price_required_spread
from .price import uncertainty_of as price_uncertainty_of
from .price_chain import gate_for
from .static_tariff import static_gated
from .ctl_inputs import TARIFF_MAX_AGE_S
_LOG = logging.getLogger("goodwe")
# OPT-11 P3: how long the last cheap run stays the price stored energy is
# valued at: the rest of that day.
REF_CHEAP_KEEP = timedelta(hours=12)
# OPT-15: the longest a run edge holds the loop at E waiting for the meter to
# show the step (control.PLANT_SETTLE_S).
EDGE_HOLD_S = _ctl.PLANT_SETTLE_S
# OPT-11 P4: store key of the house profile, and how often the forecast sensors
# are read (hourly at most).
HOUSE_PROFILE_KEY = "house_profile"
# MAINT-28: a step of a battery's command, in W, after which its reading is not
# current until a changed one arrives (`Controller._batts_settled()`).
MAINT_STEP_W = 100.0
# MAINT-28: the reason on a paused pack's cap (`Controller._m28_share()`).
M28_REASON = "peak hold"
# OPT-34: the level of a night grid charge that has started, so it does not
# drop when the forecast goes (`Controller._latch_charge()`).
CHARGE_LATCH_KEY = "night_charge_latch"
# OPT-34: a latch outlives its last cheap run by one price slot, since the next
# run is planned at the slot edge.
CHARGE_LATCH_GRACE_S = 900.0
def _night_limit(born):
"""OPT-34: a run that starts after this cannot carry the latch on: the
first bell start (`solarfc.BELL_FROM_H`, local) after `born`."""
d0, d1 = solarfc._bounds(born)
bell = solarfc._bell_start(d0)
return bell if bell > born else solarfc._bell_start(d1)
def pack_energy_of(inv):
"""OPT-09. ONE roster entry as the view `packshare` consumes.
One builder for two callers (`pack_energy` needs the roster, `cycle()` one
entry): written twice they would drift. A module function so inverter.py
need not import `packshare`."""
return packshare.PackEnergy(inv.name, inv.soc, inv.bms_soc_floor,
inv.capacity_kwh, inv.max_w)
# MAINT-13: a battery power reading at or below minus this many W is a pack
# that is taking charge.
MAINT_CHARGING_W = 50.0
class TradeMixin:
def trade_power_w(self, floor_pct, ceiling_pct) -> tuple:
"""OPT-09. `(charge_w, discharge_w)`: how hard a trade may be SIZED:
what the site can push AND STILL HAVE SOMEWHERE TO PUT. The bounds are
arbitrage's own (`arbitrage_soc_floor` / `_ceiling`), NOT the BMS
cut-out that `packshare.envelope()` uses (SAFETY-25): different
questions. It sizes the ask, it does not route it. A pack whose SoC did
not read counts on neither side. Neither side may be zero on a trading
tick (`arbitrage.decide()` refuses `IDLE_NO_SIZE`: a 0 W claim is a
park order). DECISIONS/MAIN-orchestration.md."""
# The reduction lives in `packshare`; `test_packshare.py` part 9 calls
# the SAME function (a transcription in a check is a copy that drifts).
return packshare.trade_power_w(self.pack_energy, floor_pct, ceiling_pct)
def peak_aim_w(self) -> float:
"""SAFETY-79. `peak_cap_w` less `peak_margin_w`: what the forecast
checks aim at. Reports and the bill use the real cap."""
return float(self.o.get("peak_cap_w", 3500)) - self.peak_margin_w
@property
def pack_energy(self) -> list:
"""OPT-09. Each pack as the FOUR numbers a split needs; the fourth is
`capacity_kwh`, which is why this is not `packs`. EVERY unit, live
or not, for `packs`'s reason (the allocator drops dead ones itself)."""
return [pack_energy_of(inv) for inv in self.inverters]
def pack_weights(self, target_w):
"""OPT-09. The comfort weights for a site target of `target_w`. A
method handed to `resolve()`, not a dict computed before it (energy
headroom depends on the target), and read fresh on every call, never
cached."""
base = packshare.weights(self.pack_energy, target_w)
if not self.modes_on:
return base
# OPT-11: the solar order. While the site charges, Leftover solar
# batteries weigh 0, so Solar first fill first (comfort, like the rest
# here; permission is the mode claim).
w = packmode.charge_weights(base, self.pack_modes(), target_w)
# P3: in a price run, the batteries whose run it is carry it first.
tick = self.mode_tick
return w if tick is None else modetrade.weights(tick.roles, w,
target_w)
def pack_mode(self, inv) -> "packmode.PackMode":
"""OPT-11. This battery's on/off switch and mode, read from the store."""
return packmode.read(getattr(self.store, "data", None) or {}, inv.name)
def pack_modes(self) -> dict:
return {inv.name: self.pack_mode(inv) for inv in self.inverters}
def loop_bound(self, claims):
"""OPT-11. `(lo, hi)`: what the batteries may place if the loop
decides: the sum over live units of each unit's hard limits with its
mode applied (`allocator.loop_bound()`), from THIS cycle's unit
claims. None when no mode is filed (maintenance) or the range leaves
out 0 W (a fault `resolve()` reports)."""
if len(self.inverters) <= 1:
modes = [c for c in claims if c.source == "mode"]
if not modes:
return None
lo = max(c.lo for c in modes)
hi = min(c.hi for c in modes)
return (lo, hi) if lo <= 0.0 <= hi else None
bounds = {u: pre_resolve([c for c in claims if c.actuator == u])
for u in self.units}
return allocator.loop_bound(bounds, live=self.live_units())
# --- OPT-11 P3: price runs, per battery -------------------------------
def _mode_packs(self, maint_results=None) -> list:
"""Each battery as `modetrade.Pack`, in roster order."""
live = set(self.live_units())
out = []
for i, inv in enumerate(self.inverters):
pm = self.pack_mode(inv)
idle = (maint_results is None
or maint_results[i].phase == IDLE)
refused = (inv.refused if len(self.inverters) > 1
else self.batt_refused) or 0
# OPT-15: a charge refusal's probe (SAFETY-73, N>1) as it stood
# when last decided; its pin is filed after this, in cycle().
probing = (len(self.inverters) > 1 and refused < 0
and inv.probe_from is not None)
out.append(modetrade.Pack(
inv.name, pm.use, pm.mode, pm.sell and pm.can_sell,
float(inv.max_w), inv.soc, inv.capacity_kwh,
live=inv.name in live, idle=idle, refused=int(refused),
probing=probing))
return out
def _wx_track(self, now) -> None:
"""TARIFF-24, once per cycle, before the plan: with a forecast read,
remember when the run now under way (cheap, give or sell) ends."""
if self.solar_fc is None:
return
rp = self.mode_runs
ends = []
if rp is not None and rp.on:
ends = [r.end for r in (rp.cheap, rp.sell)
if r is not None and r.holds(now)]
g = rp.give_at(now)
if g is not None:
ends.append(g.end)
self._wx_free_to = max(ends) if ends else None
def weather_held(self, now) -> bool:
"""TARIFF-24: no forecast now, but a run planned with one is under way:
it keeps its gap to its end (OPT-34: a night charge that keeps its
level too); the wider gap applies from the next run. Pure; Home asks
the same (`homeview.trade_verdict()`).
(DECISIONS/MAIN-orchestration-archive.md)"""
return self.solar_fc is None and (
(self._wx_free_to is not None and now < self._wx_free_to)
or (self._charge_latch is not None
and now < self._charge_latch[0]))
def _price_runs(self, now, packs, floor_pct, ceiling_pct):
"""The kept run plan, rebuilt at most once per price slot (15 min) or
when the prices or a battery's choice change; a run under way is kept
to its end (`priceruns.keep_started()`). None with no fresh firm
prices: then no battery holds or trades.
(DECISIONS/MAIN-orchestration-archive.md)"""
plan = self.fresh_tariff_plan(now)
if plan is None or not plan.has_prices:
self.mode_runs, self._runs_key = None, None
self.day_plan = None
return None
slot = int(now.timestamp() // 900)
key = (id(plan), slot, tuple((p.name, p.use, p.mode, p.sell)
for p in packs))
held = self.weather_held(now)
if self.fc_entity is not None:
# P4: a forecast arriving or going rebuilds the plan at once (and
# so does the end of a run that held the gap, TARIFF-24).
key += (self.solar_fc is None, held)
if key != self._runs_key:
done_c = self._run_done.get("charge", (None, set()))[1]
done_s = self._run_done.get("sell", (None, set()))[1]
e = modetrade.energy(packs, floor_pct, ceiling_pct, done_c,
done_s)
required = price_required_spread(
arbitrage.threshold_eur_kwh(self.o),
price_uncertainty_of(plan.read.product)
| arbitrage.weather_uncertainty(True, self.solar_fc, held))
ref = self._ref_cheap
if ref is not None and now - ref.end > REF_CHEAP_KEEP:
ref = self._ref_cheap = None
new = priceruns.plan(
plan.read.points, now, required_eur_kwh=required,
charge_kwh=e[0], charge_kw=e[1], sell_kwh=e[2],
sell_kw=e[3],
ref_eur_kwh=None if ref is None else ref.mean_eur_kwh)
if self.fc_entity is not None:
new = self._day_plan(now, packs, floor_pct, ceiling_pct,
new, plan, required, ref, done_c, e)
self.mode_runs = priceruns.keep_started(self.mode_runs, new, now)
self._runs_key = key
runs = self.mode_runs
# The cheapest cheap run under way lately is the price the stored
# energy was bought at; it stays the reference for REF_CHEAP_KEEP
# after it ends, unless a cheaper one comes.
ref = self._ref_cheap
if runs is not None and runs.cheap is not None \
and runs.cheap.holds(now) and (
ref is None or now - ref.end > REF_CHEAP_KEEP
or runs.cheap.mean_eur_kwh <= ref.mean_eur_kwh):
self._ref_cheap = runs.cheap
return runs
def _day_plan(self, now, packs, floor_pct, ceiling_pct, runs, plan,
required, ref, done_c, e):
"""OPT-11 P4: the day plan (`dayplan.plan()`) on the runs just made,
its levels held by the hysteresis (`dayplan.hold()`), then the runs
made again with each battery's shortfall as the charge. With no plan
(no or stale forecast, no house profile yet) the levels are dropped: P3
option A. (DECISIONS/MAIN-orchestration-archive.md)"""
dp = dayplan.plan(
self.solar_fc,
None if self.house_profile is None
else self.house_profile.estimator(),
priceruns.keep_started(self.mode_runs, runs, now), now, packs,
trust_pct=self.solar_trust_pct, floor_pct=floor_pct,
ceiling_pct=ceiling_pct, aim_w=self.peak_aim_w(),
slots=priceruns.firm_slots(plan.read.points, now),
spread=required)
self.day_plan = dp
if dp is None:
self._plan_targets = None
return runs
self._plan_targets = dayplan.hold(
self._plan_targets, dp.targets,
{p.name: p.capacity_kwh for p in packs})
e2 = modetrade.energy(packs, floor_pct, ceiling_pct, done_c, (),
targets=self._plan_targets)
return priceruns.plan(
plan.read.points, now, required_eur_kwh=required,
charge_kwh=e2[0], charge_kw=e2[1], sell_kwh=e[2], sell_kw=e[3],
ref_eur_kwh=None if ref is None else ref.mean_eur_kwh)
def plan_targets(self):
"""P4: each battery's planned level, or None (no day plan). Dropped
at once when the forecast goes (stale or missing), except the level
of a night charge that has started (OPT-34): it keeps that level."""
if self.solar_fc is None:
lt = self._charge_latch
if lt is None or datetime.now(timezone.utc) >= lt[0]:
return None
return dict(lt[1])
return self._plan_targets
def _latch_charge(self, now, runs, targets, packs=None) -> None:
"""OPT-34, once per cycle after `modetrade.decide()`: a started night
grid charge keeps its planned level when the forecast goes mid-charge
(`plan_targets()` gives the latched levels, `weather_held()` the narrow
price gap). The latch lasts through every cheap run plus one price slot
(`CHARGE_LATCH_GRACE_S`), is dropped when `now` passes its end or the
battery leaves its mode, and a charge that never started has none.
DECISIONS/OPT-34-the-night-charge-keeps-its-level.md"""
old = lt = self._charge_latch
tick = self.mode_tick
run = None if runs is None else runs.cheap
in_run = run is not None and run.holds(now)
grace = timedelta(seconds=CHARGE_LATCH_GRACE_S)
if lt is not None and now >= lt[0]:
lt = None
if lt is not None and packs is not None:
ok = {p.name for p in packs
if p.use and p.mode in packmode.PLAN_CHARGE_MODES}
lv = {n: v for n, v in lt[1].items() if n in ok}
lt = (lt[0], lv, lt[2]) if lv else None
# A run may carry the latch on only if it starts by the night's bell.
carry = in_run and (lt is None or run.start <= _night_limit(lt[2]))
if in_run and self.solar_fc is not None:
# Rebuilt from the plan: a battery already latched follows its
# level up or down whatever its role this tick (a fresh figure may
# lower it below the SoC), one that left the plan is dropped, and
# a new one comes in only while it charges from the grid.
tg = targets or {}
lv = {n: float(tg[n]) for n in (lt[1] if lt else {}) if n in tg}
if tick is not None and tick.action == modetrade.CHARGE:
lv.update({n: float(tg[n]) for n, r in tick.roles.items()
if r == modetrade.CHARGE and n in tg})
if not lv:
lt = None
elif lt is None:
lt = (run.end + grace, lv, now)
else:
lt = (max(run.end + grace, lt[0]) if carry else lt[0], lv,
lt[2])
elif lt is not None and carry:
lt = (max(lt[0], run.end + grace), lt[1], lt[2])
if lt != old:
self._charge_latch = lt
self.store.set(CHARGE_LATCH_KEY, None if lt is None else {
"until": lt[0].isoformat(), "levels": lt[1],
"born": lt[2].isoformat()})
def _mode_roles(self, now, maint_results):
"""OPT-11 P3: each battery's role and range this tick. Grid charging
and selling need a fresh plan that `TariffPlan.arbitrage()` allows with
the MEASURED peak guard (None refuses: nothing measures the quarter),
exactly the gate `arbitrage.decide()` has.
(DECISIONS/MAIN-orchestration-archive.md)"""
floor_pct, ceiling_pct = arbitrage.soc_bounds(self.o)
packs = self._mode_packs(maint_results)
self._wx_track(now)
runs = self._price_runs(now, packs, floor_pct, ceiling_pct)
guard = arbitrage.guard_state(self.peak_guard)
plan = self.fresh_tariff_plan(now)
charge_ok = sell_ok = False
trade_why = "not_covered"
def allowed(active):
return plan.arbitrage(
peak_guard_active=active,
min_spread_eur_kwh=arbitrage.threshold_eur_kwh(self.o),
uncertainty=arbitrage.weather_uncertainty(
True, self.solar_fc, self.weather_held(now)),
now=now).match(
allowed=lambda _v: True, refused=lambda _v: False)
if guard is not None and plan is not None and runs is not None:
# A charge asks the guard (section 9.1 interlock); a sell only
# needs it to have measured the quarter, since discharge is never
# capped by it (a big discharge alone engages it on export).
sell_ok = allowed(False)
charge_ok = sell_ok and allowed(guard)
trade_why = (None if charge_ok else "peak" if sell_ok
else "not_worth")
self.mode_gate = None if charge_ok else trade_why
price_now = None
if plan is not None:
try:
pt = plan.read.match(series=lambda r: r.at(now),
no_data=lambda _r: None)
price_now = (None if pt is None or pt.provisional
else float(pt.eur_per_kwh))
except Absence:
price_now = None
house = (None if self.grid is None or self.site_batt_w is None
else float(self.grid) + float(self.site_batt_w))
if self.house_profile is not None and \
self.house_profile.add(now, house):
self.store.set(HOUSE_PROFILE_KEY, self.house_profile.dump())
targets = self.plan_targets()
if targets is None:
done_c = self._run_mark("charge", runs and runs.cheap, packs,
lambda p: p.soc is not None
and p.soc >= ceiling_pct)
else:
# P4: out of the run at its planned level. A level the
# hysteresis moved opens the run to it again (a new mark key).
def full(p):
to = modetrade.charge_to(p, ceiling_pct, targets)
return p.soc is not None and (to is None or p.soc >= to)
done_c = self._run_mark("charge", runs and runs.cheap, packs,
full, tuple(sorted(targets.items())))
done_s = self._run_mark("sell", runs and runs.sell, packs,
lambda p: p.soc is not None
and p.soc <= floor_pct)
quarter = int(now.timestamp() // 900)
was = self.mode_tick is not None and \
self.mode_tick.action == modetrade.CHARGE
# SAFETY-135: the first guard stop in a period (or measured headroom
# stop in a young one) does not latch; the charge may start again
# RESTART_S after it, but not in the period's last RESTART_S. No
# start in a young period while a give falls.
# DECISIONS/SAFETY-135-young-period.md
st = getattr(self, "_charge_stop", None)
paused = (st is not None and st[0] == quarter
and (now.timestamp() - st[1] < modetrade.RESTART_S
or (quarter + 1) * 900 - now.timestamp()
< modetrade.RESTART_S))
wait = ("wait" if paused else
"settle" if self._give_falling(now) else None)
self.mode_tick = modetrade.decide(
runs, now, packs, charge_ok=charge_ok, sell_ok=sell_ok,
trade_why=trade_why, price_now=price_now,
headroom_w=self.arb_headroom_w, floor_pct=floor_pct,
ceiling_pct=ceiling_pct, house_w=house, charging_now=was,
blocked=self._charge_blocked_q == quarter,
done_charge=done_c, done_sell=done_s, targets=targets,
draining=any(r.phase == DRAIN for r in maint_results or ()),
wait=wait,
maint_charging=any(r.phase == CHARGE
for r in maint_results or ()))
self._latch_charge(now, runs, targets, packs)
# A charge the guard or the headroom stopped stays off this period.
# OPT-15: only a MEASURED stop latches; the first unmeasured headroom
# in a quarter stops one tick, a second latches.
# (DECISIONS/MAIN-orchestration-archive.md)
if was and self.mode_tick.action != modetrade.CHARGE:
why = self.mode_tick.why
gap = why == "headroom" and self.arb_headroom_w is None
if why == "peak" or (why == "headroom" and not gap) or (
gap and self._charge_gap_q == quarter):
young = now.timestamp() - quarter * 900 < modetrade.YOUNG_S
if (why == "peak" or (young and not gap)) and (
st is None or st[0] != quarter):
self._charge_stop = (quarter, now.timestamp())
else:
self._charge_blocked_q = quarter
elif gap:
self._charge_gap_q = quarter
return self.mode_tick
def _give_falling(self, now) -> bool:
"""SAFETY-135: True in a young period while the batteries give over
START_W less than they did in the last GAVE_S s: the meter may not
show that yet, so a charge room read now is too big.
DECISIONS/SAFETY-135-young-period.md"""
t = now.timestamp()
gave = getattr(self, "_gave", None)
if gave is None:
gave = collections.deque()
self._gave = gave
if gave and t < gave[-1][0]:
gave.clear() # the clock stepped back
if self.site_batt_w is not None:
gave.append((t, max(0.0, float(self.site_batt_w))))
while gave and t - gave[0][0] >= modetrade.GAVE_S:
gave.popleft()
if self.site_batt_w is None or not gave \
or t % 900 >= modetrade.YOUNG_S:
return False
drop = max(w for _t, w in gave) - max(0.0, float(self.site_batt_w))
return drop > modetrade.START_W
def _run_mark(self, kind, run, packs, out, extra=None) -> set:
"""The batteries that left run `run` (full, or at the floor); they
stay out until it ends, so a level edge does not re-arm them.
`extra` (P4: the planned levels) is part of the run's key."""
key = None if not run else (run.start, run.end)
if key is not None and extra is not None:
key += (extra,)
was_key, done = self._run_done.get(kind, (None, set()))
if key != was_key:
done = set()
if key is not None:
done |= {p.name for p in packs if out(p)}
self._run_done[kind] = (key, done)
return done
def _mode_trade(self, claims, now) -> bool:
"""OPT-11 P3: file the site trade the roles ask for, sized inside the
modes and the hard limits and, for a charge, the billed quarter's
headroom (SAFETY-45, aim cap - margin, SAFETY-79), so no battery that
its mode or a refusal holds is asked for watts it may not give.
(DECISIONS/MAIN-orchestration-archive.md)"""
tick = self.mode_tick
if tick is None:
return False
if tick.action == modetrade.CHARGE:
# OPT-20: the ask carries PROBE_W for exactly the probes whose pin
# is filed this tick (`decide()` ran before the pin, so they can
# differ by one cycle; left alone the allocator moves the pin's
# watts to another battery).
# (DECISIONS/MAIN-orchestration-archive.md)
pins = _ctl.PROBE_W * sum(
1 for c in claims if c.source == "refused"
and c.kind == "set" and c.value < 0)
if pins != tick.probe_w:
tick = self.mode_tick = dataclasses.replace(
tick, ask_w=tick.ask_w + tick.probe_w - pins,
probe_w=pins)
size = modetrade.size(tick, self.loop_bound(claims)
if tick.action else None, self.arb_headroom_w)
runs = self.mode_runs
if tick.action and (size == 0.0 or runs is None):
# Nothing the batteries may place (a refusal, a hard limit): no
# trade, and the roles say so rather than "charging".
back = {modetrade.CHARGE: modetrade.HOLD,
modetrade.REST: modetrade.HOUSE,
modetrade.SELL: modetrade.GIVE}
tick = self.mode_tick = modetrade.Tick(
tick.ranges, {n: back.get(r, r) for n, r in tick.roles.items()},
None, 0.0, "size")
if size == 0.0 or runs is None:
reason = ("battery modes: no price run now" if tick.why is None
else modetrade.WAIT_WORDS.get(tick.why)
or f"battery modes: no trade ({tick.why})")
self.arb = arbitrage.ArbitrageDecision(
action=None, power_w=None, reason=reason,
spread_eur_kwh=None, required_eur_kwh=None,
price_now_eur_kwh=None)
else:
charge = tick.action == modetrade.CHARGE
run = runs.cheap if charge else runs.sell
who = ", ".join(n for n, r in sorted(tick.roles.items())
if r == tick.action)
act = arbitrage.CHARGE if charge else arbitrage.DISCHARGE
self.arb = arbitrage.ArbitrageDecision(
action=act, power_w=size,
reason=(f"{act}: battery modes, "
f"{'cheap' if charge else 'sell'} run "
f"{run.start.isoformat()} to {run.end.isoformat()} "
f"at {run.mean_eur_kwh:.4f} EUR/kWh; "
f"{abs(size):.0f} W on {who}"),
spread_eur_kwh=None, required_eur_kwh=runs.level_eur_kwh,
price_now_eur_kwh=None)
claims.append(arbitrage.claim(self.arb))
if self.arb.action != self._arb_action:
self._arb_action = self.arb.action
self.log_event(self.arb.explain(), hint=messages.hint(
"trade_charge" if self.arb.action == arbitrage.CHARGE else
"trade_give" if self.arb.action == arbitrage.DISCHARGE
else "trade_off"))
return self.arb.action is not None
def _reseed_run_edge(self, claims, now) -> None:
"""OPT-11 P3: a mode trade just ended, so the loop takes over from a
command no loop chose: it starts at the house's own point E, not at the
trade's watts, and OPT-15 HOLDS it at E (`_edge_grid()`) until the
meter shows the step or `EDGE_HOLD_S` passes.
DECISIONS/OPT-11-battery-modes.md"""
self._edge = None
batt = self.site_batt_w
if batt is None or self.grid is None:
return
want = float(batt) + float(self.grid) - self.tuning.target_grid_w
bound = self.loop_bound(claims)
if bound is not None:
want = max(bound[0], min(bound[1], want))
want = float(round(max(-self.site_max_w, min(self.site_max_w, want))))
self.target = self.i_w = want
if want != float(batt):
self._edge = (want, 1.0 if want > float(batt) else -1.0,
now + timedelta(seconds=EDGE_HOLD_S), float(batt))
def _edge_grid(self, end, now):
"""OPT-15: the grid reading the loop acts on this tick. While a run
edge is held, the target itself (no error, the command stays at E); the
hold ends when the meter reaches the target, on `end`, or after
`EDGE_HOLD_S`. (DECISIONS/MAIN-orchestration-archive.md)"""
e = self._edge
if e is None:
return self.grid
held_w, sign, until, last_b = e
tg, db = self.tuning.target_grid_w, self.tuning.deadband_w
b = self.site_batt_w
moving = (b is not None and sign * (float(b) - last_b) >= db
and sign * (held_w - float(b)) >= db
and now < until + timedelta(seconds=EDGE_HOLD_S))
if (end or (now >= until and not moving)
or sign * (float(self.grid) - tg) < db):
self._edge = None
return self.grid
self._edge = (held_w, sign, until, last_b if b is None else float(b))
self.i_w = held_w
return tg
def _charge_track(self, claims, maint_results) -> None:
"""SAFETY-93, N>=2: a charge ends when its battery leaves CHARGE or can
no longer be placed (stale link, refusal). Kept until the loop runs.
SAFETY-95: a drain likewise; its refusal (SAFETY-73) is read from the
battery (+1 = will not give). (DECISIONS/MAIN-orchestration-archive.md)"""
if len(self.inverters) < 2:
return
live = set(self.live_units())
now = {CHARGE: set(), DRAIN: set()}
for inv, res in zip(self.inverters, maint_results):
u = self.actuator_of("maintenance", inv)
if res.phase in now and u in live and not pre_resolve(
[c for c in claims if c.actuator == u]).contradiction \
and not (res.phase == DRAIN and (inv.refused or 0) > 0):
now[res.phase].add(inv.name)
self._charge_ended |= self._charging_was - now[CHARGE]
self._charging_was = frozenset(now[CHARGE])
self._drain_ended |= self._draining_was - now[DRAIN]
self._draining_was = frozenset(now[DRAIN])
def _reseed_charge_end(self, maint_results) -> None:
"""SAFETY-93, N>=2: when a battery's maintenance charge ends, the loop
starts from what the others stood at plus that battery's new command
(its HOLD pin, or its last discharge if it is free; a charge stops);
else the charge's watts land on the others (B 0 -> -1600 W in one
cycle). DECISIONS/SAFETY-93-charge-end.md"""
ended, self._charge_ended = self._charge_ended, frozenset()
if len(self.inverters) < 2 or not ended:
return
for inv, res in zip(self.inverters, maint_results):
if inv.name not in ended:
continue
now_w = (float(res.setpoint_w or 0.0) if res.owns_setpoint
else max(float(inv.target), 0.0))
if not inv.is_live(datetime.now(timezone.utc))[0]:
now_w = 0.0 # SAFETY-96: out of the split, it is sent 0 W
self.target += now_w - float(inv.target)
# SAFETY-96: it settles from its charge to that command.
self._loop_start[inv.name] = now_w
self._settle[inv.name] = self._now_mono
self.i_w = self.target
def _reseed_drain_end(self, maint_results, live) -> None:
"""SAFETY-95, N>=2: when a battery's maintenance drain ends, its drain
leaves the loop's start point, as a charge does (SAFETY-93): the start
is what the others stood at plus its new command (its pin, else 0 W),
never above last cycle's start; else the drain's floor lands on the
others (B 0 -> +1600 W, exporting). DECISIONS/SAFETY-95-drain-end.md"""
ended, self._drain_ended = self._drain_ended, frozenset()
if len(self.inverters) < 2 or not ended:
return
hi = self.target
for inv, res in zip(self.inverters, maint_results):
if inv.name not in ended:
continue
now_w = (float(res.setpoint_w or 0.0)
if res.owns_setpoint and res.phase != DRAIN
else min(float(inv.target), 0.0))
if inv.name not in live:
now_w = 0.0 # SAFETY-96: out of the split, it is sent 0 W
else:
self._drain_tail.add(inv.name)
self.target += now_w - float(inv.target)
self._loop_start[inv.name] = now_w
self._settle[inv.name] = self._now_mono
lo, hi = sorted((self.target, hi))
# A dropped battery's power is the meter's, like the house's.
here = float(self.grid) - self.tuning.target_grid_w + sum(
float(inv.batt) for inv in self.inverters if inv.name in live)
self.target = self.i_w = min(hi, max(lo, here))
def _drain_grid_w(self, live) -> float:
"""SAFETY-95: the grid the loop regulates. While a battery settles from
its ended drain (`_held_out_w`, at most PLANT_SETTLE_DOWN_S) the
batteries count at the site command, so the loop does not chase the
drain's tail. SAFETY-103: a reading can be up to a register period (10
s) older than the meter, so the house point is held and moved only as
far as the meter proves.
DECISIONS/SAFETY-103-old-readings-after-a-drain.md"""
grid = float(self.grid)
self._drain_tail &= set(self._settle) & set(live)
if not self._drain_tail:
self._drain_house = None
return grid
aim = self.tuning.target_grid_w
lo = hi = grid - aim
for inv in self.inverters:
if inv.name not in live:
continue
r = float(inv.batt)
span = self._read_span.get(inv.name)
if (span is None or span[2] != inv.batt_fresh.changed_mono
or span[2] == self._now_mono):
span = (r, r)
# A battery that refuses one way (SAFETY-73) is not heading
# that way, whatever it was asked: that side is its reading.
if (inv.refused or 0) > 0:
span = (min(span[0], r), r)
elif (inv.refused or 0) < 0:
span = (r, max(span[1], r))
lo, hi = lo + span[0], hi + span[1]
held = (float(self.target) if self._drain_house is None
else self._drain_house)
self._drain_house = min(hi, max(lo, held))
return self._drain_house - float(self.target) + aim
def _track_reads(self) -> None:
"""SAFETY-103, N>=2: per battery, the range its power can be in now:
its last changed reading and every command on its wire since (a
lagging battery moves from one toward the others, never beyond)."""
if len(self.inverters) < 2:
return
for inv in self.inverters:
if inv.batt is None:
continue
cmd, since = inv.standing_w(), inv.batt_fresh.changed_mono
lo, hi, was = self._read_span.get(inv.name, (0.0, 0.0, None))
if was is None or since != was:
lo = hi = float(inv.batt)
self._read_span[inv.name] = (min(lo, cmd), max(hi, cmd), since)
def _batts_settled(self) -> bool:
"""MAINT-28: False while a battery reading may pre-date a step UP of
its command, so `grid + site_batt_w` is a new grid and an old battery.
DECISIONS/MAINT-28-hold-the-pause-in-a-peak.md"""
now, ok = self._now_mono, True
if now is None:
return True
for inv in self.inverters:
cmd = float(inv.standing_w())
seen = self._m28_step.get(inv.name)
if seen is None:
seen = self._m28_step[inv.name] = (cmd, None)
elif abs(cmd - seen[0]) >= MAINT_STEP_W:
seen = self._m28_step[inv.name] = (
cmd, now if cmd > seen[0] else seen[1])
at = seen[1]
if at is None or now - at >= freshness.BATT_OBLIGED_S:
continue
got = inv.batt_fresh.changed_mono
if got is None or got < at + freshness.PLANT_SETTLE_S:
ok = False
return ok
def _m28_share(self, claims, now) -> None:
"""MAINT-28: each paused pack's cap (0 W if the guard holds it at its
reserve) set to the largest part of the guard's floor left to it in
this 15-minute period: the floor less what the other units are placed
at in this cycle's split without the cap. Kept per unit in `_m28_hi`,
dropped while the unit is not paused or is held.
DECISIONS/MAINT-28-hold-the-pause-in-a-peak.md"""
floor = max((c.lo for c in claims if c.source == peakguard.SOURCE),
default=0.0)
g = self.peak_guard
held = {self.actuator_of("maintenance", inv) for inv in self.inverters
if g is not None and inv.name in g.held}
q, seen = int(now.timestamp() // 900), set()
for i, c in enumerate(claims):
if c.source != "maintenance" or c.reason != M28_REASON \
or c.actuator == ACTUATOR_SITE or c.actuator in held:
continue
seen.add(c.actuator)
shares = resolve(claims[:i] + claims[i + 1:], units=self.units,
live=self.live_units(), weights=self.pack_weights,
reserve=self._held_back()).shares
part = max(0.0, floor - sum(float(w) for u, w in shares.items()
if u != c.actuator))
hi = max(part, self._m28_was(c.actuator, now))
self._m28_hi[c.actuator] = (q, hi)
claims[i] = dataclasses.replace(c, hi=hi)
# A unit not paused (or held at its reserve) starts again from 0 W.
for u in set(self._m28_hi) - seen:
del self._m28_hi[u]
def _m28_was(self, u, now) -> float:
"""MAINT-28: unit `u`'s cap so far in this 15-minute period, 0 W in
a new one (`_m28_share()`)."""
q, hi = self._m28_hi.get(u, (None, 0.0))
return hi if q == int(now.timestamp() // 900) else 0.0
def _reseed_drop(self, live) -> None:
"""SAFETY-96, N>=2: a battery that drops out of the split (stale link)
leaves the loop's start point, so the others take over at one slew step
a cycle instead of taking its share at once.
DECISIONS/SAFETY-96-dropped-battery.md"""
was, self._live_was = self._live_was, frozenset(live)
if len(self.inverters) < 2 or was is None or was == live:
return
for inv in self.inverters:
if inv.name in self._charge_ended | self._drain_ended:
continue # SAFETY-93/95's edge: `_reseed_*_end()`
if inv.name in was and inv.name not in live:
now_w = 0.0
elif inv.name in live and inv.name not in was:
now_w = float(inv.batt)
# The split is made again, so every battery's command steps.
self._settle.update(
{u: self._now_mono for u in live})
else:
continue
self.target += now_w - float(inv.target)
self._loop_start[inv.name] = now_w
self.i_w = self.target
def _held_out_w(self, live) -> float:
"""SAFETY-96, N>=2: what to add to the site sum so that a battery the
loop cannot move right now counts at its command, not at its reading.
Its real power still reaches the loop through the meter: neither lost
nor counted twice. DECISIONS/SAFETY-96-dropped-battery.md"""
if len(self.inverters) < 2:
return 0.0
out = 0.0
for inv in self.inverters:
cmd = self._loop_start.get(inv.name, float(inv.target))
since = self._settle.get(inv.name)
age = (None if since is None or self._now_mono is None
else self._now_mono - since)
if since is not None and (
age is None or age >= _ctl.PLANT_SETTLE_DOWN_S
or (age > 0 and abs(float(inv.batt) - cmd)
< self.tuning.deadband_w)):
del self._settle[inv.name]
if (inv.name not in live or inv.rejected_since is not None
or inv.name in self._settle):
out += cmd - float(inv.batt)
return out
def _mode_fault_log(self, resolution) -> None:
"""OPT-11: say once, per battery, that its mode was dropped as a fault.
A mode range without 0 W would force a direction, which no mode may do,
so it is never applied (allocator.unit_interval()); main.py never
builds one. (DECISIONS/MAIN-orchestration-archive.md)"""
alloc = resolution.allocation
now = {u for u, _ in getattr(alloc, "mode_faults", ())}
if resolution.mode_fault is not None and self.inverters:
now.add(self.inverters[0].name)
for inv in self.inverters:
if inv.name in now and inv.name not in self._mode_faults:
_LOG.error("Battery mode ignored for %s. Software fault "
"MODE_RANGE.", inv.name)
self.log_event(f"battery mode ignored on {inv.name}, a "
f"software fault", hint=messages.hint(
"mode_fault", unit=inv.name))
self._mode_faults = now
def _pack_action(self, what, unit, value, now) -> dict:
"""OPT-11: switch one battery on or off, set its mode, or (P3) turn its
selling on or off. Store state, not an option: it applies next cycle
with no restart. Switching a battery off also stops its maintenance
cycle. (DECISIONS/MAIN-orchestration-archive.md)"""
if not self.modes_on:
return {"error": messages.pack_refused("off")}
inv = next((i for i in self.inverters if i.name == unit), None)
if inv is None:
return {"error": messages.pack_refused("unit")}
if what == "pack_use":
if not isinstance(value, bool):
return {"error": messages.pack_refused("value")}
inv.store_set(packmode.USE_KEY, value)
self.log_event(f"{inv.name} switched {'on' if value else 'off'} "
f"by operator",
hint=messages.hint("pack_on" if value
else "pack_off", unit=inv.name))
if not value:
self._maint_stop_off(self.maints[self.inverters.index(inv)],
now)
elif what == "pack_sell":
if not packmode.SELLING_ENABLED:
return {"error": messages.pack_refused("sell_off")}
if not isinstance(value, bool):
return {"error": messages.pack_refused("value")}
inv.store_set(packmode.SELL_KEY, value)
self.log_event(f"{inv.name} selling switched "
f"{'on' if value else 'off'} by operator",
hint=messages.hint("pack_sell", unit=inv.name))
else:
if value not in packmode.MODES:
return {"error": messages.pack_refused("value")}
inv.store_set(packmode.MODE_KEY, value)
self.log_event(f"{inv.name} mode set to {value.replace('_', ' ')} "
f"by operator",
hint=messages.hint("pack_mode", unit=inv.name))
pm = self.pack_mode(inv)
out = {"unit": inv.name, "use": pm.use, "mode": pm.mode}
if what == "pack_sell":
out["sell"] = pm.sell
return out
async def _maint_unit_action(self, what, unit, now) -> dict:
"""MAINT-11: start or abort the maintenance cycle of ONE named battery.
The site keeps ONE maintenance slot: a start while any battery holds it
is refused (no queue). (DECISIONS/MAIN-orchestration-archive.md)"""
inv = next((i for i in self.inverters if i.name == unit), None)
if inv is None:
return self._maint_refusal("unit")
machine = self.maints[self.inverters.index(inv)]
if what == "maint_start":
holder = next((i for i, m in zip(self.inverters, self.maints)
if m.phase in POWER_MOVING), None)
if holder is not None:
return self._maint_refusal("busy", holder.name)
if self.modes_on and not self.pack_mode(inv).use:
return self._maint_refusal("off", inv.name)
for msg in machine.force_start(now):
self.log_event(msg, hint=messages.hint(
"maintenance", phase=machine.phase))
return {"unit": inv.name, "phase": machine.phase}
if machine.phase not in POWER_MOVING:
return self._maint_refusal("idle", inv.name)
for msg in machine.abort(now, "operator"):
self.log_event(msg, hint=messages.hint("maintenance",
phase=machine.phase))
await self.command_site_zero()
return {"unit": inv.name, "phase": machine.phase}
@staticmethod
def _maint_refusal(code, unit="") -> dict:
return {"error": messages.maint_refused(code, unit), "code": code,
"unit": unit}
def mode_values(self) -> dict:
"""OPT-11 P2: each battery's mode and switch, for their HA state
topics. Read from the store, so they are right after a restart. Empty
while battery modes are off."""
if not self.modes_on:
return {}
out = {}
names = [inv.name for inv in self.inverters]
for inv, slug in zip(self.inverters, unit_slugs(names)):
pm = self.pack_mode(inv)
out[unit_state_key(slug, "mode")] = MODE_LABELS.get(pm.mode,
pm.mode)
out[unit_state_key(slug, "use")] = USE_ON if pm.use else USE_OFF
return out
def _drain_floor(self, claims, maint_results):
"""SAFETY-78: the site `lo` for a pinned maintenance drain, or None. At
N>=2 the drain pins its pack and the site target is split around the
pin; below the pin a sibling would have to charge (opposite
directions, refused, 0 W, the drain never moves), so the site target
may not go below what the pin places. At N=1 the drain is the site
SET itself: nothing filed. A draining pack with nothing to give adds
no floor (logged once)."""
if len(self.inverters) < 2:
return None
live = set(self.live_units())
floor, waits = 0.0, set()
for inv, res in zip(self.inverters, maint_results):
if res.phase != DRAIN or not res.owns_setpoint \
or not (res.setpoint_w or 0.0) > 0.0:
continue
u = self.actuator_of("maintenance", inv)
b = pre_resolve([c for c in claims if c.actuator == u])
p = (None if u not in live or b.contradiction
or b.pinned_by != "maintenance" else allocator.pin_w(b))
if p is not None and p > 0.0:
floor += p
else:
waits.add(inv.name)
for name in sorted(waits - self._drain_waits):
self.log_event(f"maintenance: {name} cannot give power now, so "
f"its monthly cycle waits",
hint=messages.hint("maint_waits", unit=name))
self._drain_waits = waits
return floor if floor > 0.0 else None
def _peak_on_able(self, decision, maint_results):
"""SAFETY-87: at N>=2, `decision` placed on the batteries that can
still give: live, not refusing, above their own reserve. `able_w` is
their rating plus the drain a held battery gives anyway.
DECISIONS/SAFETY-87-guard-uses-able-batteries.md"""
if len(self.inverters) < 2:
return decision
floor = float(self.o.get(
"peak_soc_floor", peakguard.PEAK_OPTION_DEFAULTS["peak_soc_floor"]))
ok, held = peakguard.reserve_split(self.packs, floor)
if not held:
return decision
live = set(self.live_units())
able = [p for p, inv in zip(self.packs, self.inverters)
if p in ok and inv.name in live and not (inv.refused or 0) > 0]
if not able:
return dataclasses.replace(decision, held=held)
drain = sum(min(float(r.setpoint_w), i.rating_w())
for i, r in zip(self.inverters, maint_results)
if i.name in held and r.phase == DRAIN
and r.owns_setpoint and (r.setpoint_w or 0.0) > 0.0)
names = {p.name for p in able}
return peakguard.place_on_able(
decision, held,
able_w=drain + sum(i.rating_w() for i in self.inverters
if i.name in names),
soc=min(float(p.soc) for p in able),
soc_floor=peakguard.binding_soc_floor(able, floor))
def _peak_landing(self, decision):
"""SAFETY-126: `decision` marked `within_aim` while the guard wants
power but the batteries at 0 W would end the quarter within
`ALARM_MISS_W` of the aim (`peakguard.misses_aim()`). The claim and the
commands are unchanged; only the alarms and the "Why" read it.
DECISIONS/SAFETY-126-landing-error-is-not-an-overrun.md"""
batt, prev = self.site_batt_w, self._land_batt_prev
self._land_batt_prev = batt
if not (decision.engaged and decision.blind is None
and (decision.wanted_w or 0.0) > 0.0):
self._peak_needed = False
return decision
if batt is not None and prev is not None:
batt = min(float(batt), float(prev))
self._peak_needed = self._peak_needed or (
self._peak_proj is not None and peakguard.misses_aim(
self._peak_proj, batt_w=batt, target_w=decision.target_w))
return (decision if self._peak_needed
else dataclasses.replace(decision, within_aim=True))
def _peak_reserve(self) -> frozenset:
"""SAFETY-87: the batteries that give nothing for the peak this
cycle: under their reserve while the others carry a peak floor."""
g = self.peak_guard
if g is None or g.able_w is None or not (g.floor_w or 0.0) > 0.0:
return frozenset()
return frozenset(g.held)
def _held_back(self) -> frozenset:
"""SAFETY-91, N>=2: the batteries at or under their own peak reserve
while another can still give (live, not refusing). One held back stays
so until its SoC reads more than 1 point above its reserve.
DECISIONS/SAFETY-91-held-battery-last.md"""
if len(self.inverters) < 2:
return frozenset()
floor = float(self.o.get(
"peak_soc_floor", peakguard.PEAK_OPTION_DEFAULTS["peak_soc_floor"]))
ok, held = peakguard.reserve_split(self.packs, floor)
held = set(held) | {
p.name for p in ok if p.name in self._held_was
and float(p.soc) <= peakguard.pack_floor_pct(p, floor) + 1.0}
live = set(self.live_units())
if not held or not any(
p.name not in held and inv.name in live
and not (inv.refused or 0) > 0
for p, inv in zip(self.packs, self.inverters)):
self._held_was = frozenset()
else:
self._held_was = frozenset(held)
return self._held_was
def _drain_rise(self, claims, maint_results) -> None:
"""SAFETY-91, N>=2: while a battery is held back (`_held_back()`), a
draining battery's pin becomes a floor at its drain rate, so it rises
towards its rating before the held one gives. A site stop still decides
alone. DECISIONS/SAFETY-91-held-battery-last.md"""
held = self._held_back()
if not held or any(c.kind == SET and c.actuator == ACTUATOR_SITE
and c.priority > P_PEAK for c in claims):
return
live = set(self.live_units())
for inv, res in zip(self.inverters, maint_results):
u = self.actuator_of("maintenance", inv)
if res.phase != DRAIN or not res.owns_setpoint \
or inv.name in held or u not in live:
continue
b = pre_resolve([c for c in claims if c.actuator == u])
p = (None if b.contradiction or b.pinned_by != "maintenance"
else allocator.pin_w(b))
if p is None or not p > 0.0:
continue
for i, c in enumerate(claims):
if c.source == "maintenance" and c.kind == SET \
and c.actuator == u:
claims[i] = Claim.limit("maintenance", P_MAINTENANCE,
lo=p, reason=c.reason,
actuator=u)
def _fill_peak_gaps(self, proj, now, reading):
"""SAFETY-90: `proj` with a meter gap's uncounted seconds counted at
`peakguard.gap_w()` of the imports seen just before and just after it,
and those before this run's first reading likewise at the import seen
first (shown as not measured).
DECISIONS/SAFETY-90-peak-guard-after-a-gap.md."""
self.peak_gap_s = self.peak_unmeasured_s = 0.0
avg = self.p1.averager
since = avg.held_since
if proj is None or proj.block_start is None or since is None:
return proj
if self._unseen is None and self.p1.last is not None:
self._unseen = [proj.block_start, max(0.0, (
since - proj.block_start).total_seconds() - avg.elapsed_s),
since, None]
seen = (None if self.grid is None or self.site_batt_w is None
else float(self.grid) + max(0.0, float(self.site_batt_w)))
if proj.block_start != self._gap_block:
self._gap_block, self._gap_w = proj.block_start, None
self._gap_filled_s = self._gap_held_ws = 0.0
cap = float(self.o.get("peak_cap_w", 3500))
ceiling = peakguard.quarter_ceiling_w(cap, reading)[0]
unseen_on = (self._unseen is not None
and self._unseen[0] == proj.block_start)
if unseen_on and self._unseen[3] is None and seen is not None:
# While the add-on was down the batteries were at 0 W, so the
# seconds before its first reading count like a gap, at the
# import seen first; a restored reading's held part is topped up.
self._unseen[3] = peakguard.gap_w(ceiling, seen)
if self._run_pre is not None:
s0, g0 = self._run_pre
h = (min(s0 + timedelta(seconds=avg.max_hold_s),
self._unseen[2])
- max(s0, proj.block_start)).total_seconds()
self._unseen_held_ws = max(0.0, h) * max(
0.0, self._unseen[3] - max(0.0, g0))
kw = dict(tail_s=(now - since).total_seconds(),
max_hold_s=avg.max_hold_s,
unseen_s=self._unseen[1] if unseen_on else 0.0,
unseen_w=(self._unseen[3] if unseen_on
and self._unseen[3] is not None else ceiling))
_p, gap_s, _u = peakguard.fill_gaps(proj, gap_w=0.0, **kw)
if gap_s > self._gap_filled_s + peakguard.GAP_TOL_S:
self._gap_w = peakguard.gap_w(ceiling, self._gap_w,
self._gap_seen_w, seen)
if self._gap_pre is not None:
# The averager credited the gap's first max_hold_s at the
# reading before it; top that part up to gap_w as well.
s0, g0 = self._gap_pre
h = (min(s0 + timedelta(seconds=avg.max_hold_s), since)
- max(s0, proj.block_start)).total_seconds()
self._gap_held_ws += max(0.0, h) * max(
0.0, self._gap_w - max(0.0, g0))
self.log_event(f"PEAK_GUARD_GAP: the meter missed {gap_s:.0f} s "
f"of this 15-minute period, counted at "
f"{self._gap_w:.0f} W",
hint=messages.hint("peak_gap"))
self._gap_filled_s = max(self._gap_filled_s, gap_s)
if seen is not None:
self._gap_seen_w = seen
if self.grid is not None:
self._gap_pre = (since, float(self.grid))
out, self.peak_gap_s, self.peak_unmeasured_s = peakguard.fill_gaps(
proj, gap_w=self._gap_w if self._gap_w is not None else ceiling,
held_ws=self._gap_held_ws + (self._unseen_held_ws if unseen_on
else 0.0), **kw)
return out
def _peak_over_drain(self, claims, maint_results) -> None:
"""SAFETY-83: at N=1 a peak floor above the drain rate outranks it: the
drain is the site SET at P_MAINTENANCE, above P_PEAK, so the floor
did not bind. Refiled at P_MAINTENANCE where it asks for more;
P_SAFETY still outranks. N>=2: the `drain` floor and
`_drain_over_reserve()`."""
if len(self.inverters) != 1:
self._drain_over_reserve(claims, maint_results)
return
res = maint_results[0]
if res.phase != DRAIN or not res.owns_setpoint:
return
rate = float(res.setpoint_w or 0.0)
for i, c in enumerate(claims):
if c.source == peakguard.SOURCE and c.lo > rate:
claims[i] = dataclasses.replace(c, priority=P_MAINTENANCE)
def _held_pin(self, claims, u):
"""SAFETY-87: what held unit `u` places anyway (its own pin), or None
when that pin charges, so the site is never split both ways."""
b = pre_resolve([c for c in claims if c.actuator == u])
p = None if b.contradiction else allocator.pin_w(b)
return None if p is not None and p < 0.0 else max(p or 0.0, 0.0)
def _drain_over_reserve(self, claims, maint_results) -> None:
"""SAFETY-87, N>=2: while a battery is held at its peak reserve, a
draining battery that may still give is raised from its drain rate
towards its rating for the peak floor, after the others. A site stop
still decides alone. DECISIONS/SAFETY-87-guard-uses-able-batteries.md"""
reserve = self._peak_reserve()
floor = max((c.lo for c in claims if c.source == peakguard.SOURCE),
default=0.0)
if not reserve or not floor > 0.0 or any(
c.kind == SET and c.actuator == ACTUATOR_SITE
and c.priority > P_PEAK for c in claims):
return
live = set(self.live_units())
drains, others = [], 0.0
for inv, res in zip(self.inverters, maint_results):
u = self.actuator_of("maintenance", inv)
if u not in live:
continue
if inv.name in reserve:
p = self._held_pin(claims, u)
if p is None:
return
others += p
continue
b = pre_resolve([c for c in claims if c.actuator == u])
if b.contradiction:
continue
p = allocator.pin_w(b)
if p is not None and p < 0.0:
return # a pack pinned to charge: never split both ways
if res.phase == DRAIN and b.pinned_by == "maintenance" \
and p is not None and p > 0.0:
drains.append((u, p, allocator.hi_w(b)))
others += allocator.hi_w(b) if p is None else p
give = floor - others
for u, p, hi in drains:
if give <= 0.0:
break
up = max(p, min(hi, p + give))
give -= up - p
for i, c in enumerate(claims):
if c.source == "maintenance" and c.kind == SET \
and c.actuator == u:
claims[i] = dataclasses.replace(c, value=up)
def _peak_over_hold(self, claims, maint_results):
"""SAFETY-86: a peak floor outranks a maintenance HOLD (0 W). N=1:
refiled at P_MAINTENANCE as for a drain. N>=2: the holding pack's
pin is raised to the floor minus what the others may place, and the
floor is returned as the site `hold` ceiling. A site stop still
decides alone. DECISIONS/SAFETY-86-peak-over-hold.md."""
hold = {self.actuator_of("maintenance", inv)
for inv, res in zip(self.inverters, maint_results)
if res.phase == HOLD and res.owns_setpoint}
peak = [i for i, c in enumerate(claims)
if c.source == peakguard.SOURCE and c.lo > 0.0]
if not hold or not peak:
return
if len(self.inverters) == 1:
for i in peak:
claims[i] = dataclasses.replace(claims[i],
priority=P_MAINTENANCE)
return
if any(c.kind == SET and c.actuator == ACTUATOR_SITE
and c.priority > P_PEAK for c in claims):
return
live = set(self.live_units())
reserve = self._peak_reserve() # SAFETY-87: they give nothing
others = 0.0
for inv in self.inverters:
u = self.actuator_of("maintenance", inv)
if u in hold or u not in live:
continue
if inv.name in reserve: # only its own pin, never both ways
p = self._held_pin(claims, u)
if p is None:
return
others += p
continue
b = pre_resolve([c for c in claims if c.actuator == u])
if b.contradiction:
continue
p = allocator.pin_w(b)
if p is not None and p < 0.0:
return # a pack pinned to charge: never split both ways
others += allocator.hi_w(b) if p is None else p
floor = max(claims[i].lo for i in peak)
give = floor - others
if give <= 0.0:
return
for i, c in enumerate(claims):
if c.source == "maintenance" and c.kind == SET \
and c.actuator in hold:
claims[i] = dataclasses.replace(c, value=give)
return floor
def _charge_headroom(self, floor: float, claims) -> float:
"""SAFETY-84: a cheap-window charge pulls no more than the quarter's
room under the peak aim (`charge_room_w()`), so it yields just enough
to the peak guard; at N>=2 nothing under a site stop (its 0 W would
need the other pack to give). SAFETY-125: at N=1 too; the stop rule
stays N>=2 only.
DECISIONS/SAFETY-125-grid-charge-under-the-month-peak.md"""
if len(self.inverters) > 1 and any(
c.kind == SET and c.actuator == ACTUATOR_SITE
and c.priority > P_MAINT_SHAPE for c in claims):
return 0.0
room = peakguard.charge_room_w(self.peak_guard, self._peak_proj)
floor = floor if room is None else min(floor, room)
self.room_charge = self.room_charge or floor > 0.0
return floor
def _charge_ceiling(self, claims):
"""SAFETY-84: the site `hi` for a cheap-window charge at N>=2, or None:
the charging pack's own `hi` (P_MAINT_SHAPE) makes it charge; above
that the other pack would have to give (opposite directions,
refused, 0 W). Not filed at N=1."""
if len(self.inverters) < 2:
return None
live = set(self.live_units())
ceiling = 0.0
for inv in self.inverters:
u = self.actuator_of("maintenance", inv)
b = pre_resolve([c for c in claims if c.actuator == u])
if u in live and not b.contradiction and b.hi < 0.0:
ceiling += allocator.hi_w(b)
return ceiling if ceiling < 0.0 else None
def _maint_stop_off(self, machine, now) -> None:
"""OPT-11: stop this battery's maintenance cycle because it is off."""
if machine.phase == IDLE:
return
for msg in machine.abort(now, "battery switched off"):
self.log_event(msg, hint=messages.hint("maint_off",
unit=machine.name))
def _provider_gate(self, now: datetime) -> None:
"""PRICE-01: `cheap`, the gate and the gap from the standing plan. No
price for now is a closed gate, so the charge waits rather than run
unpriced; the gap flag stays False until the first refresh has
finished. (DECISIONS/MAIN-orchestration-archive.md)"""
plan = self.fresh_tariff_plan(now)
published = None if plan is None else plan.published
if published is not None:
self._last_published = published
gate = gate_for(published, now)
self.cheap, self._price_gated = gate.cheap, True
self.tariff_words = gate.words
# Owner, 2026-10-14: the words say 'maintenance waits', so they show
# only while the maintenance charge is on.
self.price_gap = ((not gate.covered) and self.tariff_at is not None
and MaintConfig.from_options(self.o).enabled)
last = self._last_published
if gate.covered or last is None:
self.price_gap_since = None
elif last.covers(now):
# The last series still covers now, but no refresh has made it
# current for TARIFF_MAX_AGE_S: the refresh task has stopped. The
# gap began when the plan was retired.
self.price_gap_since = (
None if self.tariff_at is None
else self.tariff_at + timedelta(seconds=TARIFF_MAX_AGE_S))
else:
self.price_gap_since = last.last_end_before(now)
def _static_gated(self, o: dict, now: datetime) -> bool:
"""`static_gated()`, worked out once an hour: it builds the same
month-long plan as `static_status()` (about 20 ms with a profile), and
whether a fixed tariff is set up does not change from tick to tick
(options change only with a restart)."""
key = (id(o), now.strftime("%Y-%m-%d %H"))
if key != self._gated_key:
self._gated_key, self._gated = key, static_gated(o, now)
return self._gated
def _charge_gate_open(self, inv) -> bool:
"""MAINT-13: may this pack charge now, for the maintenance timeout?
Closed only when a price gate exists, it is shut, and the pack is not
really taking charge. (DECISIONS/MAIN-orchestration-archive.md)"""
if not self._price_gated or self.cheap:
return True
batt = inv.batt
return batt is not None and float(batt) <= -MAINT_CHARGING_W