Radiative Transfer

TwoStreamModel{FT}(
    domain;
    radiation_parameters = clm_canopy_radiation_parameters(domain.space.surface),
    ϵ_canopy = LP.get_default_parameter(FT, :canopy_emissivity),
    n_layers::Int = 20,
)

Creates a Two Stream model for canopy radiative transfer on the provided domain.

Spatially-varying parameters are read in from data files in clm_canopy_radiation_parameters.` In particular, this function returns a NamedTuple containing:

• Ω: clumping index
• G_Function: a G function for leaf angle distribution
• α_PAR_leaf, τ_PAR_leaf: albedo and transmissivity in the PAR band
• α_NIR_leaf, τ_NIR_leaf: albedo and transmissivity in the NIR band

Canopy emissivity and wavelength per PAR photon are currently treated as constants; these can be passed in as Floats by kwarg. Otherwise the default values from ClimaParams.jl are used.

The number of layers in the canopy is set by n_layers, which defaults to 20.

TwoStreamModel{FT}(
    domain;
    radiation_parameters = clm_canopy_radiation_parameters(domain.space.surface),
    ϵ_canopy = LP.get_default_parameter(FT, :canopy_emissivity),
    n_layers::Int = 20,
)

Creates a Two Stream model for canopy radiative transfer on the provided domain.

Spatially-varying parameters are read in from data files in clm_canopy_radiation_parameters.` In particular, this function returns a NamedTuple containing:

• Ω: clumping index
• G_Function: a G function for leaf angle distribution
• α_PAR_leaf, τ_PAR_leaf: albedo and transmissivity in the PAR band
• α_NIR_leaf, τ_NIR_leaf: albedo and transmissivity in the NIR band

Canopy emissivity and wavelength per PAR photon are currently treated as constants; these can be passed in as Floats by kwarg. Otherwise the default values from ClimaParams.jl are used.

The number of layers in the canopy is set by n_layers, which defaults to 20.

TwoStreamParameters{FT <: AbstractFloat}

The required parameters for the two-stream radiative transfer model.

• α_PAR_leaf: PAR leaf reflectance (unitless)

• τ_PAR_leaf: PAR leaf element transmittance

• α_NIR_leaf: NIR leaf reflectance

• τ_NIR_leaf: NIR leaf element transmittance

• ϵ_canopy: Emissivity of the canopy

• Ω: Clumping index following Braghiere 2021 (unitless)

• λ_γ_PAR: Typical wavelength per PAR photon (m)

• n_layers: Number of layers to partition the canopy into when integrating the absorption over the canopy vertically. Unrelated to the number of layers in the vertical discretization of the canopy for the plant hydraulics model. (Constant, and should eventually move to ClimaParams)

• G_Function: Leaf angle distribution function

BeerLambertModel{FT}(
    domain;
    radiation_parameters = clm_canopy_radiation_parameters(domain.space.surface),
    ϵ_canopy::FT = LP.get_default_parameter(FT, :canopy_emissivity),
) where {FT <: AbstractFloat}

Creates a Beer-Lambert model for canopy radiative transfer on the provided domain.

Spatially-varying parameters are read in from data files in clm_canopy_radiation_parameters.` In particular, this function returns a field for

• clumping index Ω
• leaf angle distribution G_Function
• albedo and transmissitivy in PAR and NIR bands (α_PAR_leaf, τ_PAR_leaf, α_NIR_leaf, τ_NIR_leaf)

Canopy emissivity and wavelength per PAR photon are currently treated as constants; these can be passed in as Floats by kwarg. Otherwise the default values from ClimaParams.jl are used.

BeerLambertModel{FT}(
    domain;
    radiation_parameters = clm_canopy_radiation_parameters(domain.space.surface),
    ϵ_canopy::FT = LP.get_default_parameter(FT, :canopy_emissivity),
) where {FT <: AbstractFloat}

Creates a Beer-Lambert model for canopy radiative transfer on the provided domain.

Spatially-varying parameters are read in from data files in clm_canopy_radiation_parameters.` In particular, this function returns a field for

• clumping index Ω
• leaf angle distribution G_Function
• albedo and transmissitivy in PAR and NIR bands (α_PAR_leaf, τ_PAR_leaf, α_NIR_leaf, τ_NIR_leaf)

Canopy emissivity and wavelength per PAR photon are currently treated as constants; these can be passed in as Floats by kwarg. Otherwise the default values from ClimaParams.jl are used.

