Troubleshooting Hydraulic Models in InfoWorks ICM

Back to blog home

January 9, 2018 | Innovyze staff

We often get asked about troubleshooting models, and it’s often quite a difficult task to provide a good response, as much of troubleshooting is based on modelling experience of a range of models over a prolonged period of time…even then there are new things which crop up with either we’ve never seen or even thought of.  Anyway, I thought I would put together a few tips, things to look at when troubleshooting models.  This is by no-means an exhaustive list but is the type of approach I would take to troubleshoot a model.  I’ll focus on models which have successfully initialised as approaches to troubleshooting initialisation issues have been discussed elsewhere on this blog (Initialisation in InfoWorks CS).

Of course, troubleshooting a problematic, non-convergent model can be avoided by following best practice, providing sensible and well thought schematisation and using the validation errors/warnings to help the model process.  I also find it useful to build models iteratively, testing the model out at various stages, for instance as a 1D river model, before merging with a 1D urban drainage model before merging with a simple 2D mesh, before adding mesh detail.  It may be more time-consuming in the short term but my experience is that it helps solves many issues and speeds up the whole modelling process.  In fact whenever I get sent an integrated 1D-2D model, the first thing I do is ‘turn off’ the 2D, by setting bank discharge coefficients to 0 and all 2D nodes to sealed flood types, to check the 1D model works on its own.

Simulation Log Files

The first point that you’ll notice that a model is non-convergent will be the premature failure of the simulation and the simulation icon in the database tree will turn red.  I would advise reviewing the log file regardless of the simulation status.  With a non-convergent simulation you will still be able to open the results but the first step should always be to take a look at the simulation log file (Right click on the simulation icon Open As…Log Results text).  Scroll down to the bottom of the log file and you will see that final place that convergence failure occurred and the point the simulation ultimately failed.

Figure 1: Convergence Failure Message in Simulation Log File

In most situations it will be the locations noted here which are responsible for the simulation failure.

Occasionally, the point of the final convergence failure is not always the real cause of the simulation failure.  In the run dialogue, under diagnostics, is the option to turn on the Timestep log.

Figure 2: Timestep Log Diagnostics Option

Switch this on for an enhanced, and bigger (we recommend only using this option for troubleshooting as it can results in very large log files), simulation log file which provides convergence information for every timestep.  Towards the point of the simulation failure, there will most likely be a particular location which regularly appears within the convergence failure information.

Figure 3: Timestep Log Convergence Detail

Also, towards the bottom of the simulation log file will be a hit count of the link/node fail counts.

Figure 4: Timestep Log Node/Link Failure Count

It would be worth investigating a couple of the locations with the larger hit counts.

For 1D-2D models I would advise checking the volume balance error in the 2D summary log.  This should be close to 0%.  Where less than 5% this is usually considered acceptable.

Figure 5: 2D Volume Balance Summary

Where the volume balance error is greater than 5%, there is a list of locations with their associated mass error.  In nearly all cases these are associated with the 1D-2D interface.  They may also be accompanied by messages about river bank flow oscillations.  This is when flow oscillates from positive (flow from the river reach to the 2D zone) to negative (flow from the 2D zone back to the river reach).  Of course such oscillations can be natural, particularly where the count is small.  However, where the oscillations occur nearly every results timestep this is indicative of an instability propagating across the 1D-2D interface.

Figure 6: Simulation Log 2D Mass Balance Error Locations

Figure 7: Simulation Log River Reach Bank Oscillations

Results Grid

With the results open in the geoplan, it is possible to check both the volume balance on a node basis using the New Nodes Results Grid.  These can be sorted to find the largest volume balance errors.

Figure 8: Nodes Grid Results Window

Finally, look for any oscillations in results where flow modes may be rapidly changing.

Once the poor convergence has been identified, at this stage a number of users would start fiddling with simulation parameters to force convergence but I wouldn’t recommend this as quite often this will mask the issue and lead to other issues further down the line with different boundary conditions.  I would advise opening the results in the geoplan, find the location specified in the simulation log file and investigate both the model geometry and the results.  The following sections provide a number of typical reasons for simulation failures both within the 1D, both fluvial and urban drainage models, and 2D domains.

Run Timestep

In the large majority of cases, ensuring a timestep of 60 seconds or less and 10 seconds or less for 1D-2D simulations is recommended.  The run timestep you specify in the schedule simulation dialog is the 1D timestep.  The 2D timestep is determined by the Courant-Friedrich-Lewy condition (see the help topic ‘Basic 2D Hydraulic Theory’ for more detail).  By default the 1D and 2D engines will pass data at the run timestep provided in the schedule simulation dialog (known as the major timestep).  However, when the 1D engine fails to converge, it will halve the timestep and try to iterate to converge to a solution.  The timestep used is called the minor timestep.  Still, by default, the 1D and 2D engines pass data at the major timestep.  By ticking the option to ‘Link 1D and 2D Calculations at Minor Timestep’, where the 1D engine has timestep halvings, the 1D and 2D engines will pass data at this minor timestep. The option to ‘Link 1D and 2D Calculations at Minor Timesteps’ will ensure more interactions between the 1D and 2D models which can increase stability and reduce the volume balance error. Note that while this option can increase stability of models, it is not ticked by default because it can slightly increase run times.

