Advanced API Reference

DensePixelHits

Dense storage for per-pixel hit stacks. This avoids hashing pixel indices during projection when the plotbox is small enough that a flat table is cheaper than a Dict.

DirectionalFluxes

Per-sector PAR and NIR fluxes aligned with one TurtleGrid.

Discrete Lambertian transfer accounting for scene emitters.

sector_fraction is the cosine- and solid-angle-weighted hemispherical quadrature, normalized to one over the non-solar turtle sectors. received_fraction maps (receiver, source) to the fraction of the source's hemispherical emission intercepted by the first physical receiver. observed_fraction stores non-consuming observations by virtual sensors along the same rays. escaped_fraction_per_node stores the complementary fraction which leaves the represented scene without a physical hit. For every source, physical receiver plus escaped fractions sum to one; sensor observations do not participate in that closure.

FirstOrderResult

Outputs of the first-order interception stage: projected area, incident power, hit counts, and artificial-emitter power that escaped without a geometric hit. Escaped power is indexed by emitting source node.

InterceptionBackend

Abstract supertype for first-order interception backends.

ResolvedMeteoStep

Internal, value-resolved meteorological forcing for one simulation step.

All main-waveband irradiances are finite. Canonical date/start/end values are optional so explicit solar geometry can be used without astronomical inputs. Other optional values are nothing when they must still be derived by the sky model. sources records the selected raw column/metadata name or the derivation path used for each logical variable.

ScatteringBackend

Abstract supertype for multiple-scattering backends.

ScatteringPairCounts

Compact transfer-edge storage for scattering graphs.

The hot topology builder accumulates counts with packed integer keys, then materializes this container once so downstream code can still iterate edges as ((to, from), count) pairs without keeping tuple-key dictionaries in the graph.

ScatteringResult

Outputs of the multiple-scattering stage: added power per node, iteration count, and convergence flag.

ScatteringTransferGraph

Compact scene-scale topology used by the scattering solver to move energy between nodes.

SmallHitStack

Compact per-pixel hit stack optimized for the common short-stack case.

The first two hits are stored directly in the struct, so pixels with 0-2 hits do not allocate a separate heap vector. When a third hit arrives, the stack "spills" to a regular Vector{HitRecord} stored in spill.

This is a tradeoff:

• small inline capacity keeps each occupied pixel stack compact
• larger inline capacity would reduce spills in dense canopies, but would make every stack heavier even when it only contains one or two hits

The current inline capacity of 2 is a conservative default, not a universal optimum. Users can override the storage mode with LightOptions(pixel_hit_stack_mode=...).

TurtleGrid

Collection of TurtleSectors used to discretize incoming radiation.

TurtleSector

One directional sector of the ARCHIMED turtle, with its direction, weight, and source (:sky, :sun, or another source label).

_nir_interception_enabled_local(options)::Bool

NIR interception activation with optional explicit override (nir_interception). Default behavior remains enabled.

_nir_scattering_enabled_local(options)::Bool

NIR scattering activation with optional explicit override (nir_scattering). Default behavior remains enabled whenever scattering is enabled.

_pack_scattering_edge(to, from) -> UInt64

Pack one scattering edge (to, from) into a single 64-bit key.

We reserve 32 bits for each node id:

[to ........ 32 bits][from ...... 32 bits]

The explicit UInt32 conversion constrains each id to one half of the packed key, and the UInt64 widening makes the shift/OR operations safe. This is cheaper to hash in the topology builder than a Tuple{Int,Int} key.

_pixel_hit_stack_mode(options)

Normalize the user-facing pixel-hit stack storage selector.

Accepted values are:

• "auto": current validated optimized default
• "small": force SmallHitStack
• "vector": force the legacy Vector{HitRecord} representation

"auto" keeps SmallHitStack for the validated sparse and mid-density cases, but switches to the legacy Vector{HitRecord} storage when the plot raster is large enough that dense canopies are likely to spill SmallHitStack constantly. This favors large toric canopies like the bundled coffee example without changing the behavior for the smaller regression fixtures.

