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	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	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	vertical matrix drainage from lowest layer	mm/d

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