3 EPANET Programmers Toolkit#

The EPANET Programmer’s Toolkit is a software applications programming interface (API) designed to facilitate the analysis and simulation of water distribution networks. Developed by the United States Environmental Protection Agency (EPA), EPANET is widely recognized as a comprehensive and reliable hydraulic and water quality modeling tool. The EPANET Programmer’s Toolkit offers engineers and researchers the ability to harness the full potential of EPANET’s capabilities, providing a platform for advanced water network analysis and optimization, directly accessing the computation engine without requiring the Graphical User Interface (GUI), or running the program in a batch mode with a prebuilt input file.

Overview#

The EPANET Programmer’s Toolkit provides essential functions that allow users to manipulate EPANET models and retrieve critical information for hydraulic and water quality analysis. With the toolkit, users can access network data such as pipe and node properties, demand patterns, and control settings. This information can be modified or updated programmatically, enabling engineers to conduct what-if scenarios, optimize system design, and assess the impact of various operational strategies on network performance.

One of the toolkit’s key features is its ability to perform hydraulic and water quality simulations. Users can dynamically simulate water flow and pressure behavior in the network, enabling accurate prediction of system performance under different operating conditions. Moreover, the toolkit allows for the analysis of water quality parameters, such as chlorine concentration and contaminant transport, aiding in the evaluation of water safety and compliance with regulatory standards.

The EPANET Programmer’s Toolkit empowers water industry professionals to tackle complex water network challenges with greater efficiency and accuracy. By leveraging its capabilities, engineers can optimize pipe sizing, evaluate system resilience, and assess the impact of infrastructure changes on network performance. The toolkit’s ability to perform advanced simulations and analysis aids in the identification of potential issues, facilitating proactive decision-making and improving overall water network management. Furthermore, the EPANET Programmer’s Toolkit plays a crucial role in supporting research and innovation in the field of water distribution system analysis, fostering the development of new methodologies and solutions to address emerging challenges in water management.

Note

link to EPANET toolkit description here :::

Purpose#

The primary purpose of the EPANET Programmer’s Toolkit is to enhance the functionality of EPANET and enable users to access its full potential in water distribution network analysis. The Toolkit serves as an interface that allows engineers and researchers to programmatically access and manipulate EPANET models, retrieve critical information, and perform hydraulic and water quality simulations without having to access the model through the Graphical User Interface (GUI). By providing essential modeling access functions, integration capabilities, and customization options, the toolkit enables analysts to conduct in-depth analysis, optimize system design, and evaluate the performance of water networks under various operational conditions.

The EPANET Programmer’s Toolkit supports integration with various programming languages, including C, C++, and Python, making it end-user adaptable to different software development environments. This flexibility allows engineers and researchers to leverage their preferred programming languages and frameworks, facilitating seamless integration with existing tools and workflows. Additionally, the toolkit’s extensive Application Programming Interface (API) documentation and code examples provide valuable resources for developers, enabling them to extend EPANET’s functionality and customize the software to meet specific project requirements.

Installing on a Raspberry Pi#

This section is specific to my development computer - the process is:

  1. Download source files.

  2. Build a shared object library.

  3. Copy the library (or path to the library) into a working directory where you intend to run scripts.

  4. Write and run your scripts to implement EPANET from python.

Download source files#

Easiest is to create a directory, navigate to that directory, then clone the GitHub repository.

# As regular user or root user
mkdir en2toolkit
cd en2toolkit 
git clone https://github.com/OpenWaterAnalytics/EPANET.git  #clone the remote into the directory

After the repository is cloned, step 1 above is complete

Build a shared object library#

From here need to work as superuser, so either change to root or use sudoprefix to the directives. I switched to the root user because my regular user cannot issue superuser commands. Then issue the cmake .. directive to compile the objects for linking into the package. After that completes then issue the cmake --build . --config Release directive and let it run to (hopefully successful) completion.

After that completes then the library is found in the \lib directory. Simply copy it into the work directory where you want to model. A symbolic link added into the PATH environment variable is another way to proceede.

Now to test the build of the shared object modules. Import the interface module (listing below) which is stored as a file in our workspace.

epamodule.py (from OWA GitHub) This is a copy from my server - specificially modified for my Raspberry Pi - the mods are in the first few lines; i left notes!

