wasa_calibwrap: Wrapper function for calibration of the WASA-SED model

Description Usage Arguments Details Value Note Author(s)

Description

A wrapper function, executing a simulation of the WASA-SED model for a given parameter realisation.

Usage

1
2
3
4
5
6
7
8
9
wasa_calibwrap(pars = NULL, wasa_app = NULL, sp_input_dir = NULL,
  meteo_dir = NULL, dir_run = paste0(tempfile(pattern = "wasa_calib_"),
  sep = "/"), sim_start = NULL, sim_end = NULL, resol = "daily",
  warmup_start = NULL, radex_file = NULL, dat_streamflow = NULL,
  dat_pr = NULL, flood_thresh = NULL, thresh_zero = NULL,
  warmup_len = 3, max_pre_runs = 20, storage_tolerance = 0.01,
  keep_warmup_states = FALSE, return_val = "river_flow_ts",
  return_sp = FALSE, log_meta = NULL, keep_rundir = FALSE,
  keep_log = FALSE, error2warn = FALSE)

Arguments

pars

A named vector of type numeric with the values of selected parameters (directed to wasa_modify_pars).

wasa_app

Character string giving the system command of the WASA-SED application (directed to wasa_run).

sp_input_dir

Character string of the directory containing the spatial WASA-SED input. E.g. the output of db_wasa_input (argument 'dest_dir') (directed to wasa_prep_runs).

meteo_dir

Character string of the directory containing the time series input files for the WASA-SED model. Requires the files temperature.dat, radiation.dat, humidity.dat, and rain_daily.dat or rain_hourly.dat (directed to wasa_prep_runs).

dir_run

Character specifying the directory for the model run with the current parameter realisation (directed to wasa_run). Default: A temporary directory created with tempfile.

sim_start

Object of class 'date' giving the start date of the simulation (will be written into WASA-SED input file 'do.dat'; directed to wasa_prep_runs).

sim_end

Object of class 'date' giving the end date of the simulation (will be written into WASA-SED input file 'do.dat' directed to wasa_prep_runs).

resol

Temporal resolution of the model simulations. Supported are: 'daily' (default) and 'hourly'.

warmup_start

An object of class 'date' giving the start date of the warm-up period. If NULL (default), the value in do.dat (lines 4 and 6) is used. Directed to wasa_run.

radex_file

Character string of the file (including path) of preprared extraterrestrial radiation input (named 'extraterrestrial_radiation.dat') (directed to wasa_prep_runs)).

dat_streamflow

OPTIONAL: Object of class 'xts' containing a time series of streamflow at the catchment outlet in (m3/s) in the resolution of the model run. NA values are allowed and will be discarded for goodness of fit calculations. Only needed if return_val = 'nse'.

dat_pr

OPTIONAL: Object of class 'xts' containing a time series of catchment-wide average precipitation in (m3) in the resolution of the model run. If not given (default), it will be read (and calculated) from the WASA-SED input files if needed. However, it is more efficient in terms of function execution time to specify it as input if needed. Only needed if return_val = 'hydInd'.

flood_thresh

OPTIONAL: Numeric value giving the threshold in (m3/s) for the definition of a flood event (directed to hydInd). Only needed if return_val = 'hydInd'.

thresh_zero

OPTIONAL: Values of discharge in (m3/s) below this value will be treated as zero flows (directed to hydInd). Only needed if return_val = 'hydInd'.

warmup_len

Integer giving the length of the warm-up period in months. Default: 3. Directed to wasa_run.

max_pre_runs

Integer specifying the maximum number of warm-up iterations to be applied. If the relative storage change is still larger than storage_tolerance after max_pre_runs iterations, the warm-up will be aborted and the model be run anyway. A warning will be issued. Default: 20. Directed to wasa_run.

storage_tolerance

Numeric value giving the relative change of the model's water storages between two connsecutive warm-up runs below which the warm-up will be concluded and the actual model simulation be started. Default: 0.01. Directed to wasa_run.

keep_warmup_states

Logical value. Shall state storage files after finishing the warm-up runs be stored for upcomming runs (i.e. *.stat files be copied into sp_input_dir/input)? WARNING: Existing *.stat files will be overwritten! Default: FALSE. This option might be useful for calibration runs as it might reduce the number of necessary warm-up runs for each new parameter set.

return_val

Character vector specifying your choice of what this function shall return. Default: 'river_flow'. See description of return value below.

return_sp

Logical flag specifying if certain output shall be given including spatial variability at subbasin level instead of mere catchment specific values. See description of return values below for spatial outputs. Default: FALSE.

log_meta

Character containg the name (and path) of a file into which information about the function call will be written. See below for more information. Default: NULL, i.e. no logile will be created. If the file already exists, the file name to be created will be extended by a call to tempfile.

keep_rundir

Value of type logical. Shall directory dir_run be retained (TRUE) or deleted (FALSE) after function execution? Default: FALSE.

keep_log

