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.

image
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).

image
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.

image
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:

image

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!







9 comments:

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

    ReplyDelete
    Replies
    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.
      Thanks-
      Chris G.
      @RASModel

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

    ReplyDelete
    Replies
    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. cgoodell@westconsultants.com

      Delete
    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.

      Delete
    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!

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

      Delete
  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 http://hecrasmodel.blogspot.com/2014/05/controlling-hec-ras.html)
    'Reference must be made to the "HEC River Analysis System" under "Tools" -> "References" and check the box next to "HEC River Analysis System" (see http://hecrasmodel.blogspot.com/2014/05/controlling-hec-ras.html)
    '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
    Sheets("Sheet1").Select
    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
    Loop
    'If No plans have been specified produce pop up message warning user and ending program
    Else
    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
    Else
    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
    Else
    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

    ReplyDelete