db_echse_input: Create ECHSE input files

In tpilz/lumpR: Landscape Unit Mapping Program for R

Create ECHSE input files

Description

Function takes parameters from a parameter database and generates ASCII files as input to specific model engines of the ECHSE simulation environment.

Usage

db_echse_input(dbname, start_year = NULL, end_year = NULL,
  res_hourly = FALSE, tz = NULL, proj_dir = "./", proj_name = "",
  overwrite = F, verbose = TRUE)

Arguments

dbname	Name of the data source (DSN) registered at ODBC.
start_year	First year of the vegetation parameter time series (typically equal to the simulation period). Only needed if column 'yearm' in table 'rainy_season' contains values of -1. Otherwise it can be set to NULL (default).
end_year	Last year of the vegetation parameter time series (typically equal to the simulation period). Only needed if column 'yearm' in table 'rainy_season' contains values of -1. Otherwise it can be set to NULL (default).
res_hourly	logical. Do you want to run ECHSE in hourly resolution? In that case, additional 'vegPar_time_series' files 'utc_add_data.dat' and 'hour_data.dat' will be created. Argument tz needs to be given. Default: FALSE.
tz	Character string with the timezone of your location. Needed to calculate 'utc_add' if argument res_hourly = TRUE. Default: NULL.
proj_dir	Path to your working directory. Output of this function will be written to this location.
proj_name	Name of your project. In proj_dir a directory proj_name will be created containing the subdirectory 'data' containing 'parameter' and 'initials' with ECHSE input files.
overwrite	logical. Should existing files and directories be overwriten? Default: FALSE.
verbose	logical. Should detailed information during execution be printed? Default: TRUE.

Details

Function creates most of the input files needed for the ECHSE model engine WASA, except for meteorological forcing which has to be prepared separately considering ECHSE tools, see https://github.com/echse/echse_tools.

More information about ECHSE, including the source code, documentation, specific model engines, and tools for model setup, can be found at https://github.com/echse/. For information on general file structures and how to run and install echse, read the core manual. The engine manual contains descriptions of the model engines and incorporated processes.

Value

The following subdirectories and files within proj_dir/proj_name/data will be created:

catchment

objDecl.dat
Object declaration table containing all object definitions ,including membership to a specific object group for the current model setup.

objLink.dat
Table specifying object relations, i.e. which output of a certain object is the input of another object, and the type of the relation. Hereby, forwardType = true means that the source object is simulated before the target object and vice verse if forwardType = false.

parameter

dummy_fun.dat
Dummy parameter function file used as input if no parameter function is given for a specific object group.

dummy_num.dat
Dummy parameter file used as input if no parameters are given for a specific object group.

paramFun_WASA_tc.dat
Defines parameter functions for objects of class 'WASA_tc' whereas the specific look-up tables are given in the linked files, in this case within subdirectory 'parFun_pos2area'. These are relating the relative position along the hillslope of a certain TC within a LU to the areal fraction covered.

paramNum_*.dat
Parameter files containing parameter definitions of individual objects of the respective object group. Values have been derived from the WASA parameter database (ATTENTION: some parameter names have been changed and unit conversions where necessary!). For description of parameters see the ECHSE WASA engine documentation.

SharedParamNum_*.dat
Definition of parameter values used by all objects of a specific object group. In this case, these are largely default values of choice flags and meteorological parameters which might have to be adapted manually, see ECHSE WASA engine documentation.

vegPar_time_series

Contains time series files *_data.dat of external input/forcing variables related to vegetation grwoth. The first column is the time stamp in ISO format and the other columns contain the respective variable value at a certain location. The file input_ext_locs.dat references the external variable to a model object, whereas one object can be referenced to different locations with specific weight (summing up to one). ATTENTION: input_ext_locs.dat has to be extended by separately prepared meteorological input!

This function creates time series of juliany day (or day of year) and different vegetation specific variables (root depth, canopy height, albedo, and leaf area index). Furthermore, time series of utc_add and hour of day will be created if argument res_hourly = TRUE. Vegetation growth is not explicitly modelled within the WASA engine but is deduced from four node points of the variable within a year (see WASA parameter database, table 'vegetation') and start and end of the growing season for each year estimated from a precipitation time series (see WASA parameter database table 'rainy_season' filled via lumpR functions rainy_season and calc_seasonality) or deviated by other means.

initials

Initial conditions, i.e. initial values of state variables for all objects (init_scal.dat for scalar and init_vect.dat for vectorial state variables).

Currently, soil moisture is set to a value between permanent wilting point and field capacity. Groundwater and interception storages are set to zero.

To avoid crude estimates, you can as well use the state outputs of another simulation. In general, you should choose an appropriate warm-up period, which is highly catchment dependent(!), and carefully examine the development of state variables to reduce uncertainties from initial conditions.

Note

So far, this function is only capable of creating input files for the ECHSE model engine WASA. Other ECHSE engines cannot be initialised with this function, although that might be enabled in the future.

Author(s)

Tobias Pilz [e-mail]

References

Theoretical description of the ECo-Hydrological Simulation Environment (ECHSE):

Kneis, D. (2015): A lightweight framework for rapid development of object-based hydrological model engines. Environmental Modelling & Software, 68, 110-121, doi: 10.1016/j.envsoft.2015.02.009

tpilz/lumpR documentation built on Aug. 5, 2023, 1:31 a.m.