EPyT: An EPANET-Python Toolkit for Smart Water Network Simulations

This paper introduces EPyT, an open-source Python package for providing a Python-based programming interface with the open-source hydraulic and quality modeling software EPANET, created by the US Environmental Protection Agency. EPyT extends the standard capabilities of the EPANET library, through the addition of new methods for research purposes. In addition to the extensive Application Programming Interface, EPyT is accompanied by a collection of water distribution benchmarks and more than 25 code examples that researchers can use as a starting point


Challenge
Both methods (direct calls and wrappers) are limited to the functions made available in the library and typically require a sufficient level of expertise in managing different data types and structures.Specifically, the fact that different researchers developed different data structures implies that sharing and reusing open-source code and releasing reproducible code using a standardized framework is not easy.With the increasing popularity of Python in both industry and academia, a comprehensive toolkit was missing to support a wide area of applications in Smart Water Network (SWN) research and development.This paper introduces the EPANET-Python Toolkit (EPyT), for performing research-related computations (e.g., simulations) and other types of analysis (e.g., graph theory), of drinking water distribution systems.Specifically, this software aims to solve the following problems: 1. Provide a standardized framework for researchers working in the area of SWN to implement their scientific findings.2. Reduce the time and effort needed to establish a connection with the EPANET libraries.(Klise et al., 2017).WNTR facilitates the simulation of both hydraulic and quality dynamics, and in addition, it allows the simulation of various events such as pipe breaks, disasters such as earthquakes, power outages, fires, and contamination events.At the moment, WNTR includes only a subset of EPANET functions necessary for its simulation capabilities.The Object-Oriented Pipe Network Analyzer (OOPNET) is a Python package that allows modelling and simulating hydraulic water distribution systems (Steffelbauer & Fuchs-Hanusch, 2015).A drawback is that, since OOPNET is based on the runtime executable of EPANET, it does not provide access to the internal library functions.The OWA-EPANET is a SWIG auto-generated "thin" wrapper around the EPANET libraries.The goal of this package is to provide a Python interface that requires minimal effort to keep up to date with the core library and can be used by higher-level applications.Other Python-based EPANET toolkits include epynet, developed by Vitens, and epanettools which supports older versions of the EPANET toolkit.Recently a new tool has been published, viswaternet which provides a tool for visualizing static and time-varying attributes of EPANET-based water distribution systems; this tool can be used in parallel with EPyT for visualization purposes (Thomas et al., 2023).

State of the field
A key unique feature of EPyT, is that it captures the complete function and parameter space of EPANET.Another important aspect of EPyT is that it shares the same function names as the EPANET-MATLAB Toolkit.Our motivation is that this will facilitate the transition of state-of-the-art code originating from research and academia (which typically uses MATLAB) to more industrial applications, which typically use Python due to its open-source license and its extended set of data analytics modules.

Functionality
The EPyT python class, epanet, includes properties of the input network model, static properties, public functions, and local functions that directly call the EPANET shared object library or the executable.The full API with detailed examples is provided in the link.In the following paragraphs, we introduce a selection of the capabilities of the tool and an illustrative smart water research example.
Through EPyT, users can easily load EPANET network models, as demonstrated by importing the module and loading the L-TOWN.inpnetwork in a provided example (Vrachimis et al., 2022).
from epyt import epanet # Import the module "epanet" from the package "epyt" G = epanet('L-TOWN.inp')# Load the L-Town input file and create the object G In this example, G is an epanet object which can be defined mathematically as the set comprised of the network graph topology (such as nodes and links), structural parameters (such as pipe lengths, diameters, etc.), and functions (such as hydraulic solvers, etc.).G can also be shared between different functions as an argument.
When the object is constructed, the module reads the EPANET input network file and populates more than 500 object parameters.To view some of the parameters and receive assistance with respect to the methods, the user can use the following commands: # Lists all available functions and properties in G help(G.getNodeElevations)

# Retrieve usage examples for getNodeElevations
Using object G, the user can call all the public toolkit functions.The toolkit contains a large set of functions that allow the user to retrieve or update the network data and simulate hydraulic and quality analysis for different scenarios using the EPANET libraries.Examples of how to retrieve some common network parameter values are provided below:

getNodeElevations() # retrieve Node elevations
Variables diameters and elevations are two arrays of size 909 and 785 respectively, corresponding to the number of links, and the number of nodes in the L-Town network, respectively.Note that, in case the network model changes, these parameters will be updated.This is demonstrated in the following example: Next, we show how to simulate the water distribution network, such as flows/pressures and water quality.Various functions have been included in the toolkit to simplify the workflows of solving and retrieving the data from the library memory.One way is to solve the hydraulics and quality equations using the EPANET library and store the results in data structures H and Q.

getComputedQualityTimeSeries() # Solve quality dynamics in library
To access the different values, the user can use the dot notation, such as H.Head to create an array with the hydraulic heads and Q.NodeQuality for the water quality at the nodes.It is important to note that the time intervals may be different for the hydraulic and quality time series, due to the simulation settings; the user can call H.Time and Q.Time respectively, to retrieve the time in seconds.
Executing the function G.plot() displays a figure of the network along with its components.The nodes i.e., junctions, reservoirs, tanks, and the links, i.e., pipes, valves, and pumps, are depicted using different colors and shapes.The user can unload the EPANET dynamic library from Python memory, using the G.unload() method.
Illustrative examples, as well as use cases on how to use EPyT, are provided in the EPyT Documentation.

Conclusions
In this paper, we have introduced the EPANET-Python Toolkit, an open-source software that provides a user-friendly and intuitive interface for Python with EPANET.This research toolkit was developed with the aim of facilitating the transition of MATLAB users to Python, while offering a similar set of functions.With the EPyT toolkit, users can access EPANET through both the shared object library and the binary file.The toolkit can serve as a framework for designing new monitoring, control, and fault/event diagnosis algorithms, as well as for formulating optimization problems based on water distribution network models.Additionally, the EPANET-Python Toolkit is released under an open-source license (EUPL), allowing for contributions, issue reporting, and suggestions for improvement, in line with the best practices of the EPANET Open-Source Initiative.Future work will aim to expand the toolkit's capabilities to include the EPANET-MSX library, thus providing multi-species water quality analysis for users.
3. Provide code templates for expanding the capabilities of EPANET and facilitating smart water systems research, while supporting the adoption of open-science and reproducible research best practices.4. Provide a similar data structure in Python and MATLAB, to facilitate translation between the two environments.

Figure 1 :
Figure 1: The L-Town network layout using the plot function.
(Eliades et al., 2016), the open-source EPANET-MATLAB Toolkit (EMT) was released in 2009, and is continuously supported by the authors(Eliades et al., 2016).As a result of serving the needs of smart water researchers and the water engineering education community, it has been extended significantly.EMT provides extensive functionalities beyond the EPANET capabilities, to support the design and evaluation of research methodologies.It is currently made available under the OpenWaterAnalytics Community.Moreover, EMT introduced the epanet class, which provides standardized data structures and function names which are human-readable and self-explanatory.In addition to EPyT, a few other relevant Python-based tools connect with EPANET.The most advanced, and relevant, is the Water Network Tool for Resilience (WNTR), which was developed by the US EPA and Sandia National Laboratories, and released under the Revised BSD license