Downloaded from ascelibrary.org by DEAKIN UNIVERSITY on 08/10/15. Copyright ASCE. For personal use only; all rights reserved.

The EPANET Programmer’s Toolkit for Analysis of Water Distribution Systems

Lewis A. Rossman
US Environmental Protection Agency
Cincinnati, Ohio 45268

Abstract
The EPANET Programmer’s Toolkit is a collection of functions that helps
simplify computer programming of water distribution network analyses. The
functions can be used to read in a pipe network description file, modify selected
component properties, run multiple hydraulic and water quality analyses, retrieve
selected output results, and write formatted output reports. The toolkit is especially
useful for developing applications, such as optimization models, that require running
many network analyses with modified input parameters. It can also simplify adding
analysis capabilities to integrated network modeling environments based on CAD,
GIS, and database packages.

Introduction
EPANET (Rossman, 1994) is a computer program that analyzes hydraulic and
water quality behavior in water distribution systems. It is one of the few full-featured
pipe network analysis packages for which source code is readily available. This code,
which contains both a stand-alone network solver and a graphical user interface, has
made it possible for different research and application groups around the world to
adapt the model to their own specific needs. Typical custom uses of EPANET which
have embedded the solver in other pieces of software have included linkages to GIS,
network parameter estimation programs, and several types of network optimization
models. In addition, several commercial vendors have adopted portions of the
EPANET engine in their products.
These uses of the model by third party researchers and developers were not
foreseen when the original code was first written. Thus the organization of its code
was not optimized for what might be termed “plug and play” use by others. Recently,
the entire EPANET package has been upgraded to a full 32-bit Windows application
that corrects some of the shortcomings in the original release. Advantage has been
taken of this opportunity to re-engineer the network solver into a programmer’s
toolkit. The toolkit consists of a collection of function calls residing in a dynamic link

Copyright ASCE 2004 WRPMD 1999

WRPMD'99
 library (for Windows operating systems) or in a compiled object library (for Unix
systems). The toolkit functions can be called from third-party applications written in a
number of different development environments (e.g., C/C++, Visual Basic, Delphi,
AutoCAD ADS, and ArcView Avenue). The functions allow a programmer to do the
following:
• Open an EPANET network description (i.e., input) file, read its contents, and
initialize all data structures needed for modeling a pipe network
• Access and change the value of selected network data elements
Downloaded from ascelibrary.org by DEAKIN UNIVERSITY on 08/10/15. Copyright ASCE. For personal use only; all rights reserved.

• Run a steady state or extended period hydraulic simulation

• Access results of the simulation for any specific network element
• Run repeated water quality simulations using previously saved hydraulic results
• Generate a custom report on simulation results
The toolkit functions make it possible to run multiple hydraulic simulations,
where only a subset of the network data (e.g., pipe roughness coefficients) are
changed from one run to the next, without having to read in and process an entire
network database every time. The same is true for water quality analyses. This makes
the toolkit well suited for use in optimization and automated parameter estimation
models. It frees modelers from having to worry about modifying the internals of the
EPANET engine. Instead, they can focus their attention on the use being made of the
engine.

EPANET Modeling Overview

Before discussing the programmer’s toolkit in detail it is necessary to provide
some background on how EPANET models a distribution system. Like all other
network models, EPANET abstracts an actual distribution system into a network of
links connected together at their endpoints called nodes (see Figure 1). Links can
represent pipes, pumps, or control valves (shutoff valves and check valves are
considered to be properties of pipes and are not represented as separate valves).
Nodes can be junctions, reservoirs, or tanks. Junctions are points where pipes join
together and where water either enters or leaves the network. Reservoirs represent
fixed head boundary locations, such as treatment works, groundwater aquifers, or tie-
ins to other networks or pressure zones. Tanks are storage facilities where the volume
and water level can change over time.
EPANET receives input data on the network being modeled through a text file
written using a Problem Description Language (PDL). This file can be created
externally by the model user or be developed via a front-end processor that resides in
a CAD, GIS, or stand-alone graphical user interface package. The input file describes
the properties and connectivity of the components in a pipe network. A portion of the
input file describing the network in Figure 1 is shown in Figure 2. EPANET’s PDL
uses different sections, identified by keywords in brackets, to describe the different
categories of network data necessary for modeling. A semicolon signifies the start of
a comment line, which helps make the input file self-documenting. A complete
description of the language is provided in the EPANET Users Manual (Rossman,
1994). The toolkit uses an EPANET input file as its starting point for defining a
network’s structure and component objects.

