Using Multi-Species Extension (MSX) for advanced water quality modeling

Product(s): WaterGEMS, WaterCAD
Version(s): 08.11.05.61 and higher
Area: Modeling

This technote explains how to configure a Multi-species analysis (MSX) which is an advanced Water Quality Modeling extension. 

Background

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)

Workflow

To perform a multi-species analysis,

  • First, configure a Multi Species analysis setup. You can import existing setups from engineering library if desired. This contains global information about your constituents. For more details information on each of the parameters in the Setup area, see the relevant Help topic or the EPANET Multi-Species Extension Software and User’s Manual 

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.

  • Next, create a new scenario and calculation options, if required as you would do for a water quality analysis. Select Multi Species Analysis as the Calculation Type in the Calculation Options for your scenario.

  • Select the appropriate Multi Species analysis setup. Use the one you created earlier or choose "Edit Multi Species analysis setup" to create a new one.

  • Lastly, configure the Model Configuration, which can be accessed from the field below the Multi-Species Analysis field in the calculation options. Multi-species model configuration consists of data for multi-species analysis that is dependent on the model (as opposed to setup data which is independent of the model). For detailed information on Multi Species analysis and Multi Species analysis model configuration, please navigate to the related topic in the in-program Help documentation, or the EPANET Multi-Species Extension Software and User’s Manual .

Calculations

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).

Advanced [OPTIONS] Parameters

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 timestepSegments 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.



Results

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.

Example Model

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.

Troubleshooting

General Troubleshooting

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.

  • Compute and validate the model with the calculation options calculation type set to "Hydraulics Only" and correct the user notifications.
  • Check for things that generate additional intermediate time steps, such as empty/full tanks.

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

  • Apply the negative demand directly to the adjacent tank.
  • If possible, instead of using a negative demand it may be better to model back to the actual source (assuming there is more to the network, upstream of the negative demand).

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:

  • Review the network topology for unnecessary elements such as pipes at a dead end with no demand
  • Review pipe lengths and consider lengthening them (while keeping things hydraulically equivalent) with Skelebrator
  • Review pipe flows and consider removing sections with very low flow that are not necessary for the analysis. This could be done manually, using active topology (to make those sections inactive) or with Skelebrator.
  • Use the FTOL, LTOL and ERRCHECK parameters in the [OPTIONS] section of the MSX setup to either ignore offending pipes or suppress the errors. See note further above under the "Advanced [OPTIONS] Parameters" section for details - these options are available for version 10.01.01.04 by contacting Technical Support, or by upgrading to a newer version (check the list of features in the respective "what's new?" article upon release, which should be listed here.)

See Also

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

Anonymous
Recommended
Related