build_scattering_transfer_graph(scene, models, turtle, first, options; mode=:raycast, backend=nothing)::ScatteringTransferGraph

Build the scattering transfer graph (pair links and per-node hit normalization data) independently from iterative scattering propagation.

build_turtle(options, sky)::TurtleGrid

Build the directional sky discretization (turtle sectors), optionally adding an explicit sun sector when options.all_in_turtle == false. Diffuse turtle sectors stay fixed in scene-local coordinates; the geographic sun direction is rotated into that basis using options.scene_rotation_deg.

Set java_logged_turtle_dirs: true in the light config to use compatibility-mode sky directions (exact Java-logged vectors for 6 sectors, Float32 Java-style construction for larger sector counts).

compute_directional_fluxes(meteo_row, sky, turtle, options)::DirectionalFluxes

Java-parity directional flux integration using meteo substeps: directional fluxes are computed at each substep sun position then averaged over the full meteo step.

compute_directional_fluxes(sky, turtle, options)::DirectionalFluxes

Project sky-level PAR/NIR irradiance to each turtle sector using Java-compatible diffuse and direct distribution rules.

compute_first_order(scene, models, turtle, fluxes, options; backend=:raster_cpu)::FirstOrderResult

Compute first-order interception by rasterizing each direction, then integrating projected area, incident power, and hit counts per geometry node.

backend accepts either a symbol (currently :raster_cpu) or an InterceptionBackend instance (currently RasterCPUBackend()).

compute_scattering(scene, models, turtle, first, options; mode=:raycast, backend=nothing)::ScatteringResult
compute_scattering(graph, first, options; mode=:raycast, backend=nothing)::ScatteringResult

Compute iterative multiple scattering for PAR and NIR from first-order incident power. When a ScatteringTransferGraph is provided, transfer-link construction is skipped and only iterative propagation is run.

compute_scattering_band(graph, first, options; mode=:raycast, backend=nothing, band="PAR", initial_power_per_node=nothing, default_coeff=nothing)

Run one-band iterative scattering from a pre-built transfer graph.

compute_sky(meteo_row, options; check_boundaries=options.check_meteo_boundaries)::SkyState

Compute sun position, effective full-timestep PAR/NIR/SW irradiance, and the direct/diffuse partition for one meteo row. Meteorological aliases and optional derivations are resolved once through ResolvedMeteoStep; supplied irradiance then follows options.radiation_input_semantics.

integrate_light(scene, models, first, scat, options; meteo_row=nothing, step_duration_seconds=nothing, check_boundaries=options.check_meteo_boundaries, ...)::LightBudget

Combine first-order interception and scattering into per-node incident and absorbed light budgets.

The result stores both irradiance-style outputs (*_f, W m^-2) and energy outputs (*_q, J component^-1 timestep^-1), plus optional extra-waveband energies when they were carried through the pipeline.

read_config(path; plot_paving_override=nothing)

Read a complete simulation configuration from path and return (options, scene, meteo, models).

When plot_paving_override is provided, it overrides the paving density declared in the model extras before the ground is materialized into the scene.

run_light_series(scene, models, meteo, options; interception_backend=:raster_cpu, scattering_mode=:raycast, scattering_backend=nothing)::Vector{LightStepResult}

Run the complete light pipeline for all rows in a PlantMeteo.TimeStepTable, with optional directional response reuse when LightOptions(cache_radiation=true) is enabled. Set LightOptions(include_sky_fraction=true) to store sky_fraction in each step. When using read_config, this option is enabled by requesting sky_fraction in component_variables or opf_variables.

run_light_step(scene, models, meteo_row, options; interception_backend=:raster_cpu, scattering_mode=:raycast, scattering_backend=nothing)::LightStepResult

Run a complete light computation for one meteo row: compute_sky -> build_turtle -> compute_directional_fluxes -> compute_first_order -> compute_scattering -> integrate_light. Set LightOptions(include_sky_fraction=true) to store the per-node sky-view fraction needed by downstream MTG attachment or coupled energy-balance models. When using read_config, this option is enabled by requesting sky_fraction in component_variables or opf_variables.