SurgeSpaceDocsTheory and validation

Theory and validation

The methods behind SurgeSpace (steady state, method of characteristics with column separation, rigid column, extended period) and every validation check.

SurgeSpace theory and validation

1. Steady state#

Global gradient algorithm (Todini–Pilati), as EPANET: Darcy–Weisbach (Swamee–Jain / laminar) or Hazen–Williams friction, minor losses, pump curves as EPANET interprets them (one point, three points, multi-point), control valves (PRV, PSV, FCV) by status iteration, pressure-breaker and general-purpose valves, non-return valves, variable-speed pumps whose speed is found (secant) to meet a pressure set point.

Emitters (Q = C·p^γ) and pressure-driven demands (EPANET 2.2: D·((p − p_min)/(p_req − p_min))^e between the two pressures) are links to a virtual source at the node elevation, linearised in the same Newton iteration, with the demand held at zero or in full while the pressure stays beyond the limits. In the surge engines the emitter keeps discharging C·p^γ at every step.

2. Wave engine (method of characteristics)#

  • Characteristic equations on a fixed grid; one time step for the whole network, pipe wave speeds adjusted within a tolerance (default 0.5 %) and reported; very short pipes become rigid columns.
  • Column separation: discrete gas cavity model (free gas fraction 10⁻⁷ by default), solved in closed form at every section, so vapour cavities form and collapse without spurious spikes.
  • Unsteady friction: Brunone–Vítkovský with Vardy's shear decay coefficient.
  • Viscoelastic pipe walls (PE, PVC): Kelvin–Voigt creep elements; the retarded strain is integrated exactly over the step and implicitly in the new head inside the cavity model, so it stays stable at any compliance.
  • Boundary conditions solved implicitly with the connected characteristics: pumps (homologous head and torque, inertia run-down, controlled ramps, starts, variable-speed PI control), four-quadrant pumps (generic odd/even form fitted to the pump curve, or tabulated Suter WH/WB), valves (stroke laws, manufacturer curves, active control valves with response time), check valves (ideal, delay, reverse velocity, dynamic characteristic), air vessels (polytropic gas, shape, bladder, dip tube, bypass), air valves (isentropic air flow, three-stage, curves), open and one-way tanks, anticipator, relief, outlets and burst discs, turbines (gate operation and speed).
  • Differential (Johnson) surge tanks: the riser follows the pipe head (with its connection loss); the chamber fills and empties through the ports (orifice law, implicit chamber level over the step); the riser overflows into the chamber. Both engines.
  • Motor start-up: the speed comes from the torque balance I·dω/dt = T_motor(ω) − T_pump(ω, Q), with the motor torque–speed curve (typical design B or a table), star–delta (torque / 3 below the switch speed) or a soft starter (torque ∝ V², voltage ramp). Both engines.
  • Turbine runner characteristics: flow and efficiency follow the unit speed ν = (n/n_r)/√(H/H_r) (Francis low and high specific speed, Kaplan, Pelton or a table; efficiency zero at runaway), with the runner speed integrated in the time loop from the power balance and the governor acting on the gates.
  • Slams at check valves and air valves are detected and reported with the Joukowsky estimate and the computed rise.

3. Rigid-column engine#

L/(gA)·dQ/dt = ΔH − losses for each pipe, continuity at the nodes, pump speed from the torque balance and storage devices (vessels, tanks) — solved together by Newton's method at each implicit step. No pressure waves. On large models each Newton step eliminates the link, pump-speed and device unknowns (each local to one link or node), leaving a sparse symmetric system in the node heads solved by preconditioned conjugate gradients; it gives the same answers as the dense solve.

4. Extended period and water quality#

Sequence of steady states with tank level integration, pattern steps, simple controls (time, clock, level, pressure) with the step cut exactly at the level, rule-based controls with EPANET's rule step and premise logic, full/empty tank handling. Water quality by Lagrangian segments (EPANET's method): age, trace, first-order bulk and wall reactions with mass transfer (Sherwood number), completely mixed tanks, boosters and source concentrations.

5. Validation (run in continuous integration unless a script is named)#

Check Reference Result
Steady heads and flows EPANET 2.2 see validation/steady-vs-epanet.ts (needs the reference folder)
PRV, PSV, FCV, PBV, GPV, TCV EPANET 2.2 heads within 0.003 m, flows within 0.01 L/s
Extended period, Net1/Net2/Net3 EPANET 2.2 heads within 0.04 m
Rule-based controls (Net1 with four rules) EPANET 2.2 heads within 0.008 m
Chlorine, Net1 EPANET 2.2 within 0.003 mg/L
Water age, Net1/Net2/Net3 EPANET 2.2 95 % of values within 0.2 h
Transient, Net3 valve closure TSNet see validation/transient-vs-tsnet.ts
Transient benchmarks Tnet0, Tnet3 published benchmark results see validation/README.md
Joukowsky rise, wave period, line packing closed form engine tests
Surge tank mass oscillation Jaeger's formula; wave engine within 5 %; engines agree within 1 %
Pipe force on a straight pipe ρ·a·V·A within 12 % (line packing)
Variable-speed drive set point holds the pressure in steady state and after a demand step
Differential surge tank limits: ports wide open = plain tank of full area; ports shut = riser alone within 5 %; engines agree within 2 %
Motor start final speed and duty; run-up order DOL < star–delta < soft start speed within 3 % of rated; engines agree
Turbine runner characteristics trends: Francis chokes (higher rise), Kaplan relieves (lower rise) vs a speed-independent runner as expected; steady state unchanged
Pipe class optimisation rising main feasible, cheaper than the highest classes, higher class near the pumps
Emitters (leakage), Net1 over 24 h EPANET 2.2 heads within 0.008 m, demands within 0.003 L/s
Pressure-driven demand, Net1 over 24 h EPANET 2.2 heads within 0.007 m, demands within 0.005 L/s
Differential surge tank SciPy ODE integration (independent code) upsurge equal to 0.01 %; history within 0.06 m
Motor start (direct on line) SciPy ODE integration (independent code) rigid within 0.03 %, wave within 1.2 % (compressibility)
Rigid-column sparse solve dense solve identical results; 3,000-pipe grid at about 0.1 s per step
Calibration synthetic field data recovers roughness ×3 and demand ×1.2
UTM conversion PROJ within 0.2 mm
DXF export ezdxf (independent reader) no audit errors
QGIS plug-in QGIS 3.34 (headless) export, SurgeSpace import and results layers
Network from a plan drawing (DXF) KY4, a real distribution network (959 junctions, 1,156 pipes with 2,812 bends, 2 pumps, 4 tanks, 1 reservoir) drawn as a DXF in feet with level, size and TWL texts, symbols and clutter; compared with the network it was drawn from 99.8 % of nodes and 99.5 % of pipes found between the right nodes; levels 99.8 % within 1 cm; sizes 99.5 %; lengths along the bends 99.8 %; sources and water levels all correct; steady heads against an independently built model: median 0.03 m, 95 % within 0.29 m (the rest is where pipes in the source data run within a metre of a junction they do not join, which a drawing cannot tell apart)
Network from schedules EPANET Net3 written as node and link schedules (Excel layout) and read back by the header rules heads equal within 0.0004 m
Pump curve digitised by hand a raster graph with a known curve; a published extension-service curve (2,000 gpm at 80 ft, stated in its text) within 0.3 units; 2,000 gpm read as 79.8 ft
Pump curve fitted to points an exact quadratic recovered exactly at shut-off, duty and end

Reference data and generators: validation/data/ (WNTR scripts and JSON results).