Thursday, May 8, 2014

Controlling HEC-RAS

Written by Christopher Goodell, P.E., D.WRE  |  WEST Consultants
Copyright © The RAS Solution 2014.  All rights reserved.

So you want to control HEC-RAS from a external program.  Perhaps, you have a lot of plans to run and want to run in batch mode.  Maybe you wish to run HEC-RAS, evaluate the results, make some changes, and rerun HEC-RAS-all automatically, on its own, while you’re at home with the family.  The good news is it can be done.  The bad news is there is really no documentation on how to do this. However I will be publishing a book on this topic this year, so keep checking back for more information on that.  The book, "Breaking the HEC-RAS Code" is now available here.

In the meantime, here’s a quick way to open HEC-RAS, select the plan you want to run, and then run it, all through Visual Basic for Applications in Excel.  If you have HEC-RAS, and you have Excel, you can do this. 

To begin, open Excel and enter the VBA Environment by pressing Alt-F11 or by clicking on the Visual Basic button under the DEVELOPER tab. If the DEVELOPER tab is not already present in your list of menu items, you can add it by accessing the Excel Options under the File menu item and selecting Customize Ribbon. Check the box next to the Developer tab so that it shows up on in your list of menu items. The DEVELOPER tab provides quick access to the VBA Code Editor as well as a host of other programming options and tools. The VBA editor will look like this when it’s opened for the first time.

Visual Basic for Applications Editor.
If a module doesn’t already exist, add one by clicking INSERT…Module from the Visual Basic Editor. A new module will be added and the space to the right of the window will be ready for programming code. You can change the name of the module if you like in the properties window (see figure below).

Visual Basic for Applications Editor with a New Module.

Before you can begin accessing the RAS Dynamic Link Library (RAS DLL), it must be added as a reference. In the Visual Basic for Applications window, select Tools…References from the menu items. A window that lists all of the available reference libraries will come up as shown in the “Add Reference” window. Look for the HEC River Analysis System reference and check the box next to it.

Add Reference Window.

If you don’t see a reference for HEC River Analysis System, you need to install HEC-RAS on your computer. If you have multiple versions of HEC-RAS installed on your computer, you’ll see multiple entries for HEC River Analysis System. Make sure to check the one for the version of HEC-RAS you wish to use.

Now that you’ve added the RAS DLL as a reference, you have access to it’s library of commands that can control HEC-RAS.  Click on the module (Module 1) and type the following code:


Now, it should open and run whatever project you have listed in cell C4 on your Excel Sheet. 
Next, you might want to explore the RC.Plan_SetCurrent() subroutine and a Do-Loop block in your code to run through multiple plans in batch mode. 

