Run the LWF-Brook90 hydrologic model — run

Sets up the input objects for the LWF-Brook90 hydrologic model, starts the model, and returns the selected results.

run_LWFB90(
  options_b90,
  param_b90,
  climate,
  precip = NULL,
  soil = NULL,
  output_fun = NULL,
  rtrn_input = TRUE,
  rtrn_output = TRUE,
  chk_input = TRUE,
  run = TRUE,
  timelimit = Inf,
  verbose = FALSE,
  ...
)

Arguments

options_b90: Named list of model control options. Use set_optionsLWFB90 to generate a list with default model control options.
param_b90: Named list of model input parameters. Use set_paramLWFB90 to generate a list with default model parameters.
climate: Data.frame with daily climatic data, or a function that returns a suitable data.frame. See details for the required variables.
precip: Data.frame with columns 'dates' and 'prec' to supply precipitation data separately from climate data. Can be used to provide sub-day resolution precipitation data to LWFBrook90. For each day in dates, 1 (daily resolution) to 240 values of precipitation can be provided, with the number of values per day defined in options_b90$prec_interval.
soil: Data.frame containing the hydraulic properties of the soil layers. See section 'Soil parameters'
output_fun: A function or a list of functions of the form f(x,...), where x is the object regularly returned by run_LWFB90. During function evaluation, x contains model input and selected output objects, irrespective of rtrn_input and rtrn_output. Can be used to aggregate output on-the-fly, and is especially useful if the function is evaluated within a large multi-run application, for which the output might overload the memory. (see run_multi_LWFB90 and run_multisite_LWFB90).
rtrn_input: Logical: append param_b90, options_b90, and daily plant properties (standprop_daily, as derived from parameters) to the result?
rtrn_output: Logical: return the simulation results select via output?
chk_input: Logical wether to check param_b90, options_b90, climate, precip, and soil for completeness and consistency.
run: Logical: run LWF-Brook90 or only return model input objects? Useful to inspect the effects of options and parameters on model input. Default is TRUE.
timelimit: Integer to set elapsed time limits (seconds) for running LWF-Brook90.
verbose: Logical: print messages to the console? Default is FALSE.
...: Additional arguments passed to output_fun and/or climate, if the latter is a function.

Value

A list containing the selected model output (if rtrn_output == TRUE), the model input (if rtrn_input == TRUE, except for climate), and the return values of output_fun if specified.

Climate input data

The climate data.frame (or function) must contain (return) the following variables in columns named 'dates' (Date), 'tmax' (deg C), 'tmin' (deg C), 'tmean' (deg C), 'windspeed' (m/s), 'prec' (mm) , 'vappres' (kPa), and either 'globrad' ( MJ/(m²d) ) or 'sunhours' (h). When using sunhours, please set options_b90$fornetrad = 'sunhours'.

Soil input parameters

Each row of soil represents one layer, containing the layers' boundaries and soil hydraulic parameters. The column names for the upper and lower layer boundaries are 'upper' and 'lower' (m, negative downwards). When using options_b90$imodel = 'MvG', the hydraulic parameters are 'ths', 'thr', 'alpha' (1/m), 'npar', 'ksat' (mm/d) and 'tort'. With options_b90$imodel = 'CH', the parameters are 'thsat', 'thetaf', 'psif' (kPa), 'bexp', 'kf' (mm/d), and 'wetinf'. For both parameterizations, the volume fraction of stones has to be named 'gravel'. If the soil argument is not provided, list items soil_nodes and soil_materials of param_b90 are used for the simulation. These have to be set up in advance, see soil_to_param.

Outputs

