Page tree
Skip to end of metadata
Go to start of metadata

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 modes 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.

An October 2019 development has made parameter updating of elements in the *.basin and *.met files possible. See the paragraph on parameter updating 

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 various configurations (December 2010):

  1. FEWS Po (Paolo Reggiani)
  2. FEWS Georgia (Paolo Reggiani)
  3. Sudan FEWS (Jan Verkade)
  4. FEWS Trinidad (Matthijs Lemans)

An improved version of the adapter has been developed and is implemented in the following configurations:

  1. FEWS CEMIG (Jan Talsma, Dirk Schwanenberg)
  2. FEWS Salto Grande (Jan Talsma, Otto de Keizer)
  3. FEWS Colombia (Micha Werner, Otto de Keizer)
  4. Bandon FFS (Jan Verkade, in co-operation with University College Cork)
  5. Mura Drava FFS (Jan Verkade, in co-operation with the University of Zagreb)
  6. FEWS Sava (Klaas-Jan van Heeringen, Daniel Tollenaar, Arjen Haag)

In October 2019 the HEC-HMS adapter was improved with Parameter Updating capabilities for the preAdapter. This adapter is implemented in the following configurations:

  1. FEWS Manitoba Hydro (Ivo Miltenburg, Ben Balk)

Download

Download of the model adapter is not available here: please 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-HMS have been shown below.

Note that only binary and configuration files relevant to the HEC-HMS 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
    |   |
    |   \---ModuleParFiles
    |            HEC-HMS_Parameters.xml.........(optional) hechms (template) parameter files, transported to Models directory by a exportParameterActivity in the GA
    |
    \---Models
        \---hec/hechms
            +---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:

