HEC-RAS Model Adapter

Introduction

The conceptual solution for the interface between HEC-RAS and FEWS has been illustrated in Figure 1. Two modes of working are identified that each support a basic use case. The modes of working are:

Operational forecasting mode
Calibration mode

The technical implementations for both modes of working are quite different. For running HEC-RAS in operational forecasting mode from FEWS, a software interface will be required that directly controls the model runs.

Calibration is considered as an activity that should be carried out offline from the forecasting system. This means that no direct control from FEWS will be required but a user will need to be able to migrate model datasets (calibrated schematizations) from the HEC-RAS calibration environment to the forecasting environment.

Present documentation will describe the first mode of operation. For details about operating model in the calibration mode please check standard HEC-RAS documentation.

Operating Forecasting Model

Figure 1 Components used to run forecasts using HEC-RAS model in the FEWS/CHPS system

Operating HEC-RAS Model and FEWS Adapter

The HEC-RAS model provides the compute engine for running a hydraulic model schematization for a section of a river or a part of a river system. The HEC-RAS Adapter forms the interface between the FEWS Forecasting Shell and the HEC-RAS model.

The HEC-RAS compute engine is, as its name suggests, the component that actually performs the HEC-RAS simulation. This simulation is controlled from the FEWS Adapter, and all run time data such as initial and boundary conditions, and parameter settings are passed through the adapter from and to the FEWS Forecasting Shell.

Interface between FEWS and HEC-RAS

The FEWS Adapter for HEC-RAS forms the interface between the FEWS Forecasting Shell and the HEC-RAS model. The adapter accepts the request from the Forecasting Shell to run HEC-RAS, and imports the required data provided by the Forecasting Shell.

This data shall be provided in a standardized XML interface format, the FEWS Published Interface. Once a HEC-RAS run has been completed, relevant results are passed back to the Forecasting Shell in the form of the standardized XML interface format.

A schematic representation of the communication between the Forecasting Shell and the HEC-RAS model via the FEWS Adapter is shown in the diagram below.

Figure 2 Data flows involved during run of HEC-RAS model FEWS adapter

The FEWS Adapter allows running of HEC-RAS by FEWS. The FEWS Adapter should be considered as a thin communication (software) layer on top the existing HEC-RAS engine. The adapter is tightly connected to the model engine. For longer term consistency, a FEWS adapter should therefore preferably be maintained by the owner of the model code, in this case HEC. The FEWS Adapter for HEC-RAS shall be developed by HEC or handed over to HEC upon completion.

Several design options for the FEWS Adapter will be discussed in this section. Red box in the diagram below outlines the components within the adapter itself. The technical options will be discussed in the next section.

The features of the are listed in the tables below.

Preprocessing 01	Clean up work and output folder
Preprocessing 02	Create module diagnostics file in Published Interface (PI) format
Preprocessing 03	Read the time series from PI time series
Preprocessing 04	Convert input PI time series into RAS DSS files
Launcher 01	Run HEC-RAS with run period and model alternative
Postprocessing 01	Open/create module diagnostics file in PI format
Postprocessing 02	Read a selection (output-dss-paths.txt) of output time series in the output RAS DSS file
Postprocessing 03	Write the time series to the output.xml
Postprocessing 04	Write the updated PI state file to export folder

ID Mapping

The location parameters used in FEWS can be coupled to HEC-RAS DSS path names through ID-mapping. The configuration files for ID-mapping should be created separately for each HEC-RAS model. Please consult 08 Mapping Id's flags and units for more information on how to configure id mapping in FEWS system.

Directory structure

The data directories and configuration files that are required for operating the FEWS Adapter for HEC-RAS have been shown below.

Note that only binary and configuration files relevant to the HEC-RAS adapter are included, in a real configuration a lot more files can be involved used by another modules of the FEWS system.