link to OWA GitHub you may find you can get the EPyT repository to work or you - it essentially is aimed at same end goal as this course, but has some of the graphics details better worked out.

Copy the library to the working directory#

For my example herein, I copied the build into: http://ects-epanet/ects-epanet-notes/lessons/lesson03/

I also copied two EPANET input files Net1.inp and Net1g.inp

The listing below shows the directory, you can see the shared object library at the end of the listing, as well as the two input files for subsequent examples. Also note the presence of a file named epamodule.py which is used below to access the toolkit.

! ls -la

total 1592
drwxrwxr-x 10 sensei sensei   4096 Aug  4 05:38 .
drwxrwxr-x  8 sensei sensei   4096 Aug  1 01:06 ..
drwxrwxr-x  2 sensei sensei   4096 Aug  4 05:38 .ipynb_checkpoints
-rw-r--r--  1 root   root     5104 Jul 29 03:50 EX3.inp
-rw-rw-r--  1 sensei sensei  31504 Aug  4 05:05 ICTSummerSchool2023.ipynb.bak
-rw-rw-r--  1 sensei sensei   3732 Aug  4 05:05 Junk.rpt
-rw-rw-r--  1 sensei sensei   6304 Jun 12 19:45 Net1.inp
-rw-rw-r--  1 sensei sensei  46587 Jun 12 19:45 Net1.out
-rw-rw-r--  1 sensei sensei  42849 Aug  4 05:38 Net1.rpt
-rw-rw-r--  1 sensei sensei   6305 Jun 12 19:45 Net1g.inp
-rw-rw-r--  1 sensei sensei  46674 Aug  4 05:25 Net1g.rpt
drwxrwxr-x  2 sensei sensei   4096 Nov 28 06:40 __pycache__
-rw-rw-r--  1 sensei sensei 387806 Jun 12 19:45 buildtools1of2.png
-rw-rw-r--  1 sensei sensei 402767 Jun 12 19:45 buildtools2of2.png
-rw-rw-r--  1 sensei sensei    169 Aug  4 05:05 enlkyr5b
-rw-rw-r--  1 sensei sensei     69 Jul 28 14:27 ensYZnxU
-rw-rw-r--  1 sensei sensei     69 Jul 28 14:27 enxPe9Sj
-rw-rw-r--  1 sensei sensei  32610 Jul 28 14:27 epamodule.py
-rw-rw-r--  1 sensei sensei   5227 Jun  8 16:49 epanet-rules.ipynb.bak
-rw-rw-r--  1 sensei sensei   9010 Aug  4 05:38 epanet-rulesAPI.ipynb
-rw-rw-r--  1 sensei sensei  38834 Aug  4 05:21 epanet-rulesCLI.ipynb
-rw-rw-r--  1 sensei sensei  33946 Aug  4 05:21 epanet-rulesGUI.ipynb
-rw-rw-r--  1 sensei sensei    779 Jul 29 06:07 epanet-sensors.ipynb
-rw-rw-r--  1 sensei sensei  16736 Aug  4 05:21 epanet-toolkit.ipynb
drwxrwxr-x  3 sensei sensei   4096 Aug  4 05:38 ex1-cr
drwxrwxr-x  3 sensei sensei   4096 Nov 28 06:40 ex1-tk
drwxrwxr-x  3 sensei sensei   4096 Aug  4 05:25 ex2-tk
drwxrwxr-x  3 sensei sensei   4096 Aug  4 05:25 ex3-tk
drwxrwxr-x  3 sensei sensei   4096 Aug  4 05:25 ex4-tk
drwxrwxr-x  3 sensei sensei   4096 Aug  4 05:25 ex5-tk
-rw-rw-r--  1 sensei sensei  15189 Jun 12 19:45 example2.inp
-rw-rw-r--  1 sensei sensei    572 Jun 12 19:45 example2.rpt
-rwxrwxr-x  1 sensei sensei 400904 Jun 12 19:45 libepanet2.so

Write and run your scripts to implement EPANET from python.#

Below we demonstrate the last step, to write and run scripts that implement EPANET from our iPython kernel.

First import the epamodule.py package.

import epamodule as em  # import the package

