AbstractEnergyHydrologyBC <: ClimaLand.AbstractBC

An abstract type for boundary conditions for the combined energy and hydrology equations.

In general these can consist of independent boundary conditions for water (<: AbstractWaterBC) and for heat (<: AbstractHeatBC) independently, , or a boundary condition type which sets both using the same parameterizations.

AbstractHeatBC <: ClimaLand.AbstractBC

An abstract type for boundary conditions for the soil heat equation.

AbstractSoilHydrologyClosure{FT <: AbstractFloat}

The abstract type of soil hydrology closure, of which vanGenuchten{FT} and BrooksCorey{FT} are the two supported concrete types.

To add a new parameterization, methods are required for:

• matric_potential,
• inversematricpotential,
• pressure_head,
• dψdϑ,
• hydraulic_conductivity.

AbstractSoilModel{FT} <: ClimaLand.AbstractImExModel{FT}

The abstract type for all soil models.

Currently, we only have plans to support a RichardsModel, simulating the flow of liquid water through soil via the Richardson-Richards equation, and a fully integrated soil heat and water model, with phase change.

AbstractSoilSource{FT} <:  ClimaLand.AbstractSource{FT}

An abstract type for types of source terms for the soil equations.

In standalone mode, the only supported source type is freezing and thawing. ClimaLand.jl creates additional sources to include as necessary e.g. root extraction (not available in stand alone mode).

AbstractWaterBC <: ClimaLand.AbstractBC

An abstract type for boundary conditions for Richards equation.

AtmosDrivenFluxBC{
    A <: AbstractAtmosphericDrivers,
    B <: AbstractRadiativeDrivers,
    R <: AbstractRunoffModel
} <: AbstractEnergyHydrologyBC

A concrete type of soil boundary condition for use at the top of the domain. This holds the conditions for the atmosphere AbstractAtmosphericDrivers, for the radiation state AbstractRadiativeDrivers. This is only supported for the EnergyHydrology model.

This choice indicates the Monin-Obukhov Surface Theory will be used to compute the sensible and latent heat fluxes, as well as evaporation, and that the net radiation and precipitation will also be computed. The net energy and water fluxes are used as boundary conditions.

A runoff model is used to simulate surface and subsurface runoff and this is accounted for when setting boundary conditions. The default is to have no runoff accounted for.

• atmos: The atmospheric conditions driving the model

• radiation: The radiative fluxes driving the model

• runoff: The runoff model. The default is no runoff.

BrooksCorey{FT} <: AbstractSoilHydrologyClosure{FT}

The Brooks and Corey soil hydrology closure, chosen when the hydraulic conductivity and matric potential are modeled using the Brooks and Corey parameterization (Brooks and Corey, 1964, 1966; see also Table 8.2 of G. Bonan 2019).

• c: The pore-size distribution index (unitless)

• ψb: The air entry matric potential, when S=1 (m)

• S_c: A derived parameter: the critical saturation at which capillary flow no longer replenishes the surface

EnergyHydrology <: AbstractSoilModel

A model for simulating the flow of water and heat in a porous medium by solving the Richardson-Richards equation and the heat equation, including terms for phase change.

A variety of boundary condition types are supported, including FluxBC, MoistureStateBC/TemperatureStateBC, FreeDrainage (only for the bottom of the domain), and an AtmosDrivenFluxBC (under which radiative fluxes and turbulent surface fluxes are computed and used as boundary conditions). Please see the documentation for this boundary condition type for more details.

• parameters: The parameter sets

• domain: the soil domain, using ClimaCore.Domains

• boundary_conditions: the boundary conditions for RRE and heat, of type AbstractSoilBoundaryConditions

• sources: A tuple of sources, each of type AbstractSoilSource

• lateral_flow: A boolean flag which, when false, turns off the horizontal flow of water and heat

EnergyHydrology{FT}(;
    parameters::PS
    domain::D,
    boundary_conditions::NamedTuple,
    sources::Tuple,
    lateral_flow::Bool = true
) where {FT, D, PS}

A constructor for a EnergyHydrology model, which sets the default value of the lateral_flow flag to true.

EnergyHydrologyParameters{
        FT <: AbstractFloat,
        F <: Union{<:AbstractFloat, ClimaCore.Fields.Field},
        SF <: Union{<:AbstractFloat, ClimaCore.Fields.Field},
        C,
        PSE,
    }

A parameter structure for the integrated soil water and energy equation system.

Note that we require two different parameter types F and SF; these are for parameters that are defined on the surface only and those defined in the interior of the soil domain:

• Surface parameters: albedo in each wavelength band (SF)
• Scalar parameters: emissivity, α, β, γ, γT_ref, Ω,

roughness lengths z0, dds ) (FT)

• Parameters defined in the interior: all else (F)

• κ_dry: The dry soil thermal conductivity, W/m/K

• κ_sat_frozen: The saturated thermal conductivity of frozen soil, W/m/K

• κ_sat_unfrozen: The saturated thermal conductivity of unfrozen soil, W/m/K

• ρc_ds: The volumetric heat capacity of dry soil, J/m^3/K (per volume dry soil, not per volume soil solids)

• ν: The porosity of the soil (m^3/m^3)

• ν_ss_om: The volumetric fraction of the soil solids in organic matter (m^3/m^3)

• ν_ss_quartz: The volumetric fraction of the soil solids in quartz (m^3/m^3)

• ν_ss_gravel: The volumetric fraction of the soil solids in gravel (m^3/m^3)

• α: The parameter α used in computing Kersten number, unitless

• β: The parameter β used in computing Kersten number, unitless

• hydrology_cm: The soil hydrology closure model: van Genuchten or Brooks and Corey

• K_sat: The saturated hydraulic conductivity (m/s)

• S_s: The specific storativity (1/m)

