How to troubleshoot instability in XPSWMM

source: Innovyze Support Portal

What is model instability?

Due to the explicit nature of the numerical methods used for Dynamic Wave routing (and to a lesser extent, Kinematic Wave routing), the flows in some links or water depths at some nodes may fluctuate or oscillate significantly at certain periods of time as a result of numerical instabilities in the solution method. SWMM does not automatically identify when such conditions exist, so it is up to the user to verify the numerical stability of the model and to determine if the simulation results are valid for the modeling objectives (Chapter 8.4 of EPA SWMM User Manual).

Time series plots at key locations in the network can help identify such situations as can a scatter plot between a link’s flow and the corresponding water depth at its upstream node. Numerical instabilities can occur over short durations and may not be apparent when time series are plotted with a long-time interval. When detecting such instabilities, it is recommended that a reporting time step of 1 minute or less be used, at least for an initial screening of results.

Common source of instability

Instability usually is the result of dramatic change in the calculation, common sources are,

Troubleshoot instability

First step is to identify the pipe or node that is causing the instability.

By tracing the instability upstream by checking the hydrograph we can quickly narrow down the areas that might cause it. Playing the HGL animation can also be a good way to quickly visualize the problem, the HGL will jump up and down at the nodes with instability issues.

Another way to quickly narrow down onto problematic nodes is to review table E8. Review junctions with very high number of not converged iterations, and total iterations, etc.

Due to the complexity involved in the numerical methods, troubleshooting instability is an iterative process of identifying possible sources.
Once the source is identified, we should go through this checklist,

We’ll discuss each of them in more details below.

Boundary condition

Challenging flow conditions

For example,

In some cases, instability will be the expected behavior, thus it is the modeler’s responsibility to adjust the model to support the design goals. Maybe the modeler should increase the losses of the pipe so that it stayed in the surcharge condition during the simulation, which will result a more conservative result.

Engine Settings

Sometimes, it could be the settings of the engine that is the source of the instability.

If the time step is too long to capture the flow changes, it could lead to instability issues. Sometimes a time step of 1 second might be needed. It should also be noted that too short a time step might also cause stability issues.

Using Table E7 in the 1D log we can get a report on the time steps. As shown in the example below, the average and smallest time step is 1 second, so a time step close to 1 second might be a better choice.

As shown below, the stability issue can be resolved by change the time step from 60 sec to 10 sec.

When a pipe length is shorter than the wave can travel in a time step, it can lead to instabilities. Adjust the time step or make the short pipe longer to avoid this situation.
If needed using Configuration Parameters to override default min. length and time step with MINLEN and MIN_TS.


Allows the user to set the minimum time step for the Hydraulics solution. The default is 1 second. Example, MIN_TS=0.2 will allow the program to lower the time step in the hydraulic solution down to 0.2 seconds if the simulation warrants that detail.


Change spatial conduit weighting to 0.50 upstream, 0.5 downstream. Default is 0.55 upstream, 0.45 downstream.

Alter the Preissmann Slot size to change the behavior when pipes are surcharged, WSLOT1 for example makes it larger


Slot width in the Preissmann slot = 0.005 × conduit width.

Note: The WSLOT is set by default, so the slot defaults to a 0.5% width.


Slot width in the Preissmann slot = 0.01 × conduit width.


Slot width in the Preissmann slot = 0.001 × conduit width.

You might also find overwriting default settings useful.

Empowering Water Experts