Troubleshooting options

00:03

In ICM, there are several tools to help you troubleshoot and fix simulation issues,

00:10

whether they are poor performance, erroneous results, or simulations that fail to complete.

00:16

Once a simulation is run, the color-coded icon displayed next to the simulation in the database indicates its status.

00:24

If your simulation has failed and has the red X icon, this is usually an IT or hardware issue.

00:32

The log report will detail the problem and may indicate how the issue can be resolved.

00:38

Troubleshooting options are available for when you encounter yellow and pink icons, specifically.

00:44

A yellow icon means a simulation has completed, but with warnings.

00:50

A pink icon means a simulation has failed to complete due to non-convergence.

00:54

The most powerful tool for troubleshooting a model is the diagnostic timestep log.

01:01

This can be activated via the Diagnostic button in the Run window, but is disabled by default, as it can generate extremely large files.

01:10

If your simulation fails with diagnostics disabled,

01:14

you can enable it and re-run the simulation to fully understand the extent of the problem.

01:19

The timestep log details each timestep halving and the location of the last non-convergence related to the 1D engine.

01:27

For a 2D model, the 2D timestep and location of the minimum timestep is also output.

01:34

If you are trying to troubleshoot RTC, then enable those additional options to investigate why it is not operating as expected.

01:42

If the RTC is large or complex, the log file can become somewhat overwhelming.

01:48

Therefore, it is often easier to troubleshoot RTC in a smaller cutdown model that you generate.

01:54

The log report provides a summary of the failure and unconverged locations in a table once the simulation is complete.

02:02

These can be useful to target high-impact locations, but use caution.

02:06

You are mainly interested in the causes of timestep halving around each point of failure,

02:11

and many of these locations may not account for those.

02:14

Resolving them, where possible, may speed up the simulation.

02:19

The most important areas to inspect and note the location of are the timestep logs immediately prior to the failure.

02:26

You can then inspect these objects to try to understand why the calculation is failing to converge.

02:31

Possible issues may relate to erroneous data or inappropriate headlosses being applied.

02:38

While simulation failure may be a result of the 1D engine, the problem may stem from the connection with the 2D domain.

02:46

Inside the log report, general 2D volume balance information is provided.

02:52

This can be inspected to see if there are any large discrepancies between total inflow into the model and the total outflow plus storage.

03:00

If there is a discrepancy, this indicates that the connection between the engines is producing considerable volumes of flow.

03:08

This should be investigated as it could produce incorrect results.

03:12

When the 1D and 2D elements have been connected at nodes, an engine check looks at the volume in the element.

03:19

A correction prevents more flow from entering the node than is available,

03:24

and this is reported as flow limiting in the node results grid window, with columns indicating the duration and total volume.

03:32

You should only be concerned by significant volumes, although it is a good idea to check the flow graph for instability.

03:39

The initialization phase is important for a river model.

03:43

Due to the scale of rivers over pipes,

03:46

steady state thresholds can sometimes be too large for a river model, and the simulation initializes prematurely.

03:53

You can see if this has occurred by inspecting the duration of the initialization in the log results report

03:59

or checking the outflow from the model at the start of the simulation.

04:03

In this example, the model took just over 3 hours to initialize, which was not sufficient to fill the river reaches.

04:11

The effect of this is seen on the graph.

04:14

The inflow starts to come into the model at the start of the simulation, displayed as the blue line.

04:20

The outflow from this reach does not start for almost 8 hours, as indicated by the green line.

04:26

This is because the river reach is still filling during that period of the simulation.

04:31

This would render your simulations inaccurate, as the peak flows and available storage are all affected.

04:37

There are options available to overcome potential initialization issues.

04:42

The initial conditions object could be used to backfill sections of river reach.

04:47

You may need to prime the hydrology so that you have higher starting inflows, which would, in turn,

04:53

give you a more appropriate initialization final state.

04:56

Another option is to manually generate the intended steady state via a separate simulation,

05:02

and then use this simulation instead of undergoing the initialization process.

05:07

There are also some simulation shortcuts that you can try for non-convergence.

05:12

If all other sensible modelling practices have been followed, you may have an inappropriate simulation timestep.

