| Product(s): | WaterGEMS, WaterCAD |
| Version(s): | CONNECT Edition, V8i |
| Area: | Modeling |
How can I define and use custom parameters and equations with Multi Species Extension (MSX), utilizing model parameters or results and/or custom equations?
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.
Terms can be defined to make writing the various water quality equations easier for example by breaking equations up into manageable pieces. One can use this feature to define pre-defined variables such as “D” for pipe diameter, “Q” for flow and “Re” for Reynolds number. A set group of hydraulic variables can be referenced using the following reserved names:
For example, if you wish to calculate the mass transfer coefficient for a chlorine decay analysis you can setup the term as follows;
[TERMS]
Kf 1.2e-4*Re^0.88/D
This way you can use the TERMS feature to define formulae for specific terms you wish to include in your analysis.
* the Darcy-Weisbach friction factor is computed based on the headloss across each pipe, only if the Ff term is referenced in the MSX setup. This happens even if the steady state/EPS friction method is set to something other than Darcy-Weisbach. For example when using the Hazen-Williams friction method, a total headloss is seen in the results of each pipe and MSX uses that to reverse-calculate the friction factor in case the Ff term needs to be referenced. This is similar to what HAMMER does, as seen here.
Example
To better understand the use of the TERMS feature along with some other important functions we have an example in which a chlorine decay analysis needs to be performed for different flow regimes (laminar, transition and turbulent) based on the Reynold’s Number (Re).
In this case the mass transfer coefficient (Kf) has a different formula for each of the flow regimes and each of these formulae need to be included as separate terms.
The key to the application of different formulae to different value ranges of Reynolds Number, or indeed different value ranges of any different kind of variable is the STEP(x) function in MSX. An example of its usage is given on page 62 of the EPANET MSX 1.1 User Manual, and it is described on page 63.
Note: This is simply a demonstration of the use of the STEP function to define the terms required. The actual equations for decay and the associated parameters might be different for different use cases or studies.
The step function works as follows;
Let's say that you had 3 flow regimes (laminar, transition and turbulent) that you wish to consider;
1. Re <= 1.0e5
2. 1.0e5 < Re <= 1.0e7
3. Re > 1.0e7
You can apply different sets of reaction equations subject to these three regimes.
First to capture the different flow regimes, you could define new TERMS as follows.
[TERMS]
FR1 STEP(1.0e5 - Re) ; Re <= 1.0e5
FR2 STEP(1.0e7 - Re) * (1 - FR1) ; Re <= 1.0e7
FR3 STEP(1.0e9 - Re) * (1 - FR2) ; Re <= 1.0e9
FR1M FR1
FR2M FR2 * 10
FR3M FR3 * 25
The first three terms (FR1, FR2, and FR3) are the flow regimes. These terms evaluate to “1” or “0” depending on whether the pipe flow is within the defined range of Reynolds Number (Re). These could be used directly to turn “On" (or “Off”) different parts of a decay equation thus enabling the ability to define reaction rates that involve different equations for different flow regimes.
The second three terms (FR1M, FR2M and FR3M) are simply terms (multipliers) that are created to demonstrate that the previous three terms work as expected. We will see how this works in a moment.
Note: In this case you could have separate equations for the different flow regimes which can be used in the formula below. You would need write the actual equations you wish to use and apply them to the ranges of Reynolds number that you deem relevant to your system.
To implement the regimes in the equations you simply write equations that leverage the previous terms. (For this example the FR1M, FR2M and FR3M terms; if you have separate equations for each flow regime then the FR1 FR2 and FR3 terms).
[PIPES]
;Free chlorine decay
RATE CL2 FR1M*(-Ks20*TC*Cs*CL2-Kf20*TC*Cf*CL2-Km20*TC*Cm*CL2) + FR2M*(-Ks20*TC*Cs*CL2-Kf20*TC*Cf*CL2-Km20*TC*Cm*CL2)+ FR3M*(-Ks20*TC*Cs*CL2-Kf20*TC*Cf*CL2-Km20*TC*Cm*CL2)
In the above equation we are modifying the CL2 decay rate for pipes subject to the flow regime.
The equation above, simplified is:
RATE CL2 FR1M*Const + FR2M*Const + FR3M*Const, where “Const” is the result of all the terms that define the decay rate. Since we are using the same equation;
Const = -Ks20*TC*Cs*CL2-Kf20*TC*Cf*CL2-Km20*TC*Cm*CL2
In this example we are using the same equation for each multiplier and increasing the decay rate by a factor, but for your case you can simply use the multipliers of 0 and 1 (obtained by evaluating FR1, FR2, FR3) to turn “On” / “Off” parts of the decay rate equation that do not apply to the specific flow regime.
The outcomes of the above equation are now given as;
If the flow regime is such that Re < 1.0e5, then the decay rate is 1*Const.
If the flow regime is such that Re > 1.0e5 and Re <= 1.0e7 then the decay rate is 10*Const
If the flow regime is such that Re > 1.0e7 and Re <= 1.0e9 then the decay rate is 25*Const
In other words, the higher the value of Re (subject to the stepwise evaluation within the defined ranges), the higher the decay rate.
These may not be the specific equations you would want to implement, but it's illustrating the underlying mechanism by which anyone can do it, subject to an arbitrary number of different ranges in Reynolds number (or any other variable or term) and making it easy to clearly demonstrate that it works (by exaggerating the effects).
When the above equations are run in a model that uses the following combinations of multipliers
FR1M = 1, FRM2 = 10, FRM3 = 25
FR1M = 1, FRM2 = 10, FRM3 = 50
FR1M = 1, FRM2 = 25, FRM3 = 50
It easy to see that the decay in the modeled system in the test model does vary depending on the defined factors, and thus varies depending on the decay function applied for the specific flow regime under consideration. In other words the evaluation of the step function is working as intended.
With the above approach you can see the use of the STEP(x) function within TERMS which can be applied to a similar use case.
Using Multi-Species Extension (MSX) for advanced water quality modeling
Related Forum Post : How to include Mass Transfer Coefficient into MSX