EPANET-MSX 2.0 User Manual
United States
Environmental Protection
Agency
EPA/600/R-22/199 | July 2023 | www.epa.gov/research
Office of Research and Development
Center for Environmental Solutions and Emergency Response

-------
4%	United States
Ai n>i Environmental Protection
^1 Mm Agency
EPA/600/R-22/199
EPANET-MSX 2.0 User Manual
Feng Shang
Lewis A. Rossman
James G. Uber
Water Infrastructure Division
Center for Environmental Solutions and Emergency Response
U.S. Environmental Protection Agency
Cincinnati, Ohio 45268
\7 :
PANET

-------
CONTENTS
DISCLAIMER	i
1	INTRODU CTTION	1
2	CONCEPTUAL FRAMEWORK	3
2.1	Material Transport		4
2.2	Chemical Reactions		4
2.3	Full Network Solution		5
2.4	Reaction System Solution		7
2.5	Pipe Surface Discretization		7
2.6	Dispersion Modeling		8
2.7	Model Implementation		9
3	PROGRAM USAGE	10
3.1	Example Command Line Run		11
3.2	Example Toolkit Usage		20
3.3	Using Compiled Reaction Models 		23
4	INPUT FILE FORMAT	24
4.1	[TITLE] 		26
4.2	[OPTIONS]		26
4.3	[SPECIES]		27
4.4	[COEFFICIENTS]		28
4.5	[TERMS]		29
4.6	[PIPES]		30
4.7	[TANKS]		31
4.8	[SOURCES] 		31
4.9	[QUALITY] 		32
4.10	[PARAMETERS] 		33
4.11	[PATTERNS]		34
4.12	[DIFFUSIVITY]		34
4.13	[REPORT]		35
5	EXAMPLE REACTION SYSTEMS	37
5.1	Multi-Source Chlorine Decay		37
5.2	Decay and Dispersion Modeling of Chlorine		39
5.3	Oxidation, Mass Transfer, and Adsorption		41
5.4	Bacterial Regrowth with Chlorine Inhibition		44
5.5	Chloramine Decomposition		47

-------
A MSX TOOLKIT FUNCTIONS	52
A.l MSXopen		53
A.2 MSXclose		54
A.3 MSXsolveH		55
A.4 MSXusehydfile		56
A. 5 MSXsolveQ		57
A.6 MSXinit		58
A.7 MSXstep 		58
A.8 MSXsaveoutfile		59
A. 9 MSXsavemsxfile		60
A. 10 MSXreport		61
A. 11 MSXgetindex		61
A. 12 MSXgetlDlen		62
A. 13 MSXgetID		63
A. 14 MSXgetcount		64
A. 15 MSXgetspecies		65
A. 16 MSXgetinitqual		66
A. 17 MSXgetqual		67
A. 18 MSXgetconstant		68
A. 19 MSXgetparameter		69
A.20 MSXgetsource 		70
A.21 MSXgetpatternlen		71
A.22 MSXgetpatternvalue 		72
A.23 MSXgeterror		73
A.24 MSXsetconstant		74
A.25 MSXsetparameter		74
A.26 MSXsetinitqual		75
A.27 MSXsetsource		76
A.28 MSXsetpattern 		77
A.29 MSXsetpatternvalue		78
A. 30 MSXaddpattern		79
B BINARY OUTPUT FILE FORMAT	80
C MSX ERROR CODES	81
BIBLIOGRAPHY	83

-------
LIST OF FIGURES
2.1	Example of reactions in the mobile bulk phase and at the fixed pipe surface phase		3
2.2	Node-link representation of a simple distribution system		4
2.3	Illustration of the 5-step water quality transport method for pipe networks. The upper pipe segments contain flow-
ing water while the lower segments are the pipe wall surface. The numbers in each segment represent hypothetical
bulk and surface species concentrations, respectively.		6
3.1	Schematic of the example pipe network 		12
3.2	Command line execution of EPANET-MSX		16
5.1	Example of a two-source water distribution system showing the average percent of water originating from the
River source		37
5.2	Schematic of the mass transfer limited arsenic oxidation/adsorption system		41
5.3	Conceptual diagram of bacterial regrowth within a pipeline. Dashed arrows represent reactions with chlorine
while solid arrows represent transformation processes		44
iii

-------
LIST OF TABLES
3.1	Files distributed with EPANET-MSX		10
3.2	Nodal properties of the example pipe network		12
3.3	Pipe properties of the example pipe network		12
4.1	EPANET-MSX input file section keywords		24
5.1	Monochloramine decay model based on Vikesland et al. (2001) and Duirk et al. (2005)		48
A. 1	EPANET-MSX toolkit processing functions		52
A.2	EPANET-MSX toolkit data retrieval functions		53
A.3	EPANET-MSX data modification functions		53
B.l	Format of the EPANET-MSX binary output file		80
C.l	EPANET-MSX Error Codes 		81
iv

-------
LIST OF LISTINGS
3.1	Contents of the examplel.inp input file		12
3.2	Contents of the examplel.msx input file		13
3.3	EPANET-MSX results for the example network		16
3.4	C source code for the command line version of EPANET-MSX		20
4.1	EPANET-MSX input file template		24
5.1	EPANET-MSX input file for modeling two-source chlorine decay		38
5.2	EPANET-MSX input file for modeling chlorine decay and dispersion (example2.msx)		40
5.3	MSX input file for the mass transfer limited arsenic oxidation/adsorption system		43
5.4	MSX input file for a bacterial regrowth model with chlorine inhibition		45
5.5	EPANET-MSX input file of the monochloramine decomposition model		48
v

-------
DISCLAIMER STATEMENT
This User's Manual is an updated version of the EPANET MSX User's Manual (EPA/600/S-07/021) written by the same authors.
The information in this document has been funded wholly or in part by the U.S. Environmental Protection Agency (EPA). It
has been subjected to the Agency's peer and administrative review, and has been approved for publication as an EPA document.
Approval does not signify that the contents reflect the views of the Agency, nor does mention of trade names or commercial
products constitute endorsement or recommendation for use.
The computer programs described in this manual are free software that can be redistributed and/or modified under the terms of
the MIT License.
These programs are distributed in the hope that they will be useful, but without any warranty; without even the implied warranty of
merchantability or fitness for a particular purpose. The authors and the U.S. Environmental Protection Agency are not responsible
and assume no liability whatsoever for any results or any use made of the results obtained from these programs, nor for any
damages or litigation that result from the use of these programs for any purpose.

