Page History

...

Introduction

WATFLOOD is a set of computer programs for hydrological forecasting and modelling. 

http://www.civil.uwaterloo.ca/watflood/

Two modes of parameter updating of WATFLOOD are supported by the Delft-FEWS General adapter (Delft-FEWS 2020.01 release), using a specifically designed preAdapter:

• The ability to switch values on/off for streamflow nudging within the WATFLOOD nudge_flags file;
•  The ability to update model parameters on-the-fly for a model simulation in the WATFLOOD basin parameter file

In November 2022 the model adapter was updated to update model routing parameters on-the-fly for a model simulation in the WATFLOOD basin parameter file

...

The WATFLOOD model files, including the WATFLOOD binaries are saved in the /Config/ModuleDataSet directory. These are copied to the /Modules/WATFLOOD/$BASIN$ directory during the exportDataSet activity in the General Adapter file. We assume that the module parameter file will be in XML format.

General Design choices for the WATFLOOD preAdapter

• The adapter will be written in Java (no FORTRAN)
• The (pre)Adapter will only write to the nudge_flags.xyz or *_parand basin parameter .csv file, not read from it (and pass info back to FEWS)
• The adapter runs with (any or all) of the following updating mechanisms. I.e.: the preAdapter also works when either the nudge_flag or the parameter updating is configured.
• The parameter files exported from Delft-FEWS are in pi-xml format.
• A very important part of the configuration is defined under the <exportRunFileActivity> element. It contains path to the WATFLOOD project file, but can also contain the path to WATFLOOD parameter and nudge_flag files in specific properties. The WATFLOOD adapter is coded to read/parse runFiles in netCDF format. Exporting to pi-xml format and referencing the xml runfile with the preAdapter is not supported.

Anchor
Update Nudge_Flags file Update Nudge_Flags file

Update Nudge_Flags file

The nudge_flags file is part of the model configuration. It is typically located in the following directory: /strfw/nudge_flags.xyz

Image Added

The file is space delineated. Only the space delineated. Only the first 4 columns are read by WATFLOOD. The rest of the line is ignored WF uses the lat-lon values to match the flows to the grid cells and not the station id. But we will use the station id to make the connection to update the correct . The nudge flag is stored in column 3 (see image above - green box), the preAdapter will use the stationId (column 4, see image above - red box) to make the connection to update the correct row in the nudge_flags.xyz file. The  The nudge flags file has 8 characters for the station id column (column 4). We willuse LNRB as the test case for the preAdapter.Reading the stationId. Reading the nudge_flags.xyz file is automatically left justified. Trailing blanks are chopped and not used for matching. 

The WATFLOOD executable (version October 2019) His updated executables now pick up the stationId instead of lat/lon to match to the flows for nudging. He adapted his code to align with our preAdapter design. Updated executables and nudge_flags.xyz files for all 3 WF models are now on the SVN.

Convention for the IdMapping in the params xml file for Nudge Flags:

locationId will match with the station Id as present in column 4 of the .xyz file
We propose not to use the lat/lon. This overcomplicates matters (rounding, how to combine lat/lon as a single identifier, differences between applications)
The parameterId of the value does not matter, in the current design only a single value can be overwritten per locationId. An example of the parameterId can be 'nudge_flag'
The value in the nudge flags params xml file will be used to overwrite the existing nudge_flag in column 3 of the .xyz file. It will be provided as a intValue, but the preAdapter should parse it as 'text'/string
Design Choices

Design Choices for nudge_flag updating

We assume that all locations in the nudge flags params xml (as exported by the General Adapter from Delft-FEWS) file are present in the nudge_flags.xyz file, no new locations can be dynamically introduced by the params file. 

To indicate to the preAdapter that nudge flags updating should take place, 2 specific keys need to be defined in the RunInfo file:

• <string key="WFNudgeFlagsFile" value="strfw/nudge_flags.xyz"/> (indicates to the preAdapter where the nudge file is located)
• <string key="NudgeFlagsParamsFile" value="strfw/$BASIN$_NudgeFlags_params.xml"/> (indicates to the preAdapter where the nudge flags parameter file for nudge flags updating is located)

Image Added

Convention for the IdMapping in the params xml file for Nudge Flags

locationId will match with the station Id as present in column 4 of the .xyz file
The parameterId of the value does not matter, in the current design only a single value can be overwritten per locationId. An example of the parameterId can be 'nudge_flag'
The value in the nudge flags params xml file will be used to overwrite the existing nudge_flag in column 3 of the .xyz file. It will be provided as a intValue, but the preAdapter should parse it as 'text'/stringWe assume that all locations in the nudge flags params xml file are present in the nudge_flags.xyz file, no new locations can be dynamically introduced by the params file
We will provide a specific key in the RunInfo file
<string key="WFNudgeFlagsFile" value="%ROOT_DIR%/strfw/nudge_flags.xyz"/>
indicates to the preAdapter where the nudge file is located.
<string key="NudgeFlagsParamsFile" value="%ROOT_DIR%/strfw/$BASIN$_NudgeFlags_params.xml"/>
indicates to the preAdapter where the nudge flags parameter file for nudge flags updating is located.
This then also indicates that nudge flags updating should take place

Configuration instructions for updating Nudge_Flags

...

locationId is free, not required to be equal to the 'Parameter block name' in the *_par.csv file. E.g. 'SnowParameters', because all parameters are unique
parameterId: The naming convention for the parameter id's is as follows: <parameter_id>-<column number>[*-**]
The <parameter_id> part is required. It should be equal to the WATFLOOD parameter id. The <parameter_id> element is 'closed' by a "-"(hyphen) character
The <column number> bit is required. It specifies which column needs to be updated by the preAdapter.
"01" is to be interpreted as the first column after the column with the parameterId
Leading zero's are not required, this part of the parameterId will be parsed as a number
The [-*] part is free to choose (and optional).

The values in the parameter.xml files from Delft-FEWS will be read as strings and are not interpreted.
This means that the representation in the params file should be correct.
Only exception is NaN's. These will not be read in/used and will be ignored. For parameterId's with NaN's, no warning/info message will be generated

An example where these design choices are followed is given in the screenshot below, where we want to update the "base" parameter in the basin file, for 19 landclasses

Image Added

Image Added

Design Choices

The adapter will parse the relevant lines of the WF parameter csv file to columns (comma separated) and replace . A parameter_id in the par file from Watflood always starts with a ":", e.g. ":fm" or ":base"
One can update all parameters with this design, if the parameterId convention is followed.
If less parameters are provided in the params.xml file as compared to the amount of columns as defined in the WATFLOOD par.csv file, the remainder of parameters will not be touched and stay in place. A WARN message should be thrown if this is the case to indicate to the user/configurator that only a subset of available parameters are being updated/passed to the model.
We will provide a specific key in the RunInfo file:in the RunInfo file:

<string key="WFBasinParFile" value="%ROOT_DIR%/basin/lnrb_par.csv"/>
This file will be used for the parameter updating.
<string key="WFBasinParFileBasinParamsFile" value="%ROOT_DIR%/basin/lnrb$BASIN$_Basin_parparams.csvxml"/>
This file will be used for the parameter updating.indicates to the preAdapter where the parameter file for parameter updating is located.
This then also indicates that parameter updating should take place.

Since November 2022, Routing parameters can also be changed on the fly when specified in a separate *_params.xml file

<string key="BasinParamsFileRoutingParamsFile" value="%ROOT_DIR%/basin/$BASIN$_BasinRouting_params.xml"/>
indicates to the preAdapter where the routing parameter file for parameter updating is located.
This then also indicates that routing parameter updating should take place

Image Added

Configuration Instructions for updating Basin Parameters

...