Name	Description	Unit	yr
year	-	mo	month
-	da	day of month	-
doy	day of year	-	aa
average available energy above canopy	W/m2	adef	available water deficit in root zone
mm	asubs	average available energy below canopy	W/m2
awat	total available soil water in layers with roots between -6.18 kPa and `param_b90$psicr`	mm	balerr
error in water balance (daily value, output at the day's last precipitation interval)	mm	byfl	total bypass flow
mm/d	cc	cold content of snowpack (positive)	MJ m-2
dsfl	downslope flow	mm/d	evap
evapotranspiration	mm/d	flow	total streamflow
mm/d	gwat	groundwater storage below soil layers	mm
gwfl	groundwater flow	mm/d	intr
intercepted rain	mm	ints	intercepted snow
mm	irvp	evaporation of intercepted rain	mm/d
isvp	evaporation of intercepted snow	mm/d	lngnet
net longwave radiation	W/m2	nits	total number of iterations
-	pint	potential interception for a canopy always wet	mm/d
pslvp	potential soil evaporation	mm/d	ptran
potential transpiration	mm/d	relawat	relative available soil water in layers with roots
-	rfal	rainfall	mm/d
rint	rain interception catch rate	mm/d	rnet
rainfall to soil surface	mm/d	rsno	rain on snow
mm/d	rthr	rain throughfall rate	mm/d
sthr	snow throughfall rate	mm/d	safrac
source area fraction	-	seep	seepage loss
mm/d	sfal	snowfall	mm/d
sint	snow interception catch rate	mm/d	slfl
input to soil surface	mm/d	slvp	evaporation rate from soil
mm/d	slrad	average solar radiation on slope over daytime	W/m2
solnet	net solar radiation on slope over daytime	W/m2	smlt
snowmelt	mm/d	snow	snowpack water equivalent
mm	snowlq	liquid water content of snow on the ground	mm
snvp	evaporation from snowpack	mm/d	srfl
source area flow	mm/d	stres	tran / ptran (daily value, output at the day's last precipitation interval)
-	swat	total soil water in all layers	mm
tran	transpiration	mm/d	vrfln

Layer outputs

Name	Description	Unit	yr
year	-	mo	month
-	da	day of month	-
doy	day of year	-	nl
index of soil layer		swati	soil water volume in layer
mm	theta	water content of soil layer, mm water / mm soil matrix	-
wetnes	wetness of soil layer, fraction of saturation	-	psimi
matric soil water potential for soil layer	kPa	infl	infiltration to soil water in soil layer
mm/d	byfl	bypass flow from soil layer	mm/d
tran	transpiration from soil layer	mm/d	vrfl
vertical matrix drainage from soil layer	mm/d	dsfl	downslope drainage from layer
mm/d	ntfl	net flow into soil layer	mm/d

Examples

# Set up lists containing model control options and model parameters:
param_b90 <- set_paramLWFB90()
options_b90 <- set_optionsLWFB90()

# Set start and end Dates for the simulation
options_b90$startdate <- as.Date("2003-06-01")
options_b90$enddate <- as.Date("2003-06-30")

# Derive soil hydraulic properties from soil physical properties
# using pedotransfer functions
soil <- cbind(slb1_soil, hydpar_wessolek_tab(slb1_soil$texture))

# Run LWF-Brook90
b90.result <- run_LWFB90(options_b90 = options_b90,
                        param_b90 = param_b90,
                        climate = slb1_meteo,
                        soil = soil)

# use a function to be performed on the output:
# aggregate soil water storage down to a specific layer
agg_swat <- function(x, layer) {
  out <- aggregate(swati~yr+doy,
                   x$SWATDAY.ASC,
                   FUN = sum,
                   subset = nl <= layer)
  out[order(out$yr, out$doy),]}

# run model without returning the selected output.
b90.aggswat <- run_LWFB90(options_b90 = options_b90,
                         param_b90 = param_b90,
                         climate = slb1_meteo,
                         soil = soil,
                         output_fun = list(swat = agg_swat),
                         rtrn_output = FALSE,
                         layer = 10)  # passed to output_fun
str(b90.aggswat$output_fun$swat)
#>  NULL