---
title: "Model definition"
subtitle: "Global description of the SamsaraLight ray-tracing model"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Model definition}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```


# 1 - Define the virtual stand from an input tree inventory

The user's inventory plot is represented by an axis-aligned rectangle
with a specified slope and aspect. The constructed virtual stand is then
divided into square cells of the same size for use in the ray-tracing
model.

The user's inventoried trees are located within this virtual stand, with
each tree's crown represented by a simple 3D geometric volume whose
dimensions and shape are defined by the user (see an example of crown
parametrisation in André et al. 2021). The crown can be given a
symmetrical shape, such as an ellipsoid (typically used for broadleaves)
or a paraboloid (typically used for conifers). Users can increase the
complexity of the crown representation by using asymmetric shapes and
defining the crown radii at the four cardinal points, as well as the
height at which the crown radius is at its maximum. This can be
constructed easily and automatically in the model using parts of
ellipsoids and paraboloids (*i.e.* two halves or eight eighths of an
ellipsoid, or four quarters of a paraboloid).


# 2 - Discretize the annual light and cast the light rays

The SamsaraLight ray-tracing model divides annual light into a finite
number of direct and diffuse rays based on the user's definition of
monthly radiation (*i.e.* global energy in a horizontal plane in
$MJ.m^{-2}$) and the ratio of diffuse to global energy for a given
month. It then calculates the angles, orientation and energy of these
rays depending on whether they are direct or diffuse*.* The annual
direct rays are discretised by following the sun's trajectory across the
year, and the annual diffuse rays are created by generating rays from
all directions across the sky. The rays characteristics also depends on
the plot's latitude: there are relatively more diffuse radiations, with
more horizontal rays, towards higher latitudes in Scandinavia than
towards lower latitudes in Spain.

The model then cast each ray towards the centre of each cell that
composed the virtual stand. The energy of each ray, measured in
megajoules ($MJ$), depends on the initial energy of the ray (in
$MJ.m^{-2}$) and the area of the cell. This enabled the continuous plane
to be considered as a discrete surface, allowing the light reaching the
ground to be modeled. Therefore, cell size is a proxy for model
accuracy: smaller cells lead to a more precise and continuous estimation
of light on the ground, but this comes at the expense of quadratic
increases in computation time and memory usage.

# 3 - Determine interceptions between light rays and tree crowns

For each light ray directed towards a cell centre, the model estimates
all the interceptions with the tree crowns. To do this, it estimates the
solutions of a solvable system of equations based on the intersection
between a simple volume (the crown) and a straight line (the ray). This
leads to a polynomial solution with either 0 (no intersection), 1 (the
ray is tangent to the crown and is therefore not considered) or 2
solutions (an intersection with entry and exit points). The model then
stores all interceptions for each ray towards each cell centre and
defines them by the path length in the crown (the distance between the
entry and exit points) and the distance from the cell centre (the
distance between the middle point of the path into the crown and the
cell centre point).

Given that we do not know the environment around the stand, the model
uses a torus system to represent plot boundaries (see the graphical
representation in Courbaud et al., 2003). Trees around the border of the
stand are not described, but they also participate in intercepting
incoming rays. Therefore, failing to consider them could result in an
underestimation of the number of interceptions, particularly for cells
in close proximity to the plot boundaries. Overall, the torus system
allows an infinite representation of the virtual stand to be created by
joining the left and right rectangular sides together, as well as the
top and bottom sides. In practice, this means that the trees outside the
left boundary are considered to be the trees on the right side of the
stand (and vice versa), and the trees outside the top boundary are
considered to be the trees on the bottom side of the stand (and vice
versa).

An algorithm has been implemented to reduce computation time by
estimating which trees could potentially be intercepted by each ray.
Given the height angle of a ray and the maximum height of the trees in
the stand, there is a maximum radius around the casting point beyond
which it would be impossible to intercept any tree crown. By estimating
this radius for each ray, the computation time for determining crown
interceptions is drastically reduced, as it is only necessary to iterate
over trees that could potentially intercept the ray when casting it
towards a given cell center.

# 4 - Estimate the attenuation of light throughout successive interceptions

The distance from the cell centre allows the interception of a given ray
by the crowns to be ordered from the farthest (i.e. the first crown to
intercept the ray) to the closest (i.e. the last crown to intercept the
ray). Doing so allows us to estimate the attenuation of each ray's
energy following successive interceptions by the tree crowns, starting
with the initial energy of the ray coming from above the canopy in $MJ$.
The transmitted energy for each intercepted crown is estimated based on
the incident energy of the ray (*i.e.* equal to the initial energy for
the first intercepted crown, or equal to the attenuated initial energy
for subsequent interceptions).

The user can choose between two transmission models that vary in how the
crown is considered: (1) as a porous envelope or (2) as a turbid medium.
In the porous envelope model, the transmitted energy is computed based
only on a crown parameter: crown openness. This is a parameter between 0
and 1 that indicates the fraction of light energy transmitted. For
example, a value of 0.7 indicates that 70% of the energy is transmitted
and 30% is absorbed by the tree. Therefore, the first model is
independent of the length of the ray path within the crown. The second,
more complex model considers the crown to be a turbid medium and assumes
that the leaves are arranged homogeneously within the canopy and not
aggregated. In this case, Beer–Lambert's law can be applied to estimate
the transmitted energy based on the ray's path length within the crown
and a crown parameter: LAD (the Leaf Area Density) (see Ligot et al.,
2014, for more details on the transmission models).

# 5 - Compute the output light variables

After estimating the transmitted energies for all rays directed towards
each cell centre, the model sums up energies to deduce the total amount
of energy absorbed by the tree during the year (in $MJ$). The model also
estimates the total amount of energy reaching a cell centre after
attenuation by the above-mentioned crowns of each ray directed towards
this cell. This is standardised by cell area to give the amount of
energy reaching the ground per unit area (in $MJ.m^{-2}$). The
SamsaRaLight package also return more detailed output if the user
specified it: the direct/diffuse energies, the matrices of interceptions
(i.e. the number of intercepted rays and energies for each tree per
target cell).

For each cell, the package also derives a common relative indicator to
represent light on the ground, $PACL$ (percentage of above canopy
light), which is the ratio of the energy reaching the cell to the energy
above the canopy before interception. This allows shade to be considered
not as an absolute amount of energy, which is highly dependent on site
location (*i.e.* greater global energy in lower latitudes), but as a
relative indicator dependent only on light interception by trees. In
practice, the indicator ranges from 0 (full shade) to 1 (full
light).This indicator is considered a better proxy for modelling the
effect of light on tree regeneration (see model calibration in Unkule et
al., manuscript in preparation) and for representing the impact of
silviculture on ground-level light (see Ligot et al., 2014b).

For each tree, the package also derives a light competition index
($LCI$), representing the level of light competition around a focal
tree. This index is based on the ratio between the actual energy
intercepted by the tree and the potential energy that would have been
intercepted if the tree were alone in the stand (*i.e.* not considering
interception by surrounding competitors). When considering light as a
resource, $LCI$ can be interpreted as the amount of light absorbed by
the tree (the supply) compared to what it would have needed based on its
crown characteristics (the demand). In practice, the indicator ranges
from 0 (full light) to 1 (full shade). This indicator is considered a
reliable proxy for estimating the effect of light competition on the
growth and survival of individual trees (see model calibration in
Beauchamp et al., 2025).