"""One site grid target, divided across N inverters so that the shares SUM to it. ⚠️ THE REASON THIS EXISTS, AND IT IS NOT EFFICIENCY. The control primitive in this system is METER EMULATION: the master reports a FABRICATED grid reading (0x056E direction, 0x056F magnitude, FC 0x10, every 1-2 s) and the inverter regulates ITSELF to it. So one number means "the battery moves X W" to this add-on and "the grid is at X W" to the inverter - an identity that holds ONLY at N=1. Hand two inverters the same target and each supplies it IN FULL: the loop gain at the meter becomes N times the per-unit gain. That is measured, not argued. On admin/goodwe's two-master rig (TEST-19, `sim/sitesim.py --table`, the add-on's own `compute()` in the loop and the firmware's own encoder on the wire): N=2 gain 0.6 BROADCAST worst export -400 W (N=1: +10 W) N=2 gain 1.0 BROADCAST commands [1000, 2000, 1000, 0] W, grid [0, -2000, 0, +2000] W, tail p2p 4000 W, FOREVER, and not one guard fires. `gain: 1.0` is what config.yaml:374 accepts as its documented maximum. The sign watchdog is evaluated on every one of those cycles and never trips, because the disagreement flips on alternate ticks and never holds its 180 s window. So the broadcast fault is not merely inefficient: it is invisible to every detector this repository has. THE FIX IS STRUCTURAL, WHICH IS WHY IT IS A MODULE AND NOT A TUNING CHANGE ========================================================================= ONE integrator on P1, above the split (§10.3, and `compute()` is that integrator). Its output S is the SITE's grid target. This module turns S into per-unit shares with one invariant: sum(shares) + unmet_w == S, with unmet_w == 0 whenever the envelopes allow and each inverter is then told a function of ITS OWN SHARE, never of the shared measurement. Write s_i = a_i * S with sum(a_i) = 1. Each unit closes its own loop with per-unit gain g_i, so the gain seen AT THE METER is gbar = sum(a_i * g_i) which is a CONVEX COMBINATION of the per-unit gains and therefore lies in [min g_i, max g_i] FOR ANY SPLIT. Compare the broadcast case, a_i = 1 for every unit, where the same sum is N * g and grows without bound in N. ⚠️ THAT IS THE WHOLE ARGUMENT, AND IT IS WHY THE WEIGHTS ARE A COMFORT CHOICE. Nothing above constrains the a_i beyond summing to 1. So SoC, thermals and pack wear may set them freely and a BAD SPLIT CANNOT DESTABILISE THE SITE - it can only be unkind to one pack. That property is the reason §6.2 chose share allocation over a regulator/ballast arrangement, in which the ballast unit's share is a function of the shared measurement and the gain question comes back. ⚠️ WEIGHTS EXPRESS PREFERENCE. ENVELOPES EXPRESS PERMISSION. A weight of 0 is "please do not use this unit", and it is honoured while any other unit has headroom - but it is NOT a constraint, because the SUM is the safety property and stranding capacity behind a preference would leave a standing error for the site integrator to chase forever. To make a unit genuinely unusable, close its envelope or leave it out of `live`. See `_fill()`. WHAT THIS MODULE MUST NOT DO ============================ ⚠️ IT MUST NOT READ P1. One integrator on the site measurement, above the split. A second reader of the meter is a second controller, and two controllers on one actuator is the failure the whole arbiter exists to prevent. Nothing in here takes a measurement of any kind: the inputs are S, the per-unit intervals, and per-tick liveness. That is checkable by reading the imports, and it is why there are none beyond the standard library. ⚠️ IT MUST NOT CACHE AN ENVELOPE. `plan()` is a pure function called once per tick with that tick's intervals. A unit's available range moves for reasons that have nothing to do with the allocator - a stale link, a pack at its floor, a device rating that failed to read - and an allocator holding a construction-time envelope over-allocates into a unit that cannot take it. There is no state here to hold one; that is deliberate and it is graded. ⚠️ ROUNDING IS A SAFETY PROPERTY. The setpoint register is 1 W (control.py says so where it quantises). A per-unit `round()` biases the sum by up to N/2 W every tick, and at 1-2 Hz a systematic 1 W bias is a PERMANENT standing error the site integrator will chase forever - it is not a rounding artefact, it is a slow offset with a control loop wound around it. So the sum is computed in INTEGER ARITHMETIC from an integer target and the fractional parts are settled by LARGEST REMAINDER (Hamilton): floor everything, then hand the leftover watts one at a time to the units with the largest discarded fraction. The sum cannot drift because no float ever enters it. """ from dataclasses import dataclass, field from math import ceil, floor, inf # The tolerance on a float comparison of watts. Envelopes arrive as floats from # config and from device registers; this is the width below which two of them # are the same number. It is never used on the sum - see the module docstring. EPS = 1e-9 # --- why a unit is not in the envelope set, and why the whole thing refused --- # Named rather than spelled inline so that main.py, SAFETY-28's write gate and # the tests can all agree on which case fired without matching English. DROP_STALE = "stale link" DROP_CONTRADICTION = "contradicts itself" DROP_NO_INTEGER = "no integer setpoint in its interval" REFUSE_SCOPE = "mis-routed claim" REFUSE_EMPTY = "no unit available" REFUSE_SIGN = "opposite directions" @dataclass(frozen=True) class UnitPlan: """What ONE unit was told this tick, and why it was that and not more. This is the per-unit half of the allocation record. `why` is written for an operator reading an action log at 2 a.m., not for a developer: it says which mechanism chose the number - the weighted fill, an envelope that ran out, a claim of the unit's own that outranked the site. """ unit: str share_w: int lo: float hi: float weight: float why: str pinned: bool = False clamped: bool = False def explain(self) -> str: span = (f"[{'-inf' if self.lo == -inf else format(self.lo, '.0f')}, " f"{'+inf' if self.hi == inf else format(self.hi, '.0f')}]") return f"{self.unit} -> {self.share_w:+d} W in {span} ({self.why})" @dataclass(frozen=True) class Allocation: """EVERY TICK PRODUCES ONE OF THESE, including the ticks that refused. ⚠️ IT IS DESIGNED TO BE GATEABLE, because SAFETY-28 gates the write path on it. That means three things, and each is a decision rather than a convenience: * `ok` is ONE boolean and it is the only thing a gate has to read. A gate that must parse a message, or check three fields in the right order, is a gate somebody gets wrong. * a REFUSAL still carries the record - `plans`, `dropped` and the reason - so the gate can say WHY it stopped the write instead of only that it did. A refusal that returns nothing is a refusal nobody can debug. * `unmet_w` is separate from `ok`. An allocation that could not place every watt is still SAFE TO WRITE and strictly better than commanding zero; it is the site target that was not fully met, not a broken allocation. Fusing the two would make a saturated inverter park the whole site. `sum_w` is the integer the shares are required to add up to, and `quantisation_w` is the ONE rounding that produced it from `target_w`. Both are here so that "the shares sum to S" can be checked by a reader rather than believed: `sum(shares.values()) + unmet_w == sum_w` is an identity over integers, and `sum_w - target_w` is a single site-level rounding of at most half a watt that is NEVER distributed into a per-unit bias. """ target_w: float sum_w: int shares: dict = field(default_factory=dict) plans: tuple = () dropped: tuple = () # ((unit, why), ...) - order is roster order unmet_w: int = 0 quantisation_w: float = 0.0 refused: str | None = None passthrough: bool = False # N<=1: the share IS the site target, unrounded @property def ok(self) -> bool: """The one boolean SAFETY-28's write gate reads.""" return self.refused is None def explain(self) -> str: """One line an operator can act on.""" if self.refused is not None: return (f"REFUSED to allocate {self.target_w:+.0f} W: " f"{self.refused}") if self.passthrough: return f"pass-through {self.target_w:+.0f} W (one unit, nothing to divide)" body = ", ".join(f"{u}{s:+d}" for u, s in sorted(self.shares.items())) out = f"{self.sum_w:+d} W as {body}" if self.unmet_w: out += f", {self.unmet_w:+d} W UNMET" if self.dropped: out += (" - dropped " + ", ".join(f"{u} ({w})" for u, w in self.dropped)) return out def _int_envelope(b): """A unit's interval, narrowed to the integers a 1 W register can hold. ⚠️ NARROWED INWARD, ALWAYS. `ceil` on the floor and `floor` on the ceiling, so every integer in the result is inside the real interval. Rounding the other way would let a share of exactly the rating be commanded on a unit whose rating is 2499.5 W, which is the one direction an envelope must never move: the envelope is what `device` and `supervised` filed, i.e. what the hardware said it can do. Infinities pass through untouched - an absent bound is not a large bound, and `ceil(-inf)` is not a number. A unit that filed nothing this cycle has exactly that interval, which is why this case is the common one at N>=2 and not an edge. """ lo = -inf if b.lo == -inf else ceil(b.lo - EPS) hi = inf if b.hi == inf else floor(b.hi + EPS) return lo, hi def _clamp_int(v, lo, hi): return min(max(int(v), lo if lo != -inf else int(v)), hi if hi != inf else int(v)) def _fill(order, weights, cap, amount): """WATER-FILL: place `amount` watts across `order`, capped, by weight. `amount` and every `cap` are NON-NEGATIVE magnitudes; the direction has already been taken out by the caller. Returns `(add, leftover)`. THE LOOP IS THE STANDARD ONE and it terminates in at most len(order) rounds: share the remaining amount in proportion to weight; any unit whose share would exceed its cap is PINNED AT ITS CAP and dropped from the active set; repeat with what is left. A unit that is not capped in a round is not capped in any later round either, so nothing is revisited. ⚠️ AND THEN THE SECOND PASS, WHICH IS THE POLICY DECISION IN THIS FUNCTION. Units with weight 0 are excluded from the weighted rounds - that is what a zero weight is for. But if the weighted set fills up and watts remain, they are offered to the zero-weight units, EQUALLY, rather than being reported as unmet. The reason is the module docstring's: the weights are a comfort choice and the sum is the safety property, so a preference must never manufacture a standing error at the meter that the site integrator will then chase. To make a unit genuinely unusable, close its envelope - `cap` is obeyed absolutely and is never overridden here. """ add = {u: 0.0 for u in order} rem = float(amount) for pool in ( [u for u in order if weights[u] > 0.0], [u for u in order if weights[u] <= 0.0], # the last-resort pass ): # Inside the last-resort pass every weight is 0, so the proportional # step needs a weight of its own; equal shares is the only choice that # does not invent a preference the caller did not express. w = {u: (weights[u] if weights[u] > 0.0 else 1.0) for u in pool} active = [u for u in pool if cap[u] > 0.0] while rem > EPS and active: total = sum(w[u] for u in active) capped = [u for u in active if rem * w[u] / total >= cap[u] - add[u]] if capped: for u in capped: rem -= cap[u] - add[u] add[u] = cap[u] active = [u for u in active if u not in capped] else: for u in active: add[u] += rem * w[u] / total rem = 0.0 return add, rem def plan(target_w, bounds, *, weights=None, live=None, scope_errors=(), site_priority=None, site_key="site") -> Allocation: """Divide the site grid target `target_w` across the units in `bounds`. `bounds` unit name -> that unit's interval for THIS TICK (arbiter stage 1, `UnitBounds`). Read per tick, never cached - see the module docstring. Duck-typed on `.lo`, `.hi`, `.gate`, `.pinned_w`, `.pinned_by` and `.contradiction` so that this module does not import the arbiter and cannot grow a dependency on claims. `weights` unit -> non-negative comfort weight. Missing units weigh 1.0. `live` the units whose master has reported recently enough to be commanded, or None for "all of them". A unit not listed is DROPPED and the record says so; the survivors then carry the whole site target, which is a real change in what the site can do and must never happen silently (AC 6). `scope_errors` the arbiter's mis-routing complaints. See REFUSE_SCOPE below. `site_priority` the priority of the SITE claim that chose `target_w`. It is what a unit's own winning SET is weighed against - see PINS. `site_key` the name to use when there are no units at all. ⚠️ N<=1 IS A PASS-THROUGH AND IS BYTE-IDENTICAL TO WHAT SHIPPED. The share IS the site target, as a float, unclamped and unrounded. That is §6.2's N=1 identity - with one inverter the fabricated grid reading and the battery setpoint are the same number - and it is also the compatibility promise: every existing test in this repository replays through here and must see the number it saw before ARB-03. Do not "tidy" this branch into the general path by giving it a roster of one; the general path rounds to an integer and applies the envelope, and both are behaviour changes on the live install. """ units = tuple(sorted(bounds)) # --- REFUSAL 1: the claim list that produced S is known to be mis-routed -- # ⚠️ THIS IS THE ANSWER TO ARB-03's OPEN QUESTION, AND IT IS A REFUSAL # RATHER THAN AN INPUT. `scope_violations()` reports a claim filed on an # actuator its source's scope does not permit. It is tempting to CONSUME # one - to read a unit-scoped claim that landed on the site as an allocation # input - and that is wrong twice over. First, by the time this function # runs the mis-routed claim has ALREADY been partitioned by `resolve()`, so # its effect is baked into S or into somebody's interval and cannot be # undone from here; consuming it would mean re-routing, which would make # `actuator` advisory and hand every filing site a second chance to be # wrong. Second, and worse, promoting a unit claim that landed on the site # requires guessing WHICH unit it belonged to, and there is no information # here to guess with - `actuator_for()` exists precisely because that answer # is chosen where the claim is built. Applying it to ALL units would put one # inverter's rating on a sibling that does not have it. # # So what is left is that S itself may be wrong, and dividing a number that # may be wrong is worse than not dividing it. Refuse, and let main.py fail # toward inaction and shout - which is the same answer clause 3 of the # arbiter's own rule already gives to a contradiction. # # ⚠️ IT IS ABOVE THE N<=1 PASS-THROUGH ON PURPOSE, and that is the one place # this card touches the pass-through's behaviour. A correctly routed # one-inverter cycle CANNOT produce a scope violation - `scope_violations()` # only complains about a unit source on the site when the site has named # units, and a site source on a unit requires somebody to have hand-written # `actuator=` past `actuator_for()` - so this cannot fire on the shipped # install, and where it does fire the input is a known bug rather than a # state to pass through. if scope_errors: return Allocation( target_w=float(target_w), sum_w=int(round(float(target_w))), shares={}, plans=(), dropped=(), unmet_w=int(round(float(target_w))), quantisation_w=float(int(round(float(target_w)))) - float(target_w), refused=f"{REFUSE_SCOPE}: " + "; ".join(scope_errors)) if len(units) <= 1: only = units[0] if units else site_key share = float(target_w) return Allocation( target_w=float(target_w), sum_w=int(round(share)), shares={only: share}, plans=(UnitPlan(only, int(round(share)), -inf, inf, 1.0, "N<=1: the share IS the site target"),), passthrough=True) w = {u: 1.0 if weights is None else float(weights.get(u, 1.0)) for u in units} for u, wu in w.items(): if wu < 0.0 or wu != wu: raise ValueError(f"weight for {u!r} is {wu!r}; weights are " "non-negative comfort factors, not signed targets") # ⚠️ THE TARGET IS ROUNDED ONCE, HERE, AND NOWHERE ELSE. Everything below # this line is integer arithmetic, which is what makes "the shares sum to S" # an identity rather than a tolerance. `round()` is banker's rounding: over a # long replay it is unbiased, where `int(x + 0.5)` would add a systematic # half-watt in the discharge direction. In practice `target_w` arrives from # `compute()` already quantised to `step_w` (10 W by default) so this is a # no-op on the live path; it is not a no-op for a peak-shaving floor or an # arbitrage setpoint, which are not quantised. sum_w = int(round(float(target_w))) quant = float(sum_w) - float(target_w) # --- the envelope set, rebuilt from scratch every tick ------------------- dropped = [] ilo, ihi = {}, {} considered = [] for u in units: b = bounds[u] if live is not None and u not in live: # AC 6. The survivor is about to carry this unit's share and the # record has to say so; `dropped` is how it says it, and main.py # logs the transition. dropped.append((u, DROP_STALE)) continue if getattr(b, "contradiction", False): # A unit contradicting ITSELF - its own `lo` above its own `hi`. # Stage 1 already decided that parks THAT unit and not the site, # which is the whole point of the partition; here it means the unit # has no interval to allocate into. dropped.append((u, DROP_CONTRADICTION)) continue lo, hi = _int_envelope(b) if lo > hi: # An interval that contains no integer. The register is 1 W, so # there is no number this unit could be commanded that both bounds # accept - dropping it is the only answer that does not violate one. dropped.append((u, DROP_NO_INTEGER)) continue ilo[u], ihi[u] = lo, hi considered.append(u) def refuse(why): return Allocation( target_w=float(target_w), sum_w=sum_w, shares={}, plans=(), dropped=tuple(dropped), unmet_w=sum_w, quantisation_w=quant, refused=why) # --- REFUSAL 2: nobody is available ------------------------------------ if not considered: return refuse(f"{REFUSE_EMPTY}: " + ", ".join(f"{u} ({why})" for u, why in dropped)) # --- PINS: a unit's own SET, weighed against the site's ------------------- # ⚠️ THIS IS THE DECISION ARB-03 DEFERRED TO HERE, IN ITS OWN WORDS: "Stage 1 # states the constraint and records what it is gated on; deciding whether it # applies is stage 3's business." `UnitBounds.gate` is the priority of the # unit's own winning SET; `site_priority` is the priority of the SITE claim # that chose S. Clause 1 of the arbiter's rule, transposed to a site with # more than one actuator: the higher priority wins, and a tie goes to the # unit, because a claim about one pack is more specific than a claim about # the connection and specificity is what a tie has left to break on. # # A pinned unit is NOT in the water-fill. It is doing something of its own - # a maintenance drain, a failsafe park - and what it does still counts # toward the site sum, so the free units carry the REMAINDER. That is not # the allocator compensating for a disturbance, which would be a second # controller; it is the shares summing to S, which is the invariant. The # meter's own answer arrives next tick through the one integrator above. # # ⚠️ AND site_priority=None MEANS "NO SITE SET WAS NAMED", so every pin # stands. `resolve()` always passes the real one. A direct caller that # passes nothing is saying it has no site claim to weigh, and honouring the # unit's own highest-priority claim is the only safe reading of that. pinned = {} for u in considered: b = bounds[u] gate = getattr(b, "gate", None) if gate is None: continue if site_priority is None or gate >= site_priority: pv = getattr(b, "pinned_w", None) if pv is None: continue pinned[u] = _clamp_int(round(float(pv)), ilo[u], ihi[u]) free = [u for u in considered if u not in pinned] remainder = sum_w - sum(pinned.values()) # --- WATER-FILL over the free units -------------------------------------- # `base` is the point of each envelope nearest zero: 0 for an ordinary # symmetric rating, and the forced end for an envelope that does not contain # zero. Filling from there rather than from `lo` is what keeps a unit that # is merely ALLOWED to charge from being TOLD to. base = {u: _clamp_int(0, ilo[u], ihi[u]) for u in free} placed = sum(base.values()) need = remainder - placed up = need >= 0 cap = {u: (ihi[u] - base[u]) if up else (base[u] - ilo[u]) for u in free} add, leftover = _fill(free, w, cap, abs(need)) exact = {u: base[u] + (add[u] if up else -add[u]) for u in free} # --- LARGEST-REMAINDER ROUNDING ----------------------------------------- # Floor every share, then hand out the discarded watts one at a time, worst # discarded fraction first. The sum is integer arithmetic end to end, so it # cannot drift; ties break on the unit name so that the same inputs give the # same allocation on every tick and on every host. share = {u: int(floor(exact[u] + EPS)) for u in free} for u in free: # floors can never leave the envelope, share[u] = _clamp_int(share[u], ilo[u], ihi[u]) # but say so anyway debt = remainder - sum(share.values()) frac_order = sorted(free, key=lambda u: (-(exact[u] - floor(exact[u])), u)) step = 1 if debt > 0 else -1 while debt != 0: moved = False for u in (frac_order if debt > 0 else list(reversed(frac_order))): if debt == 0: break nxt = share[u] + step if (step > 0 and nxt <= ihi[u]) or (step < 0 and nxt >= ilo[u]): share[u] = nxt debt -= step moved = True if not moved: break shares = dict(pinned) shares.update(share) unmet = sum_w - sum(shares.values()) # --- REFUSAL 3: SIGN COHERENCE, so circulating power is not expressible --- # ⚠️ REFUSED, NOT AVERAGED. Two shares of opposite sign mean one pack # discharging into the AC bus while another charges off it: energy round- # tripping through two conversion stages for no reason, and - this is the # part that makes it a safety property rather than an efficiency one - # INVISIBLE. The meter sees the net, which is exactly S, so the site # integrator is content; each unit sees a target it is meeting, so no # per-unit guard fires; the sign watchdog compares a command against the # meter and both agree. Nothing in this repository would ever report it. # # It cannot arise from an ordinary tick: the fill only ever moves shares in # ONE direction from a base that is zero whenever the envelope contains # zero, so opposite signs require an envelope that EXCLUDES zero (a forced # floor) or a pin. Those are the cases worth refusing, and the refusal is a # site-level one because the alternative - dropping the offending unit and # re-filling - would silently override a claim that outranked the loop. pos = sorted(u for u, s in shares.items() if s > 0) neg = sorted(u for u, s in shares.items() if s < 0) if pos and neg: return refuse( f"{REFUSE_SIGN}: {', '.join(pos)} would discharge while " f"{', '.join(neg)} charges - circulating power, which nets to " f"{sum_w:+d} W at the meter and is invisible to every guard") plans = [] for u in units: drop = dict(dropped).get(u) if drop is not None: plans.append(UnitPlan(u, 0, bounds[u].lo, bounds[u].hi, w[u], f"DROPPED: {drop}")) continue if u in pinned: by = getattr(bounds[u], "pinned_by", None) or "its own claim" plans.append(UnitPlan(u, pinned[u], ilo[u], ihi[u], w[u], f"pinned by {by} at priority " f"{bounds[u].gate}", pinned=True)) continue at_edge = share[u] in (ilo[u], ihi[u]) why = "weighted share" if at_edge and cap[u] - add[u] <= EPS and abs(need) > EPS: why = "envelope full - its surplus went to the others" elif w[u] <= 0.0 and share[u] != base[u]: why = "last resort: the preferred units were full" plans.append(UnitPlan(u, share[u], ilo[u], ihi[u], w[u], why, clamped=at_edge)) return Allocation(target_w=float(target_w), sum_w=sum_w, shares=shares, plans=tuple(plans), dropped=tuple(dropped), unmet_w=int(unmet), quantisation_w=quant)