Engine Compatibility Mode and related Calculation options

Applies To 
Product(s): WaterGEMS, WaterCAD, HAMMER
Version(s): CONNECT Edition, V8i SELECTSeries 2 and greater
Area:  Calculations
Original Author: Kathy Wiggins, Technical Support, Wayne Hartell, Advisory Software Engineer, Tom Walski, Bentley Fellow


The purpose of this article is to explain the engine compatibility modes and related advanced calculation options.

These have been added to Bentley WaterCAD/WaterGEMS/Hammer V8i SelectSeries 2 (SS2). Additional information may be found in the Help menu of each program.


Starting with V8i SELECTseries 2, the ability to switch between two different versions of the EPANET and Bentley-Enhanced numerical solvers was introduced. This allows the user to provide results directly compatible with a certain version, for example when exporting back to EPANET. Newly created models will default to the Bentley-Enhanced 2.00.12 version of the EPANET solver. Previous models will retain the solver version used by the version they were last saved in . 

Four additional calculation options are available when using the 2.00.12 numerical solver version, as seen under the ‘Hydraulics’ section of the Calculation Options dialog. Each option will be covered in detail below.

See further below for a more detailed background.

Engine Compatibility Modes

The ‘Engine Compatibility’ Calculation option in V8i SS2 replaces the ‘Use EPANET Compatible Results?’ option, as seen in V8i SELECTSeries 1 and earlier. When set to true, you were using EPANET 2.00.10. The software now includes compatibility modes, to choose between  EPANET 2.00.10, as well as the revised engine changes in EPANET 2.00.12.


The four engine compatibility modes available:

WaterGEMS 2.00.12 – this engine is based on the EPANET 2.00.12 engine, including Bentley modifications. Choose this option to get all the latest engine improvements and fixes made by Bentley and an engine mode that is based upon EPANET 2.00.12.This is the default for new models. Meaning any new model created in WaterGEMS V8i SS2 will default to the ‘WaterGEMS 2.00.12’ engine compatibility option.

WaterGEMS 2.00.10 – this engine is based on the EPANET 2.00.10 engine, including Bentley modifications. Choose this option to maintain compatibility with previous versions of WaterGEMS (meaning V8i SS1 and earlier) where the computational engine is based upon EPANET 2.00.10. This is the default for upgraded (existing) models. Note: the ‘Use Linear Interpolation for Multi Point Pumps?’ option is FALSE by default in existing models as well. These default options are designed to make the transition smoother for users.

IF an existing model has ‘Enable EPANET Calculation Results?’ set to TRUE, then the ‘Use Linear Interpolation for Multi Point Pumps?’ option is hidden (as it will not apply).

EPANET 2.00.12 – models run using this engine have results that are compatible with EPANET 2.00.12. If choosing a version of the EPANET engine, any enhancements, calculation corrections, bug fixes, etc. made by Bentley will be disabled to match the specific EPANET version results. Imported EPANET models will default to the appropriate EPANET version.

EPANET 2.00.10 – models run using this engine have results that are compatible with EPANET 2.00.10.

Should the EPANET solver and the WaterGEMS/CAD solver give the same results for a model?

Note: The following engine compatibility matrix is included in the Help file (Modeling Capabilities>Calculation Options>Engine Compatibility Calculation Option).

Additional Calculation Options

If the user has selected either the WaterGEMS 2.00.12 or EPANET 2.00.12 versions, there are three additional calculation options now available. These options are the same for both the EPANET and WaterGEMS 2.00.12 engines.


Convergence Check Frequency – The Convergence Check Frequency option sets the number of solution trials that pass during the hydraulic balancing before the status of pumps, check valves, flow control valves (FCV) and pipes connected to tanks are once again updated. The default value is 2 (meaning that status checks are made every other trial). A value equal to the maximum number of trials would mean that status checks are made only after a system has converged. The frequency of status checks on pressure reducing (PRV) and pressure sustaining valves (PSV) is determined by the Damping Factor option.

Convergence Check Cutoff – The Convergence Check Cutoff option is the number of solution trials after which periodic status checks on pumps, check valves, flow control valves (FCV) and pipes connected to tanks are discontinued. Instead, a status check is made only after convergence is achieved. The default value is 10 (after 10 trials, instead of checking status every “convergence Check Frequency” trials, the status is only checked after convergence is achieved).

Damping Limit – The Damping Limit is the accuracy value at which solution damping and status checks on PRVs and PSVs should begin. Damping limits all flow changes to 60% of what they would otherwise be as future trials unfold. So, instead of checking the status of control valves at every iteration (which could result in oscillations in some cases) damping relaxes that check to only occur when the relative flow change is getting close to the target accuracy (e.g., 0.01, versus 0.001). The default value is 0 (zero), which indicates that no damping should be used and that status checks on control valves are made at every iteration. Damping might be needed on networks that have trouble converging. A limit of 0.01 is suggested (relative to the default calculation hydraulic accuracy of 0.001). See further below for a more detailed explanation.

Additional Post Calculation Warnings

