This technote explains how to configure a Multi-species analysis (MSX) which is an advanced Water Quality Modeling extension.
Using a constituent analysis, a user can track a single constituent through a water distribution system, provided the constituent behaves according to one of the kinetic models (e.g. first order decay). However, some constituents (E.g. Multi-source chlorine decay) cannot be modeled this way because they are involved in significant multi-species reactions or their kinetics do not fit one of the existing models. To handle these cases, WaterGEMS and WaterCAD provides Multi-species Analysis, based on the EPANET-MSX model with a WaterGEMS or WaterCAD user interface. This is available in V8i SELECTseries 5 and greater (including CONNECT Edition).
Multi-species analysis allows for consideration of multiple interacting species in the bulk flow and on the pipe walls.
It can be accessed from Components > Water quality > Multi Species analysis setups (or Components>Multi Species analysis setups. for V8i)
To perform a multi-species analysis,
Note: the interval for the [PATTERNS] is taken from the [TIMES] section of the EPANET input file. For WaterGEMS and WaterCAD, this is the calculation timestep.
In some cases of multi species analysis, it is required to utilize pre-defined parameters or internally computed values to generate specific equations or set of equations to run.
This can be achieved by using the “[TERMS]” feature available in an MSX run. See more here: Adding custom parameters and equations with Multi Species Extension (MSX)
The timestep for calculations that is used in the multi-species analysis is the one which is defined in the OPTIONS section of the Multi Species analysis setup. If it is not defined in the options of Multi Species analysis, then the default water quality time step is used which is 1/10th of the hydraulic time step.
Note: if you modify the TIMESTEP parameter and your model calculation fails with "could not read hydraulic results file", the model run duration may not be divisible by the timestep you selected (for example 250 seconds for a 144.0 hour simulation).
The following Parameters are planned to be available in the next major version released after 10.01.01.04. If you have 10.01.01.04 and a newer version is not yet available, please contact Technical Support. You can add them under the "[OPTIONS]" section of your MSX Setup.
LTOL - An optional length tolerance in feet (if not supplied defaults to 0). Wall reaction calculations will be skipped for pipes with length below this tolerance. Segments still get transported (and are subject to bulk reactions) as normal. By default, pipes with a length of zero are ignored in this fashion; this option extends that to a tolerance that you can specify. FTOL - An optional flow tolerance in gal/min (if not supplied defaults to 0). Wall reaction calculations will be skipped for pipes with flow below this tolerance, at each given timestep. Segments still get transported (and are subject to bulk reactions) as normal. By default, pipes with a flow of zero are ignored in this fashion; this option extends that to a tolerance that you can specify. Smaller FTOL values should provide more accurate results but if set too low, numerical error can be introduced from low flow pipes. The exact value to use may be different for each system and the user may need to experiment to get good resultsERRCHECK - An optional flag for specifying whether MSX error checking is enabled (if not supplied defaults to ON; valid options OFF or ON). If set to "OFF", then error conditions that would otherwise cause the calculation to fail, will be suppressed and the calculation will proceed. For example Care must be taken in this case to closely review the concentration results which could be compromised. Further reporting on failures when error checking is ignored, are planned to be included in a future release.
Information on much of the input can be found in the EPANET MSX manual. The following are some key points related to various input:
MASS - A MASS type source adds a specific mass of species per unit of time to the total flow entering the source node from all connecting pipes.
CONCEN - A CONCEN type source sets the concentration of the species in any external source inflow (i.e., a negative demand) entering the node. The external inflow must be established as part of the hydraulic specification of the network model. Note: for this to work in tanks or junctions, inflow will be needed.
FLOWPACED - A FLOWPACED type source adds a specific concentration to the concentration that results when all inflows to the source node from its connecting pipes are mixed together.
SETPOINT - A SETPOINT type source fixes the concentration leaving the source node to a specific level as long as the mixture concentration of flows from all connecting pipes entering the node is less than the set point concentration. SETPOINT is a booster that will add mass.
After computing a multi-species run, a result field will be automatically generated for each of the species involved. You can find these under the section "Results (multi species analysis)". You can color code, annotate, graph, etc just like any other result field.
A note on filtering and exporting MSX results:
For examples, see the MSX manual, or the Example9 model found in the Samples folder within your product installation folder. In this model, there are several scenarios with "Multi Species" in the name.
Starting with build 10.02.03.06 (with the patch installed), you can have up to about 2.1 million characters in the Multi-Species Analysis Model Configuration. Prior to build 10.02.03.06, there was currently a limit of 32767 characters allowed in the in the Multi-Species Analysis Model Configuration dialog.
If the multi species analysis fails to compute, try computing in a small test model for debugging purposes (to determine what is causing the failure).
For the actual model, ensure that the basic EPS is in good shape.
"Could not solve reaction equilibrium expressions"
If the model has a negative demand applied at a junction upstream of a tank try one of the following
See: Error when running MSX - Could not solve reaction equilibrium expressions
If there are adjacent tanks, that are hydraulically close, try combining them into a single equivalent composite tank.
See: Rapid flow oscillation between hydraulically close tanks
There was an upper limit on the report size when running MSX in some versions of WaterGEMS and WaterCAD. This would result in results listed as "N/A" after some time for either long model runs or runs with small time steps. Starting with an updated to CONNECT Edition Update 1 (build 10.01.00.72), this upper limit is not longer an issue. If an upgrade is available, download and install it and that should help. Alternatives include running the model for less time or trying a larger time step.
“illegal math operation occurred in pipe rate for specie: ___”
First, double check the equations in your MSX setup to ensure for issues such as a condition that could could a divide by zero situation or a negative number raised to an exponent.
This has also been known to occur in the past in models with pipes that had very low flow or very small pipe lengths. It is unknown at this time exactly what causes this, but the following are some things that may help:
There is a known issue with the EPANET MSX code as of June 2022 in which only the "completely mixed" option worked correctly while the others (LIFO, FIFO and 2-compartment) did not produce expected results. (reference # 897360) This has been fixed in a cumulative patch set for WaterCAD and WaterGEMS 10.03.05.05. Contact Technical Support for the patch (available for subscribers) or upgrade to a newer version when available. Also for FIFO, ensure that you are using the WaterGEMS 2.00.10 (or EPANET 2.00.10) compatibility mode, and use the Euler (EUL) solver for MSX (NOT the ROS2 solver).
To compare results between WaterGEMS’ Age calculation and the MSX equivalent of Age, you will need to use the WaterGEMS 2.00.10 (or EPANET 2.00.10) compatibility mode, and use the Euler (EUL) solver for MSX. Also make sure tank mixing models are set right for both runs and see the note above regarding a known issue with tank mixing models.
Mixing Chlorine and Chloramines
Understanding the Water Quality Time Step
Adding custom parameters and equations with Multi Species Extension (MSX)
Modeling DBP Formation - Water Quality Analysis
EPANET Multi-Species Extension Software and User’s Manual
Rapid flow oscillation between hydraulically close tanks
Forum: Multi Species Analysis