Discussing the HECRASController API and using the API from Excel VBA. Virginia Lakes and Watersheds Association conference, March 2015.

1. Automating HEC-RAS with Excel
Virginia Lakes and Watersheds Conference, March 2015
Thomas Williams, PE
Amec Foster Wheeler
+ = ?

2. Contents
1. What is HEC-RAS? (brief intro)
2. The HECRASController API
3. Excel VBA Demos
1. Multi-Model Run
2. RAS Output Extraction
3. Manning’s ‘n’ Calibration (sort of)
4. Tips
5. Conclusion
2

3. 1. What is HEC-RAS?
3
Hydrologic
Engineering
Centers
River
Analysis
System
“HEC-RAS allows you to
perform one-dimensional
steady flow, unsteady flow,
sediment transport/mobile
bed computations, and water
temperature modeling.”
- USACE

4. What is an API?
API = Application Programmer Interface
“In computer programming, an application programmer interface (API) is
a set of routines, protocols, and tools for building software
applications. An API expresses a software component in terms of its
operations, inputs, outputs, and underlying types.”
- Wikipedia
2. The HECRASController API
4
Their Program
Your
Program API

5. 2. The HECRASController API (cont’d)
The HECRASController API
“The current version of the HECRASController has a wealth of
procedures that will allow a programmer to manipulate HEC-RAS
externally by setting input data, retrieving input or output data, and
performing common [HEC-RAS] functions…”
- Christopher Goodell, PE, D.WRE, Breaking the HEC-RAS Code, 2014
5
HEC-RAS
Excel
API

6. 2. The HECRASController API (cont’d)
Accessing the API from Microsoft Excel
1. Click the Visual Basic button (on the Developer tab)
2. Create a new VBA module
3. Go to Tools > References, check “HEC River Analysis System”,
and click OK.
4. Write code!
6

7. 2. The HECRASController API (cont’d)
A simple program…
7
Sub RunHECRAS()
' Opens and runs a HEC-RAS model
' Declare variables
Dim ras As New HECRASController
Dim nmsg As Long
Dim strMessages() As String
Dim prjFilePath As String
' Open the model
prjFilePath = "C:MyHecRasModel.prj"
ras.Project_Open (prjFilePath)
' Run the model
ras.Compute_CurrentPlan nmsg, strMessages
End Sub

8. 2. The HECRASController API (cont’d)
Some example HECRASController
fuctions and subroutines:
• Project_Open
Opens a HEC-RAS model.
• Compute_CurrentPlan
Runs the current flow/geometry
regime.
• ExportGIS
Exports an *.sdf file that can be
read into ArcGIS using HEC-
GeoRAS.
• Output_NodeOutput
Returns an output value for a
given node and profile.
8
• Geometry_SetMann
Sets the Manning’s ‘n’ values for
a cross section, horizontally
varied.
• Add_BC
Adds a bridge/culvert.
• Edit_BC
Opens the Bridge/Culvert Editor
and displays the selected station.
• PlotPF
Displays the water surface profile
for a given River/Reach.

9. 3. Excel VBA Demos
9
1. Multi-Model Run
2. RAS Output Extraction
3. Manning’s ‘n’ Calibration (sort of)
Cross your fingers!

10. 4. Tips
• Breaking the HEC-RAS Code
by Christopher Goodell, PE, D.WRE
• The API is a little rough around the edges.
• Provides a lot of functionality, but not everything
• Inconsistencies:
• Parameter names and types
• Function / subroutine behavior
• No “official” API documentation
• HEC-RAS is public domain software, but not open source
• HEC-RAS project (*.prj), geometry (*.g##), flow (*.f##), and plan
(*.p##) files are plain text.
• Sometimes that’s easier than using the API.
• HEC-RAS output files (*.O##) are binary. 
10

11. 5. Conclusion
1. The HECRASController API is really useful…
2. …but it takes a little work to figure out.
3. Happy coding!
Questions?
Contact Info
Thomas Williams, PE
Amec Foster Wheeler
thomas.williams@amecfw.com
11