47 lines
2.8 KiB
Markdown
47 lines
2.8 KiB
Markdown
|
# DECISION-20260422-pumpingstation-mode-tier-template
|
|||
|
|
|
|||
|
|
## Context
|
|||
|
|
- Task/request: Document each pumpingStation control mode uniformly so operators can compare them and contributors can add new ones from a template.
|
|||
|
|
- Impacted files/contracts: `wiki/modes/*.md`, `wiki/diagrams/modes/*.drawio.svg`.
|
|||
|
|
- Why a decision is required now: The initial `levelbased.md` used a 2D `demand-vs-level` transfer-function plot. That plot form works for static memoryless control but misleads for modes whose curve shape changes at runtime (e.g. `powerBased`) or where there is no curve at all (`mpc`). We need one template that stretches to cover all cases.
|
|||
|
|
|
|||
|
|
## Options
|
|||
|
|
1. One template, transfer-function only
|
|||
|
|
- Benefits: Uniformity.
|
|||
|
|
- Risks: Silently misleading for Tier-2/Tier-3 modes where the "curve" is not well-defined.
|
|||
|
|
|
|||
|
|
2. Per-mode ad-hoc diagrams
|
|||
|
|
- Benefits: Each mode gets the best visual for itself.
|
|||
|
|
- Risks: No common vocabulary — comparing modes becomes harder.
|
|||
|
|
|
|||
|
|
3. Three-tier template (selected)
|
|||
|
|
- Benefits: Classifies every mode into one of three buckets, each with a dedicated diagram type. Still one template — only the diagram section branches.
|
|||
|
|
- Risks: Some modes don't fit cleanly; will need judgement.
|
|||
|
|
|
|||
|
|
## Tier definitions
|
|||
|
|
|
|||
|
|
| Tier | Control surface | Example modes | Diagrams |
|
|||
|
|
|---|---|---|---|
|
|||
|
|
| 1 | Static: `demand = f(x)` memoryless | `levelbased`, `manual` | Single-curve transfer function |
|
|||
|
|
| 2 | Parameterised: shape fixed, curve moves with `θ(t)` | `flowbased` (PID), `pressureBased`, `percentageBased`, `powerBased` | Transfer function + parameter-overlay / family-of-curves |
|
|||
|
|
| 3 | Optimisation / horizon: no fixed curve | `hybrid-optimal`, `mpc`, weather-aware | Block diagram of signal flow + scenario time-series |
|
|||
|
|
|
|||
|
|
## Decision
|
|||
|
|
- Selected option: Option 3 — three-tier classification with diagram type per tier.
|
|||
|
|
- Decision owner: User
|
|||
|
|
- Date: 2026-04-22
|
|||
|
|
- Rationale: Keeps the mode pages comparable (same six sections) while being honest about what's actually drawable. Tier-3 modes get scenario-based analysis (via the `eval/` harness) instead of a fictitious static curve.
|
|||
|
|
|
|||
|
|
## Consequences
|
|||
|
|
- Compatibility impact: None — this is doc-level.
|
|||
|
|
- Safety/security impact: None.
|
|||
|
|
- Data/operations impact: New modes get a template to follow; reviews have a shared vocabulary.
|
|||
|
|
|
|||
|
|
## Implementation Notes
|
|||
|
|
- Required code/doc updates: `wiki/modes/README.md` lists the tiers and template; `wiki/modes/{flowbased, powerbased, mpc}.md` are worked templates covering Tier 2 (×2) and Tier 3 (×1) respectively.
|
|||
|
|
- Validation evidence required: A reviewer reading a mode page can identify which tier it is within 10 seconds without scrolling.
|
|||
|
|
|
|||
|
|
## Rollback / Migration
|
|||
|
|
- Rollback strategy: Delete `wiki/modes/`; revert the table in `wiki/README.md`.
|
|||
|
|
- Migration/deprecation plan: N/A — adding a tier later (e.g. Tier 4 — RL-based) is trivially additive.
|