pumpingStation/wiki/modes/powerbased.md

title, mode, tier, status, updated

title	mode	tier	status	updated
Power-based mode	powerBased	2	placeholder	2026-04-22

Power-based mode — Tier 2 template

Status — not yet implemented. Placeholder. This page documents the intended shape of a grid-aware / netcongestion-aware station.

At a glance

Item	Value
Tier	2 — parameterised transfer function
Signal driving demand	basin level (primary), max-power budget (clip)
Secondary inputs	measured pump power, live grid-price / peak-hours signal
Output	demand 0–100 % clipped so Σ pump power ≤ maxPowerKW(t)
Thresholds adjusted at runtime?	maxPowerKW(t) yes — level thresholds no
Use when	Grid has peak-hour tariffs or net-congestion caps

Diagram — the levelbased curve with a moving clip ceiling

demand %                                     ← dashed line: levelbased curve
 100 ┤               ╱ ───────                ← solid: clip at powerBudget(t)
     │              ╱            clip lowers
     │             ╱             during grid peak
     │            ╱       ─────────
     │           ╱       ╱
     │          ╱       ╱
     │         ╱       ╱
  0  ┼────────●───────●─────────────────────► level
             startLevel    maxLevel

         ↑ the family of curves:
           clip=100% (grid idle),
           clip=70% (shoulder),
           clip=40% (peak).

The shape stays levelbased; the ceiling drops when the grid is strained. That's the Tier-2 signature: same input axis, parameter shifts the curve.

Inputs

Signal	Where from	Role
current level	as in levelbased	primary input
config.control.powerBased.maxPowerKW	editor, static	hard cap on station power
config.control.powerBased.powerControlMode	limit / optimize	whether to just clip or to schedule
live grid signal (future)	external topic or forecast	modulates the cap over time
measured pump power	power.measured.* from children	real-time feedback against the cap

Threshold policy

Level thresholds (minLevel, startLevel, maxLevel) are identical to levelbased — they define the shape of the underlying curve. What's new is a runtime-varying ceiling demandCap(t) derived from the power budget.

demandCap(t) = 100 × (maxPowerKW(t) / nominalStationPowerAtFull) — where maxPowerKW(t) may come from config (static limit mode) or an external grid-price feed (dynamic).

Demand formula

rawDemand = levelbasedDemand(level)          # the underlying Tier-1 curve
demandCap = min(100, 100 × maxPowerKW(t) / nominalStationPower)
demand    = min(rawDemand, demandCap)

When demandCap < rawDemand, the mode sacrifices drainage rate to stay within power budget. Level may rise — the high-volume safety layer still applies as the last line of defence before physical overflow.

Edge cases

• Peak hour with rising level. demandCap drops faster than level rises → demand gets clipped; level approaches overflowLevel. If high-volume safety trips, it overrides the clip (safety wins).
• Power signal dropout. Fall back to static maxPowerKW from config; log warning.
• Grid exit from peak while basin is nearly full. demandCap jumps back to 100; PID is memoryless so demand rises in one tick to match rawDemand.
• Measured vs predicted pump power. Cap is enforced on predicted (decisions are made before the pump responds). Reconcile against measured for logging/diagnostics.

Related

• Functional description
• modes/levelbased.md — Tier 1 reference (the curve that powerBased clips)
• modes/flowbased.md — other Tier-2 example with different control variable