Environmental Modelling & Software 84 (2016) 339e348

Contents lists available at ScienceDirect

Environmental Modelling & Software

journal homepage: www.elsevier.com/locate/envsoft

Software data news

Controlling HEC-RAS using MATLAB

Arturo S. Leon a, *, Christopher Goodell b
a
Department of Civil and Environmental Engineering, University of Houston, Cullen College of Engineering Building 1, 4726 Calhoun Road, Room N107,
Houston, TX 77204-4003, USA
b
WEST Consultants, Inc., 10300 SW Greenburg Rd, Portland, OR 97223, USA

a r t i c l e i n f o a b s t r a c t

Article history: The U.S. Army Corps of Engineers' Hydrologic Engineering Center's River Analysis System (HEC-RAS) is a
Received 22 March 2016 widely used software application for performing one-dimensional and two-dimensional steady and
Accepted 27 June 2016 unsteady flow river hydraulics calculations, sediment transport-mobile bed modeling, and water quality
analysis. User's of HEC-RAS have often unique applications including the coupling with other software to
perform system analysis such as optimization of flooding structures and multi-objective reservoir
Keywords:
operation under uncertainty. One state-of-the-art environment for integrating software is MATLAB,
HEC-RAS
which integrates computation, visualization, and programming in an easy-to-use environment. This
HECRASController
MATLAB
paper presents a set of MATLAB scripts to write input files, read output files, make plots, execute parallel
Model integration computations, and perform fully-automated functions of HEC-RAS. Examples of procedures are pre-
Numerical modeling sented throughout the paper and they are illustrated using a river-reservoir network that involves ten
Optimization inline structures (e.g., dams) with operation of gates at each of these dams.
© 2016 Elsevier Ltd. All rights reserved.

Software availability one and two-dimensional hydraulic calculations for a full network
of natural and constructed channels, overbank/floodplain areas,
Name of software: Scripts for Controlling HEC-RAS using MATLAB levee protected areas; etc (Hydrologic Engineering Center, 2016a;
Developer and contact information: Arturo S. Leon Hydrologic Engineering Center, 2016b). HEC-RAS has four main
Mail address: University of Houston, Cullen College of Engineering modules: (a) steady flow water surface profiles, which is intended
Building 1, 4726 Calhoun Road, Room N107, Houston, TX for calculating water surface profiles for steady gradually varied
77204-4003, USA flow; (b) unsteady flow simulation, which can simulate one-
Telephone: (713) 743-8641 dimensional, two-dimensional and combined one/two-
Email address: [email protected] dimensional unsteady flow through a full network of open chan-
Year first available: 2016 nels, floodplains, and alluvial fans; (c) sediment transport compu-
Hardware required: PC that supports MATLAB tations, which is intended for the simulation of one-dimensional
software required: MATLAB 2015 or newer, HEC-RAS 4.1 or 5.0 sediment transport/movable boundary calculations resulting from
Availability and cost: The scripts will be available at http://www2. scour and deposition over moderate to long time periods; and (d)
egr.uh.edu/~aleon3/Codes.html water quality analysis; which is intended to allow the user to
Programming language: MATLAB perform riverine water quality analyses (Hydrologic Engineering
Program size: <1 MB Center, 2016a; Hydrologic Engineering Center, 2016b). Standard
applications of this model include flood wave routing and flood
1. Introduction inundation studies.
The user's of HEC-RAS have often unique applications that may
HEC-RAS is a widely used software application that can perform include the coupling with other software to perform system anal-
ysis such as flood risk analysis, optimization of flooding structures
under uncertainty and multi-objective reservoir operation under
* Corresponding author. uncertainty. A system analysis requires the use of a programming
E-mail address: [email protected] (A.S. Leon).

http://dx.doi.org/10.1016/j.envsoft.2016.06.026
1364-8152/© 2016 Elsevier Ltd. All rights reserved.
340 A.S. Leon, C. Goodell / Environmental Modelling & Software 84 (2016) 339e348

Script 1. Basic functions of USACE HEC-RAS Controller.

platform or environment for integrating multiple software and/or This paper presents a set of MATLAB scripts to write input files,
open source codes. One state-of-the-art programming platform is read output files, and perform fully-automated functions of HEC-
MATLAB, which is a high-performance language for technical RAS. To the authors' knowledge this is the first time that MATLAB
computing that integrates computation, visualization, and pro- is used for fully controlling the input and output of HEC-RAS. The
gramming in an easy-to-use environment (Mathworks, 2015). scripts described in the paper include parallel computing

Script 2. Script to obtain the title name of the geometry file.

 A.S. Leon, C. Goodell / Environmental Modelling & Software 84 (2016) 339e348 341

