You are currently reviewing an older revision of this page.
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.
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.
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. ERRCHECK - 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.
General Troubleshooting
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.
Issue 1 - The calculation fails midway through with the following user notification:
"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
Issue 2 - The model is slow to compute.
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
Issue 3 - Report results are listed as N/A after a certain period of time.
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.
Issue 4 - The calculation fails midway through with the following user notification:
“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:
Mixing Chlorine and Chloramines
Understanding the Water Quality Time Step
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