July 15, 2024
Virtual Flume
Ven Te Chow’s book “Open Channel Hydraulics” is arguably the gold-standard book for hydraulic engineers-especially those of us who model open channel flow.
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.
Have Fun!
Comments
A.L.G.
on June 15, 2014can i do it with a different program?? delphi for example.
Chris G.
on June 16, 2014I 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
Reuben Cozmyer
on June 19, 2014Is there documentation about the different commands that are available in the RAS DLL? When's your book come out?
Chris G.
on June 20, 2014There'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
Chris Goodell
on December 31, 2014**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.
Anonymous
on December 31, 2014Awesome. 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!
Chris Goodell
on December 31, 2014Excellent! Thanks for the kind words. Happy New Year to you and best of luck controlling HEC-RAS!
GoldSim Technology Group
on April 29, 2015Brilliant thank you!
Mike
on September 3, 2015Here 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-RAStest.prj) in Cell B6.")
End If
'End Program
End Sub
Prince Mathur
on January 2, 2018Hey 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?
Chris Goodell
on January 3, 2018Yes, 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.
anouk bomers
on March 9, 2018Dear 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?
Regards,
Anouk
Chris Goodell
on March 14, 2018Hi 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.
RachelO
on June 14, 2019Thank you for all the work you put into this blog, it is much appreciated!
I read on another blog "…users can only apply the HEC-RAS API to one-dimensional (1D) problems. There are no functions available for HEC-RAS 2D models." Can you verify if this is still the case? I am looking for a way to run HEC RAS 2D in batch mode. Thank you.
Chris G.
on June 14, 2019There are very few 2D-specific procedures in the HECRASController API. However, you can call the project_compute, project_open, etc. and it works with any kind of RAS model: 1D, 2D, etc. To modify 2D geometry (i.e. cell center spacing, land cover, etc.), you would have to write to the geometry hdf file to do that automatically. And you can read 2D results from the plan hdf file. So, I would disagree with the comment that the HECRASController can only be used for 1D modeling.
Kathleen H.
on September 13, 2021I have successfully set a 2D model to run using HECRASController, but have not yet exported data – are there capabilities to plot and export 2D data from the model such as profiles down the centerline of the river or cross-sectional profile lines using HECRASController? If we are running many scenarios and want to automate this, would using a python script to pull values from the hdf file be the better route?
Chris Goodell
on October 6, 2021Hi Kathleen, unfortunately, the HECRASController doesn’t have built in procedures for extracting 2D output. A python script with the HDF file is your best option.
Kathleen H.
on October 25, 2021Thanks, Chris. I am specifically interested in pulling values at profile lines within the 2D flow area, but I do not see these within the HDF file. Is there an output option I am missing to instruct RAS to output values of interest at the profile lines? Is this possible to do and then pull from the HDF file with python?
Chris Goodell
on October 25, 2021Unfortunately I don’t think there is a way to get output specifically on a profile line from the HDF file.
Add Your Comment