Functions to perform simulations on a watershed described by a set of connected grid cells.

  • Function spwb_land implements a distributed hydrological model that simulates daily local water balance, from spwb_day, on grid cells of a watershed while accounting for overland runoff, subsurface flow and groundwater flow between cells.

  • Function growth_land is similar to spwb_land, but includes daily local carbon balance, growth and mortality processes in grid cells, provided by growth_day.

  • Function fordyn_land extends the previous two functions with the simulation of management, seed dispersal, recruitment and resprouting.

spwb_land(
  r,
  sf,
  SpParams,
  meteo = NULL,
  dates = NULL,
  CO2ByYear = numeric(0),
  summary_frequency = "years",
  local_control = medfate::defaultControl(),
  watershed_control = default_watershed_control(),
  parallelize = FALSE,
  num_cores = detectCores() - 1,
  chunk_size = NULL,
  progress = TRUE
)

growth_land(
  r,
  sf,
  SpParams,
  meteo = NULL,
  dates = NULL,
  CO2ByYear = numeric(0),
  summary_frequency = "years",
  local_control = medfate::defaultControl(),
  watershed_control = default_watershed_control(),
  parallelize = FALSE,
  num_cores = detectCores() - 1,
  chunk_size = NULL,
  progress = TRUE
)

fordyn_land(
  r,
  sf,
  SpParams,
  meteo = NULL,
  dates = NULL,
  CO2ByYear = numeric(0),
  local_control = medfate::defaultControl(),
  watershed_control = default_watershed_control(),
  management_function = NULL,
  parallelize = FALSE,
  num_cores = detectCores() - 1,
  chunk_size = NULL,
  progress = TRUE
)

Arguments

r

An object of class rast, defining the raster topology.

sf

An object of class sf with the following columns:

  • geometry: Spatial point geometry corresponding to cell centers.

  • elevation: Elevation above sea level (in m).

  • slope: Slope (in degrees).

  • aspect: Aspect (in degrees).

  • land_cover_type: Land cover type of each grid cell (values should be 'wildland', 'agriculture', 'rock', 'artificial' or 'water').

  • forest: Objects of class forest.

  • soil: Objects of class soil or data frames of physical properties.

  • state: Objects of class spwbInput or growthInput (optional).

  • meteo: Data frames with weather data (required if parameter meteo = NULL).

  • crop_factor: Crop evapo-transpiration factor. Only required for 'agriculture' land cover type.

  • snowpack: A numeric vector with the snow water equivalent content of the snowpack in each cell.

  • management_arguments: Lists with management arguments (optional, relevant for fordyn_land only).

  • result_cell: A logical indicating that local model results are desired (optional, relevant for spwb_land and growth_land only).

When using TETIS watershed model, the following columns are also required:

  • channel: A logical vector indicating whether each cell belongs to the channel network.

  • depth_to_bedrock: Depth to bedrock (mm).

  • bedrock_conductivity: Bedrock (saturated) conductivity (in m·day-1).

  • bedrock_porosity: Bedrock porosity.

  • aquifer: A numeric vector with the water content of the aquifer in each cell.

SpParams

A data frame with species parameters (see SpParamsMED).

meteo

Input meteorological data (see spwb_spatial).

dates

A Date object describing the days of the period to be modeled.

CO2ByYear

A named numeric vector with years as names and atmospheric CO2 concentration (in ppm) as values. Used to specify annual changes in CO2 concentration along the simulation (as an alternative to specifying daily values in meteo).

summary_frequency

Frequency in which summary layers will be produced (e.g. "years", "months", ...) (see cut.Date). In fordyn_land summaries are always produced at monthly resolution.

local_control

A list of control parameters (see defaultControl) for function spwb_day or growth_day.

watershed_control

A list of watershed control parameters (see default_watershed_control). Importantly, the sub-model used for lateral water flows - either Francés et al. (2007) or Caviedes-Voullième et al. (2023) - is specified there.

parallelize

Boolean flag to try parallelization (will use all clusters minus one).

num_cores

Integer with the number of cores to be used for parallel computation.

chunk_size

Integer indicating the size of chunks to be sent to different processes (by default, the number of spatial elements divided by the number of cores).

progress

Boolean flag to display progress information for simulations.

management_function

A function that implements forest management actions (see fordyn). of such lists, one per spatial unit.

Value

