echse_calibwrap: Wrapper function for calibration of the WASA engine of the...
In tpilz/WasaEchseTools: Title: Handy tools for preprocessing and analysis of the hydrological models WASA-SED and ECHSE (limited to the WASA engine). Currently only meant for internal use! If you want to try it, handle with care!

Description Usage Arguments Details Value Note Author(s)

A wrapper function, executing a simulation of the WASA engine for a given parameter realisation.

echse_calibwrap(pars = NULL, dir_input = NULL,
  dir_run = paste0(tempfile(pattern = "echse_calib_"), sep = "/"),
  echse_app = NULL, choices = NULL, sim_start = NULL,
  sim_end = NULL, resolution = 86400, dat_streamflow = NULL,
  dat_pr = NULL, flood_thresh = NULL, thresh_zero = NULL,
  warmup_start = 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 = NULL,
  keep_rundir = FALSE, error2warn = FALSE, nthreads = 1)

`pars`	A named vector of type numeric with the values of selected parameters. Replaces all specified parameter values within the sharedParamNum_WASA_* files with the given values.
`dir_input`	Character string giving the main simulation directory containing a directory 'data' with the readily prepared ECHSE input (e.g. prepared with function `echse_prep_runs`).
`dir_run`	Character specifying the directory for the model run with the current parameter realisation. Default: A temporary directory created with `tempfile`.
`echse_app`	Character string giving the system command of the application.
`choices`	A named data.frame with each element containing the flag for a specific choice. See the latest version of ECHSE's WASA engine for required choice flags. Replaces all specified parameter values within the sharedParamNum_WASA_* files with the given values. If `NULL` (the default), it is assumed the model is run with default or manually defined selections.
`sim_start`	Character string giving the start date of the simulation period in the format "%Y-%m-%d %H:%M:%S".
`sim_end`	Character string giving the end date of the simulation period in the format "%Y-%m-%d %H:%M:%S".
`resolution`	Integer giving the simulation time step in seconds. Default: 86400 (i.e. daily resolution).
`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 ECHSE 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_start`	Character string giving the start date of the warm-up period in the format "%Y-%m-%d %H:%M:%S". If `NULL` (default), argument 'sim_start' will be used.
`warmup_len`	Integer giving the length of the warm-up period in months. Default: 3.
`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.
`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.
`keep_warmup_states`	Logical value. Shall state file after finishing the warm-up runs be stored for upcomming runs? In addition, file 'init_stor_sum_m3.dat' containg a single value of total catchment storage in m3 will be created. WARNING: The files will be stored in the ECHSE setup in `dir_input` and existing state 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`	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`.
`error2warn`	Value of type `logical`. Shall runtime errors of the model be reported as a warning instead of stopping this function with an error? 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`.
`nthreads`	Number of cores that shall be employed for the ECHSE run (argument 'number_of_threads' in configuration file). See ECHSE core manual for more information.

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.

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 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.

In the current form, this function cannot deal with *_tpl.dat files generated by echse_prep_runs (argument prep_tpl)!

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. In that case, create an empty initial logfile 'log' before starting the parallel calibration routine to invoke the file name extension via tempfile right away.

Tobias Pilz tpilz@uni-potsdam.de

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