Tuesday, December 28, 2010

How to Create a Hotstart File in HEC-RAS for Dam Breach Analysis

Written by Aaron A. Lee   | WEST Consultants
Copyright © 2010. All rights reserved.
While running unsteady flow simulations in HEC-RAS instabilities may occur when transitioning from the automatically created initial condition file to the first computed time step. These instabilities can be caused by mixed flow conditions, flow splits, or poorly defined initial conditions. A hotstart is another option available for defining initial conditions for the project model. This article presents one technique for setting up a hotstart run to help with initial conditions problems and to troubleshoot problem areas in your project model.

This is done by creating a new plan, using a flow file with a constant discharge as the upstream boundary, and a stage hydrograph as the downstream boundary over a 24 hour period. Typically 24 hours is long enough, but you may find that a longer hotstart period is required. The downstream boundary water surface elevation is defined artificially high, and over the simulation it is gradually reduced until it reaches the true starting depth for your project model. At this point the hotstart file will be written by HEC-RAS. In HEC-RAS lingo, the term “hotstart file” is used interchangeably with “Restart File” and “Initial Conditions file”.

STEP 1. Create a new flow file by opening the current unsteady flow file and navigate to File, Save As, and name it “hotstart”. Once saved, change the upstream boundary condition by selecting Flow Hydrograph under the Boundary Conditions tab. Change the discharge to a constant flow equal to that of the first timestep for the 24-hr period. In this example, shown in Figure 1, the entire Flow column should be modified to contain 155 for the full 24-hr simulation.


Select Stage Hydrograph as the downstream boundary condition. The beginning stage should start at an artificially high elevation - somewhere near the invert of the upstream-most cross section. The final elevation at the end of the 24-hr simulation should be equal to the starting downstream water surface elevation of the project plan. Once these values are added into the Stage column, use the Interpolate Missing Values button to add the missing elevations.

The elevation at each time interval should gradually decrease. This makes it easier for the modeler to observe problems as they occur, and where they happen in the model. For this example, the starting elevation is 820 ft and the final elevation is 637.25 ft. This is shown in Figure 2. Save the “hotstart” flow file.

image STEP 2. Navigate to the Unsteady Flow Analysis window and save as a new plan named “hotstart plan”. Name the short ID as “hotstart”. This will create a new plan that will be used to define the initial conditions for the project plan. Under the Unsteady Flow Analysis window select the Ending Date and Time to 24 hours after the Starting Date and Time (or whatever time frame you want to use-just be sure it is consistent with the hotstart flow hydrograph and stage hydrograph you created in Step 1).

STEP 3. The next step is to set up the model so that the hotstart file will be written. Under the Unsteady Flow Analysis window navigate to Options, then Output Options. Figure 3 shows this window.


Check the boxes that write the initial conditions file at the Fixed Reference of the hotstart simulation ending date and time. At the end of the specified simulation time (24 hours) HEC-RAS will automatically write the initial condition file. The final step is to ensure that the hotstart plan is using the correct geometry file, and the created “hotstart” flow file. Once the plan is completed and saved, compute the Hotstart simulation.

STEP 4. The profile plot should be reviewed for problems with the hotstart model. This will indicate areas that may cause problems in your project model. Over the course of the hotstart simulation, as the water surface drops into place along your bed profile, look for hints of instabilities. If you hotstart simulation crashes, you’ll know exactly where to investigate-the intersection between the artificially high horizontal pool and the bed profile at the time of the crash. To use the hotstart file as your initial conditions, go to the Unsteady Flow editor of your project plan. Click on the “Use a Restart File” box and browse for the initial conditions file. This file will have an extension that indicates that hotstart plan number that created it, the simulation time (day-month-year) when it was created, and .rst. In this example, it should look like:


*Warning-If you make a change to the geometry in your project model, you’ll have to re-run your hotstart simulation. However, once everything is set up, this is very easy to do. Simply open the hotstart plan and run it. Then open the project plan and run it.


  1. This is a very helpful article, along with the many other articles you have written/posted on this site. Thank you!

  2. Thanks Nick. Glad it is useful to you.

  3. Excellent site. Hardly anything else out there like this. You should add tags to your posts, might optimize SEO and being able to find it easier. Great job, though, thanks for sharing.

  4. Thanks Anthony. Adding tags is a great suggestion. I'll do that from now on. In the meantime, you can use the search toolbar on the sidebar. But yes, tags will be better for SEO.

  5. Chris, how come we click both "write initial conditions...during" and "write initial conditions at end"? When you click "during", does it write it at the time that you specified?

  6. Bethann, yes, that was a little confusing. Sorry about that. You don't click both. It's either-or. If you click "write initial conditions...during", and you select the ending date and time, that will be the same as if you select "write initial conditions at end."

  7. Dear Chris
    Is warm up file and hot start file the same? I found the following instruction to cope with instability caused by bad initial condition but i can not understand this approach very well! Do you have any idea?

    Influence of initial conditions – choose a “warm up” time
    The model needs some time at the beginning of the simulation to level out i.e. to adjust to initial and
    boundary conditions. In the following you should determine an appropriate warm up time for your
    To prepare the unsteady flow, choose EDIT ¦ UNSTEADY FLOW DATA. Define the Boundary Conditions
    at the upstream profile like required in the given tasks and define at the downstream river station
    normal depth. Choose the Initial Condition (2nd tab). Save the unsteady flow data.
     Carry out a stationary simulation with the long term mean discharge (MMean). Here you should
    use the unsteady flow tool of HEC-RAS, i.e. enter a hydrograph which doesn’t vary with time
     Conduct two additional stationary simulations of the long term mean discharge with varying
    initial conditions, i.e. the initial flow condition doesn’t match the flow hydrograph of the upper
    boundary condition (e.g. ± 50% of the long term mean).
    Compare the results and settle for an appropriate “warm up” time of the model for the following
    simulations. Comparison can for example be based on stage- and flow-hydrographs (H(t)- or
    Q(t)-graph respectively) of the different runs.

    1. In concept, they are very similar. A hotstart plan can be used to effectively "warm up" your model for good initial conditions. You can also use the built-in warm up utility that is located in the unsteady flow analysis window, under Options...Computation Options and Tolerances. The built-in method and the method described in your post, should both achieve the same objective. However, if your model has a lot of instability problems, you may need to run the step-down scheme (as described in the original post) in your hotstart, before you can achieve a good set of initial conditions.

  8. Hi,

    While using restart file, it pops out some error message saying "Error with restart file" and says an error occurred while reading the restart file Recreating the restart file might help. I tried rerunning but still shows the same error. What might be the reason behind this? How can I solve this problem?

    Thank you

  9. I received the same error in a HEC-RAS model with 2D mesh only

  10. Hi Chris,

    If i use daily series of the boundary condition, i.e the validation is can be a year or 6 month during the rainy season period. What is your suggestion based on your experience to set the Restarting file simulation. Thanks

  11. If you use a restart file to continue a dam-break simulation, how does HEC-RAS compute the Duration (DeFlood) Time and the Recession Time?


Note: Only a member of this blog may post a comment.