See discussions, stats, and author profiles for this publication at: https://www.researchgate.

net/publication/281437935

OOPNET: An object-oriented EPANET in Python

Conference Paper  in  Procedia Engineering · September 2015

DOI: 10.1016/j.proeng.2015.08.924

CITATIONS READS

4 1,309

2 authors:

David Bernhard Steffelbauer Daniela Fuchs-Hanusch

Delft University of Technology Graz University of Technology
18 PUBLICATIONS   62 CITATIONS    59 PUBLICATIONS   318 CITATIONS   

SEE PROFILE SEE PROFILE

Some of the authors of this publication are also working on these related projects:

INFOSAN View project

DASH of Water View project

All content following this page was uploaded by David Bernhard Steffelbauer on 02 September 2015.

The user has requested enhancement of the downloaded file.

 Available online at www.sciencedirect.com

ScienceDirect
Procedia Engineering 119 (2015) 710 – 718

13th Computer Control for Water Industry Conference, CCWI 2015

OOPNET: An object-oriented EPANET in Python

D. Steffelbauera* and D. Fuchs-Hanuscha
a
Institute of Urban Water Management and Landscape Water Engineering
Graz University of Technology, Stremayrgasse 10/I, A-8010 Graz, Austria

Abstract

Several attempts of the past aimed to convert EPANET into a bigger open-source project by rewriting EPANET in an object-
oriented way. We introduce a Python based object-oriented EPANET (OOPNET) with the purpose to address water engineers
that might be not so familiar with complex programming languages like C++ or Java. EPANET input files are translated into the
object oriented structure of OOPNET and manipulated and simulated with EPANET’s command-line interface through Python.
The replacement of EPANET by a hydraulic solver in Python is still ongoing and has the purpose to provide a solution
completely written in one programing language.
© 2015The
© 2015 TheAuthors.
Authors. Published
Published by Elsevier
by Elsevier Ltd.
Ltd. This is an open access article under the CC BY-NC-ND license
Peer-review under responsibility of the Scientific Committee of CCWI 2015.
(http://creativecommons.org/licenses/by-nc-nd/4.0/).
Peer-review under responsibility of the Scientific Committee of CCWI 2015
Keywords: Water Distribution, Parallel Computing, Open Source Project, Simulaton Software, Genetic Algorithms, Optimization

1. Introduction

Since the WDSA2010 conference, the water related community is waiting for EPANET3. Different attempts
have been made in the past to convert EPANET into an open-source project maintained by a bigger community
instead of a single developer [2, 3]. To obtain this goal, the whole (or parts of the) software has to be rewritten in an
object-oriented way, enabling many geographically separated programmers to contribute.
So far the provided solutions were written in programming languages with a steep learning curve (e.g. C++, C#,
Java). In contrary, Python is an easy to learn open-source language with a wide range of additional packages for
multiple tasks. In 2013, Python was the fastest growing programming language referring to the PYPL (PopularitY of
Programming Language; http://pypl.github.io/PYPL.html) index with a nowadays share of 10.9 % worldwide and

*
Corresponding author. Tel.: +43 316 873 8881; fax: +43 316 873 8376.
E-mail address: david.steffelbauer@tugraz.at

1877-7058 © 2015 The Authors. Published by Elsevier Ltd. This is an open access article under the CC BY-NC-ND license
(http://creativecommons.org/licenses/by-nc-nd/4.0/).
Peer-review under responsibility of the Scientific Committee of CCWI 2015
doi:10.1016/j.proeng.2015.08.924
 D. Steffelbauer and D. Fuchs-Hanusch / Procedia Engineering 119 (2015) 710 – 718 711

still growing. Therefore, we chose Python as programming language to rewrite EPANET to an object-oriented
EPANET (OOPNET).
So far the object-oriented structure of OOPNET is similar to CWSNET [4], OOTEN [5] or PORTEAU [6] with
the focus on being as easy as possible to handle for end-users. EPANET input files can be translated into this
structure and are manipulated and simulated with EPANET’s command-line interface through Python. The reports
are translated in Pandas [7], a python data analysis library, to enable fast and easy to use data analysis of the results.
Parallel computation is implemented with SCOOP [8], another python library. Additionally, optimization with
genetic algorithms (GA) using the DEAP [9] library was carried out. Plotting the water distribution network as well
as the results is performed either with MatplotLib [10], a plotting package similar to MATLAB, or directly in the
user’s browser or web with Bokeh [11].
In this paper we discuss why we chose Python as programming language. We give an overview on the program
design of OOPNET describing it with respect to the objectives of the program design. So far OOPNET was tested
on different tasks, like uncertainty analysis through Monte Carlo simulations, global optimization with GA, leakage
localization, optimal sensor placement as well as pipe burst outflow simulations and worked well on all of these
tasks. In the near future, the replacement of EPANET by a hydraulic solver in Python is planned to provide a
software solution completely written in one programing language.

2. Why Python?

Python is a widely used high level programming language, with a design philosophy that emphasizes code
readability and is easy to learn compared to other programming languages with the same capabilities, like Java or
C++.
The core philosophy of Python is summarized in the PEP 20 document, called the Zen of Python [12]. Here are
the first lines of this document, to get an idea of the core philosophy:

x Beautiful is better than ugly

x Explicit is better than implicit
x Simple is better than complex
x Complex is better than complicated
x Readability counts

Fig. 1. PYPL (PopularitY of Programming Language) Index showing the growing popularity of Python worldwide. Taken from
http://pypl.github.io/PYPL.html

Because of its simple syntax and its various applications, Python is more and more used around the whole world
and the user group is still growing (see Fig. 1), potentially replacing e.g. MATLAB, in the scientific community.
712 D. Steffelbauer and D. Fuchs-Hanusch / Procedia Engineering 119 (2015) 710 – 718

Furthermore, one of the main strengths of Python is that it has a large standard library providing tools suited to
various tasks. This is described as its “batteries included” philosophy. By January 2015, the Python Package Index
contained more than 54.000 Python packages offering a wide range of functionality.

3. Program Design

The design philosophy of OOPNET consists of two main objectives, usability and collaboration.
First, the usability should be as easy as possible, enabling water engineers implementing their ideas throughout
easy readable and writeable code. Moreover, OOPNET should warn users, if they make programming mistakes.
Mistakes, which may be hard to find later on if OOPNET is getting more complex due to further development, have
to be reported in an early stage.
Second, OOPNET is designed in a way to make collaboration possible for various geographically separated
contributors. Therefore, OOPNET consists of different packages containing modules with classes, having the object
oriented design paradigm included in its foundation.

Fig. 2. OOPNET Package structure respectively workflow of the user

The overall package structure is described in Fig. 2, which is structured to represent the workflow of a potential
user. Starting point is an EPANET Input file read in by the function Read. The Read function makes use of the three
packages reader, elements and graph. Package reader contains the functions, which are necessary to translate
arbitrary EPANET Input files in an object-oriented structure, which is implemented in the elements package.
Moreover, the graph package translates the water distribution network in a Python NetworkX graph object [13],
enabling the application of advanced algorithms from graph theory. The output of the Read function is an OOPNET
network object, which can be manipulated by the user in a simple Python syntax.
 D. Steffelbauer and D. Fuchs-Hanusch / Procedia Engineering 119 (2015) 710 – 718 713

After the manipulation of the network by the user, the simulation of the network is started with the function Run.
Run consists of three Python packages as well, namely writer, simulator and report. OOPNET makes use of the
command line EPANET as no hydraulic solver has been implemented so far. Therefore, from the manipulated

Fig. 3. Code snippet of a simple example implemented in OOPNET

network object a new EPANET Input file has to be generated. This is done using the package writer. Afterwards,
command line EPANET is called with the simulator package and the results of the simulation from EPANET’s
report file are read in by the package report. This translates the report file in a Python Pandas Dataframe [7].
Pandas is a Python data analysis library enabling the user to get all information out of the report file with an easy to
use syntax, containing fast statistical data analysis algorithms. Furthermore, the network respectively the simulation
results can be plotted by the function Plot, which contains the packages pyplot and bokeh. The package pyplot
makes use of Python’s plotting library MatplotLib [10], which produces publication quality figures in an easy to use
syntax similar to the programming language MATLAB. On the other hand, bokeh uses Python’s library Bokeh [11],
an interactive visualization library that targets modern web browsers for presentation.
In Fig. 3 a code snippet of a simple example is presented, to make the use of OOPNET less abstract. Imagine a
user of OOPNET wants to change the roughness values of all pipes with a diameter greater than 500 mm to the
value 2 mm. Subsequently, the user wants to analyze the mean pressure in the system for calculating e.g. the ILI
(Infrastructure Leakage Index). Therefore, the network is loaded with the Read function in the first line. The next
line leads to an iteration over all pipes in the system with Python’s for-loop, asking for the pipes with a diameter
greater than 500 mm with the if function and setting the pipe’s roughness to the desired value of 2 mm.
Subsequently, the network is simulated with the Run function and a report is generated. The last line leads to a print
of the mean over all nodal pressures given in the generated report.
The object-oriented structure implemented in the elements package is represented in Fig. 4, which shows the
object-oriented design paradigm with inheritance of classes and properties. Inheritance is depicted as a black arrow,
e.g. the class Junction is a child of class Node, which is again the child of the class Network Component. Underlying
all classes is an abstract HasStrictTraits class from the Python package Traits [14]. Traits circumvents the drawback
of Python that all class objects and all class properties can be overwritten at runtime of the program. Furthermore,
Traits enables fixed types of properties in Python. For example, the roughness coefficient of a pipe always has to be
a floating point number and not a string. If the user accidentally defines the roughness of a pipe as a string, this will
lead to an error and the user will be led to the wrong line in the code. This prevents from the aforementioned
propagation of errors in larger, more complex programs, which would be hard to find in a later stage of
programming
714 D. Steffelbauer and D. Fuchs-Hanusch / Procedia Engineering 119 (2015) 710 – 718

Additionally, Fig. 4 shows, that if a class has another class as one of its properties, it is depicted as dotted arrow.
For example, a Link has always a start-node and an end-node. Therefore the Link class has an instance of the class
Node as one of its properties.

Fig. 4. Class structure of OOPNET implemented in the elements package

The elements package is subdivided in several Python modules, to guarantee a higher level of modularity in the
code. This increases the possibility of collaboration for more programmers, since the programmers are able to work
on different files. The files are named according to the EPANET manual Input file structure [1] (Network
Components, System Operation, Water Quality, …) and are shown in different colors in Fig. 4. This structure assists
collaborators, which are new to OOPNET but used to EPANET, to quickly get familiar with OOPNET. In addition,
the reader and writer packages are structured in a similar way.
In Fig. 5 the properties of the Junction class as an example for the property structure of all the other classes in
OOPNET is shown. Only the properties emittercoefficient, demandpattern and demand are defined in the Junction
class whereas all other properties are inherited from the Node or the Network Component class. Also the properties
sourcepattern and demandpattern are stressed out in Fig. 5, since they refer to another instance of a class, namely
Pattern, which has again properties.

Fig. 5. Properties of OOPNET’s Junction class

 D. Steffelbauer and D. Fuchs-Hanusch / Procedia Engineering 119 (2015) 710 – 718 715

On top of the elements class structure is the network object, which is again a class with properties consisting of
Python lists of the classes of elements, describing the whole network and its physical properties respectively the
simulation parameters (Fig. 6). Additionally, the graph property contains the NetworkX graph object and
networkhash is a property containing a Python dictionary linking all id’s of the elements of the network to their
memory location, allowing faster connection of the elements respectively faster searching through the network’s

Fig. 6. Properties of the Network class object containing all the information from an EPANET Input file

elements.
An example of a bokeh plot of a network and its simulation results is shown in Fig. 7. The node pressures and the
pipe flows are depicted in different colors. On top of the figure the bokeh’s menu with different tools, like panning,
zooming, refreshing or exporting, can be seen.

Fig. 7. Screenshot of a Bokeh plot in the browser of a simulation of an EPANET network

716 D. Steffelbauer and D. Fuchs-Hanusch / Procedia Engineering 119 (2015) 710 – 718

4. OOPNET for water distribution systems analyses tasks - Examples

We additionally use OOPNET in combination with other Python software to extend its capabilities. The first
applications have been various global optimization tasks by genetic algorithms. For these tasks Python’s package
DEAP [9], an abbreviation for “Distributed Evolutionary Algorithms in Python”, was used. This is a novel
evolutionary computation framework, allowing rapid prototyping and testing of diverse genetic algorithms. In
DEAP it is possible to simulate single as well as multi-objective genetic algorithms. A lot of the common genetic
algorithms are predefined in the DEAP and can easily be altered through its simple to use interface, since DEAP is
also written in an object-oriented way. This enables the user to apply genetic algorithm operators like mutation and
crossover at runtime of the program. Additionally to single- and multi-objective genetic algorithms, genetic
programming is also possible with DEAP, to be used for advanced research tasks.
Parallel computing with OOPNET is enabled with the Python package SCOOP [8] (Scalable COncurrent
Operations in Python), a distributed task module allowing concurrent parallel programming on various
environments, from personal computers with multicores and hyper threading up to supercomputers. For parallelizing
a serial program in SCOOP, only minor modifications are needed. Instead of iterating over many similar operations
in a Python function with for loops, the more “pythonic” way is to use a map function, which maps a list of input
parameters on a function to a list of output parameters. Basically, the only thing to enable parallel computation with
SCOOP is to replace Python’s map function with SCOOP’s map function in its futures package (map Î
futures.map) and the computation time will decrease on ones multi-core environment.
Moreover, global sensitivity analysis was performed for water distribution systems with OOPNET and the
Python package SALib [15] (Sensitivity Analysis Library). This package includes global sensitivity analysis
techniques like Sobol Sensitivity Analysis, Method of Morris, Fourier Amplitude Sensitivity Test, Delta Moment-
Independent Measure and Derivative-based Global Sensitivity Measure.
Additional tasks performed at the Institute with OOPNET were, for example, Monte Carlo simulations for
uncertainty analysis, leakage localization and optimal sensor placement for leakage localization [16] or pipe burst
outflow calculations [17].

5. Collaboration – Open Sourcing

Rossman and van Zyl [2] mentioned, that due to the dispersed physical locations of its participants a software
tool to manage the flow of information between the contributors to an open source software project is necessary.
This project management software has to include a Web Site as a main vehicle to communicate with the public, a
Mailing List Manager program (or at least a program equivalent to it) for the communication between the
collaborators in the project, a Version Control tool and a Bug Tracking feature. Moreover, Rossman and van Zyl [2]
introduced SourceForge as the largest and best known hosting site.
We recommend using Github (https://github.com) as project management tool for OOPNET. A Github project
consists besides Version Control using GIT, the possibility for automatically rendered README files with
Markdown-like file formats, an Issue Tracker, a Wiki and even small websites can be hosted from public
repositories. Additionally to all these features, Github provides social networking-like functions (feeds, followers,
…). Collaborators have to create a Github user account for free to contribute to OOPNET, but the repository can be
downloaded by anyone around the world.
At the moment, OOPNET is not hosted on Github, but internal at our institute, we use GIT for Version Control
and hosted a Wiki site in the internal network of our University for documentation purposes. With GIT we have
made good experiences. On the one hand, no information or change is lost, since every collaborator gets a complete
mirror of the source code. Therefore, the program can be restored through every checkout of all users collaborating
to the GIT project if server problems occur. On the other hand, it is possible with GIT to create new branches of the
source code, e.g. if parts of the program are in developing status. After the new applications are tested, the branch
can be easily merged into the main branch to make the new changes available for users, which can be also non-
developers of OOPNET.
 D. Steffelbauer and D. Fuchs-Hanusch / Procedia Engineering 119 (2015) 710 – 718 717

One additional important task of an open source project is the coding style. If all contributors to a project write
the code in the same way, it will be much easier to work together. Hence, the whole source code of OOPNET is
written in such a way, that it fulfills the PEP 8 Python language styling conventions [18].

6. Summary and Outlook

OOPNET so far was developed and applied for different modeling tasks at the Institute of Urban Water
Management of Graz University of Technology. The main modeling tasks for which we could apply OOPNET, were
optimal sensor placement of hydraulic sensors, leakage localization and pipe burst outflow simulations. The
structure of OOPNET and the use of GIT Version Control enable several users at the Institute to extend or use
OOPNET. Hosting OOPNET on Github is planned in future to reach a wider scientific and user community and to
manage the flow of information between future contributors of such an open source software project.
Currently, OOPNET still uses EPANET as hydraulic solver engine. In the near future it is planned to replace
command line EPANET in the package simulator with a solver completely written in Python. This will make
OOPNET to be one unit.
As a drawback, the fact that a Python based hydraulic solver will be slower compared to the highly efficient
procedural C code EPANET is written in, has to be mentioned. To overcome this we are planning to use the package
Cython [19], a Python to C source code translator. This will enable collaborators to OOPNET to use just one
programming language, namely Python, to contribute to all parts of OOPNET. In addition, since the code will be
compiled in C, the speed losses of the solver engine compared to the original EPANET solver can be avoided.
In the hydraulic solver sparse matrices will be necessary. There exists also an implementation of these types of
matrices in Python, the sparse package in Python’s SciPy library [20].
For code testing purposes unittests should be written to guarantee a good code coverage of the program. For that
reason, the Python package unittest in Python’s standard library can be used.
Also new features should be implemented in the software, once the hydraulic solver is written in Python, like e.g.
pressure dependent demands. And maybe, later in the development of OOPNET, the community can think about
implementing a Graphical User Interface (GUI) also written in Python as various Python packages exist for this task,
like e.g. PyQT.

7. References

[1] L. A. Rossman. EPANET 2: Users Manual. U.S. Environmental Protection Agency, Cincinnati, 2000.
[2] L. Rossman and J. Van Zyl. The Open Sourcing of EPANET. Water Distribution Systems Analysis 2010, American Society of Civil
Engineers, pp. 19–28.
[3] J. Van Zyl and Y. Chang. Programming Styles for an Open Source EPANET Project. Water Distribution Systems Analysis 2010, American
Society of Civil Engineers, pp. 29–36.
[4] M. Guidolin, P. Burovskiy, Z. Kapelan, and D. Savić. CWSNET: An Object-Oriented Toolkit for Water Distribution System Simulations.
Water Distribution Systems Analysis 2010, American Society of Civil Engineers, pp. 1–13.
[5] J. E. Van Zyl, J. Borthwick, and A. Hardy. Ooten: An object-oriented programmers toolkit for epanet. Adv. Water Supply Manag. CCWI
2003, 2003.
[6] O. Piller, D. Gilbert, K. Haddane, and S. Sabatie. Porteau: An Object-Oriented programming hydraulic toolkit for water distribution system
analysis. 11th International Conference on Computing and Control for the Water Industry (CCWI 2011), 2011, vol. 1, pp. 27-32.
[7] W. McKinney. Python for Data Analysis: Data Wrangling with Pandas, NumPy, and IPython. O’Reilly Media, Inc., 2012.
[8] Y. Hold-Geoffroy, O. Gagnon, and M. Parizeau. Once You SCOOP, No Need to Fork. Proceedings of the 2014 Annual Conference on
Extreme Science and Engineering Discovery Environment, New York, NY, USA, 2014, pp. 60:1–60:8.
[9] F.-A. Fortin, D. Rainville, M.-A. G. Gardner, M. Parizeau, C. Gagné. DEAP: Evolutionary algorithms made easy. J. Mach. Learn. Res., vol.
13, no. 1, pp. 2171–2175, 2012.
[10] J. D. Hunter. Matplotlib: A 2D Graphics Environment. Comput. Sci. Eng., vol. 9, no. 3, pp. 90–95, May 2007.
[11] Bokeh 0.9.0 documentation.[Online]. Available: http://bokeh.pydata.org/en/latest/index.html. [Accessed: 21-May-2015].
[12] T. Peters. PEP 20 - The Zen of Python. Python.org, 19-Aug-2004. [Online]. Available: https://www.python.org/dev/peps/pep-0020/.
[Accessed: 21-May-2015].
[13] A. Hagberg, D. Schult, and P. Swart. Exploring Network Structure, Dynamics, and Function using NetworkX. Proceedings of the 7th Python
in Science Conference (SciPy2008), Pasadena, CA USA, 2008, pp. 11–15.
[14] Traits . [Online]. Available: http://code.enthought.com/projects/traits/. [Accessed: 29-Oct-2014].
718 D. Steffelbauer and D. Fuchs-Hanusch / Procedia Engineering 119 (2015) 710 – 718

[15] J. Herman. Sensitivity Analysis Library (SALib). GitHub. [Online]. Available: https://github.com/jdherman/SALib. [Accessed: 21-May-
2015].
[16] D. Steffelbauer, M. Neumayer, M. Günther, and D. Fuchs-Hanusch. Sensor Placement and Leakage Localization Considering Demand
Uncertainties. Procedia Eng., vol. 89, pp. 1160–1167, 2014.
[17] D. Fuchs-Hanusch, D. Steffelbauer, M. Günther, and D. Muschalla. Systematic material and crack type specific pipe burst outflow
simulations by means of EPANET2. Urban Water J., Latest Articles, DOI: 10.1080/1573062X.2014.994006.
[18] G. van Rossum, B. Warsaw, and N. Coghlan. PEP 8 - Style Guide for Python Code. Python.org, 05-Jul-2001. [Online]. Available:
https://www.python.org/dev/peps/pep-0008/. [Accessed: 21-May-2015].
[19] S. Behnel, R. Bradshaw, C. Citro, L. Dalcin, D. S. Seljebotn, and K. Smith. Cython: The Best of Both Worlds. Computing in Science and
Engineering, vol. 13, no. 2, pp. 31–39, 2011.
[20] E. Jones, T. Oliphant, and P. Peterson. Scipy: Open source scientific tools for Python. [Online]. Available:
http://scipy.jp/scipylib/citing.html. [Accessed: 22-May-2015].

View publication stats