Pages

Thursday, May 8, 2014

Controlling HEC-RAS

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.

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

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

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!

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 ProgramEnd Sub

WELCOME TO THE RAS SOLUTION

You've arrived at The RAS Solution. The best help site for all things HEC-RAS. Use the Search bar to find topics you are interested in. Do you have an idea for a blog post to The RAS Solution? I welcome and encourage guest authors. Please follow the instructions here. I do receive a lot of questions in the post comments. I try to respond to all questions, but sometimes it gets a little busy. Please be understanding. New to HEC-RAS? Here's a video from Practical Engineering on some of the great things that HEC-RAS can do.

The Author

Chris Goodell is the Director of Applied Research for WEST Consultants, Inc. and a former HEC-RAS Development Team member. Chris teaches HEC-RAS courses around the world and is the author of the popular book "Breaking the HEC-RAS Code."

"Breaking the HEC-RAS Code"

This book covers one of the most powerful, yet relatively unknown features available in HEC-RAS: the HECRASController! The HECRASController API has a wealth of procedures which allow a programmer to manipulate HEC-RAS externally by setting input data, retrieving input or output data, and performing common functions such as opening and closing HEC-RAS, changing plans, running HEC-RAS, and plotting output.

You may share this website or specific posts on this website by any of the following means:1. Using any of the share icons at the bottom of each post or on the website sidebar;2. Providing a back-link of the URL of the content you wish to disseminate; and3. You may quote extracts from this website with attribution to The RAS Solution and proper reference to www.therassolution.com.For any other mode of sharing, please contact the author.

Commercial use and distribution of the contents of the website is not allowed without express and prior written consent of the author.