Reference — Limitations
Note
What
pumpingStationdoes not do, current rough edges, and open questions tracked against the refactor. Live source for the open items:.claude/refactor/OPEN_QUESTIONS.mdin the EVOLV superproject.
When you would not use this node
| Scenario | Use instead |
|---|---|
| Pressurised distribution network without a basin | Cascade pumpingStations, or a valveGroupControl parented to a flow source |
| Single pump, no basin, no level sensor | Parent a rotatingMachine directly under a UI driver |
| Air manifold (compressor + valves) | A future compressorStation — not implemented |
| Open-channel flow without a wet-well | Out of scope for the current basin model (rectangular prismatic only) |
| Sludge thickening basin | Use a settler — different settling-velocity model required |
Known limitations
Implemented modes vs schema modes
The schema's control.mode enum lists eight modes, but only two are implemented in code:
| Mode | Status | Notes |
|---|---|---|
levelbased |
Implemented | Default; the most production-tested path |
manual |
Implemented | Operator's set.demand is forwarded unchanged |
flowbased |
Placeholder | Schema accepts it; runtime falls back to levelbased |
pressureBased |
Placeholder | Same as above |
percentageBased |
Placeholder | Same as above |
powerBased |
Placeholder | Same as above |
hybrid |
Placeholder | Same as above |
mpc |
Not in code | Reserved name |
If you select an unimplemented mode in the editor, the basin runs but the controller stays in level-based. Tracked.
Basin shape
Only rectangular prismatic basins are supported. Cylindrical, frusto-conical, or stepped basins would need a new BasinGeometry implementation. The volume = level * surfaceArea relationship is hard-wired.
Net-flow source selection
When both an MGC parent and direct rotatingMachine children are wired, the station subscribes only to the MGC's predicted flow. If you intentionally have MGC + extra individual pumps, the extras are invisible to the volume integrator. The router protects against double-counting but does not warn about this edge case.
Aliases not yet removed
The following legacy aliases still work but log a deprecation warning on first use. They are scheduled for removal in Phase 7:
| Canonical | Legacy alias |
|---|---|
set.mode |
changemode |
set.inflow |
q_in |
set.outflow |
q_out |
set.demand |
Qd |
cmd.calibrate.volume |
calibratePredictedVolume |
cmd.calibrate.level |
calibratePredictedLevel |
child.register |
registerChild |
Update integrations now.
Open questions (tracked)
Pulled from .claude/refactor/OPEN_QUESTIONS.md. Last reviewed on the date in the badge above.
| Question | Where it lives |
|---|---|
overfillVol alias drop — same shape as the already-done overfillLevel drop |
OPEN_QUESTIONS.md (pumpingStation entry) |
| Net-flow source warning when multiple aggregators are wired | Internal — not yet ticketed |
| Cylindrical basin geometry | Internal — not yet ticketed |
| Docker E2E sign-off (P2.14) | OPEN_QUESTIONS.md (Phase 6) |
Migration notes
From pre-refactor
| Pre-refactor | Now |
|---|---|
enableOverfillProtection |
enableHighVolumeSafety |
overfillThresholdPercent |
highVolumeSafetyThresholdPercent |
Legacy topics (changemode, q_in, ...) |
Canonical topics (see Reference — Contracts for the alias map) |
basic.flow.json (legacy) |
01-Basic.json (canonical-topic version) |
Renamed safety thresholds
The safety layer used to expose threshold fields named overfill*. Those names suggested the layer prevents overflow specifically; in practice the rule handles high-volume conditions more broadly (high level + low inflow / outflow imbalance). The current names (highVolumeSafety*) reflect that.
Related pages
| Page | Why |
|---|---|
| Home | Intuitive overview |
| Reference — Contracts | Topic + config + child filters (alias map at the end) |
| Reference — Architecture | Code map, state chart |
| Reference — Examples | Shipped flows |