Copyright ASCE 2004 WRPMD 1999

WRPMD'99
 Based on the information contained in an input file, EPANET will compute
flows, pressures, and water quality conditions throughout the network over an
extended period of time. These results can be written to two different types of files.
One is a formatted text file that contains a network summary, status and error
messages, and output results for specific nodes and links as requested by the user in
the input file. A second, optional file can be used to record simulation results for all
nodes and links at all reporting time periods in binary format. This file can be used in
post-processors or user interface modules to display simulation results in various
Downloaded from ascelibrary.org by DEAKIN UNIVERSITY on 08/10/15. Copyright ASCE. For personal use only; all rights reserved.

formats. For extended period simulations both of these files contain results only at
fixed time intervals as specified by the user. The actual simulations can proceed at
much smaller time steps.

Toolkit Functions
The toolkit consists of a library of functions that developers can call to
perform various network modeling tasks. A description of the major functions in the
toolkit follows.

ENepanet(F1, F2, F3)

This function performs a complete EPANET simulation as would be done with a
stand-alone executable. F1 is the name of the input file, F2 the name of the report file,
and F3 the name of the binary output file. If F3 is blank, then no output binary file is
saved. This function is used only if one has no need to customize the behavior of
EPANET using the other functions in the toolkit.

ENopen(F1, F2, F3)

This function opens up the EPANET modeling system for use. It must be the first
function called when using the toolkit. Its arguments are the same as used with
ENepanet().

ENsetnodevalue(id, property, value)

ENsetlinkvalue(id, property, value)
These two functions allow one to change certain properties for specific nodes and
links, respectively. The arguments represent the ID label of the object being modified,
a code number indicating which property to modify, and the new property value.
Node properties that can be modified include elevation, baseline demand, and source
input rate (for water quality modeling). Modifiable link properties include diameter,
length, roughness coefficient, reaction coefficients (for water quality modeling), and
status (i.e., open or closed).

ENopenH()
This function initializes the hydraulic solver included in EPANET. It must be called
once prior to initiating a hydraulic analysis.

ENsolveH(saveflag)
This function runs a complete hydraulic analysis. The saveflag argument indicates
whether results for a steady state run should be saved to an internal scratch file or not

Copyright ASCE 2004 WRPMD 1999

WRPMD'99
 (results for extended period analyses are always saved to file). Once ENopenH() has
been invoked, this function can be called over and over again to analyze hydraulics
under different property settings.

ENgetnodevalue(id, parameter, value)

ENgetlinkvalue(id, parameter, value)
These functions are used to retrieve node and link parameters, respectively, from a
steady state hydraulic analysis. The arguments specify a node/link ID label, a code
Downloaded from ascelibrary.org by DEAKIN UNIVERSITY on 08/10/15. Copyright ASCE. For personal use only; all rights reserved.

number for the parameter of interest, and a variable to contain the retrieved value of
the parameter. Node parameters that can be retrieved with this function include
elevation, demand, hydraulic head, and pressure. Link parameters include diameter,
length, roughness coefficient, status, flow rate, velocity, and headloss.

ENcloseH()
This function closes down the hydraulic solver and frees all memory associated with
it. It should be called after all hydraulic processing has been finished.

ENsaveH()
This function saves the results generated from a single hydraulic analysis (steady state
or extended period) to a binary output file. Only results for a user-specified reporting
time interval are saved. This function must be called if a binary output file is to be
saved for post-processing or if the ENreport() function will be used to generate a
hydraulics output report (see below). It does not have to be called if a water quality
analysis will be made subsequently.

ENsolveQ()
This function uses the results from an extended period hydraulic simulation to run a
water quality simulation. It automatically saves both hydraulic and water quality
results at specified reporting intervals to the binary output file.

ENreport()
This function writes output results as readable text to the report file specified in the
ENopen() function. The format of the report is specified through commands supplied
in the input file.

ENclose()
This function closes down the EPANET modeling system. It frees all allocated
memory and closes all open files. It should be the last function called after all
processing has been made.
All of these functions return an integer code indicating what type of error, if
any occurred. A more complete description of these functions, including argument
types and parameter codes, is available in the EPANET Programmer’s Toolkit
Manual (Rossman, 1999). A simple example of how these functions can be pieced
together is provided by the code that comprises the ENepanet() function. In C the
function looks as follows:

Copyright ASCE 2004 WRPMD 1999

WRPMD'99
 int ENepanet(char *infile, char *rptfile, char *outfile)
{
int errcode;
errcode = ENopen(infile, rptfile, outfile);
if (!errcode) errcode = ENopenH();
if (!errcode) errcode = ENsolveH(1);
ENcloseH();
if (!errcode) errcode = ENsolveQ();
Downloaded from ascelibrary.org by DEAKIN UNIVERSITY on 08/10/15. Copyright ASCE. For personal use only; all rights reserved.

if (!errcode) errcode = ENreport();

ENclose();
return(errcode);
}

Example Application
A simple application that shows off the advantages of the toolkit is the
construction of an interactive fire flow analyzer that can be run under Microsoft Excel
or other spreadsheet programs with macro language capabilities. Network fire flow
analysis asks what is the maximum flow available at a specific node at a given
pressure (typically 20 psi [138 kPa]). One can always determine this value through
trial and error by running a succession of simulations, increasing the demand at the
node of interest until the pressure drops to the required value. Boulos et al. (1997)
presented a more systematic method for carrying out this process that usually
converges in 4 to 6 iterations. The EPANET Programmers Toolkit was used in
conjunction with Microsoft Excel and Visual Basic for Applications (VBA) to
implement this procedure. This application is purely for demonstration purposes since
a number of commercial network modeling packages already include automated fire
flow analysis capabilities much more powerful than what is presented here.
Figure 3 shows the Excel workbook developed for this application. It consists
of a worksheet where the EPANET input file is created and edited, an additional
menu item added to Excel’s Tools menu that initiates the fire flow analysis, and a Fire
Flow dialog form that implements the procedure. In the dialog form the user enters
the ID label of the junction to be analyzed and the desired pressure target. Clicking
the Fire Flow button begins the calculations and reports the result. This process can
be repeated for different junctions and pressure targets. Clicking the Close button
dismisses the dialog and returns the user to the worksheet.
The main VBA code that implements the process is contained in three
procedures:
1. The dialog form’s OnShow procedure is called when the user selects the Fire
Flow option off of Excel’s Tools menu. The procedure copies the network
description from the worksheet into a temporary input file, calls ENopen() to open
the EPANET modeling system, and calls ENopenH() to initialize the hydraulics
solver.
2. The OnClick procedure is called when the user clicks the Fire Flow button on the
dialog form. This procedure retrieves the junction ID and pressure values entered
by the user and then makes repeated calls to the following functions until the
search for the fire flow converges:

Copyright ASCE 2004 WRPMD 1999

WRPMD'99
 • ENsetnodevalue() to set a new trial value for the fire flow (the demand) at
the node of interest
• ENsolveH() to run a hydraulic simulation
• ENgetnodevalue() to retrieve the hydraulic head that results at the node of
interest
3. The dialog form’s OnClose procedure is called when the user closes the form. It
shuts down the EPANET modeling system by calling ENcloseH() and ENclose(),
in that order.
Downloaded from ascelibrary.org by DEAKIN UNIVERSITY on 08/10/15. Copyright ASCE. For personal use only; all rights reserved.

The advantages that the toolkit brings to this application are:

• the entire input data only has to be read and processed one time,
• updating of selected input data (i.e., a single nodal demand) can be done
programmatically,
• successive hydraulic simulations converge very quickly because each new
simulation is begun with the solution from the previous simulation which, because
only a single input parameter is being changed, is likely to be close to the new
solution,
• there is no need to save results to file since only a single output value from the
current hydraulic solution needs to be retrieved.
To implement this application without the toolkit would have required modifying the
internals of the original EPANET source code.
Examples of other types of applications where the toolkit could prove useful
include:
• optimization models for pipe sizing based on genetic algorithms (Dandy et al.
1996)
• neural network training to aid in optimal parameter estimation and system
operation (Swiercz, 1994; Lingireddy and Ormsbee, 1998)
• determination of water quality impact coefficients used for optimal scheduling
and location of chlorine booster stations (Boccelli et al., 1998).
What all of these applications have in common is the need to run hundreds or even
thousands of network simulations with modified input parameters and post-
processing of selected output results. The toolkit provides an efficient, pre-packaged
means for accomplishing such tasks.

