...
An October 2019 development has made parameter updating of elements in the *.basin and *.met files possible. See the paragraph on parameter updating . This adapter version is based on 32-bit binaries and Java 8 and was developed for HEC-HMS models with version 4.2.1.
In August 2021 the HEC-HMS adapter has been updated to work with HEC-HMS models of version 4.8. This adapter is based on 64-bit binaries and Java 11. This adapter version is not backwards compatible with 32-bit HEC-HMS models (v. 4.4.1 and earlier) and has not been tested with 64-bit HEC-HMS model before v. 4.8 (4.5/4.6/4.7).
Operating HEC-HMS Model and FEWS Adapter
Compatibility
A note on the compatibilty of the HEC-HMS adapter: Most adapter developments are done under projects for clients with a specific HEC-HMS model version. The functionality of the updated adapter will be verified for the new HEC-HMS model version. Eventhough care is taken not to break backwards compatibility, there is no guarantee that a newer adapter version will work on older HEC-HMS models.
The HEC-HMS adapter that was created in October 2019 is based on 32-bit binaries/libraries and runs on Java 8. This adapter was developed for HEC-HMS models with version 4.2.1 and was tested against HEC-HMS model of that version.
In August 2021 the HEC-HMS adapter has been updated to work with HEC-HMS models of version 4.8. Since HEC-HMS was updated to a 64-bit application, running on Java 11 since version 4.5, the model adapter had to be updated to work with 64-bit binaries/libraries and run on Java 11. This adapter version is not backwards compatible with 32-bit HEC-HMS models (v. 4.4.1 and earlier). This adapterhas not been tested with 64-bit HEC-HMS models before v. 4.8 (4.5/4.6/4.7).
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 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.
...
| No Format |
|---|
+---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/Modules
\---hec/hechms/HEC-HMS
+---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
|
...
| Code Block | ||||
|---|---|---|---|---|
| ||||
<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_Reach_params.xml"/> <string key="Precipitation_SnowMelt_Params_File" value="$CATCHMENT$_BasinMet_ReachSnowMelt_params.xml"/> <string key="Precipitation_SnowMelt_Subbasin_Params_File" value="$CATCHMENT$_Met_SnowMelt_Subbasin_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>> 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/hechmsHEC-HMS/<model> directory during the exportDataSet activity in the General Adapter file.
- Please note that running the pre/post adapter based on 32-bit binaries (for HEC-HMS model version 4.2.1, developed in October 2019) requires the definition of a <customJreDir>$CUSTOMJRE_32B_DIR$</customJreDir> element, as Delft-FEWS itself is 64-bit.
- Running the pre/post adapter based on 64-bit binaries (for HEC-HMS model version 4.8, developed in August 2021) does not require the definition of a custom java, as the Delft-FEWS java version can be used.4.8, developed in August 2021) does not require the definition of a custom java, as the Delft-FEWS java version will be used.
Also note that the HEC-HMS adapter does not (completely) convert the HEC-HMS model run log files to pi-xml diagnostics files. Instead, the configuration has been set up to directly parse the HEC log file
| Anchor | ||||
|---|---|---|---|---|
|
A development (October 2019) for the HEC-HMS adapter (for HEC-HMS models with version 4.2.1) has made it possible to update parameters. The following parameter updates are supported:
...
An new (August 2021) 64-bit HEC-HMS adapter (for HEC-HMS models with version 4.8) retains the original parameter updating functionality, but has this extended withsupport with support for he following parameter updates:
...
- 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.
- 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'.
- 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)
- 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
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 of the configuration can be seen below
Code Block xml xml <?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 Limit"> <dblValue>@dry_melt_rain_limit@</dblValue> </parameter> <parameter id="Rain Melt Rate"> <dblValue>@dry<dblValue>@rain_melt_rain_limit@<rate@</dblValue> </parameter> <parameter id="RainMelt Rate ATI-Melt Rate Table Name"> <dblValue>@rain<stringValue>@melt_rate ati_melt_rate_table_rate@<name@</dblValue>stringValue> </parameter> </group> <group id="HECHMS_Met_Subbasin_Parameters" name="HEC-HMS Met Subbasin Parameters"> <locationId>@hec_ext_snowmelt_loc_id@</locationId> <model>HECHMS_M_SB</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> <parameter id="Melt Rate ATI-Melt Rate Table Name"> <stringValue>@melt_rate ati_melt_rate_table_name@</stringValue> </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:
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:
hmsProjectFile
reference the model *.hms file. This file contains the references to the filenames of the ‘Precipitation’ file (*.met) and the Basin file (*.basin)hmsScriptFile
not required for the parameter updating, but it is required for the adapter in generalnot required for the parameter updating, but it is required for the adapter in generalBasin_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 updatedBasin_ReachBasin_Subbasin_Params_File
When we want to update subbasin 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 updatedBasinPrecipitation_ReachSnowMelt_Params_File
When we want to update reach globally defined Snowmelt Method parameters in the *.basin 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
Precipitation_SnowMelt_Subbasin_Params_File
When we want to update globally subbasin specific defined Snowmelt Method parameters in the *.met file.met file (available in HEC-HMS model version 4.8), 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
Precipitation_SnowMelt_Subbasin_Params_File
When we want to update subbasin specific defined Snowmelt Method parameters in the *.met file (available in HEC-HMS model version 4.8), 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 Parameter group is equal to the subbasin location as defined in the HEC-HMS *.met file
The pre adapter is instructed by the defined properties to update the parameters, using the exported params files.
...
that contains the location/parameter combinations to be updated
Note that is is required that the locationId of the Snowmelt Parameter group is equal to the subbasin location as defined in the HEC-HMS *.met file
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.
Post Adapter
The Post Adapter is responsible for parsing the HEC output/results files (DSS format) and convert it to a pi-xml format.
The HEC-HMS 4.8 model seems to store the timeseries in the DSS files “broken up” per month. This is different as compared to the 4.2.1 model version. When the Post Adapter extracts the timeseries from the results DSS file to a simulation.xml for Delft-FEWS to import, the timeseries are also “broken up” in monthly pieces in the xml file. This is no problem for the Delft-FEWS import routine and all data is imported correctly into the application.
...