1. Home
2. Knowledge Base
3. Fixing HEC-RAS Modeling Problems

# Fixing HEC-RAS Modeling Problems

## Introduction

An unstable numerical model is one in which either the types and quantity of numerical errors grow to the point that the solution begins to oscillate, or the errors become so large that the computations can no longer be performed. This is a problem that is fairly typical of unsteady flow models of variable size or complexity.

In order to develop a good unsteady flow model of a river system, the user must understand the factors that often lead to unsteady flow equation solutions. Therefore, the objective of this article is to provide information on how to find, detect, and fix model stability problems using the tools in the CivilGEO software.

## Detecting Model Stability Problems

One of the hardest things about working with an unsteady flow model is getting the model to be stable as well as accurate for the range of events to be modeled. When the user first starts putting together an unsteady flow model, the software will likely run into some stability problems.

The following is a list of common stability problem indicators:

• Program stops running during the simulation with a math error, or states that the matrix solution went unstable.
• Program goes to the maximum number of iterations for several time steps in a row with large numerical errors.
• Program generates unrealistic oscillations in the computed stage and flow hydrographs or in the water surface profiles.
• The computed error in the water surface calculation is very large.

### What to Do When a Stability Problem Occurs?

The following steps should be taken when the stability problem occurs:

1. Note the simulation time and location from the computation window when the program either blew up or first started to go to the maximum number of iterations with large water surface errors.
2. Use the HEC-RAS Profile and Cross Section Plots as well as the Tabular Output to find the problem location and issue.
3. If you cannot find the problem using the normal HEC-RAS output, turn on the Write Computational Output File option in the Detailed Output panel of the Unsteady Flow Computational Options command.
4. View the time series and profile output associated with the Detailed Output computations. Locate the simulation output at the simulation time when the solution first started to go bad.
5. Find the river station locations that did not meet the solution tolerances. Then check the data in this general area.

## Computational Window

The Computational Window is the first place to look for problems:

• When the maximum number of iterations is reached, and the solution error is greater than the predefined tolerance, the time step, river, reach, river station, water surface elevation, and the amount of error is reported.
• When the error rate increases too much, the solution will stop and say that the Solution Solver Failed.
• Usually, the first river station to show up on the window will give clues to the source of instabilities.

An example of the Computation Window with an unstable model solution is shown below.

In this Computations Window, the red progress bar indicates the point at which the model became unstable and could not complete the simulation. The Computation Messages window provides a running dialog of what is happening in the simulation at a given time step in each location. This allows the user to watch as errors occur during the simulation. Once the simulation has crashed, don’t close the Computations Window. Rather, scroll up through the messages and try to find where the series of errors begins to accelerate and at what time.

Sometimes the first error that occurs at the beginning of the simulation is a result of the model settling out after the transition from initial conditions to the first-time step. Mainly this kind of error only occurs once for that given river station. Focus on reoccurring or compounding errors first. Note that the relatively small, isolated errors are generally not problematic.

## Utilizing the Profile Plot

The profile plot is typically the first graphical tool used to identify problem areas. Visible errors are shown distinctly in this plot, and you can see what is going on in the entire reach at the same time. Stepping through each profile using the animation tool allows you to see changes over time, including the progression of the flood wave as well as the initial appearance and frequency of errors.

To display the Animation Control dialog box, select Animate from the Options menu in the Profile Plot.

The profile output is taken from the detailed output file. Therefore, it is sometimes necessary to refine the detailed output interval to effectively see the beginning of instabilities. The profile plot allows the user to click on a given node to determine its river stationing. Find the node where the instability occurred first and then investigate further.

## Computational Level Output for Debugging

In the CivilGEO software, the Write Computational Output File section of the Unsteady Flow Computational Options dialog box helps users to find the source of model stability problems. The user can optionally enable this section to view output at the computation interval level when performing an unsteady flow analysis using the Unsteady Flow Computational Options command. This is accomplished by checking the checkboxes in the Write Computational Output File section.

The Write Computational Output File section allows the user to write out a limited list of variables at the computational time step level. This is a very useful tool for assisting in debugging an unsteady flow model. It is often very helpful to see a few output variables, like water surface and flow, at the detailed computational time step scale in order to see when and where a model is going unstable.

### Time Series Plots

The software allows the user to request various types of output, such as water surface elevation, velocity time series, and flow depth time series along the time series nodes.

The Time Series Plot command is used to view computed results for user-defined time series nodes. These time series nodes are used in the software for generating a time series plot and the time series data at that node. The time-series data are helpful for calibrating a model and are required for optimization.

### Viewing Stage and Flow Hydrographs

If the user has performed an unsteady flow analysis, then stage and flow hydrographs will be available for viewing. The software can generate stage and flow hydrographs of the HEC‑RAS unsteady flow computational results for various node types, such as Bridges/Culverts, Inline Structures, Lateral Structures, and Storage Areas.

## Utilizing the Cross Section Plot

Using the cross section plot, the user can identify isolated problems such as incorrect bank station locations, incorrect manning’s n values, and incorrect station-elevation points. It also helps identify transition problems such as contraction and expansion areas, ineffective flow areas, and levees.

The software can generate cross section plots of the HEC‑RAS steady flow and unsteady flow computational results, displaying the water surface elevation, energy gradeline elevation, critical depth elevation, as well as a velocity distribution plot on the cross section.

## Profile Summary Tables

Sometimes visual clues are not available. In such situations, tabular outputs are a great help for the users to identify problems. Tabular output allows the user to display large amounts of detailed information in a concise format.

Profile summary tables are one of the tabular outputs used to show a limited number of hydraulic variables for several cross sections. The Summary Outputs command allows the user to display the HEC-RAS profile summary table.