-------
CHAPTER
ONE
INTRODU CTTION
EPANET [Rossman, 2000, Rossman et al., 2020] is a widely used program for modeling the hydraulic and water quality behavior
of drinking water distribution systems. Its water quality component is limited to tracking the transport and fate of just a single
chemical species, such as fluoride used in a tracer study or free chlorine used in a disinfectant decay study. In addition, the
longitudinal dispersion process, which can play an important role in affecting the water qualities at the dead ends of a water
distribution system, is not modeled in EPANET. This manual describes an extension to the original EPANET that allows it to model
the advection, dispersion and reaction of any system of multiple, interacting chemical and biological species. This capability has
been incorporated into both a stand-alone executable program as well as a toolkit library of functions that programmers can use
to build custom applications. This set of software tools is referred to as EPANET-MSX, where MSX stands for Multi-Species
Extension.
Many water quality problems in distribution systems can only be analyzed by using a multi-species approach. Consider the
following descriptive examples:
•	Free chlorine disinfectant is lost in bulk solution due mainly to oxidation-reduction reactions involving HOC1 and OC1", and
natural organic matter (NOM). The NOM itself is a heterogeneous mixture of organic compounds (e.g., humic and fulvic
acids) of varying chemical characteristics. Current single-species models, however, must model free chlorine loss under the
assumption that all other reactants are in excess and thus their concentrations can be considered constant. This limitation
is responsible for the widespread observation that the water-specific decay rate constant of the common first-order model
is not a constant at all, but rather varies significantly with chlorine dose (a clear indication of model structure error). The
formation of regulated chlorination by-products, which result from free chlorine and NOM interactions, presents yet another
set of reaction mechanisms involving multiple interacting species.
•	Mono-, di-, and tri-chloramine result from interactions between free chlorine species and ammonia, and are increasingly
used as residual disinfectants. These chloramines also interact with NOM, though the reactions are slower than those for
free chlorine. Thus chloramine decay in distribution systems involves multiple interacting chemical species, which a single-
species model is forced to simplify as a quasi-first order reaction. Further, ammonia may be produced by auto-decomposition
of chloramines, which is of significant practical importance for understanding nitrification episodes in distribution systems
and storage tanks. Nitrification models may need to consider attached-growth nitrifying biofilms, suspended nitrifying
biomass, and the electron donor (ammonia), electron acceptor (oxygen), and carbon source that supports microbial growth.
•	For the relatively common situation where more than one water source supplies a distribution system, current models are not
able to represent meaningful differences in source water quality, as they relate to water quality evolution in the distribution
system. Modelers must try to compensate for this limitation by assigning bulk decay rate coefficients to specific pipes,
according to which source supplies them. Such an approach has obvious deficiencies when attempting to model distribution
system zones where sources blend together, and these zones are sometimes the focus of water quality issues.
None of these examples can be accurately modeled by using the single-species capabilities of the current EPANET program. This
shortcoming provides the motivation to extend EPANET so that it can model reaction systems of any level of complexity.
Another feature in EPANET-MSX 2.0 is the option to include the dispersion process in the water quality modeling analysis of
a water distribution system. Both EPANET and the original EPANET MSX model the transport of a single species by solving
the one-dimensional advection-reaction equation; while EPAENT-MSX 2.0 solves a set of one-dimensional advection-dispersion-
reaction equations to analyze water quality transport of mutiple interacting species.
1

-------
EPANETMSX USERS MANUAL, Release 2.0
The changes and updates that have been made in version 2.0 of EPANET-MSX include:
•	Improved water quality mass balance and mass balance reporting as in EPANET 2.2.
•	Dispersion modeling as an option to be included in water quality simulation.
•	OPENMP parallelization for both reaction and dispersion simulation codes.
•	A batch file (runvc.bat) is provided to automatically launch the Visual Studio C/C++ compiler and compile the reaction
equations.
The following sections of this manual describe the conceptual framework used by EPANET-MSX to model multiple reacting
species within a distribution system, provide instructions on how to use both the command line and toolkit versions of EPANET-
MSX, give a complete description of the format of an MSX input file, and describe several example applications in detail. The
appendices describe each function in the EPANET-MSX toolkit, the format of its binary output file, and the meaning of its error
codes.
2

-------
CHAPTER
TWO
CONCEPTUAL FRAMEWORK
From a water quality modeling perspective, two significant physical phases exist within a water distribution system: a mobile bulk
water phase and a fixed pipe surface phase. Bulk phase species are chemical or biological components that exist within the bulk
water phase and are transported through the system with the average water velocity. Surface phase species are components that
are attached or incorporated into the pipe wall and are thus rendered immobile. Fig. 2.1 shows an example of bulk phase chlorine
(HOC1) reacting with bulk phase NOM (natural organic matter) to produce a bulk phase disinfectant by-product (DBP), while also
oxidizing ferrous iron to ferric iron in the fixed surface phase at the pipe wall.
Fig. 2.1: Example of reactions in the mobile bulk phase and at the fixed pipe surface phase.
Examples of bulk species include dissolved constituents (individual compounds or ions, such as HOC1 and OC1", as well as aggre-
gate components such as TOC), suspended constituents (such as bacterial cells and inorganic particulates), and chemicals adsorbed
onto particles. Examples of surface species include bacteria incorporated within biofilm, oxidized forms of iron contained within
corrosion scale, particulate material that settles out due to gravity or is attached to the pipe wall surface through ionic or molecular
(i.e., van der Waal) forces, and organic compounds that can diffuse into or out of plastic pipes or be adsorbed onto or desorbed
from iron oxide pipe surfaces. Some components, such as bacteria and particulates, can exist in both the bulk and surface phases
and transfer from one phase to another by such mechanisms as physical attachment/detachment, chemical adsorption or molecular
diffusion. In such situations, the component is modeled as two species: one bulk and the other surface.
Additional phases that might exist within a distribution system, such as a mobile bed sediment phase, an immobile water phase
within the pore structure of pipe scale, or an air phase overlying the water surface in a storage tank, could also be included within
this modeling framework.
3

-------
EPANETMSX USERS MANUAL, Release 2.0
2.1 Material Transport
A water distribution system consists of pipes, pumps, valves, fittings, and storage facilities that convey water from source points
to consumers. This physical system is modeled as a network of links connected together at nodes in some particular branched or
looped arrangement. Fig. 2.2 provides an example of a network representation of a very simple distribution system. Links represent
pipes, pumps, and valves; nodes serve as source points, consumption points and storage facilities. The following phenomena all
influence the quality of water contained in the system and can be modeled using principles of conservation of mass coupled with
reaction kinetics:
Reservoir
Junction
Valve
Fig. 2.2: Node-link representation of a simple distribution system.
a.	Advective transport in pipes: bulk species are transported down the length of a pipe with the same average velocity as the
carrier fluid while at the same time reacting with other bulk species and with the pipe wall surface.
b.	Dispersive transport in pipes: due to the differences of concentration and the distribution of the radial flow velocity, bulk
species spread from highly concentrated to less concentrated areas.
c.	Mixing at pipe junctions: at junctions receiving inflow from two or more links the flows are assumed to undergo complete
and instantaneous mixing.
d.	Mixing in storage nodes: all inflows to storage nodes mix completely with the existing contents in storage while these
contents are subjected to possible bulk phase reactions (alternative schemes are available for modeling plug flow storage
tanks).
2.2 Chemical Reactions
Reactions can be divided into two classes based on reaction rates. Some reactions are reversible and fast enough in comparison
with the system's other processes so that a local equilibrium can be assumed; others are not sufficiently fast and/or irreversible
and it is inappropriate to use an equilibrium formulation to represent them. Theoretically, very large backward and forward rate
constants (with their ratio equaling the equilibrium constant) can be used to model fast/equilibrium reactions and therefore both
fast/equilibrium and slow/kinetic reaction dynamics can be written as a single set of ordinary differential equations (ODEs) that
can be integrated over time to simulate changes in species concentrations. This approach can result in reaction rates that may range
over several orders of magnitude and lead to such small integration time steps so as to make a numerical solution impractical.
In EPANET-MSX, algebraic equations are used to represent the fast/equilibrium reactions and mass conservation. Thus it is
assumed that all reaction dynamics can be described by a set of differential-algebraic equations (DAEs) in semi-explicit form.
2.1. Material Transport
4

