Set up and Run a Multi-Species Extension (MSX) Simulation

The Multi-Species Extension (MSX) lets you model several interacting chemical and biological species at once—in the bulk flow and at the pipe wall—within a single water quality run. For the underlying concepts, see Multi-Species Model. For standard single-species analyses, see Water Quality Simulation.

InfoWater Pro 2024.3 and earlier use the original EPA MSX engine. InfoWater Pro 2024.4 and later use MSX 2.0, which adds longitudinal dispersion and improved water quality mass balance and reporting.

Before you begin

Note: Starting from InfoWater Pro 2027.1, MSX does not require an additional license. All InfoWater Pro customers have full MSX access.

• Start from a hydraulic model that already runs successfully. The water quality solution runs after the hydraulic simulation and uses the flows it produces, so unresolved convergence problems carry through into your species results.
• MSX requires an extended period simulation. A steady state run produces no water quality results.
• Decide whether to adapt one of the seven built-in example models: CHLORAMINE, DBP, INACTIVATION, PSM1, PSM2, Temperature, or Turbidity. Adapting an example is often faster than building a reaction scheme from scratch.

Where MSX data is entered

Setting up an MSX simulation involves multiple dialogs. Global definitions are in the Multi-Species Model dialog, individual element are entered in the Model Explorer Attribute tab, and the model is selected for running in the Simulation Options dialog.

Data	Where you enter it	Scope
Species, reaction terms, parameters, constants, global initial values	Model Explorer > Command Center > Tools > Multi-Species Model	Whole network
Initial quality for bulk species, at a node; quality sources for individual species	Select the node, then Model Explorer > Attribute tab > multi-species initial quality button	One node
Initial quality for wall species, at a pipe	Select the pipe, then Model Explorer > Attribute tab > multi-species initial quality button	One pipe
Parameter values, such as reaction rates, at a pipe	Select the pipe, then Model Explorer > Attribute tab > Multi-Species Parameters	One pipe, overrides global
Parameter values at a tank	Select the tank, then Model Explorer > Attribute tab > Multi-Species Parameters	One tank, overrides global
Model selection for the run, and the quality analysis type	Model Explorer > Operation > Simulation Options > Quality	Simulation options set
Quality Timestep	Model Explorer > Operation > Simulation Time	Simulation time set

Note: The per-element multi-species tables are available only in the Model Explorer. The Database Editor does not display them.

Note: Pipes have two separate multi-species tables: one for initial quality and one for parameters. If the Model Explorer window is narrow, the second button can be cut off. Widen the window if you can't see it.

Workflow overview

To set up and run an MSX simulation, follow these steps:

• Build or choose a multi-species model
• Define your species
• Enter the reaction expressions
• Enter parameters and constants
• Assign initial quality and quality sources
• Select the model for the run
• Set the quality timestep and run
• Review species results

1. Build or choose a multi-species model

In Model Explorer, go to Command Center, then select Tools > Multi-Species Model.

Use the toolbar to create a model with New Model, or open one of the built-in examples and use Save As to make your own copy. You can also bring in a scheme from outside the project with Import a MSX Model.

2. Define your species

On the Species tab, add one row per species you want to model.

Field	What to enter
Type	Bulk for substances dissolved in the flowing water, or Wall for substances that react at the pipe surface.
Unit	Species mass units. Bulk species are measured in mass units per liter. Wall species are measured in mass units per unit area, where the area unit is set on the General tab.
Global Init.	The global initial water quality value for the species. See step 5 for how this interacts with values set at individual elements.
P Type and T Type	The expression format that defines the reaction dynamics of the species in pipes and in tanks: No Expression, Rate, Formula, or Equilibrium.
P Term and T Term	The ID of the term that holds the mathematical expression for pipes and for tanks. You create these on the Term tab in step 3.
Diffusivity	The relative diffusivity of the species used when modeling longitudinal dispersion. A value of 1 corresponds to the diffusivity of chlorine in water at 20 °C. Set it to zero to neglect dispersion for this species, which can improve run performance.
Abs. Tol. and Rel. Tol.	Optional per-species tolerances that override the global values set on the General tab.