05:19

The default value of 60 seconds is appropriate for small, 1D-only models.

05:25

As model details expand, the starting timestep should be decreased.

05:30

Shown on the screen are some guidance timestep values.

05:33

Other issues may be related to steep pipes in combination with high headlosses,

05:38

which can cause inappropriate calculations.

05:41

For more hints and tips, check out this blog post:

Video transcript

00:03

In ICM, there are several tools to help you troubleshoot and fix simulation issues,

00:10

whether they are poor performance, erroneous results, or simulations that fail to complete.

00:16

Once a simulation is run, the color-coded icon displayed next to the simulation in the database indicates its status.

00:24

If your simulation has failed and has the red X icon, this is usually an IT or hardware issue.

00:32

The log report will detail the problem and may indicate how the issue can be resolved.

00:38

Troubleshooting options are available for when you encounter yellow and pink icons, specifically.

00:44

A yellow icon means a simulation has completed, but with warnings.

00:50

A pink icon means a simulation has failed to complete due to non-convergence.

00:54

The most powerful tool for troubleshooting a model is the diagnostic timestep log.

01:01

This can be activated via the Diagnostic button in the Run window, but is disabled by default, as it can generate extremely large files.

01:10

If your simulation fails with diagnostics disabled,

01:14

you can enable it and re-run the simulation to fully understand the extent of the problem.

01:19

The timestep log details each timestep halving and the location of the last non-convergence related to the 1D engine.

01:27

For a 2D model, the 2D timestep and location of the minimum timestep is also output.

01:34

If you are trying to troubleshoot RTC, then enable those additional options to investigate why it is not operating as expected.

01:42

If the RTC is large or complex, the log file can become somewhat overwhelming.

01:48

Therefore, it is often easier to troubleshoot RTC in a smaller cutdown model that you generate.

01:54

The log report provides a summary of the failure and unconverged locations in a table once the simulation is complete.

02:02

These can be useful to target high-impact locations, but use caution.

02:06

You are mainly interested in the causes of timestep halving around each point of failure,

02:11

and many of these locations may not account for those.

02:14

Resolving them, where possible, may speed up the simulation.

02:19

The most important areas to inspect and note the location of are the timestep logs immediately prior to the failure.

02:26

You can then inspect these objects to try to understand why the calculation is failing to converge.

02:31

Possible issues may relate to erroneous data or inappropriate headlosses being applied.

02:38

While simulation failure may be a result of the 1D engine, the problem may stem from the connection with the 2D domain.

02:46

Inside the log report, general 2D volume balance information is provided.

02:52

This can be inspected to see if there are any large discrepancies between total inflow into the model and the total outflow plus storage.

03:00

If there is a discrepancy, this indicates that the connection between the engines is producing considerable volumes of flow.

03:08

This should be investigated as it could produce incorrect results.

03:12

When the 1D and 2D elements have been connected at nodes, an engine check looks at the volume in the element.

03:19

A correction prevents more flow from entering the node than is available,

03:24

and this is reported as flow limiting in the node results grid window, with columns indicating the duration and total volume.

03:32

You should only be concerned by significant volumes, although it is a good idea to check the flow graph for instability.

03:39

The initialization phase is important for a river model.

03:43

Due to the scale of rivers over pipes,

03:46

steady state thresholds can sometimes be too large for a river model, and the simulation initializes prematurely.

03:53

You can see if this has occurred by inspecting the duration of the initialization in the log results report

03:59

or checking the outflow from the model at the start of the simulation.

04:03

In this example, the model took just over 3 hours to initialize, which was not sufficient to fill the river reaches.

04:11

The effect of this is seen on the graph.

04:14

The inflow starts to come into the model at the start of the simulation, displayed as the blue line.

04:20

The outflow from this reach does not start for almost 8 hours, as indicated by the green line.

04:26

This is because the river reach is still filling during that period of the simulation.

04:31

This would render your simulations inaccurate, as the peak flows and available storage are all affected.

04:37

There are options available to overcome potential initialization issues.

04:42

The initial conditions object could be used to backfill sections of river reach.

04:47

