Appendix: Hydraulic Reference

Appendix A: Extended Period Simulation (EPS)

This appendix documents the architecture and mathematical foundation of the R-THYM Extended Period Simulation (EPS) engine.

While the R-THYM transient solver (RTHYM-MOC) is an entirely custom-built C++ and JavaScript engine (detailed in Appendix B), the standard EPS engine relies on a hybrid approach: it uses the open-source epanet.js toolkit to solve the core non-linear hydraulic equations for static snapshots, while managing all time-stepping, state integration, and advanced controls via a custom JavaScript orchestration layer.

A.1 Hybrid EPS Architecture

In a traditional EPANET desktop simulation, the EPANET solver manages its own internal simulation clock, integrating tank levels and evaluating rule-based controls autonomously over time.

R-THYM completely bypasses EPANET's internal clock and control rules.

Instead, R-THYM operates the epanet.js solver purely as a "stateless" steady-state calculator. At every simulation time step, the R-THYM orchestration engine performs the following loop:

State Synchronization: R-THYM calculates the current state of the world (including time-varying patterns, stochastic demand noise, power constraints, and current tank levels) and explicitly overwrites the boundary conditions of the underlying epanet.js model.
Hydraulic Solve: R-THYM triggers a single static hydraulic solve (project.runH()).
Extraction & Post-Processing: R-THYM extracts the resulting pipe flows and nodal pressures.
State Integration: R-THYM's custom physics engine performs mass-balance calculations to update tank levels and accumulates energy/power metrics before advancing the clock.

This decoupled architecture allows R-THYM to inject complex, real-time interactive behaviors (such as dragging sliders, power grid outages, or dynamic stochastic noise) that are impossible to model using standard EPANET control rules.

A.2 Tank Mass Balance

Because epanet.js is only solving a static snapshot at any given moment, it has no knowledge of how much water is accumulating in or draining from the tanks. R-THYM must perform strict mass balance tracking manually.

A.2.1 Explicit Level Integration

Following each steady-state solve, R-THYM sums the net flow ($Q_\text{net}$) entering or leaving each tank. The change in volume is calculated by multiplying the net flow by the duration of the time step ($\Delta t$):

$$\Delta V = Q_\text{net} \times \Delta t$$

The new water surface elevation (and corresponding percentage full) is then calculated based on the tank's geometry (Diameter and Max Depth). This updated level serves as the static fixed-head boundary condition ($H$) for the epanet.js solver in the next time step.

A.2.2 Strict Bounds Enforcement (Network Propagation)

A common issue in standard hydraulic modeling occurs when a tank completely drains (hits 0%) but downstream demand still exists, or when a tank overflows (hits 100%) but supply continues.

R-THYM implements an aggressive iterative correction algorithm to enforce strict mass balance bounds: - Empty Tanks: If a tank's level drops to 0% and the total demand pulling from the tank exceeds the available supply filling it, R-THYM computes a reduction ratio ($R = \text{Supply} / \text{Demand}$). It then iteratively throttles the flows in all outgoing pipes by this ratio. This prevents the tank from drawing "phantom" negative volume while accurately simulating the resulting pressure drop in the starved downstream network. - Full Tanks: Conversely, if a tank hits 100% and supply exceeds demand, R-THYM throttles the incoming pipe flows, simulating the physical reality of an altitude valve shutting or a pump backing up on its curve due to a full vessel.

A.3 Additional Custom Physics

Beyond tank mass balance, the custom orchestration layer handles several advanced physical phenomena during EPS:

A.3.1 Stochastic Demand Generation

While traditional models use deterministic daily multipliers, R-THYM allows Inflow and Outflow nodes to exhibit random, stochastic variations in flow.

This is achieved using a discrete autoregressive (AR1) noise model updated at every time step. The user-defined Autocorrelation parameter dictates how smoothly the demand drifts, while the Standard Deviation determines the amplitude of the noise. This forces the hydraulic solver to respond to realistic, unpredictable "noisy" boundary conditions.