3. Enter the reaction expressions

On the Term tab, define the expressions that describe how your species change and interact, then reference each one from the P Term and T Term columns on the Species tab.

Supply one expression for each species in the model. The format you choose in P Type or T Type determines how the expression is interpreted:

• Rate expresses the rate of change of the species with respect to time, as a function of the other species in the model.
• Formula is used when the concentration of the species is a simple function of the remaining species.
• Equilibrium is used for equilibrium expressions, where the expression you supply is assumed to be equated to zero.

MSX accepts user-defined expressions for both bulk and wall reactions, and supports any number of species and cross-dependent formulas.

4. Enter parameters and constants

Reaction expressions can reference two kinds of coefficient, and the difference matters:

• On the Parameter tab, enter coefficients whose values can differ from element to element, such as reaction rates. The value you enter here is the global default. You can override it for individual pipes and tanks in step 5.
• On the Constant tab, enter coefficients that are fixed for the whole model and cannot be overridden per element.

5. Assign initial quality and quality sources

Initial quality can be set globally and at individual elements, and the two interact. For a pipe, the starting concentration of a species is resolved in this order:

1. The initial quality entered for that pipe, if any.
2. The Global Init. value for the species, if it is not empty.
3. The initial values of the nodes adjacent to the pipe. These affect adjacent pipes only, and only for species where Global Init. is empty.
4. Zero, if none of the above are defined.

To set values at individual elements:

• Select a node and use its multi-species initial quality button on the Attribute tab to enter initial values for bulk species. The same dialog is where you designate the node as a quality source for individual species.
• Select a pipe and use its multi-species initial quality button on the Attribute tab to enter initial values for wall species.
• Select a pipe or tank and use Multi-Species Parameters on the Attribute tab to override global parameter values for that element.

6. Select the model for the run

In Model Explorer, select Operation > Simulation Options. On the Quality tab:

1. Set the quality analysis option to Advanced. This is the option used to run a multi-species model.
2. In MSX Model, select your model from the list, or use Browse to open the Multi-Species Model editor.

You can also make a model current from the Multi-Species Model dialog with Set as Active Model.

MSX models store all of their data, including initial quality and quality source nodes, inside the MSX model itself rather than in the Quality Set dataset used by the built-in water quality types. To tie a particular scenario to particular MSX data, select the MSX model in Simulation Options, then associate that simulation options set with the scenario on the General tab of Scenario Explorer. See Scenario management with InfoWater Pro MSX models.

7. Set the quality timestep and run

In Model Explorer, select Operation > Simulation Time, then set Quality Timestep. The default is 5 minutes. For accurate results, use a value no greater than one tenth of Hydraulic Timestep.

If Adaptive Mixing Resolution is enabled in Simulation Options, you can set Quality Timestep as long as Hydraulic Timestep.

Run the simulation from Run Manager as you would any hydraulic or water quality run.

Water quality results can take a long time to reach a steady, repeating pattern, and for some networks you may need to run several weeks of simulated time before results stabilize. The WQ State options in Simulation Options, which let you save and reuse a warmed-up state, do not apply to Advanced multi-species analyses. To keep output files manageable on long MSX runs, delay Report Start so that the initial unsteady period is excluded, and use a larger Report Timestep.

8. Review species results

Review each species over time and location using the standard water quality output tools, including Report Manager, tabular and graph reports, thematic mapping, and animation.

Tips

• Open a built-in example model to see how species, terms, parameters, and constants fit together before building your own.
• Change one thing at a time. Complex reaction schemes are easier to debug incrementally.
• If a species shows no reaction at all, check that P Type and T Type are not left at No Expression and that P Term and T Term point at the intended terms.
• If a run produces no water quality output, check that the analysis option is set to Advanced and that a model is selected in MSX Model.