Functions spwb_land, growth_land and fordyn_land return a list of class of the same name as the function with the following elements:

  • sf: An object of class sf, similar to the output of spwb_spatial, with the following columns:

    • geometry: Spatial geometry.

    • state: A list of model input objects for each simulated stand.

    • aquifer: A numeric vector with the water volume in the aquifer of each cell.

    • snowpack: A numeric vector with the snowpack water equivalent volume of each cell.

    • result: A list of cell results (only for those indicated in the input), with contents depending on the local model.

    • summary: A list of cell summaries, containing the following variables:

      • Rain: Rainfall (in mm).

      • Snow: Snowfall (in mm).

      • Snowmelt: Snow melt (in mm).

      • Interception: Rainfall interception (in mm).

      • NetRain: Net rain, i.e. throughfall, (in mm).

      • Runon: The amount of water imported from other cells via surface runoff (in mm).

      • Runoff: The amount of water exported via surface runoff (in mm).

      • Infiltration: The amount of water infiltrating into the soil (in mm).

      • DeepDrainage: The amount of water draining from soil to the aquifer via deep drainage (in mm).

      • SaturationExcess: The amount of water that reaches the soil surface because of soil saturation (in mm).

      • AquiferDischarge: The amount of water that reaches deepest soil layer from a saturated aquifer (in mm).

      • SubsurfaceInput: The amount of water that reaches the soil from adjacent cells via subsurface flow (in mm).

      • SubsurfaceOutput: The amount of water that leaves the soil towards adjacent cells via subsurface flow (in mm).

      • GroundwaterInput: The amount of water that reaches the aquifer from adjacent cells via groundwater flow (in mm).

      • GroundwaterOutput: The amount of water that leaves the aquifer towards adjacent cells via groundwater flow (in mm).

      • SoilEvaporation: Bare soil evaporation (in mm).

      • Transpiration: Plant transpiration (in mm).

      • SWE: Snow water equivalent (in mm) of the snowpack.

      • Psi1: Soil water potential of the topmost layer (in MPa).

      • SoilVol: Soil water volume integrated across vertical layers (in mm).

      • WTD: Water table depth (in mm from surface).

    In function fordyn_land the sf object contains additional columns:
    • forest: A list of forest objects for each simulated stand, to be used in subsequent simulations (see update_landscape).

    • management_arguments: A list of management arguments for each simulated stand, to be used in subsequent simulations (see update_landscape).

    • tree_table: A list of data frames for each simulated stand, containing the living trees at each time step.

    • shrub_table: A list of data frames for each simulated stand, containing the living shrub at each time step.

    • dead_tree_table: A list of data frames for each simulated stand, containing the dead trees at each time step.

    • dead_shrub_table: A list of data frames for each simulated stand, containing the dead shrub at each time step.

    • cut_tree_table: A list of data frames for each simulated stand, containing the cut trees at each time step.

    • cut_shrub_table: A list of data frames for each simulated stand, containing the cut shrub at each time step.

  • watershed_balance: A data frame with as many rows as summary points and where columns are components of the water balance at the watershed level (i.e., rain, snow, interception, infiltration, soil evaporation, plant transpiration, ...).

  • watershed_soil_balance: A data frame with as many rows as summary points and where columns are components of the water balance at the watershed level restricted to those cells with a soil definition.

  • daily_runoff: A matrix with daily runoff (in m3/day) at each of the outlet cells of the landscape.

Details

Two sub-models are available for lateral water transfer processes (overland flow, sub-surface flow, etc.), either "TETIS" (similar to Francés et al. 2007) or "SERGHEI" (Caviedes-Voullième et al. 2023).

IMPORTANT: medfateland needs to be compiled along with SERGHEI model in order to launch simulations with using this distributed hydrological model.

When running fordyn_land, the input 'sf' object has to be in a Universal Transverse Mercator (UTM) coordinate system (or any other projection using meters as length unit) for appropriate behavior of dispersal sub-model.

Parallel computation is only functional when using SERGHEI, because TETIS requires following a specific cell processing order. Moreover, parallel computations are only recommended for watersheds with large number of grid cells. In watershed with a small number of cells, can result in larger processing times than sequential computation.

References

Francés, F., Vélez, J.I. & Vélez, J.J. (2007). Split-parameter structure for the automatic calibration of distributed hydrological models. Journal of Hydrology, 332, 226–240.

Caviedes-Voullième, D., Morales-Hernández, M., Norman, M.R. & Ogzen-Xian, I. (2023). SERGHEI (SERGHEI-SWE) v1.0: a performance-portable high-performance parallel-computing shallow-water solver for hydrology and environmental hydraulics. Geoscientific Model Development, 16, 977-1008.

Author

Miquel De Cáceres Ainsa, CREAF.

Maria González-Sanchís, Universitat Politecnica de Valencia.

Daniel Caviedes-Voullième, Forschungszentrum Julich.

Mario Morales-Hernández, Universidad de Zaragoza.

Examples

if (FALSE) {
# Load example watershed data
data("example_watershed")

# Set crop factor 
example_watershed$crop_factor <- NA
example_watershed$crop_factor[example_watershed$land_cover_type=="agriculture"] <- 0.75

# Set request for daily model results in cells number 3 and 9
example_watershed$result_cell <- FALSE
example_watershed$result_cell[c(3,9)] <- TRUE

# Get bounding box to determine limits
b <- sf::st_bbox(example_watershed)
b

# Define a raster topology, using terra package, 
# with the same CRS as the watershed. In this example cells have 100 m side.
# Coordinates in the 'sf' object are assumed to be cell centers
r <-terra::rast(xmin = 401380, ymin = 4671820, xmax = 402880, ymax = 4672620, 
                nrow = 8, ncol = 15, crs = "epsg:32631")

# Load example meteo data frame from package meteoland
data("examplemeteo")
  
# Load default medfate parameters
data("SpParamsMED")
  
# Set simulation period
dates <- seq(as.Date("2001-01-01"), as.Date("2001-03-31"), by="day")

# Watershed control parameters (TETIS model; Frances et al. 2007)
ws_control <- default_watershed_control("tetis")

# Launch simulations 
res <- spwb_land(r, example_watershed, SpParamsMED, examplemeteo, 
                 dates = dates, summary_frequency = "month",
                 watershed_control = ws_control)
}