# 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 EPANET 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.
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.
Demands Contains methods to define multiple demands per junction. Demands are the rate of withdrawal from the network.
Pattern Contains methods to define patterns. Demands, reservoir heads, pump schedules, and water quality sources can have patterns associated with them.
Control Contains methods to define controls. Controls define a single action based on a single condition.
Rule Contains methods to define rules. Rules can define multiple actions and multiple conditions.
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 EPANET 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:

• [EMITTERS] section
• [LABELS] section
• [MIXING] 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 WNTRSimulator:

• [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
• Multipoint curves in the [CURVES] section (3-point curves are supported)
• Pump speed in the [PUMPS] section
• Volume curves in the [TANKS] section
• 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.