Hydraulic simulation

WNTR contains two simulators: the WNTRSimulator and the EpanetSimulator. See Software framework and limitations for more information on features and limitations of these simulators.

The EpanetSimulator can be used to run demand-driven hydraulic simulations using the EPANET 2 Programmer’s Toolkit. The simulator can also be used to run water quality simulations, as described in Water quality simulation. A hydraulic simulation using the EpanetSimulator is run using the following code:

epanet_sim = wntr.sim.EpanetSimulator(wn)
epanet_sim_results = epanet_sim.run_sim()

The WNTRSimulator is a pure Python hydraulics simulation engine based on the same equations as EPANET. The WNTRSimulator does not include equations to run water quality simulations. The WNTRSimulator includes the option to simulate leaks, and run hydraulic simulations in either demand-driven or pressure dependent demand mode. A hydraulic simulation using the WNTRSimulator is run using the following code:

wntr_sim = wntr.sim.WNTRSimulator(wn)
wntr_sim_results = wntr_sim.run_sim()

The example hydraulic_simulation.py can be used to run both simulators.

More information on the simulators can be found in the API documentation, under EpanetSimulator and WNTRSimulator.


Hydraulic simulation options are defined in the WaterNetworkOptions class. These options include duration, hydraulic timestep, rule timestep, pattern timestep, pattern start, default pattern, report timestep, report start, start clocktime, headloss, trials, accuracy, unbalanced, demand multiplier, and emitter exponent. All options are used with the EpanetSimulator. Options that are not used with the WNTRSimulator are described in Limitations.

Mass balance at nodes

Both simulators use the mass balance equations from EPANET [Ross00]:

\[\sum_{p \in P_{n}} q_{p,n} - D_{n}^{act} = 0 \hspace{1in} \forall n \in N\]

where \(P_{n}\) is the set of pipes connected to node \(n\), \(q_{p,n}\) is the flow rate of water into node \(n\) from pipe \(p\) (m³/s), \(D_{n}^{act}\) is the actual demand out of node \(n\) (m³/s), and \(N\) is the set of all nodes. If water is flowing out of node \(n\) and into pipe \(p\), then \(q_{p,n}\) is negative. Otherwise, it is positive.

Headloss in pipes

Both simulators use the Hazen-Williams headloss formula from EPANET [Ross00]:

\[H_{n_{j}} - H_{n_{i}} = h_{L} = 10.667 C^{-1.852} d^{-4.871} L q^{1.852}\]

where \(h_{L}\) is the headloss in the pipe (m), \(C\) is the Hazen-Williams roughness coefficient (unitless), \(d\) is the pipe diameter (m), \(L\) is the pipe length (m), \(q\) is the flow rate of water in the pipe (m³/s), \(H_{n_{j}}\) is the head at the starting node (m), and \(H_{n_{i}}\) is the head at the ending node (m).

The flow rate in a pipe is positive if water is flowing from the starting node to the ending node and negative if water is flowing from the ending node to the starting node.

The WNTRSimulator solves for pressures and flows throughout the network as a set of linear equations. However, the Hazen-Williams headloss formula is not valid for negative flow rates. Therefore, the WNTRSimulator uses a reformulation of this constraint.

For \(q<0\):

\[h_{L} = -10.667 C^{-1.852} d^{-4.871} L |q|^{1.852}\]

For \(q \geq 0\):

\[h_{L} = 10.667 C^{-1.852} d^{-4.871} L |q|^{1.852}\]

These equations are symmetric across the origin and valid for any \(q\). Thus, this equation can be used for flow in either direction. However, the derivative with respect to \(q\) at \(q = 0\) is \(0\). In certain scenarios, this can cause the Jacobian of the set of hydraulic equations to become singular (when \(q=0\)). To overcome this limitation, the WNTRSimulator splits the domain of \(q\) into six segments to create a piecewise smooth function.

Demand-driven simulation

In demand-driven simulation, the pressure in the system depends on the node demands. The mass balance and headloss equations described above are solved assuming that node demands are known and satisfied. This assumption is reasonable under normal operating conditions and for use in network design. Both simulators can run hydraulics using demand-driven simulation.

Pressure dependent demand simulation

In situations that lead to low pressure conditions (i.e., fire fighting, power outages, pipe leaks), consumers do not always receive their requested demand and a pressure dependent demand simulation is recommended. In a pressure dependent demand simulation, the delivered demand depends on the pressure. The mass balance and headloss equations described above are solved by simultaneously determining demand along with the network pressures and flow rates.

The WNTRSimulator can run hydraulics using a pressure dependent demand simulation according to the following pressure-demand relationship [WaSM88]:

\[\begin{split}d = \begin{cases} 0 & p \leq P_0 \\ D_f(\frac{p-P_0}{P_f-P_0})^{\frac{1}{2}} & P_0 \leq p \leq P_f \\ D^f & p \geq P_f \end{cases}\end{split}\]

where \(d\) is the actual demand (m³/s), \(D_f\) is the desired demand (m³/s), \(p\) is the pressure (Pa), \(P_f\) is the pressure above which the consumer should receive the desired demand (Pa), and \(P_0\) is the pressure below which the consumer cannot receive any water (Pa). The set of nonlinear equations comprising the hydraulic model and the pressure-demand relationship is solved directly using a Newton-Raphson algorithm.

Figure 6 illustrates the pressure-demand relationship using both the demand-driven and pressure dependent demand simulations. In the example, \(D_f\) is 0.0025 m³/s (39.6 GPM), \(P_f\) is 30 psi, and \(P_0\) is 5 psi. Using the demand-driven simulation, the demand is equal to \(D_f\) regardless of pressure. Using the pressure dependent demand simulation, the demand starts to decrease when the pressure is below \(P_f\) and goes to 0 when pressure is below \(P_0\).

Pressure driven example

Figure 6 Example relationship between pressure (p) and demand (d) using both the demand-driven and pressure dependent demand simulations.

Leak model

The WNTRSimulator includes the ability to add leaks to the network. The leak is modeled with a general form of the equation proposed by Crowl and Louvar [CrLo02] where the mass flow rate of fluid through the hole is expressed as:

\[d_{leak} = C_{d} A p^{\alpha} \sqrt{\frac{2}{\rho}}\]

where \(d_{leak}\) is the leak demand (m³/s), \(C_d\) is the discharge coefficient (unitless), \(A\) is the area of the hole (m²), \(p\) is the gauge pressure inside the pipe (Pa), \(\alpha\) is the discharge coefficient, and \(\rho\) is the density of the fluid. The default discharge coefficient is 0.75 (assuming turbulent flow), but the user can specify other values if needed. The value of \(\alpha\) is set to 0.5 (assuming large leaks out of steel pipes). Leaks can be added to junctions and tanks. A pipe break is modeled using a leak area large enough to drain the pipe. WNTR includes methods to add leaks to any location along a pipe by splitting the pipe into two sections and adding a node.

Figure 7 illustrates leak demand. In the example, the diameter of the leak is set to 0.5 cm, 1.0 cm, and 1.5 cm.

Leak demand

Figure 7 Example relationship between leak demand (d) and pressure (p).

Pause and restart

The WNTRSimulator includes the ability to

  • Reset initial values and re-simulate using the same water network model. Initial values include tank head, reservoir head, pipe status, pump status, and valve status.
  • Pause a hydraulic simulation, change network operations, and then restart the simulation
  • Save the water network model and results to files and reload for future analysis

These features are helpful when evaluating various response action plans or when simulating long periods of time where the time resolution might vary. The file hydraulic_simulation.py includes examples of these features.