Schematisation Issues

There are a large number of potential reasons for poor convergence and it would be impossible to go through all of them.  However, the following is some typical, and common examples, together with some approaches to address them.

The first common issue often manifests itself as an initialisation failure rather than a simulation failure but is worth pointing out here as it’s a regular one in the support inbox which is easily spotted and is due to poor schematisation, often where users have sampled bankline elevations from a ground model but are picking up the channel as represented in the ground model rather than the banks.  Figure 9 shows an example where the banklines are lower than the bed level of the river (thalweg). Often banklines can be low, but clearly this is very poor schematisation.

Figure 9: Poor Bankline Schematisation

In this situation the only resolution is improve the model schematisation of reality.

The next common issues large steps in the river reach long profile.  These can often occur at structures or confluences due to poor schematisation or conflicting survey data.   If the step occurs in reality, then any steps in the river reach profile typically greater than 1 in 10, should be represented as an irregular weir (or 1D inline bank).  If the step does not exist in reality then smoothing the transition should be considered.

Figure 10: Step in River Reach Long Section

This can also manifest itself in slightly different ways, such as soffit levels lower than downstream/upstream invert levels.

Figure 11: Poor Schematisation of Conduit Adjacent to River Reach

Related to this is outfalls from an urban drainage system into a river network with steep drops or poor schematisation. Occasionally due to differences in surveyed data, I’ve seen model networks with outfalls entering the river either below the bed level or out of the bank. The outfalls should connect to a break node within the river and the connecting conduit should have a downstream invert level between the river section invert level and the bankline (ie, in channel). The headloss type at the end of a sewer conduit connecting into a river should be set to either NONE or FIXED. NORMAL/HIGH headloss types are only appropriate at link ends connected to manholes.

Steep Pipes

One common one in the pipe networks is seemingly random simulation failures, often in locations where steep conduits are present. As a very general rule, removing headlosses for conduits (usually the upstream end) with a gradient greater than 0.1 (10%) can often help with convergence.

Lack of panel markers and conflicting panel markers

Occasionally the lack of panel markers can lead to poor convergence within the simulation. Also common is conflicting panel markers for adjacent identical river sections (ie, two river reaches connected at a break node or a bridge section and the adjacent river reach section) which leads to very rapid changes in the conveyance profiles. These would need improved representation.  You can use the tool “Conveyance graph pick” to plot several conveyance curves in the graph to do a direct comparison of adjacent curves.

Figure 12: Conveyance Graph for Multiple River Sections

Culvert Inlets/outlets

The invert elevation at the end of a culvert conduit connected to a culvert inlet/outlet should be at the same level as the culvert inlet/outlet. Similarly, the lowest invert on a reach connected to a culvert inlet/outlet should also have the same invert level as the culvert inlet/outlet.

The headloss type at the end of the culvert conduit connected to the culvert inlet/outlet should be set to NONE. This is because the inlet/outlet is meant to incorporate all the losses between the reach and the culvert. The only exception to this is if bend losses are to be included, in which case a FIXED headloss with an appropriate coefficient should be used. NORMAL or HIGH headloss types should not be used in this situation.

1D Structures in 2D

Quite often there is a requirement to represent structures within the 2D domain, for example an opening in a railway embankment or underpass for example. Quite often, these are represented using 1D conduits coupled to the 2D using 2D outfalls. These can be tricky to setup in a stable manner and we would recommend that the conduit invert level matches the 2D outfall ground level and the mesh element elevation at each of the ends of the conduit. The 2D Outfall level ground level can be inferred from the 2D mesh using the inference tool if required.

Ticking the option to ‘Link 1D and 2D Calculations at Minor Timesteps’ can also assist with the stability of these. Where a 2D outfall is used, the mesh element within which it resides should be large enough to contain the volume of flow which can enter the conduit, alternatively an inline bank could be used to represent a linear connection with multiple mesh elements. It is also possible to represent such structures in the 2d model directly using Base Linear Structures and Sluice/Bridge Linear Structures.

2D Initial Conditions…or lack of

The 2D engine itself is very stable. Most instabilities and poor convergence is associated with the 1D-2D interface. However, there have been instanced where users have applied a tidal level without the initial water level specified in the 2D domain, essentially applying a wall of water to the 2D domain.

River Banks

River reach banklines are often the interaction between the 1D and 2D domains (they can also be the interaction between 1D river reaches and other river reaches and storage areas).  The river reach banklines are often created from survey data.  The 2D mesh is often generated from ground models derived from aerial LiDAR.  With the best will in the world there is often a mismatch between the river reach bank levels and the 2D mesh element elevations adjacent to the banklines.  There are 2 options which can be used to manage the mismatch between the 2.  The first sits within the ‘Mesh 2D Zones’ dialogue.  This option allows you to ‘Lower 2D mesh element ground levels higher than adjacent bank levels’.  This will adjust the mesh data.

Figure 13: Mesh 2D Zones Meshing Option for Banklines

