brewpi/docs/overshoot_hold_windup.md

HOLD-state overshoot from a disturbance: root cause and fix plan

Investigation of the overshoot visible in docs/overshoot.png: a cold-water disturbance during a steady HOLD at 30°C caused theta_ist to overshoot to ~30.5°C and stay there, rather than settling back at soll. This document records the diagnosis and the (not yet implemented) fix plan. Numbers below are pulled from logs/log_latest.json.

Incident summary

• Steady HOLD at 30.0°C. Cold water added → theta_ist (Smith-corrected) dipped to ~29.49°C (diff ≈ 0.51°C).
• diff never reached Thresholds.HoldHeat (1.0°C, temp_controller_fsm.py), so the FSM never left HOLD — the entire episode happened inside what the system still considered "holding".
• pid_hold (outer loop, Hold: {kp:0.6, ki:0, kd:0, kt:0} — pure proportional) tracked 0.6 * max(0, diff) exactly, tick for tick, peaking at pid_hold_y ≈ 0.31 — nowhere near its y_max=1.0 ceiling. Confirmed directly against logged samples: rate_soll == 0.6*diff to the last digit throughout.
• pid_heat (inner loop, Heat: {kp:0.08, ki:0.02, kd:0, kt:1.5}) then chased that heatrate_soll target, driving commanded power from a baseline ~500W burst-cycle up to ~2600W (y ≈ 0.74 of the 3500W max, see tasks/heater.py:58-59: power = get_power_max() * y).
• Plant dead time (Td=17s) and thermal mass (M=27.96 kg, C≈3403 J/(kg·K), from PlantParams in the log) meant heat from that burst kept arriving after theta_ist had already crossed back over soll. By the time rate_soll had fallen back to exactly 0 (outer loop asking for zero heat rate), power_set was still 1442 W, decaying only gradually over the next ~35s (1193 → 979 → 817 → 632 → 487 → 337 → 142 W) rather than snapping to 0.
• No active cooling actuator exists; the passive loss coefficient (L=0.2 W/(kg·K)) gives a time constant C/L ≈ 17,000s (~4.7h), so the resulting ~0.4°C plateau above soll does not visibly decay within any reasonable observation window.

Root cause: pid_heat's integral term (yi) accumulated during the ~130s the outer loop demanded a real (if modest) heat rate, and nothing bounded that accumulation — the existing anti-windup in Pid.process() (components/pid/pid.py:45-48) is back-calculation that only corrects yi when the combined output y is actually clamped at y_min/y_max. Since y peaked at ~0.74, well under the 1.0 ceiling, awu was 0 the entire time and the anti-windup mechanism never engaged. The integrator just had to unwind naturally against real (delayed) negative error, which took ~35+ seconds after the outer loop had already zeroed its target.

Rejected approach: flat yi_max clamp on pid_heat

The first fix considered was bounding yi directly (self.yi = max(-yi_max, min(yi_max, self.yi)) in Pid.process(), independent of the existing y-clamp anti-windup). Numeric check against the real plant model kills this as a standalone fix:

scenario	P needed	y needed
1.5 K/min ramp @ 30°C	2435 W	0.696
1.5 K/min ramp @ 50°C	2547 W	0.728
1.5 K/min ramp @ 66°C	2636 W	0.753
the actual HOLD disturbance (peak)	2600 W	0.74

At steady state (err=0), kp*err contributes nothing — the entire y≈0.7-0.75 needed to sustain a genuine 1.5 K/min ramp has to come from yi alone, for as long as the ramp lasts. That's the same range the disturbance transient itself peaked at. So:

• yi_max set low enough to meaningfully shorten the observed hangover (well under ~0.74, e.g. ~0.3) would permanently cap a real 1.5 K/min ramp far below its commanded rate — not a transient dip, a persistent, uncorrectable shortfall for the entire ramp.
• yi_max set high enough not to interfere with legitimate ramps (~0.75+) sits at or above what the incident already peaked at, so it never engages and does nothing for the hangover.