Script 3. Script to update water stage elevations and flow discharges at multiple crosssections that will be used as the initial conditions for an unsteady flow simulation.

(simultaneous computations of HEC-RAS), modifying input files, HECRASController that are very useful. For an in-depth discussion
accessing output files and coupling with an optimization software. of all functions available in the USACE HECRASController, the reader
It is worth mentioning that although this paper makes use of the is referred to Goodell (2014). The reader is referred to Script 1 for
USACE HECRASController described in Goodell (2014), the main this discussion.
focus of this paper is on programming procedures for controlling
the input and output of HEC-RAS without relying on available
The script line containing actxserver will create a new, invisible
functions of the aforementioned HECRASController. The reasons for copy of HEC-RAS. The text RAS500.HECRASCONTROLLER is used
the latter is that the functions available on the HECRASController for HEC-RAS version 5.0 and RAS41.HECRASCONTROLLER for
are limited and very often the user's may want to perform tasks for version 4.1.
which there is no function in the controller. For an in-depth dis-
The function Project_Open(ras_file) will open a RAS file, where
cussion of all functions available in the USACE HECRASController, ras_file is a string.
the reader is referred to Goodell (2014). This paper is divided as
The function Compute_HideComputationWindow hides the HEC-
follows. First, the USACE HECRASController is briefly described. RAS computation window, which is useful when performing
Second, MATLAB scripts for various tasks are presented throughout parallel computations or serial batch computations. The func-
the paper and they are illustrated using a river-reservoir network tion Compute_ShowComputationWindow shows the computa-
that involves ten inline structures (e.g., dams) with operation of tion window for each HEC-RAS computation.
gates at each of these dams. Finally, the key points of the paper are
The function Compute_CurrentPlan runs HEC-RAS for current
summarized in the conclusion. plan.

The function Project_Save saves the HEC-RAS project
2. HEC-RAS controller
The function OutputDSS_GetStageFlow is intended for extracting
water surface stage and flow discharge at selected cross-
This section presents a very brief discussion on the USACE sections.
HECRASController. We will only focus on few functions of the
342 A.S. Leon, C. Goodell / Environmental Modelling & Software 84 (2016) 339e348

Script 3. Script to update water stage elevations and flow discharges at multiple crosssections that will be used as the initial conditions for an unsteady flow simulation.

input text files are:

1 Geometry file: :g##

3. Reading and writing HEC-RAS input files
2 Steady flow file: :f##
3 Unsteady flow file: :u##
As described in Goodell (2014), the most common HEC-RAS
 A.S. Leon, C. Goodell / Environmental Modelling & Software 84 (2016) 339e348 343

Fig. 1. Example of a plot produced using the HECRASController subroutine ‘‘PlotStageFlow.

Fig. 2. A snapshot of simultaneous HEC-RAS computations.

