How to use the models

Using the models

Directory structure: cases and runs

A case is a directory holding all the data needed to run the model. Multiple cases may exist next to each other in separate directories. The model will only work with one case at the time. If no case is specified when starting the model a default case (default_sbm or default_hbv) is assumed. Within a case the model output (the results) are stored in a separate directory. This directory is called the run, indicated with a runId. This structure is indicated in the figure below:

digraph file_system {
//rankdir=LR;
size="8,11";
"Case" -> "inmaps";
"Case" -> "instate";
"Case" -> "intbl";
"Case" -> "intss";
"Case" -> "outstate";
"Case" -> "Run";
"Case" -> "staticmaps";
   "Run" -> " intbl";
   "Run" -> "outmaps";
   "Run" -> " outstate";
   "Run" -> "outsum";
   "Run" -> "runinfo";
}

If you want to save the results and not overwrite the results from a previous run a new runId must be specified.

inmaps

Directory holding the dynamic input data. Maps of Precipitation, potential evapotranspiration and (optionally) temperature in pcraster mapstack format.

instate

Directory holding the input initial conditions. Can be used to hotstart the model. Alternatively the model can start with default initial conditions but in that case a long spinup procedure may be needed. This is done using the -I command-line option.

intbl

Directory holding the lookup tables. These hold the model parameters specified per landuse/soiltype class. Note that you can use the -i option to specify an alternative name (e.g. to support an alternative model calibration). Optionally a .tbl.mult file can be given for each parameter. This file is used after loading the .tbl file or .map file to multiply the results with. Can be used for calibration etc.

intss

Directory holding the scalar input timeseries. Scalar input data is only assumed if the ScalarInput entry in the ini file is set to 1 (True).

outstate

Directory holding the stat variable at the end of the run. These can be copied back to the instate directory to have the model start from these conditions. These are also saves in the runId/outstate directory

run_default

The default name for a run. if no runId is given all output data is saved in this directory.

staticmaps

Static maps (DEM, etc) as prepared by the wflow_prep script.

wflow_sbm|hbv.ini

The default settings file for wflow_sbm of wflow_hbv

Running the model

Overview

In general the model is run from the dos/windows/linux command line. Based on the system settings you can call the wflow_[sbm|hbv].py file directly or you need to call python with the script as the first argument e.g.:

python -m wflow.wflow_sbm -C myCase -R calib_run -T 365 -f

In the example above the wflow_sbm model is run using the information in case myCase storing the results in runId calib_run. A total to 365 timesteps is performed and the the model will overwrite existing output in the calib_run directory. The default .ini file wflow_sbm.ini located in the myCase directory is read at startup.

Command-line options

The command line options for wflow_sbm are summarized below, use wflow_sbm -h to view them at the command line (option for other models may be different, see their respective documentation to see the options):

wflow_sbm [-h][-v level][-L logfile][-C casename][-R runId]
      [-c configfile][-T last_step][-S first_step][-s seconds]
      [-P parameter multiplication][-X][-f][-I][-i tbl_dir][-x subcatchId]
      [-p inputparameter multiplication][-l loglevel][--version]
-X: save state at the end of the run over the initial conditions at the start
-f: Force overwrite of existing results
-T: Set end time of the run: yyyy-mm-dd hh:mm:ss
-S: Set start time of the run: yyyy-mm-dd hh:mm:ss
-s: Set the model timesteps in seconds
-I: re-initialize the initial model conditions with default
-i: Set input table directory (default is intbl)
-x: Apply multipliers (-P/-p ) for subcatchment only (e.g. -x 1)
-C: set the name  of the case (directory) to run
-R: set the name runId within the current case
-L: set the logfile
-c: name of wflow configuration file (default: Casename/wflow_sbm.ini).
-h: print usage information
-P: set parameter change string (e.g: -P "self.FC = self.FC * 1.6") for non-dynamic variables
-p: set parameter change string (e.g: -P "self.Precipitation = self.Precipitation * 1.11") for
    dynamic variables
-l: loglevel (most be one of DEBUG, WARNING, ERROR)

wflow_sbm|hbv.ini file

The wflow_sbm|hbv.ini file holds a number of settings that determine how the model is operated. The files consists of sections that hold entries. A section is defined using a keyword in square brackets (e.g. [model]). Variables can be set in each section using a keyword = value combination (e.g. ScalarInput = 1). The default settings for the ini file are given in the subsections below.

[model] Options for all models:

ModelSnow = 0

Set to 1 to model snow using a simple degree day model (in that case temperature data is needed).

WIMaxScale = 0.8

Scaling for the topographical wetness vs soil depth method.

nrivermethod = 1

Link N values to land cover (col 1), sub-catchment (col 2) and soil type (col 3) through the N_River.tbl file. Set to 2 to link N values in N_River.tbl file to streamorder (col 1).

MassWasting = 0

Set to 1 to transport snow downhill using the local drainage network.

kinwaveIters = 0

Set to 1 to enable iterations of the kinematic wave (time).

sCatch = 0

If set to another value than 0 the model will only use the specified subcatchment

timestepsecs = 86400

timestep of the model in seconds

Alpha = 60

Alpha term in the river width estimation function

AnnualDischarge = 300

Average annual discharge at the outlet of the catchment for the river wiidth estimation function

intbl = intbl

directory from which to read the lookup tables (relative to the case directory)

Specific options for wflow_hbv :

updating = 0

Set to 1 to switch on Q updating.

updateFile

If updating is set to 1 specify a file

UpdMaxDist = 100

Maximum distance from the gauge used in updating for which to update the kinematic wave reservoir (in model units, metres or degree lat lon)