-------
EPANETMSX USERS MANUAL, Release 2.0
The system of DAEs that defines the interactions between bulk species, surface species, and parameter values can be written in
general terms as:
^ = f(xb, xs, zb, za,p)	(2.1)
- =g(xb,xs, zb, za,p)	(2.2)
dt
0 = h(x5, xs, zb, zs, p)	(2.3)
where the vectors of time-varying differential variables xb and xs are associated with the bulk water and pipe surface, respectively,
the time-varying algebraic variables zb and zs are similarly associated, and the model parameters p are time invariant. The
algebraic variables are assumed to reach equilibrium in the system within a much smaller time scale compared to the numerical
time step used to integrate the ODEs. The dimension of the algebraic equations h must agree with that of the algebraic variables
z = [zb zs], so that the total number of equations in (2.1)-(2.3) equals the total number of time-varying species ([ajj, xs zb zs]).
As a simple example of a reaction/equilibrium system modeled as a set of DAEs, consider the oxidation of arsenite (As+3)
to arsenate (As+5) by a monochloramine disinfectant residual in the bulk flow and the subsequent adsorption of arsenate onto
exposed iron on the pipe wall. (Arsenite adsorption is not significant at the pH's typically found in drinking water.) A more
complete explanation and extension of this model is presented in EXAMPLE REACTION SYSTEMS (Section 5) of this manual.
This system consists of four species (arsenite, arsenate, and monochloramine in the bulk flow, and sorbed arsenate on the pipe
surface). It can be modeled with three differential rate equations and one equilibrium equation:
A A o+3
__ = -kaAs+3(NH2Cl)	(2.4)
fl A e + 5
kaAs+3(NH2Cl) -AvMSmax -Asf)As+5 - k2Asf5}	(2.5)
-kb{NH2Cl)	(2.6)
dt
d(NH2Cl)
dt
= 77^	<17'
where As+3 is the bulk phase concentration of arsenite, As+Z is the bulk phase concentration of arsenate, As+5 is surface phase
concentration of arsenate, and NH2Cl is the bulk phase concentration of monochloramine. The parameters in these equations
are as follows: ka is a rate coefficient for arsenite oxidation, kb is a monochloramine decay rate coefficient, Av is the pipe surface
area per liter pipe volume, and k2 are arsenate adsorption and desorption rate coefficients, Smax is the maximum pipe surface
concentration of arsenate, and ks = k\jk2. Thus in terms of the notation used in (2.1 )-(2.3), xb = {As+3, As+5, NH2Cl},
xs = {0}, zb = {0}, zs = {As+5}, p = {ka,kb,Av,ki,k2,Smax}. Example input files for this form of the model are
included with the standard EPANET-MSX distribution, while the input file for a more complex version of the model is presented
in EXAMPLE REACTION SYSTEMS (Section 5).
2.3 Full Network Solution
Dynamic models of water quality within water distribution systems can be classified spatially as either Eulerian or Lagrangian.
Eulerian models divide the network into a series of fixed control elements and record the changes at the boundaries and within
these elements, while Lagrangian models track changes of discrete parcels of water as they travel through the network. EPANET-
MSX utilizes the Lagrangian transport algorithm as used by EPANET. It tracks the movement and reaction of chemicals in discrete
water volumes, or segments. These segments are transported through network pipes by the bulk velocity, and completely mix at
junction nodes. This method is relatively efficient because the number and size of the segments in a pipe can change as hydraulic
conditions change. In addition, EPANET-MSX adds the effect of longitudinal dispersion to EPANET's Lagrangian transport
algorithm.The details of the Lagranigain algorithm to model advection, dispersion and reaction are described in [Shang et al.,
2021],
In summary form, the following steps, depicted visually in Fig. 2.3, are performed for each water quality time step:
2.3. Full Network Solution
5

-------
EPANETMSX USERS MANUAL, Release 2.0
1.	React: Apply reaction dynamics within each pipe segment and storage tank over the time step to compute new concentrations
throughout the network.
2.	Advect: Within each pipe, compute the flow volume transported over the time step and transfer this amount of volume and its
associated bulk species mass from the pipe's leading segments into accumulated mass and volume totals at the downstream
node.
3.	Mix: Compute new bulk species concentrations at each node based on its accumulated mass and volume inputs from the
advection step as well as any external sources.
4.	Release: Create a new segment at the upstream end of each pipe whose size equals the pipe's flow volume and whose bulk
species concentrations equal that of the upstream node (or if the difference in quality between the most upstream segment
and the upstream node is below some tolerance, simply increase the size of the current upstream segment).
5.	Disperse: Solve the disperison process equation and update both nodal and segment concentrations.
At Start of Time Step
V
10
6 6
W 20
16