Value of type logical. Shall the WASA-SED specific log file (not to be confused with log_meta!) of the model run be written (to dir_run)? Default: FALSE. Will be ignored if keep_rundir = FALSE. Directed to wasa_run.

error2warn

Value of type logical. Shall runtime errors of the model be reported as a warning instead of stopping this function with an error? If so, the model run's log file will be saved and, in case of reasonable model output, this wrapper function will proceed as usual. If no reasonable output could be found, a value NA will be returned. Default: FALSE. Also directed to wasa_run.

Details

Function is a wrapper function, internally executing functions wasa_prep_runs, wasa_modify_pars, and wasa_run and processing and returning the simulation output as specified. The function can be employed by model calibration functions such as dream or optim_dds, or to execute single model runs within a single function call.

Value

Function returns a named list or a single element (if length(return_val) = 1) of numeric value(s). Can be controlled by argument return_val. Currently implemented are the options:

river_flow_[mm|ts]: A single value of the catchment's simulated river outflow over the specified simulation period in (mm) or a time series of class 'xts' in (m3/s). Respects return_sp (only ts, river_flow_mm is only given for catchment outlet!).

eta_mm[_ts]: A single value of the catchment's simulated amount of actual evapotranspiration over the specified simulation period in (mm) or a time series of class 'xts' in (mm/timestep). Respects return_sp.

etp_mm[_ts]: A single value of the catchment's simulated amount of potential evapotranspiration over the specified simulation period in (mm) or a time series of class 'xts' in (mm/timestep). Respects return_sp.

runoff_total_mm[_ts]: A single value of the catchment's simulated amount of total runoff, i.e. runoff contribution into river(s), over the specified simulation period in (mm). Respects return_sp or a time series of class 'xts' in (mm/timestep).

runoff_gw_mm[_ts]: A single value of the catchment's simulated amount of groundwater runoff, i.e. groundwater contribution into river(s), over the specified simulation period in (mm). Respects return_sp or a time series of class 'xts' in (mm/timestep).

runoff_sub_mm[_ts]: A single value of the catchment's simulated amount of subsurface runoff, i.e. near-surface soil water (excl. groundwater!) contribution into river(s), over the specified simulation period in (mm) or a time series of class 'xts' in (mm/timestep). Note: due to computational reasons, 'runoff_gw_mm' will be given in addition if this value is set. Respects return_sp.

runoff_surf_mm[_ts]: A single value of the catchment's simulated amount of surface runoff, i.e. surface water contribution into river(s), over the specified simulation period in (mm) or a time series of class 'xts' in (mm/timestep). Respects return_sp.

hydInd: Named vector of hydrological indices calculated with function hydInd. See function's doc for more information. This option requires the optional input arguments flood_thresh, thresh_zero, and (optional) dat_pr.

nse: A single numeric value giving the Nash-Sutcliffe efficiency of streamflow simulation at the catchment outlet (a common goodness of fit measure of hydrological model runs).

kge: A single numeric value giving the Kling-Gupta efficiency of streamflow simulation at the catchment outlet (see paper https://doi.org/10.1016/j.jhydrol.2009.08.003).

If argument log_meta was given, the logfile contains the following information: parameter names and corresponding realisations, output element names and corresponding values, run_dir: realisation of argument dir_run, time_total: total time for function execution (i.e. until writing logfile, in secs.), time_simrun: runtime of the simulation run (in secs.), time_warmup: total runtime for all warm-up runs (in secs.), warmup_iterations: number of warm-up iterations, warmup_storchange: relative storage change after the last warm-up iteration.

Note

To avoid warm-up runs, set max_pre_runs or warmup_len to zero.

Model's water balance: runoff_total_mm = runoff_surf_mm + runoff_sub_mm + runoff_gw_mm. Moreover, river_flow_mm should be slight less than (due to transmission losses and storage changes; but all in all almost equal to) runoff_total_mm as long as there is no artificial influence (e.g. from reservoirs).

Initial states can have a large influence, depending on setup and parameterisation. Therefore, it is advisable to make some test runs with different warmup parameters ( warmup_start, warmup_len, max_pre_runs, storage_tolerance, keep_warmup_states) before starting a calibration run! Consecutive runs with the same parameterisation should come up with the same results when keep_warmup_states = TRUE.

If running this function in parallel mode: Setting argument keep_warmup_states = TRUE can have problematic side effects due to parallel reading and (over-)writing of the same files. To accelerate warmup anyway, you can generate default initial storage files by running a default parametrisation over the warmup horizon until convergence is reached and use the resulting storage files as initial storages for all calibration runs. A similar problem arises When specifying argument log_meta. In that case, create an empty initial logfile 'log_meta' before starting the parallel calibration routine to invoke the file name extension via tempfile right away.

Author(s)

Tobias Pilz tpilz@uni-potsdam.de


tpilz/WasaEchseTools documentation built on May 5, 2019, 12:33 p.m.