The options below should normally not be needed. Here you can change the location of some of the input maps.

wflow_subcatch=staticmaps/wflow_subcatch.map

map with the subcatchments

wflow_dem=staticmaps/wflow_dem.map

the digital elevation map

wflow_ldd=staticmaps/wflow_ldd.map

the local drainage network

wflow_river=staticmaps/wflow_river.map

all the cells marked as river

wflow_riverlength=staticmaps/wflow_riverlength.map

the length of the ‘river’ in each cell

wflow_riverlength_fact=staticmaps/wflow_riverlength_fact.map

factor to multiply the river length with

wflow_landuse=staticmaps/wflow_landuse.map

landuse map

wflow_soil=staticmaps/wflow_soil.map

soil map

wflow_gauges=staticmaps/wflow_gauges.map

map with the gauge locations

wflow_inflow=staticmaps/wflow_inflow.map

map with forced inflow points (optional)

wflow_mgauges=staticmaps/wflow_mgauges.map

map with locations of the meteorological gauges (only needed if you use scalar timeseries as input)

wflow_riverwidth=staticmaps/wflow_riverwidth.map

map with the width of the river

[layout]

sizeinmetres = 0

If set to zero the cell-size is given in lat/long (the default), otherwise the size is assumed to be in metres.

[outputmaps]

Outputmaps to save per timestep. Valid options for the keys in the wflow_sbm model are all variables visible the dynamic section of the model (see the code). A few useful variables are listed below.

[outputmaps]
self.RiverRunoff=run
self.SnowMelt=sno
self.Transfer=tr
self.SatWaterDepth=swd

Tip

NB See the wflow_sbm.py code for all the available variables as this list is incomplete. Also check the framwework documentation for the [run] section

The values on the right side of the equal sign can be choosen freely.

Example content:

Self.RiverRunoff=run
self.Transfer=tr
self.SatWaterDepth=swd

[outputcsv_0-n] [outputtss_0-n]

Number of sections to define output timeseries in csv format. Each section should at lears contain one samplemap item and one or more variables to save. The samplemap is the map that determines how the timesries are averaged/sampled. All other items are variabale filename pairs. The filename is given relative to the case directory.

Example:

[outputcsv_0]
samplemap=staticmaps/wflow_subcatch.map
self.RiverRunoffMM=Qsubcatch_avg.csv

[outputcsv_1]
samplemap=staticmaps/wflow_gauges.map
self.RiverRunoffMM=Qgauge.csv

[outputtss_0]
samplemap=staticmaps/wflow_landuse.map
self.RiverRunoffMM=Qlu.tss

In the above example the river discharge of this model (self.RiverRunoffMM) is saved as an average per subcatchment, a sample at the gauge locations and as an average per landuse.

[inputmapstacks]

This section can be used to overwrite the default names of the input mapstacks

Precipitation = /inmaps/P

timeseries for rainfall

EvapoTranspiration = /inmaps/PET

potential evapotranspiration

Temperature = /inmaps/TEMP

temperature time series

Inflow = /inmaps/IF

in/outflow locations (abstractions)

Updating using measured data

Note

Updating is only supported in the wflow_hbv model.

If a file (in .tss format) with measured discharge is specified using the -U command-line option the model will try to update (match) the flow at the outlet to the measured discharge. In that case the -u option should also be specified to indicate which of the columns must be used. When updating is switched on the following steps are taken:

  • the difference at the outlet between measured and simulated Q (in mm) is determined

  • this difference is added to the unsaturated store for all cells

  • the ratio of measured Q divided by simulated Q at the outlet is used to multiply the kinematic wave store with. This ratio is scaled according to a maximum distance from the gauge.

Please note the following points when using updating:

  • The tss file should have as many columns as there are gauges defined in the model

  • The tss file should have enough data points to cover the simulation time

  • The -U options should be used to specify which columns to actually use and in which order to use them. For example: -u ‘[1,3,2]’ indicates to use column 1,2 and 3 in that order.

All possible options in wflow_sbm.ini file

[layout]
sizeinmetres = 1

[fit]
areamap = staticmaps/wflow_subcatch.map
areacode = 1
Q = testing.tss
WarmUpSteps = 1
ColMeas = 0
parameter_1 = RootingDepth
parameter_0 = M
ColSim = 0

[misc]

[outputmaps]
self.RiverRunoff = run

[framework]
debug = 0
outputformat = 1

[inputmapstacks]
Inflow = /inmaps/IF
Precipitation = /inmaps/P
Temperature = /inmaps/TEMP
EvapoTranspiration = /inmaps/PET

[model]
wflow_river = staticmaps/wflow_river.map
InterpolationMethod = inv
reinit = 1
WIMaxScale = 0.6
wflow_riverlength_fact = staticmaps/wflow_riverlength_fact.map
OverWriteInit = 0
intbl = intbl
wflow_riverwidth = staticmaps/wflow_riverwidth.map
wflow_soil = staticmaps/wflow_soil.map
sCatch = 0
Alpha = 120
wflow_subcatch = staticmaps/wflow_subcatch.map
wflow_mgauges = staticmaps/wflow_mgauges.map
timestepsecs = 86400
ScalarInput = 0
ModelSnow = 0
AnnualDischarge = 2290
wflow_landuse = staticmaps/wflow_landuse.map
TemperatureCorrectionMap = staticmaps/wflow_tempcor.map
wflow_inflow = staticmaps/wflow_inflow.map
wflow_riverlength = staticmaps/wflow_riverlength.map
wflow_ldd = staticmaps/wflow_ldd.map
wflow_gauges = staticmaps/wflow_gauges.map
wflow_dem = staticmaps/wflow_dem.map