Software framework and limitations#

Before using WNTR, it is helpful to understand the software framework. WNTR is a Python package, which contains several subpackages, listed in Table 1. Each subpackage contains modules that contain classes, methods, and functions. The classes used to generate water network models and run simulations are described in more detail below, followed by a list of software limitations.

See API documentation for more information on the code structure.

Table 1 WNTR Subpackages#
Subpackage	Description
`network`	Contains classes and methods to define a water network model, network controls, model options, and graph representation of the network.
`scenario`	Contains classes and methods to define disaster scenarios and fragility/survival curves.
`sim`	Contains classes and methods to run hydraulic and water quality simulations using the water network model.
`metrics`	Contains functions to compute resilience, including topographic, hydraulic, water quality, water security, and economic metrics.
`morph`	Contains methods to modify water network model morphology, including network skeletonization, modifying node coordinates, and splitting or breaking pipes.
`gis`	Contains geospatial capabilities, including a function to convert the water network model to GeoDataFrames.
`graphics`	Contains functions to generate graphics.
`epanet`	Contains EPANET 2.00.12 and EPANET 2.2.0 compatibility class and methods for WNTR.
`utils`	Contains helper functions.

Water network model#

The network subpackage contains classes to define the water network model, network controls, and graph representation of the network. These classes are listed in Table 2. Water network models can be built from scratch or built directly from EPANET INP files. Additionally, EPANET INP files can be generated from water network models.

Table 2 Network Classes#
Class	Description
`WaterNetworkModel`	Class to generate water network models, including methods to read and write EPANET INP files, and access/add/remove/modify network components. This class links to additional network classes that are listed below to define network components, controls, and model options.
`Junction`	Class to define junctions. Junctions are nodes where links connect. Water can enter or leave the network at a junction.
`Reservoir`	Class to define reservoirs. Reservoirs are nodes with an infinite external source or sink.
`Tank`	Class to define tanks. Tanks are nodes with storage capacity.
`Pipe`	Class to define pipes. Pipes are links that transport water.
`Pump`	Class to define pumps. Pumps are links that increase hydraulic head.
`Valve`	Class to define valves. Valves are links that regulate pressure or flow.
`Curve`	Class to define curves. Curves are data pairs representing a relationship between two quantities. Curves are used to define pump, efficiency, headloss, and volume curves.
`Source`	Class to define sources. Sources define the location and characteristics of a substance injected directly into the network.
`Demands`	Class to define multiple demands per junction. Demands are the rate of withdrawal from the network.
`Pattern`	Class to define patterns. Demands, reservoir heads, pump schedules, and water quality sources can have patterns associated with them.
`Control`	Class to define controls. Controls define a single action based on a single condition.
`Rule`	Class to define rules. Rules can define multiple actions and multiple conditions.
`Options`	Class to define model options, including the simulation duration and timestep.

Simulators#

The sim subpackage contains classes to run hydraulic and water quality simulations using the water network model. WNTR contains two simulators: the EpanetSimulator and the WNTRSimulator. These classes are listed in Table 3.

Table 3 Simulator Classes#
Class	Description
`EpanetSimulator`	The EpanetSimulator can run both the EPANET 2.00.12 Programmer’s Toolkit [22] and EPANET 2.2.0 Programmer’s Toolkit [21] to run hydraulic and water quality simulations. EPANET 2.2.0 (which is used by default) includes both demand-driven and pressure dependent analysis, while EPANET 2.00.12 includes only demand-driven analysis. When using the EpanetSimulator, the water network model is written to an EPANET INP file which is used to run an EPANET simulation. This allows the user to run EPANET simulations, while taking advantage of additional analysis options in WNTR.
`WNTRSimulator`	The WNTRSimulator uses custom Python solvers to run demand-driven and pressure dependent demand hydraulic simulations and includes models to simulate pipe leaks. The simulator includes an algebraic model, which can be extended to simulate additional components or behaviors in water network models. The WNTRSimulator does not perform water quality simulations.

Limitations#

Current WNTR limitations include:

Certain EPANET INP model options are not supported in WNTR, as outlined below.
Water quality simulations are only available using the EpanetSimulator.
Use of the “MAP” file option in EPANET will not automatically assign node coordinates from that file.

WNTR reads and writes all sections of EPANET INP files. This includes the following sections: [BACKDROP], [CONTROLS], [COORDINATES], [CURVES], [DEMANDS], [EMITTERS], [ENERGY], [JUNCTIONS], [LABELS], [MIXING], [OPTIONS], [PATTERNS], [PIPES], [PUMPS], [QUALITY], [REACTIONS], [REPORT], [RESERVOIRS], [RULES], [SOURCES], [TAGS], [TANKS], [TIMES], [TITLE], [VALVES], and [VERTICES].

However, the [LABELS] section cannot be modified/created through the WNTR API.

While the EpanetSimulator uses all EPANET model options, several model options are not used by the WNTRSimulator. Of the EPANET model options that directly apply to hydraulic simulations, the following options are not supported by the WNTRSimulator:

[EMITTERS] section
D-W and C-M headloss options in the [OPTIONS] section (H-W option is used)
Accuracy, unbalanced, and emitter exponent from the [OPTIONS] section
Pump speed in the [PUMPS] section
Report start and statistics in the [TIMES] section
PBV and GPV values in the [VALVES] section

Future development of WNTR will address these limitations.

Discrepancies#

Known discrepancies between the WNTRSimulator and EpanetSimulator are listed below.

Tank draining: The EpanetSimulator (and EPANET) continue to supply water from tanks after they reach their minimum elevation. This can result in incorrect system pressures. See issues at the following sites: USEPA/WNTR#210 and OpenWaterAnalytics/EPANET#623. The EPANET dll in WNTR will be updated when an EPANET release is available.
Pump controls and patterns: Pumps have speed settings which are adjustable by controls and/or patterns. With the EpanetSimulator, controls and patterns adjust the actual speed. With the WNTRSimulator, pumps have a ‘base speed’ (similar to junction demand and reservoir head), controls adjust the base speed, and speed patterns are a multiplier on the base speed. Results from the two simulators can match by scaling speed patterns and using controls appropriately.
Leak models: Leak models are only available using the WNTRSimulator. Emitters can be used to model leaks in EPANET.
Multi-point head pump curves: When using the EpanetSimulator, multi-point head pump curves are created by connecting the points with straight-line segments. When using the WNTRSimulator, the points are fit to the same \(H = A - B*Q^C\) function that is used for 3-point curves.
Variable required pressure, minimum pressure, and pressure exponent: Junction attributes can be used to assign spatially variable required pressure, minimum pressure, and pressure exponent. These attributes are only used for pressure dependent demand simulation with the WNTRSimulator. If the junction attributes are set to None (the default value), then the required pressure, minimum pressure, and pressure exponent defined in the global hydraulic options (wn.options.hydraulic) are used for that junction. Pressure dependent demand simulation using the EpanetSimulator always uses values in the global hydraulic options.
Pattern interpolation: The WNTRSimulator can include pattern interpolation by setting wn.options.time.pattern_interpolation. If True, interpolation is used to determine pattern values between pattern timesteps. If False, the step-like behavior from EPANET is used. Interpolation with a shorter hydraulic timestep can make problems with large changes in patterns (e.g., large changes in demand) easier to solve. The default is False.