Software framework and limitations

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

Table 1 WNTR Subpackages
Subpackage Description
epanet Contains EPANET 2 compatibility functions for WNTR.
metrics Contains methods to compute resilience, including hydraulic, water quality, water security, and economic metrics. Methods to compute topographic metrics are included in the wntr.network.graph module.
network Contains methods to define a water network model, network controls, and graph representation of the network.
scenario Contains methods to define disaster scenarios and fragility/survival curves.
sim Contains methods to run hydraulic and water quality simulations using the water network model.
graphics Contains methods to generate graphics.
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 Classes in the network Subpackage
Class Description
WaterNetworkModel Contains methods to generate water network models, including methods to read and write INP files, and access/add/remove/modify network components. This class links to additional model classes (below) which define network components, controls, and model options.
Junction Contains methods to define junctions. Junctions are nodes where links connect. Water can enter or leave the network at a junction.
Reservoir Contains methods to define reservoirs. Reservoirs are nodes with an infinite external source or sink.
Tank Contains methods to define tanks. Tanks are nodes with storage capacity.
Pipe Contains methods to define pipes. Pipes are links that transport water.
Pump Contains methods to define pumps. Pumps are links that increase hydraulic head.
Energy Contains attributes for specifying global energy prices and global pump efficiencies.
Valve Contains methods to define valves. Valves are links that limit pressure or flow.
Curve Contains methods to define curves. Curves are data pairs representing a relationship between two quantities. Curves are used to define pump curves.
Source Contains methods to define sources. Sources define the location and characteristics of a substance injected directly into the network.
TimeControl Contains methods to define time controls. Time controls define actions that start or stop at a particular time.
ConditionalControl Contains methods to define conditional controls. Conditional controls define actions that start or stop based on a particular condition in the network.
WaterNetworkOptions Contains methods to define model options, including the simulation duration and time step.

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 Classes in the sim Subpackage
Class Description
EpanetSimulator The EpanetSimulator uses the EPANET 2 Programmer’s Toolkit [Ross00] to run demand-driven hydraulic simulations and water quality simulations. 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 read in INP files, modify the model, run an EPANET simulation, and analyze results all within WNTR.
WNTRSimulator The WNTRSimulator uses custom Python solvers to run demand-driven and pressure dependent demand hydraulic simulation and includes models to simulate pipe leaks. The WNTRSimulator does not perform water quality simulations.

Limitations

Current software limitations are noted:

  • Certain EPANET INP model options are not supported in WNTR, as outlined below.
  • Pressure dependent demand hydraulic simulation and leak models are only available using the WNTRSimulator.
  • Water quality simulations are only available using the EpanetSimulator.

WNTR reads in 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 following model options cannot be modified/created in WNTR:

  • [BACKDROP] section
  • Efficiency curves in the [CURVES] section
  • [DEMANDS] section (base demand and patterns from the [JUNCTIONS] section can be modified)
  • [EMITTERS] section
  • [LABELS] section
  • [MIXING] section
  • [REPORT] section
  • [VERTICES] section

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 WNTRSimualtor:

  • [DEMANDS] section (base demand and patterns from the [JUNCTIONS] section are used)
  • [EMITTERS] section
  • D-W and C-M headloss options in the [OPTIONS] section (H-W option is used)
  • Accuracy, unbalanced, demand multiplier, and emitter exponent from the [OPTIONS] section
  • Speed option and multipoint head curves in the [PUMPS] section (3-point head curves are supported)
  • Head pattern option in the [RESERVOIRS] section
  • Volume curves in the [TANKS] section
  • Rule timestep, pattern start, report start, start clocktime, and statistics in the [TIMES] section
  • PSV, PBV, and GPV values in the [VALVES] section

Future development of WNTR will address these limitations.