BeerLambertParameters{
    FT <: AbstractFloat,
    G <: Union{AbstractGFunction, ClimaCore.Fields.Field},
    F <: Union{FT, ClimaCore.Fields.Field},
}

The required parameters for the Beer-Lambert radiative transfer model.

• α_PAR_leaf: PAR leaf reflectance (unitless)

• α_NIR_leaf: NIR leaf reflectance

• ϵ_canopy: Emissivity of the canopy

• Ω: Clumping index following Braghiere (2021) (unitless)

• λ_γ_PAR: Typical wavelength per PAR photon (m)

• G_Function: Leaf angle distribution function

function BeerLambertParameters(::Type{FT};
    ld = (_) -> 0.5,
    α_PAR_leaf = 0.1,
    α_NIR_leaf = 0.4,
    Ω = 1,
    kwargs...
)
function BeerLambertParameters(toml_dict;
    ld = (_) -> 0.5,
    α_PAR_leaf = 0.1,
    α_NIR_leaf = 0.4,
    Ω = 1,
    kwargs...
)

Floating-point and toml dict based constructor supplying default values for the BeerLambertParameters struct. Additional parameter values can be directly set via kwargs.

function TwoStreamParameters(FT::AbstractFloat;
    ld = (_) -> 0.5,
    α_PAR_leaf = 0.3,
    τ_PAR_leaf = 0.2,
    α_NIR_leaf = 0.4,
    τ_NIR_leaf = 0.25,
    Ω = 1,
    n_layers = UInt64(20),
    kwargs...
)
function TwoStreamParameters(toml_dict;
    ld = (_) -> 0.5,
    α_PAR_leaf = 0.3,
    τ_PAR_leaf = 0.2,
    α_NIR_leaf = 0.4,
    τ_NIR_leaf = 0.25,
    Ω = 1,
    n_layers = UInt64(20),
    kwargs...
)

Floating-point and toml dict based constructor supplying default values for the TwoStreamParameters struct. Additional parameter values can be directly set via kwargs.

ConstantGFunction

A type for a constant G function, which is used to represent the leaf angle distribution function in the radiative transfer models.

CLMGFunction

A type for a G function that is parameterized by the cosine of the solar zenith angle, following the CLM approach to parameterizing the leaf angle distribution function.

Canopy.canopy_radiant_energy_fluxes!(p::NamedTuple,
                                     s::Union{PrognosticGroundConditions,PrognosticSoilConditions},
                                     canopy,
                                     radiation::PrescribedRadiativeFluxes,
                                     earth_param_set::PSE,
                                     Y::ClimaCore.Fields.FieldVector,
                                     t,
                                    ) where {PSE}

In standalone mode, this function computes and stores the net long and short wave radition, in W/m^2, absorbed by the canopy.

In integrated mode, we have already computed those quantities in lsm_radiant_energy_fluxes!, so this method does nothing additional.

LW and SW net radiation are stored in p.canopy.radiative_transfer.LW_n and p.canopy.radiative_transfer.SW_n.

canopy_radiant_energy_fluxes!(p::NamedTuple,
                              ground::PrescribedGroundConditions
                              canopy,
                              radiation::PrescribedRadiativeFluxes,
                              earth_param_set::PSE,
                              Y::ClimaCore.Fields.FieldVector,
                              t,
                             ) where {PSE}

Computes and stores the net long and short wave radiation, in W/m^2, over all bands, absorbed by the canopy when the canopy is run in standalone mode, with only a :canopy model as a prognostic component, with PrescribedGroundConditions.

LW and SW net radiation are stored in p.canopy.radiative_transfer.LW_n and p.canopy.radiative_transfer.SW_n.

Canopy.ground_albedo_PAR(
    prognostic_land_components::Val{(:canopy, :soil, :soilco2)},
    ground::PrognosticSoilConditions,
    Y,
    p,
    t,
)

A method of Canopy.Canopy.groundalbedoPAR for a prognostic soil.

Canopy.ground_albedo_PAR(
    prognostic_land_components::Val{(:canopy, :snow, :soil, :soilco2)},
    ground::PrognosticGroundConditions,
    Y,
    p,
    t,
)

A method of Canopy.groundalbedoPAR for a prognostic soil/snow. This function is called in the Canopy update_aux! function.

ground_albedo_PAR(prognostic_land_components::Val{(:canopy,)}, ground::PrescribedGroundConditions, _...)

Returns the ground albedo in the PAR for a PrescribedGroundConditions driver. In this case, the prognosticlandcomponents only contain :canopy, because the canopy is being run in standalone mode.