There are other input files such as Plan file (:p##), Project file
(*.prj), and others. The manipulation of the input files are very
similar so due to space limitations we will show four examples for The second example updates water stage elevations and flow
the geometry and unsteady flow input files. discharges at multiple cross-sections that will be used as the initial
The first example will find and printout the title name of the conditions for an unsteady flow simulation. This example corre-
geometry file. The reader is referred to Script 2 for this example. In sponds to an optimization of reservoir operation in a ten-reservoir
this script, the filename will have the extension *.g##. Script 2 system. The reader is referred to Script 3 for this example. In this
reads the file line by line. Whenever the script finds the character script, the filename to use will have the extension *.u##.
‘‘¼’’, it will split the text in two (left and right of ‘‘¼’’). Then the Script 3 first reads data of current tailwater and forebay eleva-
script checks if the left of the text is the same as the string ‘‘Geom tion for the ten dams. Then the script reads the current inflows and
Title’’. If it is, it will extract and printout the right of the text, which outflows of the ten reservoirs, which are stored for later use.
will be the title name of the geometry file. Following, the unsteady input file needs to be updated with the
344 A.S. Leon, C. Goodell / Environmental Modelling & Software 84 (2016) 339e348

Script 4. Script to prepare the data lines for the inflow hydrographs and gate outflows to be written in the unsteady file of HEC-RAS.

corresponding initial water stages and flow discharges. To perform rewritten. The initial flow should contain the string ‘‘Initial Flow
this task, first the original unsteady file is copied to a temporal file Loc ¼ ’’ at the most left part of the text line. This string should be
(‘‘24XSNEW_temp.u01’’). Then using as baseline the temporal un- followed by the river, reach, station and the initial flow discharge at
steady file, the original unsteady file (‘‘24XSNEW.u01’’) is rewritten this river station. The initial water stage should contain the string
with the current water stages and flow discharges. To start to ‘‘Initial RRR Elev ¼ ’’ at the most left part of the text line. This string
replace the initial conditions, it is necessary to find the key variable should be followed by the river, reach, station and the initial water
‘‘Use Restart ¼ 000 in the temporal file that is being read. Once this stage at this river station. After this data is written in the original
string is found, it should be printed out in the file and then the file, we should continue reading the temporal file without writing
initial flows and stages are also printed out in the original file being anything until the string ‘‘Boundary Location ¼ ’’ is found. The latter
 A.S. Leon, C. Goodell / Environmental Modelling & Software 84 (2016) 339e348 345

Script 5. Script to update pre-scheduled gate outflows and hydrographs at dams.

will avoid errors in the input file due to data size incompatibility
between the old (temporal file) and the new (being rewritten) The third example updates the inflow hydrographs (two) and
input files. pre-scheduled gate outflows at ten inline structures (i.e, dams). The
pre-scheduled outflows are generated by an optimization routine
346 A.S. Leon, C. Goodell / Environmental Modelling & Software 84 (2016) 339e348

Script 5. Script to update pre-scheduled gate outflows and hydrographs at dams.

Script 6. Script to extract water surface stage and flow discharge.

(Genetic Algorithm) with a pre-specified population. randomly generated individuals, and is an iterative process, with the
In a genetic algorithm, a population of candidate solutions (called population in each iteration called a generation. In each generation,
individuals) to an optimization problem is evolved toward better the fitness of every individual in the population is evaluated; the
solutions. The evolution usually starts from a population of fitness is usually the value of the objective function in the
 A.S. Leon, C. Goodell / Environmental Modelling & Software 84 (2016) 339e348 347

Script 7. Script to plot water surface stage and flow discharge.

Script 8. Script to perform parallel HEC-RAS computations.

optimization problem being solved. The more fit individuals are net/).