Post Calculation warnings have been added to advise a user if they are using any features that are NOT supported by EPANET when they are running with one of the two EPANET compatibility settings. These are POST calculation and will not be displayed when validating a model (i.e. these calculation warnings are only displayed when computing a model.

Detailed Background

The hydraulic engine upon which the WaterGEMS and WaterCAD numerical engine is based, is the US EPA's EPANET v2.

EPANET v2 was originally developed in the late 90's (first released to the public in 2000) and was actively developed by the US EPA until 2008. During those years, changes were made to the computational engine by the US EPA in response to feedback from users. In the history of the engine development there were and continue to be (as of this writing in August, 2016) two main stable release points as follows.

EPANET 2.00.10, released 6/24/2002.
EPANET 2.00.12, released 2/25/2008.

That is, EPANET 2.00.10 was the result of 2 years of public feedback that stood un-modified for 5 years until 2007, and EPANET 2.00.12 has been the standard since 2008. EPANET 2.00.12 was the release that included a parameter for controlling the damping limit, Convergence Check Frequency and Convergence Check Cutoff.

You will note corresponding to the above stable releases, that in WaterGEMS, we support an engine compatibility setting, that has four possible options as follows:

1. EPANET 2.00.10
2. EPANET 2.00.12
3. WaterGEMS 2.00.10
4. WaterGEMS 2.00.12

The meaning of these four settings, in the same order as listed above, is:

1. An engine closely based upon EPANET 2.00.10. This engine attempts to match the result obtained by EPANET 2.00.10.
2. An engine closely based upon EPANET 2.00.12. This engine attempts to match the result obtained by EPANET 2.00.12.
3. An engine based upon EPANET 2.00.10, but with corrections and enhanced features.
4. An engine based upon EPANET 2.00.12, but with corrections and enhanced features.

In reality, it is always the same computational engine behind the scenes, but the compatibility setting changes the way the engine behaves in accordance with the above descriptions. The words "attempts to" (for cases 1 and 2) means that the engine version will faithfully reproduce any known computational errors that exist in the corresponding EPANET version in order to match the EPANET results of the same version. For that reason, you would only want to use an EPANET compatibility mode in the case you are exporting to EPANET and wish to match hydraulic results with that version of EPANET. The words "based upon" (for cases 3 and 4) could also, for most intents and purposes, be interpreted as "using the convergence strategy of".

One of the more significant changes made between EPANET 2.00.10 and 2.00.12 was to alter the convergence strategy used for control valves. This was presumably in response to cases (models) where the previous strategy was unable to solve correctly. Cases that could not solve would typically manifest in unbalanced calculations where pairs of control valves would oscillate. 

The convergence strategy was modified in a number of ways.

One modification was to initialize control valves to ACTIVE (versus explicitly starting only PRVs and PSVs as OPEN). The EPANET 2.00.12 based mode does this in comparison to the EPANET 2.00.10 based mode, but otherwise there is no effect on starting point (other than the continued fact that the solution for one time-step in an EPS run forms the starting point for the next time's simulation). Or in other words, the EPANET 2.00.10 based engines use a different starting point to the EPANET 2.00.12 based engines, but changing engine options does not affect starting point.

Another modification to the convergence strategy is that the concept of damping (2.00.11) and a damping factor (2.00.12) was introduced, in order to assist with the convergence of problematic models. The change was simply to no longer check the status of control valve every iteration (which could result in oscillations in some cases) and to relax that check to only occur when the relative flow change is getting close to the target accuracy (e.g., 0.01, versus 0.001). In EPANET 2.00.11 the damp limit was fixed at ten times the hydraulic accuracy, however, in EPANET 2.00.12 it was exposed to allow the user to change it (and it defaults to OFF (0) in that case, which reverts to the same case as EPANET 2.00.10, unless a user wishes to enable it).

Regarding the Damping Limit, one must first understand why the damping is in place, and not some other kind of modification. The computational engine essentially solves one linear continuity equation for each node and one non-linear energy equation for each loop. Since the equations are non-linear, an iterative method must be used. Once the equations are set up, the solution converges very efficiently, however, once a control valve changes status, the equations themselves change. Thus, the computational engine is "shooting at a moving target", so to speak. In order to help the equations to stay stable for a while, the damping comes into play. Too much damping, however, can slow down the process. So damping affects the convergence checks that are made on valves and then the subsequent flow changes applied to all hydraulic links, by reducing the magnitude of the flow changes. The damping option aims to allow the solution to converge to within a reasonable level before checking control valve status, and then when it has converged to within a certain value, to smooth out the effect of oscillating valve status changes and improve the final convergence in such situations. As an analogy, think of the damping as something similar to tweaking the feedback amplifier in a feedback control system. The damping tries to avoid overshoot.

In so far as computed results go, the main factor here is the specified hydraulic accuracy. Valve statuses are checked for the converged solution so using damping should not affect the result in that way; it's merely a means to improving the ability of the algorithm to find a valid solution.

Converged results achieved with different calculations in play are not guaranteed to be exactly the same since the results in part may depend on the path taken to convergence, however, the default hydraulic accuracy value normally means that for most practical purposes and systems that results do not significantly vary (by any appreciable value in an engineering sense). You may wish to perform a sensitivity analysis on your model with varying hydraulic accuracy to see whether the model you have built solves well with the default hydraulic accuracy, or whether a tighter value is required (at the potential trade-off of more hydraulic trials).

With that said, you should adopt the set of calculation options that results in consistent and stable convergence, and if that is not readily obtainable, then you should seek to eliminate the causes of such stability issues from the model itself.

See Also

Drawbacks of Using Damping Limit?

Troubleshooting "Network Unbalanced" or "Cannot solve network hydraulic equations" user notification