Contents
Introduction
Two modes of working of HEC-HMS are supported by the General adapter. Given a calibrated model, the modes of working are:
- Continuous mode, with state handling, suitable for operational forecasting;
- Event mode, without state handeling;
The technical implementations for both modes of working are quite similar. However it is important that models to be implemented in continuous mode, have also been calibrated for such mode. The same holds for event mode.
Present documentation will describe both mode of operation. Calibration is not a subject of this documentation, for details about operating model in the calibration mode please check standard HEC-HMS documentation.
Operating HEC-HMS Model and FEWS Adapter
The HEC-HMS model provides the compute engine for running a rainfall runoff model schematization for a basin or a system of basins. the modelling options include also routing. The HEC-HMS Adapter forms the interface between the FEWS Forecasting Shell and the HEC-HMS model.
The HEC-HMS compute engine is, as its name suggests, the component that actually performs the HEC-HMS simulation. This simulation is controlled from the FEWS Adapter, and all run time data such as initial and boundary conditions are passed through the adapter from and to the FEWS Forecasting Shell.
Applications
An earlier version of the HEC-HMS adapter has been implemented in three configurations (December 2010):
- FEWS Po (Paolo Reggiani)
- FEWS Georgia (Paolo Reggiani)
- FEWS Sudan (Jan Verkade)
- FEWS Trinidad (Matthijs Lemans)
Recently (July 2013), the adapter has been improved. The new adapter has been (or will) implemented in the following configurations:
- FEWS CEMIG (Jan Talsma, Dirk Schwanenberg)
- FEWS Salto Grande (Jan Talsma, Otto de Keizer)
- FEWS Colombia (Micha Werner, Otto de Keizer)
- FEWS Sava (Klaas-Jan van Heeringen, Daniel Tollenaar, Arjen Haag)
Download
Download of the model adapter is not available here: pls e-mail to Delft-FEWS Product Management for more information.
A tutorial of how to add a HEC-HMS model as an adapter in FEWS is attached.
Interface between FEWS and HEC-HMS
The FEWS Adapter for HEC-HMS forms the interface between the FEWS Forecasting Shell and the HEC-HMS model. The adapter accepts the request from the Forecasting Shell to run HEC-HMS, 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-HMS run has been completed, relevant results are passed back to the Forecasting Shell in the form of the standardized XML interface format.
The FEWS Adapter allows running of HEC-HMS by FEWS. The FEWS Adapter should be considered as a thin communication (software) layer on top the existing HEC-HMS engine. For more details about general structure of the General Adapter please check 05 General Adapter Module.
ID Mapping
The location parameters used in FEWS can be coupled to HEC-HMS DSS path names through ID-mapping. The configuration files for ID-mapping should be created separately for each HEC-HMS 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
| <FEWS binaries>
\---FEWS_sa
|
+---Config
| +---ColdStateFiles
| | HECHMS_UpdateStates Default.zip....cold state files
| |
| +---IdMapFiles
| | IdExportHECHMS.xml
| | IdImportHECHMS.xml.......................... custom mappings for the HEC-HMS variables and locations
| |
| +---ModuleConfigFiles
| | HECHMS_Forecast.xml
| | HECHMS_Update.xml............ main configuration file of the adapter
| |
| \---ModuleDataSetFiles
| HECHMS_model.zip.........zipped hechms files, transported to Models directory
|
\---Models
\---hec/hecras
+---bin........................................ directory which contains all HEC-HMS executables for Windows and Linux platforms
|
+---binAdapter................................. directory which contains allHEC-HMS adapter java files
|
\---model
| run_info.xml.......................... a file generated by FEWS containing paths, run options
|
+---basinStates.................................. folder containing the start/end statesinput directory of the adapter, input FEWS-PI time series files
|
+---map
|
+---optimizer
|
|
+---piInputTimeseries.................................... input FEWS-PI time series files
| input.xml
|
+---piOutputTimeseriesoutput................................. output FEWS-PI time series files
| output.xml
|
|
|model files
|.dssfiles/results
|debugfiles
Configuring HEC-HMS adapter
HEC-HMS 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.
A very important part of the configuration is defined under the <exportRunFileActivity> element. It contains path to the HMS project file, location of the HMS binary files and list of variables to be written into the output files. It can also contain the path to HMS script file in property "hmsScriptFile", if it does the pre adapter will replace the path separator \ or / in the call OpenProject("project_name", "d:\dir\another") to \\. . If the path separator already is \\ it will remain unchanged.
Example configuration of the HEC-HMS adapter:
<?xml version="1.0" encoding="UTF-8"?> <!-- edited with XMLSpy v2009 sp1 (http://www.altova.com) by ICT (Stichting Deltares) --> <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> <rootDir>%REGION_HOME%/Modules/hechms</rootDir> <workDir>%ROOT_DIR%/bin</workDir> <exportDir>%ROOT_DIR%/UpperBlueNile/piInputTimeSeries</exportDir> <exportIdMap>IdExportHECHMS</exportIdMap> <importDir>%ROOT_DIR%/UpperBlueNile/piOutputTimeSeries</importDir> <importIdMap>IdImportHECHMS</importIdMap> <dumpFileDir>$GA_DUMPFILEDIR$</dumpFileDir> <dumpDir>%ROOT_DIR%/UpperBlueNile</dumpDir> <diagnosticFile>%ROOT_DIR%/UpperBlueNile/piDiagnostic.xml</diagnosticFile> <missVal>-901.0</missVal> <convertDatum>true</convertDatum> </general> <activities> <startUpActivities> <purgeActivity> <filter>%ROOT_DIR%/UpperBlueNile/piInputTimeSeries/*.*</filter> </purgeActivity> <purgeActivity> <filter>%ROOT_DIR%/UpperBlueNile/piOutputTimeSeries/*.*</filter> </purgeActivity> <purgeActivity> <filter>%ROOT_DIR%/UpperBlueNile/*.ds*</filter> </purgeActivity> </startUpActivities> <exportActivities> <!-- Export state (warm state)--> <exportStateActivity> <moduleInstanceId>UpperBlueNile_HEC-HMS_historical</moduleInstanceId> <stateExportDir>%ROOT_DIR%/UpperBlueNile/basinStates</stateExportDir> <stateConfigFile>%ROOT_DIR%/UpperBlueNile/State.xml</stateConfigFile> <stateLocations type="file"> <stateLocation> <readLocation>UpperBlueNile_hist_state.state</readLocation> <writeLocation>UpperBlueNile_hist_state.state</writeLocation> </stateLocation> </stateLocations> <stateSelection> <warmState> <stateSearchPeriod unit="hour" start="-240" end="-1"/> </warmState> </stateSelection> </exportStateActivity> <!-- Export time series --> <exportTimeSeriesActivity> <description>Export rainfall as input for HecHms model</description> <exportFile>FEWS2DSS.xml</exportFile> <timeSeriesSets> <timeSeriesSet> <moduleInstanceId>Catchments_Aggregate_Precipitation_Historical</moduleInstanceId> <valueType>scalar</valueType> <parameterId>P.merged</parameterId> <locationId>UpperBlueNile</locationId> <timeSeriesType>external historical</timeSeriesType> <timeStep times="21:00"/> <relativeViewPeriod unit="day" startOverrulable="true" end="0"/> <readWriteMode>read only</readWriteMode> </timeSeriesSet> </timeSeriesSets> <checkMissing>true</checkMissing> </exportTimeSeriesActivity> </exportActivities> <executeActivities> <executeActivity> <command> <className>nl.wldelft.fews.adapter.hec.HmsPreAdapter</className> <binDir>%ROOT_DIR%/binAdapter</binDir> </command> <arguments> <argument>%ROOT_DIR%/work/RunInfo.xml</argument> </arguments> <timeOut>120000</timeOut> </executeActivity> <executeActivity> <command> <executable>%WORK_DIR%/HEC-HMS.cmd</executable> </command> <arguments> <argument>-s</argument> <argument>%ROOT_DIR%/UpperBlueNile/UpperBlueNile.script </argument> </arguments> <timeOut>120000</timeOut> </executeActivity> <executeActivity> <command> <className>nl.wldelft.fews.adapter.hec.HmsPostAdapter</className> <binDir>%ROOT_DIR%/binAdapter</binDir> </command> <arguments> <argument>%ROOT_DIR%/work/RunInfo.xml</argument> </arguments> <timeOut>120000</timeOut> </executeActivity> </executeActivities> <importActivities> <!-- Import state --> <importStateActivity> <stateConfigFile>%ROOT_DIR%/UpperBlueNile/piOutputState.xml</stateConfigFile> </importStateActivity> <!-- Import HMS results--> <importTimeSeriesActivity> <description>Import XML file</description> <importFile>simulation.xml</importFile> <timeSeriesSets> <timeSeriesSet> <moduleInstanceId>UpperBlueNile_HEC-HMS_historical</moduleInstanceId> <valueType>scalar</valueType> <parameterId>Q.simulated.historical</parameterId> <locationId>900012</locationId> <timeSeriesType>simulated historical</timeSeriesType> <timeStep times="21:00"/> <readWriteMode>add originals</readWriteMode> </timeSeriesSet> </timeSeriesSets> </importTimeSeriesActivity> </importActivities> </activities> </generalAdapterRun>
The hecras files (.basin, .contol, .gage, .hms, .pdata, .run, .script, .met, .dss etc.)are saved in the /Config/ModuleDataSet directory. These are copied to the /Model/hecras/<model> directory during the exportDataSet activity in the General Adapter file.