To display this table, select the Summary Output command from the Results ribbon menu.

The HEC-RAS profile summary table will be displayed.

Several standard table (Std. Tables) types are available to the user. Some of the tables are designed to provide specific information on hydraulic structures (for example, bridges and culverts), while others provide generic information at all cross sections.

To change the profile summary table to the desired tabular output, select the Std. Tables menu, and then choose the desired table option from the list. The software will then display the desired profile summary output. By default, the Standard Table 1 type of table is displayed. This table gives a summary of some of the key output variables.

The following standard table types are available to users:

• Standard Table 1 (default)
• Standard Table 2
• Four XS Culvert
• Culvert Only
• Six XS Bridge
• Bridge Only
• Bridge Comparison
• Multiple Opening
• Four XS Inline Structure
• Inline Structure
• Lateral Structure
• Encroachment 1
• Encroachment 2
• Encroachment 2
• HEC-FDA
• Ice Cover
• Junctions
• Storage Area
• Conn with Culverts
• Conn with Weir and Gates
• Pump Stations

Note that the user can view the profile summary output table in either US unit system or metric (SI) unit. The user can select the desired unit system from the Options backstage page. Refer to this article in our knowledge base to learn more about setting the model units to metric (SI) or US units.

## Detailed Output Tables

Detailed output tables are another basic type of tabular output that show hydraulic information at a single location for a single profile. The Detailed Output command allows the user to display the HEC-RAS detailed output table. To display this table, select the Detailed Output command from the Results ribbon menu.

The HEC-RAS detailed output table will be displayed.

By default, this table displays the detailed output for cross sections. The user needs to select the appropriate river, reach, and river station from the dropdown combo boxes provided at the top of the table to display any cross section in the table. The computed profiles can be displayed by selecting the desired profile in yearly format from the Profile dropdown combo box. Additionally, different plans can be viewed by selecting a plan from the Plan dropdown combo box.

The user can also view detailed hydraulic information for other types of nodes. Select the Type menu provided on the detailed output table window to select the desired table type.

The following table types are available in the Type menu:

• Cross Sections (default)
• Culvert
• Bridges
• Multiple Openings
• Inline Structures
• Lateral Structures
• Storage Areas
• SA/2D Connections
• Pump Stations
• Flow Distribution in Cross Sections

## Turning on Detailed Log Output for Debugging

If the user detects a possible stability problem, and is unable to find the location using the graphical output discussed above, the detailed log output for debugging is another option for finding the location of the problem. The detailed log output can be turned on by checking the Detailed log output for debugging checkbox in the Detailed Output panel of the Unsteady Flow Computational Options command.

This checkbox option can be used to control the detailed output of results from the unsteady flow simulation. This option is useful when the unsteady flow simulation is becoming unstable or completely blowing up (stopping).

### Viewing Detailed Output

The Detailed Output panel of the Unsteady Flow Computational Options dialog box helps the user find model stability problems. To pinpoint stability issues, the user can generate a computational output file and/or a detailed log output file.

#### DSS Output

The DSS Output shows all the hydrograph data that will be used as input to the model, including data read from HEC-DSS. For any project, the DDS output file gets stored in the folder containing the project.

The CivilGEO software provides some default computational options and tolerances for unsteady flow models. The tolerances are used in the solution of unsteady flow equations. In general, it is recommended that the default computation options and tolerances be maintained. However, the user can override the default computational options to achieve model stability while maintaining computational accuracy. Extra care should be taken while overriding the default calculation tolerances, as it could result in computational errors in the water surface profile.

Using the Unsteady Flow Computational Options command, the user can implement the following computational options for detailed unsteady flow calculations:

• Job control parameters
• Initial conditions calculations
• Detailed output for each time step

#### Table Output

The Table Output represents the final computed hydrographs that are written to HEC-DSS. The program lists the computed initial conditions from a backwater calculation for each of the rivers/reaches. These conditions are listed in the order they were computed during the backwater analysis, which is downstream to upstream.

An example of the initial conditions output is shown below.

During the unsteady flow computations, the program will output detailed information for cross sections, bridges/culverts, inline weir/spillways, lateral weir/spillways, storage areas, and storage area connections. This information should be reviewed closely when the software is having stability issues.

An example of the detailed output for cross sections is shown below.

When the program has stability problems, it will generally try to solve them by iterating. For example, in a few cases, the program iterated to the maximum number of iterations. By default, the number of iterations is 20.

A warning message will appear at the end of the iterations, stating, WARNING: USED COMPUTED CHANGES IN FLOW AND STAGE AT MINIMUM ERROR. MINIMUM ERROR OCCURRED AT ITERATION XX. This message means that the program could not solve the unsteady flow equations to the required tolerance within the specified number of iterations. Therefore, the program used the iteration that had the least number of errors in the numerical solution.

Another way to find and locate potential stability problems with the solution is to do a search in the file for the word WARNING. The user must then carefully examine the detailed output to detect where and why the solution is failing.

Following is a list of variables that are printed out during the iterations:

• Iter = Iteration number
• River = The name of the river in which the largest stage error is occurring
• Station = River station with the largest error in the calculated stage
• Elev = Computed water surface elevation at that river station
• DZ = The Numerical Error in the computed stage at that location
• Storage = Name of the storage area
• Zsa = Computed elevation of the storage area
• Dzsa = The Numerical Error in the computed storage area elevation
• Q = Computed flow
• DQ = The Numerical Error in the computed flow at the listed river station

After the iterations output, the program will show the computed stages and flows for all the cross sections in which the user has selected to have hydrographs computed. This is also useful information for detecting model stability problems. It is not always clear which cross section or modeling component is causing the problem. Sometimes the program may blow up at one cross section, but the real problem is caused by a cross section upstream or downstream from this location.