Biomass

struct PrescribedBiomassModel{FT, PSAI <: PrescribedAreaIndices, RDTH <: Union{FT, ClimaCore.Fields.Field}} <: AbstractBiomassModel{FT}

A prescribed biomass model where LAI, SAI, RAI, rooting depth, and height are prescribed.

In global run with patches of bare soil, you can "turn off" the canopy model (to get zero root extraction, zero absorption and emission, zero transpiration and sensible heat flux from the canopy), by setting:

• LAI = SAI = RAI = 0.

  • plant_area_index: The plant area index model for LAI, SAI, RAI

  • rooting_depth: Rooting depth parameter (m) - a characteristic depth below which 1/e of the root mass lies

  • height: Canopy height (m) - can be scalar (uniform) or spatially-varying Field

PrescribedBiomassModel{FT}(
    domain,
    LAI::AbstractTimeVaryingInput,
    toml_dict::CP.ParamDict;
    SAI::FT = toml_dict["SAI"],
    RAI::FT = toml_dict["RAI"],
    rooting_depth = clm_rooting_depth(domain.space.surface),
    height =  clm_canopy_height(domain.space.surface)
) where {FT <: AbstractFloat}

Creates a PrescribedBiomassModel on the provided domain, using parameters from toml_dict.

The required argument LAI should be a ClimaUtilities TimeVaryingInput for leaf area index.

The following default parameters are used:

• SAI = 0 (m2/m2) - stem area index
• RAI = 1 (m2/m2) - root area index
• height = 1m

PrescribedBiomassModel{FT}(;LAI::AbstractTimeVaryingInput,
                            SAI::FT,
                            RAI::FT,
                            rooting_depth,
                            height) where {FT}

An outer constructor to help set up the PrescribedBiomassModel from LAI, SAI, and RAI directly, instead of requiring the user to make the area index object first; rooting_depth and height are also required.

Height can be either:

• A scalar FT value (uniform height across domain)
• A ClimaCore.Fields.Field (spatially-varying height)

PrescribedAreaIndices{FS <: Union{AbstractFloat, ClimaCore.Fields.Field}, F <: AbstractTimeVaryingInput}

A struct containing the area indices of the plants at a specific site; LAI varies in time, while SAI and RAI are fixed in time and can either be a scalar (spatially uniform) or a ClimaCore Field (spatially varying).

• LAI: A function of simulation time t giving the leaf area index (LAI; m2/m2)

• SAI: The constant-in-time stem area index (SAI; m2/m2), scalar or Field

• RAI: The constant-in-time root area index (RAI; m2/m2), scalar or Field

PrescribedAreaIndices(
    LAI::AbstractTimeVaryingInput,
    SAI,
    RAI,
)

An outer constructor for setting the PrescribedAreaIndices given LAI, SAI, and RAI. SAI and RAI may be scalars or ClimaCore Fields.

area_index_from_max_lai(max_LAI, tree_share, factors::AreaIndexFromMaxLAI)

Stem or root area index (m^2 m^-2) proportional to the maximum LAI max_LAI, with the area index per unit of maximum LAI weighted between that of trees and grasses (factors) by the tree share tree_share.

AreaIndexFromMaxLAI{FT}(tree, grass)
AreaIndexFromMaxLAI{FT}(toml_dict, name)

A stem or root area index proportional to the maximum LAI, with the factors tree and grass, the area index per unit of maximum LAI of trees and grasses, weighted by the tree share (area_index_from_max_lai). From toml_dict, they are the parameters "$(name)_coeff_tree" and "$(name)_coeff_grass", with name "SAI" or "RAI". As the SAI or RAI of a ZhouOptimalLAIModel, it follows the model's own seasonal maximum LAI (LAI_max) and the tree share that sets the unit cost of leaves.

 prescribed_lai_era5(era5_lai_ncdata_path,
                     era5_lai_cover_ncdata_path,
                     surface_space,
                     start_date,
                     earth_param_set;
                     time_interpolation_method = LinearInterpolation(PeriodicCalendar()),
                     regridder_type = :InterpolationsRegridder,
                     interpolation_method = Interpolations.Constant(),)

A helper function which constructs the TimeVaryingInput object for Leaf Area Index, from a file path pointing to the ERA5 LAI data in a netcdf file, a file path pointing to the ERA5 LAI cover data in a netcdf file, the surfacespace, the start date, and the earthparam_set.

