run_sl: Run SamsaRaLight radiative balance

In SamsaRaLight: Simulate Tree Light Transmission Using Ray-Tracing

Run SamsaRaLight radiative balance

Description

This function computes light interception and radiative balance for a forest stand using the SamsaRaLight ray-tracing engine.

Usage

run_sl(
  sl_stand,
  monthly_radiations,
  sensors_only = FALSE,
  detailed_output = FALSE,
  parallel_mode = FALSE,
  n_threads = NULL,
  verbose = TRUE
)

Arguments

sl_stand	An object of class "sl_stand" describing the forest stand, created with create_sl_stand. It contains trees, sensors, terrain, and grid geometry.
monthly_radiations	A data.frame of monthly horizontal radiation (Hrad, in MJ m^{-2}) and diffuse-to-global ratio (DGratio), typically obtained using get_monthly_radiations and checked using check_monthly_radiations..
sensors_only	Logical. If TRUE, compute light interception only for sensors (much faster).
detailed_output	Logical. If TRUE, the output contains detailed diffuse/direct energies in the light datasets, full interception matrices interceptions and output of ray discretization monthy_rays. If FALSE, only total energies are returned (recommended for most uses).
parallel_mode	logical. If TRUE, ray–target computations are parallelised using OpenMP. If FALSE, the model runs in single-thread mode. SamsaRaLight uses OpenMP for ray–target parallelisation. To avoid competition between OpenMP and BLAS (matrix algebra libraries), BLAS is automatically forced to single-thread mode during the simulation. Using parallel_mode = TRUE is strongly recommended for large stands or fine ray discretisation, as computation time scales almost linearly with the number of available CPU cores.
n_threads	integer or NULL. Number of CPU threads to use when parallel_mode = TRUE. If NULL (default), OpenMP automatically selects the number of available cores. If provided, must be a positive integer.
verbose	Logical; if TRUE, informative messages are printed.

Details

It is the standard user interface of SamsaRaLight. Advanced ray-tracing and sky discretization parameters are internally set to robust defaults and do not need to be provided.

Internally, run_sl() calls the advanced engine run_sl_advanced() with fixed ray-tracing and sky discretization.

You should normally not use SamsaRaLight:::run_sl_advanced() directly unless you are developing new ray-tracing configurations or doing methodological work.

Value

An object of class "sl_output", containing:

light

A list of data.frames with simulated light interception:

• trees: light intercepted by trees

• cells: light received by ground cells

• sensors: light received by sensors

info

A list of metadata about the simulation (latitude, sky type, torus use, etc.).

monthly_rays

(only if detailed_output = TRUE) Discretization of monthly radiations

interceptions

(only if detailed_output = TRUE) interception matrices between trees and rays for each cell/sensor

See Also

create_sl_stand, check_inventory, check_sensors, get_monthly_radiations, check_monthly_radiations

Examples

data_prenovel <- SamsaRaLight::data_prenovel

stand <- create_sl_stand(
  trees = data_prenovel$trees,
  sensors = data_prenovel$sensors,
  cell_size = 10,
  latitude = data_prenovel$info$latitude,
  slope = data_prenovel$info$slope,
  aspect = data_prenovel$info$aspect,
  north2x = data_prenovel$info$north2x
)

out <- run_sl(
  sl_stand = stand,
  monthly_radiations = data_prenovel$radiations
)

str(out)

SamsaRaLight documentation built on April 16, 2026, 5:08 p.m.