Add eval harness + Tier 2/3 mode template pages

### eval/ (scenario-based evaluation) Complements the unit tests under test/basic. Scenarios fluctuate inputs over simulated time, record every tick to JSONL, print a summary table + event log, and check expectations. Complementary to unit tests — these answer "how does the system respond to this input profile" rather than "is this function correct". - eval/run.js — driver; monkey-patches Date.now so the volume integrator ticks at 1 s/iter regardless of wall-clock - eval/scenarios/ — one file per scenario - levelbased-steady.js — constant inflow, demand converges - levelbased-storm.js — inflow surge, demand saturates - safety-dry-run-trip.js — manual mode, empty basin, safety trips - eval/formatters/table.js — ASCII summary of sampled ticks - eval/logs/ — per-scenario JSONL output (one line per tick) - eval/README.md — usage + scenario file shape + how to pipe into InfluxDB/Grafana All three starter scenarios PASS with their expectations. ### wiki/modes/ (tier template pages) The levelbased page templated Tier-1 modes (static transfer function). Added worked examples for the other two tiers so all mode pages share a common skeleton and new modes have something concrete to imitate: - flowbased.md — Tier 2 (PID on measured outflow) - powerbased.md — Tier 2 (levelbased curve clipped by grid power budget) - mpc.md — Tier 3 (optimisation + forecast; block diagram + scenario time-series instead of a fixed curve) - modes/README.md — updated with the three-tier classification table and diagram-type-per-tier guidance Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-22 16:49:41 +02:00
parent 016433abe6
commit 66fd3feff8
10 changed files with 880 additions and 13 deletions
--- a/eval/scenarios/levelbased-steady.js
+++ b/eval/scenarios/levelbased-steady.js
@@ -0,0 +1,60 @@
+// Steady sewer inflow, level-based control, pumps should settle.
+//
+// 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
+// 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,
+
+  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 },
+    hydraulics: { refHeight: 'NAP', basinBottomRef: 0, minHeightBasedOn: 'outlet' },
+    control: {
+      mode: 'levelbased',
+      allowedModes: new Set(['levelbased']),
+      levelbased: { minLevel: 1, startLevel: 2, maxLevel: 4 },
+    },
+    safety: {
+      enableDryRunProtection: true,
+      dryRunThresholdPercent: 2,
+      enableOverfillProtection: true,
+      overfillThresholdPercent: 98,
+      timeleftToFullOrEmptyThresholdSeconds: 0,
+    },
+  },
+
+  setup: async (ps) => {
+    // Stub MGC: its pumps collectively deliver (demand/100) × MAX_OUTFLOW.
+    const MAX_OUTFLOW = 0.012;  // m³/s
+    ps.machineGroups['mgc1'] = {
+      config: { general: { name: 'mgc1' } },
+      turnOffAllMachines: () => {
+        ps.measurements.type('flow').variant('predicted').position('out').child('mgc1').value(0, Date.now(), 'm3/s');
+      },
+      handleInput: async (_source, demand) => {
+        const d = Math.max(0, Math.min(100, Number(demand) || 0));
+        const outflow = (d / 100) * MAX_OUTFLOW;
+        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
+  },
+
+  inputs: (t, ps) => {
+    ps.setManualInflow(0.008, Date.now(), 'm3/s');  // ≈ 29 m³/h
+  },
+
+  expectations: [
+    { 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: 'no threshold issues on init', type: 'threshold_issues_eq', value: 0 },
+  ],
+};
--- a/eval/scenarios/levelbased-storm.js
+++ b/eval/scenarios/levelbased-storm.js
@@ -0,0 +1,60 @@
+// Storm surge — inflow triples briefly, pumps should saturate at 100%,
+// level rises toward overflow then recedes.
+//
+// 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.
+
+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.',
+  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 },
+    hydraulics: { refHeight: 'NAP', basinBottomRef: 0, minHeightBasedOn: 'outlet' },
+    control: {
+      mode: 'levelbased',
+      allowedModes: new Set(['levelbased']),
+      levelbased: { minLevel: 1, startLevel: 2, maxLevel: 4 },
+    },
+    safety: {
+      enableDryRunProtection: true,
+      dryRunThresholdPercent: 2,
+      enableOverfillProtection: true,
+      overfillThresholdPercent: 95,
+      timeleftToFullOrEmptyThresholdSeconds: 0,
+    },
+  },
+
+  setup: async (ps) => {
+    const MAX_OUTFLOW = 0.012;  // m³/s pumps cannot keep up with 3× surge
+    ps.machineGroups['mgc1'] = {
+      config: { general: { name: 'mgc1' } },
+      turnOffAllMachines: () => {
+        ps.measurements.type('flow').variant('predicted').position('out').child('mgc1').value(0, Date.now(), 'm3/s');
+      },
+      handleInput: async (_src, demand) => {
+        const d = Math.max(0, Math.min(100, Number(demand) || 0));
+        const outflow = (d / 100) * MAX_OUTFLOW;
+        ps.measurements.type('flow').variant('predicted').position('out').child('mgc1').value(outflow, Date.now(), 'm3/s');
+      },
+    };
+    ps.calibratePredictedLevel(2.5);
+  },
+
+  inputs: (t, ps) => {
+    const surge = (t >= 300 && t < 600) ? 0.024 : 0.008;
+    ps.setManualInflow(surge, Date.now(), 'm3/s');
+  },
+
+  expectations: [
+    { 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 },
+  ],
+};
--- a/eval/scenarios/safety-dry-run-trip.js
+++ b/eval/scenarios/safety-dry-run-trip.js
@@ -0,0 +1,66 @@
+// Dry-run safety trip — manual mode, fixed high demand, zero inflow.
+// Levelbased control would taper demand as the level drops (its ramp),
+// stalling drainage before safety fires. Manual mode holds demand
+// constant so the level actually reaches the dry-run threshold.
+
+module.exports = {
+  name: 'safety-dry-run-trip',
+  description: 'Manual mode, constant 100 % demand, zero inflow; expect safety to force-stop downstream pumps when level reaches the dry-run threshold.',
+  durationSec: 600,
+
+  config: {
+    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 },
+    hydraulics: { refHeight: 'NAP', basinBottomRef: 0, minHeightBasedOn: 'outlet' },
+    control: {
+      mode: 'manual',
+      allowedModes: new Set(['levelbased', 'manual']),
+      levelbased: { minLevel: 0.5, startLevel: 2, maxLevel: 4 },
+    },
+    safety: {
+      enableDryRunProtection: true,
+      dryRunThresholdPercent: 50,
+      enableOverfillProtection: false,
+      overfillThresholdPercent: 98,
+      timeleftToFullOrEmptyThresholdSeconds: 0,
+    },
+  },
+
+  setup: async (ps) => {
+    const MAX_OUTFLOW = 0.04;
+    let mgcRunning = true;  // gets toggled by safety's shutdown call
+    ps.machineGroups['mgc1'] = {
+      config: { general: { name: 'mgc1', id: 'mgc1' }, functionality: { positionVsParent: 'downstream' } },
+      turnOffAllMachines: () => {
+        mgcRunning = false;
+        ps.measurements.type('flow').variant('predicted').position('out').child('mgc1').value(0, Date.now(), 'm3/s');
+      },
+      handleInput: async (_src, demand) => {
+        if (!mgcRunning) return;
+        const d = Math.max(0, Math.min(100, Number(demand) || 0));
+        ps.measurements.type('flow').variant('predicted').position('out').child('mgc1').value((d / 100) * MAX_OUTFLOW, Date.now(), 'm3/s');
+      },
+    };
+    // Need a downstream machine for safety to shut down
+    ps.machines['pump1'] = {
+      config: { general: { name: 'pump1', id: 'pump1' }, functionality: { positionVsParent: 'downstream' } },
+      _isOperationalState: () => mgcRunning,
+      handleInput: async (_src, action) => {
+        if (action === 'execSequence') mgcRunning = false;
+      },
+    };
+    ps.calibratePredictedLevel(2.5);
+  },
+
+  inputs: (t, ps) => {
+    ps.setManualInflow(0, Date.now(), 'm3/s');
+    if (ps.mode === 'manual') ps.forwardDemandToChildren(100);
+  },
+
+  expectations: [
+    { name: 'safety engages at some point', type: 'safety_trips_gt', value: 0 },
+    { name: 'level never goes below outflow pipe', type: 'min_level_bounded', value: 0.2 },
+  ],
+};