• θ_r: The residual water fraction (m^3/m^3

• Ω: Ice impedance factor for the hydraulic conductivity

• γ: Coefficient of viscosity factor for the hydraulic conductivity

• γT_ref: Reference temperature for the viscosity factor

• PAR_albedo: Soil PAR Albedo

• NIR_albedo: Soil NIR Albedo

• emissivity: Soil Emissivity

• z_0m: Roughness length for momentum

• z_0b: Roughness length for scalars

• d_ds: Maximum dry soil layer thickness under evaporation (m)

• earth_param_set: Physical constants and clima-wide parameters

FreeDrainage <: AbstractWaterBC

A concrete type of soil boundary condition, for use at the BottomBoundary only, where the flux is set to be F = -K∇h = -K.

HeatFluxBC <: AbstractHeatBC

A simple concrete type of boundary condition, which enforces a normal flux boundary condition f(p,t) at either the top or bottom of the domain.

MoistureStateBC <: AbstractWaterBC

A simple concrete type of boundary condition, which enforces a state boundary condition ϑ_l = f(p,t) at either the top or bottom of the domain.

PhaseChange{FT} <: AbstractSoilSource{FT}

PhaseChange source type.

RichardsAtmosDrivenFluxBC{F <: PrescribedPrecipitation, R <: AbstractRunoffModel} <: AbstractWaterBC

A concrete type of boundary condition intended only for use with the RichardsModel, which uses a prescribed precipitation rate (m/s) to compute the infiltration into the soil.

A runoff model is used to simulate surface and subsurface runoff and this is accounted for when setting boundary conditions. In order to run the simulation without runoff, choose runoff = NoRunoff() - this is also the default.

If you wish to simulate precipitation and runoff in the full EnergyHydrology model, you must use the AtmosDrivenFluxBC type.

• precip: The prescribed liquid water precipitation rate f(t) (m/s); Negative by convention.

• runoff: The runoff model. The default is no runoff.

RichardsModel

A model for simulating the flow of water in a porous medium by solving the Richardson-Richards Equation.

A variety of boundary condition types are supported, including FluxBC, RichardsAtmosDrivenFluxBC, MoistureStateBC, and FreeDrainage (only for the bottom of the domain).

If you wish to simulate soil hydrology under the context of a prescribed precipitation volume flux (m/s) as a function of time, the RichardsAtmosDrivenFluxBC type should be chosen. Please see the documentation for more details.

• parameters: the parameter set

• domain: the soil domain, using ClimaCore.Domains

• boundary_conditions: the boundary conditions, of type AbstractSoilBoundaryConditions

• sources: A tuple of sources, each of type AbstractSoilSource

• lateral_flow: A boolean flag which, when false, turns off the horizontal flow of water

RichardsModel{FT}(;
    parameters::RichardsParameters,
    domain::D,
    boundary_conditions::NamedTuple,
    sources::Tuple,
    lateral_flow::Bool = true
) where {FT, D}

A constructor for a RichardsModel, which sets the default value of lateral_flow to be true.

RichardsParameters{F <: Union{<: AbstractFloat, ClimaCore.Fields.Field}, C <: AbstractSoilHydrologyClosure}

A struct for storing parameters of the RichardsModel.

• ν: The porosity of the soil (m^3/m^3)

• hydrology_cm: The hydrology closure model: vanGenuchten or BrooksCorey

• K_sat: The saturated hydraulic conductivity (m/s)

• S_s: The specific storativity (1/m)

• θ_r: The residual water fraction (m^3/m^3

SoilSublimation{FT} <: AbstractSoilSource{FT}

Soil Sublimation source type. Used to defined a method of ClimaLand.source! for soil sublimation.

TemperatureStateBC <: AbstractHeatBC

A simple concrete type of boundary condition, which enforces a state boundary condition T = f(p,t) at either the top or bottom of the domain.

WaterFluxBC <: AbstractWaterBC

A simple concrete type of boundary condition, which enforces a normal flux boundary condition f(p,t) at either the top or bottom of the domain.

WaterHeatBC{W <: AbstractWaterBC, H <: AbstractHeatBC} <:
   AbstractEnergyHydrologyBC

A general struct used to store the boundary conditions for Richards and the soil heat equations separately; useful when the boundary conditions for each component are independent of each other.

vanGenuchten{FT} <: AbstractSoilHydrologyClosure{FT}

The van Genuchten soil hydrology closure, chosen when the hydraulic conductivity and matric potential are modeled using the van Genuchten parameterization (van Genuchten 1980; see also Table 8.2 of G. Bonan 2019).

• α: The inverse of the air entry potential (1/m)

• n: The van Genuchten pore-size distribution index (unitless)

• m: The van Genuchten parameter m = 1 - 1/n (unitless)

• S_c: A derived parameter: the critical saturation at which capillary flow no longer replenishes the surface

append_source(src::AbstractSoilSource, srcs::Tuple)::Tuple

Appends src to the tuple of sources srcs if src is of type AbstractSoilSource.

append_source(src::Nothing , srcs::Tuple)::Tuple

Appends src to the tuple of sources srcs if src is of type AbstractSoilSource.

 approximate_ψ_S_slope(cm::BrooksCorey)

The slope of the logψ-logS curve for the Brooks and Corey model.

 approximate_ψ_S_slope(cm::vanGenuchten)

An estimate of the slope of the absolute value of the logψ-logS curve. Following Lehmann, Assouline, and Or (2008), we linearize the ψ(S) curve about the inflection point (where d²ψ/dS² = 0, at S = (1+m)^(-m)).

covariant3_unit_vector(local_geometry)

A function to compute the unit vector in the direction of the normal to the surface.

Adapted from ClimaAtmos.jl's unitbasisvector_data function.

dry_soil_layer_thickness(S_w::FT, S_c::FT, d_ds::FT)::FT where {FT}

Returns the maximum dry soil layer thickness that can develop under vapor flux; this is used when computing the soil resistance to vapor flux according to Swenson et al (2012)/Sakaguchi and Zeng (2009).

dψdϑ(cm::BrooksCorey{FT}, ϑ, ν, θr, Ss)

Computes and returns the derivative of the pressure head with respect to ϑ for the Brooks and Corey formulation.

dψdϑ(cm::vanGenuchten{FT}, ϑ, ν, θr, Ss)

Computes and returns the derivative of the pressure head with respect to ϑ for the van Genuchten formulation.

effective_saturation(porosity::FT, ϑ_l::FT, θr::FT) where {FT}

A point-wise function computing the effective saturation.

horizontal_components!(dY::ClimaCore.Fields.FieldVector, domain::Column, _...) Updates dY in place by adding in the tendency terms resulting from horizontal derivative operators.

In the case of a column domain, there are no horizontal contributions to the right hand side.

horizontalcomponents!(dY::ClimaCore.Fields.FieldVector, domain::Union{HybridBox, SphericalShell}, lateralflow::Val{false}, _...) Updates dY in place by adding in the tendency terms resulting from horizontal derivative operators.

In the case of a 3D domain, for either the RichardsModel or the EnergyHydrology model, if the lateral_flow flag is set to false, there are no horizontal contributions to the right hand side.

horizontalcomponents!(dY::ClimaCore.Fields.FieldVector, domain::Union{HybridBox, SphericalShell}, lateralflow::Val{true}, model::EnergyHydrology, p::NamedTuple)

Updates dY in place by adding in the tendency terms resulting from horizontal derivative operators for the EnergyHydrology model, in the case of a hybrid box or spherical shell domain with the model lateral_flag set to true.

The horizontal contributions are computed using the WeakDivergence and Gradient operators.

horizontalcomponents!(dY::ClimaCore.Fields.FieldVector, domain::Union{HybridBox, SphericalShell}, lateralflow::Val{true}, model::RichardsModel, p::NamedTuple)

Updates dY in place by adding in the tendency terms resulting from horizontal derivative operators for the RichardsModel, in the case of a hybrid box or spherical shell domain with the model lateral_flag set to true.

The horizontal contributions are computed using the WeakDivergence and Gradient operators.

 hydraulic_conductivity(cm::BrooksCorey{FT}, K_sat::FT, S::FT) where {FT}

A point-wise function returning the hydraulic conductivity, using the Brooks and Corey formulation.

 hydraulic_conductivity(cm::vanGenuchten{FT}, K_sat::FT, S::FT) where {FT}

A point-wise function returning the hydraulic conductivity, using the van Genuchten formulation.

ice_fraction(θ_l::FT, θ_i::FT, ν::FT, θ_r::FT)::FT where {FT}

Computes and returns the ice fraction, which is the fraction of the vapor flux that is due to sublimation, and the fraction of the humidity in the air due to ice, as

f = Si/(Si+S_l)

This same fraction is used to estimate the specific humidity, i.e. q = qoverice * f + qoverwater * (1-f).

impedance_factor(
    f_i::FT,
    Ω::FT
) where {FT}

Returns the multiplicative factor reducing conductivity when a fraction of ice f_i is present.

Only for use with the EnergyHydrology model.

 inverse_matric_potential(cm::BrooksCorey{FT}, ψ::FT) where {FT}

A point-wise function returning the effective saturation, given the matric potential, using the Brooks and Corey formulation.

 inverse_matric_potential(cm::vanGenuchten{FT}, ψ::FT) where {FT}

A point-wise function returning the effective saturation, given the matric potential, using the van Genuchten formulation.

is_saturated(twc::FT, ν::FT) where {FT}

A helper function which can be used to indicate whether a layer of soil is saturated based on if the total volumetric water content, twc is greater than porosity ν.

kersten_number(
    θ_i::FT,
    S_r::FT,
    α::FT,
    β::FT,
    ν_ss_om::FT,
    ν_ss_quartz::FT,
    ν_ss_gravel::FT,
    ) where {FT}

Compute the expression for the Kersten number, using the Balland and Arp model.

 matric_potential(cm::BrooksCorey{FT}, S::FT) where {FT}

A point-wise function returning the matric potential, using the Brooks and Corey formulation.

 matric_potential(cm::vanGenuchten{FT}, S::FT) where {FT}

A point-wise function returning the matric potential, using the van Genuchten formulation.

phase_change_source(
    θ_l::FT,
    θ_i::FT,
    T::FT,
    τ::FT,
    ν::FT,
    θ_r::FT,
    hydrology_cm::C,
    earth_param_set::EP,
) where {FT, EP, C}

Returns the source term (1/s) used for converting liquid water and ice into each other during phase changes. Note that there are unitless prefactors multiplying this term in the equations.

Note that these equations match what is in Dall'Amico (for θstar, ψ(T), ψw0). We should double check them in the case where we have ϑl > θl, but they should be very close to the form we want regardless.

pressure_head(
    cm::BrooksCorey{FT},
    θ_r::FT,
    ϑ_l::FT,
    ν_eff::FT,
    S_s::FT,
) where {FT}

A point-wise function returning the pressure head in variably saturated soil, using the Brooks and Corey matric potential if the soil is not saturated, and an approximation of the positive pressure in the soil if the soil is saturated.

pressure_head(
    cm::vanGenuchten{FT},
    θ_r::FT,
    ϑ_l::FT,
    ν_eff::FT,
    S_s::FT,
) where {FT}

A point-wise function returning the pressure head in variably saturated soil, using the van Genuchten matric potential if the soil is not saturated, and an approximation of the positive pressure in the soil if the soil is saturated.

relative_saturation(
        θ_l::FT,
        θ_i::FT,
        ν::FT
) where {FT}

Compute the expression for relative saturation. This is referred to as θ_sat in Balland and Arp's paper.

soil_boundary_fluxes!(
    bc::AtmosDrivenFluxBC{
        <:PrescribedAtmosphere,
        <:PrescribedRadiativeFluxes,
    },
    boundary::ClimaLand.TopBoundary,
    model::EnergyHydrology,
    Δz,
    Y,
    p,
    t,
)

Returns the net volumetric water flux (m/s) and net energy flux (W/m^2) for the soil EnergyHydrology model at the top of the soil domain.

If you wish to compute surface fluxes taking into account the presence of a canopy, snow, etc, as in a land surface model, this is not the correct method to be using.

This function calls the turbulent_fluxes and net_radiation functions, which use the soil surface conditions as well as the atmos and radiation conditions in order to compute the surface fluxes using Monin Obukhov Surface Theory.

soil_boundary_fluxes!(bc::WaterHeatBC, boundary::TopBoundary, model, Δz, Y, p, t)

updates the boundary fluxes for ϑl and ρeint.

soil_resistance(θ_l::FT,
                θ_i::FT,
                hydrology_cm::C,
                ν::FT,
                θ_r::FT,
                d_ds::FT,
                earth_param_set::EP,
               ) where {FT, EP, C}

Computes the resistance of the top of the soil column to water vapor diffusion, as a function of the surface volumetric liquid water fraction θ_l, the augmented liquid water fraction ϑ_l, the volumetric ice water fraction θ_i, and other soil parameters.

soil_tortuosity(θ_l::FT, θ_i::FT, ν::FT) where {FT}

Computes the tortuosity of water vapor in a porous medium, as a function of porosity ν and the volumetric liquid water and ice contents, θ_l and θ_i.

See Equation (1) of : Shokri, N., P. Lehmann, and D. Or (2008), Effects of hydrophobic layers on evaporation from porous media, Geophys. Res. Lett., 35, L19407, doi:10.1029/ 2008GL035230.

temperature_from_ρe_int(ρe_int::FT, θ_i::FT, ρc_s::FT
                        earth_param_set::EP) where {FT, EP}

A pointwise function for computing the temperature from the volumetric internal energy, volumetric ice content, and volumetric heat capacity of the soil.

thermal_conductivity(
    κ_dry::FT,
    K_e::FT,
    κ_sat::FT
) where {FT}

Compute the expression for thermal conductivity of soil matrix.

thermal_time(ρc::FT, Δz::FT, κ::FT) where {FT}

Returns the thermal timescale for temperature differences across a typical thickness Δz to equilibrate.

viscosity_factor(
    T::FT,
    γ::FT,
    γT_ref::FT,
) where {FT}

Returns the multiplicative factor which accounts for the temperature dependence of the conductivity.

Only for use with the EnergyHydrology model.

volumetric_heat_capacity(
    θ_l::FT,
    θ_i::FT,
    ρc_ds::FT,
    earth_param_set::EP,
) where {FT,EP}

Compute the expression for volumetric heat capacity.

volumetric_internal_energy(θ_i::FT, ρc_s::FT, T::FT,
                             earth_param_set::EP) where {FT, EP}

A pointwise function for computing the volumetric internal energy of the soil, given the volumetric ice content, volumetric heat capacity, and temperature.

volumetric_internal_energy_liq(T::FT, earth_param_set::EP) where {FT, EP}

A pointwise function for computing the volumetric internal energy of the liquid water in the soil, given the temperature T.

volumetric_liquid_fraction(ϑ_l::FT, ν_eff::FT, θ_r::FT) where {FT}

A pointwise function returning the volumetric liquid fraction given the augmented liquid fraction and the effective porosity.

function κ_dry(ρp::FT,
               ν::FT,
               κ_solid::FT,
               κ_air::FT;
               a = FT(0.053)) where {FT}

Computes the thermal conductivity of dry soil according to the model of Balland and Arp.

κ_sat(
    θ_l::FT,
    θ_i::FT,
    κ_sat_unfrozen::FT,
    κ_sat_frozen::FT
) where {FT}

Compute the expression for saturated thermal conductivity of soil matrix.

function κ_sat_frozen(
    κ_solid::FT,
    ν::FT,
    κ_ice::FT
) where {FT}

Computes the thermal conductivity for saturated frozen soil.

function κ_sat_unfrozen(
    κ_solid::FT,
    ν::FT,
    κ_l::FT
) where {FT}

Computes the thermal conductivity for saturated unfrozen soil.

κ_solid(ν_ss_om::FT,
        ν_ss_quartz::FT,
        κ_om::FT,
        κ_quartz::FT,
        κ_minerals::FT) where {FT}

Computes the thermal conductivity of the solid material in soil. The _ss_ subscript denotes that the volumetric fractions of the soil components are referred to the soil solid components, not including the pore space.

auxiliary_domain_names(soil::RichardsModel)

A function which returns the names of the auxiliary domain names of RichardsModel.

auxiliary_types(soil::EnergyHydrology{FT}) where {FT}

A function which returns the types of the auxiliary variables of EnergyHydrology.

auxiliary_types(soil::RichardsModel)

A function which returns the names of the auxiliary types of RichardsModel.

auxiliary_vars(soil::EnergyHydrology)

A function which returns the names of the auxiliary variables of EnergyHydrology.

auxiliary_vars(soil::RichardsModel)

A function which returns the names of the auxiliary variables of RichardsModel.

boundary_flux(bc::FreeDrainage,
                       boundary::ClimaLand.BottomBoundary,
                       model::AbstractSoilModel,
                       Δz::ClimaCore.Fields.Field,
                       Y::ClimaCore.Fields.FieldVector,
                       p::NamedTuple,
                       t,
                       )::ClimaCore.Fields.Field

A method of boundary fluxes which enforces free drainage at the bottom of the domain.

boundary_flux(bc::HeatFluxBC,  _...)::ClimaCore.Fields.Field

A method of boundary fluxes which returns the desired flux.

We add a field of zeros in order to convert the bc (float) into a field.

boundary_flux(rre_bc::MoistureStateBC,
                       ::ClimaLand.BottomBoundary,
                       model::AbstractSoilModel,
                       Δz::ClimaCore.Fields.Field,
                       Y::ClimaCore.Fields.FieldVector,
                       p::NamedTuple,
                       t,
                       )::ClimaCore.Fields.Field

A method of boundary fluxes which converts a state boundary condition on θ_l at the bottom of the domain into a flux of liquid water.

boundary_flux(rre_bc::MoistureStateBC,
                       ::ClimaLand.TopBoundary,
                       model::AbstractSoilModel,
                       Δz::ClimaCore.Fields.Field,
                       Y::ClimaCore.Fields.FieldVector,
                       p::NamedTuple,
                       t,
                       )::ClimaCore.Fields.Field

A method of boundary fluxes which converts a state boundary condition on θ_l at the top of the domain into a flux of liquid water.

boundary_flux(bc::RichardsAtmosDrivenFluxBC,
                       boundary::ClimaLand.AbstractBoundary,
                       model::RichardsModel{FT},
                       Δz::ClimaCore.Fields.Field,
                       Y::ClimaCore.Fields.FieldVector,
                       p::NamedTuple,
                       t,
                       )::ClimaCore.Fields.Field where {FT}

A method of boundary fluxes which returns the desired water volume flux for the RichardsModel, at the top of the domain, in the case of a prescribed precipitation flux.

If model.runoff is not of type NoRunoff, surface runoff is accounted for when computing the infiltration.

boundary_flux(heat_bc::TemperatureStateBC,
                       ::ClimaLand.BottomBoundary,
                       model::EnergyHydrology,
                       Δz::ClimaCore.Fields.Field,
                       Y::ClimaCore.Fields.FieldVector,
                       p::NamedTuple,
                       t,
                       )::ClimaCore.Fields.Field

A method of boundary fluxes which converts a state boundary condition on temperature at the bottom of the domain into a flux of energy.

boundary_flux(heat_bc::TemperatureStateBC,
                       ::ClimaLand.TopBoundary,
                       model::EnergyHydrology,
                       Δz::ClimaCore.Fields.Field,
                       Y::ClimaCore.Fields.FieldVector,
                       p::NamedTuple,
                       t,
                       )::ClimaCore.Fields.Field

A method of boundary fluxes which converts a state boundary condition on temperature at the top of the domain into a flux of energy.

boundary_flux(bc::WaterFluxBC,  _...)::ClimaCore.Fields.Field

A method of boundary fluxes which returns the desired flux.

We add a field of zeros in order to convert the bc (float) into a field.

boundary_var_domain_names(::AtmosDrivenFluxBC{<:AbstractAtmosphericDrivers,
                                              <:AbstractRadiativeDrivers,
                                              <:AbstractRunoffModel,
                                              },
                          ::ClimaLand.TopBoundary)

An extension of the boundary_var_domain_names method for AtmosDrivenFluxBC. This specifies the part of the domain on which the additional variables should be defined.

boundary_var_domain_names(::AtmosDrivenFluxBC{<:AbstractAtmosphericDrivers,
                                              <:AbstractRadiativeDrivers,
                                              <:Runoff.TOPMODELRunoff,
                                              },
                          ::ClimaLand.TopBoundary)

An extension of the boundary_var_domain_names method for AtmosDrivenFluxBC with TOPMODELRunoff. This specifies the part of the domain on which the additional variables should be defined.

boundary_var_domain_names(::MoistureStateBC, ::ClimaLand.TopBoundary)

An extension of the boundary_var_domain_names method for MoistureStateBC at the top boundary.

boundary_var_domain_names(::RichardsAtmosDrivenFluxBC{<:PrescribedPrecipitation,
                                          <:Runoff.AbstractRunoffModel,
                                          },
                          ::ClimaLand.TopBoundary)

An extension of the boundary_var_domain_names method for RichardsAtmosDrivenFluxBC with no runoff modeled.

boundary_var_domain_names(::RichardsAtmosDrivenFluxBC{<:PrescribedPrecipitation,
                                          <:Runoff.TOPMODELRunoff,
                                          },
                          ::ClimaLand.TopBoundary)

An extension of the boundary_var_domain_names method for RichardsAtmosDrivenFluxBC with TOPMODELRunoff.

boundary_var_types(::Soil.EnergyHydrology{FT}, ::AbstractEnergyHydrologyBC, ::ClimaLand.AbstractBoundary) where {FT}

The list of domain names for additional variables added to the EnergyHydrology model auxiliary state, which defaults to adding storage for the boundary flux field.

Because we supply boundary conditions for water and heat, we found it convenient to have these stored as a NamedTuple under the names top_bc and bottom_bc.

boundary_var_types(
    model::EnergyHydrology{FT},
    ::AtmosDrivenFluxBC{
        <:PrescribedAtmosphere{FT},
        <:AbstractRadiativeDrivers{FT},
        <:Runoff.TOPMODELRunoff{FT},
    }, ::ClimaLand.TopBoundary,
) where {FT}

An extension of the boundary_var_types method for AtmosDrivenFluxBC with TOPMODELRunoff. This specifies the type of the additional variables.

boundary_var_types(
    ::EnergyHydrology{FT},
    ::AtmosDrivenFluxBC{
        <:PrescribedAtmosphere{FT},
        <:AbstractRadiativeDrivers{FT},
        <:AbstractRunoffModel,
    }, ::ClimaLand.TopBoundary,
) where {FT}

An extension of the boundary_var_types method for AtmosDrivenFluxBC. This specifies the type of the additional variables.

boundary_var_types(::RichardsModel{FT},
                    ::MoistureStateBC,
                    ::ClimaLand.TopBoundary,
                    ) where {FT}

An extension of the boundary_var_types method for MoistureStateBC at the top boundary.

boundary_var_types(::RichardsModel{FT}
                    ::RichardsAtmosDrivenFluxBC{<:PrescribedPrecipitation,
                                               <:Runoff.AbstractRunoffModel,
                                              },
                    ::ClimaLand.TopBoundary,
                    ) where {FT}

An extension of the boundary_var_types method for RichardsAtmosDrivenFluxBC with no runoff modeled.

boundary_var_types(::RichardsModel{FT},
                    ::RichardsAtmosDrivenFluxBC{<:PrescribedPrecipitation,
                                               <:Runoff.TOPMODELRunoff{FT},
                                              },
                    ::ClimaLand.TopBoundary,
                    ) where {FT}

An extension of the boundary_var_types method for RichardsAtmosDrivenFluxBC with TOPMODELRunoff.

boundary_vars(::AtmosDrivenFluxBC{<:AbstractAtmosphericDrivers,
                                <:AbstractRadiativeDrivers,
                                <:AbstractRunoffModel,
                                }, ::ClimaLand.TopBoundary)

An extension of the boundary_vars method for AtmosDrivenFluxBC. This adds the surface conditions (SHF, LHF, evaporation, and resistance) and the net radiation to the auxiliary variables.

These variables are updated in place in soil_boundary_fluxes!.

boundary_vars(::AtmosDrivenFluxBC{<:AbstractAtmosphericDrivers,
                                <:AbstractRadiativeDrivers,
                                <:Runoff.TOPMODELRunoff,
                                }, ::ClimaLand.TopBoundary)

An extension of the boundary_vars method for AtmosDrivenFluxBC with TOPMODELRunoff. This adds the surface conditions (SHF, LHF, evaporation, and resistance) and the net radiation to the auxiliary variables.

These variables are updated in place in soil_boundary_fluxes!.

boundary_vars(::MoistureStateBC, ::ClimaLand.TopBoundary)

An extension of the boundary_vars method for MoistureStateBC at the top boundary.

These variables are updated in place in boundary_flux.

boundary_vars(::RichardsAtmosDrivenFluxBC{<:PrescribedPrecipitation,
                                          <:Runoff.AbstractRunoffModel,
                                          }, ::ClimaLand.TopBoundary)

An extension of the boundary_vars method for RichardsAtmosDrivenFluxBC with no runoff modeled.

These variables are updated in place in boundary_flux.

boundary_vars(::RichardsAtmosDrivenFluxBC{<:PrescribedPrecipitation,
                                          <:Runoff.TOPMODELRunoff,
                                          }, ::ClimaLand.TopBoundary)

An extension of the boundary_vars method for RichardsAtmosDrivenFluxBC with TOPMODELRunoff.

These variables are updated in place in boundary_flux.

ClimaLand.get_drivers(model::RichardsModel)

Returns the driver variable symbols for the RichardsModel; these depend on the boundary condition type and currently only are required for the RichardsAtmosDrivenFluxBC, which is driven by a prescribed time and space varying precipitation.

make_explicit_tendency(model::Soil.RichardsModel)

An extension of the function make_compute_imp_tendency, for the Richardson- Richards equation.

Construct the tendency computation function for the explicit terms of the RHS, which are horizontal components and source/sink terms.

make_compute_exp_tendency(model::EnergyHydrology)

An extension of the function make_compute_exp_tendency, for the integrated soil energy and heat equations, including phase change.

This function creates and returns a function which computes the entire right hand side of the PDE for Y.soil.ϑ_l, Y.soil.θ_i, Y.soil.ρe_int, and updates dY.soil in place with those values. All of these quantities will be stepped explicitly.

This has been written so as to work with Differential Equations.jl.

make_compute_imp_tendency(model::RichardsModel)

An extension of the function make_compute_imp_tendency, for the Richardson- Richards equation.

This function creates and returns a function which computes the entire right hand side of the PDE for ϑ_l, and updates dY.soil.ϑ_l in place with that value.

make_compute_imp_tendency(model::EnergyHydrology)

An extension of the function make_compute_imp_tendency, for the integrated soil energy and heat equations, including phase change.

This version of this function computes the right hand side of the PDE for Y.soil.ϑ_l, which is the only quantity we currently step implicitly.

This has been written so as to work with Differential Equations.jl.

ClimaLand.make_compute_jacobian(model::EnergyHydrology{FT}) where {FT}

Creates and returns the compute_jacobian! function for the EnergyHydrology model. This updates the contribution for the soil liquid water content only.

Using this Jacobian with a backwards Euler timestepper is equivalent to using the modified Picard scheme of Celia et al. (1990).

ClimaLand.make_compute_jacobian(model::RichardsModel{FT}) where {FT}

Creates and returns the compute_jacobian! function for RichardsModel. This updates the contribution for the soil liquid water content.

Using this Jacobian with a backwards Euler timestepper is equivalent to using the modified Picard scheme of Celia et al. (1990).

make_update_aux(model::EnergyHydrology)

An extension of the function make_update_aux, for the integrated soil hydrology and energy model.

This function creates and returns a function which updates the auxiliary variables p.soil.variable in place.

This has been written so as to work with Differential Equations.jl.

make_update_aux(model::RichardsModel)

An extension of the function make_update_aux, for the Richardson- Richards equation.

This function creates and returns a function which updates the auxiliary variables p.soil.variable in place.

This has been written so as to work with Differential Equations.jl.

prognostic_types(soil::EnergyHydrology{FT}) where {FT}

A function which returns the types of the prognostic variables of EnergyHydrology.

prognostic_vars(soil::EnergyHydrology)

A function which returns the names of the prognostic variables of EnergyHydrology.

prognostic_vars(soil::RichardsModel)

A function which returns the names of the prognostic variables of RichardsModel.

ClimaLand.set_dfluxBCdY!(
    model::RichardsModel,
    ::MoistureStateBC,
    boundary::ClimaLand.TopBoundary,
    Δz,
    Y,
    p,
    t,

)

Computes the derivative of the flux in the top layer (due to the boundary condition), with respect to the state variable in the top layer. This value is then updated in-place in the cache.

For Richards equation (a diffusion equation with a single state variable), this is given by ∂F_bc/∂Y_N= -K_N (∂ψ_bc/∂ϑ_N) / Δz, where N indicates the top layer cell index and ψ_bc is the pressure head at the boundary condition.

 source!(dY::ClimaCore.Fields.FieldVector,
         src::PhaseChange{FT},
         Y::ClimaCore.Fields.FieldVector,
         p::NamedTuple,
         model
         )

Computes the source terms for phase change.

 source!(dY::ClimaCore.Fields.FieldVector,
         src::SoilSublimation{FT},
         Y::ClimaCore.Fields.FieldVector,
         p::NamedTuple,
         model
         )

Updates dY.soil.θ_i in place with a term due to sublimation; this only affects the surface layer of soil.

ClimaLand.surface_albedo(
    model::EnergyHydrology{FT},
    Y,
    p,
) where {FT}

Returns the surface albedo field of the EnergyHydrology soil model.

ClimaLand.surface_emissivity(
    model::EnergyHydrology{FT},
    Y,
    p,
) where {FT}

Returns the surface emissivity field of the EnergyHydrology soil model.

ClimaLand.surface_height(
    model::EnergyHydrology{FT},
    Y,
    p,
) where {FT}

Returns the surface height of the EnergyHydrology model.

ClimaLand.surface_resistance(
    model::EnergyHydrology{FT},
    Y,
    p,
    t,
) where {FT}

Returns the surface resistance field of the EnergyHydrology soil model.

ClimaLand.surface_specific_humidity(
    model::EnergyHydrology{FT},
    Y,
    p,
    T_sfc,
    ρ_sfc
) where {FT}

Returns the surface specific humidity field of the EnergyHydrology soil model.

This models the specific humidity over the soil liquid water as the saturated value multiplied by the factor exp(ψ_sfc g M_w/(RT_sfc)) in accordance with the Clausius-Clapeyron equation, where ψ_sfc is the matric potential at the surface, T_sfc the surface temperature, g the gravitational acceleration on the surface of the Earth, M_w the molar mass of water, and R the universal gas constant.

Over the soil ice, the specific humidity is the saturated value.

The total surface specific humidity of the soil is approximated by q = qoverice * f + qoverwater * (1-f), where f is given by the function ice_fraction.

ClimaLand.surface_temperature(
    model::EnergyHydrology{FT},
    Y,
    p,
    t,
) where {FT}

Returns the surface temperature field of the EnergyHydrology soil model.

The assumption is that the soil surface temperature is the same as the temperature at the center of the first soil layer.

AbstractDomain{FT <:AbstractFloat}

An abstract type for domains.

The domain structs typically hold information regarding the bounds of the domain, the boundary condition type (periodic or not), and the spatial discretization.

Additionally, the domain struct holds the relevant spaces for that domain. For example, a 3D domain holds the center space (in terms of finite difference - the space corresponding to the centers of each element), and the top face space where surface fluxes are computed.

Column{FT} <: AbstractDomain{FT}

A struct holding the necessary information to construct a domain, a mesh, a center and face space, etc. for use when a finite difference in 1D is suitable, as for a soil column model.

space is a NamedTuple holding the surface space (in this case, the top face space) and the center space for the subsurface. These are stored using the keys :surface and :subsurface.

Fields

• zlim: Domain interval limits, (zmin, zmax), in meters

• nelements: Number of elements used to discretize the interval

• dz_tuple: Tuple for mesh stretching specifying target (dzbottom, dztop) (m). If nothing, no stretching is applied.

• boundary_names: Boundary face identifiers

• space: A NamedTuple of associated ClimaCore spaces: in this case, the surface space and subsurface center space

• fields: Fields associated with the coordinates of the domain that are useful to store

Column(;
    zlim::Tuple{FT, FT},
    nelements::Int,
    dz_tuple::Union{Tuple{FT, FT}, Nothing} = nothing) where {FT}

Outer constructor for the Column type.

Using ClimaCore tools, the coordinate mesh can be stretched such that the top of the domain has finer resolution than the bottom of the domain. In order to activate this, a tuple with the target dzbottom and dztop should be passed via keyword argument. The default is uniform spacing. Please note that in order to use this feature, ClimaCore requires that the elements of zlim be <=0. Additionally, the dz_tuple you supply may not be compatible with the domain boundaries in some cases, in which case you may need to choose different values.

The boundary_names field values are used to label the boundary faces at the top and bottom of the domain.

struct HybridBox{FT} <: AbstractDomain{FT}
    xlim::Tuple{FT, FT}
    ylim::Tuple{FT, FT}
    zlim::Tuple{FT, FT}
    dz_tuple::Union{Tuple{FT, FT}, Nothing}
    nelements::Tuple{Int, Int, Int}
    npolynomial::Int
    periodic::Tuple{Bool, Bool}
end

A struct holding the necessary information to construct a domain, a mesh, a 2d spectral element space (horizontal) x a 1d finite difference space (vertical), and the resulting coordinate field. This domain is not periodic along the z-axis. Note that only periodic domains are supported in the horizontal.

space is a NamedTuple holding the surface space (in this case, the top face space) and the center space for the subsurface. These are stored using the keys :surface and :subsurface.

Fields

• xlim: Domain interval limits along x axis, in meters

• ylim: Domain interval limits along y axis, in meters

• zlim: Domain interval limits along z axis, in meters

• dz_tuple: Tuple for mesh stretching specifying target (dzbottom, dztop) (m). If nothing, no stretching is applied.

• nelements: Number of elements to discretize interval, (nx, ny,nz)

• npolynomial: Polynomial order for the horizontal directions

• periodic: Flag indicating periodic boundaries in horizontal. only true is supported

• space: A NamedTuple of associated ClimaCore spaces: in this case, the surface space and subsurface center space

• fields: Fields associated with the coordinates of the domain that are useful to store

HybridBox(;
    xlim::Tuple{FT, FT},
    ylim::Tuple{FT, FT},
    zlim::Tuple{FT, FT},
    nelements::Tuple{Int, Int, Int},
    npolynomial::Int,
    dz_tuple::Union{Tuple{FT, FT}, Nothing} = nothing,
    periodic = (true, true),
) where {FT}

Constructs the HybridBox domain with limits xlim ylim and zlim (wherexlim[1] < xlim[2],ylim[1] < ylim[2], andzlim[1] < zlim[2]),nelementsmust be a tuple with three values, with the first value corresponding to the x-axis, the second corresponding to the y-axis, and the third corresponding to the z-axis. The domain is periodic at the (xy) boundaries, and the function space is of polynomial ordernpolynomial` in the horizontal directions.

Using ClimaCore tools, the coordinate mesh can be stretched such that the top of the domain has finer resolution than the bottom of the domain. In order to activate this, a tuple with the target dzbottom and dztop should be passed via keyword argument. The default is uniform spacing. Please note that in order to use this feature, ClimaCore requires that the elements of zlim be <=0. Additionally, the dz_tuple you supply may not be compatible with the domain boundaries in some cases, in which case you may need to choose different values.

Plane{FT} <: AbstractDomain{FT}

A struct holding the necessary information to construct a domain, a mesh, a 2d spectral element space, and the resulting coordinate field. Note that only periodic domains are currently supported.

space is a NamedTuple holding the surface space (in this case, the entire Plane space).

Fields

• xlim: Domain interval limits along x axis, in meters

• ylim: Domain interval limits along y axis, in meters

• nelements: Number of elements to discretize interval, (nx, ny)

• periodic: Flags for periodic boundaries; only true is supported

• npolynomial: Polynomial order for both x and y

• space: A NamedTuple of associated ClimaCore spaces: in this case, the surface(Plane) space

Plane(;
    xlim::Tuple{FT,FT},
    ylim::Tuple{FT,FT},
    nelements::Tuple{Int,Int},
    periodic::Tuple{Bool,Bool},
    npolynomial::Int,
    comms_ctx = ClimaComms.SingletonCommsContext(),
    ) where {FT}

Outer constructor for the Plane domain, using keyword arguments.

Point{FT} <: AbstractDomain{FT}

A domain for single column surface variables. For models such as ponds, snow, plant hydraulics, etc. Enables consistency in variable initialization across all domains.

space is a NamedTuple holding the surface space (in this case, the Point space).

Fields

• z_sfc: Surface elevation relative to a reference (m)

• space: A NamedTuple of associated ClimaCore spaces: in this case, the Point (surface) space

Point(;z_sfc::FT,
       comms = ClimaComms.SingletonCommsContext()
      ) where {FT}

Constructor for the Point domain using keyword arguments.

All other ClimaLand domains rely on default comms set internally by ClimaCore. However, the Point space is unique in this context, and does not have the same default defined in ClimaCore. Because of this, we set the default here in ClimaLand. In long term, we will repeat the same for all ClimaLand domains and not rely on any internal defaults set in ClimaCore.

struct SphericalShell{FT} <: AbstractDomain{FT}
    radius::FT
    depth::FT
    dz_tuple::Union{Tuple{FT, FT}, Nothing}
    nelements::Tuple{Int, Int}
    npolynomial::Int
end

A struct holding the necessary information to construct a domain, a mesh, a 2d spectral element space (non-radial directions) x a 1d finite difference space (radial direction), and the resulting coordinate field.

space is a NamedTuple holding the surface space (in this case, the top face space) and the center space for the subsurface. These are stored using the keys :surface and :subsurface.

Fields

• radius: The radius of the shell

• depth: The radial extent of the shell

• dz_tuple: Tuple for mesh stretching specifying target (dzbottom, dztop) (m). If nothing, no stretching is applied.

• nelements: The number of elements to be used in the non-radial and radial directions

• npolynomial: The polynomial order to be used in the non-radial directions

• space: A NamedTuple of associated ClimaCore spaces: in this case, the surface space and subsurface center space

• fields: Fields associated with the coordinates of the domain that are useful to store

SphericalShell(;
    radius::FT,
    depth::FT,
    nelements::Tuple{Int, Int},
    npolynomial::Int,
    dz_tuple::Union{Tuple{FT, FT}, Nothing} = nothing,
    comms_ctx = ClimaComms.SingletonCommsContext(),
) where {FT}

Outer constructor for the SphericalShell domain, using keyword arguments.

Using ClimaCore tools, the coordinate mesh can be stretched such that the top of the domain has finer resolution than the bottom of the domain. In order to activate this, a tuple with the target dzbottom and dztop should be passed via keyword argument. The default is uniform spacing. Please note that the dz_tuple you supply may not be compatible with the depth/nelements chosen, in which case you may need to choose different values.

struct SphericalSurface{FT} <: AbstractDomain{FT}
    radius::FT
    nelements::Tuple{Int, Int}
    npolynomial::Int
end

A struct holding the necessary information to construct a domain, a mesh, a 2d spectral element space (non-radial directions) and the resulting coordinate field.

space is a NamedTuple holding the surface space (in this case, the entire SphericalSurface space).

Fields

• radius: The radius of the surface

• nelements: The number of elements to be used in the non-radial directions

• npolynomial: The polynomial order to be used in the non-radial directions

• space: A NamedTuple of associated ClimaCore spaces: in this case, the surface (SphericalSurface) space

SphericalSurface(;
    radius::FT,
    nelements::Int
    npolynomial::Int,
    comms_ctx = ClimaComms.SingletonCommsContext(),
) where {FT}

Outer constructor for the SphericalSurface domain, using keyword arguments.

bottom_center_to_surface(val)

When val is a scalar (e.g. a single float or struct), returns val.

bottom_center_to_surface(center_field::ClimaCore.Fields.Field)

Creates and returns a ClimaCore.Fields.Field defined on the space corresponding to the bottom surface of the space on which center_field is defined, with values equal to the those at the level of the bottom center.

For example, given a center_field defined on 1D center finite difference space, this would return a field defined on the Point space of the bottom surface of the column. The value would be the value of the original center_field at the bottommost location. Given a center_field defined on a 3D extruded center finite difference space, this would return a 2D field corresponding to the bottom surface, with values equal to the bottommost level.

coordinates(domain::AbstractDomain)

Returns the coordinate fields for the domain as a NamedTuple.

The returned coordinates are stored with keys :surface, :subsurface, e.g. as relevant for the domain.

get_additional_domain_fields(subsurface_space)

A helper function which returns additional fields corresponding to ClimaLand domains which have a subsurface_space (Column, HybridBox, SphericalShell); these fields are the center coordinates of the subsurface space, the spacing between the top center and top surface and bottom center and bottom surface, as well as the field corresponding to the surface height z.

We allocate these once, upon domain construction, so that they are accessible during the simulation.

get_Δz(z::ClimaCore.Fields.Field)

A function to return a tuple containing the distance between the top boundary and its closest center, and the bottom boundary and its closest center, both as Fields.

linear_interpolation_to_surface!(sfc_field, center_field, z, Δz_top)

Linearly interpolate the center field center_field to the surface defined by the top face coordinate of z with a center to face distance Δz_top in the first layer; updates the sfc_field on the surface (face) space in place.

obtain_face_space(cs::ClimaCore.Spaces.AbstractSpace)

Returns the face space, if applicable, for the center space cs.

obtain_face_space(cs::ClimaCore.Spaces.CenterExtrudedFiniteDifferenceSpace)

Returns the face space for the CenterExtrudedFiniteDifferenceSpace cs.

obtain_face_space(cs::ClimaCore.Spaces.CenterFiniteDifferenceSpace)

Returns the face space corresponding to the CenterFiniteDifferenceSpace cs.

obtain_surface_domain(d::AbstractDomain) where {FT}

Default method throwing an error; any domain with a corresponding domain should define a new method of this function.

obtain_surface_domain(c::Column{FT}) where {FT}

Returns the Point domain corresponding to the top face (surface) of the Column domain c.

obtain_surface_domain(b::HybridBox{FT}) where {FT}

Returns the Plane domain corresponding to the top face (surface) of the HybridBox domain b.

obtain_surface_domain(s::SphericalShell{FT}) where {FT}

Returns the SphericalSurface domain corresponding to the top face (surface) of the SphericalShell domain s.

obtain_surface_space(cs::ClimaCore.Spaces.AbstractSpace)

Returns the surface space, if applicable, for the center space cs.

obtain_surface_space(cs::ClimaCore.Spaces.CenterExtrudedFiniteDifferenceSpace)

Returns the horizontal space for the CenterExtrudedFiniteDifferenceSpace cs.

obtain_surface_space(cs::ClimaCore.Spaces.CenterFiniteDifferenceSpace)

Returns the top level of the face space corresponding to the CenterFiniteDifferenceSpace cs.

top_center_to_surface(val)

When val is a scalar (e.g. a single float or struct), returns val.

top_center_to_surface(center_field::ClimaCore.Fields.Field)

Creates and returns a ClimaCore.Fields.Field defined on the space corresponding to the surface of the space on which center_field is defined, with values equal to the those at the level of the top center.

For example, given a center_field defined on 1D center finite difference space, this would return a field defined on the Point space of the surface of the column. The value would be the value of the oroginal center_field at the topmost location. Given a center_field defined on a 3D extruded center finite difference space, this would return a 2D field corresponding to the surface, with values equal to the topmost level.

top_face_to_surface(face_field::ClimaCore.Fields.Field, surface_space)

Creates and returns a ClimaCore.Fields.Field defined on the space corresponding to the surface of the space on which face_field is defined, with values equal to the those at the level of the top face.

Given a face_field defined on a 3D extruded face finite difference space, this would return a 2D field corresponding to the surface, with values equal to the topmost level.

AbstractSnowModel{FT} <: ClimaLand.AbstractExpModel{FT}

Defines a new type of abstract explicit model for snow modeling. Currently, the only supported concrete example is called SnowModel and is used as a bulk snow model.

struct SnowModel{
    FT,
    PS <: SnowParameters{FT},
    ATM <: AbstractAtmosphericDrivers{FT},
    RAD <: AbstractRadiativeDrivers{FT},
    D,
} <: AbstractSnowModel{FT}

A container/type for the bulk snow model, based on the UEB snow model of Tarboton et al. (1995) and Tarboton and Luce (1996).

SnowParameters{FT <: AbstractFloat, PSE}

A struct for storing parameters of the SnowModel.

Note that in our current implementation of runoff, a physical timescale is required and computed using Ksat and the depth of the snow. For shallow snowpacks, this will fall below the timestep of the model. For that reason, we pass the timestep of the model as a parameter, and take the larger of the timestep and the physical timescale as the value used in the model. Future implementations will revisit this.

• ρ_snow: Density of snow (kg/m^3)

• z_0m: Roughness length over snow for momentum (m)

• z_0b: Roughness length over snow for scalars (m)

• α_snow: Albedo of snow (unitless)

• ϵ_snow: Emissivity of snow (unitless)

• θ_r: Volumetric holding capacity of water in snow (unitless)

• Ksat: Hydraulic conductivity of wet snow (m/s)

• κ_ice: Thermal conductivity of ice (W/m/K)

• Δt: Timestep of the model (s)

• ρcD_g: Areal specific heat of ground interacting with snow (J/m^2/K)

• earth_param_set: Clima-wide parameters

SnowParameters{FT}(Δt; ρsnow = FT(200), z0m = FT(0.0024), z0b = FT(0.00024), αsnow = FT(0.8), ϵsnow = FT(0.99), θr = FT(0.08), Ksat = FT(1e-3), κice = FT(2.21), ρcDg = FT(3.553e5), earthparamset::PSE) where {FT, PSE}

An outer constructor for SnowParameters which supplies defaults for all arguments but earth_param_set.

clip_dSdt(S, dSdt, Δt)

A helper function which clips the tendency of S such that S will not become negative.

clip_dUdt(U, S, dUdt, dSdt, Δt)

A helper function which clips the tendency of U such that U will not become negative, and which ensures that if S goes to zero in a step, U will too.

compute_energy_runoff(S::FT, q_l::FT, T::FT, parameters) where {FT}

Computes the rate of change in the snow water equivalent S due to loss of liquid water (runoff) from the snowpack.

Runoff occurs as the snow melts and exceeds the water holding capacity.

energy_from_T_and_swe(S::FT, T::FT, parameters) where {FT}

A helper function for compute the snow energy per unit area, given snow water equivalent S, bulk temperature T, and snow model parameters.

If T = Tfreeze, we return the energy as if ql = 0.

energy_from_q_l_and_swe(S::FT, q_l::FT, parameters) where {FT}

A helper function for compute the snow energy per unit area, given snow water equivalent S, liquid fraction q_l, and snow model parameters.

Note that liquid water can only exist at the freezing point in this model, so temperature is not required as an input.

maximum_liquid_mass_fraction(T::FT, ρ_snow::FT, parameters::SnowParameters{FT}) where {FT}

Computes the maximum liquid water mass fraction, given the bulk temperature of the snow T, the density of the snow ρ_snow, and parameters.

runoff_timescale(z::FT, Ksat::FT, Δt::FT) where {FT}

Computes the timescale for liquid water to percolate and leave the snowpack, given the depth of the snowpack z and the hydraulic conductivity Ksat.

snow_bulk_temperature(U::FT,
                      SWE::FT,
                      q_l::FT,
                      parameters::SnowParameters{FT}) where {FT}

Computes the bulk snow temperature from the snow water equivalent SWE, energy per unit area U, liquid water mass fraction ql, and specific heat capacity cs, along with other needed parameters.

If there is no snow (U = SWE = 0), the bulk temperature is the reference temperature, which is 273.16K.

snow_depth(SWE::FT, ρ_snow::FT, ρ_l::FT) where {FT}

Returns the snow depth given SWE, snow density ρsnow, and the density of liquid water ρl.

snow_liquid_mass_fraction(U::FT, SWE::FT, parameters::SnowParameters{FT}) where {FT}

Computes the snow liquid water mass fraction, given the snow water equivalent SWE, snow energy per unit area U, and other needed parameters.

snow_surface_temperature(T::FT) where {FT}

Returns the snow surface temperature assuming it is the same as the bulk temperature T.

snow_thermal_conductivity(ρ_snow::FT,
                     parameters::SnowParameters{FT},
                     ) where {FT}

Computes the thermal conductivity, given the density of the snow, according to Equation 5.33 from Bonan's textbook, which in turn is taken from Jordan (1991).

specific_heat_capacity(q_l::FT,
                       parameters::SnowParameters{FT}
                       ) where {FT}

Computes the specific heat capacity of the snow, neglecting any contribution from air in the pore spaces, given the liquid water mass fraction q_l and other parameters.

volumetric_internal_energy_liq(FT, parameters)

Computes the volumetric internal energy of the liquid water in the snowpack.

Since liquid water can only exist in the snowpack at the freezing point, this is a constant.

auxiliary_vars(::SnowModel)

Returns the auxiliary variable names for the snow model. These include the mass fraction in liquid water (q_l, unitless), the bulk temperature (T, K), the surface temperature (T_sfc, K), the SHF, LHF, and vapor flux (turbulent_fluxes.shf, etc), the net radiation (R_n, J/m^2/s), the energy flux in liquid water runoff (energy_runoff, J/m^2/s), the water volume in runoff (water_runoff, m/s), and the total energy and water fluxes applied to the snowpack.

ClimaLand.get_drivers(model::SnowModel)

Returns the driver variable symbols for the SnowModel.

prognostic_domain_names(::SnowModel)

Returns the prognostic variable domain names of the snow model; both snow water equivalent and energy per unit area are modeling only as a function of (x,y), and not as a function of depth. Therefore their domain name is ":surface".

prognostic_types(::SnowModel{FT})

Returns the prognostic variable types of the snow model; both snow water equivalent and energy per unit area are scalars.

prognostic_vars(::SnowModel)

Returns the prognostic variable names of the snow model.

For this model, we track the snow water equivalent S [m] and the energy per unit area U [J/m^2] prognostically.

surface_albedo(model::SnowModel, Y, p)

A helper function which computes and returns the snow albedo.

surface_emissivity(model::SnowModel, Y, p)

A helper function which computes and returns the snow emissivity.

ClimaLand.surface_height(
    model::SnowModel{FT},
    Y,
    p,
) where {FT}

Returns the surface height of the Snow model.

ClimaLand.surface_specific_humidity(model::BucketModel, Y, p)

Computes and returns the specific humidity over snow as a weighted fraction of the saturated specific humidity over liquid and frozen water.

ClimaLand.surface_temperature(model::SnowModel, Y, p)

a helper function which returns the surface temperature for the snow model, which is stored in the aux state.

PondModel{FT, D, R} <: AbstractSurfaceWaterModel{FT}

A stand-in model for models like the snow or river model. In standalone mode, a prescribed soil infiltration rate and precipitation rate control the rate of change of the pond height variable η via an ODE. In integrated LSM mode, the infiltration into the soil will be computed via a different method, and also be applied as a flux boundary condition for the soil model.

• domain: The domain for the pond model

• runoff: The runoff model for the pond model

PrescribedRunoff{F1 <: Function, F2 <: Function} <:  AbstractSurfaceRunoff

The required input for driving the simple pond model: precipitation, as a function of time, soil effective saturation at a depth Δz below the surface, as a function of time, and soil parameters, which affect infiltration.

struct BucketModel{
     FT,
     PS <: BucketModelParameters{FT},
     ATM <: AbstractAtmosphericDrivers{FT},
     RAD <: AbstractRadiativeDrivers{FT},
     D,
 } <: AbstractBucketModel{FT}

Concrete type for the BucketModel, which store the model domain and parameters, as well as the necessary atmosphere and radiation fields for driving the model.

• parameters: Parameters required by the bucket model

• atmos: The atmospheric drivers: Prescribed or Coupled

• radiation: The radiation drivers: Prescribed or Coupled

• domain: The domain of the model

BucketModel(; parameters::BucketModelParameters{FT, PSE}, domain::D, atmosphere::ATM, radiation::RAD, ) where {FT, PSE, ATM, RAD, D<: ClimaLand.Domains.AbstractDomain}

An outer constructor for the BucketModel, which enforces the constraints:

1. The bucket model domain is of type <: ClimaLand.Domains.AbstractDomain
2. Using an albedo read from a lat/lon file requires a global run.

struct BucketModelParameters{
    FT <: AbstractFloat,
    PSE,
}

Container for holding the parameters of the bucket model.

• κ_soil: Conductivity of the soil (W/K/m); constant

• ρc_soil: Volumetric heat capacity of the soil (J/m^3/K); constant

• albedo: Albedo Model

• σS_c: Critical σSWE amount (m) where surface transitions from to snow-covered

• f_snow: Fraction of critical amount of snow at which sublimation β begins to decay to zero (unitless)

• W_f: Capacity of the land bucket (m)

• f_bucket: Fraction of bucket capacity at which evaporation β begins to decay to zero (unitless)

• p: Exponent used in β decay (unitless)

• z_0m: Roughness length for momentum (m)

• z_0b: Roughness length for scalars (m)

• τc: τc timescale on which snow melts

• earth_param_set: Earth Parameter set; physical constants, etc

PrescribedBaregroundAlbedo{FT, F <: ClimaCore.Fields.Field} <: AbstractBucketAlbedoModel

An albedo model where the static snow-free bareground albedo is prescribed as a function of space or using data from a file, and the land surface albedo is computed each timestep as a linear combination of the snow albedo and the bareground albedo, following the SLIM model (Lague et al 2019).

 PrescribedBaregroundAlbedo{FT}(α_snow::FT,
                                surface_space::ClimaCore.Spaces.AbstractSpace;
                                varnames = ["sw_alb"],
                                albedo_file_path::AbstractString = ClimaLand.Artifacts.bareground_albedo_dataset_path(),
                                ) where{FT}

An outer constructor for the PrescribedBaregroundAlbedo model which uses data from a file obtained from a net cdf file for the bareground albedo.

This particular method can only be used with global runs.

 PrescribedBaregroundAlbedo{FT}(α_snow::FT,
                                α_bareground_func::Function,
                                surface_space::ClimaCore.Spaces.AbstractSpace
                                ) where {FT}

An outer constructor for the PrescribedBaregroundAlbedo model which uses an analytic function of the coordinates to compute αbareground on the model `surfacespace`.

This particular method can be used with site level or global runs.

PrescribedSurfaceAlbedo{FT, TV <: AbstractTimeVaryingInput}
                   <: AbstractBucketAlbedoModel

An albedo model where the albedo of different surface types is specified. Albedo is specified via a NetCDF file which is a function of time and covers all surface types (soil, vegetation, snow, etc). This albedo type changes over time according to the input file.

Note that this option should only be used with global simulations, i.e. with a ClimaLand.LSMSphericalShellDomain.

PrescribedSurfaceAlbedo{FT}(
    date_ref::Union{DateTime, DateTimeNoLeap},
    t_start,
    Space::ClimaCore.Spaces.AbstractSpace;
    get_infile = ClimaLand.Artifacts.cesm2_albedo_dataset_path,
    varname = "sw_alb"
) where {FT}

Constructor for the PrescribedSurfaceAlbedo struct. The varname must correspond to the name of the variable in the NetCDF file retrieved by the get_infile function. get_infile uses ArtifactWrappers.jl to return a path to the data file and download the data if it doesn't already exist on the machine. The input data file must have a time component.

bareground_albedo_dataset_path()

Triggers the download of the average bareground land albedo dataset, if not already downloaded, using Julia Artifacts, and returns the path to this file.

This dataset does not contain a time component.

beta_factor(W::FT, σS::FT, fW_f::FT, fσS_c::FT, p::FT) where {FT}

Computes the beta factor which scales the evaporation/sublimation from the potential rate. The beta factor is given by:

β = (x/xc)^p x < xc 1 otherwise

where x = W and xc = fbucket * Wf for the bucket, and x = σS and xc = fsnow *σSc for snow.

cesm2_albedo_dataset_path()

Triggers the download of the CESM2 land albedo dataset, if not already downloaded, using Julia Artifacts, and returns the path to this file.

This dataset contains monthly albedo data from 15/01/1850 to 15/12/2014.

infiltration_at_point(W::FT, M::FT, P::FT, E::FT, W_f::FT)::FT where {FT <: AbstractFloat}

Returns the infiltration given the current water content of the bucket W, the snow melt volume flux M, the precipitation volume flux P, the liquid evaporative volume flux E, and the bucket capacity W_f.

Extra inflow when the bucket is at capacity runs off. Note that all fluxes are positive if towards the atmosphere.

next_albedo!(next_α_sfc,
             model_albedo::PrescribedBaregroundAlbedo{FT},
             parameters, Y, p, t)

Update the surface albedo for time t: the albedo is calculated by linearly interpolating between the albedo of snow and of the bareground surface, based on the snow water equivalent S relative to the parameter S_c. The linear interpolation is taken from Lague et al 2019.

Note that if our snowcoverfraction function was smoothly varying, the albedo would simply be σαsnow + (1-σ)αbareground. Since we cannot support snow cover fractions that are not a heaviside function, we have a small inconsistency for 0 < σS < eps(FT) where the snow cover fraction is zero, but there is a small contribution of snow to the albedo.

next_albedo!(next_α_sfc, model_albedo::PrescribedSurfaceAlbedo{FT}, parameters, Y, p, t)

Update the surface albedo for time t: for a file containing surface albedo information over time, this reads in the value for time t.

partition_snow_surface_fluxes(
    σS::FT,
    T_sfc::FT,
    τ::FT,
    snow_cover_fraction::FT,
    E::FT,
    F_sfc::FT,
    _LH_f0::FT,
    _T_freeze::FT,
) where{FT}

Partitions the surface fluxes in a flux for melting snow, a flux for sublimating snow, and a ground heat flux. Fluxes are given over snow covered area and multiplied by snow cover fraciton elsewhere.

All fluxes are positive if they are in the direction from land towards the atmosphere.

saturation_specific_humidity(T::FT, σS::FT, ρ_sfc::FT, thermo_parameters::TPE)::FT where {FT, TPE}

Computes the saturation specific humidity for the land surface, over ice if snow is present (σS>0), and over water for a snow-free surface.

β(x::FT, x_c::FT, p::FT) where {FT}

Returns the coefficient which scales the evaporation or sublimation rate based on the bucket water or snow levels.

Over ground, x_c is a default of 75% of the capacity, since the ground evaporation rate remains near the potential rate until water has dropped sufficiently.

Over snow, x_c taken a default of 10% of the value around which snow starts to become patchy, since snow sublimates at the potential rate in general. We use the β function mainly to damp sublimation to zero for vanishing snowpacks. Note that the snow cover fraction returns zero for 0 < σS < eps(FT) while this function returns a nonzero function.

make_compute_exp_tendency(model::BucketModel{FT}) where {FT}

Creates the computeexptendency! function for the bucket model.

make_update_aux(model::BucketModel{FT}) where {FT}

Creates the update_aux! function for the BucketModel.

surface_albedo(model::BucketModel, Y, p)

Returns the bulk surface albedo, which gets updated in update_aux via next_albedo.

ClimaLand.surface_emissivity(model::BucketModel{FT}, Y, p)

Returns the emissivity for the bucket model (1.0).

ClimaLand.surface_evaporative_scaling(model::BucketModel, Y, p)

a helper function which computes and returns the surface evaporative scaling factor for the bucket model.

ClimaLand.surface_height(model::BucketModel, Y, p)

a helper function which returns the surface height for the bucket model, which is zero currently.

ClimaLand.surface_specific_humidity(model::BucketModel, Y, p)

a helper function which returns the surface specific humidity for the bucket model, which is stored in the aux state.

ClimaLand.surface_temperature(model::BucketModel, Y, p)

a helper function which returns the surface temperature for the bucket model, which is stored in the aux state.

 AbstractAtmosphericDrivers{FT}

An abstract type of atmospheric drivers of land models.

AbstractBC

An abstract type for types of boundary conditions, which will include prescribed functions of space and time as Dirichlet conditions or Neumann conditions, in addition to other convenient conditions.

AbstractBoundary

An abstract type to indicate which boundary we are doing calculations for. Currently, we support the top boundary (TopBoundary) and bottom boundary (BottomBoundary).

 AbstractClimaLandDrivers{FT <: AbstractFloat}

An abstract type of radiative drivers of land models.

AbstractExpModel{FT} <: AbstractModel{FT}

An abstract type for models which must be treated explicitly. This inherits all the default function definitions from AbstractModel, as well as a make_imp_tendency default.

AbstractImExModel{FT} <: AbstractModel{FT}

An abstract type for models which must be treated implicitly (and which may also have tendency terms that can be treated explicitly). This inherits all the default function definitions from AbstractModel, as well as make_imp_tendency and make_compute_imp_tendency defaults.

 AbstractLandModel{FT} <: AbstractModel{FT}

An abstract type for all land model types, which are used to simulated multiple land surface components as a single system. Standalone component runs do not require this interface and it should not be used for that purpose.

Many methods taking an argument of type AbstractLandModel are extensions of functions defined for AbstractModels. There are default methods that apply for all AbstractLandModels, including make_update_aux, make_exp_tendency, make_imp_tendency, make_compute_exp_tendency, make_compute_imp_tendency, initialize_prognostic, initialize_auxiliary, initialize, and coordinates.

Methods which dispatch on a specific type of AbstractLandModel include any function involving interactions between components, as these interactions depend on the components in the land model and the versions of these component models being used.

abstract type AbstractModel{FT <: AbstractFloat}

An abstract type for all models.

 AbstractRadiativeDrivers{FT}

An abstract type of radiative drivers of land models.

AbstractSource{FT <: AbstractFloat}

An abstract type for types of source terms.

BottomBoundary{} <: AbstractBoundary{}

A simple object which should be passed into a function to indicate that we are considering the bottom boundary.

CanopyRadiativeFluxes{FT} <: AbstractRadiativeDrivers{FT}

A struct used to compute radiative fluxes in land surface models, indicating that canopy absorption and emission is taken into account when computing radiation at the surface of the soil or snow.

The only other alternative at this stage is ClimaLand.PrescribedRadiativeFluxes, where the prescribed downwelling short and longwave radiative fluxes are used directly, without accounting for the canopy. There is a different method of the function soil_boundary_fluxes! in this case.

CoupledAtmosphere{FT} <: AbstractAtmosphericDrivers{FT}

To be used when coupling to an atmosphere model.

CoupledRadiativeFluxes{FT} <: AbstractRadiativeDrivers{FT}

To be used when coupling to an atmosphere model.

DriverAffect{updateType, updateFType}

This struct is used by DriverUpdateCallback to update the values of p.drivers at different timesteps specified by updateat, using the function updatefunc which takes as arguments (p, t).

(affect!::DriverAffect)(integrator)

This function is used by DriverUpdateCallback to perform the updating.

ImplicitEquationJacobian{M, S}

A struct containing the necessary information for constructing a block Jacobian matrix used for implicit timestepping.

matrix is a block matrix containing one block on the diagonal for each variable in the model. solver is a diagonal solver because our matrix is block diagonal.

Note that the diagonal, upper diagonal, and lower diagonal entry values are stored in this struct and updated in place.

ImplicitEquationJacobian(Y::ClimaCore.Fields.FieldVector)

Outer constructor for the ImplicitEquationJacobian Jacobian matrix struct.

For variables that will be stepped implicitly, the Jacobian matrix is a tridiagonal matrix. For variables that will be stepped explicitly, the Jacobian matrix is a negative identity matrix.

To run a model with one or more prognostic variables stepped implicitly, the Jacobian matrix must be constructed and passed to the solver. All implicitly-stepped variables of the model should be added to the implicit_names tuple, and any explicitly-stepped variables should be added to the explicit_names tuple.

struct LandHydrology{
    FT,
    SM <: Soil.AbstractSoilModel{FT},
    SW <: Pond.AbstractSurfaceWaterModel{FT},
} <: AbstractLandModel{FT}

A concrete type of land model used for simulating systems with a soil and surface water component.

• soil: The soil model

• surface_water: The surface water model

LandHydrology{FT}(;
    land_args::NamedTuple = (;),
    soil_model_type::Type{SM},
    soil_args::NamedTuple = (;),
    surface_water_model_type::Type{SW},
    surface_water_args::NamedTuple = (;),
) where {
    FT,
    SM <: Soil.AbstractSoilModel{FT},
    SW <: Pond.AbstractSurfaceWaterModel{FT},
}

A constructor for the LandHydrology model, which takes in the concrete model type and required arguments for each component, constructs those models, and constructs the LandHydrology from them.

Each component model is constructed with everything it needs to be stepped forward in time, including boundary conditions, source terms, and interaction terms.

Additional arguments, like parameters and driving atmospheric data, are passed in as land_args.

struct LandSoilBiogeochemistry{
    FT,
    SEH <: Soil.EnergyHydrology{FT},
    SB <: Soil.Biogeochemistry.SoilCO2Model{FT},
} <: AbstractLandModel{FT}

A concrete type of land model used for simulating systems with a soil energy, hydrology, and biogeochemistry component.

• soil: The soil model

• soilco2: The biochemistry model

LandSoilBiogeochemistry{FT}(;
    soil_args::NamedTuple = (;),
    biogeochemistry_args::NamedTuple = (;),
) where {FT}

A constructor for the LandSoilBiogeochemistry model, which takes in the required arguments for each component, constructs those models, and constructs the LandSoilBiogeochemistry from them.

Each component model is constructed with everything it needs to be stepped forward in time, including boundary conditions, source terms, and interaction terms.

Additional arguments, like parameters and driving atmospheric data, can be passed in as needed.

PrescribedAtmosphere{FT, CA, DT} <: AbstractAtmosphericDrivers{FT}

Container for holding prescribed atmospheric drivers and other information needed for computing turbulent surface fluxes when driving land models in standalone mode.

The default CO2 concentration is a constant as a function of time, equal to 4.2e-4 mol/mol.

Since not all models require co2 concentration, the default for that is nothing.

• liquid_precip: Precipitation (m/s) function of time: positive by definition

• snow_precip: Snow precipitation (m/s) function of time: positive by definition

• T: Prescribed atmospheric temperature (function of time) at the reference height (K)

• u: Prescribed wind speed (function of time) at the reference height (m/s)

• q: Prescribed specific humidity (function of time) at the reference height (_)

• P: Prescribed air pressure (function of time) at the reference height (Pa)

• c_co2: CO2 concentration in atmosphere (mol/mol)

• ref_time: Reference time - the datetime corresponding to t=0 for the simulation

• h: Reference height (m), relative to surface elevation

• gustiness: Minimum wind speed (gustiness; m/s)

• thermo_params: Thermodynamic parameters

PrescribedPrecipitation{FT, LP} <: AbstractAtmosphericDrivers{FT}

Container for holding prescribed precipitation driver for models which only require precipitation (RichardsModel).

• liquid_precip: Precipitation (m/s) function of time: positive by definition

PrescribedRadiativeFluxes{FT, SW, LW, DT, T} <: AbstractRadiativeDrivers{FT}

Container for the prescribed radiation functions needed to drive land models in standalone mode.

• SW_d: Downward shortwave radiation function of time (W/m^2): positive indicates towards surface

• LW_d: Downward longwave radiation function of time (W/m^2): positive indicates towards surface

• ref_time: Reference time - the datetime corresponding to t=0 for the simulation

• θs: Sun zenith angle, in radians

 PrescribedSoilOrganicCarbon{FT}

A type for prescribing soil organic carbon.

• soc: Soil organic carbon, function of time and space: kg C/m^3

PrognosticRunoff <: Pond.AbstractSurfaceRunoff

Concrete type of Pond.AbstractSurfaceRunoff for use in LSM models, where precipitation is passed in, but infiltration is computed prognostically.

This is paired with Soil.RunoffBC: both are used at the same time, ensuring the infiltration used for the boundary condition of soil is also used to compute the runoff for the surface water.

 PrognosticSoil{FT} <: AbstractSoilDriver

Concrete type of AbstractSoilDriver used for dispatch in cases where both a canopy model and soil model are run.

• α_PAR: Soil albedo for PAR

• α_NIR: Soil albedo for NIR

RootExtraction{FT} <: Soil.AbstractSoilSource{FT}

Concrete type of Soil.AbstractSoilSource, used for dispatch in an LSM with both soil and plant hydraulic components.

This is paired with the source term Canopy.PrognosticSoil:both are used at the same time, ensuring that the water flux into the roots is extracted correctly from the soil.

RunoffBC <: Soil.AbstractSoilBC

Concrete type of Soil.AbstractSoilBC for use in LSM models, where precipitation is passed in, but infiltration is computed prognostically. This infiltration is then used to set an upper boundary condition for the soil.

This is paired with Pond.PrognosticRunoff: both are used at the same time, ensuring that the infiltration used for the boundary condition of soil is also used to compute the runoff for the surface water.

SavingAffect{saveatType}

This struct is used by NonInterpSavingCallback to fill saved_values with values of p at various timesteps. The saveiter field allows us to allocate saved_values before the simulation and fill it during the run, rather than pushing to an initially empty structure.

(affect!::SavingAffect)(integrator)

This function is used by NonInterpSavingCallback to perform the saving.

struct SoilCanopyModel{
    FT,
    MM <: Soil.Biogeochemistry.SoilCO2Model{FT},
    SM <: Soil.EnergyHydrology{FT},
    VM <: Canopy.CanopyModel{FT},
} <: AbstractLandModel{FT}
    "The soil microbe model to be used"
    soilco2::MM
    "The soil model to be used"
    soil::SM
    "The canopy model to be used"
    canopy::VM
end

A concrete type of land model used for simulating systems with a canopy and a soil component.

• soilco2: The soil microbe model to be used

• soil: The soil model to be used

• canopy: The canopy model to be used

SoilCanopyModel{FT}(;
    soilco2_type::Type{MM},
    soilco2_args::NamedTuple = (;),
    land_args::NamedTuple = (;),
    soil_model_type::Type{SM},
    soil_args::NamedTuple = (;),
    canopy_component_types::NamedTuple = (;),
    canopy_component_args::NamedTuple = (;),
    canopy_model_args::NamedTuple = (;),
    ) where {
        FT,
        SM <: Soil.EnergyHydrology{FT},
        MM <: Soil.Biogeochemistry.SoilCO2Model{FT},
        }

A constructor for the SoilCanopyModel, which takes in the concrete model type and required arguments for each component, constructs those models, and constructs the SoilCanopyModel from them.

Each component model is constructed with everything it needs to be stepped forward in time, including boundary conditions, source terms, and interaction terms.

TopBoundary{} <: AbstractBoundary{}

A simple object which should be passed into a function to indicate that we are considering the top boundary.

PlantHydraulics.root_water_flux_per_ground_area!(
    fa::ClimaCore.Fields.Field,
    s::PrognosticSoil,
    model::Canopy.PlantHydraulics.PlantHydraulicsModel{FT},
    Y::ClimaCore.Fields.FieldVector,
    p::NamedTuple,
    t,
)

An extension of the PlantHydraulics.root_water_flux_per_ground_area! function, which returns the net flux of water between the roots and the soil, per unit ground area, when both soil and plant hydraulics are modeled prognostically. This is for use in an LSM.

It is computed by summing the flux of water per ground area between roots and soil at each soil layer.

Canopy.canopy_radiant_energy_fluxes!(p::NamedTuple,
                                     s::PrognosticSoil{F},
                                     canopy,
                                     radiation::PrescribedRadiativeFluxes,
                                     earth_param_set::PSE,
                                     Y::ClimaCore.Fields.FieldVector,
                                     t,
                                    ) where {FT, 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.

root_energy_flux_per_ground_area!(
    fa_energy::ClimaCore.Fields.Field,
    s::PrognosticSoil{F},
    model::Canopy.AbstractCanopyEnergyModel{FT},
    Y::ClimaCore.Fields.FieldVector,
    p::NamedTuple,
    t,
) where {FT, F}

A method computing the energy flux associated with the root-soil water flux, which returns 0 in cases where we do not need to track this quantity: in this case, when the canopy energy is tracked, but we are using a PrescribedSoil model (non-prognostic soil model).

Note that this energy flux is not typically included in land surface models. We account for it when the soil model is prognostic because the soil model includes the energy in the soil water in its energy balance; therefore, in order to conserve energy, the canopy model must account for it as well.

Domains.coordinates(model::AbstractLandModel)

Returns a NamedTuple of the unique set of coordinates for the LSM model, where the unique set is taken over the coordinates of all of the subcomponents.

For example, an LSM with a single layer snow model, multi-layer soil model, and canopy model would have a coordinate set corresponding to the coordinates of the surface (snow), the subsurface coordinates (soil) and the coordinates of the surface (canopy). This would return the coordinates of the surface and subsurface. These are distinct because the subsurface coordinates correspond to the centers of the layers, while the surface corresponds to the top face of the domain.

DriverUpdateCallback(updateat::Vector{FT}, updatefunc)

Constructs a DiscreteCallback which updates the cache p.drivers at each time specified by updateat, using the function updatefunc which takes as arguments (p,t).

NonInterpSavingCallback(saved_values, saveat::Vector{FT})

Constructs a DiscreteCallback which saves the time and cache p at each time specified by saveat. The first argument must be a named tuple containing t and saveval, each having the same length as saveat.

Important: The times in saveat must be times the simulation is evaluated at for this function to work.

Note that unlike SciMLBase's SavingCallback, this version does not interpolate if a time in saveat is not a multiple of our timestep. This function also doesn't work with adaptive timestepping.

function Pond.surface_runoff(
    runoff::PrognosticRunoff,
    Y::ClimaCore.Fields.FieldVector,
    p::NamedTuple,
    t,
)

Extension of the Pond.surface_runoff function, which computes the surface runoff, for use in an LSM when the runoff is determined prognostically.

soil_moisture(driver::PrognosticSoil, p, Y, t, z)

Returns the volumetric liquid fraction, computed by the soil model from the prognostic liquid and ice fractions.

soil_temperature(driver::PrognosticSoil, p, Y, t, z)

Returns the prognostic soil temperature.

soil_boundary_fluxes!(
    bc::AtmosDrivenFluxBC{<:PrescribedAtmosphere, <:CanopyRadiativeFluxes},
    boundary::ClimaLand.TopBoundary,
    soil::EnergyHydrology{FT},
    Δz,
    Y,
    p,
    t,
) where {FT}

A method of ClimaLand.Soil.soil_boundary_fluxes! which is used for integrated land surface models; this computes and returns the net energy and water flux at the surface of the soil for use as boundary conditions.

add_drivers_to_cache(p, model::AbstractModel)

Adds driver variables to the cache; the default is not add anything, consistent with the default of no additional driver variables in the cache.

add_drivers_to_cache(p::NamedTuple, model::AbstractModel, coords)

Creates the driver variable NamedTuple (atmospheric and radiative forcing, etc), and merges it into p under the key drivers. If no driver variables are required, p is returned unchanged.

add_dss_buffer_to_aux(p::NamedTuple, domain::Domains.AbstractDomain)

Fallback method for add_dss_buffer_to_aux which does not add a dss buffer.

add_dss_buffer_to_aux(
    p::NamedTuple,
    domain::Union{Domains.HybridBox, Domains.SphericalShell},
)

Adds a 2d and 3d dss buffer corresponding to domain.space to p with the names dss_buffer_3d, and dss_buffer_2d.

This buffer is added so that we preallocate memory for the dss step and do not allocate it at every timestep. We use a name which specifically denotes that the buffer is on a 3d space. This is because some models require both a buffer on the 3d space as well as on the surface 2d space, e.g. in the case when they have prognostic variables that are only defined on the surface space.

add_dss_buffer_to_aux(
    p::NamedTuple,
    domain::Union{Domains.Plane, Domains.SphericalSurface},
)

Adds a dss buffer corresponding to domain.space to p with the name dss_buffer_2d, appropriate for a 2D domain.

This buffer is added so that we preallocate memory for the dss step and do not allocate it at every timestep. We use a name which specifically denotes that the buffer is on a 2d space. This is because some models require both a buffer on the 3d space as well as on the surface 2d space, e.g. in the case when they have prognostic variables that are only defined on the surface space.

auxiliarydomainnames(m::AbstractModel)

Returns the domain names for the auxiliary variables in the form of a tuple.

Examples: (:surface, :surface, :subsurface).

auxiliary_types(m::AbstractModel{FT}) where {FT}

Returns the auxiliary variable types for the model in the form of a tuple.

Types provided must have ClimaCore.RecursiveApply.rzero(T::DataType) defined. Common examples include

• Float64, Float32 for scalar variables (a scalar value at each

coordinate point)

• SVector{k,Float64} for a mutable but statically sized array of

length k at each coordinate point.

• Note that Arrays, MVectors are not isbits and cannot be used.

Here, the coordinate points are those returned by coordinates(model).

auxiliary_vars(m::AbstractModel)

Returns the auxiliary variable symbols for the model in the form of a tuple.

boundary_flux(bc::AbstractBC, bound_type::AbstractBoundary, Δz, _...)::ClimaCore.Fields.Field

A function which returns the correct boundary flux given any boundary condition (BC).

function ClimaLand.boundary_flux(
    bc::RunoffBC,
    ::TopBoundary,
    model::Soil.RichardsModel,
    Δz::FT,
    Y::ClimaCore.Fields.FieldVector,
    p::NamedTuple,
    t,
    params,
)::ClimaCore.Fields.Field

Extension of the ClimaLand.boundary_flux function, which returns the water volume boundary flux for the soil. At the top boundary, return the soil infiltration (computed each step and stored in p.soil_infiltration).

boundary_var_domain_names(::AbstractBC, ::ClimaLand.AbstractBoundary)

The list of domain names for additional variables to add to the model auxiliary state, for models solving PDEs, which defaults to adding storage on the surface domain for the top or bottom boundary flux fields, but which can be extended depending on the type of boundary condition used.

Use in conjunction with boundary_vars, in the same way you would use auxiliary_var_domain_names.

boundary_var_types(model::AbstractModel{FT}, ::AbstractBC, ::ClimaLand.AbstractBoundary) where {FT}

The list of types for additional variables to add to the model auxiliary state, for models solving PDEs, which defaults to adding a scalar variable on the surface domain for the top or bottom boundary flux fields, but which can be extended depending on the type of boundary condition used.

Use in conjunction with boundary_vars, in the same way you would use auxiliary_var_types. The use of a scalar is appropriate for models with a single PDE; models with multiple PDEs will need to supply multiple scalar fields.

boundary_vars(::AbstractBC, ::ClimaLand.BottomBoundary)

The list of symbols for additional variables to add to the model auxiliary state, for models solving PDEs, which defaults to adding storage for the bottom boundary flux fields, but which can be extended depending on the type of boundary condition used.

For the Soil and SoilCO2 models - which solve PDEs - the tendency functions and updateboundaryfluxes functions are coded to access the field :bottom_bc to be present in the model cache, which is why this is the default. If this is not your (PDE) model's desired behavior, you can extend this function with a new method.

Use this function in the exact same way you would use auxiliary_vars.

boundary_vars(::AbstractBC , ::ClimaLand.TopBoundary)

The list of symbols for additional variables to add to the model auxiliary state, for models solving PDEs, which defaults to adding storage for the top boundary flux fields, but which can be extended depending on the type of boundary condition used.

For the Soil and SoilCO2 models - which solve PDEs - the tendency functions and updateboundaryfluxes functions are coded to access the field :top_bc to be present in the model cache, which is why this is the default. If this is not your (PDE) model's desired behavior, you can extend this function with a new method.

Use this function in the exact same way you would use auxiliary_vars.

compute_ρ_sfc(thermo_params, ts_in, T_sfc)

Computes the density of air at the surface, given the temperature at the surface Tsfc, the thermodynamic state of the atmosphere, tsin, and a set of Clima.Thermodynamics parameters thermo_params.

This assumes the ideal gas law and hydrostatic balance to extrapolate to the surface.

condition(saveat)

This function returns a function with the type signature expected by SciMLBase.DiscreteCallback, and determines whether affect! gets called in the callback. This implementation simply checks if the current time is contained in the list of affect times used for the callback.

diffusive_flux(K, x_2, x_1, Δz)

Calculates the diffusive flux of a quantity x (water content, temp, etc). Here, x2 = x(z + Δz) and x1 = x(z), so x_2 is at a larger z by convention.

displacement_height(model::AbstractModel, Y, p)

A helper function which returns the displacement height for a given model; the default is zero.

Extending this function for your model is only necessary if you need to compute surface fluxes and radiative fluxes at the surface using the functions in this file.

driver_initialize(cb, u, t, integrator)

This function updates p.drivers at the start of the simulation.

  dss!(Y::ClimaCore.Fields.FieldVector, p::NamedTuple, t)

Computes the weighted direct stiffness summation and updates Y in place. In the case of a column domain, no dss operations are performed.

dss_helper!(
    field::ClimaCore.Fields.Field,
    space::ClimaCore.Spaces.AbstractSpectralElementSpace,
    p::NamedTuple)

Method of dss_helper! which performs dss on a Field which is defined on a 2-dimensional domain.

The assumption is that Y contains FieldVectors which themselves contain either FieldVectors or Fields, and that the final unpacked variable is a Field. This method is invoked when the element cannot be unpacked further. We further assume that all fields in Y are defined on cell centers.

dss_helper!(
    field::ClimaCore.Fields.Field,
    space::ClimaCore.Spaces.ExtrudedFiniteDifferenceSpace,
    p::NamedTuple)

Method of dss_helper! which performs dss on a Field which is defined on a 3-dimensional domain.

The assumption is that Y contains FieldVectors which themselves contain either FieldVectors or Fields, and that the final unpacked variable is a Field. This method is invoked when the element cannot be unpacked further. We further assume that all fields in Y are defined on cell centers.

dss_helper!(field_vec::ClimaCore.Fields.FieldVector, space, p::NamedTuple)

Method of dss_helper! which unpacks properties of Y when on a domain that is 2-dimensional in the horizontal.

The assumption is that Y contains FieldVectors which themselves contain either FieldVectors or Fields, and that the final unpacked variable is a Field. This method is invoked when the current property itself contains additional property(ies).

dss_helper!(
    field::Union{ClimaCore.Fields.Field, Vector},
    space::Union{
        ClimaCore.Spaces.FiniteDifferenceSpace,
        ClimaCore.Spaces.PointSpace,
        Tuple,
    }, _)

Method of dss_helper! which does not perform dss.

This is intended for spaces that don't use spectral elements (FiniteDifferenceSpace, PointSpace, etc). Model components with no prognostic variables appear in Y as empty Vectors, and also do not need dss.

get_drivers(model::AbstractModel)

Returns the driver objects for the model - atmospheric and radiative forcing, etc - as a tuple (atmos, radiation, ...). If no drivers are needed by a model, an empty tuple should be returned

 heaviside(x::FT)::FT where {FT}

Computes the heaviside function.

infiltration_at_point(η::FT, i_c::FT, P::FT)

Returns the infiltration given pond height η, infiltration capacity, and precipitation.

This is defined such that positive means into soil.

function infiltration_capacity(
    Y::ClimaCore.Fields.FieldVector,
    p::NamedTuple,
)

Function which computes the infiltration capacity of the soil based on soil characteristics, moisture levels, and pond height.

Defined such that positive means into soil.

initialize(model::AbstractModel)

Creates the prognostic and auxiliary states structures, but with unset values; constructs and returns the coordinates for the model domain. We may need to consider this default more as we add diverse components and Simulations.

initialize_auxiliary(model::AbstractModel, state::NamedTuple)

Returns a NamedTuple of auxiliary variables for model with the required structure, with values equal to similar(state). This assumes that all auxiliary variables are defined over the entire domain, and that all auxiliary variables have the same dimension and type. The auxiliary variables NamedTuple can also hold preallocated objects which are not Fields.

If a model has no auxiliary variables, the returned NamedTuple contains only an empty array.

The input state is an array-like object, usually a ClimaCore Field or a Vector{FT}.

Adjustments to this - for example because different auxiliary variables have different dimensions - require defining a new method.

initialize_drivers(::AbstractClimaLandDrivers, coords)

Creates and returns a default empty NamedTuple for AbstractClimaLandDrivers. More generally this should return a named tuple of the driver fields, which will then be stored in the cache under p.drivers.

initialize_drivers(driver_tuple::Tuple,
                   coords)

Creates and returns a NamedTuple with the cache variables required by the model drivers.

If no forcing is required, driver_tuple is an empty tuple, and an empty NamedTuple is returned.

initialize_drivers(r::CoupledAtmosphere{FT}, coords) where {FT}

Creates and returns a NamedTuple for the CoupledAtmosphere driver, with variables P_liq, and P_snow. This is intended to be used in coupled simulations with ClimaCoupler.jl

initialize_drivers(a::PrescribedAtmosphere{FT}, coords) where {FT}

Creates and returns a NamedTuple for the PrescribedAtmosphere driver, with variables P_liq, P_snow, and air temperature T, pressure P, horizontal wind speed u, specific humidity q, and CO2 concentration c_co2.

initialize_drivers(a::PrescribedPrecipitation{FT}, coords) where {FT}

Creates and returns a NamedTuple for the PrescribedPrecipitation driver, with variable P_liq.

initialize_drivers(r::PrescribedRadiativeFluxes{FT}, coords) where {FT}

Creates and returns a NamedTuple for the PrescribedRadiativeFluxes driver, with variables SW_d, LW_d, and zenith angle θ_s.

initialize_drivers(r::PrescribedSoilOrganicCarbon{FT}, coords) where {FT}

Creates and returns a NamedTuple for the PrescribedSoilOrganicCarbon driver, with variable soc.

initialize_lsm_aux(land::AbstractLandModel) end

Initializes additional auxiliary variables required in integrated models, and not existing in the individual component models auxiliary vars.

Additional auxiliary variables are specified by lsm_aux_vars, their types by lsm_aux_types, and their domain names by lsm_aux_domain_names. This function should be called during initialize_auxiliary step.

initialize_prognostic(model::AbstractModel, state::NamedTuple)

Returns a FieldVector of prognostic variables for model with the required structure, with values equal to similar(state). This assumes that all prognostic variables are defined over the entire domain, and that all prognostic variables have the same dimension and type.

If a model has no prognostic variables, the returned FieldVector contains only an empty array.

The input state is an array-like object, usually a ClimaCore Field or a Vector{FT}.

Adjustments to this - for example because different prognostic variables have different dimensions - require defining a new method.

land_components(land::AbstractLandModel)

Returns the component names of the land model, by calling propertynames(land).

liquid_precipitation(atmos::AbstractAtmosphericDrivers, p, t)

Returns the liquid precipitation (m/s) at the surface.

lsmauxdomain_names(m::AbstractLandModel)

Returns the additional domain symbols in the form of a tuple e.g. :surface or :subsurface.

This is only required for variables shared between land submodels, and only needed for multi-component models, not standalone components. Component-specific variables should be listed as prognostic or auxiliary variables which do not require this to initialize.

lsm_aux_domain_names(m::SoilCanopyModel)

The domain names of the additional auxiliary variables that are included in the integrated Soil-Canopy model.

lsmauxtypes(m::AbstractLandModel)

Returns the shared additional aux variable types for the model in the form of a tuple.

lsm_aux_types(m::SoilCanopyModel)

The types of the additional auxiliary variables that are included in the integrated Soil-Canopy model.

lsmauxvars(m::AbstractLandModel)

Returns the additional aux variable symbols for the model in the form of a tuple.

lsm_aux_vars(m::SoilCanopyModel)

The names of the additional auxiliary variables that are included in the integrated Soil-Canopy model.

lsm_radiant_energy_fluxes!(p,
                            canopy_radiation::Canopy.AbstractRadiationModel{FT},
                            canopy,
                            ground_model::Soil.EnergyHydrology,
                            Y,
                            t,
                            ) where {FT}

A function which computes the net radiation at the ground surface give the canopy radiation model, as well as the outgoing radiation, and the net canopy radiation.

Returns the correct radiative fluxes for bare ground in the case where the canopy LAI is zero. Note also that this serves the role of canopy_radiant_energy_fluxes!, which computes the net canopy radiation when the Canopy is run in standalone mode.

make_compute_exp_tendency(model::AbstractModel)

Return a compute_exp_tendency! function that updates state variables that we will be stepped explicitly. This fallback sets all tendencies of this model to zero, which is appropriate for models that do not have any explicit tendencies to update. Note that we cannot set dY .= 0 here because this would overwrite the tendencies of all models in the case of an integrated LSM.

compute_exp_tendency! should be compatible with SciMLBase.jl solvers.

make_compute_imp_tendency(model::AbstractModel)

Return a compute_imp_tendency! function that updates state variables that we will be stepped implicitly. This fallback sets all tendencies of this model to zero, which is appropriate for models that do not have any implicit tendencies to update. Note that we cannot set dY .= 0 here because this would overwrite the tendencies of all models in the case of an integrated LSM.

compute_imp_tendency! should be compatible with SciMLBase.jl solvers.

make_compute_jacobian(model::AbstractModel)

Creates and returns a function which computes the entries of the Jacobian matrix W in place.

If the implicit tendency function is given by T!(dY, Y, p, t) = make_implicit_tendency(model), the Jacobian should be given by W_{i,j}! = ∂T!_i/∂Y_j, where Y_j is the j-th state variable and T!_i is the implicit tendency of the i-th state variable.

The default is that no updates are required, but this function must be extended for models that use implicit timestepping.

make_exp_tendency(model::AbstractModel)

Returns an exp_tendency that updates auxiliary variables and updates the prognostic state of variables that are stepped explicitly.

compute_exp_tendency! should be compatible with SciMLBase.jl solvers.

make_imp_tendency(model::AbstractImExModel)

Returns an imp_tendency that updates auxiliary variables and updates the prognostic state of variables that are stepped implicitly.

compute_imp_tendency! should be compatible with SciMLBase.jl solvers.

make_imp_tendency(model::AbstractModel)

Returns an imp_tendency that does nothing. This model type is not stepped explicity.

make_jacobian(model::AbstractModel)

Creates and returns a function which updates the auxiliary variables p in place and then updates the entries of the Jacobian matrix W for the model in place.

The default is that no updates are required, no implicit tendency is present, and hence the timestepping is entirely explicit.

Note that the returned function jacobian! should be used as Wfact! in ClimaTimeSteppers.jl and SciMLBase.jl.

make_set_initial_cache(model::AbstractModel)

Returns the setinitialcache! function, which updates the auxiliary state p in place with the initial values corresponding to Y(t=t0) = Y0.

In principle, this function is not needed, because in the very first evaluation of either explicit_tendency or implicit_tendency, at t=t0, the auxiliary state is updated using the initial conditions for Y=Y0. However, without setting the initial p state prior to running the simulation, the value of p in the saved output at t=t0 will be unset.

Furthermore, specific methods of this function may be useful for models which store time indepedent spatially varying parameter fields in the auxiliary state. In this case, update_aux! does not need to do anything, but they do need to be set with the initial (constant) values before the simulation can be carried out.

make_update_aux(model::AbstractModel)

Return an update_aux! function that updates auxiliary parameters p.

make_update_boundary_fluxes(model::AbstractModel)

Return an update_boundary_fluxes! function that updates the auxiliary parameters in p corresponding to boundary fluxes or interactions between componets..

make_update_boundary_fluxes(
    land::LandHydrology{FT, SM, SW},
) where {FT, SM <: Soil.RichardsModel{FT}, SW <: Pond.PondModel{FT}}

A method which makes a function; the returned function updates the auxiliary variable p.soil_infiltration, which is needed for both the boundary condition for the soil model and the source term (runoff) for the surface water model.

This function is called each ode function evaluation.

make_update_boundary_fluxes(
    land::SoilCanopyModel{FT, MM, SM, RM},
) where {
    FT,
    MM <: Soil.Biogeochemistry.SoilCO2Model{FT},
    SM <: Soil.RichardsModel{FT},
    RM <: Canopy.CanopyModel{FT}
    }

A method which makes a function; the returned function updates the additional auxiliary variables for the integrated model, as well as updates the boundary auxiliary variables for all component models.

This function is called each ode function evaluation, prior to the tendency function evaluation.

 make_update_cache(model::AbstractModel)

A helper function which updates all cache variables of a model; currently only used in set_initial_cache since not all cache variables are updated at the same time.

make_update_drivers(::AbstractClimaLandDrivers)

Creates and returns a function which updates the driver variables in the default case of no drivers. More generally, this should return a function which updates the driver fields stored in p.drivers.

make_update_drivers(driver_tuple)

Creates and returns a function which updates the forcing variables ("drivers"). If no drivers are being used, driver_tuple is empty, and the update function does nothing.

make_update_drivers(a::PrescribedAtmosphere{FT}) where {FT}

Creates and returns a function which updates the driver variables in the case of a PrescribedAtmosphere.

make_update_drivers(a::PrescribedPrecipitation{FT}) where {FT}

Creates and returns a function which updates the driver variables in the case of a PrescribedPrecipitation.

make_update_drivers(r::PrescribedRadiativeFluxes{FT}) where {FT}

Creates and returns a function which updates the driver variables in the case of a PrescribedRadiativeFluxes.

make_update_drivers(d::PrescribedSoilOrganicCarbon{FT}) where {FT}

Creates and returns a function which updates the driver variables in the case of a PrescribedSoilOrganicCarbon.

name(model::AbstractModel)

Returns a symbol of the model component name, e.g. :soil or :vegetation.

net_radiation(radiation::CoupledRadiativeFluxes,
              model::AbstractModel,
              Y,
              p,
              t)

Computes the net radiative flux at the ground for a coupled simulation. Your model cache must contain the field R_n.

net_radiation(radiation::PrescribedRadiativeFluxes{FT},
              model::AbstractModel{FT},
              Y::ClimaCore.Fields.FieldVector,
              p::NamedTuple,
              t,
              ) where {FT}

Computes net radiative fluxes for a prescribed incoming longwave and shortwave radiation.

This returns an energy flux.

prognosticdomainnames(m::AbstractModel)

Returns the domain names for the prognostic variables in the form of a tuple.

Examples: (:surface, :surface, :subsurface).

Note that this default suggests that a model has no prognostic variables, which is an invalid model setup. This function is meant to be extended for all models.

prognostic_types(m::AbstractModel{FT}) where {FT}

Returns the prognostic variable types for the model in the form of a tuple.

Types provided must have ClimaCore.RecursiveApply.rzero(T::DataType) defined. Common examples include

• Float64, Float32 for scalar variables (a scalar value at each

coordinate point)

• SVector{k,Float64} for a mutable but statically sized array of

length k at each coordinate point.

Here, the coordinate points are those returned by coordinates(model).

Note that this default suggests that a model has no prognostic variables, which is an invalid model setup. This function is meant to be extended for all models.

prognostic_vars(m::AbstractModel)

Returns the prognostic variable symbols for the model in the form of a tuple.

Note that this default suggests that a model has no prognostic variables, which is an invalid model setup. This function is meant to be extended for all models.

relative_humidity(T_air, P_air, q_air, thermo_params)

Computes the vapor pressure deficit for air with temperature Tair, pressure Pair, and specific humidity qair, using thermoparams, a Thermodynamics.jl param set.

saving_initialize(cb, u, t, integrator)

This function saves t and p at the start of the simulation, as long as the initial time is in saveat. To run the simulation without saving these initial values, don't pass the initialize argument to the DiscreteCallback constructor.

set_atmos_ts!(ts_in, atmos::PrescribedAtmosphere{FT}, p)

Fill the pre-allocated ts_in Field with a thermodynamic state computed from the atmosphere.

set_dfluxBCdY!(::AbstractModel,
              ::AbstractBC,
              ::AbstractBoundary,
              _...)::Union{ClimaCore.Fields.FieldVector, Nothing}

A function stub which returns the derivative of the implicit tendency term of the model arising from the boundary condition, with respect to the state Y.

snow_precipitation(atmos::AbstractAtmosphericDrivers, p, t)

Returns the precipitation in snow (m of liquid water/s) at the surface.

 source!(dY::ClimaCore.Fields.FieldVector,
         src::AbstractSource,
         Y::ClimaCore.Fields.FieldVector,
         p::NamedTuple
         )::ClimaCore.Fields.Field

A stub function, which is extended by ClimaLand.

ClimaLand.source!(dY::ClimaCore.Fields.FieldVector,
                 src::RootExtraction,
                 Y::ClimaCore.Fields.FieldVector,
                 p::NamedTuple
                 model::EnergyHydrology)

An extension of the ClimaLand.source! function, which computes source terms for the soil model; this method returns the water and energy loss/gain due to root extraction.

ClimaLand.surface_air_density(
                atmos::CoupledAtmosphere,
                model::AbstractModel,
                Y,
                p,
                _...,
            )

Returns the air density at the surface in the case of a coupled simulation.

This requires the field ρ_sfc to be present in the cache p under the name of the model.

surface_air_density(
                    atmos::PrescribedAtmosphere,
                    model::AbstractModel,
                    Y,
                    p,
                    t,
                    T_sfc,
                    )

A helper function which returns the surface air density; this assumes that the model has a property called parameters containing earth_param_set.

We additionally include the atmos type as an argument because the surface air density computation will change between a coupled simulation and a prescibed atmos simulation.

Extending this function for your model is only necessary if you need to compute the air density in a different way.

surface_albedo(model::AbstractModel, Y, p)

A helper function which returns the surface albedo for a given model, needed because different models compute and store α_sfc in different ways and places.

Extending this function for your model is only necessary if you need to compute surface fluxes and radiative fluxes at the surface using the functions in this file.

surface_emissivity(model::AbstractModel, Y, p)

A helper function which returns the surface emissivity for a given model, needed because different models compute and store ϵ_sfc in different ways and places.

Extending this function for your model is only necessary if you need to compute surface fluxes and radiative fluxes at the surface using the functions in this file.

surface_evaporative_scaling(model::AbstractModel{FT}, Y, p) where {FT}

A helper function which returns the surface evaporative scaling factor for a given model, needed because different models compute and store β_sfc in different ways and places. Currently, this factor is 1 for all models besides the bucket model, so we have chosen a default of 1.

Extending this function for your model is only necessary if you need to compute surface fluxes and radiative fluxes at the surface using the functions in this file.

surface_height(model::AbstractModel, Y, p)

A helper function which returns the surface height (canopy height+elevation) for a given model, needed because different models compute and store h_sfc in different ways and places.

Extending this function for your model is only necessary if you need to compute surface fluxes and radiative fluxes at the surface using the functions in this file.

surface_resistance(model::AbstractModel, Y, p, t)

A helper function which returns the surface resistance for a given model, needed because different models compute and store surface resistance in different ways and places.

Extending this function for your model is only necessary if you need to compute surface fluxes and radiative fluxes at the surface using the functions in this file.

The default is 0, which is no additional resistance aside from the usual aerodynamic resistance from MOST.

surface_specific_humidity(model::AbstractModel, Y, p, T_sfc, ρ_sfc)

A helper function which returns the surface specific humidity for a given model, needed because different models compute and store q_sfc in different ways and places.

Extending this function for your model is only necessary if you need to compute surface fluxes and radiative fluxes at the surface using the functions in this file.

surface_temperature(model::AbstractModel, Y, p, t)

A helper function which returns the surface temperature for a given model, needed because different models compute and store surface temperature in different ways and places.

Extending this function for your model is only necessary if you need to compute surface fluxes and radiative fluxes at the surface using the functions in this file.

turbulent_fluxes(atmos::CoupledAtmosphere,
                model::AbstractModel,
                Y,
                p,
                t)

Computes the turbulent surface fluxes terms at the ground for a coupled simulation.

turbulent_fluxes(atmos::PrescribedAtmosphere,
               model::AbstractModel,
               Y::ClimaCore.Fields.FieldVector,
               p::NamedTuple,
               t
               )

Computes the turbulent surface flux terms at the ground for a standalone simulation, including turbulent energy fluxes as well as the water vapor flux (in units of m^3/m^2/s of water). Positive fluxes indicate flow from the ground to the atmosphere.

It solves for these given atmospheric conditions, stored in atmos, model parameters, and the surface conditions.

turbulent_fluxes_at_a_point(T_sfc::FT,
                            q_sfc::FT,
                            ρ_sfc::FT,
                            β_sfc::FT,
                            h_sfc::FT,
                            r_sfc::FT,
                            d_sfc::FT,
                            ts_in,
                            u::FT,
                            h::FT,
                            gustiness::FT,
                            z_0m::FT,
                            z_0b::FT,
                            earth_param_set::EP,
                           ) where {FT <: AbstractFloat, P}

Computes turbulent surface fluxes at a point on a surface given (1) the surface temperature (Tsfc), specific humidity (qsfc), and air density (ρsfc), (2) Other surface properties, such as the factor βsfc which scales the evaporation from the potential rate (used in bucket models), and the surface resistance rsfc (used in more complex land models), and the topographical height of the surface (hsfc) (3) the roughness lengths z_0m, z_0b, and the Earth parameter set for the model earth_params. (4) the prescribed atmospheric state, ts_in, u, h the height at which these measurements are made, and the gustiness parameter (m/s). (5) the displacement height for the model d_sfc

This returns an energy flux and a liquid water volume flux, stored in a tuple with self explanatory keys.

update_condition(updateat)

This function returns a function with the type signature expected by SciMLBase.DiscreteCallback, and determines whether affect! gets called in the callback. This implementation simply checks if the current time of the simulation is within the (inclusive) bounds of updateat.

vapor_pressure_deficit(T_air, P_air, q_air, thermo_params)

Computes the vapor pressure deficit for air with temperature Tair, pressure Pair, and specific humidity qair, using thermoparams, a Thermodynamics.jl param set.

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.

An abstract type of soil drivers of the canopy model.

AutotrophicRespirationModel{FT, ARP <: AutotrophicRespirationParameters{FT},} <: AbstractAutotrophicRespirationModel{FT}

The JULES autotrophic respiration model.

Clark, D. B., et al. "The Joint UK Land Environment Simulator (JULES), model description–Part 2: carbon fluxes and vegetation dynamics." Geoscientific Model Development 4.3 (2011): 701-722.

AutotrophicRespirationParameters{FT<:AbstractFloat}

The required parameters for the autrophic respiration model, which is based off of the JULES model. Clark, D. B., et al. "The Joint UK Land Environment Simulator (JULES), model description–Part 2: carbon fluxes and vegetation dynamics." Geoscientific Model Development 4.3 (2011): 701-722.

• ne: Vcmax25 to N factor (mol CO2 m-2 s-1 kg C (kg C)-1)

• ηsl: Live stem wood coefficient (kg C m-3)

• σl: Specific leaf density (kg C m-2 [leaf])

• μr: Ratio root nitrogen to top leaf nitrogen (-), typical value 1.0

• μs: Ratio stem nitrogen to top leaf nitrogen (-), typical value 0.1

• f1: Factor to convert from mol CO2 to kg C

• f2: Factor of relative contribution or Rgrowth (-)

BeerLambertParameters{FT <: AbstractFloat}

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)

• λ_γ_NIR: Typical wavelength per NIR photon (m)

• G_Function: Leaf angle distribution function

BigLeafEnergyModel{FT} <: AbstractCanopyEnergyModel{FT}

BigLeafEnergyParameters{FT <: AbstractFloat}

• ac_canopy: Specific heat per emitting area [J/m^2/K]

C3 <: AbstractPhotosynthesisMechanism

Helper struct for dispatching between C3 and C4 photosynthesis.

C4 <: AbstractPhotosynthesisMechanism

Helper struct for dispatching between C3 and C4 photosynthesis.

CLMGFunction

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

 CanopyModel{FT, AR, RM, PM, SM, PHM, EM, A, R, S, PS, D} <: AbstractExpModel{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 currently only the FarquharModel is supported.

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

AbstractStomatalConductanceModel and currently only the MedlynModel is supported

• 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.

• canopy model parameters, which include parameters that are shared

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

• 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 soil conditions, which are either prescribed (of type PrecribedSoil, for

running the canopy model in standalone mode), or prognostic (of type PrognosticSoil, for running integrated soil+canopy models)

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

• hydraulics: Plant hydraulics model, a canopy component model

• energy: Energy balance model, a canopy component model

• atmos: Atmospheric forcing: prescribed or coupled

• radiation: Radiative forcing: prescribed or coupled

• soil_driver: Soil pressure: prescribed or prognostic

• parameters: Shared canopy parameters between component models

• domain: Canopy model domain

CanopyModel{FT}(;
    autotrophic_respiration::AbstractAutotrophicRespirationModel{FT},
    radiative_transfer::AbstractRadiationModel{FT},
    photosynthesis::AbstractPhotosynthesisModel{FT},
    conductance::AbstractStomatalConductanceModel{FT},
    hydraulics::AbstractPlantHydraulicsModel{FT},
    energy::AbstractCanopyEnergyModel{FT},
    atmos::AbstractAtmosphericDrivers{FT},
    radiation::AbstractRadiativeDrivers{FT},
    soil::AbstractSoilDriver,
    parameters::SharedCanopyParameters{FT, PSE},
    domain::Union{
        ClimaLand.Domains.Point,
        ClimaLand.Domains.Plane,
        ClimaLand.Domains.SphericalSurface,
    },
    energy = PrescribedCanopyTempModel{FT}(),
) where {FT, PSE}

An outer constructor for the CanopyModel. The primary constraints this applies are (1) ensuring that the domain is 1d or 2d (a ``surface" domain of a column, box, or sphere) and (2) ensuring consistency between the PlantHydraulics model and the general canopy model, since these are built separately.

ConstantGFunction

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

FarquharParameters{FT<:AbstractFloat, MECH <: AbstractPhotosynthesisMechanism}

The required parameters for the Farquhar photosynthesis model.

• Vcmax25: Vcmax at 25 °C (mol CO2/m^2/s)

• Γstar25: Γstar at 25 °C (mol/mol)

• Kc25: Michaelis-Menten parameter for CO2 at 25 °C (mol/mol)

• Ko25: Michaelis-Menten parameter for O2 at 25 °C (mol/mol)

• ΔHkc: Energy of activation for CO2 (J/mol)

• ΔHko: Energy of activation for oxygen (J/mol)

• ΔHVcmax: Energy of activation for Vcmax (J/mol)

• ΔHΓstar: Energy of activation for Γstar (J/mol)

• ΔHJmax: Energy of activation for Jmax (J/mol)

• ΔHRd: Energy of activation for Rd (J/mol)

• To: Reference temperature equal to 25 degrees Celsius (K)

• oi: Intercelluar O2 concentration (mol/mol); taken to be constant

• ϕ: Quantum yield of photosystem II (Bernacchi, 2003; unitless)

• θj: Curvature parameter, a fitting constant to compute J, unitless

• f: Constant factor appearing the dark respiration term, equal to 0.015.

• sc: Sensitivity to low water pressure, in the moisture stress factor, (Pa^{-1}) [Tuzet et al. (2003)]

• pc: Reference water pressure for the moisture stress factor (Pa) [Tuzet et al. (2003)]

• mechanism: Photosynthesis mechanism: C3 or C4

MedlynConductanceParameters{FT <: AbstractFloat}

The required parameters for the Medlyn stomatal conductance model.

• Drel: Relative diffusivity of water vapor (unitless)

• g0: Minimum stomatal conductance mol/m^2/s

• g1: Slope parameter, inversely proportional to the square root of marginal water use efficiency (Pa^{1/2})

OptimalityFarquharModel{FT,
                        OPFT <: OptimalityFarquharParameters{FT}
                        } <: AbstractPhotosynthesisModel{FT}

Optimality model of Smith et al. (2019) for estimating Vcmax, based on the assumption that Aj = Ac. Smith et al. (2019). Global photosynthetic capacity is optimized to the environment. Ecology Letters, 22(3), 506–517. https://doi.org/10.1111/ele.13210

OptimalityFarquharParameters{FT<:AbstractFloat}

The required parameters for the optimality Farquhar photosynthesis model. Currently, only C3 photosynthesis is supported.

• mechanism: Photosynthesis mechanism: C3 only

• Γstar25: Γstar at 25 °C (mol/mol)

• Kc25: Michaelis-Menten parameter for CO2 at 25 °C (mol/mol)

• Ko25: Michaelis-Menten parameter for O2 at 25 °C (mol/mol)

• ΔHkc: Energy of activation for CO2 (J/mol)

• ΔHko: Energy of activation for oxygen (J/mol)

• ΔHVcmax: Energy of activation for Vcmax (J/mol)

• ΔHΓstar: Energy of activation for Γstar (J/mol)

• ΔHJmax: Energy of activation for Jmax (J/mol)

• ΔHRd: Energy of activation for Rd (J/mol)

• To: Reference temperature equal to 25 degrees Celsius (K)

• oi: Intercellular O2 concentration (mol/mol); taken to be constant

• ϕ: Quantum yield of photosystem II (Bernacchi, 2003; unitless)

• θj: Curvature parameter, a fitting constant to compute J, unitless

• f: Constant factor appearing the dark respiration term, equal to 0.015.

• sc: Fitting constant to compute the moisture stress factor (Pa^{-1})

• pc: Fitting constant to compute the moisture stress factor (Pa)

• c: Constant describing cost of maintaining electron transport (unitless)

Define a PFT type that can be used to store the parameters for each PFT. Each PFT has a name and a list of parameters. The parameters are stored as NamedTuples mapping parameter names to values. The inner constructor checks to ensure all required parameters are defined for the PFT.

PrescribedCanopyTempModel{FT} <: AbstractCanopyEnergyModel{FT}

A model for the energy of the canopy which assumes the canopy temperature is the same as the atmosphere temperature prescribed in the PrescribedAtmos struct.

No equation for the energy of the canopy is solved.

 PrescribedSoil <: AbstractSoilDriver

A container for holding prescribed soil parameters needed by the canopy model when running the canopy in standalone mode, including the soil pressure, surface temperature, and albedo.

• root_depths: The depth of the root tips, in meters

• ψ: Prescribed soil potential (m) in the root zone a function of time

• T: Prescribed soil surface temperature (K) as a function of time

• α_PAR: Soil albedo for PAR

• α_NIR: Soil albedo for NIR

• ϵ: Soil emissivity

 function PrescribedSoil(FT;
     root_depths::AbstractArray{FT},
     ψ::Function,
     T::Function,
     α_PAR::FT,
     α_NIR::FT,
     ϵ::FT
 ) where {FT}

An outer constructor for the PrescribedSoil soil driver allowing the user to specify the soil parameters by keyword arguments.

SharedCanopyParameters{FT <: AbstractFloat, PSE}

A place to store shared parameters that are required by multiple canopy components.

• z_0m: Roughness length for momentum (m)

• z_0b: Roughness length for scalars (m)

• earth_param_set: Earth param set

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)

• λ_γ_NIR: Typical wavelength per NIR 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

MM_Kc(Kc25::FT,
      ΔHkc::FT,
      T::FT,
      To::FT,
      R::FT) where {FT}

Computes the Michaelis-Menten coefficient for CO2 (Kc), in units of mol/mol, as a function of its value at 25 °C (Kc25), a constant (ΔHkc), a standard temperature (To), the unversal gas constant (R), and the temperature (T).

See Table 11.5 of G. Bonan's textbook, Climate Change and Terrestrial Ecosystem Modeling (2019).

MM_Ko(Ko25::FT,
      ΔHko::FT,
      T::FT,
      To::FT,
      R::FT) where {FT}

Computes the Michaelis-Menten coefficient for O2 (Ko), in units of mol/mol, as a function of its value at 25 °C (Ko25), a constant (ΔHko), a standard temperature (To), the universal gas constant (R), and the temperature (T).

See Table 11.5 of G. Bonan's textbook, Climate Change and Terrestrial Ecosystem Modeling (2019).

arrhenius_function(T::FT, To::FT, R::FT, ΔH::FT)

Computes the Arrhenius function at temperature T given the reference temperature To=298.15K, the universal gas constant R, and the energy activation ΔH.

See Table 11.5 of G. Bonan's textbook, Climate Change and Terrestrial Ecosystem Modeling (2019).

canopy_boundary_fluxes!(p::NamedTuple,
                        canopy::CanopyModel{
                            FT,
                            <:AutotrophicRespirationModel,
                            <:Union{BeerLambertModel, TwoStreamModel},
                            <:Union{FarquharModel,OptimalityFarquharModel},
                            <:MedlynConductanceModel,
                            <:PlantHydraulicsModel,
                            <:Union{PrescribedCanopyTempModel,BigLeafEnergyModel}
                        },
                        radiation::PrescribedRadiativeFluxes,
                        atmos::PrescribedAtmosphere,
                        Y::ClimaCore.Fields.FieldVector,
                        t,
                        ) where {FT}

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.energy.shf: Canopy SHF
• p.canopy.energy.lhf: Canopy LHF
• p.canopy.hydraulics.fa[end]: Transpiration
• p.canopy.conductance.transpiration: Transpiration (stored twice; to be addressed in a future PR)
• 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_components(::CanopyModel)

Returns the names of the components of the CanopyModel.

These names are used for storing prognostic and auxiliary variables in a hierarchical manner within the state vectors.

These names must match the field names of the CanopyModel struct.

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

Computes and stores the net long and short wave radition, in W/m^2, absorbed by the canopy when the canopy is run in standalone mode, with a PrescribedSoil conditions.

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

canopy_temperature(model::BigLeafEnergyModel, canopy, Y, p, t)

Returns the canopy temperature under the BigLeafEnergyModel model, where the canopy temperature is modeled prognostically.

canopy_temperature(model::PrescribedCanopyTempModel, canopy, Y, p, t)

Returns the canopy temperature under the PrescribedCanopyTemp model, where the canopy temperature is assumed to be the same as the atmosphere temperature.

function canopy_turbulent_fluxes(
    atmos::PrescribedAtmosphere,
    model::CanopyModel,
    Y::ClimaCore.Fields.FieldVector,
    p::NamedTuple,
    t,
)

A canopy specific function for compute turbulent fluxes with the atmosphere; returns the latent heat flux, sensible heat flux, vapor flux, and aerodynamic resistance.

We cannot use the default version in src/shared_utilities/drivers.jl because the canopy requires a different resistance for vapor and sensible heat fluxes, and the resistances depend on ustar, which we must compute using SurfaceFluxes before adjusting to account for these resistances.

function canopy_turbulent_fluxes_at_a_point(
    T_sfc::FT,
    q_sfc::FT,
    ρ_sfc::FT,
    h_sfc::FT,
    leaf_r_stomata::FT,
    d_sfc::FT,
    ts_in,
    u::FT,
    h::FT,
    LAI::FT,
    SAI::FT,
    gustiness::FT,
    z_0m::FT,
    z_0b::FT,
    earth_param_set::EP,
) where {FT <: AbstractFloat, EP}

Computes the turbulent surface fluxes for the canopy at a point and returns the fluxes in a named tuple.

co2_compensation(Γstar25::FT,
                 ΔHΓstar::FT,
                 T::FT,
                 To::FT,
                 R::FT) where {FT}

Computes the CO2 compensation point (Γstar), in units of mol/mol, as a function of its value at 25 °C (Γstar25), a constant energy of activation (ΔHΓstar), a standard temperature (To), the unversal gas constant (R), and the temperature (T).

See Table 11.5 of G. Bonan's textbook, Climate Change and Terrestrial Ecosystem Modeling (2019).

compute_G(
    G::CLMGFunction{FT},
    θs::FT,
)

Returns the leaf angle distribution value for CLM G function as a function 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

compute_G(
    G::ConstantGFunction{FT},
    _::FT,
)

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

compute_GPP(An::FT,
         K::FT,
         LAI::FT,
         Ω::FT) where {FT}

Computes the total canopy photosynthesis (GPP) as a function of the total net carbon assimilation (An), the extinction coefficient (K), leaf area index (LAI) and the clumping index (Ω).

compute_NIR!(nir,
    model::AbstractRadiationModel,
    solar_radiation::ClimaLand.PrescribedRadiativeFluxes,
    p,
    t,
)

Update nir with the estimated NIR (W/m^2) given the input solar radiation for a radiative transfer model.

The estimated PNIR is half of the incident shortwave radiation.

compute_PAR!(par,
    model::AbstractRadiationModel,
    solar_radiation::ClimaLand.PrescribedRadiativeFluxes,
    p,
    t,
)

Updates par with the estimated PAR (W/,m^2) given the input solar radiation for a radiative transfer model.

The estimated PAR is half of the incident shortwave radiation.

compute_Vcmax(Vcmax25::FT,
       T::FT,
       To::FT,
       R::FT,
       ep5::FT) where {FT}

Computes the maximum rate of carboxylation of Rubisco (Vcmax), in units of mol/m^2/s, as a function of temperature (T), Vcmax at the reference temperature 25 °C (Vcmax25), the universal gas constant (R), and the reference temperature (To).

See Table 11.5 of G. Bonan's textbook, Climate Change and Terrestrial Ecosystem Modeling (2019).

compute_absorbances(
    RT::BeerLambertModel{FT},
    PAR,
    NIR,
    LAI,
    K,
    α_soil_PAR,
    α_soil_NIR,
    energy_per_photon_PAR,
    energy_per_photon_NIR,
    N_a,
    _,
    _,
)

Computes the PAR and NIR 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 magnitude of incident PAR and NIR radiation in W/m^2, the leaf area index, 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_absorbances!(p,
    RT::TwoStreamModel{FT},
    PAR,
    NIR,
    LAI,
    K,
    α_soil_PAR,
    α_soil_NIR,
    energy_per_photon_PAR,
    energy_per_photon_NIR,
    N_a,
    θs,
    frac_diff,
)

Computes the PAR and NIR 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 magnitude of incident PAR and NIR radiation in W/m^2, the leaf area index, the extinction coefficient, and the soil albedo in the PAR and NIR bands.

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

compute_autrophic_respiration(model::AutotrophicRespirationModel,
                              Vcmax25,
                              LAI,
                              SAI,
                              RAI,
                              K,
                              Ω,
                              An,
                              Rd,
                              β,
                              h,
                             )

Computes the autotrophic respiration as the sum of the plant maintenance and growth respirations, according to the JULES model.

Clark, D. B., et al. "The Joint UK Land Environment Simulator (JULES), model description–Part 2: carbon fluxes and vegetation dynamics." Geoscientific Model Development 4.3 (2011): 701-722.

dark_respiration(Vcmax25::FT,
                 β::FT,
                 f::FT,
                 ΔHkc::FT,
                 T::FT,
                 To::FT,
                 R::FT) where {FT}

Computes dark respiration (Rd), in units of mol CO2/m^2/s, as a function of the maximum rate of carboxylation of Rubisco (Vcmax25), and the moisture stress factor (β), an empirical factor f is equal to 0.015, a constant (ΔHRd), a standard temperature (To), the unversal gas constant (R), and the temperature (T).

See Table 11.5 of G. Bonan's textbook, Climate Change and Terrestrial Ecosystem Modeling (2019).

diffuse_fraction(td::FT, T::FT, P, q, SW_IN::FT, θs::FT, thermo_params) where {FT}

Computes the fraction of diffuse radiation (diff_frac) as a function of the solar zenith angle (θs), the total surface incident shortwave radiation (SW_IN), the air temperature (T), air pressure (P), specific humidity (q), and the day of the year (td).

See Appendix A of Braghiere, "Evaluation of turbulent fluxes of CO2, sensible heat, and latent heat as a function of aerosol optical depth over the course of deforestation in the Brazilian Amazon" 2013.

Note that cos(θs) is equal to zero when θs = π/2, and this is a coefficient of k₀, which we divide by in this expression. This can amplify small errors when θs is near π/2.

This formula is empirical and can yied negative numbers depending on the input, which, when dividing by something very near zero, can become large negative numbers.

Because of that, we cap the returned value to lie within [0,1].

electron_transport(APAR::FT,
                   Jmax::FT,
                   θj::FT,
                   ϕ::FT) where {FT}

Computes the rate of electron transport (J), in units of mol/m^2/s, as a function of the maximum potential rate of electron transport (Jmax), absorbed photosynthetically active radiation (APAR), an empirical "curvature parameter" (θj; Bonan Eqn 11.21) and the quantum yield of photosystem II (ϕ).

See Ch 11, G. Bonan's textbook, Climate Change and Terrestrial Ecosystem Modeling (2019).

extinction_coeff(ld::FT,
                 θs::FT) where {FT}

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

filter_nt(nt)

Base case for filter_nt recursion, used when this function is called on a NamedTuple with no nested NamedTuples.

filter_nt(nt::NamedTuple)

Removes all key/value pairs of a NamedTuple where the value is nothing. Note that NamedTuples are immutable, so rather than updating the input in-place, this creates a new NamedTuple with the filtered key/value pairs.

This results in unnecessary allocations because a new object is being created, and we may want to implement a better solution in the future.

ground_albedo_NIR(soil_driver::PrescribedSoil, _...)

Returns the soil albedo in the NIR for a PrescribedSoil driver.

ground_albedo_PAR(soil_driver::PrescribedSoil, _...)

Returns the soil albedo in the PAR for a PrescribedSoil driver.

intercellular_co2(ca::FT, Γstar::FT, medlyn_factor::FT) where{FT}

Computes the intercellular CO2 concentration (mol/mol) given the atmospheric concentration (ca, mol/mol), the CO2 compensation (Γstar, mol/mol), and the Medlyn factor (unitless).

light_assimilation(::C3,
                   J::FT,
                   ci::FT,
                   Γstar::FT) where {FT}

Computes the electron transport limiting rate (Aj), in units of moles CO2/m^2/s, for C3 plants as a function of the rate of electron transport (J), the leaf internal carbon dioxide partial pressure (ci), and the CO2 compensation point (Γstar).

See Table 11.5 of G. Bonan's textbook, Climate Change and Terrestrial Ecosystem Modeling (2019).

light_assimilation(::C4, J::FT, _...) where {FT}

Computes the electron transport limiting rate (Aj), in units of moles CO2/m^2/s, for C4 plants, as equal to the rate of electron transport (J).

max_electron_transport(Vcmax::FT) where {FT}

Computes the maximum potential rate of electron transport (Jmax), in units of mol/m^2/s, as a function of Vcmax at 25 °C (Vcmax25), a constant (ΔHJmax), a standard temperature (To), the unversal gas constant (R), and the temperature (T).

See Table 11.5 of G. Bonan's textbook, Climate Change and Terrestrial Ecosystem Modeling (2019).

medlyn_conductance(g0::FT,
                   Drel::FT,
                   medlyn_term::FT,
                   An::FT,
                   ca::FT) where {FT}

Computes the stomatal conductance according to Medlyn, as a function of the minimum stomatal conductance (g0), the relative diffusivity of water vapor with respect to CO2 (Drel), the Medlyn term (unitless), the biochemical demand for CO2 (An), and the atmospheric concentration of CO2 (ca).

This returns the conductance in units of mol/m^2/s. It must be converted to m/s using the molar density of water prior to use in SurfaceFluxes.jl.

medlyn_term(g1::FT, T_air::FT, P_air::FT, q_air::FT, thermo_params) where {FT}

Computes the Medlyn term, equal to 1+g1/sqrt(VPD), by first computing the VPD, where VPD is the vapor pressure deficit in the atmosphere (Pa), and g_1 is a constant with units of sqrt(Pa).

thermo_params is the Thermodynamics.jl parameter set.

moisture_stress(pl::FT,
                sc::FT,
                pc::FT) where {FT}

Computes the moisture stress factor (β), which is unitless, as a function of a constant (sc, 1/Pa), a reference pressure (pc, Pa), and the leaf water pressure (pl, Pa) .

See Eqn 12.57 of G. Bonan's textbook, Climate Change and Terrestrial Ecosystem Modeling (2019).

net_photosynthesis(Ac::FT,
                   Aj::FT,
                   Rd::FT,
                   β::FT) where {FT}

Computes the total net carbon assimilation (An), in units of mol CO2/m^2/s, as a function of the Rubisco limiting factor (Ac), the electron transport limiting rate (Aj), dark respiration (Rd), and the moisture stress factor (β).

See Table 11.5 of G. Bonan's textbook, Climate Change and Terrestrial Ecosystem Modeling (2019).

nitrogen_content(
                 ne::FT, # Mean leaf nitrogen concentration (kg N (kg C)-1)
                 Vcmax25::FT, #
                 LAI::FT, # Leaf area index
                 SAI::FT,
                 RAI::FT,
                 ηsl::FT, # live stem  wood coefficient (kg C m-3) 
                 h::FT, # canopy height (m)
                 σl::FT # Specific leaf density (kg C m-2 [leaf])
                 μr::FT, # Ratio root nitrogen to top leaf nitrogen (-), typical value 1.0
                 μs::FT, # Ratio stem nitrogen to top leaf nitrogen (-), typical value 0.1 
                ) where {FT}

Computes the nitrogen content of leafs (Nl), roots (Nr) and stems (Ns).

optimalitymaxphotosynthetic_rates(APAR::FT, θj::FT, ϕ::FT, oi::FT, ci::FT, Γstar::FT, Kc::FT, Ko::FT)

Computes the photosynthesis rates Vcmax and Jmax in mol/m^2/s given absorbed photosynthetically active radiation (APAR), an empirical "curvature parameter" (θj; Bonan Eqn 11.21) the quantum yield of photosystem II (ϕ), the intercellular o2 content (oi), the intercellular CO2 concentration (ci), Γstar, and Kc and Ko.

See Smith et al. 2019.

penman_monteith(
    Δ::FT, # Rate of change of saturation vapor pressure with air temperature. (Pa K−1)  
    Rn::FT, # Net irradiance (W m−2)
    G::FT, # Ground heat flux (W m−2)
    ρa::FT, # Dry air density (kg m−3)
    cp::FT, # Specific heat capacity of air (J kg−1 K−1) 
    VPD::FT, # vapor pressure deficit (Pa)
    ga::FT, # atmospheric conductance (m s−1)
    γ::FT, # Psychrometric constant (γ ≈ 66 Pa K−1)
    gs::FT, # surface or stomatal conductance (m s−1)
    Lv::FT, # Volumetric latent heat of vaporization (J m-3)
    ) where {FT}

Computes the evapotranspiration in m/s using the Penman-Monteith equation.

plant_absorbed_pfd(
    RT::BeerLambertModel{FT},
    SW_IN:FT,
    α_leaf::FT,
    LAI::FT,
    K::FT,
    α_soil::FT
)

Computes the absorbed, reflected, and transmitted photon flux density in terms of mol photons per m^2 per second for a radiation band.

This applies the Beer-Lambert law, which is a function of incident radiation (SW_IN; moles of photons/m^2/), leaf reflectance (α_leaf), the extinction coefficient (K), leaf area index (LAI), and the albedo of the soil (α_soil).

Returns a tuple of reflected, absorbed, and transmitted radiation in mol photons/m^2/s.

plant_absorbed_pfd(
    RT::TwoStreamModel{FT},
    α_leaf,
    SW_IN::FT,
    LAI::FT,
    K::FT,
    τ_leaf,
    θs::FT,
    α_soil::FT,
)

Computes the absorbed, transmitted, and reflected photon flux density in terms of mol photons per m^2 per second for a 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, solar zenith angle, and τ.

Returns a tuple of reflected, absorbed, and transmitted radiation in mol photons/m^2/s.

plant_respiration_growth(
    f::FT, # Factor of relative contribution
    An::FT, # Net photosynthesis
    Rpm::FT # Plant maintenance respiration
    ) where {FT}

Computes plant growth respiration as a function of net photosynthesis (An), plant maintenance respiration (Rpm), and a relative contribution factor, f.

plant_respiration_maintenance(
    Rd::FT, # Dark respiration
    β::FT, # Soil moisture factor
    Nl::FT, # Nitrogen content of leafs
    Nr::FT, # Nitrogen content of roots
    Ns::FT, # Nitrogen content of stems
    f::FT # Factor to convert from mol CO2 to kg C
    ) where {FT}

Computes plant maintenance respiration as a function of dark respiration (Rd), the nitrogen content of leafs (Nl), roots (Nr) and stems (Ns), and the soil moisture factor (β).

root_energy_flux_per_ground_area!(
    fa_energy::ClimaCore.Fields.Field,
    s::PrescribedSoil,
    model::AbstractCanopyEnergyModel{FT},
    Y::ClimaCore.Fields.FieldVector,
    p::NamedTuple,
    t,
) where {FT}

A method which updates the ClimaCore.Fields.Field fa_energy in place with the energy flux associated with the root-soil water flux for the CanopyModel run in standalone mode, with a PrescribedSoil model.This value is ignored and set to zero in this case.

Background information: This energy flux is not typically included in land surface models. We account for it when the soil model is prognostic because the soil model includes the energy in the soil water in its energy balance; therefore, in order to conserve energy, the canopy model must account for it as well.

rubisco_assimilation(::C3,
                     Vcmax::FT,
                     ci::FT,
                     Γstar::FT,
                     Kc::FT,
                     Ko::FT,
                     oi::FT) where {FT}

Computes the Rubisco limiting rate of photosynthesis for C3 plants (Ac), in units of moles CO2/m^2/s, as a function of the maximum rate of carboxylation of Rubisco (Vcmax), the leaf internal carbon dioxide partial pressure (ci), the CO2 compensation point (Γstar), and Michaelis-Menten parameters for CO2 and O2, respectively, (Kc) and (Ko).

The empirical parameter oi is equal to 0.209 (mol/mol). See Table 11.5 of G. Bonan's textbook, Climate Change and Terrestrial Ecosystem Modeling (2019).

rubisco_assimilation(::C4, Vcmax::FT,_...) where {FT}

Computes the Rubisco limiting rate of photosynthesis for C4 plants (Ac) in units of moles CO2/m^2/s, as equal to the maximum rate of carboxylation of Rubisco (Vcmax).

 set_canopy_prescribed_field!(component::AbstractCanopyComponent,
                              p,
                              t,
                             ) end

Updates the spatio-temporally varying prescribed fields of the component with their values at time t.

These fields are stored in the aux-state, and currently are updated at the beginning of the update_aux! function. Any required order of operations must be enforced by the developer who writes the update_aux! function.

update_photosynthesis!(Rd, An, Vcmax25,
    model::FarquharModel,
    T,
    APAR,
    β,
    medlyn_factor,
    c_co2,
    R,
)

Computes the net photosynthesis rate An for the Farquhar model, along with the dark respiration Rd, and updates them in place.

To do so, we require the canopy leaf temperature T, Medlyn factor, APAR in photons per m^2 per second, CO2 concentration in the atmosphere, moisture stress factor β (unitless), and the universal gas constant R.

update_photosynthesis!(Rd, An, Vcmax25,
    model::OptimalityFarquharModel,
    T,
    APAR,
    β,
    medlyn_factor,
    c_co2,
    R,
)

Computes the net photosynthesis rate An for the Optimality Farquhar model, along with the dark respiration Rd, and the value of Vcmax25, and updates them in place.

To do so, we require the canopy leaf temperature T, Medlyn factor, APAR in photons per m^2 per second, CO2 concentration in the atmosphere, moisture stress factor β (unitless), and the universal gas constant R.

upscale_leaf_conductance(gs::FT, LAI::FT, T::FT, R::FT, P::FT) where {FT}

This currently takes a leaf conductance (moles per leaf area per second) and (1) converts it to m/s, (2) upscales to the entire canopy, by assuming the leaves in the canopy are in parallel and hence multiplying by LAI.

TODO: Check what CLM does, and check if we can use the same function for GPP from An, and make more general.

auxiliarydomainnames(m::AbstractCanopyComponent)

Returns the domain names for the auxiliary variables in the form of a tuple.

ClimaLand.auxiliary_types(::AbstractCanopyComponent)

Returns the auxiliary types of the canopy component passed in as an argument.

auxiliary_types(canopy::CanopyModel)

Returns the auxiliary types for the canopy model by looping over each sub-component name in canopy_components.

This relies on the propertynames of CanopyModel being the same as those returned by canopy_components.

ClimaLand.auxiliary_vars(::AbstractCanopyComponent)

Returns the auxiliary types of the canopy component passed in as an argument.

auxiliary_vars(canopy::CanopyModel)

Returns the auxiliary variables for the canopy model by looping over each sub-component name in canopy_components.

This relies on the propertynames of CanopyModel being the same as those returned by canopy_components.

ClimaLand.displacment_height(model::CanopyModel, Y, p)

A helper function which returns the displacement height for the canopy model.

See Cowan 1968; Brutsaert 1982, pp. 113–116; Campbell and Norman 1998, p. 71; Shuttleworth 2012, p. 343; Monteith and Unsworth 2013, p. 304.

initialize_auxiliary(
    component::AbstractCanopyComponent,
    state,
)

Creates and returns a ClimaCore.Fields.FieldVector with the auxiliary variables of the canopy component component, stored using the name of the component.

The input state is usually a ClimaCore Field object.

initialize_auxiliary(
    model::CanopyModel{FT},
    coords,
) where {FT}

Creates the auxiliary state vector of the CanopyModel and returns it as a ClimaCore.Fields.FieldVector.

The input coords is usually a ClimaCore Field object.

This function loops over the components of the CanopyModel and appends each component models auxiliary state vector into a single state vector, structured by component name.

initialize_prognostic(
    component::AbstractCanopyComponent,
    state,
)

Creates and returns a ClimaCore.Fields.FieldVector with the prognostic variables of the canopy component component, stored using the name of the component.

The input state is usually a ClimaCore Field object.

initialize_prognostic(
    model::CanopyModel{FT},
    coords,
) where {FT}

Creates the prognostic state vector of the CanopyModel and returns it as a ClimaCore.Fields.FieldVector.

The input state is usually a ClimaCore Field object.

This function loops over the components of the CanopyModel and appends each component models prognostic state vector into a single state vector, structured by component name.

 ClimaLand.make_compute_exp_tendency(component::AbstractCanopyComponent, canopy)

Creates the computeexptendency!(dY,Y,p,t) function for the canopy component.

Since component models are not standalone models, other information may be needed and passed in (via the canopy model itself). The right hand side for the entire canopy model can make use of these functions for the individual components.

make_compute_exp_tendency(canopy::CanopyModel)

Creates and returns the computeexptendency! for the CanopyModel.

 ClimaLand.make_update_aux(canopy::CanopyModel{FT,
                                              <:AutotrophicRespirationModel,
                                              <:Union{BeerLambertModel, TwoStreamModel},
                                              <:FarquharModel,
                                              <:MedlynConductanceModel,
                                              <:PlantHydraulicsModel,},
                          ) where {FT}

Creates the update_aux! function for the CanopyModel; a specific method for update_aux! for the case where the canopy model components are of the type in the parametric type signature: AutotrophicRespirationModel, AbstractRadiationModel, FarquharModel, MedlynConductanceModel, and PlantHydraulicsModel.

Please note that the plant hydraulics model has auxiliary variables that are updated in its prognostic compute_exp_tendency! function. While confusing, this is better for performance as it saves looping over the state vector multiple times.

The other sub-components rely heavily on each other, so the version of the CanopyModel with these subcomponents has a single update_aux! function, given here.

prognosticdomainnames(m::AbstractCanopyComponent)

Returns the domain names for the prognostic variables in the form of a tuple.

ClimaLand.prognostic_types(::AbstractCanopyComponent)

Returns the prognostic types of the canopy component passed in as an argument.

prognostic_types(canopy::CanopyModel)

Returns the prognostic types for the canopy model by looping over each sub-component name in canopy_components.

This relies on the propertynames of CanopyModel being the same as those returned by canopy_components.

ClimaLand.prognostic_vars(::AbstractCanopyComponent)

Returns the prognostic vars of the canopy component passed in as an argument.

prognostic_vars(canopy::CanopyModel)

Returns the prognostic variables for the canopy model by looping over each sub-component name in canopy_components.

This relies on the propertynames of CanopyModel being the same as those returned by canopy_components.

ClimaLand.surface_height(model::CanopyModel, Y, _...)

A helper function which returns the surface height for the canopy model, which is stored in the parameter struct.

ClimaLand.surface_resistance(
    model::CanopyModel{FT},
    Y,
    p,
    t,
) where {FT}

Returns the stomatal resistance field of the CanopyModel canopy.

ClimaLand.surface_specific_humidity(model::CanopyModel, Y, p)

A helper function which returns the surface specific humidity for the canopy model, which is stored in the aux state.

ClimaLand.surface_temperature(model::CanopyModel, Y, p, t)

A helper function which returns the temperature for the canopy model.

AbstractCarbonSource{FT} <: ClimaLand.AbstractSource{FT}

An abstract type for soil CO2 sources. There are two sources: roots and microbes, in struct RootProduction and MicrobeProduction.

AbstractSoilBiogeochemistryModel{FT} <: ClimaLand.AbstractExpModel{FT}

An abstract model type for soil biogeochemistry models.

AbstractSoilDriver

An abstract type for drivers of soil CO2 production and diffusion. These are soil temperature, soil moisture, root carbon, soil organic matter and microbe carbon, and atmospheric pressure. Soil temperature and moisture, as well as soc, vary in space (horizontally and vertically) and time. Atmospheric pressure vary in time (defined at the surface only, not with depth).

AtmosCO2StateBC <: ClimaLand.AbstractBC

Set the CO2 concentration to the atmospheric one.

MicrobeProduction{FT} <: AbstractCarbonSource{FT}

Struct for the microbe production of CO2, appearing as a source term in the differential equation.

PrescribedMet <: AbstractSoilDriver

A container which holds the prescribed functions for soil temperature and moisture.

This is meant for use when running the biogeochemistry model in standalone mode, without a prognostic soil model.

• temperature: The temperature of the soil, of the form f(z::FT,t) where FT <: AbstractFloat

• volumetric_liquid_fraction: Soil moisture, of the form f(z::FT,t) FT <: AbstractFloat

• ν: Soil porosity (m³ m⁻³)

• θ_a100: Air-filled porosity at soil water potential of -100 cm H₂O (~ 10 Pa)

• b: Absolute value of the slope of the line relating log(ψ) versus log(S) (unitless)

SoilCO2FluxBC <: ClimaLand.AbstractBC

A container holding the CO2 flux boundary condition, which is a function f(p,t), where p is the auxiliary state vector.

SoilCO2Model

A model for simulating the production and transport of CO₂ in the soil with dynamic source and diffusion terms.

• parameters: the parameter set

• domain: the soil domain, using ClimaCore.Domains

• boundary_conditions: the boundary conditions, of type NamedTuple

• sources: A tuple of sources, each of type AbstractSource

• drivers: Drivers

SoilCO2Model{FT}(; parameters::SoilCO2ModelParameters{FT}, domain::ClimaLand.AbstractDomain, boundary_conditions::NamedTuple, sources::Tuple, drivers::DT, ) where {FT, BC, DT}

A constructor for SoilCO2Model.

SoilCO2ModelParameters{FT <: AbstractFloat, PSE}

A struct for storing parameters of the SoilCO2Model.

All of these parameters are currently treated as global constants.

• D_ref: Diffusion coefficient for CO₂ in air at standard temperature and pressure (m² s⁻¹)

• D_liq: Diffusivity of soil C substrate in liquid (unitless)

• α_sx: Pre-exponential factor (kg C m-3 s-1)

• Ea_sx: Activation energy (J mol-1)

• kM_sx: Michaelis constant (kg C m-3)

• kM_o2: Michaelis constant for O2 (m3 m-3)

• O2_a: Volumetric fraction of O₂ in the soil air, dimensionless

• D_oa: Diffusion coefficient of oxygen in air, dimensionless

• p_sx: Fraction of soil carbon that is considered soluble, dimensionless

• earth_param_set: Physical constants used Clima-wide

SoilCO2StateBC <: ClimaLand.AbstractBC

A container holding the CO2 state boundary condition (kg CO2 m−3), which is a function f(p,t), where p is the auxiliary state vector.

SoilDrivers

A container which passes in the soil drivers to the biogeochemistry model. These drivers are either of type Prescribed (for standalone mode) or Prognostic (for running with a prognostic model for soil temp and moisture).

• met: Soil temperature and moisture drivers - Prescribed or Prognostic

• soc: Soil SOM driver - Prescribed only

• atmos: Prescribed atmospheric variables

co2_diffusivity(
                T_soil::FT,
                θ_w::FT,
                P_sfc::FT,
                θ_a100::FT,
                b::FT,
                ν::FT,
                params::SoilCO2ModelParameters{FT},
                ) where {FT}

Computes the diffusivity of CO₂ within the soil (D).

First, D0 is computed using the temperature within the soil (T_soil in K) and pressure at the surface of the soil (P_sfc in Pa), using reference values of T_ref and P_ref (273 K and 101325 Pa). Here, θ_a is the volumetric air content and θ_a100 is the volumetric air content at a soil water potential of 100cm, and b is the pore size distribution of the soil.

This parameterization is from Ryan et al., GMD 11, 1909-1928, 2018, https://doi.org/10.5194/gmd-11-1909-2018.

microbe_source(T_soil::FT,
               θ_l::FT,
               Csom::FT,
               ν::FT,
               params::SoilCO2ModelParameters{FT}
               ) where {FT}

Computes the CO₂ production in the soil by microbes, in depth and time (kg C / m^3/s), using the Dual Arrhenius Michaelis Menten model (Davidson et al., 2012).

soil_moisture(driver::PrescribedMet, p, Y, t, z)

Returns the soil moisture at location (z) and time (t) for the prescribed soil case.

soil_temperature(driver::PrescribedMet, p, Y, t, z)

Returns the soil temperature at location (z) and time (t) for the prescribed soil case.

volumetric_air_content(θ_w::FT,
                       ν::FT,
                       ) where {FT}

Computes the volumetric air content (θ_a) in the soil, which is related to the total soil porosity (ν) and volumetric soil water content (θ_w = θ_l+θ_i).

ClimaLand.boundary_flux(
bc::AtmosCO2StateBC,
boundary::ClimaLand.TopBoundary,
Δz::ClimaCore.Fields.Field,
Y::ClimaCore.Fields.FieldVector,
p::NamedTuple,
t,
)::ClimaCore.Fields.Field

A method of ClimaLand.boundary_flux which returns the soilco2 flux in the case when the atmospheric CO2 is ued at top of the domain.

ClimaLand.boundary_flux(
    bc::SoilCO2FluxBC,
    boundary::ClimaLand.AbstractBoundary,
    Δz::ClimaCore.Fields.Field,
    Y::ClimaCore.Fields.FieldVector,
    p::NamedTuple,
    t,
)::ClimaCore.Fields.Field

A method of ClimaLand.boundary_flux which returns the soilco2 flux (kg CO2 /m^2/s) in the case of a prescribed flux BC at either the top or bottom of the domain.

ClimaLand.boundary_flux(
    bc::SoilCO2StateBC,
    boundary::ClimaLand.BottomBoundary,
    Δz::ClimaCore.Fields.Field,
    Y::ClimaCore.Fields.FieldVector,
    p::NamedTuple,
    t,
)::ClimaCore.Fields.Field

A method of ClimaLand.boundary_flux which returns the soilco2 flux in the case of a prescribed state BC at bottom of the domain.

ClimaLand.boundary_flux(
bc::SoilCO2StateBC,
boundary::ClimaLand.TopBoundary,
Δz::ClimaCore.Fields.Field,
Y::ClimaCore.Fields.FieldVector,
p::NamedTuple,
t,
)::ClimaCore.Fields.Field

A method of ClimaLand.boundary_flux which returns the soilco2 flux in the case of a prescribed state BC at top of the domain.

make_compute_exp_tendency(model::SoilCO2Model)

An extension of the function make_compute_exp_tendency, for the soilco2 equation. This function creates and returns a function which computes the entire right hand side of the PDE for C, and updates dY.soil.C in place with that value. These quantities will be stepped explicitly.

This has been written so as to work with Differential Equations.jl.

make_update_aux(model::SoilCO2Model)

An extension of the function make_update_aux, for the soilco2 equation. This function creates and returns a function which updates the auxiliary variables p.soil.variable in place. This has been written so as to work with Differential Equations.jl.

ClimaLand.source!(dY::ClimaCore.Fields.FieldVector,
                      src::MicrobeProduction,
                      Y::ClimaCore.Fields.FieldVector,
                      p::NamedTuple,
                      params)

A method which extends the ClimaLand source! function for the case of microbe production of CO2 in soil.

add_diagnostic_variable!(; short_name,
                           long_name,
                           standard_name,
                           units,
                           description,
                           compute!)

Add a new variable to the ALL_DIAGNOSTICS dictionary (this function mutates the state of ClimaLand.ALL_DIAGNOSTICS).

If possible, please follow the naming scheme outline in https://airtable.com/appYNLuWqAgzLbhSq/shrKcLEdssxb8Yvcp/tblL7dJkC3vl5zQLb

Keyword arguments

• short_name: Name used to identify the variable in the output files and in the file names. Short but descriptive. ClimaLand diagnostics are identified by the short name. We follow the Coupled Model Intercomparison Project conventions.

• long_name: Name used to identify the variable in the output files.

• standard_name: Standard name, as in http://cfconventions.org/Data/cf-standard-names/71/build/cf-standard-name-table.html

• units: Physical units of the variable.

• comments: More verbose explanation of what the variable is, or comments related to how it is defined or computed.

• compute!: Function that compute the diagnostic variable from the state. It has to take two arguments: the integrator, and a pre-allocated area of memory where to write the result of the computation. If no pre-allocated area is available, a new one will be allocated. To avoid extra allocations, this function should perform the calculation in-place (i.e., using .=).

function common_diagnostics(
                            period,
                            reduction,
                            output_writer,
                            t_start,
                            short_names...;
                            pre_output_hook! = nothing,
                           )

Helper function to define functions like daily_max.

daily_max(short_names; output_writer, t_start)

Return a ScheduledDiagnostics that computes the daily max for the given variable.

daily_maxs(short_names...; output_writer, t_start)

Return a list of ScheduledDiagnostics that compute the daily max for the given variables.

daily_min(short_names; output_writer, t_start)

Return a ScheduledDiagnostics that computes the daily min for the given variable.

daily_mins(short_names...; output_writer, t_start)

Return a list of ScheduledDiagnostics that compute the daily min for the given variables.

define_diagnostics!(land_model)

Calls add_diagnostic_variable! for all available variables specializing the compute function for land_model.

get_diagnostic_variable!(short_name)

Return a DiagnosticVariable from its short_name, if it exists.

hourly_average(short_names...; output_writer, t_start)

Return a ScheduledDiagnostics that computes the hourly average for the given variable.

hourly_averages(short_names...; output_writer, t_start)

Return a list of ScheduledDiagnostics that compute the hourly average for the given variables.

hourly_max(short_names; output_writer, t_start)

Return a ScheduledDiagnostics that computes the hourly max for the given variable.

hourly_maxs(short_names...; output_writer, t_start)

Return a list of ScheduledDiagnostics that compute the hourly max for the given variables.

hourly_mins(short_names...; output_writer, t_start)

Return a ScheduledDiagnostics that computes the hourly min for the given variable.

hourly_mins(short_names...; output_writer, t_start)

Return a list of ScheduledDiagnostics that compute the hourly min for the given variables.

monthly_max(short_names; output_writer, t_start)

Return a ScheduledDiagnostics that computes the monthly max for the given variable.

A month is defined as 30 days.

monthly_maxs(short_names...; output_writer, t_start)

Return a list of ScheduledDiagnostics that compute the monthly max for the given variables.

A month is defined as 30 days.

monthly_min(short_names; output_writer, t_start)

Return a ScheduledDiagnostics that computes the monthly min for the given variable.

A month is defined as 30 days.

monthly_mins(short_names...; output_writer, t_start)

Return a list of ScheduledDiagnostics that compute the monthly min for the given variables.

tendaily_max(short_names; output_writer, t_start)

Return a ScheduledDiagnostics that computes the max over ten days for the given variable.

tendaily_maxs(short_names...; output_writer, t_start)

Return a list of ScheduledDiagnostics that compute the max over ten days for the given variables.

tendaily_min(short_names; output_writer, t_start)

Return a ScheduledDiagnostics that computes the min over ten days for the given variable.

tendaily_mins(short_names...; output_writer, t_start)

Return a list of ScheduledDiagnostics that compute the min over ten days for the given variables.

bareground_albedo_dataset_path()

Triggers the download of the average bareground land albedo dataset, if not already downloaded, using Julia Artifacts, and returns the path to this file.

This dataset does not contain a time component.

cesm2_albedo_dataset_path()

Triggers the download of the CESM2 land albedo dataset, if not already downloaded, using Julia Artifacts, and returns the path to this file.

This dataset contains monthly albedo data from 15/01/1850 to 15/12/2014.

era5_land_forcing_data2021_path(; context)

Return the path to the folder that contains the ERA5 data.

esm_snowmip_data_path(; site_ID = "cdp", context = nothing)

Returns the paths to the Col de Porte met data file and snow data file from the ESM-SnowMIP data set.

Citation: Menard, Cecile; Essery, Richard (2019): ESM-SnowMIP meteorological and evaluation datasets at ten reference sites (in situ and bias corrected reanalysis data) [dataset]. PANGAEA, https://doi.org/10.1594/PANGAEA.897575, Supplement to: Menard, Cecile; Essery, Richard; Barr, Alan; Bartlett, Paul; Derry, Jeff; Dumont, Marie; Fierz, Charles; Kim, Hyungjun; Kontu, Anna; Lejeune, Yves; Marks, Danny; Niwano, Masashi; Raleigh, Mark; Wang, Libo; Wever, Nander (2019): Meteorological and evaluation datasets for snow modelling at 10 reference sites: description of in situ and bias-corrected reanalysis data. Earth System Science Data, 11(2), 865-880, https://doi.org/10.5194/essd-11-865-2019

Creative Commons Attribution-NonCommercial 4.0 International (CC-BY-NC-4.0)

This dataset is soon to be in ClimaArtifacts and then we can update this function.

experiment_fluxnet_data_path(
    site_ID,
    data_link;
    context = nothing,
)

Return the path to the file that contains a year of fluxnet data corresponding to a site_ID in the set (US-MOz, US-NR1, US-Ha1, US-Var).

Site publications and licenses: US-Ha1:

Urbanski, S., Barford, C., Wofsy, S., Kucharik, C., Pyle, E., Budney, J., McKain, K., Fitzjarrald, D., Czikowsky, M., Munger, J. W. 2007. Factors Controlling CO2 Exchange On Timescales From Hourly To Decadal At Harvard Forest, Journal Of Geophysical Research, 112:G2, .

AmeriFlux FLUXNET: https://doi.org/10.17190/AMF/1871137 Citation: J. William Munger (2022), AmeriFlux FLUXNET-1F US-Ha1 Harvard Forest EMS Tower (HFR1), Ver. 3-5, AmeriFlux AMP, (Dataset). https://doi.org/10.17190/AMF/1871137

AmeriFlux CC-BY-4.0 Policy

US-MOz

Gu, L., Pallardy, S. G., Yang, B., Hosman, K. P., Mao, J., Ricciuto, D., Shi, X., Sun, Y. 2016. Testing a Land Model In Ecosystem Functional Space via a Comparison of Observed and Modeled Ecosystem Responses to Precipitation Regimes and Associated Stresses in a Central U.S. Forest, Journal Of Geophysical Research: Biogeosciences, 121:7, 1884-1902.

AmeriFlux FLUXNET: https://doi.org/10.17190/AMF/1854370 Citation: Jeffrey Wood, Lianhong Gu (2021), AmeriFlux FLUXNET-1F US-MOz Missouri Ozark Site, Ver. 3-5, AmeriFlux AMP, (Dataset). https://doi.org/10.17190/AMF/1854370

AmeriFlux CC-BY-4.0 Policy

US-NR1

Burns, S. P., Blanken, P. D., Turnipseed, A. A., Hu, J., Monson, R. K. 2015. The Influence Of Warm-Season Precipitation On The Diel Cycle Of The Surface Energy Balance And Carbon Dioxide At A Colorado Subalpine Forest Site, Biogeosciences, 12:23, 7349-7377.

AmeriFlux FLUXNET: https://doi.org/10.17190/AMF/1871141 Citation: Peter D. Blanken, Russel K. Monson, Sean P. Burns, David R. Bowling, Andrew A. Turnipseed (2022), AmeriFlux FLUXNET-1F US-NR1 Niwot Ridge Forest (LTER NWT1), Ver. 3-5, AmeriFlux AMP, (Dataset). https://doi.org/10.17190/AMF/1871141

AmeriFlux CC-BY-4.0 License

US-Var

AmeriFlux FLUXNET: https://doi.org/10.17190/AMF/1993904 Citation: Siyan Ma, Liukang Xu, Joseph Verfaillie, Dennis Baldocchi (2023), AmeriFlux FLUXNET-1F US-Var Vaira Ranch- Ione, Ver. 3-5, AmeriFlux AMP, (Dataset). https://doi.org/10.17190/AMF/1993904

AmeriFlux CC-BY-4.0 License

huang_et_al2011_soil_van_genuchten_data(; context=nothing)

Local path to file containing soil van Genuchten parameters as a function of depth for soil from site SV62 in Fort McMurray, Alberta, Canada.

Data was originally collected by Huang, Mingbin, et al. "Infiltration and drainage processes in multi-layered coarse soils." Canadian Journal of Soil Science 91.2 (2011): 169-183 and presented in Table 1b of that work.

https://doi.org/10.4141/cjss09118

lehmann_assouline_or2008_evaporation_data(; context=nothing)

Local path to file containing measured evaporation rate as a function of time for bare soil.

Data was originally collected by Lehmann, Peter, Shmuel Assouline, and Dani Or. "Characteristic lengths affecting evaporative drying of porous media." Physical Review E 77.5 (2008): 056309 and presented in Figure 8 of that work.

https://doi.org/10.1103/PhysRevE.77.056309

mizoguchi1990_soil_freezing_data(; context=nothing)

Local path to file containing soil volumetric content as a function of depth and time during a freezing soil column experiment.

Data was originally collected in Mizoguchi, M. 1990. Water, heat and salt transport in freezing soil, Ph.D. thesis. (In Japanese.) University of Tokyo, Tokyo.

Data was obtained by us from Figure 4 of Hansson, Klas, et al. "Water flow and heat transport in frozen soil: Numerical solution and freeze–thaw applications." Vadose Zone Journal 3.2 (2004): 693-704 using a plot digitizer; we did not quantify uncertainties introduced in this process.

richards_eqn_bonan_data_path(; context = nothing)

Returns the file path for data created solving Richards equation with G. Bonan's matlab code, found here: https://github.com/gbonan/bonanmodeling/tree/master/sp0801

The data files correspond to the clay and sand data set described in that code and in G. Bonan's book, Climate Change and Terrestrial Ecosystem Modeling DOI: https://doi.org/10.1017/9781107339217 Publisher: Cambridge University Press Print publication year: 2019

soil_params_artifact_path(; context)

Return the path to the folder that contains the soil parameters.

topmodel_data_path(; context = nothing)

Returns the path to the file which contains the necessary information for the TOPMODEL runoff parameterization at 2.5 degrees resolution.

This file was created with https://github.com/CliMA/ClimaLand.jl/blob/main/src/standalone/Soil/Runoff/preprocesstopographicindex_simple.jl

using the data provided by Marthews, T.R., Dadson, S.J., Lehner, B., Abele, S., Gedney, N. (2015). High-resolution global topographic index values. NERC Environmental Information Data Centre. (Dataset). https://doi.org/10.5285/6b0c4358-2bf3-4924-aa8f-793d468b92be

This resource is available under the Open Government Licence (OGL), and contains data supplied by Natural Environment Research Council.

This product, High-resolution global topographic index values, has been created with use of data from the HydroSHEDS database which is © World Wildlife Fund, Inc. (2006-2013) and has been used herein under license. The HydroSHEDS database and more information are available at http://www.hydrosheds.org.

Eventually, the script processing this data, and this data, will be added to ClimaArtifacts.

water_conservation_test_data_path(; context = nothing)

Returns the filepaths for data from two simulations of ClimaLand.Soil.RichardsModel; these were carried out with a very small timestep with an explicit timestepper and are used as ground truth for solutions using an implicit timestepper.

Experiment details are in experiments/standalone/Soil/water_conservation.jl.

AbstractConductivityModel{FT <: AbstractFloat}

An abstract type for the plant hydraulics conductivity model.

AbstractPlantHydraulicsModel{FT} <: AbstractCanopyComponent{FT}

An abstract type for plant hydraulics models.

AbstractRetentionModel{FT <: AbstractFloat}

An abstract type for the plant retention curve model.

AbstractTranspiration{FT <: AbstractFloat}

An abstract type for types representing different models of transpiration (Prescribed or Diagnostic)

DiagnosticTranspiration{FT} <: AbstractTranspiration{FT}

A concrete type used for dispatch in the case where transpiration is computed diagnostically, as a function of prognostic variables and parameters, and stored in p during the update_aux! step.

LinearRetentionCurve{FT} <: AbstractRetentionModel{FT}

A concrete type specifying that a linear water retention model is to be used; the struct contains the require parameters for this model.

When ψ = 0, the effective saturation is one, so the intercept is not a free parameter, and only the slope must be specified.

Fields

• a: Bulk modulus of elasticity and slope of potential to volume curve. See also Corcuera, 2002, and Christoffersen, 2016.

PlantHydraulicsModel{FT, PS, T, AA} <: AbstractPlantHydraulicsModel{FT}

Defines, and constructs instances of, the PlantHydraulicsModel type, which is used for simulation flux of water to/from soil, along roots of different depths, along a stem, to a leaf, and ultimately being lost from the system by transpiration. Note that the canopy height is specified as part of the PlantHydraulicsModel, along with the area indices of the leaves, roots, and stems.

This model can also be combined with the soil model using ClimaLand, in which case the prognostic soil water content is used to determine root extraction, and the transpiration is also computed diagnostically. 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:

• n_leaf = 1
• n_stem = 0
• LAI = SAI = RAI = 0.

A plant model can have leaves but no stem, but not vice versa. If n_stem = 0, SAI must be zero.

Finally, the model can be used in Canopy standalone mode by prescribing the soil matric potential at the root tips or flux in the roots. There is also the option (intendend only for debugging) to use a prescribed transpiration rate.

• n_stem: The number of stem compartments for the plant; can be zero

• n_leaf: The number of leaf compartments for the plant; must be >=1

• compartment_midpoints: The height of the center of each leaf compartment/stem compartment, in meters

• compartment_surfaces: The height of the compartments' top faces, in meters. The canopy height is the last element of the vector.

• compartment_labels: The label (:stem or :leaf) of each compartment

• parameters: Parameters required by the Plant Hydraulics model

• transpiration: The transpiration model, of type AbstractTranspiration

PlantHydraulicsParameters

A struct for holding parameters of the PlantHydraulics Model.

• ai_parameterization: The area index model for LAI, SAI, RAI

• ν: porosity (m3/m3)

• S_s: storativity (m3/m3)

• conductivity_model: Conductivity model and parameters

• retention_model: Water retention model and parameters

• root_distribution: Root distribution function P(z)

PrescribedSiteAreaIndex{FT <:AbstractFloat, F <: Function}

A struct containing the area indices of the plants at a specific site; LAI varies in time, while SAI and RAI are fixed. No spatial variation is modeled.

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

• SAI: The constant stem area index (SAI; m2/m2)

• RAI: The constant root area index (RAI; m2/m2)

PrescribedTranspiration{FT, F <: Function} <: AbstractTranspiration{FT}

A concrete type used for dispatch when computing the transpiration from the leaves, in the case where transpiration is prescribed.

Weibull{FT} <: AbstractConductivityModel{FT}

A concrete type specifying that a Weibull conductivity model is to be used; the struct contains the require parameters for this model.

Fields

• K_sat: Maximum Water conductivity in the above-ground plant compartments (m/s) at saturation

• ψ63: The absolute water potential in xylem (or xylem water potential) at which ∼63% of maximum xylem conductance is lost (Liu, 2020).

• c: Weibull parameter c, which controls shape the shape of the conductance curve (Sperry, 2016).

augmented_liquid_fraction(
    ν::FT,
    S_l::FT) where {FT}

Computes the augmented liquid fraction from porosity and effective saturation.

Augmented liquid fraction allows for oversaturation: an expansion of the volume of space available for storage in a plant compartment.

effective_saturation(
    ν::FT,
    ϑ_l::FT) where {FT}

Computes the effective saturation given the augmented liquid fraction.

flux(
    z1,
    z2,
    ψ1,
    ψ2,
    K1,
    K2,
) where {FT}

Computes the water flux given the absolute potential (pressure/(ρg)) at the center of the two compartments z1 and z2, and the conductivity along the flow path between these two points.

We currently assuming an arithmetic mean for mean Ksat between the two points (Bonan, 2019; Zhu, 2008) to take into account the change in Ksat halfway between z1 and z2; this is incorrect for compartments of differing sizes.

hydraulic_conductivity(conductivity_params::Weibull{FT}, ψ::FT) where {FT}

Computes the hydraulic conductivity at a point, using the Weibull formulation, given the potential ψ.

inverse_water_retention_curve(
    ψ::FT,
    b::FT,
    ν::FT,
    S_s::FT) where {FT}

Returns the effective saturation given the potential at a point, according to the linear retention curve model.

lai_consistency_check(
    n_stem::Int64,
    n_leaf::Int64,
    area_index::NamedTuple{(:root, :stem, :leaf), Tuple{FT, FT, FT}},
) where {FT}

Carries out consistency checks using the area indices supplied and the number of stem elements being modeled.

Note that it is possible to have a plant with no stem compartments but with leaf compartments, and that a plant must have leaf compartments (even if LAI = 0).

Specifically, this checks that:

1. n_leaf > 0
2. if LAI is nonzero or SAI is nonzero, RAI must be nonzero.
3. if SAI > 0, nstem must be > 0 for consistency. If SAI == 0, nstem must

be zero.

root_water_flux_per_ground_area!(
    fa::ClimaCore.Fields.Field,
    s::PrescribedSoil,
    model::PlantHydraulicsModel{FT},
    Y::ClimaCore.Fields.FieldVector,
    p::NamedTuple,
    t,
) where {FT}

A method which computes the water flux between the soil and the stem, via the roots, and multiplied by the RAI, in the case of a model running without an integrated soil model.

The returned flux is per unit ground area. This assumes that the stem compartment is the first element of Y.canopy.hydraulics.ϑ_l.

transpiration_per_ground_area(transpiration::DiagnosticTranspiration, Y, p, t)

Returns the transpiration computed diagnostically using local conditions. In this case, it just returns the value which was computed and stored in the aux state during the update_aux! step.

Transpiration should be per unit ground area, not per leaf area.

transpiration_per_ground_area(
    transpiration::PrescribedTranspiration{FT},
    Y,
    p,
    t,
)::FT where {FT}

A method which computes the transpiration in meters/sec between the leaf and the atmosphere, in the case of a standalone plant hydraulics model with prescribed transpiration rate.

Transpiration should be per unit ground area, not per leaf area.

water_retention_curve(
    S_l::FT,
    b::FT,
    ν::FT,
    S_s::FT) where {FT}

Returns the potential ψ given the effective saturation S at a point, according to a linear model for the retention curve with parameters specified by retention_params.

set_canopy_prescribed_field!(component::PlantHydraulics{FT},
                             p,
                             t,
                             ) where {FT}

Sets the canopy prescribed fields pertaining to the PlantHydraulics component (the area indices) with their values at time t.

ClimaLand.auxiliary_types(model::PlantHydraulicsModel{FT}) where {FT}

Defines the auxiliary types for the PlantHydraulicsModel.

auxiliary_vars(model::PlantHydraulicsModel)

A function which returns the names of the auxiliary variables of the PlantHydraulicsModel, the transpiration stress factor β (unitless), the water potential ψ (m), the volume fluxcross section fa (1/s), and the volume fluxroot cross section in the roots fa_roots (1/s), where the cross section can be represented by an area index.

make_compute_exp_tendency(model::PlantHydraulicsModel, _)

A function which creates the computeexptendency! function for the PlantHydraulicsModel. The computeexptendency! function must comply with a rhs function of SciMLBase.jl.

Below, fa denotes a flux multiplied by the relevant cross section (per unit area ground, or area index, AI). The tendency for the ith compartment can be written then as: ∂ϑ[i]/∂t = 1/(AI*dz)[fa[i]-fa[i+1]).

Note that if the area_index is zero because no plant is present, AIdz is zero, and the fluxes fa appearing in the numerator are zero because they are scaled by AI.

To prevent dividing by zero, we change AI/(AI x dz)" to "AI/max(AI x dz, eps(FT))"

ClimaLand.prognostic_types(model::PlantHydraulicsModel{FT}) where {FT}

Defines the prognostic types for the PlantHydraulicsModel.

prognostic_vars(model::PlantHydraulicsModel)

A function which returns the names of the prognostic variables of the PlantHydraulicsModel.

AbstractRunoffModel

The soil runoff models are only to be used with the following boundary condition types:

• ClimaLand.Soil.AtmosDrivenFluxBC
• ClimaLand.Soil.RichardsAtmosDrivenFluxBC.

It must have methods for

• subsurface_runoff_source (defined in this module)
• update_runoff! (defined in this module)
• ClimaLand.source!.

Please see the documentation for these for more details.

Your runoff model must specify the subsurface runoff sink term as well as the surface runoff implementation.

NoRunoff <: AbstractRunoffModel

A concrete type of soil runoff model; the default choice, which does not include any runoff.

TOPMODELRunoff{FT <: AbstractFloat, F <: ClimaCore.Fields.Field} <: AbstractRunoffModel

The TOPMODEL surface runoff parameterization, which is affects the surface boundary condition of the soil model.

The runoff flux is given by Equation 8 of with fsat given by Equation (11), of Niu et al. (2005), "A simple TOPMODEL-based runoff parameterization (SIMTOP) for use in global climate models".

• f_over: A calibrated parameter defining how subsurface runoff decays with depth to water table (1/m ; calibrated)

• f_max: The maximum saturated fraction of a grid cell, computed from the topographic index CDF per grid cell.

• subsurface_source: The subsurface source term corresponding to this implementation of TOPMODEL.

TOPMODELSubsurfaceRunoff{FT} <: AbstractSoilSource{FT}

The TOPMODEL subsurface runoff parameterization, which is implemented as a sink term in the soil equations.

The runoff flux is given by Equation 12 of Niu et al. (2005), "A simple TOPMODEL-based runoff parameterization (SIMTOP) for use in global climate models".

• R_sb: The subsurface runoff flux (m/s) when the depth to the water table = 1/f_over; calibrated

• f_over: A calibrated parameter defining how subsurface runoff decays with depth to water table (1/m ; calibrated)

model_agnostic_volumetric_ice_content(Y, FT)

Helper function which returns the volumetric ice content stored in Y.soil.θ_i, if present, as it is for EnergyHydrologyModels, or else returns a scalar zero of type FT if it is not present, as it is not for RichardsModel.

soil_infiltration_capacity(model::EnergyHydrology, Y, p)

Computes the soil infiltration capacity on the surface space for the full soil model.

Currently approximates ic = -KsatF(θ_i)G(T) at the surface, where F and G are the functions which adjust the conductivity for the presence ice and taking into account the temperature dependence of the viscosity of water.

soil_infiltration_capacity(model::RichardsModel, Y, p)

Computes the soil infiltration capacity on the surface space for Richards model.

Currently approximates ic = -Ksat at the surface.

subsurface_runoff_source(runoff::AbstractRunoffModel)

A helper function which returns the subsurface source of the runoff model runoff.

topmodel_ss_flux(R_sb::FT, f_over::FT, z∇::FT) where {FT}

A pointwise function which returns the subsurface runoff flux, given the depth to the water table z∇>0, and the TOPMODEL parameters Rsb and fover.

see: Niu et al. (2005), "A simple TOPMODEL-based runoff parameterization (SIMTOP) for use in global climate models", Equations (12).

topmodel_surface_infiltration(h∇, f_max, f_over, z∇, f_ic, precip)

A pointwise function which returns the infiltration into the soil, given the precipitation flux (m/s), the water table thickness h∇>=0, the depth to the water table z∇>0, the infiltration capacity flux fic, and the TOPMODEL parameters fmax and f_over.

see: Niu et al. (2005), "A simple TOPMODEL-based runoff parameterization (SIMTOP) for use in global climate models", Equations (8) and (11).

update_runoff!(p, runoff::NoRunoff, _...)

Updates the runoff variables in the cache p.soil in place in the case of NoRunoff: sets infiltration = precipitation.

update_runoff!(p, runoff::TOPMODELRunoff, Y,t, model::AbstractSoilModel)

Updates the runoff model variables in place in p.soil for the TOPMODELRunoff parameterization: p.soil.Rs p.soil.Rss p.soil.h∇ p.soil.infiltration

ClimaLand.source!(
    dY::ClimaCore.Fields.FieldVector,
    src::TOPMODELSubsurfaceRunoff,
    Y::ClimaCore.Fields.FieldVector,
    p::NamedTuple,
    model::AbstractSoilModel{FT},
) where {FT}

Adjusts dY.soil.ϑ_l in place to account for the loss of water due to subsurface runoff.

The sink term is given by - Rss/h∇ H(twc - ν), where H is the Heaviside function, h∇ is the water table thickness (defined to be where twc>ν), where twc is the total water content, and Rss is the runoff as a flux(m/s).