TOML is used as the configuration format for models available in wflow. File paths included in the configuration TOML file are relative to the TOML file location.
Time information is optional. When left out, each time step in the forcing NetCDF will be calculated. If you wish to calculate a subset of this time range, or a different timestep, you can specify a
timestepsecs yourself. The
time_units optional information is used by the
writer of the model, for model output in netCDF format. The
calendar option allows you to calculate in one of the different CF conventions calendars provided by the CFTime.jl package, such as
"360_day". This is useful if you want to calculate climate scenarios which are sometimes provided in these alternative calendars.
calendar = "standard" # optional, this is default value endtime = 2000-02-01T00:00:00 # optional, default from forcing NetCDF starttime = 2000-01-01T00:00:00 # optional, default from forcing NetCDF time_units = "days since 1900-01-01 00:00:00" # optional, this is default value timestepsecs = 86400 # optional, default from forcing NetCDF
Model specific settings can be included in the model section of the TOML file.
[model] type = "sbm" # one of ("sbm", "sbm_gwf, "hbv") masswasting = true # include lateral snow transport in the model, default is false snow = true # include snow modelling, default is false reinit = true # cold (reinit = true) or warm state (reinit = false), default is true reservoirs = true # include reservoir modelling, default is false kin_wave_iteration = true # enable kinematic wave iterations in the model, default is false thicknesslayers = [100, 300, 800] # specific SBM setting: for each soil layer a thickness [mm] is specified min_streamorder = 3 # minimum stream order to delineate subbasins, default is 4 (for multi-threading computing purposes)
state section in the TOML file provides information about the location of the state file if the model is initialized with a warm state (
path_input) and to what file the states are written at the end of the model run (
path_output). A mapping between external state names and internal model states is required. This information is specified for each model component, the
vertical model and
lateral model components. In the example below the
vertical component represents the SBM concept, and for the
lateral components there is a
subsurface domain. The internal model states are listed on the left side, and the external state names are listed on the right side. Note that
path_input is only required when
reinit is set to false.
path_output is optional, an output state file is only written when it is defined. If neither is set, the entire
state section can be left out.
[state] path_input = "data/instates-moselle.nc" path_output = "data/outstates-moselle.nc" [state.vertical] satwaterdepth = "satwaterdepth" snow = "snow" tsoil = "tsoil" ustorelayerdepth = "ustorelayerdepth" snowwater = "snowwater" canopystorage = "canopystorage" [state.lateral.river] q = "q_river" h = "h_river" h_av = "h_av_river" [state.lateral.river.reservoir] volume = "volume_reservoir" [state.lateral.subsurface] ssf = "ssf" [state.lateral.land] q = "q_land" h = "h_land" h_av = "h_av_land"
input section of the TOML file contains information about the input forcing and model parameters files (netCDF format). Forcing is applied to the vertical component of the model, and needs to be mapped to the external netCDF variable name.
forcing lists the internal model forcing parameters, and these are mapped to the external netCDF variables listed under the section
[input.vertical]. It is possible to provide cyclic parameters to the model. In the example below this is done for the internal
vertical.leaf_area_index model parameter, that is linked to the external netCDF variable "LAI" variable.
As for the states, mapping of external model parameters (provided in the example below by the file staticmaps-moselle.nc) is done per model component. If a model parameter is not mapped a default value will be used if available.
[input] path_forcing = "data/forcing-moselle.nc" path_static = "data/staticmaps-moselle.nc" # these are not directly part of the model gauges = "wflow_gauges" ldd = "wflow_ldd" river_location = "wflow_river" subcatchment = "wflow_subcatch" # specify the internal IDs of the parameters which vary over time # the external name mapping needs to be below together with the other mappings forcing = [ "vertical.precipitation", "vertical.temperature", "vertical.potential_evaporation", ] cyclic = ["vertical.leaf_area_index"] [input.vertical] altitude = "wflow_dem" c = "c" cf_soil = "cf_soil" cfmax = "Cfmax" e_r = "EoverR" infiltcappath = "InfiltCapPath" infiltcapsoil = "InfiltCapSoil" kext = "Kext" "kv₀" = "KsatVer" leaf_area_index = "LAI" m = "M" maxleakage = "MaxLeakage" pathfrac = "PathFrac" potential_evaporation = "PET" # forcing precipitation = "P" # forcing rootdistpar = "rootdistpar" rootingdepth = "RootingDepth" soilminthickness = "SoilMinThickness" soilthickness = "SoilThickness" specific_leaf = "Sl" storage_wood = "Swood" temperature = "TEMP" # forcing tt = "TT" tti = "TTI" ttm = "TTM" w_soil = "wflow_soil" water_holding_capacity = "WHC" waterfrac = "WaterFrac" "θᵣ" = "thetaR" "θₛ" = "thetaS" [input.lateral.river] length = "wflow_riverlength" n = "N_River" slope = "RiverSlope" width = "wflow_riverwidth" [input.lateral.river.reservoir] area = "ResSimpleArea" areas = "wflow_reservoirareas" demand = "ResDemand" locs = "wflow_reservoirlocs" maxrelease = "ResMaxRelease" maxvolume = "ResMaxVolume" targetfullfrac = "ResTargetFullFrac" targetminfrac = "ResTargetMinFrac" [input.lateral.subsurface] ksathorfrac = "KsatHorFrac" [input.lateral.land] n = "N" slope = "Slope"
This optional section of the TOML file contains the output netCDF file for writing gridded model output, including a mapping between internal model parameter components and external netCDF variables.
[output] path = "data/output_moselle.nc" [output.vertical] satwaterdepth = "satwaterdepth" snow = "snow" tsoil = "tsoil" ustorelayerdepth = "ustorelayerdepth" snowwater = "snowwater" canopystorage = "canopystorage" [output.lateral.river] q = "q_river" h = "h_river" [output.lateral.river.reservoir] volume = "volume_reservoir" [output.lateral.subsurface] ssf = "ssf" [output.lateral.land] q = "q_land" h = "h_land"
Besides gridded data, it is also possible to write scalar data to a NetCDF file. Below is an example that writes scalar data to the file "output_scalar_moselle.nc". For each NetCDF variable a
name (external variable name) and
parameter (internal model parameter) is required. A
reducer can be specified to apply to the model output, see for more information the following section Output CSV section. When a
map is provided to extract data for certain locations (e.g.
gauges) or areas (e.g.
subcatchment), the NetCDF location names are extracted from these maps. For a specific location (grid cell) a
location is required. In the section Output CSV section, similar functionality is available for CSV. For integration with Delft-FEWS, see also Run from Delft-FEWS, it is recommended to write scalar data to NetCDF format since the General Adapter of Delft-FEWS can ingest this data format directly.
[netcdf] path = "data/output_scalar_moselle.nc" [[netcdf.variable]] name = "Q" map = "gauges" parameter = "lateral.river.q" [[netcdf.variable]] coordinate.x = 6.255 coordinate.y = 50.012 name = "temp_coord" location = "temp_bycoord" parameter = "vertical.temperature" [[netcdf.variable]] location = "temp_byindex" name = "temp_index" index.x = 100 index.y = 264 parameter = "vertical.temperature"
Model output can also be written to CSV output. Below is an example that writes model output to the file "output_moselle.csv". For each CSV column a
parameter (internal model parameter) is required. A
reducer can be specified to apply to the model output, with the following available reducers:
only as the default. To extract data for a specific location (grid cell), the
index of the vector, the coordinates
coordinate.y, or the x and y indices of the 2D array (
index.y) can be provided. Finally a
map can be provided to extract data for certain locations (e.g.
gauges) or areas (e.g.
subcatchment). In this case a single entry can lead to multiple columns in the CSV file, which will be of the form
Q_20, for a gauge with integer ID 20.
The double brackets in
[[csv.column]] is TOML syntax to indicate that it is part of a list. You may specify as many entries as you wish.
[csv] path = "data/output_moselle.csv" [[csv.column]] header = "Q" parameter = "lateral.river.q" reducer = "maximum" [[csv.column]] header = "volume" index = 1 parameter = "lateral.river.reservoir.volume" [[csv.column]] coordinate.x = 6.255 coordinate.y = 50.012 header = "temp_bycoord" parameter = "vertical.temperature" [[csv.column]] header = "temp_byindex" index.x = 100 index.y = 264 parameter = "vertical.temperature" [[csv.column]] header = "Q" map = "gauges" parameter = "lateral.river.q" [[csv.column]] header = "recharge" map = "subcatchment" parameter = "vertical.recharge" reducer = "mean"
It is possible to modify model parameters and forcing through the TOML file. Two options to modify input parameters are available:
- Set an input parameter (static) to an uniform value.
- Modify an input parameter (cyclic and static) or forcing variable through the use of a
To set for example the input parameter
cfmax to an uniform value of 2.5:
[input.vertical] water_holding_capacity = "WHC" waterfrac = "WaterFrac" cfmax.value = 2.5
To change for example the forcing variable
precipitation with a
scale factor of 1.5 and an
offset of 0.5:
[input.vertical.precipitation] netcdf.variable.name = "P" scale = 1.5 offset = 0.5