This currently one works when a single file is passed for both the era5 lai and era5 lai cover data.

The ClimaLand default is to use nearest neighbor interpolation, but linear interpolation is supported by passing interpolation_method = Interpolations.Linear().

 prescribed_lai_modis(surface_space,
                      start_date
                      stop_date,
                      earth_param_set;
                      time_interpolation_method = LinearInterpolation(),
                      regridder_type = :InterpolationsRegridder,
                      interpolation_method = Interpolations.Constant(),
                      modis_lai_ncdata_path = nothing,
                      context = ClimaComms.context(surface_space))

A helper function which constructs the TimeVaryingInput object for Leaf Area Index using MODIS LAI data; requires the surfacespace, the start and stop dates, and the earthparam_set.

The ClimaLand default is to use nearest neighbor interpolation, but linear interpolation is supported by passing interpolation_method = Interpolations.Linear().

If modis_lai_ncdata_path is provided, it will be used directly. Otherwise, the path will be inferred from the start and stop dates.

 prescribed_climatological_lai_modis(surface_space,
                                     time_interpolation_method = LinearInterpolation(PeriodicCalendar(Year(1), DateTime(2000))),
                                     regridder_type = :InterpolationsRegridder,
                                     interpolation_method = Interpolations.Constant(),
                                     context = ClimaComms.context(surface_space))

A helper function which constructs the TimeVaryingInput object for Leaf Area Index using MODIS climatological LAI data; requires the surface_space.

The ClimaLand default is to use nearest neighbor interpolation, but linear interpolation is supported by passing interpolation_method = Interpolations.Linear().

update_biomass!(
    p,
    Y,
    t,
    component::PrescribedBiomassModel{FT},
    canopy,
) where {FT}

Sets the area indices pertaining to their values at time t.

Note that we clip all values of LAI below 0.05 to zero, and SAI to zero where the plant area index is below 0.05 (clip_absent_plant_area!). This is because we currently run into issues when LAI is of order eps(FT) in the SW radiation code. Please see Issue #644 or PR #645 for details. For now, this clipping is similar to what CLM and NOAH MP do.

update_biomass!(
    p,
    Y,
    t,
    component::ZhouOptimalLAIModel{FT},
    canopy,
) where {FT}

Updates the optimal-LAI cache from the prognostic state in Y: derives f0, vpd_gs and GSL from the trailing climate totals; sets the canopy composition (tree, C3 grass, C4 grass shares) from the C3/C4 competition on the trailing per-pathway potential GPP (A0c3_annual, A0c4_annual) and realized C3 GPP (GPPc3_annual), or the climate tree share; sets the seasonal maximum LAI LAI_max (set_max_leaf_area_index!); sets the leaf area index used by the rest of the canopy from the prognostic LAI and the canopy trees retain (set_leaf_area_index!), clipped below 0.05; and sets SAI and RAI (set_area_index!), zeroing SAI where plants are absent (clip_absent_plant_area!) and all area indices where a lake is present (mask_biomass!). This runs first in update_aux, before radiative transfer and photosynthesis read the area index and C3 fraction.

clip_absent_plant_area!(area_index)

Sets the stem area index in area_index to zero where the plants are absent (plants_present), after the leaf area index has been clipped below 0.05. An absent canopy then neither absorbs radiation nor stores heat, so the relaxation of its temperature to the air temperature (make_compute_imp_tendency(::BigLeafEnergyModel, canopy)) changes no energy.

mask_biomass!(p, prognostic_land_components)

Default method of setting LAI/RAI/SAI to zero where there cannot be canopy; does nothing.

Currently, this is only does something when a lake model is included in integrated models, as we cannot have vegetation over a lake, and the lake masks may not be consistent with the biomass model.

mask_biomass!(
    p,
    prognostic_land_components::Union{
        Val{(:canopy, :lake, :snow, :soil, :soilco2)},
        Val{(:canopy, :lake, :snow, :soil)},},
)

Mask out areas where there is a lake by setting LAI, RAI, and SAI to zero. Called in canopy update_aux!.

Currently treats the lake mask as 1 or 0. It is TBD how to clip LAI, SAI RAI - or if it is needed - if the lake fraction is not binary.