stochastically selected from the current population, and each in- The update of dam outflows is done at each generation for each
dividual's genome is modified (recombined and randomly mutated) population of the optimization. It is worth mentioning that in an
to form a new generation. The new generation of candidate solutions optimization-simulation framework, the initial conditions (second
is then used in the next iteration of the algorithm. Commonly, the example) need to be updated only at the beginning of the optimi-
algorithm terminates when either a maximum number of genera- zation. The reader is referred to Scripts 4 and 5 for the third example.
tions has been produced, or a satisfactory fitness level has been In this example, the file to update will have the extension *.u##.
reached for the population. For more details about the genetic al- This example has two parts. In the first part, the data (inflow
gorithm and its application to reservoir operation the reader is hydrographs and outflows) to be written in the unsteady file is
referred to Wardlaw and Sharif (1999), Leon and Kanashiro (2010), prepared. The HEC-RAS unsteady input file (*.u##) is formatted in
Leon et al. (2014), Lerma et al. (2015), Yang et al. (2015), and Chen such a way that the data points for inflow hydrographs and out-
et al. (2016). Due to space limitations, a code of a genetic algo- flows at inline structures can have a maximum of 10 data points per
rithm is not presented herein. However, there are various codes line. Script 4 prepares the lines of data to be written in the unsteady
available in the literature (e.g., https://www.idealsoftware.com/ file. This script first calculates the number of lines of data for the
opensource/genetic-algorithm.html and http://gaul.sourceforge. inflow hydrographs (‘‘NLines_inflow’’) and the outflows
348 A.S. Leon, C. Goodell / Environmental Modelling & Software 84 (2016) 339e348

(‘‘NLines_Out’’) based on the number of data points. For instance, if computations. Next, the parfor function of MATLAB is used for the
the simulation period is 4 days with gate outflows specified every parallel computations. Finally, the system taskkill command is used
hour, the number of data points for the outflows would be 97 that to close all open HEC-RAS projects. A snapshot of simultaneous
includes the initial condition (t ¼ 0). In this case, the number of HEC-RAS computations is shown in Fig. 2.
lines of data for the outflows (‘‘NLines_Out’’) would be 10. Next, the
script calculates the number of data points for the last line of the
inflow hydrographs (‘‘last_line_inf’’) and the outflows (‘‘las-
5. Conclusions
t_line_dam’’). The reason for the latter is because not always the
number of data points of the last line is 10. Then, the data for inflow
This paper presents a set of MATLAB scripts to write input files,
hydrographs is split in two, one for all the lines except the last one
read output files, and perform fully-automated functions of HEC-
(‘‘Inflow_array_main’’) and the last line (‘‘Inflow_array_last_line’’).
RAS. Examples of various programming procedures are presented
Likewise, the data for the dam outflows are split into (‘‘Out-
throughout the paper and they are illustrated using a river-
flow_array_main’’) and (‘‘Outflow_array_last_line’’).
reservoir network that involves ten inline structures (e.g., dams)
Once the data has been prepared, Script 4 will call Script 5 for
with operation of gates at each of these dams. The procedures in-
each population of the optimization. To start to replace the data, it
cludes reading and writing HEC-RAS input files, extracting output
is necessary to find key variables in the temporal unsteady file that
variables, plotting and parallel computing. In addition, this paper
is being read. These variables are ‘‘Flow Hydrograph ¼ ’’ for the
presents a brief introduction to the USACE HECRASController.
inflow hydrographs and ‘‘Rule Table ¼ ’’ for the dam outflows. In a
similar way to the second example, after the data has been written
in the original file, we should continue reading the temporal file Acknowledgments
without writing anything until the strings ‘‘DSS Path ¼ ’’ and ‘‘Rule
Operation ¼ ’’ have been found for the inflow hydrographs and dam The first author gratefully acknowledges the financial support of
outflows, respectively. The latter will avoid errors in the input file the Bonneville Power Administration of the U.S. Department of
due to data size incompatibility between the old (temporal file) and Energy under award number TIP#258.
the new (being rewritten) input files.
References
4. Extracting output variables, plotting and parallel computing
Chen, D., Leon, A.S., Gibson, N.L., Hosseini, P., 2016. Dimension reduction of decision
This section presents examples to extract water surface stages variables for multireservoir operation: a spectral optimization model. Water
and flow discharges, plotting and to perform parallel HEC-RAS Resour. Res. 52, 36e51.
Goodell, C., 2014. Breaking the HEC-RAS Code, first ed. Oregon, Portland. h2ls.
computations. There are functions available in the HECRASCon- Hydrologic Engineering Center, 2016a. HEC-RAS, River Analysis System, Hydraulic
troller for extracting water surface stages and flow discharges, and Reference Manual. Version 5.0. U.S. Army Corps of Engineers, Davis, California.
their plotting, so these tasks are straight forward. The reader is Hydrologic Engineering Center, 2016b. HEC-RAS River Analysis System User's
Manual e Version 5.0. U.S. Army Corps of Engineers, Davis, California.
referred to Script 6 for extracting water surface stages and flow Leon, A.S., Kanashiro, E., 2010. A new coupled optimization-hydraulic routing model
discharges and Script 7 for plotting water surface stage and flow for real-time operation of highly complex regulated river systems. In: Water-
discharge at a given river station. The HECRASController function shed Management Conference: Innovations in Watershed Management under
Land Use and Climate Change, ASCE-EWRI, Madison, Wisconsin, USA,
‘‘OutputDSS_GetStageFlow’’ allows to extract stage and flow hydro- pp. 213e224.
graphs at a given river station. The HECRASController subroutine Leon, A.S., Kanashiro, E., Valverde, R., Sridhar, V., 2014. Dynamic framework for
‘‘PlotStageFlow’’ allows to plot the stage and flow hydrograph at a intelligent control of river flooding: case study. J. Water Resour. Plan. Manag.
140, 258e268. http://dx.doi.org/10.1061/(ASCE)WR.1943-5452.0000260.
given river station. An example of this plot is shown in Fig. 1. Lerma, N., Paredes-Arquiola, J., Andreu, J., Solera, A., Sechi, G.M., 2015. Assessment
of evolutionary algorithms for optimal operating rules design in real water
resource systems. Environ. Model. Softw. 69, 425e436.
Mathworks, 2015. MATLAB Version 8.6.0.267246 (R2015b). The Mathworks, Inc,
Following we present the script to perform parallel HEC-RAS
Natick, Massachusetts.
computations. The reader is referred to Script 8 for this example. Wardlaw, R., Sharif, M., 1999. Evaluation of genetic algorithms for optimal reservoir
The script first creates a special job on a pool of workers, and system operation. J. Water Resour. Plan. Manag. 125, 25e33.
connects the MATLAB client to the parallel pool. This is done using Yang, T., Gao, X., Sellars, S.L., Sorooshian, S., 2015. Improving the multi-objective
evolutionary optimization algorithm for hydropower reservoir operations in
the ‘‘parpool’’ function of MATLAB. Then, the scripts defines an array the california orovilleA ~^C
ca n
^ 
aAthermalito complex. Environ. Model. Softw. 69,
of handles (h{j}) with a number equal to the number of HEC-RAS 262e279.