Introduction¶
This adapter supports 3 NWS models: SNOW-17, SACSMA and UNIT-HG, as described in the following sections. It further offers the WEIGHT-TS calculation and time series transfer similar to functionality in CHPS/FEWS.
Concept¶
A basin constitutes a geographical hydrological unit relevant to the runoff calculations as described by the NWS models. A basin may be further sub-divided into areas or sub-basins.
For each basin a sequence of NWS models lead to calculation of the runoff or Total Channel Inflow (TCI) relevant to downstream hydraulic models. Often output from SNOW-17 is further processed in a SACSMA model for the same basin/area, and the SACSMA output is finally processed into TCI through the UNIT-HG model.
Transfers of time series may happen between models within a basin – but rarely (never) between basins. NWS models for multiple basins may be executed in a batch – generating all the TCI for a hydraulic model for an entire river.
The adapter supports various combinations of NWS models within MIKE Workbench:
-
One model for one basin/area, e.g. a separate UNIT-HG model
-
A sequence of NWS models for a basin
-
Multiple basins, each with a sequence of models for the basin/areas.
-
Combinations of the above.
Prerequisites¶
The configuration and execution of NWS models into MIKE Workbench using this adapter will require:
-
CHPS/FEWS executables for the OHD models (SNOW-17m SACSMA and UNIT-HG) located on the machine(s). the adapter has been with “OHD Fews Adapter version: OHD-CORE-CHPS-3.2.a (November, 7 2013)”
-
Prepared NWS model setups as described below
-
Shape file information about geometries (optional)
Configuration¶
This section describes the formats and details of the NWS Adapter and NWS model setups files. It also explains about the preferred organization of the data.
Main configuration file¶
The main configuration file is a text-file listing the run_info.xml files of the participating NWS models in the order in which the NWS models are to be executed. See a sample in Figure 1.
code1.txt
Figure 1 Sample of main configuration file
The format of the file must respect:
-
One line per run_info.xml file
-
Lines beginning with a hash (#) is discarded as comments
-
Each line has 3 mandatory and one optional values separated by semi-colon:
-
Basin name – a text string describing the basin of the NWS models. Several models may share this.
-
Basin area – a string describing the sub-basin area name
-
Run_info.xml file path – a relative path from the location of the configuration file
-
Max. run time (optional) – maximum number of seconds, the model is allowed to run. If it hangs or run longer for some reason the adapter will kill it and stop. A negative number or zero means not check is performed. This is the default.
-
As the file paths of the sample indicate, the txt-file is usually located below all the NWS model files. See next section on file organization.
How to organize model setup files¶
Each of the NWS model setups typically organizes files as shown in Figure 2.
Figure 2 Sample of main configuration file
A run_info.xml file is at the root of each model setup and other files organized in sub-folders input, output, states and work.
For the adapter to detect all the necessary files and time series types of the participating NWS models all files must be present – input and output, equivalent to presenting the FEWS run files after a model run. These run file typically have absolute paths from the modelling machine but the adapter attempts to handle that as it needs to use the files with relative paths at runtime.
As indicated in Figure 1 the best way is simply to organize the individual NWS model folders side-by-side with the main configuration file (e.g. “Test5 (all).txt”) at the same level.
This means that all run_info.xml file are located in separate sub-folders – one for each basin/area/model combination, see Figure 3.
Figure 3 Sample of common configuration for 4 basins. 2 model folders are
expanded.
Time series¶
In order to reduce the amount of data to be registered with the models the run files should only cover a short time period.
At runtime MIKE Workbench will substitute the time steps for real data.
It is also suggested to avoid data in mods time series. MIKE Workbench will only replace time steps in selected (configured) time series, and if modifiers are specified at configuration time they will have to be replaced (perhaps with missing values) each time to avoid the original modifiers to be present. Having empty time series at registration will allow only specifying them when required.
Output time series in MIKE Workbench (and input times retrieved during registration) will be given names indicating the locationId and parameterId in the NWS models, as the MIKE Workbench variable and unit system is less flexible.
States¶
The input states present at registration time will be considered COLD states in MIKE Workbench unless otherwise specified during registration. The states will be stored with a date and time equivalent to the startDateTime of the sample runs – using the startDateTime of the first run_info.xml
CHPS/FEWS bin-folder¶
The adapter needs to know where the java classes of CHPS/FEWS are located as they are needed at runtime to execute the models.
At configuration time this can be supplied by an absolute path for the location of the configuration machine. However, this then requires CHPS/FEWS to be located at exactly the same path at runtime at any machine which may run the models.
Alternatively, a Windows environment variable can be defined and used – as long as this variable is also defined in the executing machine.
GIS data¶
Although NWS models have no geographic information the adapter offers a possibility to provide spatial information for the registration of the models in MIKE Workbench.
This information will be in the form of the geometry of a basin. i.e. all NWS models associated with a basin will be linked to a so-called model object with the geometry of the basin. The adapter will expect a shape file as input. The shape file must have an attribute holding basin name, which identifies a row (or shape) in the shape file as ‘belonging to’ a basin.
The shape file must have a coordinate system or projection which is known to MIKE Workbench – i.e. the geometries of the shape file are all defined in this projection. The projection may be specified in the form of a prj-file with the shape file. If a prj-file is not present or the system cannot recognize the projection inside, the user must select the appropriate projection to use.
Specification of a shape file is optional.
Transfer¶
A sequence of NWS models for a basin will involve transfer of time series, e.g. output of TCI from the SACSMA model into input for the UNIT_HG model. In CHPS/FEWS this happens via the system.
In a MIKE Workbench model setup containing all the NWS models for a basin the transfer is handled by the adapter. Parsing the setup(s) the adapter identifies matching output and input time series sharing locationId and paramterId in the order of sequence and suggests the inputs are resolved via transfer.
The user may override the suggested transfer and provide the input from MIKE Workbench, but usually this is not the case.
Variables and units¶
NWS time series are very flexible with definition of parameterId – the abbreviation telling which type of data the time series holds. Likewise the units for these types can also be quite flexible – as long as the basic unit types are respected (e.g. length, weight, time). MIKE Workbench is less flexible, hence a translation from NWS to MIKE Workbench has been established for the supported models.
Table 1, Table 2 and Table 3 show how NWS types and units are described in MIKE Workbench EUM types and units. For input time series the adapter will check if the incoming DataSeries from MIKE Workbench match the expected type allowing conversion into NWS time series. The unit is expected to be in the same unit as when the model was registered, i.e. not conversion takes place. This means the NEWS model setups should be prepared before registration with data of same unit as will be provided at runtime.
Output time series are converted/translated into MIKE Workbench DataSeries. The adapter offers a conversion from the default unit to other allowed units in the EUM system – enabling for instance translation of m\^3/s into ft\^3/s if needed.
Table 1. Input Time Series Types
| NWS | MIKE Workbench | ||||
|---|---|---|---|---|---|
| Type | Unit | Type | Unit | ||
| SNOW17 | MAP | MM | Precipitation Areal Mean | Rainfall | Mm |
| MAT | DEGC | Air Temperature Areal Mean | Temperature | degC | |
| PTPS | PCTD | Precipitation Snowfall (Fraction) | Fraction | Percent | |
| RSEL | M | Rain-Snow Elevation | Elevation | M | |
| SNWE | MM | Snow Cover Water Equivalent Observed | Snow Water Content | Mm | |
| AESC | PCTD | Snow Cover Areal Extent Observed | Snow Cover Percentage | Percent | |
| SNOG | CM | Snow Cover Depth Observed | Snow Depth | Mm | |
| SACSMA | RAIM | MM | Precipitation Rain+Melt | Rainfall | Mm |
| SASC | PCTD | Snow Cover Areal Extent Simulated | Snow Cover Percentage | Percent | |
| MAPE | MM | Evapotranspiration Potential Areal Mean | Evaporation | mm | |
| MAT | degC | Air Temperature Areal Mean | Temperature | degC | |
| SWE | MM | Snow Cover Water Equivalent Simulated | Snow Water Content | Mm | |
| UNIT-HG | TCI (Runoff) | MM | Total Channel Inflow | Storage Depth | mm |
| Discharge | CMS | Discharge | Discharge | m3/s |
Table 2. Modifier Time Series Types
| NWS | MIKE Workbench | ||||
|---|---|---|---|---|---|
| Type | Unit | Type | Unit | ||
| SNOW17 | AESCCHNG | PCTD | Areal Extent Of Snow Cover | Snow Cover Percentage | Percent |
| MFC | REAL | Melt Factor Correction | Factor | - | |
| RAINSNOW | INT | Ratio of Rain To Snow | Factor | - | |
| UADJ | REAL | Wind Speed Adjustment Factor | Factor | ||
| WEADD | MM | Additional Snow Water Content | Snow Water Content | mm | |
| WECHNG | MM | Change in Snow Water Content | Snow Water Content | mm | |
| SACSMA | UZTWC | MM | Upper Zone Tension Water Content | Storage Depth | mm |
| UZFWC | MM | Upper Zone Free Water Content | Storage Depth | mm | |
| LZTWC | MM | Lower Zone Tension Water Content | Storage Depth | mm | |
| LZFSC | MM | Lower Zone Free Secondary Water Content | Storage Depth | mm | |
| LZFPC | MM | Lower Zone Free Primary Water Content | Storage Depth | mm | |
| ADIMC | Additional Impervious Area Water Content | ||||
| FGIX | DecC | Frozen Ground Index | Temperature | Deg C | |
| SACBASEF | REAL | Baseflow Adjustment | Fraction | - |
Table 3. Output Time Series Types
| NWS | MIKE Workbench | ||||
|---|---|---|---|---|---|
| Type | Unit | Type | Unit | ||
| SNOW17 | RAIM | MM | Precipitation Rain+Melt | Rainfall | mm |
| SASC | PCTD | Areal Extent of Snow Cover | Snow Cover Percentage | Percent | |
| SWE | MM | Snow Water Equivalent | Snow Water Content | mm | |
| SNSG | MM | Snow depth | Snow depth | m | |
| PRAIN | MM | Precip as rain | Rainfall | mm | |
| PSFALL | MM | Precip as snow fall | Rainfall | mm | |
| PROBG | MM | Rain on bare ground within MAT interval | Rainfall | mm | |
| PSNWRO | MM | Snow pack outflow within MAT interval (note: the sum of PROBG and SNWRO equals to RAIM) | Rainfall | mm | |
| ACCMAX | MM | Maximum water-equivalent that has occurred since snow began to accumulate (units of MM) | Snow Water Content | mm | |
| AEADJ | MM | Areal extent of snow cover adjustment; units of MM | Storage Depth | mm | |
| LIQW | MM | Initial amount of liquid-water held against gravity drainage (units of MM) | Storage Depth | mm | |
| NEGHS | MM | Initial heat deficit (units of MM) | Storage Depth | mm | |
| PQNET | MM | State | Storage Depth | mm | |
| SB | MM | Areal water equivalent just prior to the new snowfall (units of MM) | Snow Water Content | mm | |
| SBAESC | PCTD | Areal extent of snow cover just prior to the new Snowfall (units of PCT) | Snow Cover Percentage | Percent | |
| SBWS | MM | Water equivalent above which 100 percent areal snow cover temporarily exists (units of MM) | Snow Water Content | mm | |
| SNDPT | MM | Snow depth; in unit of MM | Snow Depth | mm | |
| SNTMP | DEGC | Average snow cover temperature (units of DEGC) | Temperature | Deg C | |
| STORGE | MM | Excess liquid water in storage (units of MM) | Storage Depth | mm | |
| TAPREV | DEGC | Previous air temperature (units of DEGC) | Temperature | Deg C | |
| TINDEX | DEGC | Initial antecedent snow temperature index (units of DEGC) | Temperature | Dec C | |
| WE | MM | Initial water equivalent of solid (ice) portion of the snow cover (units of MM) | Snow Water Content | mm | |
| SACSMA | TCI | MM | Total Channel Inflow | Storage Depth | mm |
| IMP_RO | MM | Impervious Runoff | Storage Depth | mm | |
| DIR_RO | MM | Direct Runoff | Storage Depth | mm | |
| SUR_RO | MM | Surface Runoff | Storage Depth | mm | |
| INT_RO | MM | Interflow | Storage Depth | mm | |
| SUP_RO | MM | Supplemental Baseflow | Storage Depth | mm | |
| PRI_RO | MM | Primary Baseflow | Storage Depth | mm | |
| LZTDEF | MM | Lower zone tension water deficit | Storage Depth | mm | |
| UZTDEF | MM | Upper zone tension water deficit | Storage Depth | mm | |
| LZDEFR | REAL | Lower Zone Deficit | Fraction | - | |
| UZTWC | MM | Upper Zone Tension Water Content | Storage Depth | mm | |
| UZFWC | MM | Upper Zone Free Water Content | Storage Depth | mm | |
| LZTWC | MM | Lower Zone Tension Water Content | Storage Depth | mm | |
| LZFSC | MM | Lower Zone Free Secondary Water Content | Storage Depth | mm | |
| LZFPC | MM | Lower Zone Free Primary Water Content | Storage Depth | mm | |
| ADIMC | MM | Additional Impervious Area Water Content | Storage Depth | mm | |
| UZTWC_PERC | PCTD | Upper Zone Tension Water Fraction | Fraction | Percent | |
| UZFWC_PERC | PCTD | Upper Zone Free Water Fraction | Fraction | Percent | |
| LZTWC_PERC | PCTD | Lower Zone Tension Water Fraction | Fraction | Percent | |
| LZFSC_PERC | PCTD | Lower Zone Free Secondary Water Fraction | Fraction | Percent | |
| LZFPC_PERC | PCTD | Lower Zone Free Primary Water Fraction | Fraction | Percent | |
| ADIMC_PERC | PCTD | Additional Impervious Area Water Fraction | Fraction | Percent | |
| FGIX | DEGC | Frozen Ground Index | Temperature | Deg C | |
| UNITHG | SQIN | CMS | Discharge | Discharge | m\^3/s |
Time zone¶
Although the NWS models and time series support a time zone specification, the adapter does not. It is therefore important that:
-
All NWS models are configured to use the same time zone
-
All input and output time series are assumed to be in the same time zone
This means that input time series from MIKE Workbench should be prepared for the relevant time zone and that output time series are returned from the adapter in the same time zone.
Model registration¶
The following illustrates the registration process:
-
From Scenario Manager in MIKE Workbench the user selects “Register model”
-
The user selects the NWS model adapter
-
The user provides the required (and optional ) input to the NWS Adapter:
a. Select a main configuration file – the model setup name will by default be that of the file.
b. Perhaps edit the name
c. Specify the bin-folder location. In this case an environment variable is used
d. Specify a shape file – the projection is accepted
e. Select the attribute holding the basin names
-
Clicking next will start the parsing of the model setup.
-
Then the adapter presents a list of transfers for the user to acknowledge. Clicking Cancel will stop the registration process.
-
Finally the adapter offers selection of alternative nits for the output time series. Clicking Cancel will stop the registration process
-
Clicking Finish will return the model setup information to MIKE Workbench
-
Eventually the model setup can be seen and use in Scenario Manager
Weigh-TS configuration¶
A sequence of NWS models for a basin may involve parallel models for different basin areas, e.g. to enable different SNOW-17 and SACSMA models for different elevation zones. The output of such sub-basin area models may then be joined into a common input to the UNIT_HG model via a configuration of a weighting scheme by which to adjust and sum the time series.
In CHPS/FEWS this happens via the system where a Transformation Module configuration is used.
In a MIKE Workbench model setup containing all the NWS models for a basin the weighting is handled by the adapter. The configuration of the routine is similar to that of a NWS model, i.e. with run_info.ml, params.xml and input and output time series.
An example of such a configuration is given below. The files and folders are organized as shown in Figure 4.
Figure 4 Files and subfolder of a WEIGH-TS configuration
The run_info.xml defines the relative position of the input time series, parameters, output time series and diagnostics, see Figure 5.
code2.txt
Figure 5 run_info.xml of a WEIGH-TS configuration
Requirements for this file is:
-
It adheres to the CHPS/FEWS pi_run.xsd schema
-
TimeZone should match the timeZone of other NWS models in the setup
-
startDateTime, endDatetime and time0 should match that of other NWS models in the setup
-
Only one inputParameterFile tag must exist
-
A minimum of one inputTimeSeriesFile tag must exist. The filename of the input time series MUST be “inputN.xml” where N corresponds to a parameter file parameter group of the same name.
-
One and only one outputTimeSeriesFile tag must exist.
-
The property with key=”model” and value=”weigh-ts” must exist
The parameter file defines the weights to use for each input time series, see Figure 6.
code3.xml
Figure 6 params.xml of a WEIGH-TS configuration
Requirements for the params.xml file are:
-
It must adhere to the pi_modelparameters.xsd schema of CHPS/FEWS.
-
It must have as many ‘input’ groups with Id matching the name of the input time series files - one group per file.
-
Within each input group 4 parameters must be defined:
-
locationId – a string value of the point location of the input time series
-
parameterId – a string value with the time series parameter
-
scalingFactor – a double number giving the multiplier to use with the time series values
-
offset – a double number giving a value to add to the time steps values.
-
-
One group with Id=”Output” must exist and define 3 parameters:
-
locationId – the identification of the location to use with the output time series
-
parameterId – a string value with the time series parameter of the output time series
-
stationName – a string defining the stationName of the output time series
-
The adapter will use locationId and parameterId to identify the input and output time series in the respective time series xml-files.
The inputN.xml and outputs.xml files follow the same pattern, see Figure 7 and Figure 8
code4.xml
Figure 7 inputN.xml of a WEIGH-TS configuration
code5.xml
Figure 8 outputs.xml of a WEIGH-TS configuration
The time series files:
-
Must as a minimum contain the time series referred by locationId and parameterId in the corresponding parameter group in params.xml
-
Should have the same timeZone as the rest of the NWS setups.
-
Must share the same timeStep size.
-
startDate, endDate and (optionally) forecastDate can be anything at configuration time, but should match the other NWS setups.
At runtime the input time series are usually filled via transfers and as such the start and end of the time series will match. The output time series will be updated according to the time series content being written to it.
For configuration, the time series file can be constructed by copying headers of the corresponding output and input time series to the model before/after the WEIGH-TS. The time series xml files need not have actual time steps for registration, although it is advisable to initial testing of the models.
When the model runs, diagnostics are written to diag.xml, similar to the NWS models. The diag.xml adheres to the CHPS/FEWS pi_diag.xsd schema.
The WEIGH-TS will:
-
Read input time series
-
Calculate new time steps as “newvalue = value*scalingFactor + offset” (for all non-missing value time steps)
-
Sum the adjusted input time series
-
Write the result to the output time series.
It is assumed the calculations will respect the type and units of the time series, giving a result matching the parameterId and unit of the output time series as defined in the template outputs.xml file.
Issues¶
Small differences (+/- 5E-6) between results from WEIGH-TS and the equivalent output of FEWS have been seen.
This can be due to differences in single or double point precision between the two systems. However, the magnitude of difference should not affect the end results.
Running models¶
Running models from MIKE Workbench requires the user to prepare the input time series according to requirements of the NWS models, e.g.:
-
First time step must be at Start Of Simulation
-
Last time steps must be at Start of Simulation
-
Input time series required by the NWS model to be equidistant must be provided with appropriate time steps and interval.
-
Input Time series which are required to have a time step which is a multiple of the main input time series must be provided with appropriate time steps.
-
Input time series should have values matching the target unit of the model. E.g. an input time series of rainfall should be in inches if configured to be in inches.
-
Consideration of the unit of output time series must be taken at configuration time. E.g. a requirement to have flows in ft\^3/s in MIKE Workbench should result in the output of the UNIT-HG models be configured to include unit conversion by the adapter.
The NWS models require/prefer the input state to be at startDateTime, i.e. a state from another run must be saved at that time. This implies a scheme for running the models whereby:
-
A scenario is configured to run a staterun where by the state is brought forward, say 24 hours, each day using observed data only.
-
Another scenario is configured to run forecast runs. They will start at the date+time of the latest state saved (\~last midnight) and run forward. Should the NWS model outputs be used as iput for other models requiring a hindcast for warming up the model, the NWS models can be run with a hindcast period also, extending back to a prior saved state (1,2,3.. days before as required). The forecast runs do not save states.