Configuring a general adapter for HSPF

The general adapter is similar to the setup of any general adapter. Two HSPF specific settings are:

the uci file is treated as the State file, because it contains initial conditions in the INIT tables
HSPF is run in OpenDA, therefore OpenDA is run from FEWS, and via OpenDA the WinHSPFLight executable is run.

See examples of the States ExportActivity and the ExecuteActivity below.

ExportActivity States

			<exportStateActivity>
				<moduleInstanceId>HSPF_Basin_update</moduleInstanceId>
				<stateExportDir>%WORK_DIR%/model</stateExportDir>
				<stateConfigFile>%WORK_DIR%/states/state_in.xml</stateConfigFile>
				<stateLocations type="file">
					<stateLocation>
						<readLocation>Basin.uci</readLocation>
						<writeLocation>../work0/Basin.uci</writeLocation>
					</stateLocation>
				</stateLocations>
				...
			</exportStateActivity>

ExecuteActivity

		<executeActivities>
			<!-- Execute HSPF model-->
			<executeActivity>
				<description>OpenDa in Fews adapter</description>
				<command>
					<executable>%REGION_HOME%/Modules/OpenDaInFews/bin/run_openda_in_fews.bat</executable>
				</command>
				<arguments>
					<argument>-m</argument>
					<argument>org.openda.blackbox.wrapper.BBModelFactory</argument>
					<argument>hspfModel.xml</argument>
					<argument>-f</argument>
					<argument>%WORK_DIR%/run_info.xml</argument>
				</arguments>
				<timeOut>4000000</timeOut>
			</executeActivity>
		</executeActivities>

Configuring the HSPF model adapter in OpenDA

There are two OpenDA files that need to be configured. The hspfWrapper.xml and the hspfModel.xml. Only if the intention is to use the HSPF model in a Data Assimilation or Calibration run a more extensive OpenDA setup, that requires additional xml-files, is needed. See http://openda.org/ for more information on OpenDA or for downloading the OpenDA binaries.

hspfWrapper.xml file

This is the wrapper file that describes the run actions (model initialize actions, compute actions, and finalize actions), and the InputOutput objects.

The HSPF adapter:

copies files from the model dir to the work dir as part of the initializeActionsUsingDirClone action
clears the content of the WDM Results and WDM State files with the ClearWdmFile statement, to prevent that old records from a previous run may be present in the file.
runs HSPF with the WinHspfLt.exe and a reference to the uci file as an argument
copies records from the WDM State file to the INIT tables in the uci-file as part of the finalizeActions

An example configuration file is shown below:

<blackBoxWrapperConfig xmlns="http://www.openda.org" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.openda.org http://www.openda.org/schemas/openda_2.2/blackBoxWrapperConfig.xsd">
	<aliasDefinitions defaultKeyPrefix="%" defaultKeySuffix="%">
		<alias key="HSPFDIR" value="../bin"/>
		<alias key="templateDir" value="model"/>
		<alias key="instanceDir" value="work"/>
		<alias key="uciFile" value="Basin.uci"/>
		<alias key="inputParametersFile" value="BasinInput.wdm"/>
		<alias key="stateVariablesFile" value="BasinState.wdm"/>
		<alias key="outputFile" value="BasinResults.wdm"/>
		<alias key="wdmDllFile" value="../../../OpenDaInFews/bin_dll/win32_gfortran/wdm.dll"/>
		<alias key="wdmMessageFile" value="../../../OpenDaInFews/bin_dll/MESSAGE.WDM"/>
		<alias key="startTime" value="dummy"/>
		<alias key="endTime" value="dummy"/>
		<alias key="TimeZone" value="1.0"/>
	</aliasDefinitions>
	<run>
		<initializeActionsUsingDirClone instanceDir="%instanceDir%%instanceNumber%" templateDir="%templateDir%"/>
		<computeActions>
			<!-- delete all existing data in output file -->
			<action className="org.openda.model_hspf.ClearWdmFile" workingDirectory="%instanceDir%%instanceNumber%">
				<arg>%wdmDllFile%</arg>
				<arg>%wdmMessageFile%</arg>
				<arg>%outputFile%</arg>
			</action>
			<action className="org.openda.model_hspf.ClearWdmFile" workingDirectory="%instanceDir%%instanceNumber%">
				<arg>%wdmDllFile%</arg>
				<arg>%wdmMessageFile%</arg>
				<arg>%stateVariablesFile%</arg>
			</action>
			<!-- run model -->
			<action exe="%HSPFDIR%/WinHspfLt.exe" workingDirectory="%instanceDir%%instanceNumber%">
				<arg>%uciFile%</arg>
			</action>
		</computeActions>	
		<finalizeActions>
			<!-- STATES -->
			<action className="org.openda.exchange.iotools.DataCopier">
				<!-- classname of input data object -->
				<arg>-c</arg>
				<arg>org.openda.model_hspf.WdmTimeSeriesDataObject</arg>
				<!-- arguments for input data object -->
				<arg>-a</arg>
				<!-- The first argument should be the pathname of the wdm.dll file (relative to the folder with the input wdm file).
		The second argument should be the pathname of the message file (relative to the folder with the input wdm file).
		The third argument should be the role of this DataObject. Role must be 'output'.
		The fourth argument should be the timeZone that is used by the model (in hours with respect to GMT, between -12 and 12).
		The fifth and sixth arguments should be respectively the startTime and endTime of the model run.
		The (optional) seventh and further arguments should be the location and parameter ids of the time series for which exchange items should be made, if no seventh and further arguments present then exchange items will be created for all time series in the files. -->
				<arg>%wdmDllFile% %wdmMessageFile% output %TimeZone% %startTime% %endTime%</arg>
				<!-- File pathname:
		The pathname of the file containing the data for this DataObject (relative to the instance directory). -->
				<arg>%instanceDir%%instanceNumber%/%stateVariablesFile%</arg>
				<!-- classname of output data object -->
				<arg>-c</arg>
				<arg>org.openda.model_hspf.UciStateDataObject</arg>
				<!-- arguments for output data object -->
				<arg>-a</arg>
				<!-- The first argument should be the absolute state time.
				     The (optional) second argument should be the state time shift in seconds (can be negative). 
				     The timestamp for the state in the .uci file will be equal to (absolute state time) + (state time shift). -->
                <arg>%endTime% -3600</arg>
				<!-- File pathname:
		The pathname of the .uci state file containing the data for this DataObject (relative to the instance directory). -->
				<arg>%instanceDir%%instanceNumber%/%uciFile%</arg>
			</action>		
		</finalizeActions>
	</run>
	<inputOutput>
	<ioObject className="org.openda.model_hspf.UciDataObject">
			<file>%uciFile%</file>
			<id>uciDataObject</id>
			<arg>%TimeZone%</arg>
			<arg>TSTART1</arg>
			<arg>TSTOP1</arg>
			<!-- the following argument is the optional startTimeExtension. This is the startTime of the runPeriod for the HSPF model in hours relative to the startTime of the OpenDA runPeriod. This can be used to extend the runPeriod for the HSPF model (the runPeriod as it will be put in the uci file) with respect to the OpenDA runPeriod. This is useful when there is no restart file (warm state) available for the forecast. In other words the extended period will allow the model to get to a warm state before the forecast starts. -->
			<!---43800 equals 5 years-->
			<!--<arg>0</arg>-->
		</ioObject>
		<ioObject className="org.openda.model_hspf.WdmTimeSeriesIoObject">
			<file>%inputParametersFile%</file>
			<id>inputParametersIoObject</id>
			<arg>%wdmDllFile%</arg>
			<arg>%wdmMessageFile%</arg>
			<arg>input</arg>
			<arg>%TimeZone%</arg>
			<arg>TSTART2</arg>
			<arg>TSTOP2</arg>
		</ioObject>
		<ioObject className="org.openda.model_hspf.WdmTimeSeriesIoObject">
			<file>%outputFile%</file>
			<id>outputIoObject</id>
			<arg>%wdmDllFile%</arg>
			<arg>%wdmMessageFile%</arg>
			<arg>output</arg>
			<arg>%TimeZone%</arg>
			<arg>%startTime%</arg>
			<arg>%endTime%</arg>
		</ioObject>
	</inputOutput>
</blackBoxWrapperConfig>

hspfModel.xml file

This file describes the models exchangeItems and can be kept very simple by defining "allElementsFromIoObject" for the model exchangeItems. A standard configuration is shown below:

<blackBoxModelConfig xmlns="http://www.openda.org" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.openda.org http://www.openda.org/schemas/openda_2.2/blackBoxModelConfig.xsd">
	<wrapperConfig>
		<file>./hspfWrapper.xml</file>
	</wrapperConfig>
	<aliasValues/>
	<timeInfoExchangeItems start="TSTART1" end="TSTOP1"/>
	<timeInfoExchangeItems start="TSTART2" end="TSTOP2"/>
	<exchangeItems>
		<vector id="allElementsFromIoObject" ioObjectId="uciDataObject"/>
		<vector id="allElementsFromIoObject" ioObjectId="inputParametersIoObject" role="Input"/>
		<vector id="allElementsFromIoObject" idSuffix="_output" ioObjectId="outputIoObject" role="Output"/> 
	</exchangeItems>
	<doCleanUp>false</doCleanUp>
</blackBoxModelConfig>

See an example ModuleDataset including the hspfWrapper.xml and the hspfModel.xml files.

Preparation of the HSPF modelset

To be able to run HSPF the following binaries or actions are required:

Installation of basins4.1.2015.09.25.exe.
binaries for WinHSPFLight which need to be placed in the REGION_HOME\Modules folder
binaries for OpenDA together with java files (jre) that is used by OpenDA; HSPF is run via OpenDA, therefore OpenDA is required. Besides the OpenDA binaries also a dll for reading and writing records in WDM files is included in OpenDA: OpenDaInFews\bin\win32_gfortran\WDM.dll

Checking the format of the UCI file

The UCI file should contain at least references to three WDM files, e.g.:

FILES
<FILE> <UN#>***<----FILE NAME------------------------------------------------->
...
WDM1 26 BasinResults.WDM
WDM2 27 BasinInput.WDM
WDM4 28 BasinState.WDM
...
END FILES

In the EXT SOURCES (BasinInput.WDM) and EXT TARGETS (BasinState.WDM and BasinResults.WDM) blocks the items in the different WDM files should be listed.

The INIT tables will be updated by the HSPF model adapter, make sure that the table format is correct, see also XXX

Note: Be aware of the units that HSPF will use, indicated by ENGL or METR in the EXT TARGETS and EXT SOURCES Blocks

Creating a WDM state file

A WDM state file can be created by following the instructions below:

create a new (empty) state.WDM file using WDMutil
- Open WDM Util
- Menu: File > New > fill in the name of the WDM file
- confirm that you will create a new WDM file:
Prepare the complete HSPF case including the UCI file, the WDM input file, the WDM output (results) file and the empty WDM state file (created in the previous step)
- Note that the UCI file should already contain items for the WDM state file, if not present add these first in the EXT TARGET Block
open the complete HSPF case in WinHSPF 2.3 (only works in this version) and adjust the WDM state file:
- Open WinHSPF.exe
- Menu: File > Open > select the uci file (the uci file should include the EXT TARGET section describing the items that are needed for the WDM state file, see "Checking the format of the UCI file"
- Menu: Edit > EXT TARGET; a Edit EXT TARGETS Block dialog should open
- Click on Add (then Apply button will be selectable),
- Click on Apply; a new dialog "Add Dataset" should open
- change the following in the Add Dataset dialog:
  - LocationNames; shorten the location Ids (the total length of locationIds is limited to 8 characters)
    - use P for PERLND, IMP for IMPLND, and RCH for RCHRES;
    - use e.g. MS Excel for adjusting the names; copy all records from the Location column to excel, shorten the names and paste the shortened names back into the table of the Add Dataset dialog)
    - do the same for the Time Units column, if the units are not in hours; IMPORTANT: the time unit should always be in hours (code = 3), otherwise the restart function will not work. OpenDA searches for the values in the WDM state file for the model's end timestep.
      C TCODE - time units of data
      C 1 - second 4 - day
      C 2 - minute 5 - month
      C 3 - hour 6 - year
      
      The result should look something like this:
When done press OK (Confirm that the empty row will be ignored by pressing OK again),
Close the Edit EXT TARGETS Block dialog by clicking OK
Then save the adjusted WDM file via Menu: File > Save
Close WinHSPF (Menu: File > Exit)
The WDM state file should now be filled with the new items; confirm this by opening the file in WDM Util
Optionally try to run HSPF in WinHSPF 2.3 before exiting WinHSPF