Product(s):	WaterGEMS, WaterCAD
Version(s):	CONNECT Edition, 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 (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)

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 .

Custom Calculations and Parameters

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)

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/10^th 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 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 results

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.

Other input

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.

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.

A note on filtering and exporting MSX results:

The "Constant" and "Variable" options for the Reporting Time Step calculation option are not currently supported with MSX. You must set this to "<All>" and use the hydraulic timestep to control the amount of output. (reference # 918545). This is because this option filters the hydraulic results which then get passed to the MSX engine, and the MSX engine requires regular/constant reporting intervals.
If you need to perform a long simulation (for example two weeks) and export the results to Excel (using File > Export > Export to Excel) you may want to filter the results to avoid long delays in exporting large amounts of output. First, consider creating Flextables with just the fields you want to export, and use the check boxes on the left side of the Excel Export dialog to reduce the amount of output. Next, you can utilize the time step export options in the lower-right corner of the Excel Export dialog. This feature is available in version 10.04.00.XX and greater and enables you to filter the MSX results using a Constant output step, or a Variable output step (where you can choose between No results, All results or a constant output step, for multiple time ranges, just like the calculation option). Note that this feature applies a filter on top of the existing computed results, and the setting you choose is persisted across all models (be sure to adjust it for other models as needed). Note that the Excel file format is limited to roughly 1 million rows, so if you encounter "Export to Excel failed", try reducing the amount of output or consider using the CSV file format option (using the dropdown in the bottom-left corner of the Excel Export dialog.) See more here: Export time series data to Excel or CSV format
If you have an earlier version, you may need to consider using the advanced Data Integrator tool to avoid long delays in exporting all timesteps in the Excel Export feature.

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: 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: 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

If the EPS calculation is relatively fast but the MSX calculation is slower than expected, please upgrade to a version newer than 24.00.01.12 (or contact Support for a patch for 24.00.01.12) as performance has been improved. Reference #1512770.

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

Issue: the different tank mixing model options do not seem to be working (results do not change)

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

Issue: I am trying to simulate water age results with MSX but they do not match WaterGEMS age results

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.

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