A flat magnitude clamp cannot distinguish "leftover integral from an already-resolved disturbance" from "integral correctly holding up a real ongoing ramp" — in this plant they occupy the same output range. Rejected.

Refined plan: gate pid_heat by FSM state instead

Bound (or freeze) the rate at which pid_heat reacts based on FSM state, not a constant on yi, since real sustained-rate demand only ever happens in HEAT; in HOLD any large yi is by definition windup, since the target rate there is always ~0 outside of a real disturbance.

1. New flag heat_loop_active, scoped to HOLD only, in TempControllerFsm. is_holding() stays state == HOLD regardless — Sud step "have we reached target" logic is unaffected.
2. While heat_loop_active is False in HOLD: force y=0, skip pid_heat.process() entirely (freeze it, don't reset — same bumpless-resume convention already used for HOLD→HEAT, see temp_controller_fsm.py:99-101). pid_hold keeps running every tick regardless (it's pure-P, no windup risk, and its output is needed to evaluate the engage condition below).
3. Engagement (False→True), checked each tick while in HOLD:
   • Explicit command — a new engage_heat_loop()/force_heat() call, wired to a manual UI action and/or auto-fired from set_theta_soll() when the new target is a genuine change (not the same value re-sent every tick).
   • diff >= Thresholds.HoldHeatEngage (new config key).
4. Disengagement: once diff settles back inside the existing HoldHeat/HoldCool band, held for a short dwell time (a few seconds), to avoid chatter right at the boundary.
5. Config/back-compat: new threshold merges into DEFAULT_THRESHOLDS the same way existing ones do (temp_controller_base.py:30).

Open design question (unresolved)

HoldHeatEngage needs to sit below the existing HoldHeat/HeatHold FSM threshold (currently 1.0°C) to ever fire from inside HOLD — if HoldHeat stays at 1.0, the FSM fully escalates to HEAT (where pid_heat always runs anyway) before any larger engage threshold is ever reached. Two ways to resolve, not yet decided:

• Raise HoldHeat/HeatHold too, widening the HOLD↔HEAT band so HOLD covers the full deadband and the new flag is the only gate within it.
• Keep HoldHeat at 1.0, set the engage threshold below it (e.g. ~0.7-0.8°C) — loop only goes offline for small disturbances, engaging before the FSM would escalate to full HEAT anyway.

Test plan (not yet implemented)

Stdlib unittest, no pytest — tests/components/pid/test_pid.py, discoverable via python -m unittest discover -t . -s tests/components/pid.

A. Unit-level, isolated Pid — no plant involved. Feed a synthetic err sequence shaped like the incident (positive heatrate_err ≈ 0.3 held for ~130 ticks, then decaying/negative tail, matching the real rate_soll - rate_ist pulled from the log) into pid_heat with the loop gated (frozen while "HOLD"/inactive) vs ungated (today's behavior). Assert: recovery time (ticks after error goes negative until y drops back under a small threshold) is measurably shorter when gated; yi never grows during the frozen window.

B. Closed-loop, self-contained synthetic scenario — no dependency on the multi-MB log file. Real numbers from PlantParams/config.json: Pot(dt) with M=27.96, C=3403.43, L=0.2, Td=17, ambient from config.json; TempController via PidFactory.create('Smith', dt) with the real Hold/Heat/Cool gains. Run closed-loop (controller's own y drives the plant, unlike utils/replay_sim.py's open-loop observe-only mode): hold at 30°C until settled, knock plant.temp down ~0.5°C to emulate the cold-water event, keep ticking for several minutes. Run twice — gating on vs off — and assert peak overshoot above 30.0°C is measurably smaller with gating, while a separate run driving a genuine 1.5 K/min ramp confirms gating does not reduce the sustained ramp rate (guards against reintroducing the flat-clamp regression above).

Status

Plan only — nothing in this document has been implemented yet.