Have Fun!


  1. can i do it with a different program?? delphi for example.

    1. I don't know Delphi, so I couldn't say. However, if Delphi can read and reference a dll, then it probably can. Please let me know if you find out one way or another.
      Chris G.

  2. Is there documentation about the different commands that are available in the RAS DLL? When's your book come out?

    1. There's no documentation out there yet. There will be in the book. I'm planning on publishing it around the end of the summer or into the fall. It depends really on when the full release of HEC-RAS Version 5.0 comes out. I might be able to get you an advanced copy later this summer after it has been updated. Email me your contact info and I'll get you on the list for future announcements.

    2. **UPDATE** The book "Breaking the HEC-RAS Code" is now available from my e-store and on Amazon. Check the link on the side panel. It covers everything you need to know about controlling and automating HEC-RAS.

    3. Awesome. Chris. This is exactly what I am looking for. I need run HEC-RAS from Excel. The RAS model needs to work with other models I developed. You are the Savior! I will check your new e-book. Happy New Year!

    4. Excellent! Thanks for the kind words. Happy New Year to you and best of luck controlling HEC-RAS!

  3. Here is what I came up with for Batch Running Multiple Plans from Excel. Let me know if you find any issues.

    Sub HECRAS_BatchCompute()
    'If creating this routine in a new document a Module must be added under the current workbooks VBA Project and this code pasted into the VBA editor (see
    'Reference must be made to the "HEC River Analysis System" under "Tools" -> "References" and check the box next to "HEC River Analysis System" (see
    'This routine works with HEC-RAS 4.1.0
    'This routine will open the HEC-RAS project file listed in cell B6 and run the plans listed in the cells in column B beginning in cell B11
    Dim RC As New RAS41.HECRASController
    'Define the File Name of the Project
    Dim FileName As String
    'The Number of Computation Messages that HEC-RAS Will Return
    Dim nMessages As Long
    'An Array of Computation Messages Returned from HEC-RAS during the Computations
    Dim Messages() As String
    'A Boolean (True or False) Tag that Indicates Whether the HECRASController was able to run the simulation
    Dim DidItCompute As Boolean
    'Get the Project File Name - This should be typed in Cell B6
    FileName = Range("B6").Value

    'Check to see if there is a file name specified
    If FileName <> "" Then
    'Check to see if the specified file name is valid
    If Dir(FileName) <> "" Then
    'Open The Project File
    RC.Project_Open (FileName)
    Dim i As Integer
    i = 11
    Dim PlanName As String
    'Check to see if plans have been specified
    If Cells(i, 2).Value <> "" Then
    'Loop to run specified plans
    Do While Cells(i, 2).Value <> ""
    'Define the PlanName variable = to the first value in the list
    PlanName = Cells(i, 2).Value
    'Turn application (Excel) warnings and alert messages off
    Application.DisplayAlerts = False
    'Set the current plan = to the PlanName variable
    RC.Plan_SetCurrent (PlanName)
    'Compute the current plan
    DidItCompute = RC.Compute_CurrentPlan(nMessages, Messages())
    'Turn application (Excel) warnings and alert messages back on
    Application.DisplayAlerts = True
    'Move to the next plan in the list
    i = i + 1
    'If No plans have been specified produce pop up message warning user and ending program
    MsgBox ("No Plans Specified." & vbNewLine & "Please Specify at Least One Plan Beginning in Cell B11.")
    End If
    'If file name not valid; produce pop up message warning user and ending program
    MsgBox ("File Name and Path Not Valid." & vbNewLine & "Please Check the File name and path Specified in Cell B6.")
    End If
    'If no project file has been specified; produce pop up message warning user and ending program
    MsgBox ("No Project File Specified." & vbNewLine & "Please Specify a Valid File Path (e.g. C:\HEC-RAS\test.prj) in Cell B6.")
    End If
    'End Program
    End Sub

  4. Hey Chris, could we also setup HecRAS for large basin without using GUI interface? Actually, i would like to setup HecRAS for large basins and while using GUI approach it became too messy to dealt with. Because of large size of sdf file HecRAS starts hanging and some time crashes. Could you please suggest me how can we deal with such large basins in HecRAS?

    1. Yes, you could certainly write your own code to create a new geometry file. But this would be a fairly monumental effort. My suggestion is if the sdf file is too large and causing problems, try building your model in pieces. Maybe one reach at a time. Then connect everything together once it's in RAS.

  5. Dear Chris,
    I get an error while trying to run multiple plans within hec-ras, namely: error loading plan data. I just have to click at OK and then the next plan starts to run. Do you have any idea how I can resolve this problem or is it just a bug in hec-ras?
    Besides, can running multple plans outside hec-ras as showing above be a solution?

    1. Hi Anouk. Sounds like RAS is not able to read in all of the data for those plans. Try manually opening another plan. If you get that same error than you know there is something wrong with an input file. You might try rebooting your computer and fixing it a try again. If that doesn’t work, you’ll have to go through your geometry, flow, and plan files to see if you can find the issue. I think you’ll likely have the same problem if you try to run multiple plans using an external script.