---------------------------------------------------------------------------
OSError                                   Traceback (most recent call last)
/tmp/ipykernel_219845/1326067120.py in <module>
----> 1 import epamodule as em  # import the package

~/ects-epanet/ects-epanet-notes/lessons/lesson03/epamodule.py in <module>
     10 _plat= platform.system()
     11 if _plat=='Linux':
---> 12   _lib = ctypes.CDLL("./libepanet2.so") # For My Raspberry Pi
     13 ##  _lib = ctypes.CDLL("./en2tools.so.1.5.0")
     14 ##  _lib = ctypes.CDLL("./epanet2toolkit.so")

/usr/lib/python3.8/ctypes/__init__.py in __init__(self, name, mode, handle, use_errno, use_last_error, winmode)
    371 
    372         if handle is None:
--> 373             self._handle = _dlopen(self._name, mode)
    374         else:
    375             self._handle = handle

OSError: ./libepanet2.so: cannot open shared object file: No such file or directory

Then run an example

em.ENepanet("./ex1-tk/EX1tk.inp", "./ex1-tk/EX1yk-live.rpt") # runs a complete simulation. input file must exist and have contents.

! cat ./ex1-tk/EX1yk-live.rpt

  Page 1                                    Thu Aug  3 09:44:33 2023

  ******************************************************************
  *                           E P A N E T                          *
  *                   Hydraulic and Water Quality                  *
  *                   Analysis for Pipe Networks                   *
  *                         Version 2.2                            *
  ******************************************************************
  
   
      Input Data File ................... ./ex1-tk/EX1tk.inp
      Number of Junctions................ 1
      Number of Reservoirs............... 1
      Number of Tanks ................... 0
      Number of Pipes ................... 1
      Number of Pumps ................... 0
      Number of Valves .................. 0
      Headloss Formula .................. Darcy-Weisbach
      Nodal Demand Model ................ DDA
      Hydraulic Timestep ................ 1.00 hrs
      Hydraulic Accuracy ................ 0.001000
      Status Check Frequency ............ 2
      Maximum Trials Checked ............ 10
      Damping Limit Threshold ........... 0.000000
      Maximum Trials .................... 40
      Quality Analysis .................. None
      Specific Gravity .................. 1.00
      Relative Kinematic Viscosity ...... 1.00
      Relative Chemical Diffusivity ..... 1.00
      Demand Multiplier ................. 1.00
      Total Duration .................... 0.00 hrs
      Reporting Criteria:
         All Nodes
         All Links
   
  Analysis begun Thu Aug  3 09:44:33 2023

   
  Node Results:
  ----------------------------------------------
                     Demand      Head  Pressure
  Node                  cfs        ft       psi
  ----------------------------------------------
  2                  295.00     26.93     11.67
  R1                -295.00    100.00      0.00  Reservoir
   
   
  Link Results:
  ----------------------------------------------
                       Flow  Velocity  Headloss
  Link                  cfs       fps   /1000ft
  ----------------------------------------------
  frenchy            295.00     15.02      7.31
   
  Analysis ended Thu Aug  3 09:44:33 2023

Now same example but more granular control.

#Open the EPANET toolkit & hydraulics solver   
em.ENopen("Net1g.inp", "Net1g.rpt")
em.ENopenH()
em.ENsolveH()
em.ENsaveH() # need to save to a binary file before write
em.ENcloseH()
em.ENopenQ()
em.ENsolveQ()
em.ENreport() # now write report
# Close hydraulics solver & toolkit */
em.ENclose()

References#

  1. OpenWaterAnalytics(epanet-python) The GitHub source for the epamodule.py above.

  2. https://github.com/OpenWaterAnalytics/epanet/ The GitHub source for the code and build instructions for the shared object library above.

  3. EPANET (EPA website) Links to current EPA distributed EPANET programs and source files.

  4. EPANET2.2 EPA GitHub source.

  5. EPANETTOOLS1.0.0 (A pypi.org package) A package manager for EPANETTOOLS.

  6. mycopy Link to modified copy of epamodule.py

  7. Net1.inp Link to modified copy of

  8. Net1g.inp Link to modified copy of

Note

Most of these sites cross-share content, so whether using OWA or EPA official you are likely getting the same program; if its use is for some official capacity (like a water utility) use the EPA sites as your source.