A.3.2 Power-Constrained Hydraulics

In EPANET, a pump runs if its rule says "ON". In R-THYM, a pump will only run if it traces a continuous, unbroken path through the electrical topology to an active power source (like the Utility Grid or a Solar Array). The orchestration layer evaluates this electrical graph before syncing the pump status to the hydraulic solver. If a power switch is tripped, all dependent pumps immediately snap to zero speed, and their corresponding EPANET links are closed or set to zero speed for the next hydraulic solve.

A.4 Composite Nodes (Pumps, Valves, Turbines)

Standard EPANET models pumps and valves as links (directional connections between two discrete junction nodes). However, to make the user experience more intuitive and visually streamlined, R-THYM represents Pumps, Valves, and Turbines as single nodes on the canvas.

To bridge the gap between the intuitive visual interface and the strict EPANET solver requirements, R-THYM dynamically assembles a "Composite Node" topology under the hood before every simulation:

Topology Generation: When you place a Valve_A node on the canvas, the R-THYM generator.js secretly splits it into three EPANET components: an upstream junction (Valve_A_in), a downstream junction (Valve_A_out), and an internal EPANET link connecting them (Valve_A_link).
Dynamic Physics Mapping:
Pumps: The visual node's instantaneous _currentSpeed (0-100%) is mapped directly to the internal EPANET pump link's EN_SETTING parameter.
Valves: The valve opening (1-100%) is mathematically converted into a dynamic minor loss coefficient ($K$). The internal EPANET link is modeled as a pipe, and its EN_MINORLOSS is updated dynamically at each time step using the formula $K = (100 / \text{setting})^2 - 1$.
Turbines: EPANET does not natively support turbines. R-THYM models them as pipes with a dynamic minor loss coefficient. A baseline $K$ is calculated to achieve the user-defined Design Head drop at the Design Flow. This baseline is then scaled by the turbine's gate opening percentage and passed to the internal link's EN_MINORLOSS.
Extraction & Reassembly: After the EPANET solver completes its static snapshot, R-THYM extracts the flows, headloss, and pressures from the internal _in / _out junctions and the _link, calculates power/efficiency metrics, and reassembles them back into a single set of telemetry metrics for the visual node.

A.5 Visual Control Links (Rules & PID)

EPANET traditionally handles logic via text-based, sequential "Rules" (e.g., RULE 1 IF NODE A BELOW 50 THEN PUMP B IS ON). R-THYM replaces this text-based system entirely with Control Links—visual logic connections drawn directly on the canvas between a monitoring node (like a Tank) and an active component (like a Pump or Valve).

The orchestration layer evaluates these Control Links natively before the component states are mapped to the EPANET solver. This supports several advanced control schemas that are difficult or impossible in raw EPANET:

A.5.1 Deadband Control (Fill/Drain)

You can define a Target level and a Deadband. For example, setting a Target of 50% with a Deadband of 10% on a "Fill" action means the pump will turn ON when the tank hits 45%, and stay ON until the tank hits 55%. This provides built-in hysteresis to prevent pump short-cycling.

A.5.2 Continuous PID Control

Unlike standard EPANET controls which primarily toggle states (ON/OFF or fixed settings), R-THYM features a true discrete PID (Proportional-Integral-Derivative) controller. The orchestration engine calculates the error between the monitored value (like Tank Level) and the Target, computes the discrete P, I, and D terms over the time step, and dynamically outputs an instantaneous _targetSetting percentage. This allows variable speed pumps or modulating valves to smoothly seek an equilibrium state.

A.5.3 Pump Control Valve (PCV) Sequencing

R-THYM natively supports PCV logic. When a pump receives a command to shut down, the orchestration layer intercepts it, begins closing the associated discharge valve, and forces the pump to remain ON in a "surge override" state until the valve is completely closed. Only then is the pump tripped to OFF. This mimics real-world soft-shutdown sequences to mitigate water hammer, which EPANET cannot natively sequence.