adminandClaude Opus 5
5d7e275df4
checks / unit (pull_request) Successful in 5m16s
`slew_w: 1000` was derived on 2026-08-22 against a clamp of 1500 W, where "capping how far the loop can jump ahead of the inverter" was true because the rail itself bounded the excursion. The live install went to max_w 5000 and the constant did not move, so the loop crosses its whole output range in 10 s against a plant NOTES.md §5.10 measured at ~18 s. Measured on the owner's system 2026-09-05 11:43-11:46: a 3.4 kW export drove the setpoint 380 -> 5000 W in five 2 s ticks, the battery to -5154 W past a 5000 VA rating, and the grid from 3.4 kW of EXPORT to 2.8 kW of IMPORT. Nothing was broken; the rail moved. REPRODUCED FIRST, and one half of it is not reproducible at all. On plantsim.Plant and on an independent in-repo model: the setpoint stepping a full 1000 W per tick to the rail (48 of 51 export steps), and the meter crossing from export into import. The -5154 W figure is NOT reproducible in either model, because both clamp the plant at its rating - so the card's AC "battery no longer exceeds max_w in simulation" is unfalsifiable and was rewritten rather than met. THE DELIVERABLE IS THE RELATIONSHIP. SLEW_RAIL_FRAC = LOOP_TICK_S / PLANT_SETTLE_S = 2 s / 18 s = 1/9 slew_w = 0 now means FOLLOW THE RAIL - SLEW_RAIL_FRAC * max_w - exactly as integrator_max_w = 0 already means follow max_w. It is the shipped default: 222 W at max_w 2000, 556 W at 5000, 1067 W at a ~9600 W two-inverter site. validate.py rule 10 refuses an explicit value faster than that, graded against sum(unit_caps(opts)) - the roster sum, i.e. Controller.site_max_w - so a second inverter moves the bound with no operator action. VERIFIED BY BREAKING IT: restoring slew_w 1000 at max_w 5000 is refused, and the refusal names the rail, the crossing time, the measurement and what to do. Equality, one watt of slack, the live interim 400 and slew_w 0 at every rating all still start. GAIN IS THE CONSTANT THAT IS STILL WRONG, and it is NOT changed here. Over 51 export steps the over-absorption is FLAT in slew (958 W at 1000, 1081 W at 250) and monotone in gain (987 W at 0.6, 876 at 0.3, 435 at 0.2): slew_w bounds the OUTPUT, while the integrator moves gain*error per cycle and reaches a 5000 W rail in under three ticks whatever the slew is. Two control-law constants moving in one release on a running house makes the next measurement uninterpretable. ⚠️ N=2: the site rail becomes sum(max_w) ~ 9600 W (inverter B FROM DATASHEET AND SERIAL, not measured, and sim/plantsim.py's INVERTER_B is A copied), and the enforced ratio produces 1067 W there automatically. But a growing rail LOOSENS this bound, and the >= 900 W symptom goes stale at N=2 the same way the constant did - both stated in the record rather than left to be discovered. Nothing reached the inverter. The live install still runs the interim slew_w 400 applied by hand on 2026-09-05, which rule 10 accepts unchanged. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BwRLw7eKYj2byVdwB6kbjU
683 lines
37 KiB
Python
683 lines
37 KiB
Python
"""Runnable check for the control law. `python3 test_control.py`
|
|
|
|
No framework, no fixtures - it needs to run on a tech's laptop and in CI with
|
|
nothing installed. Every assert here corresponds to a rule that exists because
|
|
its absence caused an observed failure on real hardware.
|
|
|
|
If you change control.py, run this. If it fails, the inverter would have done
|
|
something you did not intend.
|
|
|
|
⚠️ MUTATING THE MODULE THIS FILE GRADES? PURGE `__pycache__` FIRST - or run
|
|
`tools/mutation_run.sh`, which does. `python3 -B` alone does NOT save you: it
|
|
stops bytecode being WRITTEN, not a stale one being READ, and a size-preserving
|
|
edit reverted inside one second is invisible to CPython's staleness test. That
|
|
is TEST-15, and it has already turned one live mutation into a false survivor.
|
|
Read MUTATION.md before you report a survivor.
|
|
"""
|
|
|
|
import sys
|
|
|
|
from app.control import (LOOP_TICK_S, PLANT_SETTLE_S, SLEW_RAIL_FRAC,
|
|
Tuning, compute, slew_limit_w,
|
|
maintenance_charge_floor, peak_at_risk)
|
|
|
|
# ⚠️ SAFETY-39: `slew_w` IS EXPLICIT HERE NOW, AND IT IS release/1.0's VALUE.
|
|
# `Tuning()`'s default became 0 - "follow the rail", `SLEW_RAIL_FRAC * max_w`,
|
|
# 222 W against this 2000 W rail - so a bare `Tuning()` here would silently
|
|
# re-tune every assertion below that the slew limit touches, and several of them
|
|
# assert on a number the slew produces. The pair written here (max_w 2000,
|
|
# slew_w 1000) is exactly what release/1.0 shipped, which is what most of this
|
|
# file is a regression test against. The new default gets its own section at the
|
|
# end, where it is the subject rather than a hidden parameter.
|
|
T = Tuning(slew_w=1000.0)
|
|
fails = []
|
|
|
|
|
|
def check(name, cond):
|
|
if cond:
|
|
print(f" ok {name}")
|
|
else:
|
|
print(f" FAIL {name}")
|
|
fails.append(name)
|
|
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# COVERAGE AUDIT - measured, not executed. Read this before adding a mechanism.
|
|
#
|
|
# THE INVARIANT: every mechanism in compute() must be noticed by AT LEAST TWO
|
|
# checks when it is deleted. If you add a mechanism to compute(), re-run the
|
|
# audit and add it to the table. If a figure here drops, a check has started
|
|
# passing for a reason other than the one it names.
|
|
#
|
|
# THE TECHNIQUE, because there is no script to run: replace one mechanism in
|
|
# control.py with a no-op, run this file, count the failures, restore. That is
|
|
# the converse of the usual mutation - not "does a wrong value fail?" but "does
|
|
# anyone notice when the mechanism is GONE?". It is kept as a comment rather
|
|
# than as tooling on purpose: the only cheap way to automate it is to key on
|
|
# source lines, which goes stale silently, and a green audit that has quietly
|
|
# stopped testing anything is precisely the failure this ticket exists to fix.
|
|
# A comment cannot go stale-green, because it never claims to be running.
|
|
#
|
|
# Measured at 389d9ec. Numbers are the lead's independent reproduction.
|
|
# ⚠️ THE SLEW ROWS WERE RE-MEASURED AT SAFETY-39 AND ONE OF THEM MOVED: the
|
|
# slew limit was 4 and is now 5, because the SAFETY-39 section grades it too.
|
|
# The new row is the RAIL DEFAULT specifically - `slew_limit_w()` reduced to
|
|
# `return abs(float(tuning.slew_w))`, which leaves the limit intact and only
|
|
# removes the 0-means-the-rail resolution. Three checks notice, which is over
|
|
# the invariant's floor of two. Both figures were reproduced by deleting the
|
|
# mechanism, running this file and counting, on a tree with __pycache__ purged.
|
|
#
|
|
# mechanism in compute() checks that fail when deleted
|
|
# ------------------------------------------ -----------------------------
|
|
# integrator freeze (AC 3) 2
|
|
# integrator clamp (AC 1) 6
|
|
# integrator bound follows max_w 4
|
|
# output clamp 3
|
|
# slew limit 5
|
|
# slew follows the rail (SAFETY-39), `slew_w` read raw 3
|
|
# output freeze 2
|
|
# deadband 5
|
|
# quantisation 2
|
|
# saturation detector, `saturated_now = False` 11
|
|
# saturation duration (AC 2), fires instantly 2
|
|
# sat counter reset on a good cycle 6
|
|
# target_grid_w bias 3
|
|
# i_w=None seeding from prev_w 6
|
|
#
|
|
# The detector figure is for the `saturated_now = False` form specifically;
|
|
# disabling it further down as `frozen = False` is a weaker mutation and gives
|
|
# 10. Reproduce the same form or the number will not match.
|
|
#
|
|
# ⚠️ IT HAS FOUND A DEAD MECHANISM TWICE, BOTH THE SAME WAY: a clamp standing in
|
|
# for the mechanism under test. Deleting the integrator freeze once failed
|
|
# NOTHING, because the fixtures sat at max_w 2000 and the integrator bound
|
|
# truncated a wound value back to exactly 2000 - the assertion passed on the
|
|
# clamp. The output clamp was masked the same way by the integrator bound.
|
|
# Hence: A FIXTURE MUST SIT CLEAR OF EVERY RAIL IT IS NOT TESTING. Where a test
|
|
# names one mechanism, make that mechanism the binding one (see TCLAMP and TF).
|
|
#
|
|
# ⚠️ RUN MUTATIONS THROUGH `tools/mutation_run.sh`, WHICH CLEARS __pycache__
|
|
# BEFORE IT RUNS ANYTHING. CPython invalidates a .pyc on (source mtime in whole
|
|
# seconds, source size), so a same-second rewrite that also preserves the file
|
|
# size reuses stale bytecode and the suite reports on code you are no longer
|
|
# running. It under-reported one mutation here as 2 where the true figure is 6.
|
|
#
|
|
# ⚠️ AND THE CLEAR IS THE HALF THAT WORKS. This note used to lead with
|
|
# `python -B`; TEST-15 measured what that flag actually does, and it is
|
|
# write-only - it does not stop an EXISTING stale .pyc being read, and a
|
|
# mutation run always has one, because the previous run wrote it. -B is still
|
|
# worth passing, for the NEXT edit rather than this one.
|
|
#
|
|
# The error is one-directional - stale bytecode can only under-report - so
|
|
# every figure above is a lower bound at worst, and the two zeros ever recorded
|
|
# were both confirmed by fixing them and watching the count rise, which a
|
|
# caching artefact cannot do.
|
|
# ---------------------------------------------------------------------------
|
|
|
|
print("control law")
|
|
|
|
# Deadband: inside meter noise, hold exactly - do not drift.
|
|
d = compute(prev_w=900, grid_w=10, actual_w=900, tuning=T)
|
|
check("deadband holds the command", d.target_w == 900 and d.reason == "deadband")
|
|
|
|
d = compute(prev_w=900, grid_w=20, actual_w=900, tuning=T)
|
|
check("outside deadband it acts", d.target_w != 900)
|
|
|
|
# Proportional: 0 + 0.6*500 = 300
|
|
d = compute(prev_w=0, grid_w=500, actual_w=0, tuning=T)
|
|
check("proportional step (gain 0.6)", d.target_w == 300)
|
|
|
|
# Sign: exporting (negative grid) must CHARGE (negative target).
|
|
d = compute(prev_w=0, grid_w=-500, actual_w=0, tuning=T)
|
|
check("export drives charging", d.target_w == -300)
|
|
|
|
# Clamp.
|
|
# ⚠️ integrator_max_w is lifted clear of max_w so that the OUTPUT clamp is the
|
|
# mechanism under test. Left at the default the integrator bound truncates
|
|
# first, these two assertions pass on that alone, and deleting the output clamp
|
|
# fails nothing - the same masking that hid the integrator freeze.
|
|
TCLAMP = Tuning(max_w=2000, slew_w=5000, integrator_max_w=5000)
|
|
d = compute(prev_w=1900, grid_w=1000, actual_w=1900, tuning=TCLAMP)
|
|
check("clamped to max_w", d.target_w == 2000)
|
|
|
|
# Slew: from 0 with a huge error, no more than slew_w in one cycle.
|
|
d = compute(prev_w=0, grid_w=5000, actual_w=0, tuning=Tuning(max_w=5000, slew_w=1000))
|
|
check("slew limits one cycle", d.target_w == 1000)
|
|
d = compute(prev_w=-1900, grid_w=-1000, actual_w=-1900, tuning=TCLAMP)
|
|
check("clamped to -max_w", d.target_w == -2000)
|
|
d = compute(prev_w=0, grid_w=-5000, actual_w=0, tuning=Tuning(max_w=5000, slew_w=1000))
|
|
check("slew limits one cycle, charging", d.target_w == -1000)
|
|
|
|
# Saturation needs DURATION: one diverging cycle must NOT freeze.
|
|
t = Tuning(saturation_w=500, saturation_cycles=3)
|
|
d1 = compute(prev_w=2000, grid_w=500, actual_w=1000, tuning=t, sat_count=0)
|
|
check("one saturated cycle does not freeze", not d1.frozen and d1.sat_count == 1)
|
|
d2 = compute(prev_w=2000, grid_w=500, actual_w=1000, tuning=t, sat_count=d1.sat_count)
|
|
d3 = compute(prev_w=2000, grid_w=500, actual_w=1000, tuning=t, sat_count=d2.sat_count)
|
|
check("three consecutive saturated cycles freeze", d3.frozen)
|
|
check("freeze forbids raising magnitude", d3.target_w <= 2000)
|
|
|
|
# ...and one good cycle clears the counter immediately.
|
|
d4 = compute(prev_w=2000, grid_w=500, actual_w=1990, tuning=t, sat_count=3)
|
|
check("counter resets when tracking resumes", d4.sat_count == 0 and not d4.frozen)
|
|
|
|
# Freeze must still allow the magnitude to FALL (that is the escape route).
|
|
d = compute(prev_w=2000, grid_w=-800, actual_w=1000, tuning=t, sat_count=3)
|
|
check("freeze still allows magnitude to fall", d.target_w < 2000)
|
|
|
|
# Maintenance shaping (charge-only, cheap-window floor) is no longer this
|
|
# function's business - it is expressed as limit claims. See test_arbiter.py.
|
|
|
|
# Quantisation
|
|
d = compute(prev_w=0, grid_w=7, actual_w=0, tuning=Tuning(deadband_w=1, step_w=10))
|
|
check("quantised to step_w", d.target_w % 10 == 0)
|
|
|
|
print("SAFETY-04: the integrator is bounded apart from the output")
|
|
|
|
# The historical runaway, with its real numbers. A commercial controller on
|
|
# this site, with the inverter switched OFF, wound ~130 W every 4 s past 10 kW
|
|
# and reported 14 768 W while its output clamp sat at 5 kW. At gain 0.6 that
|
|
# rate is a standing error of 130/0.6 = 217 W that never resolves, because the
|
|
# inverter is not there to resolve it. 150 cycles is past the ~113 it took to
|
|
# reach 14 768 W at that rate.
|
|
RUNAWAY_ERROR = 130.0 / 0.6
|
|
RUNAWAY_CYCLES = 150
|
|
HISTORICAL_W = 14768.0
|
|
|
|
|
|
def runaway(tuning, sign=1):
|
|
"""Inverter off: it reports 0 W forever, the error never clears."""
|
|
prev, i_w, sat = 0.0, 0.0, 0
|
|
worst_i, worst_cmd = 0.0, 0.0
|
|
for _ in range(RUNAWAY_CYCLES):
|
|
d = compute(prev_w=prev, grid_w=sign * RUNAWAY_ERROR, actual_w=0.0,
|
|
tuning=tuning, sat_count=sat, i_w=i_w)
|
|
prev, i_w, sat = d.target_w, d.i_w, d.sat_count
|
|
worst_i = max(worst_i, abs(i_w))
|
|
worst_cmd = max(worst_cmd, abs(prev))
|
|
return worst_i, worst_cmd
|
|
|
|
|
|
TR = Tuning(max_w=2000) # integrator_max_w unset => follows max_w
|
|
wi, wc = runaway(TR)
|
|
check(f"runaway: integrator plateaus at {wi:.0f} W (<= 2000)", wi <= TR.max_w)
|
|
check(f"runaway: emitted command peaks at {wc:.0f} W (<= 2000)", wc <= TR.max_w)
|
|
check("runaway: nowhere near the historical 14 768 W", wc < HISTORICAL_W / 4)
|
|
|
|
# ...and with the saturation detector deliberately defeated, so that only the
|
|
# clamp is holding. Kill one mechanism, the other still bounds it.
|
|
TD = Tuning(max_w=2000, saturation_w=1e9)
|
|
wi, wc = runaway(TD)
|
|
check(f"runaway with the detector defeated: integrator still bounded ({wi:.0f} W)",
|
|
wi <= TD.max_w)
|
|
check("runaway with the detector defeated: command still <= max_w", wc <= TD.max_w)
|
|
|
|
# The mirror: the same runaway driving the other way. An export that never
|
|
# clears winds the integrator negative just as hard.
|
|
wi, wc = runaway(Tuning(max_w=2000), sign=-1)
|
|
check(f"runaway (export direction): integrator bounded at {wi:.0f} W", wi <= 2000)
|
|
check("runaway (export direction): emitted command <= max_w", wc <= 2000)
|
|
|
|
# The bound is a separate quantity, and the useful direction is BELOW max_w:
|
|
# there it binds first and caps unwind latency tighter than the rail does.
|
|
d = compute(prev_w=0, grid_w=6000, actual_w=0,
|
|
tuning=Tuning(max_w=2000, integrator_max_w=1000, slew_w=5000))
|
|
check("integrator bound binds independently of the output clamp",
|
|
d.i_w == 1000 and d.target_w == 1000)
|
|
|
|
# Freeze = may not wind further in the direction it is already pushing.
|
|
# ⚠️ max_w is raised WELL above the fixtures on purpose. At the default 2000
|
|
# the integrator bound truncates a wound value back to exactly 2000 and
|
|
# satisfies these assertions on its own, so deleting the freeze outright
|
|
# failed nothing - the clamp was standing in for the mechanism under test.
|
|
# Any fixture here must sit clear of every rail, or it tests the rail.
|
|
TF = Tuning(saturation_w=500, saturation_cycles=3, max_w=5000)
|
|
f1 = compute(prev_w=2000, grid_w=800, actual_w=0, tuning=TF, sat_count=3, i_w=2000.0)
|
|
check("frozen: integration does not wind further", f1.i_w == 2000.0 and f1.frozen)
|
|
f2 = compute(prev_w=2000, grid_w=-800, actual_w=0, tuning=TF, sat_count=3, i_w=2000.0)
|
|
check("frozen: unwinding is still allowed", f2.i_w < 2000.0)
|
|
# ...and the same two on the charging side. Every freeze rule in this file has
|
|
# a mirror, because the one that did not is the defect that got through review.
|
|
f3 = compute(prev_w=-2000, grid_w=-800, actual_w=0, tuning=TF, sat_count=3, i_w=-2000.0)
|
|
check("frozen (charging): integration does not wind further", f3.i_w == -2000.0)
|
|
f4 = compute(prev_w=-2000, grid_w=800, actual_w=0, tuning=TF, sat_count=3, i_w=-2000.0)
|
|
check("frozen (charging): unwinding is still allowed", f4.i_w > -2000.0)
|
|
|
|
# ⚠️ REGRESSION, and the reason the first cut of SAFETY-04 was rejected. A
|
|
# freeze encoded as "only corrections that shrink |i_w|" is unsatisfiable for
|
|
# BOTH signs of error whenever |correction| > 2*|i_w|, so near zero the loop
|
|
# stops moving forever - the freeze cannot clear, because clearing it needs the
|
|
# inverter to track and not-tracking is what saturation means. Measured on that
|
|
# encoding: 0 W held into a 2 kW import for as long as the sim ran.
|
|
z = compute(prev_w=0, grid_w=2000, actual_w=600, tuning=T, sat_count=3, i_w=0.0)
|
|
check("frozen at i_w=0: a 2 kW import still moves the command",
|
|
z.frozen and z.target_w == 1000)
|
|
# ...and the next cycle the inverter is inside saturation_w of the command, so
|
|
# the freeze clears on its own. Deadlock would show up here as frozen=True.
|
|
z2 = compute(prev_w=1000, grid_w=1000, actual_w=600, tuning=T,
|
|
sat_count=z.sat_count, i_w=z.i_w)
|
|
check("frozen at i_w=0: the freeze then clears", not z2.frozen)
|
|
# Same stranding on the other side: a small positive integrator against export.
|
|
z3 = compute(prev_w=100, grid_w=-1000, actual_w=800, tuning=T, sat_count=3, i_w=100.0)
|
|
check("frozen at i_w=+100: a 1 kW export still moves the command",
|
|
z3.frozen and z3.target_w < 0)
|
|
z4 = compute(prev_w=-100, grid_w=1000, actual_w=-800, tuning=T, sat_count=3, i_w=-100.0)
|
|
check("frozen at i_w=-100: a 1 kW import still moves the command",
|
|
z4.frozen and z4.target_w > 0)
|
|
|
|
# ⚠️ EXACTLY ZERO, BOTH DIRECTIONS. This boundary has a history: the first cut
|
|
# deadlocked here under import, and the fix for it deadlocked here under export
|
|
# because `if i_w > 0 ... else ...` files 0.0 under rising-only. main.py resets
|
|
# i_w to exactly 0.0 on every stop and every reseed, so it is a normal state,
|
|
# not a corner.
|
|
zi = compute(prev_w=0, grid_w=2000, actual_w=600, tuning=T, sat_count=3, i_w=0.0)
|
|
check("frozen at i_w=0.0: an import push moves the integrator",
|
|
zi.frozen and zi.i_w > 0)
|
|
ze = compute(prev_w=0, grid_w=-2000, actual_w=-600, tuning=T, sat_count=3, i_w=0.0)
|
|
check("frozen at i_w=0.0: an export push moves the integrator",
|
|
ze.frozen and ze.i_w < 0)
|
|
# The COMMAND still holds at 0 W in that second case, and that is release/1.0's
|
|
# rule, not a leftover: at prev_w == 0 the output freeze forbids starting to
|
|
# charge while saturated, because commanding 0 while the inverter reports
|
|
# hundreds of watts means something else is driving the bus. Asserted so that
|
|
# nobody "fixes" it by accident - the integrator moving is what this ticket
|
|
# owns, the command rule belongs to the output freeze.
|
|
check("frozen at i_w=0.0: the output freeze still blocks a charge from 0 W",
|
|
ze.target_w == 0.0)
|
|
# Where prev_w is already charging the output freeze does NOT block, and there
|
|
# the difference reaches the wire: held at 0.0 the integrator abandons the
|
|
# charge mid-export.
|
|
zc = compute(prev_w=-2000, grid_w=-4000, actual_w=-600, tuning=T, sat_count=3, i_w=0.0)
|
|
check("frozen at i_w=0.0: a charge is not abandoned during heavy export",
|
|
zc.target_w == -2000.0)
|
|
|
|
# The general property, rather than another handful of points: while frozen the
|
|
# integrator may be held ONLY when the correction would push it further from
|
|
# zero on the side it already sits. Any other hold is a deadlock.
|
|
stuck = []
|
|
for i0 in [x * 25.0 for x in range(-80, 81)]:
|
|
for g in [x * 100.0 for x in range(-40, 41)]:
|
|
err = g - T.target_grid_w
|
|
if abs(err) < T.deadband_w:
|
|
continue
|
|
dd = compute(prev_w=0.0, grid_w=g, actual_w=1500.0, tuning=T, sat_count=3, i_w=i0)
|
|
if dd.i_w == i0 and not ((i0 > 0 and err > 0) or (i0 < 0 and err < 0)):
|
|
stuck.append((i0, g))
|
|
check(f"frozen integrator never deadlocks, over {161*81} states"
|
|
+ (f" (e.g. {stuck[0]})" if stuck else ""), not stuck)
|
|
|
|
# False-positive guard: a normal 2 kW load step must not trip the detector,
|
|
# because the plant needs several cycles to catch up on every one of them.
|
|
prev, actual, sat, i_w, froze = 0.0, 0.0, 0, 0.0, False
|
|
for _ in range(12):
|
|
d = compute(prev, 2000.0 - actual, actual, T, sat, i_w)
|
|
prev, sat, i_w = d.target_w, d.sat_count, d.i_w
|
|
actual = actual + 0.94 * (prev - actual)
|
|
froze = froze or d.frozen
|
|
check("a normal 2 kW load step does not trip the saturation freeze", not froze)
|
|
|
|
# The convergence sim below runs WITHOUT a carried integrator. This is the same
|
|
# 2 kW step in the configuration that actually ships, where main.py carries it.
|
|
prev, actual, sat, i_w = 0.0, 0.0, 0, 0.0
|
|
carried = 0
|
|
for _ in range(12):
|
|
d = compute(prev, 2000.0 - actual, actual, T, sat, i_w)
|
|
prev, sat, i_w = d.target_w, d.sat_count, d.i_w
|
|
actual = actual + 0.94 * (prev - actual)
|
|
carried += 1
|
|
if abs(2000.0 - actual) < T.deadband_w:
|
|
break
|
|
check(f"carried integrator converges in {carried} cycles (<=6)", carried <= 6)
|
|
check("carried integrator does not overshoot the load", actual <= 2000.0 + T.deadband_w)
|
|
|
|
# ⚠️ REGRESSION: an integrator allowed to wind past the rail buys nothing (the
|
|
# output clamp already bounds the wire) and costs extra cycles of
|
|
# wrong-direction power after every saturation event. 4000 W load held to
|
|
# saturation, then dropped to 0; the figure is the command on the first cycle
|
|
# after the drop. This is what makes the DOCS advice checkable.
|
|
def unwind(t):
|
|
prev, actual, sat, i_w, load = 0.0, 0.0, 0, 0.0, 4000.0
|
|
for c in range(16):
|
|
if c == 15:
|
|
load = 0.0
|
|
d = compute(prev, load - actual, actual, t, sat, i_w)
|
|
prev, sat, i_w = d.target_w, d.sat_count, d.i_w
|
|
actual = actual + 0.94 * (prev - actual)
|
|
return prev
|
|
|
|
|
|
# ⚠️ BOTH FIXTURES CARRY release/1.0's `slew_w` EXPLICITLY (SAFETY-39). The
|
|
# subject here is `integrator_max_w`, and the figure the check names - 1000 W on
|
|
# the first cycle after the drop - is `max_w - slew_w`, so it moves with the slew
|
|
# limit and would stop being the number DOCS.md quotes. Pinning it keeps this a
|
|
# test about integrator headroom instead of a test about two mechanisms at once;
|
|
# the shipped default's own unwind is measured in the SAFETY-39 section below.
|
|
tight = unwind(Tuning(max_w=2000, slew_w=1000.0))
|
|
loose = unwind(Tuning(max_w=2000, slew_w=1000.0, integrator_max_w=3000))
|
|
check(f"after saturation ends the command is {tight:.0f} W (<= 1000)", tight <= 1000)
|
|
check(f"headroom above max_w makes that worse ({loose:.0f} W) - hence the default",
|
|
loose > tight)
|
|
|
|
print("SAFETY-04: the i_w=None path is still release/1.0, exactly")
|
|
|
|
|
|
def legacy(prev, grid, actual, t, sat_count):
|
|
"""release/1.0's control law, transcribed. Do not 'improve' this."""
|
|
reason = "tracking"
|
|
sc = min(sat_count + 1, 10) if abs(prev - actual) > t.saturation_w else 0
|
|
frozen = sc >= t.saturation_cycles
|
|
error = grid - t.target_grid_w
|
|
if abs(error) < t.deadband_w:
|
|
want, reason = prev, "deadband"
|
|
else:
|
|
want = prev + t.gain * error
|
|
target = max(-t.max_w, min(t.max_w, want))
|
|
if target != want:
|
|
reason = "clamped"
|
|
slewed = max(prev - t.slew_w, min(prev + t.slew_w, target))
|
|
if slewed != target:
|
|
reason = "slew-limited"
|
|
target = slewed
|
|
if frozen:
|
|
target = min(target, prev) if prev > 0 else max(target, prev)
|
|
reason = "saturated-freeze"
|
|
step = max(1, int(t.step_w))
|
|
return float(round(target / step) * step), sc, frozen, reason
|
|
|
|
|
|
# ⚠️ Compare EVERYTHING observable, not just the number. A previous version of
|
|
# this sweep compared (target_w, sat_count) only and passed 3024 cases while
|
|
# `reason` had silently lost a value - which is the kind of thing a sweep this
|
|
# broad exists to catch. `frozen` and `reason` are both in the tuple now.
|
|
#
|
|
# The one deliberate rename: what release/1.0 called "clamped" is now
|
|
# "i-clamped", because the truncation happens on the integrator before the
|
|
# command is derived from it. Aliased here rather than papered over - if any
|
|
# OTHER reason ever diverges, this check goes red.
|
|
ALIAS = {"i-clamped": "clamped"}
|
|
diffs = []
|
|
seen = set()
|
|
# ⚠️ `slew_w` IS WRITTEN OUT IN ALL THREE (SAFETY-39). `legacy()` below is a
|
|
# TRANSCRIPTION of release/1.0 and reads `t.slew_w` directly, as release/1.0
|
|
# did; the new law reads `slew_limit_w(t)`, which treats 0 as 'follow the
|
|
# rail'. The two agree for every non-zero value and differ at 0 BY DESIGN, so
|
|
# a fixture that left the field at its new default would report the design as
|
|
# a regression. Fixing it in `legacy()` instead would make this sweep compare
|
|
# the new law against itself, which is the one thing it must never do.
|
|
for tune in (Tuning(slew_w=1000.0), Tuning(slew_w=1000.0, target_grid_w=-10.0),
|
|
Tuning(max_w=5000, slew_w=5000)):
|
|
for prev in (-2000.0, -500.0, -100.0, 0.0, 100.0, 500.0, 2000.0):
|
|
for grid in (-6000.0, -1000.0, -500.0, -14.0, 0.0, 14.0, 500.0, 1000.0, 6000.0):
|
|
for actual in (-2000.0, 0.0, 600.0, 2000.0):
|
|
for sc in (0, 2, 3, 9):
|
|
d = compute(prev, grid, actual, tune, sc) # i_w defaults to None
|
|
seen.add(d.reason)
|
|
got = (d.target_w, d.sat_count, d.frozen,
|
|
ALIAS.get(d.reason, d.reason))
|
|
if got != legacy(prev, grid, actual, tune, sc):
|
|
diffs.append((prev, grid, actual, sc, got,
|
|
legacy(prev, grid, actual, tune, sc)))
|
|
check(f"i_w=None reproduces release/1.0 over {3*7*9*4*4} cases, reason included"
|
|
+ (f" (first diff {diffs[0]})" if diffs else ""), not diffs)
|
|
|
|
# ...and the rename is not a quiet deletion: the signal SAFETY-03 alarms on has
|
|
# to actually occur in that sweep, or its hook is dead.
|
|
check("the integrator clamp reports itself as 'i-clamped'", "i-clamped" in seen)
|
|
|
|
# "clamped" stays reachable, but only where the integrator is deliberately
|
|
# allowed above the rail - then BOTH fire and the output clamp, which describes
|
|
# the value actually emitted, is the one reported.
|
|
dc = compute(prev_w=0, grid_w=6000, actual_w=0,
|
|
tuning=Tuning(max_w=2000, integrator_max_w=3000, slew_w=5000))
|
|
check("the output clamp still reports 'clamped' when it is the binding one",
|
|
dc.reason == "clamped" and dc.i_w == 3000 and dc.target_w == 2000)
|
|
|
|
print("capacity tariff")
|
|
check("no forecast means no cap", maintenance_charge_floor(2500, None, 3500) == 2500)
|
|
check("headroom caps the charge", maintenance_charge_floor(2500, 2000, 3500) == 1500)
|
|
check("no headroom means no charge", maintenance_charge_floor(2500, 4000, 3500) == 0)
|
|
check("peak risk detected", peak_at_risk(4000, 3500) is True)
|
|
check("peak risk off without forecast", peak_at_risk(None, 3500) is False)
|
|
|
|
print("behaviour: 2 kW load step converges")
|
|
# Closed-loop sim. The plant is modelled as first-order-ish: it moves most of
|
|
# the way to the command each cycle (measured: 94 % by 3.3 s against a ~5 s
|
|
# cycle). House load steps by 2000 W at t=0.
|
|
prev, actual, sat, load = 0.0, 0.0, 0, 2000.0
|
|
cycles = 0
|
|
for i in range(12):
|
|
grid = load - actual # what the meter sees
|
|
d = compute(prev, grid, actual, T, sat)
|
|
prev, sat = d.target_w, d.sat_count
|
|
actual = actual + 0.94 * (prev - actual) # plant follows
|
|
cycles += 1
|
|
if abs(load - actual) < T.deadband_w:
|
|
break
|
|
check(f"converges within deadband in {cycles} cycles (<=6)", cycles <= 6)
|
|
check("no overshoot past the load", actual <= load + T.deadband_w)
|
|
|
|
print("grid bias: the deadband must not rest on the import register")
|
|
# The billed asymmetry: import and export are separate registers, so a resting
|
|
# point inside the deadband on the import side is paid for every second it
|
|
# holds. 14 W held all day is 0.34 kWh.
|
|
T0 = Tuning(target_grid_w=0.0)
|
|
TB = Tuning(target_grid_w=-10.0)
|
|
check("unbiased, +14 W import rests forever",
|
|
compute(500.0, 14.0, 500.0, T0).reason == "deadband")
|
|
d = compute(500.0, 14.0, 500.0, TB)
|
|
check("biased, the same +14 W is corrected", d.reason != "deadband" and d.target_w > 500.0)
|
|
check("biased, a small export rests", compute(500.0, -10.0, 500.0, TB).reason == "deadband")
|
|
check("biased, the band still ends before -25 W",
|
|
compute(500.0, -30.0, 500.0, TB).reason != "deadband")
|
|
# Worst-case billed leak: the band is [bias - deadband, bias + deadband], so it
|
|
# drops from 15 W to 5 W. Set target_grid_w to -deadband_w to remove it entirely,
|
|
# at the cost of giving that much away as export.
|
|
check("worst billed rest point falls from 15 W to under 5 W",
|
|
compute(500.0, 4.9, 500.0, TB).reason == "deadband"
|
|
and compute(500.0, 5.0, 500.0, TB).reason != "deadband")
|
|
|
|
print("SAFETY-39: the slew limit is a RATIO to the rail, not a number")
|
|
# ⚠️ WHAT WENT WRONG, IN ONE LINE, BECAUSE THE SHAPE IS THE POINT. `slew_w:
|
|
# 1000` was derived on 2026-08-22 against a clamp of 1500 W and its stated
|
|
# justification was that it caps "how far the loop can jump ahead of the
|
|
# inverter". The live install then ran max_w 5000 with the same 1000, and on
|
|
# 2026-09-05 11:43-11:46 a real 3.4 kW export drove the setpoint 380 -> 5000 W
|
|
# in five 2 s ticks, the battery to -5154 W against a 5000 VA inverter, and the
|
|
# grid from 3.4 kW of EXPORT to 2.8 kW of IMPORT. Nothing was broken. The rail
|
|
# moved and the constant did not.
|
|
#
|
|
# So what is graded below is the RELATIONSHIP and not a value: at every rail,
|
|
# the loop takes the plant's own settling time to cross its whole output range.
|
|
# A check that pinned "555 W" would go stale the same way the comment did.
|
|
print(f" SLEW_RAIL_FRAC = LOOP_TICK_S / PLANT_SETTLE_S = {SLEW_RAIL_FRAC:.4f}"
|
|
f" ({1 / SLEW_RAIL_FRAC:.0f} ticks to cross the rail)")
|
|
check("0 means FOLLOW THE RAIL and resolves to SLEW_RAIL_FRAC * max_w",
|
|
slew_limit_w(Tuning(max_w=5000.0, slew_w=0.0)) == SLEW_RAIL_FRAC * 5000.0)
|
|
check("an explicit value is passed through untouched - it is the operator's "
|
|
"number and nothing here silently reduces it",
|
|
slew_limit_w(Tuning(max_w=5000.0, slew_w=400.0)) == 400.0)
|
|
check("the shipped Tuning default is 0, i.e. the rail, so the law carries no "
|
|
"second constant to go stale beside config.yaml",
|
|
Tuning().slew_w == 0.0)
|
|
|
|
# ⭐ THE RELATIONSHIP ITSELF, over every rail this add-on can be built at: the
|
|
# single-inverter schema range (100..5000), the live install (5000), and the
|
|
# roster sums a second inverter produces - 9600 with inverter B's datasheet
|
|
# figure, 10000 with two of A. ⚠️ 9600 IS NOT A MEASUREMENT: inverter B does not
|
|
# exist on site yet (SPIKE-04, ~2026-09-12) and 4600 W is its datasheet and
|
|
# serial, per goodwe/NOTES.md §1.1b. It is here because the ARITHMETIC is what
|
|
# is being graded, and the arithmetic does not care.
|
|
_rails = [100.0, 500.0, 1500.0, 2000.0, 5000.0, 9600.0, 10000.0]
|
|
_ticks = {r: r / slew_limit_w(Tuning(max_w=r)) for r in _rails}
|
|
print(" ticks to cross the rail at the default, by rail: "
|
|
+ ", ".join(f"{r:.0f}W={t:.1f}" for r, t in _ticks.items()))
|
|
check("⭐ AT EVERY RAIL THE DEFAULT TAKES THE SAME NUMBER OF TICKS TO CROSS IT - "
|
|
"which is PLANT_SETTLE_S at the measured tick. This is the whole of "
|
|
"SAFETY-39: raising max_w moves the slew limit with it, so the constant "
|
|
"cannot be left behind by the rail again",
|
|
all(abs(t - PLANT_SETTLE_S / LOOP_TICK_S) < 1e-9 for t in _ticks.values()))
|
|
check("...and that is the same as saying the crossing takes the plant's own "
|
|
f"measured settling time ({PLANT_SETTLE_S:.0f} s) at the "
|
|
f"{LOOP_TICK_S:.0f} s tick the live install was measured running",
|
|
all(abs(t * LOOP_TICK_S - PLANT_SETTLE_S) < 1e-9 for t in _ticks.values()))
|
|
|
|
# ⭐ VERIFIED BY BREAKING IT. The configuration that produced the 2026-09-05
|
|
# excursion, put through the same arithmetic: it crosses the rail in 10 s
|
|
# against a plant that takes 18 s. This is the number validate.py rule 10
|
|
# refuses on, and it is asserted HERE too so that the law and the gate cannot
|
|
# drift apart - the rule can only ever refuse what this ratio says is too fast.
|
|
_broken = Tuning(max_w=5000.0, slew_w=1000.0)
|
|
_broken_s = 5000.0 / slew_limit_w(_broken) * LOOP_TICK_S
|
|
print(f" the 2026-09-05 configuration (max_w 5000, slew_w 1000) crosses its "
|
|
f"rail in {_broken_s:.0f} s against a plant measured at {PLANT_SETTLE_S:.0f} s")
|
|
check("⭐ RESTORING slew_w 1000 AT max_w 5000 IS FASTER THAN THE PLANT, and by "
|
|
"the ratio rather than by anybody's opinion - test_validate.py's rule 10 "
|
|
"section refuses exactly this pair",
|
|
_broken_s < PLANT_SETTLE_S
|
|
and slew_limit_w(_broken) > SLEW_RAIL_FRAC * _broken.max_w)
|
|
|
|
# THE CLOSED LOOP, AND WHAT THIS PLANT IS AND IS NOT.
|
|
#
|
|
# ⚠️ THE PLANT BELOW IS MODELLED HERE AND IS NOT THE RIG. admin/goodwe's
|
|
# `plantsim.Plant` is the battery model this project grades control changes
|
|
# against, and this repository's CI cannot reach it - that repository is private
|
|
# and this job's token is minted for this one (see .gitea/workflows/checks.yml).
|
|
# So the rig evidence lives in `tools/slew_sim.py`, is quoted in the pull
|
|
# request and in DECISIONS/SAFETY-39-slew-against-the-rail.md, and what runs
|
|
# HERE is a first-order lag with the time constant that reproduces §5.10's
|
|
# measured ~18 s to the deadband. test_alloc.py makes the same split for the
|
|
# same reason and says so in the same words.
|
|
#
|
|
# ⚠️ AND IT CANNOT SHOW A BATTERY ABOVE ITS RATING, WHICH IS SAID BEFORE THE
|
|
# RESULT RATHER THAN AFTER IT. Neither this model nor `plantsim.Plant` lets the
|
|
# plant exceed `p_max`; both clamp. The -5154 W against a 5000 VA inverter that
|
|
# the ticket reports is therefore NOT REPRODUCIBLE IN SIMULATION AT ALL, by
|
|
# construction, and no acceptance criterion here is written on it. What IS
|
|
# reproducible, and is what is graded, is the loop OVER-ABSORBING and driving
|
|
# the meter from export into import - the error it then chases.
|
|
_TAU_S = 6.0 # first-order lag; with the 2 s tick it reaches the
|
|
# deadband ~18 s after a step, which is §5.10's figure
|
|
|
|
|
|
def _step_run(tuning, export_w, load_w=350.0, phase=5, cycles=90,
|
|
dt=LOOP_TICK_S):
|
|
"""One export step onto a converged loop.
|
|
|
|
-> (worst import at the meter, peak battery beyond what the site NEEDED,
|
|
largest setpoint change in one tick).
|
|
"""
|
|
import math
|
|
prev, i_w, sat, actual, pv = 0.0, None, 0, 0.0, 0.0
|
|
a = 1.0 - math.exp(-dt / _TAU_S)
|
|
worst_import, peak, biggest, last = -1e9, 0.0, 0.0, None
|
|
for c in range(cycles):
|
|
if c == phase:
|
|
pv = export_w + load_w
|
|
grid = load_w - pv - actual
|
|
d = compute(prev, grid, actual, tuning, sat, i_w)
|
|
if c >= phase and last is not None:
|
|
biggest = max(biggest, abs(d.target_w - last))
|
|
last = d.target_w
|
|
prev, i_w, sat = d.target_w, d.i_w, d.sat_count
|
|
# the plant: a first-order lag, clamped at the rating like the real one
|
|
actual += (max(-tuning.max_w, min(tuning.max_w, prev)) - actual) * a
|
|
if c >= phase:
|
|
worst_import = max(worst_import, load_w - pv - actual)
|
|
peak = max(peak, abs(actual))
|
|
return worst_import, peak - export_w, biggest
|
|
|
|
|
|
def _family(tuning):
|
|
"""The worst case over 51 export steps, 1.0-4.2 kW, at three phases.
|
|
|
|
⚠️ A FAMILY AND NOT ONE STEP, AND THAT IS A FINDING RATHER THAN CAUTION.
|
|
A single run of this loop is not evidence: the deadband, the 10 W
|
|
quantisation and the phase of the step against the tick move the result by
|
|
hundreds of watts, non-monotonically, so two adjacent slews can rank either
|
|
way on one step and the opposite way on the next. Every number below is a
|
|
worst case over the family, which is how admin/goodwe grades the same
|
|
quantities (see `config.yaml`'s "1890 closed-loop runs" and "924 runs").
|
|
"""
|
|
worst = dict(imp=-1e9, over=-1e9, step=0.0, big=0, runs=0)
|
|
for export_w in range(1000, 4300, 200):
|
|
for phase in (5, 6, 7):
|
|
imp, over, step = _step_run(tuning, float(export_w), phase=phase)
|
|
worst["runs"] += 1
|
|
worst["imp"] = max(worst["imp"], imp)
|
|
worst["over"] = max(worst["over"], over)
|
|
worst["step"] = max(worst["step"], step)
|
|
worst["big"] += step >= 900.0
|
|
return worst
|
|
|
|
|
|
_LIVE = Tuning(max_w=5000.0, slew_w=1000.0) # what ran on 2026-09-05
|
|
_RAIL = Tuning(max_w=5000.0) # slew_w 0 - follow the rail
|
|
_INTERIM = Tuning(max_w=5000.0, slew_w=400.0) # applied live 2026-09-05 12:00
|
|
_SLOWER = Tuning(max_w=5000.0, slew_w=250.0)
|
|
_GAIN03 = Tuning(max_w=5000.0, gain=0.3)
|
|
_GAIN02 = Tuning(max_w=5000.0, gain=0.2)
|
|
_R = {k: _family(t) for k, t in
|
|
(("live", _LIVE), ("rail", _RAIL), ("interim", _INTERIM),
|
|
("slower", _SLOWER), ("gain03", _GAIN03), ("gain02", _GAIN02))}
|
|
print(f" worst case over {_R['live']['runs']} export steps at max_w 5000, "
|
|
f"{LOOP_TICK_S:.0f} s tick:")
|
|
for _k, _lab in (("live", "gain 0.6 slew_w 1000 (the 2026-09-05 live pair)"),
|
|
("rail", "gain 0.6 slew_w 0 (follow the rail)"),
|
|
("interim", "gain 0.6 slew_w 400 (the live interim)"),
|
|
("slower", "gain 0.6 slew_w 250"),
|
|
("gain03", "gain 0.3 slew_w 0"),
|
|
("gain02", "gain 0.2 slew_w 0")):
|
|
_w = _R[_k]
|
|
print(f" {_lab:<48} largest tick step {_w['step']:5.0f} W, "
|
|
f"{_w['big']:2}/{_w['runs']} runs step >= 900 W, "
|
|
f"over-absorbed {_w['over']:5.0f} W, meter driven to {_w['imp']:+6.0f} W")
|
|
|
|
# ⭐ THE DEFECT, REPRODUCED BEFORE ANYTHING IS CHANGED. The live pair steps the
|
|
# setpoint by a full 1000 W on nearly every member of the family and drives the
|
|
# meter from EXPORT into IMPORT - the loop manufacturing the error it then
|
|
# chases. That is the 2026-09-05 observation and it is what makes this a control
|
|
# fault rather than a slow loop.
|
|
check("⭐ REPRODUCED: at max_w 5000 with slew_w 1000 the setpoint steps a full "
|
|
"1000 W per tick on nearly every step in the family, and the meter is "
|
|
"driven from export into import",
|
|
_R["live"]["step"] >= 900.0
|
|
and _R["live"]["big"] > 0.9 * _R["live"]["runs"]
|
|
and _R["live"]["imp"] > 200.0)
|
|
check("⭐ FIXED, ON THE THING THE SLEW ACTUALLY OWNS: following the rail removes "
|
|
"the >= 900 W step from EVERY member of the family - which is the symptom "
|
|
"that escalated 2 -> 1 -> 13 -> 43 per 30 min on the morning of the "
|
|
"2026-09-05 excursion",
|
|
_R["live"]["big"] > 0 and _R["rail"]["big"] == 0
|
|
and _R["interim"]["big"] == 0)
|
|
|
|
# ⚠️ AND WHAT IT DOES NOT BUY, MEASURED, ASSERTED, AND SAID BEFORE ANYBODY CAN
|
|
# READ MORE INTO THIS CARD THAN IT DELIVERED. `slew_w` bounds the OUTPUT; the
|
|
# integrator accumulates `gain * error` per cycle and is bounded only by
|
|
# `integrator_max_w`. At gain 0.6 into a 3.4 kW error the integrator moves
|
|
# ~2000 W per tick and reaches a 5000 W rail in under three ticks WHATEVER
|
|
# `slew_w` is. So the over-absorption is a GAIN term, and slowing the slew does
|
|
# not reduce it - on this model it gets slightly WORSE, because the command
|
|
# spends longer away from where it needs to be while the integrator keeps
|
|
# winding. admin/goodwe's rig, a different plant model, agrees: over-absorption
|
|
# 990 W at slew 1000 and 1086 W at slew 250, against 1010 W at gain 0.6 and
|
|
# 863 W at gain 0.3 (tools/slew_sim.py).
|
|
#
|
|
# `gain` is therefore the next constant to re-derive. SAFETY-39 measured it and
|
|
# CHANGED NOTHING: it is a live control-law constant on a running house, and two
|
|
# of them moving in one release makes the next measurement uninterpretable.
|
|
check("⚠️ THE SLEW DOES NOT OWN THE OVER-ABSORPTION, AND THIS CHECK IS HERE SO "
|
|
"THAT NOBODY READS SAFETY-39 AS 'THE OVERSHOOT IS FIXED'. Quartering the "
|
|
"slew from 1000 to 250 does not reduce the over-absorption at all",
|
|
_R["slower"]["over"] >= _R["live"]["over"])
|
|
check("...while the GAIN does own it: 0.6 -> 0.3 -> 0.2 falls monotonically, at "
|
|
"the same slew. That is the measurement behind 'gain is the next constant "
|
|
"to re-derive', and it is a measurement rather than an opinion",
|
|
_R["gain03"]["over"] < _R["rail"]["over"]
|
|
and _R["gain02"]["over"] < _R["gain03"]["over"])
|
|
|
|
print()
|
|
if fails:
|
|
print(f"{len(fails)} FAILED: {', '.join(fails)}")
|
|
sys.exit(1)
|
|
print("all checks passed")
|