Canopy

 CanopyModel{FT, AR, RM, PM, SM, SMSM, PHM, EM, SIFM, B, PS, D} <: ClimaLand.AbstractImExModel{FT}

The model struct for the canopy, which contains

• the canopy model domain (a point for site-level simulations, or

an extended surface (plane/spherical surface) for regional or global simulations.

• subcomponent model type for radiative transfer. This is of type

AbstractRadiationModel.

• subcomponent model type for photosynthesis. This is of type

AbstractPhotosynthesisModel and supports FarquharModel, and PModel.

• subcomponent model type for stomatal conductance. This is of type

AbstractStomatalConductanceModel and supports MedlynConductanceModel and PModelConductance. Note if PModel is used for photosynthesis, then you must also use PModelConductance for stomatal conductance, since these two models are derived from the same set of conditions.

• subcomponent model type for soil moisture stress. This is of type

AbstractSoilMoistureStressModel. Currently we support TuzetMoistureStressModel (default) PiecewiseMoistureStressModel, and NoMoistureStressModel (stress factor = 1).

• subcomponent model type for plant hydraulics. This is of type

AbstractPlantHydraulicsModel and currently only a version which prognostically solves Richards equation in the plant is available.

• subcomponent model type for canopy energy. This is of type

AbstractCanopyEnergyModel and currently we support a version where the canopy temperature is prescribed, and one where it is solved for prognostically.

• subcomponent model type for canopy SIF. prognostically.
• canopy model parameters, which include parameters that are shared

between canopy model components or those needed to compute boundary fluxes.

• The boundary conditions, which contain:
  • The atmospheric conditions, which are either prescribed (of type PrescribedAtmosphere) or computed via a coupled simulation (of type CoupledAtmosphere).
  • The radiative flux conditions, which are either prescribed (of type PrescribedRadiativeFluxes) or computed via a coupled simulation (of type CoupledRadiativeFluxes).
  • The ground conditions, which are either prescribed or prognostic

Note that the canopy height is specified as part of the PlantHydraulicsModel, along with the area indices of the leaves, roots, and stems. Eventually, when plant biomass becomes a prognostic variable (by integrating with a carbon model), some parameters specified here will be treated differently.

• autotrophic_respiration: Autotrophic respiration model, a canopy component model

• radiative_transfer: Radiative transfer model, a canopy component model

• photosynthesis: Photosynthesis model, a canopy component model

• conductance: Stomatal conductance model, a canopy component model

• soil_moisture_stress: Soil moisture stress parameterization, a canopy component model

• hydraulics: Plant hydraulics model, a canopy component model

• energy: Energy balance model, a canopy component model

• sif: SIF model, a canopy component model

• biomass: Biomass parameterization, a canopy component model

• boundary_conditions: Boundary Conditions

• earth_param_set: Shared parameters between component models

• domain: Canopy model domain

CanopyModel{FT}(;
    autotrophic_respiration::AbstractAutotrophicRespirationModel{FT},
    radiative_transfer::AbstractRadiationModel{FT},
    photosynthesis::AbstractPhotosynthesisModel{FT},
    conductance::AbstractStomatalConductanceModel{FT},
    soil_moisture_stress::AbstractSoilMoistureStressModel{FT},
    hydraulics::AbstractPlantHydraulicsModel{FT},
    energy::AbstractCanopyEnergyModel{FT},
    sif::AbstractSIFModel{FT},
    biomass::AbstractBiomassModel{FT},
    boundary_conditions::B,
    earth_param_set::PSE,
    domain::Union{
        ClimaLand.Domains.Point,
        ClimaLand.Domains.Plane,
        ClimaLand.Domains.SphericalSurface,
    },
    energy = PrescribedCanopyTempModel{FT}(),
) where {FT, PSE}

An outer constructor for the CanopyModel, which makes certain consistency checks between parameterizations.

function CanopyModel{FT}(
    domain::Union{
        ClimaLand.Domains.Point,
        ClimaLand.Domains.Plane,
        ClimaLand.Domains.SphericalSurface,
    },
    forcing::NamedTuple,
    LAI::AbstractTimeVaryingInput,
    toml_dict::CP.ParamDict;
    prognostic_land_components = (:canopy,),
    autotrophic_respiration = AutotrophicRespirationModel{FT}(toml_dict),
    radiative_transfer = TwoStreamModel{FT}(domain, toml_dict),
    photosynthesis = PModel{FT}(domain, toml_dict),
    conductance = PModelConductance{FT}(toml_dict),
    soil_moisture_stress = TuzetMoistureStressModel{FT}(toml_dict),
    hydraulics = PlantHydraulicsModel{FT}(domain, toml_dict),
    energy = BigLeafEnergyModel{FT}(toml_dict),
    biomass= PrescribedBiomassModel{FT}(domain, LAI, toml_dict),
    sif = Lee2015SIFModel{FT}(toml_dict),
    turbulent_flux_parameterization = MoninObukhovCanopyFluxes(toml_dict, biomass.height),
) where {FT, PSE}

Creates a CanopyModel with the provided domain, forcing, and toml_dict.

Defaults are provided for each canopy component model, which can be overridden by passing in a different instance of that type of model. Default parameters are also provided for each canopy component, and can be changed with keyword arguments. Please see the documentation of each component model for details on the default parameters.

The required argument forcing should be a NamedTuple with the following field:

• atmos: a PrescribedAtmosphere or CoupledAtmosphere object
• radiation: a PrescribedRadiativeFluxes or CoupledRadiativeFluxes object
• ground: a PrescribedGroundConditions or PrognosticGroundConditions object

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

When running the canopy model in standalone mode, set prognostic_land_components = (:canopy,), while for running integrated land models, this should be a list of the individual models. This value of this argument must be the same across all components in the land model.

AbstractCanopyComponent{FT <: AbstractFloat}

An abstract type for canopy component parameterizations.

Canopy component parameterizations do not run in standalone mode, but only as part of a CanopyModel. As such, they do not require all of the functionality of AbstractModels, and they are not AbstractModels themselves. The CanopyModel is an AbstractModel.

However, some of the same functionality is nice to have for canopy components, especially when defining the variables, which is why we introduce the AbstractCanopyComponent type and extend many of the methods for ClimaLand.AbstractModels for the canopy component parameterizations.

clm_canopy_height(
    surface_space;
    regridder_type = :InterpolationsRegridder,
    extrapolation_bc = (
        Interpolations.Periodic(),
        Interpolations.Flat(),
        Interpolations.Flat(),
    ),
    interpolation_method = Interpolations.Constant(),
    lowres = false,
    max_height = nothing
)

Read spatially-varying canopy height (m) data from CLM vegetation properties onto the surface_space.

If maxheight is set, the heights are clipped to be <= maxheight. ```

AbstractCanopyBC <: ClimaLand.AbstractBC

An abstract type for boundary conditions for the canopy model.

AtmosDrivenCanopyBC{
    A <: AbstractAtmosphericDrivers,
    B <: AbstractRadiativeDrivers,
    G <: AbstractGroundConditions,
    R <: AbstractCanopyFluxParameterization,
    C::Tuple
} <: AbstractCanopyBC

A struct used to specify the canopy fluxes, referred to as "boundary conditions", at the surface and bottom of the canopy, for water and energy.

These fluxes include turbulent surface fluxes computed with Monin-Obukhov theory, radiative fluxes, and root extraction.

• atmos: The atmospheric conditions driving the model

• radiation: The radiative fluxes driving the model

• ground: Ground conditions

• turbulent_flux_parameterization: Turbulent flux (latent, sensible, vapor, and momentum) parameterization

• prognostic_land_components: Prognostic land components present

canopy_boundary_fluxes!(p::NamedTuple,
                        canopy::CanopyModel,
                        Y::ClimaCore.Fields.FieldVector,
                        t,
                        )

Computes the boundary fluxes for the canopy prognostic equations; updates the specific fields in the auxiliary state p which hold these variables. This function is called within the explicit tendency of the canopy model.

• p.canopy.turbulent_fluxes: Canopy SHF, LHF, transpiration, their derivatives with respect to T, the canopy temperature and effective surface humidity of the flux solve, and its similarity scales
• p.canopy.hydraulics.fa[end]: Transpiration
• p.canopy.hydraulics.fa_roots: Root water flux
• p.canopy.radiative_transfer.LW_n: net long wave radiation
• p.canopy.radiative_transfer.SW_n: net short wave radiation

canopy_turbulent_fluxes!(p, canopy::CanopyModel, Y, t)

Compute the canopy turbulent fluxes p.canopy.turbulent_fluxes (sensible and latent heat, transpiration, their temperature derivatives, and the canopy-air state and similarity scales of the solve) with ClimaLand.turbulent_fluxes!, and zero them where plants are absent (zero_canopy_fluxes_without_plants!); return nothing.

Called from canopy_boundary_fluxes! and, before the ground skin solves that read the canopy-air state, from the integrated models.

canopy_root_fluxes!(p, canopy::CanopyModel, Y, t)

Update the root fluxes of water p.canopy.hydraulics.fa_roots and of energy p.canopy.energy.fa_energy_roots per unit ground area in place; return nothing. Called from canopy_boundary_fluxes! and from the integrated models.

zero_canopy_fluxes_without_plants!(turbulent_fluxes, p)

Set the canopy sensible heat flux and its temperature derivative to zero where plants are absent (plants_present), and the latent heat flux, transpiration, and the latent heat flux derivative to zero where leaves are absent (leaves_present) or the transpiration is not positive (the canopy does not condense water); modify turbulent_fluxes in place and return nothing. The area indices are read from p.canopy.biomass.area_index.

Below these area indices the Monin-Obukhov solve exchanges heat with a canopy of negligible conductance, and the fluxes it returns are roundoff.

Called from canopy_boundary_fluxes! and from the implicit boundary flux update of the canopy energy model, so that the explicit and implicit fluxes agree.

plants_present(LAI, SAI)

Whether the plant area index LAI + SAI reaches the threshold MIN_CANOPY_AREA_INDEX (0.05) below which the canopy exchanges no heat with the air and the ground below it is forced as a standalone surface. Called from zero_canopy_fluxes_without_plants!, subcanopy_forcing, and the screen-level diagnostics.

leaves_present(LAI)

Whether the leaf area index LAI reaches the threshold MIN_CANOPY_AREA_INDEX (0.05) below which the canopy transpires no water. Stems exchange heat but do not transpire, so this test uses the leaf area index alone. Called from zero_canopy_fluxes_without_plants!.

MoninObukhovCanopyFluxes{FT, F <: Union{FT, ClimaCore.Fields.Field}} <: AbstractCanopyFluxParameterization{FT}

A parameterization specifying how to compute latent and sensible heat fluxes between the atmosphere and the canopy based on Monin-Obukhov Surface Theory.

You must specify

• a minimum roughness length (global constant)
• the roughness length for momentum (can be a constant or a field)
• the roughness length for scalars (can be a constant or a field)
• the displacement height (can be a constant or a field)
• the leaf-level drag coefficient (unitless)
• the extinction coefficient of the wind speed within the canopy (unitless)
• the minimum height above the ground at which the fluxes of the ground below the canopy are evaluated (m)

subcanopy_wind(u, gustiness, h_atmos, z, height, displ, z_0m, PAI, extinction)

Return the wind speed [m/s] driving the turbulent exchange of the ground below a canopy of height height, displacement height displ, momentum roughness length z_0m, and plant area index PAI (leaf plus stem area index, unitless), evaluated with reference height z below the forcing height h_atmos, given the wind u and gustiness gustiness at h_atmos:

U = max(u, gustiness)
    * log((max(z, height) - displ) / z_0m) / log((h_atmos - displ) / z_0m)
    * exp(-extinction * PAI).

Above the canopy the wind follows the neutral logarithmic profile of the canopy down to max(z, height); across the canopy it is attenuated exponentially by the full plant area index PAI between the canopy top and the ground (Inoue, 1963; Cionco, 1965; Brutsaert, 1982; Shuttleworth and Wallace, 1985; Choudhury and Monteith, 1988), with the extinction coefficient extinction per unit plant area index. Attenuation by the full PAI lets dense short canopies (height < z, where z is floored at subcanopy_min_reference_height) shelter the ground beneath them. The gustiness is folded into the wind at h_atmos so that it acts as a floor on the wind speed above the canopy, as in the Monin-Obukhov solve of SurfaceFluxes.jl (SurfaceFluxes.windspeed); the ground-level solve is therefore given the gustiness model without its floor (see ground_gustiness).

When u is a two-component SVector, the attenuated wind keeps the direction of u; a zero vector is mapped onto the first component.

Called from subcanopy_forcing.

subcanopy_reference_height(h_sfc, displ, z_0m, z_min, h_atmos)

Return the height [m] at which the ground below a canopy exchanges heat and water vapor with the air: the apparent sink height displ + z_0m of the canopy, which is where the wind profile above the canopy places the canopy air, but at least z_min above the ground surface at height h_sfc and no higher than the forcing height h_atmos. The floor matters for canopies shorter than about z_min.

The temperature and humidity at this height are taken to be the canopy-air values (p.canopy.turbulent_fluxes.T_sfc and q_sfc) from the canopy Monin-Obukhov solve, and the wind is attenuated across the full plant area index of the canopy (see subcanopy_wind and subcanopy_forcing).

subcanopy_forcing(canopy::CanopyModel, p, h_sfc)

Return the NamedTuple (; h_atmos, u_atmos, T_atmos, q_atmos, gustiness) of lazy broadcasts of the reference height [m], the wind [m/s], the air temperature [K], the specific humidity [kg/kg], and the gustiness model for the turbulent fluxes of a ground surface (soil or snow) at height h_sfc below the canopy, from the atmospheric forcing in p.drivers, the canopy height and plant area index in canopy.biomass and p.canopy.biomass.area_index, the canopy-air state in p.canopy.turbulent_fluxes, and the canopy turbulent flux parameterization; see subcanopy_reference_height, subcanopy_wind, and ground_gustiness.

Where plants are present (plants_present), the reference height is the sub-canopy height, the wind the attenuated wind there, and the gustiness the model of the forcing without its floor, which is folded into that wind; T_atmos and q_atmos are the canopy-air temperature p.canopy.turbulent_fluxes.T_sfc and specific humidity p.canopy.turbulent_fluxes.q_sfc at the scalar roughness height d + z_0b from the canopy Monin-Obukhov solve, which the integrated models run first, so that the ground exchanges heat and water vapor with the canopy air space rather than directly with the atmosphere above the canopy (Shuttleworth and Wallace, 1985). Where plants are absent, the ground is forced as a standalone surface: the forcing height, wind, temperature, humidity, and gustiness model of p.drivers and the atmospheric driver.

The coupling is one-way: the canopy solve that sets the canopy-air state includes the exchange of the canopy itself only, and the ground fluxes pass to the atmosphere without a budget of the canopy air space. The air pressure of the forcing, p.drivers.P, serves at the sub-canopy height too; the hydrostatic difference across a canopy is below 0.1 %.

ground_gustiness(gustiness, plants)

Return the gustiness model of the ground below a canopy as a lazy field over the Boolean field plants (plants_present): where plants are present, the model of the atmospheric forcing gustiness with its minimum wind speed set to zero, since that floor is folded into the sub-canopy wind (subcanopy_wind), so that only its convective part remains; where they are absent, the model of the forcing itself, so that bare ground is forced as a standalone surface (see SurfaceFluxes.without_floor). Models without a floor are returned as they are.