After Reaction
V
7
• (¦
W 30
20

After Advection and Node Mixing

6
7
4 (
r -
4

30

20

18

-W 12
After Release and Surface Re-segmentation
"V
6
7
• r
W 30
25
19
18 ^
After Dispersion
11
y
7
7
' (
5
1
v.	^
§ 30
25
19

Fig. 2.3: Illustration of the 5-step water quality transport method for pipe networks. The upper pipe segments contain flowing
water while the lower segments are the pipe wall surface. The numbers in each segment represent hypothetical bulk and surface
species concentrations, respectively.
2.3. Full Network Solution
6

-------
EPANETMSX USERS MANUAL, Release 2.0
2.4 Reaction System Solution
The multi-species water quality algorithm modifies the React step (step 1) of the solution scheme described above. Within each
pipe segment, reaction dynamics are represented by the system of DAEs (2.1)-(2.3). The same applies for storage tanks, except
that the DAEs are modified to consider only bulk reactions. Although not indicated, the model parameters p can possibly vary by
pipe. For the equilibrium reactions, it is assumed that the Jacobian matrix of h with respect to z, f^, is unique and nonsingular
for all t. In this case, the implicit functions defined by (2.3),
zb = zb(xb,xs,p)	(2.8)
zs = zs(xb,xs,p)	(2.9)
exist, are continuous and unique, and possess continuous partial derivatives. These properties, and in particular the resultant
ability to evaluate (2.8)-(2.9) (numerically), are central to the numerical algorithms used for solution of (2.1)-(2.3).
Given the implicit functions (2.8)-(2.9), the solution of (2.1)-(2.3) is performed by substituting (2.8)-(2.9) into (2.1)-(2.2), thus
eliminating the algebraic equations (2.3) and leaving a reduced system of ordinary differential equations (ODEs) that can be
integrated numerically:
= f(xb, xs, zb(xb, xs,p), zs(xb, xs,p),p) = f(xb, xs,p)	(2.10)
= g(xb,xs,zb(xb,xs,p),zs(xb,xs,p),p) = g'(xb,xs,p)	(2.11)
at
Note that the above "substitution" is not performed literally, since (2.8)-(2.9) are implicit, and thus so are the reduced trajectories
f and g'. Solving (2.10)-(2.11) numerically with an explicit method, such as any of the Runge-Kutta schemes, will require that
f and g' be evaluated at intermediate values of xb and xs over the integration time step. Each such evaluation will in turn require
a solution of the nested set of algebraic equations (2.8)-(2.9). Alternative strategies for accomplishing these steps are discussed
in the Model Implementation (Section 2.7) below.
In addition to the React step, evaluation of the equilibrium equations also needs to be performed at the Mix phase of the overall
algorithm since the blending together of multiple flow streams can result in a new equilibrium condition. This process needs to
be performed at each network node, including storage tanks.
2.5 Pipe Surface Discretization
The segment bulk water state variables xb and zb have moving coordinates, due to the nature of the Lagrangian water quality
model (they move with the bulk water velocity). In contrast the associated pipe surface variables xs and zs have fixed coordinates,
since they are associated with the non-moving pipe. The lack of a common fixed coordinate system for the bulk and surface state
variables must be reconciled, since these variables interact through the common pipe-water interface (through equations (2.1)-
(2.3)). To resolve this issue a simple mass-conserving scheme is applied at every water quality time step to update the pipe surface
elements to remain consistent with the (advected) water quality segments and re-distribute the surface variable mass among the
updated elements.
As shown in Fig. 2.3, within any single water quality time step, a moving mesh divides each pipe surface into discrete-length
elements, such that each shares a common surface/water interface with the water quality segment above it. At the end of the time
step the pipe elements will, however, be inconsistent with the water quality segments, due to advection of the latter (i.e., through
the Advect step of the overall algorithm). This inconsistency is removed by updating the surface species concentrations using an
interfacial area-weighted average:
*%W=(jL;)f2(LrwnLj)xaj for i = l,...n™	(2.12)
V % J j=1
= (^) nL^ for * = 1 >-nnew	m)
2.4. Reaction System Solution
1

-------
EPANETMSX USERS MANUAL, Release 2.0
where i is the water quality segment index, n is the number of water quality segments in the pipe during the most recent React step,
Lj is the length of segment j, with corresponding vectors of surface species xsj and zsj, nnew is the updated number of water
quality segments in the pipe after advection, L"ew is the length of each updated segment, with corresponding updated surface
concentrations x"[w and znsfw. The quantity (L"ew n Lj) is the length of the overlapping intersection between segment j and
updated segment i.
2.6 Dispersion Modeling
One-dimensional mass transport in a pipe with a uniform cross-sectional area can be described as advection-dispersion-reaction
equations. For a specific species,
f)c- 3c-	cP* c-
^u — = Di— +r(c)	(2.14)
dt + dx 1 dx2 + [ '
where i = species index; q = concentration of the species i; u = flow velocity; x = distance alone the pipe's longitudinal direction;
Di = effective dispersion coefficient of the species i; r-j = reaction rate of the species i; and c = the concentration vector of all
species which includes both differential and algebraic variables as defined in Chemical Reactions (Section 2.2).
The impact of dispersion may be negligible for many parts of water distribution systems under highly turbulent conditions. How-
ever, it is important to consider dispersion when modeling dead-end segments of a system or premise plumbing systems where
the flow Reynolds number can be low. The relative importance of the dispersion can be quantified with the Peclet number:
PeH = ^	(2.15)
where I = pipe length. The Peclet number is a dimensionless measure of the relative importance of advection versus dispersion,
where a large number indicates an advection-dominated flow condition in which the dispersion is negligible.
The effective longitudinal dispersion coefficient accounts for the combined effect of molecular diffusion and shear dispersion due
to the nonuniformity of the velocity profile. For laminar flow conditions (Reynolds number less than 2300), the effective dispersion
coefficient is calcuated as an averaged value over the residence time [Lee, 2004]:
D
a?v?
48 Dm
1 -
1 - exp (-16^p^)
16
Dmtr
(2.16)
where Dm = molecular diffusion coefficient; a = pipe radius; and tr = pipe residence time (^).
For turbulent and transitional flow conditions, the effective dispersion coefficient does not depend on the molecular diffusion
coefficient and the formula used is [Basha and Malaeb, 2007]:
D = au-,_
10.1 + 577
V 1000 I
-2.21
(2.17)
where w* = shear velocity; and Re = the Reynolds number.
2.6. Dispersion Modeling
8

-------
EPANETMSX USERS MANUAL, Release 2.0
2.7 Model Implementation
EPANET-MSX offers several choices of numerical integration methods for solving the reaction system's ODEs, equations (2.1)
and (2.2). These include a forward Euler method (as used in EPANET), a fifth order Runge-Kutta method with automatic time
step control [Hairer et al., 1993], and a second order Rosenbrock method with automatic time step control [Verwer et al., 1992],
These are listed in order of the numerical work per time step required to obtain a solution. The Euler method is best applied to
non-stiff, linear reaction systems, the Runge-Kutta method to non-stiff, nonlinear systems, and the Rosenbrock method to stiff
systems (see, e.g., Golub and Ortega [1992]).
The algebraic equilibrium equations (2.3) are solved using a standard implementation of the Newton method [Press et al., 1992],
This algorithm requires that the Jacobian of h with respect to the algebraic variables zb and zs be used to iteratively solve an
approximating linear system of equations until convergence is achieved. This can be a computationally expensive procedure since
the Jacobian must be evaluated numerically and the system (2.3) is being solved within every pipe segment of every pipe at every
time step, possibly several times over, as the ODEs are integrated. To help reduce this burden EPANET-MSX offers the following
options for evaluating the nonlinear equilibrium equation system:
•	The Non-Coupled option only evaluates the equilibrium equations at the end of the time step after a new ODE solution
has been found; the algebraic variables maintain the values they had at the start of the time step while the ODEs are being
numerically integrated.
•	The Fully-Coupled option solves the algebraic equations at each stage of the ODE solution process using a fresh Jacobian
for each Newton step.
The choice of coupling involves a trade-off between computational effort and level of accuracy, the degree of which will likely be
very system dependent.
A mass balance report is provided for all species that are represented by the differential variables, xb and xs. For each species
the report lists the ratio of the total mass entering the system to the total mass leaving the system (including mass lost to reaction).
Dispersion modeling of particular species can be excluded from the network solution procedure by not assigning them a molecular
diffusivity. It can also be excluded for pipes that experience highly turbulent flow resulting in a Peclet number ((2.15)) above a
user-specified limit.
2.7. Model Implementation
9

-------
CHAPTER
THREE
PROGRAM USAGE
EPANET-MSX is a 64-bit application that runs under Microsoft Windows 7 or higher. It is distributed in a compressed archive file
named EPANETMSX.ZIP. The contents of this archive are listed in Table 3.1. The top level archive folder contains a Readme.txt
file that describes the contents of the archive and procedures for reporting bugs.
Table 3.1: Files distributed with EPANET-MSX
Readme.txt
describes the contents of the archive
\bin

runepanetmsx.exe
command line version of EPANET-MSX
epanetmsx.dll
EPANET-MSX function library
epanet2.dll
standard EPANET function library
vcompl40.dll
Visual Studio C/C++ OpenMP Runtime library
runvc.bat
batch file to launch the Visual Studio C/C++ compiler and comiple the reaction equations

(see the section Using Compiled Reaction Models)
\Examples

example l.inp
EPANET input file for example 1
example l.msx
MSX input file for example 1
example l.rpt
report file containing the MSX results for example 1
example2.inp
EPANET input file for example 2
example2.msx
MSX input file for example 2
example2.rpt
report file containing the MSX results for example 2
\Doc

epanetmsx.pdf
EPANET-MSX users manual
license.txt
licensing agreement for using EPANET-MSX
continues on next page
10

-------
EPANETMSX USERS MANUAL, Release 2.0
Table 3.1 - continued from previous page
\Include

epanetmsx.h
C/C++ header file for EPANET-MSX toolkit
epanetmsx.bas
Visual Basic declarations of EPANET-MSX functions
epanetmsx.pas
Delphi-Pascal declarations of EPANET-MSX functions
epanet2.h
C/C++ header file for EPANET2.2 toolkit
epanet2_enums.h
C/C++ header file for the symbolic constants used by EPANET2.2 Toolkit
epanet2.bas
Visual Basic declarations of EPANET2 functions
epanet2.pas
Delphi-Pascal declarations of EPANET2 functions
epanetmsx.lib
Microsoft C/C++ LIB file for epanetmsx.dll
epanet2.1ib
Microsoft C/C++ LIB file for epanet2.dll
\Src
EPANET-MSX source files
Most end users will only need to extract the files in the \bin, Vxamples, and \doc folders to a directory of their choosing. Developers
will also need the files in th eMnchide folder to write custom applications. They should also be aware of the licensing requirements
set forth in the license.txt file.
The EPANET-MSX system is supplied as both:
•	a stand-alone console application (runepanetmsx.exe) that can run standard water quality analyses without any additional
programming effort required,
•	a function library (epanetmsx.dll) that, when used in conjunction with the original EPANET function library (epanet2.dll),
can produce customized programming applications.
At this point in time the extension has not been integrated into the Windows version of EPANET. This is expected to happen at
some future date. Examples of each type of usage are provided below.
Regardless of which approach is used, the user must prepare two input files to run a multi-species analysis. One of these is
a standard EPANET input file that describes the hydraulic characteristics of the network being analyzed (EPANET-MSX will
ignore any water quality information that might be in this file). The format of this file is described in the EPANET Users Manual
[Rossman, 2000, Rossman et al., 2020], Any network file that was created, edited and then exported from the Windows version
of EPANET can serve as the EPANET input file for the multi-species extension.
The second file that must be prepared is a special EPANET-MSX file that describes the species being simulated and the chemical
reaction/equilibrium model that governs their dynamics. The format of this file is described in INPUT FILE FORMAT (Section
4) of this manual.
3.1 Example Command Line Run
In order to demonstrate the use of the command line version of EPANET-MSX we will simulate the arsenic oxidation/adsorption
reaction system that was briefly described in CONCEPTUAL FRAMEWORK (Section 2) of this manual using the simple pipe
network shown in Fig. 3.1 that was adapted from Zhang et al. [2004], Table 3.2 lists the properties associated with the nodes of
this network while Table 3.3 does the same for the pipe links.
3.1. Example Command Line Run
11

-------
EPANETMSX USERS MANUAL, Release 2.0
B
Fig. 3.1: Schematic of the example pipe network
Table 3.2: Nodal properties of the example pipe network
Node
Elevation (m)
Demand (m3//?.?•)
Source
100
-
A
0
4.1
B
0
3.4
C
0
5.5
D
0
2.3
Table 3.3: Pipe properties of the example pipe network
Pipe
Length (m)
Diameter (mm)
C-Factor
1
1000
200
100
2
800
150
100
3
1200
200
100
4
1000
150
100
5
2000
150
100
The first step in running a multi-species analysis of a water distribution system is to prepare a standard EPANET input file of the
system that contains all of the information needed to perform a hydraulic analysis of the system. The Windows version of EPANET
2 was used to draw the network layout and assign node and pipe attributes using the program's graphical editing tools. A standard
.INP file was then created by issuing the File | Export | Network command. The resulting file was named examplel.inp and is
shown in Listing 3.1 (after some editing was performed to remove empty sections and default options). Note that for this simple
application the water demands remain constant over time and that a 48 hour simulation period is requested.
Listing 3.1: Contents of the examplel.inp input file.
[TITLE]
EPANET-MSX Example Network
[JUNCTIONS]
;ID Elev Demand Pattern
A ® 4.1
(continues on next page)
3.1. Example Command Line Run
12

-------
EPANETMSX USERS MANUAL, Release 2.0
(continued from previous page)
B
8
3.4
C
8
5.5
D
8
2.3
[RESERVOIRS]
; ID Head Pattern
Source 18®
[PIPES]
ID
Nodel
Node2
Length
Diameter Roughness
1
Source
A
1888
288 188
2
A
B
888
158 188
3
A
C
1288
288 188
4
B
C
1888
158 188
5
C
D
2888
158 188
[TIMES]
Duration	48
Hydraulic Timestep	1:8®
Quality Timestep	8:85
Report Timestep	2
Report Start	8
Statistic	NONE
[OPTIONS]
Units
Headloss
Quality
[END]
CMH
H-W
NONE
The next step is to prepare the MSX input file that defines the individual water quality species of interest and the reaction expres-
sions that govern their dynamics. This was done using a text editor, following the format described in INPUT FILE FORMAT
(Section 4) of this manual. The resulting MSX input file, named examplel.msx, is shown in Listing 3.2.
Listing 3.2: Contents of the examplel.msx input file.
[TITLE]
Arsenic Oxidation/Adsorption Example
[OPTIONS]
AREA_UNITS M2
RATE_UNITS HR
SOLVER RK5
TIMESTEP 368
RTOL	8.881
ATOL	8.8881
;Surface concentration is mass/m2
;Reaction rates are concentration/hour
;5-th order Runge-Kutta integrator
;368 sec (5 min) solution time step
;Relative concentration tolerance
;Absolute concentration tolerance
[SPECIES]
BULK AS3	UG
BULK AS 5	UG
BULK AStot	UG
;Dissolved arsenite
;Dissolved arsenate
;Total dissolved arsenic
(continues on next page)
3.1. Example Command Line Run
13

-------
EPANETMSX USERS MANUAL, Release 2.0
(continued from previous page)
WALL AS5s UG	;Adsorbed arsenate
BULK NH2CL MG	;Monochloramine
[COEFFICIENTS]


CONSTANT
Ka
18.®
;Arsenite oxidation rate coefficient
CONSTANT
Kb
8.1
;Monochloramine decay rate coefficient
CONSTANT
K1
5.8
;Arsenate adsorption coefficient
CONSTANT
K2
1.8
;Arsenate desorption coefficient
CONSTANT
Smax
58
;Arsenate adsorption saturation limit
[TERMS]



Ks
K1/K2

;Equil. adsorption coeff.
[PIPES]



;Arsenite oxidation
RATE AS3 -Ka*AS3*NH2CL
;Arsenate production
RATE AS5 Ka*AS3*NH2CL - Av*(Kl*(Smax-AS5s)*AS5 - K2*AS5s)
;Monochloramine decay
RATE NH2CL -Kb*NH2CL
;Arsenate adsorption
EQUIL AS5s Ks*Smax*AS5/(l+Ks*AS5) - AS5s
;Total bulk arsenic
FORMULA AStot AS3 + AS5
[TANKS]
RATE	AS3
RATE	AS5
RATE	NH2CL
FORMULA	AStot
-Ka*AS3*NH2CL
Ka*AS3*NH2CL
-Kb*NH2CL
AS3 + AS5
[QUALITY]
;Initial conditions (= 8 if not specified here)
NODE Source AS3 18.®
NODE Source NH2CL 2.5
[REPORT]
NODES C D
LINKS 5
SPECIES AStot YES
SPECIES AS5 YES
SPECIES AS5s YES
SPECIES NH2CL YES
There are several things of note in this file:
1. The species have been named as follows:
•	AS3 is dissolved arsenite (As+3), expressed in ng/L
•	AS5 is dissolved arsenate (As+5), expressed in ng/L
•	AStot is total dissolved arsenic expressed in ng/L
•	AS5s is adsorbed arsenate, expressed in ng/m2
;Report results for nodes C and D
;Report results for pipe 5
;Report results for each specie
3.1. Example Command Line Run
14

-------
EPANETMSX USERS MANUAL, Release 2.0
• NH2CL is dissolved monochloramine, expressed in mg/L
2.	The reaction rate coefficients, Ka and Kb, and the adsorption coefficients, K\, K2, and Smax, have been designated as
constants. If instead they varied by pipe, then they could have been declared as parameters and their values could have
been adjusted on a pipe-specific basis in the [PARAMETERS] section (Section 4.10) of the file. Note that the units of these
coefficients areas follows: (L/mg-hr) for Ka\ (l/hr) for Kb, (L/fj,g-hr) for if i; (l/hr) for K2; ^g/m? for Smax.
3.	The [PIPES] section supplies the three reaction rate expressions and the single equilibrium expression for this system as
was presented previously in equations (2.4) - (2.7) of CONCEPTUAL FRAMEWORK (Section 2). For example, the rate
expression for arsenite oxidation
A A o+3
__ = -kaAs+3(NH2Cl)
is expressed in the file as:
RATE As3 -Ka* As3 *NH2CL
while the equilibrium expression
a +5 	 kgSmax-A-S^
s 1 + ksAs+5
is re-written so that it has an implied 0 on the left hand side:
EQUIL As5s Ks*Smax*As5/(l + Ks*As5) - As5s
4.	The variable Av that appears in the rate expression for AS5 is a reserved symbol for the pipe wall surface area per unit of
pipe volume. It is computed internally by EPANET-MSX and has units of area per liter, where the area units are the same
as those specified in the [OPTIONS] section of the file.
5.	Even though there are no tanks in this example, a [TANKS] section is still needed in the MSX file because both BULK and
WALL species have been defined (Tank water quality reactions can not use wall species, which are associated only with
pipes). If only BULK species were present then a redundant [TANKS] section would not be required.
6.	An initial quality is assigned to the source reservoir which remains constant over the course of the simulation. If source
quality was to vary over time or there were source injections at other locations they could be described in a [SOURCES]
section.
7.	In the [REPORT] section we ask that results for all species at nodes C and D and link 5 be written to the report file.
The final step in analyzing arsenic oxidation/adsorption for our example network is to run the EPANET-MSX command line
executable. This can be done by first opening a Command Prompt window in Windows, navigating to the folder where
runepanetmsx.exe, epanetmsx.dll, epanet2.dll and the input files were saved, and issuing the following command:
runepanetmsx.exe examplel.inp examplel.msx examplel.rpt examplel.out
where examplel.rpt is the name of the file where the results will be written. If the executable were saved to a different folder than
that of the example files, then either the full path name would have to be added to the name of the executable on the command
line or the folder name would have to be added to the user's PATH environment variable. Fig. 3.2 is a screen capture of what
appears on the screen as the program runs. The last argument of the runepanetmsx.exe is optional and specifies the binary output
file name. The details of the binary output file are described in BINARY OUTPUT FILE FORMAT.
After the program finishes, the examplel.rpt file can be opened in any text editor (such as Windows Notepad) where its contents
can be viewed. Excerpts from the results file are reproduced in Listing 3.3. The first page contains a summary of the standard
EPANET options that were chosen for the run. Following this is a table of results for each node and each link. These tables
contain the concentrations of each species at each reporting period. Note that the surface species are not listed for nodes since by
definition this class of constituent is associated only with pipe surfaces. At the end of the report file, the mass balance summaries
of the three differential variables (As+3, \As+z and NH2Cl) are provided. These mass balances reports are consistent with those
provided by EPANET 2.2, and will include all relevant species. Starting and ending mass, mass inflow, outflow, and reacted are
included.
3.1. Example Command Line Run
15

-------
EPANETMSX USERS MANUAL, Release 2.0
SB Command Prompt
~ X
I
c:\Epanet-MSX>runepanetmsx.exe examplel.inp examplel.msx examplel.rpt examplel.out
... EPANET-MSX Version 2.0.0
o	Processing EPANET input file
o	Processing MSX input file
o	Computing network hydraulics
o	Initializing network water quality
o	Computing water quality at hour 48
o	Reporting water quality results
...	EPANET-MSX completed successfully.
c:\Epanet-MSX>
Fig. 3.2: Command line execution of EPANET-MSX.
Listing 3.3: EPANET-MSX results for the example network
Page 1	Thu Feb 9 18:48:39 2823
EPANET
Hydraulic and Water Quality
Analysis for Pipe Networks
Version 2.2
EPANET-MSX Example Network
Input Data File 		examplel.inp
Number of Junctions		4
Number of Reservoirs		1
Number of Tanks 		8
Number of Pipes 		5
Number of Pumps 		8
Number of Valves 		8
Headloss Formula 		Hazen-Williams
Nodal Demand Model 		DDA
Hydraulic Timestep 		1.88 hrs
Hydraulic Accuracy 		8.881888
Status Check Frequency 		2
Maximum Trials Checked 		18
Damping Limit Threshold 		8.888888
Maximum Trials 		288
Quality Analysis 		None
(continues on next page)
3.1. Example Command Line Run
16

-------
EPANETMSX USERS MANUAL, Release 2.0
(continued from previous page)
Specific Gravity 	 1.8®
Relative Kinematic Viscosity 	 1.8®
Relative Chemical Diffusivity 	 1.88
Demand Multiplier 	 1.88
Total Duration 	 48.88 hrs
Reporting Criteria:
No Nodes
No Links
Analysis begun Thu Feb 9 18:48:39 2823
Processing MSX input file examplel.msx
Page 1	EPANET-MSX 2.8.
EPANET - MSX
Multi-Species Water Quality
Analysis for Pipe Networks
Version 2.8.8
Arsenic Oxidation/Adsorption Example
< Node
n
V
V
V


me

AS 5
AStot
NH2CL
•:min
UG/L
UG/L
MG/L
8
88
8.88
8.88
8.88
2
88
8.88
8.88
8.88
4
88
8.88
8.88
8.88
6
88
8.88
8.88
8.88
8
88
8.88
8.88
1.18
18
88
9.17
9.17
1.18
12
88
9.17
9.17
1.18
14
88
9.17
9.17
1.18
16
88
9.17
9.17
1.18
18
88
9.17
9.17
1.18
28
88
9.17
9.17
1.18
22
88
9.17
9.17
1.18
24
88
9.17
9.17
1.18
26
88
9.17
9.17
1.18
28
88
9.17
9.17
1.18
38
88
9.17
9.17
1.18
32
88
9.17
9.17
1.18
34
88
9.17
9.17
1.11
36
88
9.17
9.17
1.11
38
88
18.83
18.83
1.11
48
88
18.83
18.83
1.11
(continues on next page)
3.1. Example Command Line Run
17

-------
EPANETMSX USERS MANUAL, Release 2.0
(continued from previous page)
42
88
1®. 83
18.83
1.11
44
88
18.83
18.83
1.11
46
88
18.83
18.83
1.11
48
®8
18.83
18.83
1.11
«< Node D »>
Time	AS5	AStot	NH2CL
hr:min	UG/L	UG/L	MG/L
8
88
8
88
8
8®
8
88
2
88
8
88
8
88
8
88
4
88
8
88
8
88
8
88
6
8
88
88
8
8
88
88
8
8
88
88
8
8
88
88
18
88
8
88
8
88
8
88
12
88
8
88
8
88
8
88
14
88
8
88
8
88
8
88
16
88
8
88
8
88
8
88
18
88
8
88
8
8®
8
88
28
88
8
88
8
88
8
88
22
8®
8
88
8
88
8
88
24
88
8
88
8
88
8
24
26
88
8
88
8
88
8
24
28
8®
9
17
9
17
8
24
38
8®
9
17
9
17
8
24
32
88
9
17
9
17
8
24
34
8®
9
17
9
17
8
24
36
8®
9
17
9
17
8
24
38
88
9
17
9
17
8
24
48
88
9
17
9
17
8
24
42
88
9
17
9
17
8
24
44
88
9
17
9
17
8
24
46
88
9
17
9
17
8
24
48
88
9
17
9
17
8
24
«< Link 5 »>
NH2CL
MG/L
Time	AS5	AStot	AS5s
hr:min	UG/L	UG/L	UG/M2
8
88
8.88
8.88
-8.88
8.8®
2
88
8.88
8.8®
8.®®
®. 8®
4
88
8.88
8.88
®. 8®
®. 8®
6
88
8.8®
8.88
8.88
8.88
8
88
8.88
8.8®
8.88
8.85
18
88
8.85
8.85
4.51
8.17
12
88
1.86
1.86
9.88
8.27
14
88
2.87
2.87
15.27
8.35
16
88
3.87
3.87
28.64
8.42
18
88
4.88
4.88
26.82
8.47
28
8®
5.89
5.89
31.39
8.52
(continues on next page)
3.1. Example Command Line Run
18

-------
EPANETMSX USERS MANUAL, Release 2.0
(continued from previous page)
22
88
6.89
6.89
36.75
8. 55
24
88
7.98
7.98
42.12
8.56
26
88
8.91
8.91
47. 58
8.56
28
88
9.17
9.17
48.93
8.56
38
8®
9.17
9.17
48.93
8.56
32
8®
9.17
9.17
48.93
8.56
34
88
9.17
9.17
48.93
8.56
36
88
9.17
9.17
48.93
8.57
38
88
9.19
9.19
48.93
8.57
48
88
9.38
9.38
48.95
8.57
42
88
9.41
9.41
48.96
8.57
44
88
9.52
9.52
48.97
8.57
46
88
9.64
9.64
48.98
8.57
48
88
9.75
9.75
48.99
8.57
Water Quality Mass Balance: ASB (UG)
Initial Mass:
Mass Inflow:
Mass Outflow:
Mass Reacted:
Final Mass:
Mass Ratio:
8.88888e+88
7.344®9e+®6
5.156®9e-ll
-7.3274®e+®6
1.66911e+®4
1.888®®
Water Quality Mass Balance: AS5 (UG)
Initial Mass:
Mass Inflow:
Mass Outflow:
Mass Reacted:
Final Mass:
Mass Ratio:
8.888®8e+88
8.8®®®®e+8®
5.79736e+86
7.13763e+86
1.34827e+86
1.88888
Water Quality Mass Balance: NH2CL (MG)
Initial Mass:
Mass Inflow:
Mass Outflow:
Mass Reacted:
Final Mass:
Mass Ratio:
8.888®8e+88
1.83682e+86
8.51117 e+8 5
-8.88156e+85
1.84749e+85
1.88888
Analysis ended Thu Feb 9 18:48:39 2823
3.1. Example Command Line Run
19

-------
EPANETMSX USERS MANUAL, Release 2.0
3.2 Example Toolkit Usage
Using the EPANET-MSX function library requires some programming effort to build custom applications and must be used in
conjunction with the standard EPANET Programmer's Toolkit. Applications can be written in any programming language that can
call external functions residing in a Windows DLL (or a Linux shared object library), such as C, C++, Visual Basic, and Delphi
Pascal. Section MSX TOOLKIT FUNCTIONS describes each function included in the MSX toolkit library. The functions in the
EPANET toolkit library are documented online at http://wateranalytics.org/EPANET/.
As an example of how the library can be used to construct an application, Listing 3.4 displays the C code behind the command line
implementation of the MSX system, runepanetmsx.exe, which was just discussed. The listing begins by checking for the correct
number of command line arguments and then attempts to open and read the EPANET file supplied as the first argument. It uses
the EPANET toolkit function ENopen for this purpose.
The code then begins a do-while loop that simplifies error detection through the remainder of the program. The MSXopen function
is used to open and process the MSX file (the second command line argument), and the MSXsolveH function is used to run a
hydraulic analysis of the network whose results are saved to a scratch file. This is followed by a call to MSXinit to initialize the
water quality analysis. Note that the argument of 1 to this function tells the MSX system to save its computed water quality results
to a scratch file so that they can be used for reporting purposes later on.
The program then begins another do-while loop that will step through each water quality time step. At each such step, theMSXstep
function is called to update water quality throughout the network and save these results to the scratch output file. This function
also updates the amount of time left in the simulation (stored in the variable named tleft). The loop continues until either no more
time is left or an error condition is encountered.
If the simulation ends successfully, the MSXreport function is called to write the water quality results to the report file that was
named on the command line. If a fourth file name was supplied on the command line, then the MSXsaveoutfile is called to save
the results in a binary format to this file. Lastly, the MSX system is closed down by calling MSXclose and the same is done for
the EPANET system by calling ENclose.
If the source code in Listing 3.4 was saved to a file named epanetmsx.c then it could be compiled into an executable named
runepanetmsx.exe by first opening a Microsoft Visual Studio command prompt window (64-bit) and then using the following
commands:
CL/c epanetmsx.c
LINK epanetmsx.obj epanet2.lib epanetmsx. lib/O UT.-runepanetmsx.exe
Note that when developing MSX applications in C/C++, the header files epanet2.h, epanetmsx.h and epanet2_enums.h must be in
the same folder as the application's source codes (epanetmsx.c here), and the library modules epanet2.lib and epanetmsx.lib must
be linked in with the application's object modules. Versions of these files that are compatible with the Microsoft C/C++ compiler
(Version 6 and higher) are supplied with the EPANET-MSX distribution. Also, copies of the distributed DLL files epanet2.dll
and epanetmsx.dll must be placed in the same directory as the application's executable file or reside in a directory listed the user's
PATH environment variable.
Users using other compilers or platforms would need to use the appropriate commands to produce the required object library files
and executables.
Listing 3.4: C source code for the command line version of EPANET-
MSX
£
OI1U
fI
j£ EPAMET-l
#include
Z'XRCXUC'Q
#include
#include
12
EP.
12
(continues on next page)
3.2. Example Toolkit Usage
20

-------
EPANETMSX USERS MANUAL, Release 2.0
(continued from previous page)
int main(int argc, char* argv[])
/*
Purpose:
runs a multi-species EPANET analysis
-A" "A°
* 'A-
A- ~k
-A- -A;
-A" si'
si' >1'
>1- -/?
V
{
juinn::
argc = number of command line arguments
argv = array of command line arguments.
Returns:
an. error code (or S for no error),
rw>:es:
The command line arguments are:
-	the name of a regular EPANET input data file
-	the name of a EPANET-MSX input file
-	the name of a report file that will contain status
messages and output results
-	optionally, the name of an, output file that will
contain water quality results in binary format.
int err, done = 1;
double t, tleft;
long oldHour, newHour;
// — Check command line arguments
if (argc < 4) {
printf("\n Too few command line arguments,\n");
return is;
}
// — Open the EPANET file
printf("\n... EPANET-MSX Version 2.®\n");
printf("\n o Processing EPANET input file");
err = ENopen(argv[l], argv[3], "");
if (err) {
printf("\n\n... Cannot read EPANET file; error code = %d\n", err);
ENcloseO;
return ®;
}
// 	-- Begin an error detection loop
do {
// — Open the MSX input file
printf("\n o Processing MSX input file");
err = MSXopen(argv[2]);
if (err) {
printf("\n\n... Cannot read MSI file; error code = %d\n", err);
(continues on next page)
3.2. Example Toolkit Usage
21

-------
EPANETMSX USERS MANUAL, Release 2.0
(continued from previous page)
break;
}
// — Solve hydraulics
printf("\n o Computing network hydraulics");
err = MSXsolveHO;
if (err) {
printf(
"\n\n.,, Cannot obtain network hydraulics; error code = %d\n", err);
break;
}
// — Initialize the multi-species, analysis
printf("\n o Initializing network water quality");
err = MSXinit(l);
if (err) {
printf(
"\n\ri... Cannot initialize EPANET-MSX; error code = %d\n", err);
break;
}
t = ®;
oldHour = -1;
newHour = ®;
printf("\n");
// — Repeat for each time step
do {
// -	- Report current progress
if (oldHour != newHour) {
printf("\r o Computing water quality at hour %-4d", newHour);
oldHour = newHour;
}
// — Compute water quality
err = MSXstep(&t, frtleft);
newHour = (long) (t / 368®.®);
} while (!err && tleft > ®);
// — Report: any runtime error
if (err) {
printf("\n\n... EPANET-MSX runtime error; error code = %d\n", err);
break;
}
else
printf("\r o Computing water quality at hour %-4d", (long) (t / 36®®.®));
// 	 neuorr. results
(continues on next page)
3.2. Example Toolkit Usage
22

-------
EPANETMSX USERS MANUAL, Release 2.0
(continued from previous page)
printf("\n o Reporting water quality results");
err = MSXreportO;
if (err) {
printf(
"\n\n,., MSI report writer error; error code = %d\n", err);
break;
}
// — Save results to binary file if a file name was provided
if (argc >= 5) {
err = MSXsaveoutfile(argv[4]);
if (err > ®) {
printf(
"\n\n... Cannot save MSX results file; error code = %d\n", err);
break;
}
}
// — End of error detection loop
} while (!done);
// — Close both the multi-species & EPASET systems
MSXcloseO;
ENcloseO;
if (!err) printf("\n\n.,. EPANET-MSX completed successfully.");
printf("\n");
return err;
}
3.3 Using Compiled Reaction Models
EPANET-MSX has the option to compile the chemical reaction equations that a user specifies within their MSX input file using
a C compiler that already resides on the user's system. This can speed up execution times by a factor of 2 to 5, depending on the
nature of the reaction system and the choice of integration method. This option is available on Windows operating systems that
have either the Microsoft Visual Studio C++ compiler or the MinGW port of the Gnu C++ compiler installed, or on Linux systems
with the Gnu C++ compiler. To utilize this option, one adds the following command to the [OPTIONS] (Section 4.2) section of
the MSX input file:
COMPILER choice
where choice is VC for the Visual Studio C++ compiler, GC for the MinGW or Gnu C++ compilers, or NONE for no compiler
(the default compiler option). To determine if your Windows system has the Visual Studio C++ build tools installed you can check
to see if a Visual Studio folder appears on your Start Menu. To check for the MinGW compiler, open a Command Prompt window
and enter gcc.
The Gnu compiler comes standard with most Linux installations.
3.3. Using Compiled Reaction Models
23

-------
CHAPTER
FOUR
INPUT FILE FORMAT
The input file used by EPANET-MSX to describe the species and reaction system being modeled is organized into sections, where
each section begins with a keyword enclosed in brackets. The various section keywords are listed in Table 4.1. Listing 4.1 contains
a template of what the input file layout looks like.
Table 4.1: EPANET-MSX input file section keywords
[TITLE]
adds a descriptive title to the data set
[OPTIONS]
sets the values of computational options
[SPECIES]
names the chemical species being analyzed
[COEFFICIENTS]
names the parameters and constants used in chemical rate and equilibrium ex-
pressions
[TERMS]
defines intermediate terms used in chemical rate and equilibrium expressions
[PIPES]
supplies the rate and equilibrium expressions that govern species dynamics in
pipes
[TANKS]
supplies the rate and equilibrium expressions that govern species dynamics in
storage tanks
[SOURCES]
identifies input sources (i.e., boundary conditions) for selected species
[QUALITY]
supplies initial conditions for selected species throughout the network
[PARAMETERS]
allows parameter values to be assigned on a pipe by pipe basis
[DIFFU SIVIT Y]
specifies the relative molecular diffusivity of bulk species
[PATTERNS]
defines time patterns used with input sources
[REPORT]
specifies reporting options
Each section can contain any number of lines of data and appear in any order. Blank lines can appear anywhere in the file and the
semicolon (;) can be used to indicate what follows on the line is a comment, not data. A maximum of 1024 characters can appear
on a line. The ID labels used to identify objects can be any combination of characters and numbers that do not contain square
brackets ([]), double quotes or a semicolon, except that they cannot be the same as any reserved keyword or hydrauic variable (see
[TERMS]).
On the pages that follow the contents and formats of each input file section are described in the order shown above. Reserved
keywords are shown in bold and option choices are separated by slashes. The usage of parentheses in mathematical expressions (in
[TERMS], [PIPES], and [TANKS]) is encouraged to avoid potential misintepretations of the expression parser of EPANET-MSX.
Listing 4.1: EPANET-MSX input file template
[TITLE]