Design of a MATLAB HEC-RAS Interface to Test Advanced Control Strategies on Water Systems

: The software package HEC-RAS (Hydrologic Engineering Center’s River Analysis 1 System) is widely used by the water engineering community to analyze hydraulic systems and 2 perform development planning. Furthermore, it integrates a control module that allows imple- 3 menting basic controllers. For more complex approaches, developers from the automatic control 4 and artiﬁcial intelligence (AI) communities usually design, implement, and test new algorithms 5 using dedicated software such as MATLAB. However, models of hydraulic systems employed 6 in MATLAB are often very simple. The main objective of the paper is to design a simulation 7 architecture by coupling HEC-RAS with MATLAB, thus improving the accuracy of the dynamics 8 of the hydraulic systems considered in the control simulations. The main feature of the MAT- 9 LAB HEC-RAS interface design is that it allows one to execute customized code at regular time 10 intervals during the simulation. In this way, closed-loop control and optimization algorithms 11 can be implemented and tested. Moreover, the generic interface allows for any conﬁguration of 12 hydrographical systems. The proposed interface is presented in this paper, and the performance 13 of the approach is demonstrated considering two case studies of different nature. 14


Introduction
Hydrographical networks are large-scale systems and consist of natural rivers and 18 artificial canals. Their management, which aims to meet human needs, e.g., avoid natural 19 disasters such as floods, can be divided into two categories: structural and non-structural. 20 On the one hand, structural management aims at defining the infrastructure facilities that 21 allow to fulfill the defined objectives. It is of long-term nature, requires the definition 22 and execution of development planning, and responds to environmental guidelines 23 elaborated with all stakeholders in mind. Managers are usually assisted by engineers and 24 advisors that employ hydraulic software tools, e.g., Hydra (http://hydra-software.net/), 25 Mike11 (https://www.mikepoweredbydhi.com/products/mike-11), SWMM (https: 26 //www.epa.gov/water-research/storm-water-management-model-swmm) and HEC-27 RAS (https://www.hec.usace.army.mil/software/hec-ras/). These software packages 28 allow one to carry out 2D/3D modeling of rivers and canals as well as hydraulic devices 29 and infrastructures, and are used to simulate scenarios and design equipment. On the 30 other hand, the main purpose of non-structural management is that of guaranteeing an 31 efficient management of these systems without modifying the existing structure and 32 equipment. In this case, adaptive and predictive management strategies are required, 33 and they can benefit from forecasts of meteorological events and human activities.  Research on the potential benefits of an interface between MATLAB and HEC-55 RAS has not attracted a lot of attention except for [18]. The authors provide HEC-56 RAS specifications together with several useful scripts for basic operations, which 57 are illustrated using a complete example. Their interface allows MATLAB to control 58 HEC-RAS by considering unique sequences, i.e., hydrographs over long periods of time. 59 Therefore, Monte Carlo simulations can be performed using HEC-RAS and MATLAB [19, 60 20]. However, control algorithms that require a feedback loop cannot be implemented 61 using their approach, as there exists no interface that enables it. 62 Building on the existing results, this work tackles the design of a MATLAB HEC-63 RAS interface that provides both researchers and practitioners with a tool to test MAT-64 LAB control algorithms using the capabilities that HEC-RAS offers in terms of model 65 accuracy. The developed interface is a ready-to-use solution that only requires using the 66 MATLAB command window and editing some m-files to automate HEC-RAS compu-67 tations. Moreover, it deals with any HEC-RAS project-related task, including writing, 68 reading, and extracting results, thus allowing the user to focus on the control algorithm 69 and the results. Indeed, a successful initialization of the interface, which can be achieved 70 by simply supplying a stable HEC-RAS project to the interface, guarantees that the 71 user will never need to use the HEC-RAS GUI (Graphical User Interface). Further-72 more, the proposed solution allows to perform closed-loop simulations, thus extending 73 the results reported in [18]. Last but not least, the development of such interface al-74 lows the automatic control and artificial intelligence (AI) communities to benefit from 75 the expertise of the hydraulic and environmental engineering communities. Indeed, 76 the knowledge about detailed hydraulic and environmental phenomena from the former 77 is rather limited compared to that of the latter. This tool should also be interesting to hy-78 draulic and environmental researchers, allowing them to develop more faithful models 79 from which automatic control and AI researchers would definitely benefit, and would 80 allow them to design innovative approaches.

81
Note that the main contribution with regard to the state-of-the-art is the set of codes 82 employed by the interface to allow for the exchange of information between MATLAB 83 and HEC-RAS. As stated before, these are offered as a ready-to-use solution and are 84 accompanied by exhaustive supporting documentation that provide insight on the poten-85 tial of the solution. Information on how to access codes and documentation is provided 86 in the Data Availability Statement located at the end of the paper. Furthermore, the present 87 paper describes the main features of the interface and presents some examples.

88
The remainder of this paper is structured as follows. Section 2 presents some 89 updates on the HEC-RAS controller discussed in [18] and provides an overview on the 90 vast diversity of HEC-RAS versions. The MATLAB HEC-RAS interface is detailed in 91 Section 3. Section 4 illustrates the approach by considering two case studies (a canal 92 and a river) and three scenarios, which allows to demonstrate the effectiveness of the 93 proposed approach.   The design of the MATLAB HEC-RAS interface is directly inspired from the work 158 in [26]. A MATLAB transcription of the offtake flow example in [22] is then performed.

159
In doing so, a modified version of the offtake flow example is supported by the MATLAB 160 interface. Note that the HEC-RAS objects that already integrate automation capabilities, 161 e.g., navigation dams, are not supported yet by the interface.

Name Description
Classes Classes for object-oriented programming, used as enhanced structures. Variables of these classes store information in a format compatible with HEC-RAS (e.g., XS) or information given by the user (e.g., Settings_)

RAS reading
Low-level functions, which look for parameters in a given HEC-RAS form and return position line number(s)

RAS writing
Low-level functions that replace a given line in an HEC-RAS file with a given string Shortcut Simple functions (unrelated to HEC-RAS) to help developers save time

User interface
High-level functions that use RAS reading and writing in a special context to make the interface smarter and help developers save time Utility Low-level functions used to avoid code repetition for specific tasks However, to avoid further coding work from the user, the interface has been coded 221 to be used directly. Indeed, it is only necessary to specify the HEC-RAS data that are 222 required by the control algorithms, as well as the control setpoints that must be sent 223 to the hydraulic devices in HEC-RAS. Therefore, it is recommended to use the master 224 script as a pattern, to identify which functions must be called, and the execution order.

225
The reader is referred to the interface documentation [27] for detailed information on     The initial condition considered downstream, i.e., XS 0, is given in Table 3 as a stage   258 hydrograph. The simulated upstream hydrographs, i.e., XS 1000, are defined according 259 to two scenarios. The first one, labeled as scenario1, is defined based on the pattern given 260 in Table 3. At the initial time, the upstream flow is equal to zero during ten minutes,    Figure 5 shows the water level at XS 700 for scenario1. The level increases and decreases according to the predefined upstream flow. The HEC-RAS results with automated start and stop simulations are depicted in dashed red, while the results without restart correspond to the continuous blue line. Note that the results obtained are identical for both methods, confirming that the MATLAB HEC-RAS interface approach performs as desired.
Regarding the second scenario, i.e., scenario2, the gate control rule is implemented in input_before_step.m as shown in Listing 3. This script is executed every hour, in accordance with the defined sampling time. Note that the variable ws_elev is assigned the current WSE (read from HEC-RAS), and xs{3} corresponds to an offtake flow, which is applied at the next steps of HEC-RAS.
On the other hand, Listing 4 shows how to access the WSE information from HEC-RAS using output_after_step.m.  Figure 6a depicts the level at XS 700 for scenario2, when the control rule is implemented. This rule requires to withdraw water from the canal whenever the level exceeds a height of 9.3 m. The lateral inflow hydrograph applied by the control rule to the offtake gate at XS 500 is presented in Figure 6b. Note again that both approaches yield the same results. Thus, scenario2 demonstrates the effectiveness of the control approach defined in MATLAB and its application in HEC-RAS thanks to the interface. The most interesting feature of the first case study is that it allows to demonstrate the coordination possibilities between MATLAB and HEC-RAS. Moreover, advanced control algorithms can be easily implemented instead of the simple control rules, which only requires replacing the latter with the algorithm of choice. Indeed, this first case study depicts the basic functioning of the interface. In contrast, the following case study is closer to a real scenario.

Second Case Study: Beaver Creek
The Beaver Creek case study was proposed in [22] (p. 116), and is based on the Bridge Hydraulics project, available for download on HEC-RAS website [21]. Further information on how to set up and run this case study can be found on the MATLAB HEC-RAS interface documentation ( [27], Tutorial 1: simple automation example), which provides a step-by-step explanation to build a simplified version of this project. Figure 7 presents the Beaver Creek HEC-RAS model with the cross sections and the locations of the measurement stations and the two gates, i.e., XS 5.61 and XS 5.44. The offtake gate located at XS 5.61 is used to withdraw water from the canal. Conversely, the inflow gate located at XS 5.44 is used to supply the canal with water. The initial and boundary conditions are summarized in Table 4, and consist of a constant stage downstream hydrograph at XS 5.0 and a modification over time of the upstream flow at XS 5.99. Initially, the upstream flow is equal to zero, then it increases to 50 m 3 /s for the next period, and so on. The sampling time for the HEC-RAS project and MATLAB are equal to twelve hours and one day, respectively.
The user must define, in settings.ini, the control points XS1 and XS2 that correspond to the cross sections XS 5.61 and XS 5.44, respectively. This is shown in Listing 5.
A new scenario is defined for the Beaver Creek case study, i.e., scenario3, which modifies the upstream hydrograph and implements a control rule in MATLAB. The rule controls the two gates based on conditions on the WSE value at XS 5.61. When this value exceeds a height of 65 m, the offtake gate located also at XS 5.61 opens, withdrawing 100 m 3 /s. As soon as the WSE is lower than 65 m, this gate is closed. On the other hand, when the WSE is lower than 64.5 m, the inflow gate opens to supply the canal with 20 m 3 /s. These control rules are summarized in Algorithm 2. Moreover, the file input_before_step.m is used to implement Algorithm 2.    scenario3 shows that the upstream flow modification and the control of the several gates based on one or several measurements of WSE are enabled by the MATLAB HEC-RAS interface. This approach can be easily extended to deal with advanced control algorithms for more complex systems, benefiting from the multiple functionalities offered by MATLAB and HEC-RAS.

Conclusions
The work performed in this paper aims at contributing to the issue of providing an appropriate interface between HEC-RAS and MATLAB, bearing in mind the first steps carried out in [18]. More precisely, a MATLAB HEC-RAS interface has been designed to allow for closed-loop simulations of hydraulic systems that make use of advanced control algorithms. The proposed solution is coded as a series of simple MATLAB scripts. The main objective is that researchers in the Automatic Control and Artificial Intelligence communities can focus on testing control approaches. At the same time, it also aims at providing hydraulic researchers and engineers with a tool to include MATLAB functionalities in their simulations. In particular, the proposed interface allows one to read and write HEC-RAS files, perform fully automated step-by-step simulations, extract and save HEC-RAS results using the HEC-RAS controller, and apply MATLAB code to hydrographs or hydraulic devices.
To illustrate the performance of the interface, two case studies and three scenarios have been considered. The comparison of the accuracy yielded by manual and automated simulation approaches allows to validate the design and performance of the interface.
The considered examples are representative in that several different possibilities of the MATLAB HEC-RAS interface are tested. Moreover, the proposed scripts can be easily adapted to deal with any HEC-RAS project and MATLAB control algorithm. Furthermore, documentation, tutorials, and a website have been created and made accessible to all users.
One of the most sensitive issues linked with environmental systems is that of parameter uncertainty. A typical example of this is the roughness coefficient of the river bed. Indeed, the exact value might be hard to define in certain scenarios, and tables of values are used instead, resulting in small, unavoidable errors. However, such mismatch should not result in a significant performance decrease. Moreover, the developed interface is intended to bridge the gap between the hydraulic and environmental engineering and the automatic control and AI communities, ideally leading to closer cooperation that could mitigate this issue.
On the other hand, unmodeled phenomena represent another sensitive matter to consider during the application of the integrated models with real data. Therefore, and aside from improving the quality of the model used and performing statistical filtering, the integration of other information sources (such as weather forecasts) can definitely contribute to reducing uncertainty. However, an excess of detail might also pose a challenge. Indeed, it needs to be ensured that the computational time does not exceed the sampling time, thus allowing for real-time applicability. Then, the trade-off between the level of modeling detail put in the, e.g., bathymetry and terrain, and the required computational time needs to be considered.
Short-term perspectives regard the implementation and testing of model predictive control (MPC) strategies such as those proposed in [28,29], but using an accurate HEC-RAS model of a real canal in the north of France. Such models are based on precise geographic information systems (GIS), whose data are provided by the Institut Géographique National (IGN), a French organization that manages a highly accurate geographical database of the French territory. In doing so, it will be possible to assess the performance of the MPC with a more realistic model. writing-review and editing: P.S. and E.D.; visualization: R.D. and P.S.; supervision: P.S. and E.D.; project administration: E.D. All authors have read and agreed to the published version of the manuscript.