Getting started#

To start using WNTR, open a Python console or IDE like Spyder and import the package:

import wntr

WNTR comes with a simple getting started example, shown below, that uses the EPANET Example Network 3 (Net3) INP file. This example demonstrates how to:

  • Import WNTR

  • Generate a water network model

  • Simulate hydraulics

  • Plot simulation results on the network

Note

If WNTR is installed using PyPI or Anaconda, the examples folder is not included. The examples folder can be downloaded by going to USEPA/WNTR, selecting the “Clone or download” button, and then selecting “Download ZIP.” Uncompress the zip file using standard software tools (e.g., unzip, WinZip) and store them in a folder. The following example assumes the user is running the example from the examples folder.

"""
The following example demonstrates how to import WNTR, generate a water network 
model from an INP file, simulate hydraulics, and plot simulation results on the network.
"""
import wntr

# Create a water network model
inp_file = 'networks/Net3.inp'
wn = wntr.network.WaterNetworkModel(inp_file)

# Graph the network
wntr.graphics.plot_network(wn, title=wn.name)

# Simulate hydraulics
sim = wntr.sim.EpanetSimulator(wn)
results = sim.run_sim()

# Plot results on the network
pressure_at_5hr = results.node['pressure'].loc[5*3600, :]
wntr.graphics.plot_network(wn, node_attribute=pressure_at_5hr, node_size=30, 
                        title='Pressure at 5 hours')

Additional examples of Python code snippets are included throughout the WNTR documentation. The examples provided in the documentation assume that a user has experience using EPANET (https://www.epa.gov/water-research/epanet) and Python (https://www.python.org/), including the ability to install and use additional Python packages, such as those listed in Requirements and Optional dependencies.

Several EPANET INP files and Python code example files are also included in the WNTR repository in the examples folder. Example EPANET INP files are for networks that range from a simple 9 node network to a 3,000 node network. Additional network models can be downloaded from the University of Kentucky Water Distribution System Research Database at https://uknowledge.uky.edu/wdsrd.

Example files can be run as follows:

  • Open a command line or PowerShell prompt and run the example file using Python in interactive mode. This will keep Python open so that graphics can be viewed. Use exit() to close Python when done. For example, the getting started example can be run as follows:

    python -i getting_started.py
    
  • Open a Python console in script mode (no -i) and copy/paste lines of code into the Python console. Use exit() to close Python when done.

  • Open the example file within an IDE like Spyder and run or step through the file.

Example Files#

WNTR comes with Python code examples that illustrate advanced use cases, including:

  • Pipe leak, stochastic simulation example: This example runs multiple hydraulic simulations of a pipe leak scenario where the location and duration are drawn from probability distributions.

  • Pipe criticality example: This example runs multiple hydraulic simulations to compute the impact that individual pipe closures have on water pressure.

  • Fire flow example: This example runs hydraulic simulations with and without fire fighting flow demand.

  • Sensor placement example: This example is hosted in Chama repository (sandialabs/chama) and uses WNTR to optimize the placement of sensors that minimizes detection time. Note that Chama requires Pyomo and a MIP solver, see Chama installation instructions for more details.

For example, to run the pipe criticality example, run the following command:

python -i pipe_criticality.py

Additionally, the examples folder contains demonstrations using Jupyter Notebooks. A Jupyter Notebook, an open-sourced web-based application, can be accessed through Anaconda or by installing the associated software available at https://jupyter.org.

Note

When running Jupyter Notebooks outside of an Anaconda environment:

  • Install Jupyter Notebook within the virtual environment that also contains WNTR before launching any notebooks.

  • Ensure all example files are in the same directory as the virtual environment.

  • Run the notebook from this specific directory to maintain correct file path references.

WNTR Jupyter Notebook demonstrations include the following:

  • Pipe break demo: This demonstration runs multiple hydraulic simulations to compute the impact that different individual pipe breaks/closures have on network pressure. It also plots the pressure and population impacts for all junctions affected by the pipe breaks/closures.

  • Segment pipe break demo: This demonstration runs multiple hydraulic simulations to compute the impact that different pipe segment breaks/closures (identified by isolation valve locations) have on network pressure. It also plots the pressure and population impacts for all junctions affected by the pipe segment breaks/closures.

  • Fire flow demo: This demonstration runs multiple hydraulic simulations with and without fire fighting flow demand to multiple fire hydrant nodes. It also plots the pressure and population impacts for junctions affected by the additional fire fighting flow demand.

  • Earthquake demo: This demonstration runs hydraulic simulations of earthquake damage with and without repair efforts. It plots fragility curves, peak ground acceleration, peak ground velocity, repair rate, leak probability, and damage states. In addition, it compares junction pressure 24 hours into the simulation, and tank and junction pressure over time. The demonstration also plots water service availability and population impacted by low pressure conditions.

For example, to open the pipe break demo using Jupyter, run the following command:

jupyter notebook pipe_break_demo.ipynb

The Jupyter Notebook will open in a browser (e.g., Chrome, Firefox) and the example can be run using ‘Run’ button. Additional information on Jupyter Notebooks is available at https://jupyter.org.

For more details about the steps in the demonstrations, review Chapter 12: Water network tool for resilience in Embracing Analytics in the Drinking Water Industry.