+---bin
|       hec.jar
|       heclib.jar
|       heclib60.dll
|       javaHeclib.dll
|       libjavaHeclib.so
|       module-adapter-hec-ras.jar......................... pre- and pos- adapter, Coverts HEC-RAS data files to/from FEWS-PI format
|       nwsras.jar......................................... main library used by the adapter, reads and writes HEC-RAS data files
|       
\---connecticu
    +---ColdStates
    |       hecras_connecticut_Historical Default.zip...... cold state files
    |       
    +---Config
    |   +---IdMapFiles
    |   |       IdExportHECRAS.xml......................... custom mappings for the HEC-RAS variables and locations
    |   |       
    |   \---ModuleConfigFiles
    |           hecras_Connecticut_Forecast.xml............ main configuration file of the adapter
    |           
    \---Modules
        \---hec-ras
            +---bin........................................ directory which contains all HEC-RAS executables for Windows and Linux platforms
            |       DSSWriter.exe.......................... generates binary file containing detailed model output
            |       dss_writer
            |       GeomPreprocessor.exe................... converts geometry files from GUI ASCII format to binary
            |       geo_pre
            |       Steady.exe............................. performs steady flow simulations
            |       steady
            |       Unsteady.exe........................... performs unsteady flow simulations
            |       unsteady
            |       libmtsk.so.1
            |       
            \---connecticut
                +---input.................................. input directory of the adapter, input FEWS-PI time series files
                |       inputs.xml
                |       
                +---log.................................... log messages written by the pre- and post- adapters
                |       postadapter.xml
                |       preadapter.xml
                |       
                +---output................................. contains HEC-RAS output converted from the binary and dss output files
                |       binary-output.xml
                |       output.xml
                |       
                \---work................................... working directory of the adapters
                        clean.cmd.......................... Windows and Linux scripts used to clean temporary files
                        clean.sh
                        run.cmd............................ Windows and Linux scripts used to execute the HEC-RAS model
                        run.sh
                        ctfld2ras.b01
                        ctfld2ras.b02
                        ctfld2ras.b03
                        ctfld2ras.c02
                        ctfld2ras.f04
                        ctfld2ras.g02
                        ctfld2ras.p01
                        ctfld2ras.p02
                        ctfld2ras.p05
                        ctfld2ras.prj
                        ctfld2ras.r01
                        ctfld2ras.r02
                        ctfld2ras.r03
                        ctfld2ras.r05
                        ctfld2ras.u01
                        ctfld2ras.u02
                        ctfld2ras.x02

Communication between FEWS system and pre-/post- adapter strictly follows the FEWS Published Interface format.

Configuring HEC-RAS adapter

HEC-RAS model adapter follows standard way of integrating external models into the Delft-FEWS system by use of General Adapter. For more details about configuration of General Adapter please check 05 General Adapter Module.

Example configuration of the HEC-RAS adapter:

<generalAdapterRun xmlns="http://www.wldelft.nl/fews" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.wldelft.nl/fews http://fews.wldelft.nl/schemas/version1.0/generalAdapterRun.xsd">
	<general>
		<description>hecras Model for Connecticut River</description>
		<rootDir>%REGION_HOME%/modules/hec-ras/</rootDir>
		<workDir>%ROOT_DIR%/connecticut/work</workDir>
		<exportDir>%ROOT_DIR%/connecticut/input</exportDir>
		<exportIdMap>IdExportHECRAS</exportIdMap>
		<importDir>%ROOT_DIR%/connecticut/output</importDir>
		<importIdMap>IdImportHECRAS</importIdMap>
		<dumpFileDir>$GA_DUMPFILEDIR$</dumpFileDir>
		<dumpDir>%ROOT_DIR%/connecticut</dumpDir>
		<diagnosticFile>%ROOT_DIR%/connecticut/log/preadapter.xml</diagnosticFile>
		<convertDatum>true</convertDatum>
	</general>

	<activities>
		<startUpActivities>
			<purgeActivity>
				<filter>%ROOT_DIR%/connecticut/log/*.*</filter>
			</purgeActivity>
			<purgeActivity>
				<filter>%ROOT_DIR%/connecticut/input/*.*</filter>
			</purgeActivity>			
			<purgeActivity>
				<filter>%ROOT_DIR%/connecticut/output/*.*</filter>
			</purgeActivity>			
			<purgeActivity>
				<filter>%ROOT_DIR%/connecticut/work/*.dss</filter>
			</purgeActivity>			
		</startUpActivities>
		
		<exportActivities>
			<exportStateActivity>
				<moduleInstanceId>hecras_connecticut_Historical</moduleInstanceId>
				<stateExportDir>%ROOT_DIR%/connecticut/work</stateExportDir>
				<stateConfigFile>%ROOT_DIR%/connecticut/work/state.xml</stateConfigFile>
				<stateLocations type="file">
					<stateLocation>
						<readLocation>ctfld2ras.p05.rst</readLocation>
						<writeLocation>ctfld2ras.p05.rst</writeLocation>
					</stateLocation>
				</stateLocations>
				<stateSelection>
					<warmState>
						<stateSearchPeriod unit="day" start="-10" end="0"/>
					</warmState>
				</stateSelection>
			</exportStateActivity>
			<exportTimeSeriesActivity>
				<exportFile>inputs.xml</exportFile>
				<timeSeriesSets>
					<timeSeriesSet>
						<moduleInstanceId>HFDC3FLW_6to1_ChangeT_Forecast</moduleInstanceId>
						<valueType>scalar</valueType>
						<parameterId>QINE</parameterId>
				
						<locationId>TMVC3</locationId>
						<timeSeriesType>external forecasting</timeSeriesType>
						<timeStep unit="hour" multiplier="1"/>
						<relativeViewPeriod unit="hour" start="0" end="48" endOverrulable="true"/>
						<readWriteMode>read only</readWriteMode>
					</timeSeriesSet>
					<timeSeriesSet>
						<moduleInstanceId>HFDC3FLW_ChangeT_Forecast</moduleInstanceId>
						<valueType>scalar</valueType>
						<parameterId>QINE</parameterId>
						<locationId>TARC3</locationId>
						<timeSeriesType>external forecasting</timeSeriesType>
						<timeStep unit="hour" multiplier="1"/>
						<relativeViewPeriod unit="hour" start="0" end="48" endOverrulable="true"/>
						<readWriteMode>read only</readWriteMode>
					</timeSeriesSet>
					<timeSeriesSet>
						<moduleInstanceId>PRTN6GRL_Q2STG_STAGEQ_Forecast</moduleInstanceId>
						<valueType>scalar</valueType>
						<parameterId>SSTG</parameterId>
						<locationId>PRTN6GRL</locationId>
						<timeSeriesType>simulated forecasting</timeSeriesType>
						<timeStep unit="hour" multiplier="6"/>
						<relativeViewPeriod unit="hour"  end="120" endOverrulable="true"/>
						<readWriteMode>read only</readWriteMode>
					</timeSeriesSet>
				</timeSeriesSets>
			</exportTimeSeriesActivity>
		</exportActivities>
		

		
		
		<executeActivities>
                        <!-- run pre-adapter, converts time series from FEWS-PI to HEC-RAS data files -->				
		        <executeActivity>
			        <command>
				        <className>nl.wldelft.fews.adapter.hec.HecRasPreAdapter</className>
				</command>
				<arguments>
					<argument>--project-file=%ROOT_DIR%/connecticut/work/ctfld2ras.prj</argument>
					<argument>--dss-file=%ROOT_DIR%/connecticut/work/ctfld2ras.dss</argument>
					<argument>--time-step=1MIN</argument>
				</arguments>
				<timeOut>120000</timeOut>
			</executeActivity>

                        <!-- run HEC-RAS model using script -->
			<executeActivity>
				<description></description>
				<command>
					<executable>%ROOT_DIR%/connecticut/work/run.cmd</executable>
				</command>
				<arguments />
 				<timeOut>1500000</timeOut>
				<ignoreDiagnostics>true</ignoreDiagnostics>
			</executeActivity>
			
			<!-- Convert HEC-RAS results from DSS to FEWS PI XML -->
			<executeActivity>
				<command>
					<className>nl.wldelft.fews.adapter.hec.HecRasPostAdapter</className>
				</command>
				<arguments>
					<argument>--project-file=%ROOT_DIR%/connecticut/work/ctfld2ras.prj</argument>
					<argument>--output-log-file=%ROOT_DIR%/connecticut/log/postadapter.xml</argument>
					<argument>--output-pi-file=%ROOT_DIR%/connecticut/output/output.xml</argument>
					<argument>--output-binary-file=%ROOT_DIR%/connecticut/work/ctfld2ras.O01</argument>
					<argument>--output-binary-pi-file=%ROOT_DIR%/connecticut/output/binary-output.xml</argument>
				</arguments>
				
				<timeOut>1500000</timeOut>
			</executeActivity>
		</executeActivities>
		
		<!-- import converted FEWS PIXML time series -->
		<importActivities>
			<importStateActivity>
				<stateConfigFile>%ROOT_DIR%/connecticut/work/state.xml</stateConfigFile>
			</importStateActivity>
			<importTimeSeriesActivity>
				<importFile>results.xml</importFile>
				<timeSeriesSets>
					<timeSeriesSet>
						<moduleInstanceId>hecras_connecticut_Forecast</moduleInstanceId>
						<valueType>scalar</valueType>
						<parameterId>SSTG</parameterId>
						<locationId>MDDC3</locationId>
						<locationId>TMVC3</locationId>
						<locationId>LYMC3</locationId>
						<locationId>SAYC3</locationId>
						<timeSeriesType>simulated forecasting</timeSeriesType>
						<timeStep unit="hour" multiplier="1"/>
						<readWriteMode>add originals</readWriteMode>
					</timeSeriesSet>
					<timeSeriesSet>
						<moduleInstanceId>hecras_connecticut_Forecast</moduleInstanceId>
						<valueType>scalar</valueType>
						<parameterId>SQIN</parameterId>
						<locationId>MDDC3</locationId>
						<locationId>TMVC3</locationId>
						<locationId>LYMC3</locationId>
						<locationId>SAYC3</locationId>
						<timeSeriesType>simulated forecasting</timeSeriesType>
						<timeStep unit="hour" multiplier="1"/>
						<readWriteMode>add originals</readWriteMode>
					</timeSeriesSet>
				</timeSeriesSets>
			</importTimeSeriesActivity>
		</importActivities>
	</activities>
</generalAdapterRun>

Description of the HEC-RAS data files

Table 1 List of files to be read and written by adapter

Extension	Description	pre-adapter input	pre-adapter output	post-adapter input	post-adapter output
.prj	project file
.p01	plan files
.g01	geometry files
.f01	flow files
.u01	unsteady flow files
.b01	unsteady run files
.x01	input file for geometry preprocessor
.r01	steady run file
.O01	binary output file
.bco	model log file
.c01	output of geometry preprocessor
.dss	input / output files
.hyd01	input file for geometry preprocessor

Running model from FEWS

Check Delft-FEWS User Guide on how to run configured model from the Delft-FEWS system.

Running model using command-line

For testing purposes and also to simplify configuration of the HEC-RAS adapter the following command-line scripts were created:

run.cmd - allows to run HEC-RAS model using command-line
run.sh
clean.cmd - cleans model working directory, all temporary or output files of the HEC-RAS model
clean.sh

Scripts are available for Windows and Linux OS, .cmd and .sh extensions correspondingly.

Note that all files names and extensions used in the run.cmd or run.sh scripts must be defined correctly based on used input data files of the HEC-RAS model in the HEC-RAS GUI.

run.cmd

@echo on

set RAS_BIN_HOME=..\..\bin

echo Processing geometry ... 
%RAS_BIN_HOME%\GeomPreprocessor.exe ctfld2ras.x02 runnext=1

echo Running Unsteady.exe ... 
%RAS_BIN_HOME%\Unsteady.exe ctfld2ras.c02 b03 runnext=1

echo Running Steady.exe (also produces binary output, after Unsteady.exe) ... 
%RAS_BIN_HOME%\Steady.exe ctfld2ras.r03 runnext=1 

echo Writing DSS ... 
%RAS_BIN_HOME%\DSSWriter.exe ctfld2ras.c02 p03 runnext=1

pause

clean.cmd

del *.hyd*
del *.IC*
del *.O0*
del Steady_CRASHED
del *scratch*
del *bco
del *blf
del *.xrj
del *.a0*
del *.hto*
del *.t*
del *.c
del ctfld2ras.dsc
del ctfld2ras.dss
del GeomPreprocessor_CRASHED
del *.bco*
del *.rst

run.sh

#!/bin/sh

RAS_BIN_PATH=../../bin

export LD_LIBRARY_PATH=$RAS_BIN_PATH:$LD_LIBRARY_PATH

echo "Running Geometry Preprocessor ..."
$RAS_BIN_PATH/geo_pre ctfld2ras.x02

echo "Running Unsteady ..."
$RAS_BIN_PATH/unsteady ctfld2ras.c02 b02

echo "Running Steady ..."
$RAS_BIN_PATH/steady ctfld2ras.r01

echo "Running DSS Writer ..."
$RAS_BIN_PATH/dss_writer ctfld2ras.c02 p02

clean.sh

rm -f ./*.hyd*
rm -f ./*.IC*
rm -f ./*.O0*
rm -f ./Steady_CRASHED
rm -f ./*scratch*
rm -f ./*bco
rm -f ./*blf
rm -f ./*.xrj
rm -f ./*.a0*
rm -f ./*.hto*
rm -f ./*.t*
rm -f ./*.c
rm -f ./ctfld2ras.dsc
rm -f ./ctfld2ras.dss
rm -f ./GeomPreprocessor_CRASHED
rm -f ./*.bco*

Page tree

Contents