Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Table of Contents

Introduction

Note: The Delft-FEWS HEC-RAS adapter is maintained by RMA

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:

...

Download of the model adapter is not available here: pls contact the adapter owner RMA or e-mail to the Delft-FEWS Product Management for more information.
Configuration Manual : how to add a hecras model in chps.pdf\for HEC-RAS versions 4.1: Config manual RAS 4.1

Configuration Manual for HEC-RAS versions 5.0.3: Config manual RAS 5.0.3.

Configuration Manual for HEC-RAS versions 5.0.7: Config manual RAS 5.0.7 and RAS Mapper

Configuration Manual for HEC-RAS version 6.0: Config manual RAS 6.0

Interface between FEWS and HEC-RAS

...

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 *.b01 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 the output time series from the RAS DSS and binary output files

Postprocessing 03

Write the time series to the output.xml

Postprocessing 04

Write the time series to the binary-output.xml

Postprocessing 05

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.

...

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

(tick)

 


(tick)

 


.p01

plan files

(tick)

 


(tick)

 


.g01

geometry files

(tick)

 


(tick)

 


.f01

flow files

 

 

 

 





.u01

unsteady flow files

 

 

 

 





.b01

unsteady run files

(tick)

(tick)

(tick)

 


.x01

input file for geometry preprocessor

 

 

 

 





.r01

steady run file

 

 

 

 





.O01

binary output file

 

 



(tick)

 


.bco

model log file

 

 



(tick)

 


.c01

output of geometry preprocessor

 

 

 

 





.dss

input / output files

 

 



(tick)

 


.hyd01

input file for geometry preprocessor

 

 

 

 





Configuring HEC-RAS adapter

...

Note

List of output variables is defined under outputTimeSeriesParametersFilter item uses and outputLongtitudionalProfileParametersFilter items use Regular Expressions. In most cases it is a list of variable names delimited with '|' character and for those variables where name can occur in another variable names (e.g. FLOW and FLOW AT GATE) it is necessary to use ^ as a prefix and $$ as a suffix of the variable. For example:

Code Block
languagexml
         <string key="outputTimeSeriesParametersFilter" value="^STAGE$$|^FLOW$$|Hydr Radius R|Hydr Radius L|^Flow Area$$" />


...