Conclusions
The Programmer’s Toolkit provides the flexibility that network modelers need
to employ EPANET’s computational engine in a variety of pipe network modeling
and analysis efforts without the burden of having to modify its source code. It is
particularly useful for running large numbers of simulations efficiently. It also
simplifies the task of embedding the EPANET engine in integrated network modeling
environments that utilize CAD, GIS, and database packages. The toolkit can improve
the productivity of researchers and developers involved in water distribution system
modeling.

Copyright ASCE 2004 WRPMD 1999

WRPMD'99
 Acknowledgements
The material in the paper is based on work partially funded by the U.S.
Environmental Protection Agency. It has not been subject to the agency’s review and,
therefore, does not necessarily reflect the views of the agency, and no official
endorsement should be inferred. Mention of trade names or commercial products does
not constitute endorsement or recommendation for use.

References
Downloaded from ascelibrary.org by DEAKIN UNIVERSITY on 08/10/15. Copyright ASCE. For personal use only; all rights reserved.

Boccelli, D.L. et al. (1998). “Optimal scheduling model for booster disinfection in
water distribution networks”, Jour. Water Res. Planning & Mgmt., 124:99.

Boulos, P.F., Rossman, L.A., Orr, C-H., Heath, J.E., and Meyer, M.S. (1997). “Fire
flow computation with network models”, Jour. AWWA, 89(2):51-56.

Dandy, G.C., Simpson, A.R., and Murphy, L.J. (1996). “An improved genetic
algorithm for pipe network optimization”, Water Resour. Res., 32(2):449-458.

Lingireddy, S. and Ormsbee, L.E. (1998). “Neural networks in optimal calibration of

water distribution systems” in Artificial Neural Networks for Civil Engineers:
Advanced Features and Applications, edited by I. Flood and N. Kartam, American
Society of Civil Engineers, Reston, VA.

Rossman, L.A. (1994). EPANET Users Manual, EPA-600/R-94/057, Risk Reduction

Engineering Laboratory, U.S. Environmental Protection Agency, Cincinnati, OH.

Rossman, L.A. (1999). EPANET Programmer’s Toolkit Manual, National Risk

Management Research Laboratory, U.S. Environmental Protection Agency,
Cincinnati, OH.

Swiercz, M. (1994). “Using neural networks to simplify mathematical models of

water distribution networks: a case study”, First International Symposium on
Mathematical Models in Automation and Robotics, September 1-3, Miedzyzdroje,
Poland.

Copyright ASCE 2004 WRPMD 1999

WRPMD'99
 Downloaded from ascelibrary.org by DEAKIN UNIVERSITY on 08/10/15. Copyright ASCE. For personal use only; all rights reserved.

Copyright ASCE 2004

RESERVOIR

TANK

WRPMD'99
VALVE

Figure 1. Example Distribution System

PIPE

JUNCTION
PUMP

WRPMD 1999
 [TITLE]
Sample Pipe Network

[JUNCTIONS]
; Elev. Demand
;ID ft. gpm
;----------------------------
1 1090
101 1090
2 1122
Downloaded from ascelibrary.org by DEAKIN UNIVERSITY on 08/10/15. Copyright ASCE. For personal use only; all rights reserved.

3 1138
4 1157 500
5 1180
< etc.>

[TANKS]
; Elev. Init. Min. Max. Diam.
;ID ft. Level Level Level ft.
;-------------------------------------
17 910
18 080 10 0 20 50

[PIPES]
; From To Length Diam.
;ID Node Node ft. in. C-factor
;----------------------------------------
1 1 2 1500 12 130
2 2 3 1000 8 130
3 3 4 1200 10 120
4 4 5 2000 10 120
< etc. >

[PUMPS]
; From To Head Flow
;ID Node Node ft. gpm
;-------------------------------
171 17 101 456 2700

[VALVES]
; From To Setting
;ID Node Node Type psi
;--------------------------------
25 21 23 PRV 75

[END]

Figure 2. Excerpt of EPANET Input File

Copyright ASCE 2004 WRPMD 1999

WRPMD'99
 Downloaded from ascelibrary.org by DEAKIN UNIVERSITY on 08/10/15. Copyright ASCE. For personal use only; all rights reserved.

Copyright ASCE 2004

10

WRPMD'99
Figure 3. Interactive Fire Flow Analyzer

WRPMD 1999