Calculate water balance for a time series at a single site

This is the core water balance calculation that operates on primitive numeric vectors for easy testing and debugging. Each input is a time series of daily values for a single location (one date per row). The units for all quantities are arbitrary, but they should be consistent (distance / time; e.g., most commonly, mm/day).

Usage

calc_water_balance(
  et,
  precip,
  whc,
  whc_min_frac,
  W_initial = NULL,
  w_min = NULL,
  irrigation_max = NULL
)

Arguments

et

Vector of evapotranspiration values (distance / time)

precip

Vector of precipitation values (distance / time)

whc

Water holding capacity (distance); the plant-available range from wilting point to field capacity (i.e., `whc = field_capacity - wilting_point`). Can be a single value or a vector of the same length as `et`.

whc_min_frac

Fraction of WHC for minimum water level (irrigation trigger); unused if `w_min` is explicitly specified. Can be a single value or a vector of the same length as `et`.

W_initial

Initial soil water content at start of time series (distance); defaults to `whc[1]` (field capacity) if NULL

w_min

Minimum water level threshold (distance); irrigation is triggered when soil water falls below this level; defaults to `whc_min_frac * whc` if NULL. Can be a single value or a vector of the same length as `et`.

irrigation_max

If set, maximum amount of irrigation to apply at a time (distance).

Value

List with vectors: W_t (soil water), irr (irrigation), runoff

Details

This function operates in *relative* WHC space, where: - `w = 0` represents wilting point (no plant-available water) - `w = whc` represents field capacity (maximum plant-available water) - `whc = (field_capacity - wilting_point) * rooting_depth` (the plant-available range)

Although this function can be used as a crude approximation of rice irrigation (by setting `whc_min_frac = 1.0`), we recommend using [calc_water_balance_rice()] instead, which explicitly tracks rice pond depth, implements seepage, etc.

Examples

# Calculate WHC from field capacity, wilting point, and rooting depth
field_capacity <- 0.30  # volumetric (m3/m3)
wilting_point <- 0.10   # volumetric (m3/m3)
rooting_depth <- 1000   # mm
whc <- (field_capacity - wilting_point) * rooting_depth  # mm

# Run water balance with 5 days of ET and precip data
et <- c(4, 5, 6, 4, 3)  # mm/day
precip <- c(0, 0, 10, 0, 0)  # mm/day
result <- calc_water_balance(et, precip, whc = whc, whc_min_frac = 0.5)
str(result)
#> List of 3
#>  $ W_t   : num [1:5] 196 191 195 191 188
#>  $ irr   : num [1:5] 0 0 0 0 0
#>  $ runoff: num [1:5] 0 0 0 0 0