Runs the full light interception and radiative balance simulation for a virtual forest stand with advanced ray-tracing and interception parameters. This function provides full control over ray discretization, sky model, crown interception model, trunk interception, and parallel computation.
Usage
run_sl_advanced(
sl_stand,
monthly_radiations,
sensors_only = FALSE,
use_torus = TRUE,
turbid_medium = TRUE,
extinction_coef = 0.5,
clumping_factor = 1,
trunk_interception = TRUE,
height_anglemin = 10,
direct_startoffset = 0,
direct_anglestep = 5,
diffuse_anglestep = 15,
soc = TRUE,
start_day = 1,
end_day = 365,
detailed_output = FALSE,
parallel_mode = FALSE,
n_threads = NULL,
verbose = TRUE
)Arguments
- sl_stand
An object of class
"sl_stand"representing the virtual forest stand. Each row ofsl_stand$treesrepresents a tree, with required and optional columns describing crown geometry, tree height, crown radius, crown openness, leaf area density, and related attributes. See validate_sl_stand.- monthly_radiations
A data frame containing monthly horizontal radiation (
Hrad) and diffuse-to-global radiation ratios (DGratio), typically computed with get_monthly_radiations.- sensors_only
Logical. If
TRUE, compute light interception only for sensors. Defaults toFALSE.- use_torus
Logical. If
TRUE, use a torus system to handle stand borders. Defaults toTRUE.- turbid_medium
Logical. If
TRUE, crowns are represented as turbid media usingcrown_lad. IfFALSE, crowns are represented as porous envelopes usingcrown_openess. Defaults toTRUE.- extinction_coef
Numeric scalar. Leaf extinction coefficient controlling the attenuation of radiation by foliage. It represents the effective light attenuation per unit leaf area and is related to average leaf orientation. Higher values increase light interception. Defaults to
0.5.- clumping_factor
Numeric scalar controlling the aggregation of foliage within the crown volume. A value of
1corresponds to homogeneous foliage distribution, values below1indicate clumped foliage, and values above1indicate more regular spacing. This parameter affects light interception in the turbid-medium model. Defaults to1.- trunk_interception
Logical. If
TRUE, account for interception by tree trunks. Defaults toTRUE.- height_anglemin
Numeric. Minimum altitude angle of rays, in degrees. Defaults to
10.- direct_startoffset
Numeric. Starting angle of the first direct ray, in degrees. Defaults to
0.- direct_anglestep
Numeric. Angular step between direct rays, in degrees. Defaults to
5.- diffuse_anglestep
Numeric. Angular step between diffuse rays, in degrees. Defaults to
15.- soc
Logical. If
TRUE, use the Standard Overcast Sky model; ifFALSE, use the Uniform Overcast Sky model. Defaults toTRUE.- start_day
Numeric. First day of the simulated vegetative period, between 1 and 365. Defaults to
1.- end_day
Numeric. Last day of the simulated vegetative period, between 1 and 365. Must be greater than or equal to
start_day. Defaults to365.- detailed_output
Logical. If
TRUE, retain detailed ray, energy, and interception information in the output. IfFALSE, only the main light-interception metrics are retained. Defaults toFALSE.- parallel_mode
Logical. If
TRUE, ray–target computations are parallelised using OpenMP. IfFALSE, the model runs in single-thread mode. Defaults toFALSE.- n_threads
Integer or
NULL. Number of CPU threads to use whenparallel_mode = TRUE. IfNULL, OpenMP automatically selects the number of available threads. If supplied, must be a positive integer. Defaults toNULL.- verbose
Logical. If
TRUE, print informative messages during the simulation, including OpenMP status. Defaults toTRUE.
Value
An object of class "sl_output" (a list) containing:
output: A list containing the simulation results:light: Light-interception results for trees, cells, and sensors. Whendetailed_output = FALSE, these contain the main output metrics only.monthly_rays: The generated monthly ray discretization and associated radiation energies. Returned only whendetailed_output = TRUE.interceptions: Detailed tree/cell interception matrices. Returned only whendetailed_output = TRUE.
params: A list containing the simulation parameters, including the simulated period, sky model, ray discretization, crown interception model, and interception parameters.input: A list containing the originalsl_standandmonthly_radiationsobjects. Returned only wheninclude_input = TRUE.
When detailed_output = FALSE, the main output tables contain:
light$sensors:id_sensor,e,pacl, andpunobs;light$cells:id_cell,e,pacl, andpunobs;light$trees:id_tree,epot,e,lci,eunobs, andrci.
Details
For typical use, see run_sl, which provides standard values for the ray-discretization parameters.
This advanced function exposes all ray-tracing parameters used by
create_sl_rays and the interception model used by the
underlying C++ simulation. It is intended for users who need fine control
over ray discretization, sky conditions, crown representation, or
computational settings.
Before running the simulation, the function validates the stand, monthly radiation data, interception-model configuration, logical and numeric parameters, simulation period, and number of OpenMP threads.
BLAS and OpenMP thread counts are configured to avoid competing parallel
execution. When parallel_mode = TRUE, the number of OpenMP threads
can be controlled with n_threads.
For most users, run_sl is recommended because it provides standard ray-discretization parameters.