<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>
		<piVersion>1.8</piVersion>
		<rootDir>$REGION_HOME$/Modules/HEC-HMS</rootDir>
		<workDir>$REGION_HOME$/Modules/HEC-HMS/bin</workDir>
		<exportDir>%ROOT_DIR%/$CATCHMENT$/piInputTimeSeries</exportDir>
		<exportDataSetDir>%ROOT_DIR%</exportDataSetDir>
		<exportIdMap>IdExportHEC-HMS</exportIdMap>
		<exportUnitConversionsId>ExportHEC-HMS</exportUnitConversionsId>
		<importDir>%ROOT_DIR%/work/piOutputTimeSeries</importDir>
		<importIdMap>IdImportHEC-HMS</importIdMap>
		<dumpFileDir>$GA_DUMPFILEDIR$</dumpFileDir>
		<dumpDir>%ROOT_DIR%/$CATCHMENT$</dumpDir>
		<diagnosticFile>%ROOT_DIR%/$CATCHMENT$/piDiagnostic.xml</diagnosticFile>
		<missVal>-999</missVal>
		<timeZone>
			<timeZoneOffset>-06:00</timeZoneOffset>
		</timeZone>
	</general>
	<activities>
		<startUpActivities>
			<purgeActivity>
				<filter>%ROOT_DIR%/$CATCHMENT$/piInputTimeSeries/*.*</filter>
			</purgeActivity>
			<purgeActivity>
				<filter>%ROOT_DIR%/$CATCHMENT$/piOutputTimeSeries/*.*</filter>
			</purgeActivity>
			<purgeActivity>
				<filter>%ROOT_DIR%/$CATCHMENT$/basinStates/*.*</filter>
			</purgeActivity>
			<purgeActivity>
				<filter>%ROOT_DIR%/$CATCHMENT$/results/*.*</filter>
			</purgeActivity>
			<purgeActivity>
				<filter>%ROOT_DIR%/$CATCHMENT$/*.*</filter>
			</purgeActivity>
		</startUpActivities>
		<exportActivities>
			<!--Export States-->
			<exportStateActivity>
				<moduleInstanceId>HEC-HMS_$CATCHMENT$_Update</moduleInstanceId>
				<stateExportDir>%ROOT_DIR%/$CATCHMENT$/basinStates</stateExportDir>
				<stateConfigFile>%ROOT_DIR%/$CATCHMENT$/state.xml</stateConfigFile>
				<stateLocations type="file">
					<stateLocation>
						<readLocation>$HMSproject$_state.state</readLocation>
						<writeLocation>$HMSproject$_state.state</writeLocation>
					</stateLocation>
				</stateLocations>
				<stateSelection>
					<warmState>
						<stateSearchPeriod unit="day" start="$STARTTIME$" end="-1"/>
					</warmState>
				</stateSelection>
			</exportStateActivity>
			<!--Export times eries-->
			<exportTimeSeriesActivity>
				<exportFile>%ROOT_DIR%/$CATCHMENT$/piInputTimeSeries/input.xml</exportFile>
				<timeSeriesSets>
					<timeSeriesSet>
						<moduleInstanceId>Grid_Sampling_HEC-HMS_$CATCHMENT$_Update</moduleInstanceId>
						<valueType>scalar</valueType>
						<parameterId>PC.obs</parameterId>
						<locationSetId>HEC-HMS_$CATCHMENT$_precip_input</locationSetId>
						<timeSeriesType>simulated historical</timeSeriesType>
						<timeStep unit="hour" multiplier="6"/>
						<relativeViewPeriod unit="day" end="0" startOverrulable="true"/>
						<readWriteMode>read only</readWriteMode>
					</timeSeriesSet>
					<timeSeriesSet>
						<moduleInstanceId>Grid_Sampling_HEC-HMS_$CATCHMENT$_Update</moduleInstanceId>
						<valueType>scalar</valueType>
						<parameterId>TA.obs</parameterId>
						<locationSetId>HEC-HMS_$CATCHMENT$_temperature_input</locationSetId>
						<timeSeriesType>simulated historical</timeSeriesType>
						<timeStep unit="hour" multiplier="6"/>
						<relativeViewPeriod unit="day" end="0" startOverrulable="true"/>
						<readWriteMode>read only</readWriteMode>
					</timeSeriesSet>
					<timeSeriesSet>
						<moduleInstanceId>Preprocess_HEC-HMS_$CATCHMENT$_Update</moduleInstanceId>
						<valueType>scalar</valueType>
						<parameterId>QR.obs</parameterId>
						<locationSetId>HEC-HMS_$CATCHMENT$_flow_input</locationSetId>
						<timeSeriesType>simulated historical</timeSeriesType>
						<timeStep unit="hour" multiplier="6"/>
						<relativeViewPeriod unit="day" end="0" startOverrulable="true"/>
						<readWriteMode>read only</readWriteMode>
					</timeSeriesSet>
					<timeSeriesSet>
						<moduleInstanceId>Preprocess_HEC-HMS_$CATCHMENT$_Update</moduleInstanceId>
						<valueType>scalar</valueType>
						<parameterId>HG.obs</parameterId>
						<locationSetId>HEC-HMS_$CATCHMENT$_stage_input</locationSetId>
						<timeSeriesType>simulated historical</timeSeriesType>
						<timeStep unit="hour" multiplier="6"/>
						<relativeViewPeriod unit="day" end="0" startOverrulable="true"/>
						<readWriteMode>read only</readWriteMode>
					</timeSeriesSet>
				</timeSeriesSets>
			</exportTimeSeriesActivity>
			<!--Export Model Data Set (.basin, .contol, .gage, .hms, .pdata, .run, .script, .met, .dss etc.)-->
			<exportDataSetActivity>
				<moduleInstanceId>HEC-HMS_$CATCHMENT$_Update</moduleInstanceId>
			</exportDataSetActivity>
			<!--(Optional) Export parameter files-->
			<exportParameterActivity>
				<fileName>%ROOT_DIR%/$CATCHMENT$/$CATCHMENT$_Basin_Subbasin_params.xml</fileName>
				<templateLocationLooping>
					<locationModelLoop>
						<locationSetId>HEC-HMS_$CATCHMENT$_subbasin_params</locationSetId>
						<model>HECHMS_B_SB</model>
					</locationModelLoop>
				</templateLocationLooping>
				<moduleInstanceId>HEC-HMS_Parameters</moduleInstanceId>
			</exportParameterActivity>
			<exportParameterActivity>
				<fileName>%ROOT_DIR%/$CATCHMENT$/$CATCHMENT$_Basin_Reach_params.xml</fileName>
				<templateLocationLooping>
					<locationModelLoop>
						<locationSetId>HEC-HMS_$CATCHMENT$_reach_params</locationSetId>
						<model>HECHMS_B_R</model>
					</locationModelLoop>
				</templateLocationLooping>
				<moduleInstanceId>HEC-HMS_Parameters</moduleInstanceId>
			</exportParameterActivity>
			<exportParameterActivity>
				<fileName>%ROOT_DIR%/$CATCHMENT$/$CATCHMENT$_Met_SnowMelt_params.xml</fileName>
				<templateLocationLooping>
					<locationModelLoop>
						<locationSetId>HEC-HMS_$CATCHMENT$_snowmelt_method_temperature_index_params</locationSetId>
						<model>HECHMS_M</model>
					</locationModelLoop>
				</templateLocationLooping>
				<moduleInstanceId>HEC-HMS_Parameters</moduleInstanceId>
			</exportParameterActivity>
			<!--Export RunFile (Params related keys are optional)-->
			<exportRunFileActivity>
				<exportFile>%ROOT_DIR%/$CATCHMENT$/RunInfo.xml</exportFile>
				<properties>
					<string key="hmsProjectFile" value="%ROOT_DIR%/$CATCHMENT$/$HMSproject$.hms"/>
					<string key="hmsScriptFile" value="%ROOT_DIR%/$CATCHMENT$/$HMSproject$.script"/>
					<string key="Basin_Subbasin_Params_File" value="$CATCHMENT$_Basin_Subbasin_params.xml"/>
					<string key="Basin_Reach_Params_File" value="$CATCHMENT$_Basin_Reach_params.xml"/>
					<string key="Precipitation_SnowMelt_Params_File" value="$CATCHMENT$_Met_SnowMelt_params.xml"/>
				</properties>
			</exportRunFileActivity>
		</exportActivities>
		<executeActivities>
			<executeActivity>
				<!--Run the HEC-HMS preAdapter-->
				<command>
					<className>nl.wldelft.fews.adapter.hec.HmsPreAdapter</className>
					<binDir>$REGION_HOME$/Modules/HEC-HMS/binAdapter</binDir>
					<customJreDir>$CUSTOMJRE_32B_DIR$</customJreDir>
				</command>
				<arguments>
					<argument>%ROOT_DIR%/$CATCHMENT$/RunInfo.xml</argument>
				</arguments>
				<timeOut>600000</timeOut>
			</executeActivity>
			<!--Run the HEC-HMS model-->
			<executeActivity>
				<command>
					<executable>$REGION_HOME$/Modules/HEC-HMS/bin/HEC-HMS.cmd</executable>
				</command>
				<arguments>
					<argument>-s</argument>
					<argument>%ROOT_DIR%/$CATCHMENT$/$HMSproject$.script</argument>
					<argument>&gt; NULL</argument>
				</arguments>
				<logFile>
					<file>%ROOT_DIR%\$CATCHMENT$\$CATCHMENT$_HEC.log</file>
					<errorLinePattern>*ERROR*</errorLinePattern>
					<warningLinePattern>*WARNING*</warningLinePattern>
					<infoLinePattern>*NOTE*</infoLinePattern>
					<debugLinePattern>*DEBUG*</debugLinePattern>
				</logFile>
				<timeOut>1800000</timeOut>
				<ignoreDiagnostics>false</ignoreDiagnostics>
			</executeActivity>
			<!--Run the HEC-HMS postAdapter-->
			<executeActivity>
				<command>
					<className>nl.wldelft.fews.adapter.hec.HmsPostAdapter</className>
					<binDir>$REGION_HOME$/Modules/HEC-HMS/binAdapter</binDir>
					<customJreDir>$CUSTOMJRE_32B_DIR$</customJreDir>
				</command>
				<arguments>
					<argument>%ROOT_DIR%/$CATCHMENT$/RunInfo.xml</argument>
				</arguments>
				<timeOut>600000</timeOut>
				<ignoreDiagnostics>true</ignoreDiagnostics>
			</executeActivity>
		</executeActivities>
		<importActivities>
			<!--Import States (Update runs)-->
			<importStateActivity>
				<stateFile>
					<importFile>%ROOT_DIR%/$CATCHMENT$/basinStates/$HMSproject$_out_state.state</importFile>
					<relativeExportFile>$HMSproject$_state.state</relativeExportFile>
				</stateFile>
				<expiryTime multiplier="30" unit="day"/>
			</importStateActivity>
			<!--Import Time Series-->
			<importTimeSeriesActivity>
				<importFile>%ROOT_DIR%/$CATCHMENT$/piOutputTimeSeries/simulation.xml</importFile>
				<timeSeriesSets>
					<timeSeriesSet>
						<moduleInstanceId>$MODULE_INSTANCE_ID$</moduleInstanceId>
						<valueType>scalar</valueType>
						<parameterId>QR.sim</parameterId>
						<locationSetId>HEC-HMS_$CATCHMENT$_flow_output</locationSetId>
						<timeSeriesType>simulated historical</timeSeriesType>
						<timeStep unit="hour" multiplier="6"/>
						<readWriteMode>add originals</readWriteMode>
					</timeSeriesSet>
					<timeSeriesSet>
						<moduleInstanceId>$MODULE_INSTANCE_ID$</moduleInstanceId>
						<valueType>scalar</valueType>
						<parameterId>HG.sim</parameterId>
						<locationSetId>HEC-HMS_$CATCHMENT$_stage_output</locationSetId>
						<timeSeriesType>simulated historical</timeSeriesType>
						<timeStep unit="hour" multiplier="6"/>
						<readWriteMode>add originals</readWriteMode>
					</timeSeriesSet>
				</timeSeriesSets>
			</importTimeSeriesActivity>
		</importActivities>
	</activities>
</generalAdapterRun>

The hechms files (.basin, .contol, .gage, .hms, .pdata, .run, .script, .met, .dss etc.)are saved in the /Config/ModuleDataSet directory. These are copied to the /Model/hechms/<model> directory during the exportDataSet activity in the General Adapter file.

HEC-HMS Parameter updating

A development (October 2019) for the HEC-HMS adapter has made it possible to update parameters. The following parameter updates are supported:

  • All parameters for the Subbasin elements in the *.basin HEC-HMS file
  • All parameters for the Reach elements in the *.basin HEC-HMS file
  • All parameters for the Snow Method Parameter element in the *.met HEC-HMS file

To use this capability the various FEWS configuration is required.

  1. The correct HEC-HMS binAdapter needs to be placed in \Config\ModuleDataSetFiles\HEC-HMS_bin.zip (binAdapter directory) and the binaries need to be exported to the Modules.
  2. The subbasins/reaches (from the model *.basin file) and the snowmelt method (in the model *.met file) from the (multiple) HEC-HMS models need to be defined as locations with their own unique (FEWS) locationId. The locationId's under which they are known in the HEC-HMS model need to extracted from the *.basin file and stored as an attribute, so they can be exported correctly. Note that the pre adapter is case insensitive: when a subbasin in the *.basin file has the id 'location a', the pre adapter will match it with a paramter defined as 'LOCATION A'.
  3. For each of the locations where parameter updating is required, the parameter values need to configured as attributes (define a .csv file and create a suitable locationSet)
  4. To be able to see the parameters for the various HEC-HMS models in the Delft-FEWS interface, the ModifierTypes.xml can be extended with a locationAttributeModifier section as can be seen below. The modifier can be linked with the relevant HEC-HMS model run Topology Nodes

    ModifierType configuration for HEC-HMS parameters

  5. A (template) ModuleParFile configuration is required, to allow for Parameter updating by the pre adapter. In the GA, under <exportParameterActivity> the modulePar template file is referenced, providing the 'model' and a 'locationSet'. For each of the locations in the locationSet, the '@attributes'@ need to be defined. An example f the configuration can be seen below

    <?xml version="1.0" encoding="UTF-8"?>
    <parameters xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.wldelft.nl/fews/PI" xsi:schemaLocation="http://www.wldelft.nl/fews/PI http://fews.wldelft.nl/schemas/version1.0/pi-schemas/pi_modelparameters.xsd" version="1.5">
    	<modifierType>HECHMS_Parameters</modifierType>
    	<group id="HECHMS_Basin_Subbasin_Parameters" name="HEC-HMS Basin Subbasin Parameters">
    		<locationId>@hec_ext_subbasin_id@</locationId>
    		<model>HECHMS_B_SB</model>
    		<parameter id="Time of Concentration">
    			<intValue>@time_of_concentration@</intValue>
    		</parameter>
    		<parameter id="Storage Coefficient">
    			<intValue>@storage_coefficient@</intValue>
    		</parameter>
    	</group>
    	<group id="HECHMS_Basin_Reach_Parameters" name="HEC-HMS Basin Reach Parameters">
    		<locationId>@hec_ext_reach_id@</locationId>
    		<model>HECHMS_B_R</model>
    		<parameter id="Muskingum K">
    			<intValue>@muskingum_k@</intValue>
    		</parameter>
    	</group>
    	<group id="HECHMS_Met_Parameters" name="HEC-HMS Met Parameters">
    		<locationId>@hec_ext_snowmelt_method_id@</locationId>
    		<model>HECHMS_M</model>
    		<parameter id="Base Temperature">
    			<dblValue>@base_temperature@</dblValue>
    		</parameter>
    		<parameter id="Snow vs Rain Temperature">
    			<dblValue>@snow_vs_rain_temperature@</dblValue>
    		</parameter>
    		<parameter id="Dry Melt Rain Rate Limit">
    			<dblValue>@dry_melt_rain_limit@</dblValue>
    		</parameter>
    		<parameter id="Rain Melt Rate">
    			<dblValue>@rain_melt_rate@</dblValue>
    		</parameter>
    	</group>
    </parameters>
    
    

    An example of the resulting parameter file for the Basin - Subbasin parameters that will be exported to the HEC-HMS modules directory:

    Example of NRB_Basin_Subbasin_params.xml

  6. To instruct the preAdapter to update parameters, some specific keys need to be provided to the runInfo file. In the exportRunFileActivity in the GA we require the following keys for parameter updating:


    1. hmsProjectFile
      reference the model *.hms file. This file contains the references to the filenames of the ‘Precipitation’ file (*.met) and the Basin file (*.basin)

    2. hmsScriptFile
      not required for the parameter updating, but it is required for the adapter in general

    3. Basin_Subbasin_Params_File
      When we want to update subbasin parameters in the *.basin file, we need to define this Key and provide the reference to the params file that contains the location/parameter combinations to be updated

    4. Basin_Reach_Params_File
      When we want to update reach parameters in the *.basin file, we need to define this Key and provide the reference to the params file that contains the location/parameter combinations to be updated

    5. Precipitation_SnowMelt_Params_File
      When we want to update Snowmelt Method parameters in the *.met file, we need to define this Key and provide the reference to the params file that contains the location/parameter combinations to be updated
      Note that is is required that the locationId of the Snowmelt Method is equal to the method as defined in the HEC-HMS *.met file 

    Example of NRB_Met_SnowMelt_params.xml for the 'Temperature Index' method

The pre adapter is instructed by the defined properties to update the parameters, using the exported params files. 

  • The check for locationId's is case insensitive. Info messegaes will be written by the pre adapter specifying which locations/parameters were updated.
  • When a location is defined in the params file, but does not exist in the HEC-HMS file, a warning is produced.  
  • When a parameter is defined in the params file, but does not exist in the HEC-HMS file, a warning is produced.