You may need to prime the hydrology so that you have higher starting inflows, which would, in turn,

04:53

give you a more appropriate initialization final state.

04:56

Another option is to manually generate the intended steady state via a separate simulation,

05:02

and then use this simulation instead of undergoing the initialization process.

05:07

There are also some simulation shortcuts that you can try for non-convergence.

05:12

If all other sensible modelling practices have been followed, you may have an inappropriate simulation timestep.

05:19

The default value of 60 seconds is appropriate for small, 1D-only models.

05:25

As model details expand, the starting timestep should be decreased.

05:30

Shown on the screen are some guidance timestep values.

05:33

Other issues may be related to steep pipes in combination with high headlosses,

05:38

which can cause inappropriate calculations.

05:41

For more hints and tips, check out this blog post:

Video quiz

Required for course completion

What does a yellow simulation result icon signify?

(Select one)
Select an answer

1/1 questions left unanswered

In ICM, there are several tools to help with troubleshooting and fixing simulation issues, whether they are poor performance, erroneous results, or simulations that fail to complete.

Once a simulation is run, the color-coded icon displayed next to the simulation in the database indicates its status:

A presentation slide with the meanings of each simulation icon, with a red “X” indicating failure, yellow indicating that there are warnings, and pink indicating that the simulation failed due to non-convergence.

The most powerful tool for troubleshooting a model is the diagnostic timestep log:

A presentation slide stating that the diagnostic timestep log, a powerful troubleshooting tool, is disabled by default due to the potential of large file size generation; with an image of the Diagnostics dialog.

The timestep log details each timestep halving and the location of the last non-convergence related to the 1D engine. For a 2D model, the 2D timestep and location of the minimum timestep is also output.

When trying to troubleshoot RTC, enable those additional options to investigate why it is not operating as expected. If the RTC is large or complex, consider troubleshooting RTC in a smaller cutdown model.

The log report provides a summary of the failure and unconverged locations once the simulation is complete:

A presentation slide with an image of a diagnostic timestep log; and stating that the main interest is the causes of timestep halving around each point of failure, and the most important locations to check are areas immediately prior to failure.

Possible issues may relate to erroneous data or inappropriate headlosses being applied.

While simulation failure may be a result of the 1D engine, the problem may stem from the connection with the 2D domain. Inside the log report, inspect general 2D volume balance for any large discrepancies between total inflow and total outflow plus storage. This indicates that the connection between engines is producing considerable volumes of flow and should be investigated.

When 1D and 2D elements are connected at nodes, an engine check looks at the volume in the element and makes corrections using flow limiting:

A presentation slide with information about flow limiting, a correction that limits the flow entering a node and is only concerning with significant volumes; with an image of the duration and total volume columns in a node results grid.

The initialization phase is important for a river model. Due to the scale of rivers over pipes, steady state thresholds can sometimes be too large for a river model, and the simulation initializes prematurely. Inspect the duration of the initialization in the log results report or check the model outflow at the start of the simulation. In the example below, the model took just over 3 hours to initialize, which was not sufficient to fill the river reaches. The river reach was still filling during a period of the simulation, rendering the simulations inaccurate.

A presentation slide of an initialization graph for a river model, showing inflow in cubic meters coming into the model at the start of the simulation, represented by a blue line, and outflow starting almost 8 hours later, represented by a green line.

To overcome potential initialization issues, the initial conditions object could be used to backfill sections of river reach. The hydrology may need to be primed so that the starting inflows are higher, resulting in a more appropriate initialization final state. Another option is to manually generate the intended steady state via a separate simulation, and then use this simulation instead of undergoing the initialization process.

There are also some simulation shortcuts for non-convergence. The issue may be an inappropriate simulation timestep. Shown below are some guidance timestep values:

A presentation slide with a table of guidance timestep values, with a suggested timestep of from 60 seconds to a minimum of 20 seconds for small, 1D models, and shorter timesteps as the model size increases.

Other issues may be related to steep pipes in combination with high headlosses, which can cause inappropriate calculations.

For more hints and tips, check out this blog post: Troubleshooting hydraulic models in InfoWorks ICM.

Was this information helpful?