The other option resides in the 2D parameters part of the schedule simulation dialog, the ‘Adjust bank levels based on adjacent element ground levels’. This will adjust the bank levels which are lower than the adjacent mesh element elevations so that they match the mesh element elevations.

Figure 14: 2D Parameters Run Option for Banklines

In both instances, the correction is adjusted either the mesh element elevations or the bankline elevations where the mesh element elevation is greater than the bankline elevations. This is undesirable as flow could be generated artificially. In the case where the bankline elevation is greater than the mesh element elevation the bank elevations will control the spill from the river reaches to the 2D zone and vice versa.

Occasionally you may be faced with results which show flow oscillating over the river reach banklines. As has been suggested previously, using the correct run timestep and using the option to ‘Link 1D and 2D Calculations at minor timesteps’ can assist in reducing the oscillations. It may also be necessary to reduce the modular limit for the banklines. The modular limit is the ratio between upstream and downstream water levels used to determine whether the weir flow over the bank is drowned or free flow as described in the help page ‘River Reach – Bank Flows’. See particularly the conditions in equations 2 and 3. Typically a value of between 0.6 and 0.9 would be appropriate.

Another useful option is the bank linearization threshold. When calculating bank flow for a drowned spill segment, linearised flow equations will be used when the head difference at both ends of the segment is below this threshold. The concept of linearisation of the drowned bank equation is a mathematical procedure which was described by Cunge et al. in their ‘Practical Aspects of Computational River Hydraulics’ book to avoid the derivatives of the equation approaching infinity as the head difference approaches zero. The default of 0.01m is taken from their value of ε, where ε is the order of a centimetre. This has the effect of smoothing flows across a drowned bankline.

1D-2D Connection at nodes

At the 1D-2D node connection we have the node ground level and the mesh element elevation. In most situations these values should be the same as the manhole cover level would be at ground level. However, due to the differences in the way manhole cover levels are often surveyed, ground elevations are often taken from LiDAR data and the assignment of mesh element elevations as an average of the underlying ground model grid cell elevations often means there is a mismatch between the node ground level and the mesh element elevation. The transfer of flow between the 1D and 2D (and vice versa) is, by default, based on a transfer of depth. This is because mismatches between the manhole ground level and the mesh element level are usually not expected. The transfer of depth means any mismatch is ignored. This means that as long as there is depth in the 2D mesh element that the 2D node resides, there can be transfer of flow between the 2D and 1D domains even if the mesh element water surface elevation was lower than the node ground level.

There is an option in the simulation parameters to ‘Use 2D elevations instead of depth’ which transfers elevations instead of depths. This applies globally. It is also possible to this on a node-by-node basis using the 1D-2D Linkage field. The option would only really be used if the mismatch in levels is deliberate, ie, the manhole is a raised manhole. In this case the flow elevation is the 2D mesh element has to be larger than the node ground elevation in order for flow to enter the 2D manhole. The other common situation where this might be necessary is if you have a 1D pipe discharging (or draining) to a pond represented in the 2D domain. Usually the 2D mesh element elevation would be the bottom of the pond and the pipe outfall would be slightly higher. In this case there would be a deliberate mismatch between the levels and the ‘elevation’ option should be used. Without it, the depth of flow in the 2D mesh element would be applied to the pipe outfall regardless of whether the elevation was sufficient to interact with it.

Simulation Parameters

As a general rule we would not recommend changing the simulation parameters. Often, users will increase the number of timestep halvings and number of iterations from the default 10 to say 30. This results in a very small timestep being used to solve the equations. In most cases, this approach just masks other underlying issues with the schematisation.

The one simulation parameter which is often useful to reduce is the maximum space step. The simulation engine adds a number of computational nodes to conduits/river reaches to undertake the calculations. Results are not seen for these computational nodes. The computational nodes are added depending on the space step which is determined by the ‘Conduit Width Multiplier’. By default this is 20. A conduit with a width of 2m will have computational nodes at 40m intervals. There are also minimum space steps and maximum space step defaults (0.5 and 100m respectively). For river reaches, the maximum space step should not be greater than 1/(2S) where S is the river slope and not greater than 0.2D/S where D is the typical depth of flow. There may be some circumstances where the user may want to consider reducing the maximum space step. This is akin to adding global interpolates throughout the model. The downside is, with an increased number of computational nodes and subsequent calculations, the simulation time will increase.


This blog post goes through the InfoWorks ICM troubleshooting procedure and common things to look out for.  It is not exhaustive and focuses on simulation convergence rather than initialisation.  Many of the issues reported above could also lead to initialisation failures. A better schematised and convergent model should run quicker.  One potential reason why a model may still run slowly despite being convergent is due to small 2D mesh elements.  For this the user is referred to Tips & Tricks - Tips for a Good Meshing Experience.

Find out more

Contact us

Tags: modeling, timesteps, schematisation, panel markers

About the Authors

Innovyze staff

Innovyze staff

Innovyze team member


Innovyze staff include water engineers, modelers, mathematicians, developers, product managers, support specialists, licensing specialists, sales and sales support specialists, marketing and content creators, and many others.