Docs + simulations refresh; align spill-flow keys with new position

- wiki/functional-description.md: rename Overfill Protection → High-volume
  Safety; tighten basin-ordering chain; relocate level-based mode
  diagrams under wiki/diagrams/modes/level-based/; document the new
  flow.predicted.overflow.default position (replaces the previous
  child='overflow' under position 'out'); add underflowVolume +
  predictedUnderflowVolume entries.
- wiki/modes/{levelbased,powerbased}.md: paragraph cleanups.
- wiki/diagrams: move level-linear basin diagram under modes/level-based/
  alongside a new level-log variant.
- simulations/run.js: add max_demand_gt expectation.
- simulations/scenarios/*: minor fixture updates.
- test/basic/nodeClass-config.test.js: new config-shape coverage.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

simulations/README.md

@@ -49,6 +49,7 @@ module.exports = {
 | `max_level_bounded` | max level across the run must be `≤ value` |
 | `min_level_bounded` | min level across the run must be `≥ value` |
 | `max_demand_bounded` | max percControl must be `≤ value` |
+| `max_demand_gt` | max percControl must be `> value` |
 | `safety_trips_eq` | total ticks with `safetyActive` must equal `value` |
 | `safety_trips_gt` | total ticks with `safetyActive` must be `> value` |
 | `end_state_eq` | final record's `field` must equal `value` |

simulations/run.js

@@ -54,6 +54,10 @@ function evalExpectation(ex, records) {
       const v = Math.max(...demands);
       return { ok: v <= ex.value, msg: `max demand = ${v.toFixed(0)} % (bound: ≤ ${ex.value})` };
     }
+    case 'max_demand_gt': {
+      const v = Math.max(...demands);
+      return { ok: v > ex.value, msg: `max demand = ${v.toFixed(0)} % (expected > ${ex.value})` };
+    }
     case 'safety_trips_eq': {
       const n = records.filter((r) => r.safetyActive).length;
       return { ok: n === ex.value, msg: `${n} ticks with safetyActive (expected ${ex.value})` };

simulations/scenarios/levelbased-steady.js

@@ -2,30 +2,30 @@
 //
 // Expectation: with a stable inflow of 0.008 m³/s and a pump bank with
 // max capacity 0.012 m³/s, the level settles in the RAMP zone (between
-// startLevel and maxLevel) at roughly the point where demand matches
+// inflowLevel and maxLevel while filling) at roughly the point where demand matches
 // inflow. No safety trips should fire.
 
 module.exports = {
   name: 'levelbased-steady',
   description: 'Constant sewer inflow below pump capacity; level converges inside the RAMP zone with demand matching inflow.',
-  durationSec: 1200,
+  durationSec: 3600,
 
   config: {
     general: { name: 'EvalSteady', id: 'eval-steady', unit: 'm3/h',
       logging: { enabled: false, logLevel: 'error' } },
     functionality: { softwareType: 'pumpingStation', role: 'stationcontroller', positionVsParent: 'atEquipment' },
-    basin: { volume: 50, height: 5, inflowLevel: 3, outflowLevel: 0.2, overflowLevel: 4.5 },
+    basin: { volume: 50, height: 5, inflowLevel: 3, outflowLevel: 0.2, overflowLevel: 4.5, inletPipeDiameter: 0.4, outletPipeDiameter: 0.3 },
     hydraulics: { refHeight: 'NAP', basinBottomRef: 0, minHeightBasedOn: 'outlet' },
     control: {
       mode: 'levelbased',
       allowedModes: new Set(['levelbased']),
-      levelbased: { minLevel: 1, startLevel: 2, maxLevel: 4 },
+      levelbased: { minLevel: 1, startLevel: 2, maxLevel: 4, curveType: 'linear', logCurveFactor: 9 },
     },
     safety: {
       enableDryRunProtection: true,
       dryRunThresholdPercent: 2,
-      enableOverfillProtection: true,
-      overfillThresholdPercent: 98,
+      enableHighVolumeSafety: true,
+      highVolumeSafetyThresholdPercent: 98,
       timeleftToFullOrEmptyThresholdSeconds: 0,
     },
   },
@@ -44,7 +44,7 @@ module.exports = {
         ps.measurements.type('flow').variant('predicted').position('out').child('mgc1').value(outflow, Date.now(), 'm3/s');
       },
     };
-    ps.calibratePredictedLevel(2.0);  // start at the bottom of the RAMP zone
+    ps.calibratePredictedLevel(2.0);  // start at the mode start level, below the rising ramp
   },
 
   inputs: (t, ps) => {
@@ -55,6 +55,7 @@ module.exports = {
     { name: 'no safety trips', type: 'safety_trips_eq', value: 0 },
     { name: 'level stays below overflow', type: 'max_level_bounded', value: 4.5 },
     { name: 'level stays above outflow', type: 'min_level_bounded', value: 0.2 },
+    { name: 'rising ramp engages after inlet level', type: 'max_demand_gt', value: 0 },
     { name: 'no threshold issues on init', type: 'threshold_issues_eq', value: 0 },
   ],
 };

simulations/scenarios/levelbased-storm.js

@@ -1,31 +1,31 @@
-// Storm surge — inflow triples briefly, pumps should saturate at 100%,
-// level rises toward overflow then recedes.
+// Storm surge — inflow triples briefly, pumps should increase demand as
+// the level enters the rising ramp.
 //
-// Expectation: during the surge (t=300..600), demand reaches 100% and
-// level may transiently climb above maxLevel. Overflow safety should
-// fire if the surge overwhelms pump capacity; dry-run should not fire.
+// Expectation: during the surge (t=300..600), demand rises but remains
+// bounded. High-volume safety should fire if the surge overwhelms pump
+// capacity; dry-run should not fire.
 
 module.exports = {
   name: 'levelbased-storm',
-  description: 'Sewer inflow triples from 0.008 → 0.024 m³/s for 5 minutes then returns to baseline. Overfill safety may engage.',
+  description: 'Sewer inflow triples from 0.008 → 0.024 m³/s for 5 minutes then returns to baseline. High-volume safety may engage.',
   durationSec: 1500,
 
   config: {
     general: { name: 'EvalStorm', id: 'eval-storm', unit: 'm3/h',
       logging: { enabled: false, logLevel: 'error' } },
     functionality: { softwareType: 'pumpingStation', role: 'stationcontroller', positionVsParent: 'atEquipment' },
-    basin: { volume: 50, height: 5, inflowLevel: 3, outflowLevel: 0.2, overflowLevel: 4.5 },
+    basin: { volume: 50, height: 5, inflowLevel: 3, outflowLevel: 0.2, overflowLevel: 4.5, inletPipeDiameter: 0.4, outletPipeDiameter: 0.3 },
     hydraulics: { refHeight: 'NAP', basinBottomRef: 0, minHeightBasedOn: 'outlet' },
     control: {
       mode: 'levelbased',
       allowedModes: new Set(['levelbased']),
-      levelbased: { minLevel: 1, startLevel: 2, maxLevel: 4 },
+      levelbased: { minLevel: 1, startLevel: 2, maxLevel: 4, curveType: 'linear', logCurveFactor: 9 },
     },
     safety: {
       enableDryRunProtection: true,
       dryRunThresholdPercent: 2,
-      enableOverfillProtection: true,
-      overfillThresholdPercent: 95,
+      enableHighVolumeSafety: true,
+      highVolumeSafetyThresholdPercent: 95,
       timeleftToFullOrEmptyThresholdSeconds: 0,
     },
   },
@@ -55,6 +55,6 @@ module.exports = {
     { name: 'dry-run never trips', type: 'end_state_eq', field: 'safetyActive', value: false },
     // Level may exceed maxLevel transiently but must stay under basinHeight
     { name: 'level never breaches physical basin', type: 'max_level_bounded', value: 5.0 },
-    { name: 'demand saturates at 100% during surge', type: 'max_demand_bounded', value: 100 },
+    { name: 'demand remains bounded during surge', type: 'max_demand_bounded', value: 100 },
   ],
 };

simulations/scenarios/safety-dry-run-trip.js

@@ -12,18 +12,18 @@ module.exports = {
     general: { name: 'EvalDryRun', id: 'eval-dry-run', unit: 'm3/h',
       logging: { enabled: false, logLevel: 'error' } },
     functionality: { softwareType: 'pumpingStation', role: 'stationcontroller', positionVsParent: 'atEquipment' },
-    basin: { volume: 50, height: 5, inflowLevel: 3, outflowLevel: 0.2, overflowLevel: 4.5 },
+    basin: { volume: 50, height: 5, inflowLevel: 3, outflowLevel: 0.2, overflowLevel: 4.5, inletPipeDiameter: 0.4, outletPipeDiameter: 0.3 },
     hydraulics: { refHeight: 'NAP', basinBottomRef: 0, minHeightBasedOn: 'outlet' },
     control: {
       mode: 'manual',
       allowedModes: new Set(['levelbased', 'manual']),
-      levelbased: { minLevel: 0.5, startLevel: 2, maxLevel: 4 },
+      levelbased: { minLevel: 0.5, startLevel: 2, maxLevel: 4, curveType: 'linear', logCurveFactor: 9 },
     },
     safety: {
       enableDryRunProtection: true,
       dryRunThresholdPercent: 50,
-      enableOverfillProtection: false,
-      overfillThresholdPercent: 98,
+      enableHighVolumeSafety: false,
+      highVolumeSafetyThresholdPercent: 98,
       timeleftToFullOrEmptyThresholdSeconds: 0,
     },
   },