Add modes/ section with levelbased page as the template

Introduces the pattern: basin model is the shared canvas (mode-agnostic
physics); each control mode is its own page under wiki/modes/ plus a
demand-vs-level transfer-function diagram under wiki/diagrams/modes/.

- wiki/modes/README.md — index + per-mode page template (inputs,
  threshold policy, demand formula, edge cases, related)
- wiki/modes/levelbased.md — first worked example using the new naming
  convention (dryRunLevel / minLevel / startLevel / maxLevel /
  overflowLevel). Forward-looking — the code still uses the old names
  until the pending rename refactor.
- wiki/diagrams/modes/levelbased.drawio.svg — transfer-function plot
  (zones: STOP / DEAD ZONE / RAMP / SATURATE, safety trips outside the
  plot). Round-trippable via embedded drawio XML.
- functional-description.md — replaced the inline levelbased/manual
  subsection with a table pointing at the modes/ pages. Removed the
  old control-zones ASCII diagram reference (superseded by the
  per-mode transfer function).
- wiki/README.md — added Control modes entry + diagrams/modes/ pointer.

The remaining placeholder modes (flowbased, pressureBased,
percentageBased, powerBased, hybrid, manual) can each fill in the
template independently.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
znetsixe
2026-04-22 15:45:01 +02:00
parent 61e0688f73
commit 4637448c49
6 changed files with 235 additions and 183 deletions

29
wiki/modes/README.md Normal file
View File

@@ -0,0 +1,29 @@
# Control modes
Each page describes one `pumpingStation` control mode and how it uses the shared [basin model](../functional-description.md#basin-model) — specifically, how it sets the three control thresholds (`minLevel`, `startLevel`, `maxLevel`) and computes the demand it sends to the MGC.
The two **safety** thresholds (`dryRunLevel` and `overflowLevel`) are mode-independent and are enforced by the safety layer outside any mode. They never appear in a mode's policy.
## Template
Every mode page follows the same structure:
1. **At a glance** — one sentence + small fact table (inputs, output, status)
2. **Diagram** — reference to `../diagrams/modes/<mode>.drawio.svg`
3. **Inputs** — what signals the mode reads
4. **Threshold policy** — how it sets/adjusts `minLevel`, `startLevel`, `maxLevel`
5. **Demand formula** — how it turns inputs into a 0-100 % demand for the MGC
6. **Edge cases** — cold start, sensor dropout, interaction with safety layer
7. **Related** — links to other modes + functional description
## Implementation status
| Mode | Status | Page |
|---|---|---|
| `levelbased` | ✅ implemented | [levelbased.md](levelbased.md) |
| `flowbased` | 🚧 placeholder in code | — |
| `pressureBased` | 🚧 placeholder in code | — |
| `percentageBased` | 🚧 placeholder in code | — |
| `powerBased` | 🚧 placeholder in code | — |
| `hybrid` | 🚧 placeholder in code | — |
| `manual` | ✅ implemented (Qd topic) | — |