spwb_land: Watershed simulations

Description

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.

Usage

spwb_land(
  r,
  sf,
  SpParams,
  meteo = NULL,
  dates = NULL,
  CO2ByYear = numeric(0),
  summary_blocks = NULL,
  summary_frequency = "years",
  local_control = defaultControl(soilDomains = "single"),
  watershed_control = default_watershed_control(),
  parallelize = FALSE,
  num_cores = parallel::detectCores() - 1,
  progress = TRUE
)
growth_land(
  r,
  sf,
  SpParams,
  meteo = NULL,
  dates = NULL,
  CO2ByYear = numeric(0),
  summary_blocks = NULL,
  summary_frequency = "years",
  local_control = medfate::defaultControl(soilDomains = "single"),
  watershed_control = default_watershed_control(),
  parallelize = FALSE,
  num_cores = parallel::detectCores() - 1,
  progress = TRUE
)
fordyn_land(
  r,
  sf,
  SpParams,
  meteo = NULL,
  dates = NULL,
  CO2ByYear = numeric(0),
  summary_blocks = NULL,
  summary_frequency = "years",
  local_control = medfate::defaultControl(soilDomains = "single"),
  watershed_control = default_watershed_control(),
  dispersal_control = default_dispersal_control(),
  management_function = NULL,
  parallelize = FALSE,
  num_cores = parallel::detectCores() - 1,
  progress = TRUE
)
# S3 method for spwb_land
summary(object, ...)
# S3 method for growth_land
summary(object, ...)

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:

watershed_control: A list with input control parameters.
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.
- summary: A list of cell summaries containing at least the following variables (additional variables are summarized using summary_blocks):
  - MinTemperature: Minimum temperature (degrees Celsius).
  - MaxTemperature: Maximum temperature (degrees Celsius).
  - PET: Potential evapotranspiration (in mm).
  - Rain: Rainfall (in mm).
  - Snow: Snowfall (in mm).
  - SWE: Snow water equivalent (in mm) of the snowpack.
  - RWC: Soil relative water content with respect to field capacity (in percent).
  - SoilVol: Soil water volume integrated across vertical layers (in mm).
  - WTD: Saturated soil water table depth (in mm from surface).
  - DTA: Depth to aquifer (in m from surface).
- result: A list of cell detailed results (only for those indicated in the input), with contents depending on the local model.
- outlet: A logical vector indicating outlet cells.
- channel: A logical vector indicating channel cells.
- target_outlet: Index of the outlet cell to which the channel leads (NA for non-channel cells).
- outlet_backlog: A vector indicating channel water volume (m3) backlog of outlet cells (for subsequent simulations).
- subwatershed: Integer vector indicating watershed subunits (NA if subwatersheds = FALSE in watershed control parameters).
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 days and where columns are (spatially-averaged) 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 days and where columns are (spatially-averaged) components of the water balance at the watershed level restricted to those cells with a soil definition.
channel_export_m3s: A matrix with daily values of runoff (in m3/s) reaching each of the channel cells of the landscape (useful for channel processing with an external model).
outlet_export_m3s: A matrix with daily values of runoff (in m3/s) reaching each of the outlet cells of the landscape. Each outlet drains its own subset of cells (sometimes including channel routing), so the daily overall watershed export corresponds to the sum of row values.

Arguments

r

An object of class SpatRaster, 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.
local_control: A list of control parameters (optional). Used to override function parameter local_control for specific cells (values can be NULL for the remaining ones).
snowpack: An optional numeric vector with the snow water equivalent content of the snowpack in each cell (in mm). If missing it will be initialized to zero.
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). Model results are only produced for wildland and agriculture cells.

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

depth_to_bedrock: Depth to bedrock (mm).
bedrock_conductivity: Bedrock (saturated) conductivity (in m·day-1).
bedrock_porosity: Bedrock porosity (the proportion of pore space in the rock).

When using TETIS watershed model, the following columns are OPTIONAL:

aquifer: A numeric vector with the water content of the aquifer in each cell (in mm). If missing, it will be initialized to zero.
deep_aquifer_loss: A numeric vector with the maximum daily loss to a deeper aquifer (in mm·day-1). If missing all cells take their value from deep_aquifer_loss in default_watershed_control
channel: A logical (or binary) vector indicating overland channel routing.
outlet_backlog: A vector indicating, for outlet cells, backlog volume of water (m3) of the corresponding channel network from a previous simulation.

SpParams

A data frame with species parameters (see SpParamsMED). IMPORTANT: If sf has been already initialized, this parameter has no effect.

meteo

Input meteorological data (see spwb_spatial and details).

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_blocks

A character vector with variable blocks for cell summaries (or NULL to retain only basic summaries). Accepted summary blocks for spwb_land are "WaterBalance", "Stand" and "FireHazard". For growth_land and fordyn_land, "CarbonBalance" and "BiomassBalance" are also accepted.

summary_frequency

Frequency in which cell summary will be produced (e.g. "years", "months", "weeks", ...) (see cut.Date). In fordyn_land summary frequency can only be "months" or "years".

local_control

A list of control parameters (see defaultControl) for function spwb_day or growth_day. By default, parameter soilDomains is set to "single", meaning a single-domain Richards model. IMPORTANT: If sf has been already initialized, this parameter has no effect.

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 (only works with subwatersheds, see details).

num_cores

Integer with the number of cores to be used for parallel computation (by default it will use all clusters minus one).

progress

Boolean flag to display progress information for simulations.

dispersal_control

A list of dispersal control parameters (see default_dispersal_control). If NULL, then dispersal is not simulated.

management_function

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

object

An object of class spwb_land or groth_land

...

Additional parameters for summary functions

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.

Details

IMPORTANT: Simulation function will normally call the initialization of state variables via an internal call to initialize_landscape, using parameters local_control and SpParams in this call. The default soilDomains = "single" means that vertical bulk soil flows are simulated using a single permeability domain with Richards equation. However, if object sf has been previously initialized, then the control parameters of this previous initialization will remain the same. In other words, parameters local_control and SpParams will have no effect in the call to the simulation routines if the sf has been previously initialized.

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.

Due to the large communication overload, parallel computation is only allowed for TETIS in combination with definition of subwatersheds (see flag of TETIS parameters in default_watershed_control).

When dealing with large data sets, weather data included in the 'sf' object will likely be very data hungry. In those cases, it is recommended to resort on weather interpolation (see spwb_spatial). Weather interpolation can be done using a coarser resolution than that of raster 'r', by changing the watershed control parameter called 'weather_aggregation_factor' (see default_watershed_control).

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.

Examples

Run this code

# \donttest{
# 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, 6 (outlet) and 9
example_watershed$result_cell <- FALSE
example_watershed$result_cell[c(3,6,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)
                 
# Print a summary of water balance components
summary(res)

# Option 'reduce_to_dominant = TRUE' in initialization, may be useful to speed up calculations
example_simplified <- initialize_landscape(example_watershed, SpParams = SpParamsMED,
                                           local_control = defaultControl(soilDomains = "single"), 
                                           reduce_to_dominant = TRUE)

# Launch simulations over simplified landscape (should be considerably faster)
res_simplified <- spwb_land(r, example_simplified, SpParamsMED, examplemeteo, 
                            dates = dates, summary_frequency = "month",
                            watershed_control = ws_control)
# }

Run the code above in your browser using DataLab