Canopy.ground_albedo_NIR(
    prognostic_land_components::Val{(:canopy, :soil, :soilco2)},
    ground::PrognosticSoilConditions,
    Y,
    p,
    t,
)

A method of Canopy.groundalbedoNIR for a prognostic soil.

Canopy.ground_albedo_NIR(
    prognostic_land_components::Val{(:canopy, :snow, :soil, :soilco2)},
    ground::PrognosticGroundConditions,
    Y,
    p,
    t,
)

A method of Canopy.groundalbedoNIR for a prognostic soil/snow. This function is called in the Canopy update_aux! function.

ground_albedo_NIR(prognostic_land_components::Val{(:canopy,)}, ground::PrescribedGroundConditions, _...)

Returns the ground albedo in the NIR for a PrescribedGroundConditions driver. In this case, the prognosticlandcomponents only contain :canopy, because the canopy is being run in standalone mode.

compute_fractional_absorbances!(
    p,
    RT::BeerLambertModel{FT},
    LAI,
    α_soil_PAR,
    α_soil_NIR,
)

Computes the PAR and NIR fractional absorbances, reflectances, and tranmittances for a canopy in the case of the Beer-Lambert model. The absorbances are a function of the radiative transfer model, as well as the leaf area index, the clumping index, the cosine of the zenith angle, the leaf angle distribution, the extinction coefficient, and the soil albedo in the PAR and NIR bands. Returns a NamedTuple of NamedTuple, of the form: (; par = (; refl = , trans = , abs = ), nir = (; refl = , trans = , abs = ))

compute_fractional_absorbances!(p,
    RT::TwoStreamModel{FT},
    LAI,
    α_soil_PAR,
    α_soil_NIR,
)

Computes the PAR and NIR fractional absorbances, reflectances, and tranmittances for a canopy in the case of the Two-stream model. The absorbances are a function of the radiative transfer model, as well as the leaf area index, the clumping index, the cosine of the zenith angle, the leaf angle distribution, the extinction coefficient, and the soil albedo in the PAR and NIR bands.

This model also depends on the diffuse fraction. Returns a NamedTuple of NamedTuple, of the form: (; par = (; refl = , trans = , abs = ), nir = (; refl = , trans = , abs = ))

canopy_sw_rt_beer_lambert(
    G_Function,
    cosθs::FT,
    Ω::FT,
    α_leaf::FT,
    LAI::FT,
    α_soil::FT,
)

Computes the absorbed, reflected, and transmitted flux fractions by radiation band.

This applies the Beer-Lambert law, which is a function of leaf reflectance (α_leaf), the leaf angle distribution and zenith angle (defined via G_Function, and cosθs), leaf area index (LAI), and the albedo of the soil (α_soil).

Returns a tuple of reflected, absorbed, and transmitted radiation fractions.

canopy_sw_rt_two_stream(
    G_Function,
    Ω::FT,
    n_layers::UInt64,
    SW_d::FT,
    α_leaf::FT,
    τ_leaf::FT,
    LAI::FT,
    cosθs::FT,
    α_soil::FT,
    frac_diff::FT,
)

Computes the absorbed, reflected, and transmitted flux fractions by radiation band.

This applies the two-stream radiative transfer solution which takes into account the impacts of scattering within the canopy. The function takes in all parameters from the parameter struct of a TwoStreamModel, along with the incident radiation, LAI, extinction coefficient K, soil albedo from the canopy soil_driver, the cosine of the solar zenith angle, and τ.

Returns a tuple of reflected, absorbed, and transmitted radiation fractions.

extinction_coeff(G_Function,
                 cosθs::FT) where {FT}

Computes the vegetation extinction coefficient (K), as a function of the cosine of the sun zenith angle (cosθs), and the leaf angle distribution function(G_Function).

In the two-stream scheme, values of K ~ 1/epsilon can lead to numerical issues. Here we clip it to 1e6.

compute_G(
    G::ConstantGFunction,
    _,
)

Returns the constant leaf angle distribution value for the given G function. Takes in an arbitrary value for the cosine of the solar zenith angle, which is not used.

compute_G(
    G::CLMGFunction,
    cosθs,
)

Returns the leaf angle distribution value for CLM G function as a function of the cosine of the solar zenith angle and the leaf orientation index. See section 3.1 of https://www2.cesm.ucar.edu/models/cesm2/land/CLM50TechNote.pdf.

Note that the zenith angle is defined ∈ [0,2π), so to prevent a negative value of G when the sun is below the horizon, we clip cosθs >= 0.