Code Block
xml
xml
<?xml version="1.0" encoding="UTF-8"?>
<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 Kennebec River</description>
		<rootDir>$HECRASMODELDIR$/kennebec</rootDir>
		<workDir>%ROOT_DIR%/work</workDir>
		<exportDir>%ROOT_DIR%/input</exportDir>
		<exportDataSetDir>%ROOT_DIR%/work</exportDataSetDir>
		<exportIdMap>IdExportHECRAS</exportIdMap>
		<exportUnitConversionsId>ExportHECRAS</exportUnitConversionsId>
		<importDir>%ROOT_DIR%output</importDir>
		<importIdMap>IdImportHECRAS</importIdMap>
		<importUnitConversionsId>ImportHECRAS</importUnitConversionsId>
		<dumpFileDir>$GA_DUMPFILEDIR$</dumpFileDir>
		<dumpDir>%ROOT_DIR%</dumpDir>
		<diagnosticFile>%ROOT_DIR%/log/preadapter.xml</diagnosticFile>
	</general>
	<activities>
		<startUpActivities>
			<purgeActivity>
				<filter>%ROOT_DIR%/log/*.*</filter>
			</purgeActivity>
			<purgeActivity>
				<filter>%ROOT_DIR%/input/*.*</filter>
			</purgeActivity>
			<purgeActivity>
				<filter>%ROOT_DIR%/output/*.*</filter>
			</purgeActivity>
			<purgeActivity>
				<filter>%ROOT_DIR%/work/*.*</filter>
			</purgeActivity>
		</startUpActivities>
		<exportActivities>
			<exportStateActivity>
				<moduleInstanceId>HECRAS_KENNEBEC_UpdateStates</moduleInstanceId>
				<stateExportDir>%ROOT_DIR%/work</stateExportDir>
				<stateConfigFile>%ROOT_DIR%/work/state.xml</stateConfigFile>
				<stateLocations type="file">
					<stateLocation>
						<readLocation>Augusta.p02.rst</readLocation>
						<writeLocation>Augusta.p02.rst</writeLocation>
					</stateLocation>
				</stateLocations>
				<stateSelection>
					<warmState>
						<stateSearchPeriod unit="day" start="-10" end="-1"/>
					</warmState>
				</stateSelection>
			</exportStateActivity>
			<exportTimeSeriesActivity>
				<exportFile>%ROOT_DIR%/input/input.xml</exportFile>
				<timeSeriesSets>
					<timeSeriesSet>
						<moduleInstanceId>HECRAS_KENNEBEC_Preprocessing_UpdateStates</moduleInstanceId>
						<valueType>scalar</valueType>
						<parameterId>QINE</parameterId>
						<locationId>SIDM1ME</locationId>
						<timeSeriesType>simulated historical</timeSeriesType>
						<timeStep unit="hour" multiplier="1"/>
						<relativeViewPeriod unit="hour" end="0"/>
						<readWriteMode>read only</readWriteMode>
					</timeSeriesSet>
					<timeSeriesSet>
						<moduleInstanceId>HECRAS_KENNEBEC_Preprocessing_UpdateStates</moduleInstanceId>
						<valueType>scalar</valueType>
						<parameterId>STID</parameterId>
						<locationId>CASM1ME</locationId>
						<timeSeriesType>simulated historical</timeSeriesType>
						<timeStep unit="hour" multiplier="1"/>
						<relativeViewPeriod unit="hour" end="0"/>
						<readWriteMode>read only</readWriteMode>
					</timeSeriesSet>
				</timeSeriesSets>
			</exportTimeSeriesActivity>
			<exportDataSetActivity>
				<moduleInstanceId>HECRAS_KENNEBEC_UpdateStates</moduleInstanceId>
			</exportDataSetActivity>
			<exportParameterActivity>
				<fileName>params.xml</fileName>
				<moduleInstanceId>HECRAS_KENNEBEC_UpdateStates</moduleInstanceId>
			</exportParameterActivity>
			<exportRunFileActivity>
				<exportFile>%ROOT_DIR%/run_info.xml</exportFile>
				<properties>
	                        <string key="hecRasProjectFile" value="%ROOT_DIR%/work/Augusta.prj"/>
	                        <string key="hecRasBinDirectory" value="$HECRASBINDIR$"/>
	                        <string key="outputTimeSeriesParametersFilter" value="^STAGE$^STAGE$$|^FLOW$^FLOW$$"/>
	                        <string key="outputLongtitudionalProfileParametersFilter" value="^STAGE$$|Hydr Radius L"/>
	                        <string key="logLevel" value="DEBUG"/>
	                        <string key="skipBinaryOutput" value="false"/>
                                <string key="hecRasEnvironment" value="LD_LIBRARY_PATH=$HECRASBINDIR$:$LD_LIBRARY_PATH"/>
				</properties>
			</exportRunFileActivity>
		</exportActivities>
		<executeActivities>
			<executeActivity>
				<command>
					<className>nl.wldelft.fews.adapter.hec.HecRasAdapter</className>
					<binDir>$HECRASBINDIR$</binDir>
				</command>
				<arguments>
					<argument>%ROOT_DIR%/run_info.xml</argument>
				</arguments>
				<timeOut>1500000</timeOut>
			</executeActivity>
		</executeActivities>
		<importActivities>
			<importStateActivity>
				<stateConfigFile>%ROOT_DIR%/work/state.xml</stateConfigFile>
				<synchLevel>20</synchLevel>
			</importStateActivity>
			<importTimeSeriesActivity>
				<importFile>%ROOT_DIR%/output/output.xml</importFile>
				<timeSeriesSets>
					<timeSeriesSet>
						<moduleInstanceId>HECRAS_KENNEBEC_UpdateStates</moduleInstanceId>
						<valueType>scalar</valueType>
						<parameterId>SSTG</parameterId>
						<locationId>AUGM1ME</locationId>
						<timeSeriesType>simulated historical</timeSeriesType>
						<timeStep unit="hour" multiplier="1"/>
						<readWriteMode>add originals</readWriteMode>
					</timeSeriesSet>
					<timeSeriesSet>
						<moduleInstanceId>HECRAS_KENNEBEC_UpdateStates</moduleInstanceId>
						<valueType>scalar</valueType>
						<parameterId>SQIN</parameterId>
						<locationId>AUGM1ME</locationId>
						<timeSeriesType>simulated historical</timeSeriesType>
						<timeStep unit="hour" multiplier="1"/>
						<readWriteMode>add originals</readWriteMode>
					</timeSeriesSet>
				</timeSeriesSets>
			</importTimeSeriesActivity>
		</importActivities>
	</activities>
</generalAdapterRun>

...

Code Block
xml
xml
titleExample of the FEWS-PI containing DSS output of the HEC-RAS model
<TimeSeries
    xsi:schemaLocation="http://www.wldelft.nl/fews/PI http://fews.wldelft.nl/schemas/version1.0/pi-schemas/pi_timeseries.xsd"
    version="1.2" xmlns="http://www.wldelft.nl/fews/PI" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <timeZone>0.0</timeZone>
    <series>
        <header>
            <type>instantaneous</type>
            <locationId>CT RIVER R1/0.00</locationId>
            <parameterId>FLOW</parameterId>
            <timeStep unit="second" multiplier="3600"/>
            <startDate date="2008-11-06" time="00:00:00"/>
            <endDate date="2008-11-08" time="00:00:00"/>
            <missVal>NaN</missVal>
            <units>CFS</units>
        </header>
        <event date="2008-11-06" time="00:00:00" value="24.38823" flag="0"/>
        <event date="2008-11-06" time="01:00:00" value="-5.8442316" flag="0"/>
        <event date="2008-11-06" time="02:00:00" value="68.705124" flag="0"/>
        <event date="2008-11-06" time="03:00:00" value="391.09784" flag="0"/>
        ...
        <event date="2008-11-07" time="23:00:00" value="438.6425" flag="0"/>
        <event date="2008-11-08" time="00:00:00" value="-5259.6562" flag="0"/>
    </series>
    <series>
        <header>
            <type>instantaneous</type>
            <locationId>CT RIVER R1/0.00</locationId>
            <parameterId>STAGE</parameterId>
            <timeStep unit="second" multiplier="3600"/>
            <startDate date="2008-11-06" time="00:00:00"/>
            <endDate date="2008-11-08" time="00:00:00"/>
            <missVal>NaN</missVal>
            <units>FEET</units>
        </header>
        <event date="2008-11-06" time="00:00:00" value="5.0" flag="0"/>
        <event date="2008-11-06" time="01:00:00" value="5.0" flag="0"/>
        <event date="2008-11-06" time="02:00:00" value="5.0" flag="0"/>
        <event date="2008-11-06" time="03:00:00" value="5.0" flag="0"/>
        ...

Running model from FEWS

Beste Practise Considerations

The HEC-RAS adapter requires quite some synergy between FEWS, Java and the actual HEC-RAS software versions. While a FEWS General Adapter config that uses embedded Java adapters is technically preferred above a custom JRE, it very sensitive to any software update. From past implementations we experience that using old models that run with older RAS versions, do not run anymore with actual adapter and Java versions. Therefore from an organizational and robustness perspective, it is preferred to have your both softwares as independent as possible, so with a custom JRE.

So instead of using the below default config:

Code Block
languagexml
titleEmbedded GA execute activity, running with FEWS 2016.02 and HEC-RAS v5
<executeActivity>
	<command>
		<className>nl.wldelft.fews.adapter.hec.HecRasAdapter</className>
    		<binDir>$HECRASBINDIR$</binDir>
	</command>
	<arguments>
    		<argument>%ROOT_DIR%/run_info.xml</argument>
	</arguments>
 	<timeOut>3600000</timeOut>
</executeActivity> 

one can better use a config like:

Code Block
languagexml
titleIndependent GA execute activity running with FEWS 2023.02 and HEC-RAS v5
<executeActivity>
	<command>
		<className>nl.wldelft.fews.adapter.hec.HecRasAdapter</className>
		<binDir>$HECRASBINDIR$</binDir>
		<!-- use old Java 8, while 2023.02 uses 11-->
		<customJreDir>$CUSTOMJRE_64B_DIR$</customJreDir>
 		<!-- in case of custom JRE, pass correct default Parser definition-->
         <jvmArg>-Dorg.xml.sax.parser=com.sun.org.apache.xerces.internal.parsers.SAXParser</jvmArg>
	</command>
	<arguments>
		<argument>%ROOT_DIR%/run_info.xml</argument>
	</arguments>
     <console>
   		<!-- dump console in txt file, so in case of a crash, you see what happend-->
         <redirectToLogFile>%ROOT_DIR%/log/adapter_console_logging.txt</redirectToLogFile>
	</console>
	<timeOut>3600000</timeOut>
</executeActivity>


Running model from FEWS

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