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 ClimaLSM.AbstractModels for the canopy component parameterizations.

An abstract type of soil drivers of the canopy model.

AutotrophicRespirationParameters{FT<:AbstractFloat}

The required parameters for the autrophic respiration model.

• 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 (-)

function AutotrophicRespirationParameters{FT}(;
    ne = FT(8 * 1e-4),
    ηsl = FT(0.01),
    σl = FT(0.05),
    μr = FT(1.0),
    μs = FT(0.1),
    f1 = FT(0.012), 
    f2 = FT(0.25)

) where {FT}

A constructor supplying default values for the AutotrophicRespirationParameters struct.

BeerLambertParameters{FT <: AbstractFloat}

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

• ld: Leaf angle distribution function (unitless)

• α_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)

function BeerLambertParameters{FT}(;
    ld = FT(0.5),
    α_PAR_leaf = FT(0.1),
    α_NIR_leaf = FT(0.4),
    ϵ_canopy = FT(0.98),
    Ω = FT(1),
    λ_γ_PAR = FT(5e-7),
    λ_γ_NIR = FT(1.65e-6),
) where {FT}

A constructor supplying default values for the BeerLambertParameters struct.

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.

 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{
        ClimaLSM.Domains.Point,
        ClimaLSM.Domains.Plane,
        ClimaLSM.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.

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

function FarquharParameters{FT}(mechanism::AbstractPhotosynthesisMechanism;
    oi = FT(0.209),# mol/mol
    ϕ = FT(0.6), # unitless
    θj = FT(0.9), # unitless
    f = FT(0.015), # unitless
    sc = FT(5e-6),# Pa
    pc = FT(-2e6), # Pa
    Vcmax25 = FT(5e-5), # converted from 50 μmol/mol CO2/m^2/s to mol/m^2/s
    Γstar25 = FT(4.275e-5),  # converted from 42.75 μmol/mol to mol/mol
    Kc25 = FT(4.049e-4), # converted from 404.9 μmol/mol to mol/mol
    Ko25 = FT(0.2874), # converted from 278.4 mmol/mol to mol/mol
    To = FT(298.15), # 25 C
    ΔHkc = FT(79430), #J/mol, Table 11.2 Bonan
    ΔHko = FT(36380), #J/mol, Table 11.2 Bonan
    ΔHVcmax = FT(58520), #J/mol, Table 11.2 Bonan
    ΔHΓstar = FT(37830), #J/mol, 11.2 Bonan
    ΔHJmax = FT(43540), # J/mol, 11.2 Bonan
    ΔHRd = FT(43390), # J/mol, 11.2 Bonan
    ) where {FT}

A constructor supplying default values for the FarquharParameters struct.

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})

function MedlynConductanceParameters{FT}(;
    Drel = FT(1.6), # unitless
    g0 =  FT(1e-4), # mol/m^2/s 
    g1 = FT(790) # converted from 5 √kPa to units of √Pa

) where{FT}

A constructor supplying default values for the MedlynConductanceParameters struct.

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)

function OptimalityFarquharParameters{FT}(
    oi = FT(0.209),
    ϕ = FT(0.6),
    θj = FT(0.9),
    f = FT(0.015),
    sc = FT(5e-6),
    pc = FT(-2e6),
    Γstar25 = FT(4.275e-5),
    Kc25 = FT(4.049e-4),
    Ko25 = FT(0.2874),
    To = FT(298.15),
    ΔHkc = FT(79430),
    ΔHko = FT(36380),
    ΔHVcmax = FT(58520),
    ΔHΓstar = FT(37830),
    ΔHJmax = FT(43540),
    ΔHRd = FT(46390),
    c = FT(0.05336251)
)

A constructor supplying default values for the FarquharParameters struct.

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.

• ld: Leaf angle distribution function (unitless)

• α_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 simulate radiative transfer through

function TwoStreamParameters{FT}(;
    ld = FT(0.5),
    α_PAR_leaf = FT(0.3),
    τ_PAR_leaf = FT(0.2),
    α_NIR_leaf = FT(0.4),
    τ_NIR_leaf = FT(0.25),
    ϵ_canopy = FT(0.98),
    Ω = FT(1),
    λ_γ_PAR = FT(5e-7),
    λ_γ_NIR = FT(1.65e-6),
    n_layers = UInt64(20),
) where {FT}

A constructor supplying default values for the TwoStreamParameters struct.

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.

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_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(
    model::AbstractRadiationModel,
    solar_radiation::ClimaLSM.PrescribedRadiativeFluxes,
    p,
    t,
)

Returns 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(
    model::AbstractRadiationModel,
    solar_radiation::ClimaLSM.PrescribedRadiativeFluxes,
    p,
    t,
)

Returns 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,
    _,
    _,
)

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 moles of photons, 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(
    RT::TwoStreamModel{FT},
    PAR,
    NIR,
    LAI,
    K,
    α_soil_PAR,
    α_soil_NIR,
    θ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 moles of photons, 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 = ))

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, SW_IN::FT, RH::FT, θs::FT) 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), the relative humidity (RH), 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
                 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) as a function of leaf area index (LAI), specific leaf density (σl), the carbon content of roots (Rc), the carbon content of stems (Rs), and mean leaf nitrogen concentration (nm).

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
    GPP::FT, # Gross primary productivity
    Rpm::FT # Plant maintenance respiration
    ) where {FT}

Computes plant growth respiration as a function of gross primary productivity (GPP), 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,
                              t0,
                             ) end

Sets the spatially and temporally varying prescribed fields of the component with their initial values.

These fields are stored in the aux-state and should not depend on the prognostic state Y or other diagnostic variables stored in p; this allows them to be updated first, prior to updating the rest of the aux state and prognostic state.

However, there is no guarantee on the order of operations in terms of when diagnostic auxiliary variables are updated vs. prescribed field auxiliary variables; any required order of operations must be enforced by the developer who writes the update_aux function.

 update_canopy_prescribed_field!(component::AbstractCanopyComponent,
                                 p,
                                 t,
                                 ) end

Updates the spatially and temporally varying prescribed fields of the component with their values at time t.

These fields are stored in the aux-state and should not depend on the prognostic state Y or other diagnostic variables stored in p; this allows them to be updated first, prior to updating the rest of the aux state and prognostic state.

However, there is no guarantee on the order of operations in terms of when diagnostic auxiliary variables are updated vs. prescribed field auxiliary variables; 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.

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

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

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

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

ClimaLSM.make_set_initial_cache(model::CanopyModel)

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

In this case, we also use this method to update the initial values for the spatially and temporally varying canopy parameter fields, read in from data files or otherwise prescribed.

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

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

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

ClimaLSM.surface_height(model::CanopyModel, Y, _...)

A helper function which returns the surface height for the canopy model, which is stored in the parameter struct.

ClimaLSM.surface_resistance(
    model::CanopyModel{FT},
    Y,
    p,
    t,
) where {FT}

Returns the surface resistance field of the CanopyModel canopy.

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

ClimaLSM.surface_temperature(model::CanopyModel, Y, p, t)

A helper function which returns the temperature for the canopy model.

 AbstractAtmosphericDrivers{FT <: AbstractFloat}

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

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 <: AbstractFloat}

An abstract type of radiative drivers of land models.

AbstractSource{FT <: AbstractFloat}

An abstract type for types of source terms.

AbstractTridiagonalW

An abstract type for tridiagonal Jacobian matrices.

BottomBoundary{} <: AbstractBoundary{}

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

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

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)

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

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 of the soil.

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{FT},
                                     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{FT},
    model::Canopy.AbstractCanopyEnergyModel{FT},
    Y::ClimaCore.Fields.FieldVector,
    p::NamedTuple,
    t,
) where {FT}

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::ClimaLSM.TopBoundary,
    model::EnergyHydrology{FT},
    Δz,
    Y,
    p,
    t,
) where {FT}

A method of ClimaLSM.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), 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 ClimaLSM.boundary_flux(
    bc::RunoffBC,
    ::TopBoundary,
    model::Soil.RichardsModel,
    Δz::FT,
    Y::ClimaCore.Fields.FieldVector,
    p::NamedTuple,
    t,
    params,
)::ClimaCore.Fields.Field

Extension of the ClimaLSM.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).

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.

construct_atmos_ts(
    atmos::PrescribedAtmosphere,
    p,
    thermo_params,
)

A helper function which constructs a Clima.Thermodynamics thermodynamic state given a PrescribedAtmosphere, the cache p, and a set of Clima.Thermodynamics parameters thermo_params.

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 - as a tuple (atmos, radiation).

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.

 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(d::Union{AbstractAtmosphericDrivers, AbstractRadiativeDrivers, Nothing}, coords)

Creates and returns a NamedTuple with nothing when no driver cache variables are needed.

initialize_drivers(a::Union{AbstractAtmosphericDrivers, Nothing},
                   r::Union{AbstractRadiativeDrivers, Nothing},
                   coords)

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

If no forcing is required, a and r are type Nothing and an empty NamedTuple is returned.

initialize_drivers(r::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(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_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.

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.

compute_imp_tendency! should be compatible with SciMLBase.jl solvers.

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_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_set_initial_cache(land::AbstractLandModel)

Creates and returns the function which sets the initial cache with the correct values given the initial conditions Y0 and initial time t0.

Note that this will call update_drivers! multiple times, once per component model.

maketendencyjacobian(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 tendency_jacobian! should be used as Wfact! in ClimaTimeSteppers.jl and SciMLBase.jl.

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(d::Union{AbstractAtmosphericDrivers, AbstractRadiativeDrivers, Nothing})

Creates and returns a function which updates the driver variables in the case of no driver variables. This is also the default.

make_update_drivers(a::Union{AbstractAtmosphericDrivers, Nothing},
                      r::Union{AbstractRadiativeDrivers, Nothing},
                     )

Creates and returns a function which updates the atmospheric and radiative forcing variables ("drivers").

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

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

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

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

make_update_jacobian(model::AbstractModel)

Creates and returns a function which updates 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, no implicit tendency is present, and hence the timestepping is entirely explicit.

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.

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.

searchsortednearest(a, x)

Find the index corresponding to the nearest value to x in a.

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

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

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

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

thomas_algorithm!(A, b)

Thomas algorithm for solving a linear system A x = b, where A is a tri-diagonal matrix. A and b are overwritten, solution is written to b. Pass this as linsolve to ODEFunction.

to_scalar_coefs(vector_coefs)

Helper function used in computing tendencies of vertical diffusion terms.

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

∂tendencyBC∂Y(::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.

AbstractRunoffModel

The abstract type for soil runoff models to be used with the following boundary condition types:

• ClimaLSM.Soil.AtmosDrivenFluxBC
• ClimaLSM.Soil.RichardsAtmosDrivenFluxBC,

and for these functions: -ClimaLSM.Soil.soil_surface_infiltration

• ClimaLSM.Soil.subsurface_runoff_source
• ClimaLSM.source!.

Please see the documentation for these for more details. The model should specify the subsurface runoff sink term as well as the surface runoff implementation.

AbstractSoilBC <: ClimaLSM. AbstractBC

An abstract type for soil-specific types of boundary conditions, like free drainage.

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} <: ClimaLSM.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} <:  ClimaLSM.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. ClimaLSM.jl creates additional sources to include as necessary e.g. root extraction (not available in stand alone mode).

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

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}

A parameter structure for the integrated soil water and energy equation system. In this simplest form, we assume the conductivity and volumetric heat capacity of the soil are constant.

• κ_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

• ν: 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 Genucthen 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

FluxBC <: AbstractSoilBC

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.

FreeDrainage <: AbstractSoilBC

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

MoistureStateBC <: AbstractSoilBC

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.

NoRunoff <: AbstractRunoffModel

A concrete type of soil runoff model; the default choice which does not include the effects of runoff.

PhaseChange{FT} <: AbstractSoilSource{FT}

PhaseChange source type.

RichardsAtmosDrivenFluxBC{F <: Function, R <: AbstractRunoffModel} <: AbstractSoilBC

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{FT},
    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{FT <: AbstractFloat, C <: AbstractSoilHydrologyClosure}

A struct for storing parameters of the RichardModel.

• ν: 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

RichardsTridiagonalW{R, J, W, T} <: ClimaLSM.AbstractTridiagonalW

A struct containing the necessary information for constructing a tridiagonal Jacobian matrix (W) for solving Richards equation, treating only the vertical diffusion term implicitly.

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

• dtγ_ref: Reference to dtγ, which is specified by the ODE solver

• ∂ϑₜ∂ϑ: Diagonal entries of the Jacobian stored as a ClimaCore.Fields.Field

• W_column_arrays: Array of tridiagonal matrices containing W for each column

• temp1: An allocated cache used to evaluate ldiv!

• temp2: An allocated cache used to evaluate ldiv!

• transform: A flag indicating whether this struct is used to compute Wfact_t or Wfact

• ones_face_space: A pre-allocated cache storing ones on the face space

RichardsTridiagonalW(
    Y::ClimaCore.Fields.FieldVector;
    transform::Bool = false

)

Outer constructor for the RichardsTridiagonalW Jacobian matrix struct.

Initializes all variables to zeros.

TemperatureStateBC <: AbstractSoilBC

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.

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.

boundary_var_domain_names(::AtmosDrivenFluxBC, ::ClimaLSM.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(::AbstractSoilBC, ::ClimaLSM.AbstractBoundary)

The list of domain names for additional variables to add to the soil model auxiliary state, which defaults to adding storage for the boundary flux fields, but which can be extended depending on the type of boundary condition used. Note that extensions to this function must still include a flux bc defined on the surface in addition to other variables.

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

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

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

boundary_var_types(::Soil.EnergyHydrology{FT}, ::NamedTuple, ::ClimaLSM.AbstractBoundary) where {FT}

The list of variable types for additional variables to add to the EnergyHydrology model auxiliary state, which defaults to adding storage for the boundary flux fields, but which can be extended depending on the type of boundary condition used.

Use this function in the exact same way you would use auxiliary_types. Note that extensions to this function must still include a flux bc defined on the surface in addition to other variables.

boundary_var_types(::Soil.RichardsModel{FT}, ::NamedTuple, ::ClimaLSM.AbstractBoundary) where {FT}

The list of variable types for additional variables to add to the Richards model auxiliary state, which defaults to adding storage for the boundary flux fields, but which can be extended depending on the type of boundary condition used.

Since the only prognostic variable for the Richards-Richardson equation is the volumetric water content, only a water flux boundary condition is required per boundary.

Use this function in the exact same way you would use auxiliary_types. Note that extensions to this function must still include a flux bc defined on the surface in addition to other variables.

boundary_vars(::AtmosDrivenFluxBC, ::ClimaLSM.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(::NamedTuple, ::ClimaLSM.BottomBoundary)

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

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

Note that :bottom_bc must be present, with the default type and domain name, for both the RichardsModel and the EnergyHydrology soil models.

boundary_vars(::NamedTuple, ::ClimaLSM.TopBoundary)

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

Note that :top_bc must be present, with the default type and domain name, for both the RichardsModel and the EnergyHydrology soil models.

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

create_soil_bc_named_tuple(water_flux, heat_flux)

A helper function which takes in two scalar values of water_flux and heat_flux, and creates a named tuple out of them.

When broadcasted over two ClimaCore.Fields.Field objects, this returns a Field of NamedTuples which we can access like x.water, x.heat, to obtain the boundary condition fields.

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

Returns the maximum dry soil layer thickness that can develop under evaporation; this is used when computing the soil resistance to evaporation according to Swenson et al (2012).

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.

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.

kersten_number(
    θ_i::FT,
    S_r::FT,
    parameters::EnergyHydrologyParameters{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,
    params::EnergyHydrologyParameters{FT},
) where {FT}

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::ClimaLSM.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::NamedTuple, boundary, model, Δz, Y, p, t)

Returns the boundary fluxes for ϑl and ρeint, in that order.

soil_resistance(θ_l_sfc, ϑ_l_sfc, θ_i_sfc, parameters::EnergyHydrologyParameters::FT)

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_surface_infiltration(::NoRunoff, net_water_flux, _...)

A function which computes the infiltration into the soil for the default of NoRunoff.

If net_water_flux = P+E, where P is the precipitation and E is the evaporation (both negative if towards the soil), this returns P+E as the water boundary flux for the soil.

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.

subsurface_runoff_source(runoff::AbstractRunoffModel)::Union{Nothing, AbstractSoilSource}

A function which returns the soil source for the runoff model runoff; the default returns nothing in which case no source is added.

temperature_from_ρe_int(ρe_int::FT, θ_i::FT, ρc_s::FT
                        parameters::EnergyHydrologyParameters{FT}) where {FT}

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,
    parameters::EnergyHydrologyParameters{FT},
) where {FT}

Compute the expression for volumetric heat capacity.

volumetric_internal_energy(θ_i::FT, ρc_s::FT, T::FT,
                             parameters::EnergyHydrologyParameters{FT}) where {FT}

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, parameters::EnergyHydrologyParameters{FT}) where {FT}

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.

ClimaLSM.boundary_flux(bc::FluxBC,  _...)::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.

ClimaLSM.boundary_flux(bc::FreeDrainage,
                       boundary::ClimaLSM.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.

ClimaLSM.boundary_flux(rre_bc::MoistureStateBC,
                       ::ClimaLSM.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.

ClimaLSM.boundary_flux(rre_bc::MoistureStateBC,
                       ::ClimaLSM.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.

ClimaLSM.boundary_flux(bc::RichardsAtmosDrivenFluxBC,
                       boundary::ClimaLSM.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.

ClimaLSM.boundary_flux(heat_bc::TemperatureStateBC,
                       ::ClimaLSM.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.

ClimaLSM.boundary_flux(heat_bc::TemperatureStateBC,
                       ::ClimaLSM.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.

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

ClimaLSM.make_update_jacobian(model::RichardsModel{FT}) where {FT}

Creates and returns the update_jacobian! function for RichardsModel.

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

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.

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

Computes the source terms for phase change.

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

Returns the surface albedo field of the EnergyHydrology soil model.

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

Returns the surface emissivity field of the EnergyHydrology soil model.

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

Returns the surface height of the EnergyHydrology model.

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

Returns the surface resistance field of the EnergyHydrology soil model.

ClimaLSM.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 surface specific humidity 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.

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

ClimaLSM.∂tendencyBC∂Y(
    ::AbstractSoilModel,
    ::AbstractSoilBC,
    boundary::ClimaLSM.TopBoundary,
    Δz,
    Y,
    p,
    t,

)

A default method which computes and returns the zero for the derivative of the part of the implicit tendency in the top layer, due to the boundary condition, with respect to the state variable in the top layer.

For a diffusion equation like Richards equation with a single state variable, this is given by ∂T_N∂Y_N = [-∂/∂z(∂F_bc/∂Y_N)]_N, where N indicates the top layer cell index.

If F_bc can be approximated as independent of Y_N, the derivative is zero.

ClimaLSM.∂tendencyBC∂Y(
    model::RichardsModel,
    ::MoistureStateBC,
    boundary::ClimaLSM.TopBoundary,
    Δz,
    Y,
    p,
    t,

)

Computes and returns the derivative of the part of the implicit tendency in the top layer, due to the boundary condition, with respect to the state variable in the top layer.

For a diffusion equation like Richards equation with a single state variable, this is given by ∂T_N∂Y_N = [-∂/∂z(∂F_bc/∂Y_N)]_N, where N indicates the top layer cell index.

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_tags: Boundary face identifiers

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

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_tags 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

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
    ) 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 ClimaLSM 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 ClimaLSM. In long term, we will repeat the same for all ClimaLSM 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

SphericalShell(;
    radius::FT,
    depth::FT,
    nelements::Tuple{Int, Int},
    npolynomial::Int,
    dz_tuple::Union{Tuple{FT, FT}, Nothing} = nothing,
) 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,
) where {FT}

Outer constructor for the SphericalSurface domain, using keyword arguments.

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.

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

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.

LinearModel(data, vars, target; dtype, scale_const)

Create a linear regression model on a data frame for comparison to neural model. Returns the coefficients for the model.

Arguments

• data::DataFrame: The data set to be utilized.
• vars::Vector{Symbol}: The input variables to be used in the model creation.
• target::Symbol: The target variable to be used in the model ceation.
• dtype::Type: Sets type, consistent with neural model. Default is Float32.
• scale_const: Optional scaling constant for model output. Default is 1.0.

LinearModel(x_train, y_train; dtype, scale_const)

Create a linear regression model on a training matrix for comparison to neural model. Returns the coefficients for the model. **Note: using the same matrices input to the neural model will require a transpose of xtrain, ytrain

Arguments

• x_train::Matrix: The input to be utilized.
• y_train::Vector: The output data to be utilized.
• dtype::Type: Sets type, consistent with neural model. Default is Float32.
• scale_const: Optional scaling constant for model output. Default is 1.0.

custom_loss(x, y, model, n1, n2)

Creates a loss function to be used during training specified by two hyperparameters n1, n2, as outlined in the paper.

Arguments

• x: the input values.
• y: output values to compare to.
• model: the model over which to evaluate the loss function.
• n1::Int: the hyperparameter dictating the scaling of mismatch error.
• n2::Int: the hyperparameter dictating the weighting of a given mismatch error by the target magnitude.

evaluate(model, input)

Evaluate a created model on a given input vector.

Arguments

• model::Chain: A neural model to be used for prediction.
• input: The input data used to generate a prediction.

evaluate(model, input)

Evaluate a created model on a given input vector.

Arguments

• model::Vector{<:Real}: Linear regression coefficients used for prediction.
• input: The input data used to generate a prediction.

get_model_ps(model)

Return the trainable weights for the developed neural model.

Arguments

• model::Chain: the neural model to be used.

make_model(nfeatures, n, z_idx, p_idx; in_scale, dtype)

Create the neural network to be trained, with initial scaling weights.

Arguments

• nfeatures::Int: indicates number of features.
• n::Int: the value of the hyperparameter n.
• z_idx::Int: The index of the data vectors pertaining to the depth (z) values.
• p_idx::Int: The index of the data vectors pertaining to the precipitation values.
• in_scale::Vector{<:Real}: Optional scaling constants for each input feature.
• dtype::Type: Sets type of output model. Default is Float32.

make_timeseries(model, timeseries, dt; predictvar, timevar, inputvars, dtype, hole_thresh)

Generate a predicted timeseries given forcing data and the timestep present in that data (holes acceptable).

Arguments

• model: The model used for forecasting (can be any model with a defined "evaluate" call).
• timeseries::DataFrame: The input data frame used to generate predictions, including a time variable.
• dt::Period: The unit timestep present in the dataframe (i.e. daily dataframe, dt = Day(1) or Second(86400)).
• predictvar::Symbol: The variable to predict from the timeseries. Default is :z.
• timevar::Symbol: The variable giving the time of each forcing. Default is :date.
• inputvars::Vector{Symbol}: The variables (in order), to extract from the data to use for predictions.

Default is [:z, :SWE, :relhumavg, :solradavg, :windspeedavg, :airtempavg, :dprecipdt_snow] like the paper.

• dtype::Type: The data type required for input to the model. Default is Float32.
• hole_thresh::Int: The acceptable number of "holes" in the timeseries for the model to skip over. Default is 30.

setoutscale!(model, scale; dtype)

Set the physical scaling parameter for model usage (i.e. rectifying scaling done on model input).

Arguments

• model::Chain: the neural model to be used.
• scale::Real: the scaling parameter to return data to applicable units.
• dtype::Type: Sets type, consistent with neural model. Default is Float32.

settimescale!(model, dt; dtype)

Set the timescale parameter for model usage.

Arguments

• model::Chain: the neural model to be used.
• dt::Real: the number of seconds per timestep for usage.
• dtype::Type: Sets type, consistent with neural model. Default is Float32.

trainmodel!(model, ps, x_train, y_train, n1, n2; nepochs, opt, verbose, cb)

A training function for a neural model, permitting usage of a callback function.

Arguments

• model: the model used for training.
• ps: the model parameters that will be trained.
• x_train: the input training data to be used in training.
• y_train: the target data to be used in training.
• n1: the scaling hypermarameter used to generate custom loss functions.
• n2: the weighting hyperparameter used to generate custom loss functions.
• nepochs::Int: the number of epochs. Default is 100.
• nbatch::Int: The number of data points to be used per batch. Default is 64.
• opt: the Flux optimizer to be used. Default is RMSProp()
• verbose::Bool: indicates whether to print the training loss every 10 epochs
• cb: Allows utlization of a callback function (must take no required

input arguments, but default optional args are permitted). Default is Nothing.

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 ClimaLSM, 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,
                             t0,
                             ) where {FT}

Sets the canopy prescribed fields pertaining to the PlantHydraulics component (the area indices) with their initial values at time t0.

update_canopy_prescribed_field!(component::PlantHydraulics{FT},
                                p,
                                t,
                                ) where {FT}

Updates the canopy prescribed fields pertaining to the PlantHydraulics component (the LAI only in this case) with their values at time t.

ClimaLSM.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))"

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

FileReader

This module coordinates reading, regridding, and interpolating data from NetCDF files that is required for global land model simulations, including globally varying parameters which may or may not change in time. It also includes regridding and temporal interpolations of this data.

This is based on ClimaCoupler.jl's BCReader and TimeManager modules.

abstract type AbstractPrescribedData

An abstract type for storing prescribed data info. Subtypes include temporally-varying prescribed data and static prescribed data.

FileInfo

Stores information about the current data being read in from a file.

Inputs:

• infile_path::String # path to the input NetCDF data file
• regrid_dirpath::String # directory for storing files used in regridding
• varname::String # name of the variable we're reading from the input file, which we assume is a scalar
• outfile_root::String # root for regridded data files generated when writing data at each time from input file
• all_dates::Vector # vector containing all dates of the input file, which we assume are DateTimes or DateTimeNoLeaps
• date_idx0::Vector{Int} # index of the first data in the file being used for this simulation

FileState

Stores information about the current data being read in from a file.

Inputs:

• data_fields::F # tuple of two fields at consecutive dates, that will be used for interpolation
• date_idx::Vector{Int} # index in the input file of the first data field currently being used
• segment_length::Vector{Int} # length of the time interval between the two data field entries; used in temporal interpolation

PrescribedDataStatic <: AbstractPrescribedData

Stores information to read in a prescribed variable from a file. The data is read in once and stored without changing for the duration of a simulation. This type is meant to be used with input data that does not have a time dimension. Each of the fields of this struct is itself a struct.

Inputs:

• file_info::FI # unchanging info about the input data file

PrescribedDataStatic(
    get_infile::Function,
    regrid_dirpath::String,
    varname::String,
    commx_ctx::ClimaComms.AbstractCommsContext,
)

Constructor for the PrescribedDataStatictype. Creates aFileInfo` object containing all the information needed to read in the data stored in the input file, which will later be regridded to our simulation grid. Date-related args (last 3 to FileInfo) are unused for static data maps.

PrescribedDataTemporal <: AbstractPrescribedData

Stores information to read in a prescribed variable from a file. Contains sufficient information to read in the variable at various timesteps, and to coordinate this reading between variables coming from different files. This type is meant to be used with input data that has a time dimension. Each of the fields of this struct is itself a struct.

Inputs:

• file_info::FI # unchanging info about the input data file
• file_state::FS # info about the dates currently being read from file
• sim_info::S # unchanging info about the start date/time of the simulation

PrescribedDataTemporal{FT}(
    regrid_dirpath,
    get_infile,
    varname,
    date_ref,
    t_start,
    surface_space;
    mono = true,
) where {FT <: AbstractFloat}

Constructor for the PrescribedDataTemporal type. Regrids from the input lat-lon grid to the simulation cgll grid, saving the regridded output in a new file found at regrid_dirpath, and returns the info required to run the simulation using this prescribed data packaged into a single PrescribedDataTemporal struct.

Arguments

• regrid_dirpath # directory the data file is stored in.
• get_infile # function returning path to NCDataset file containing data to regrid.
• varname # name of the variable to be regridded.
• date_ref # reference date to coordinate start of the simulation
• t_start # start time of the simulation relative to date_ref (datestart = dateref + t_start)
• surface_space # the space to which we are mapping.
• mono # flag for monotone remapping of infile_path.

Returns

• PrescribedDataTemporal object

SimInfo

Stores information about the simulation being run. We may want to store multiple copies of an instance of this struct in multiple PrescribedDataTemporal objects if we're reading in data over time for multiple variables.

Inputs:

• date_ref::D # a reference date before or at the start of the simulation
• tstart # time in seconds since `dateref`

interpol(f1::FT, f2::FT, Δt_tt1::FT, Δt_t2t1::FT)

Performs linear interpolation of f at time t within a segment Δt_t2t1 = (t2 - t1), of fields f1 and f2, with t2 > t1.

Arguments

• f1::FT # first value to be interpolated (f(t1) = f1).
• f2::FT # second value to be interpolated.
• Δt_tt1::FT # time between t1 and some t (Δt_tt1 = (t - t1)).
• Δt_t2t1::FT # time between t1 and t2.

Returns

• FT

interpolate_data(prescribed_data::PrescribedDataTemporal, date::Union{DateTime, DateTimeNoLeap}, space::Spaces.AbstractSpace)

Interpolates linearly between two Fields in the prescribed_data struct.

Arguments

• prescribed_data # contains fields to be interpolated.
• date # start date for data.
• space # the space of our simulation.

Returns

• Fields.field

next_date_in_file(prescribed_data::PrescribedDataTemporal)

Returns the next date stored in the file prescribed_data struct after the current date index given by date_idx. Note: this function does not update date_idx, so repeated calls will return the same value unless date_idx is modified elsewhere in between.

Arguments

• prescribed_data # contains all input file information needed for the simulation.

Returns

• DateTime or DateTimeNoLeap

read_data_fields!(prescribed_data::PrescribedDataTemporal, date::DateTime, space::Spaces.AbstractSpace)

Extracts data from regridded (to model grid) NetCDF files. The times for which data is extracted depends on the specifications in the prescribed_data struct). Data at one point in time is stored in prescribed_data.file_state.data_fields[1], and data at the next time is stored in prescribed_data.file_state.data_fields[2]. With these two data fields saved, we can interpolate between them for any dates in this range of time.

Arguments

• prescribed_data # containing parameter value data.
• date # current date to read in data for.
• space # space we're remapping the data onto.

to_datetime(date)

Convert a DateTime-like object (e.g. DateTimeNoLeap) to a DateTime, using CFTime.jl. We need this since the CESM2 albedo file contains DateTimeNoLeap objects for dates, which can't be used for math with DateTimes.

Note that this conversion may fail if the date to convert doesn't exist in the DateTime calendar.

Arguments

• date: object to be converted to DateTime

function hdwrite_regridfile_rll_to_cgll(
    FT,
    REGRID_DIR,
    datafile_rll,
    varname,
    space;
    hd_outfile_root = "data_cgll",
    mono = false,
)

Reads and regrids data of the varname variable from an input NetCDF file and saves it as another NetCDF file using Tempest Remap. The input NetCDF fileneeds to be Exodus formatted, and can contain time-dependent data. The output NetCDF file is then read back, the output arrays converted into Fields and saved as HDF5 files (one per time slice). This function should be called by the root process. The saved regridded HDF5 output is readable by multiple MPI processes.

Code taken from ClimaCoupler.Regridder.

Arguments

• FT: [DataType] Float type.
• REGRID_DIR: [String] directory to save output files in.
• datafile_rll: [String] filename of RLL dataset to be mapped to CGLL.
• varname: [String] the name of the variable to be remapped.
• space: [ClimaCore.Spaces.AbstractSpace] the space to which we are mapping.
• hd_outfile_root: [String] root of the output file name.
• mono: [Bool] flag to specify monotone remapping.

read_from_hdf5(REGIRD_DIR, hd_outfile_root, time, varname,
    comms_ctx = ClimaComms.SingletonCommsContext())

Read in a variable varname from an HDF5 file. If a CommsContext other than SingletonCommsContext is used for comms_ctx, the input HDF5 file must be readable by multiple MPI processes.

Code taken from ClimaCoupler.Regridder.

Arguments

• REGRID_DIR: [String] directory to save output files in.
• hd_outfile_root: [String] root of the output file name.
• time: [Dates.DateTime] the timestamp of the data being written.
• varname: [String] variable name of data.
• comms_ctx: [ClimaComms.AbstractCommsContext] context used for this operation.

Returns

• Field or FieldVector

This function is slightly modified from ClimaCoupler "landseamask" function.

reshape_cgll_sparse_to_field!(field::Fields.Field, in_array::Array, R)

Reshapes a sparse vector array in_array (CGLL, raw output of the TempestRemap), and uses its data to populate the input Field object field. Redundant nodes are populated using dss operations.

Code taken from ClimaCoupler.Regridder.

Arguments

• field: [Fields.Field] object populated with the input array.
• in_array: [Array] input used to fill field.
• R: [NamedTuple] containing target_idxs and row_indices used for indexing.

write_to_hdf5(REGRID_DIR, hd_outfile_root, time, field, varname,
    comms_ctx = ClimaComms.SingletonCommsContext())

Function to save individual HDF5 files after remapping. If a CommsContext other than SingletonCommsContext is used for comms_ctx, the HDF5 output is readable by multiple MPI processes.

Code taken from ClimaCoupler.Regridder.

Arguments

• REGRID_DIR: [String] directory to save output files in.
• hd_outfile_root: [String] root of the output file name.
• time: [Dates.DateTime] the timestamp of the data being written.
• field: [Fields.Field] object to be written.
• varname: [String] variable name of data.
• comms_ctx: [ClimaComms.AbstractCommsContext] context used for this operation.

SnowParameters{FT <: AbstractFloat, PSE}

A struct for storing parameters of the SnowModel.

• ρ_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)

• fS_c: Critical threshold for snow cover fraction (m)

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

• Δt: Timestep of the model

• 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), fSc = FT(0.2), κice = FT(2.21), earthparamset::PSE) where {FT, PSE}

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

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) 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,
                      c_s::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.

If there is no snow (U = SWE = 0), the liquid mass fraction is 1.

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.

AbstractCarbonSource{FT} <: ClimaLSM.AbstractSource{FT}

An abstract type for soil CO2 sources. There are two sources: roots and microbes, in struct RootProduction and MicrobeProduction.

AbstractSoilBiogeochemistryModel{FT} <: ClimaLSM.AbstractExpModel{FT}

An abstract model type for soil biogeochemistry models.

AbstractSoilCO2BC <: ClimaLSM. AbstractBC

An abstract type for co2-specific types of boundary conditions.

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 <: AbstractSoilCO2BC

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

PrescribedSOC <: AbstractSoilDriver

A container which holds the prescribed function for soil organic carbon

This is meant for use when running the biogeochemistry model without a soil organic carbon model.

• soil_organic_carbon: Carbon content of soil organic matter, of the form f(z::FT, t) where FT <: AbstractFloat

SoilCO2FluxBC <: AbstractSoilCO2BC

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 AbstractBoundaryConditions

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

• driver: Drivers

SoilCO2Model{FT}(; parameters::SoilCO2ModelParameters{FT}, domain::ClimaLSM.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.

• ν: Soil porosity (m³ m⁻³)

• θ_a100: Air-filled porosity at soil water potential of -100 cm H₂O (~ 10 Pa)

• D_ref: Diffusion coefficient for CO₂ in air at standard temperature and pressure (m² s⁻¹)

• b: Absolute value of the slope of the line relating log(ψ) versus log(θ) (unitless)

• 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

SoilCO2ModelParameters{FT}(;
                            ν = FT(0.556),
                            θ_a100 = FT(0.1816),
                            D_ref = FT(1.39e-5),
                            b = FT(4.547),
                            D_liq = FT(3.17),
                            # DAMM
                            α_sx = FT(194e3),
                            Ea_sx = FT(61e3),
                            kM_sx = FT(5e-3),
                            kM_o2 = FT(0.004),
                            O2_a = FT(0.209),
                            D_oa = FT(1.67),
                            p_sx = FT(0.024),
                            earth_param_set::PSE
                           ) where {FT, PSE}

An outer constructor for creating the parameter struct of the SoilCO2Model, based on keyword arguments.

SoilCO2StateBC <: AbstractSoilCO2BC

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

air_pressure(driver::PrescribedAtmosphere, t)

Returns the prescribed air pressure at the top boundary condition at time (t).

co2_diffusivity(
                T_soil::FT,
                θ_w::FT,
                P_sfc::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.

microbe_source(T_soil::FT,
               θ_l::FT,
               Csom::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_som_C(driver::PrescribedSOC, p, Y, t, z)

Returns the carbon soil organic matter (SOM) at location (z) and time (t) for the prescribed soil case.

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,
                       params::SoilCO2ModelParameters{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).

ClimaLSM.boundary_flux(
bc::AtmosCO2StateBC,
boundary::ClimaLSM.TopBoundary,
Δz::ClimaCore.Fields.Field,
Y::ClimaCore.Fields.FieldVector,
p::NamedTuple,
t,
)::ClimaCore.Fields.Field

A method of ClimaLSM.boundary_flux which returns the soilco2 flux in the case when the atmospheric CO2 is ued at top of the domain.

ClimaLSM.boundary_flux(
    bc::SoilCO2FluxBC,
    boundary::ClimaLSM.AbstractBoundary,
    Δz::ClimaCore.Fields.Field,
    Y::ClimaCore.Fields.FieldVector,
    p::NamedTuple,
    t,
)::ClimaCore.Fields.Field

A method of ClimaLSM.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.

ClimaLSM.boundary_flux(
    bc::SoilCO2StateBC,
    boundary::ClimaLSM.BottomBoundary,
    Δz::ClimaCore.Fields.Field,
    Y::ClimaCore.Fields.FieldVector,
    p::NamedTuple,
    t,
)::ClimaCore.Fields.Field

A method of ClimaLSM.boundary_flux which returns the soilco2 flux in the case of a prescribed state BC at bottom of the domain.

ClimaLSM.boundary_flux(
bc::SoilCO2StateBC,
boundary::ClimaLSM.TopBoundary,
Δz::ClimaCore.Fields.Field,
Y::ClimaCore.Fields.FieldVector,
p::NamedTuple,
t,
)::ClimaCore.Fields.Field

A method of ClimaLSM.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.

ClimaLSM.source!(dY::ClimaCore.Fields.FieldVector,
                      src::MicrobeProduction,
                      Y::ClimaCore.Fields.FieldVector,
                      p::NamedTuple,
                      params)

A method which extends the ClimaLSM source! function for the case of microbe production of CO2 in soil.

apply_bounds(data, bounds)

Threshold data in a min/max form from a database using a dictionary of specified bounds. Values outside bounds are converted to 'missing'.

Arguments

• data::DataFrame: the data over which to apply bounds.
• bounds::Dict{Symbol, Tuple{Real, Real}}: The dictionary specifying which columns to threshold, as

well as the thresholds to apply via (min, max).

data_url(id, state, fields; metric, hourly, start_date, end_date)

Return the url to gather SNOTEL data from a particular station.

Arguments

• id::String: the id code of the station to access.
• state::String: the state abbreviation of the station to access.
• fields::Vector{String}: a list of strings specifying the SNOTEL parameters to collect.
• metric::Bool: a boolean specifying whether to gather data in metric (true) or imperial (false) units. Default is false.
• hourly::Bool: a boolean specifying whether to scrape hourly (true) or daily (false) data. default is false.
• start_date::String:
• end_date::Stirng:

filter_phys!(data; eps)

Filter unphysical/undesirable data points out of the dataset, following physical choices outlined in the paper, such as:

• Removing rows were SWE, z, and precipitation are all less than some threshold
• Removing rows where SWE is zero and z is nonzero
• Removing rows where dz/dt is positive but precipitation is zero
• Removing rows where dSWE/dt > precipitation
• Removing rows where SWE < z

**Note: requires column names to match those of the paper for usage.

Arguments

• data::DataFrame: the cleaned and processed data.
• eps::Real: a filtering threshold, set to 0.5 cm.

get_data(id, state, fields; metric, hourly, start, finish)

Return the SNOTEL data from a station as a DataFrame.

Arguments

• id::String: the id code of the station to access.
• state::String: the state abbreviation of the station to access.
• fields::Vector{String}: a list of strings specifying the SNOTEL parameters to collect.
• metric::Bool = false: a boolean specifying whether to gather data in metric (true) or imperial (false) units.
• hourly::Bool = false: a boolean specifying whether to scrape hourly (true) or daily (false) data.
• start::String: Optional string to specify starting date of data collection. Default is "start".
• finish::String: Optional string to specify ending date of data collection. Default is "end".

hourly2daily(hourlydata)

Convert an hourly SNOTEL dataset to a daily SNOTEL dataset, averaging humidity, radiation, wind, and temperature data, but maintaining start-of-window SWE, z, and precipitation data. Makes use of custom "missingmean" and "missingfirst" functions to handle missing values when finding the mean and first non-missing values, respectively, when working with hourly datasets with missing values. **Note: does not extend to dataframes with fields beyond those extracted for the paper.

Arguments

• hourlydata::DataFrame: the hourly data over which to average by-day.

makediffs(data, Δt; diffvars)

Turn accumulated data fields into differential data fields. Turns data fields which represent accumulated values of variables into a rate of change of that variable, (data[i+1]-data[i])/(time[i+1]-time[i]), but only in the case where time[i+1]-time[i] = Δt. **Note: apply after scaling and getting rid of missing values. Assumes time column has name "date" and has Date/DateTime units.

Arguments

• data::DataFrame: the data over which to apply differencing.
• Δt::Period: the amount of time representing one unit timestep in the data.
• diffvars::Vector{Symbol}: Columns to apply differencing to. Default is [:SWE, :z, :precip].

prep_data(data; extract_vars, make_snow_split, physical_filter, eps)

Prepare a cleaned (scaled & gap-filled, potentially rolled) data stream or non-scraped data stream for model usage. **Note: Requires column names to match those of the paper for usage.

Arguments

• data::DataFrame: the cleaned and processed data.
• extract_vars::Vector{Symbol}: The list of columns to be used in the model. Default is the variables used in the paper.
• make_snow_split::Bool: Boolean indicating whether to split precipitation into water and snow. Default is true.
• physical_filter::Bool: Boolean indicating whether to filter data using filter_phys!. Default is true.
• eps::Real: a filtering threshold, set to 0.5 cm.

rectify_daily_hourly(daily_data, hourly_data)

Use one SNOTEL data stream (hourly data) to fill holes in another SNOTEL data stream (daily data). **Note: requires time column to be named "date".

Arguments

• daily_data::DataFrame: the main (daily) data over which to fill missing holes.
• hourly_data::DataFrame: the (converted to daily-format, see hourly2daily) hourly data over which to fill holes in the daily data.

rolldata(data, Δt, N; takefirst)

Apply a moving average of N timesteps to all data, except for the variables specified in "takefirst", for which the leading value is maintained. **Note: assumes the time column is named "date" and has Date/DateTime units

Arguments

• data::DataFrame: the data over which to apply averaging.
• Δt::Period: the amount of time representing one unit timestep in the data.
• N::Int: the number of intervals (timesteps) to include in the average
• takefirst::Vector{Symbol}: Columns to apply differencing to. Default is [:date, :SWE, :z, :precip].

scale_cols(data, scales)

Apply multiplicative scaling to select columns of a data frame.

Arguments

• data::DataFrame: the data frame over which to apply the scaling.
• scales::Dict{Symbol, Real}: The dictionary specifying which columns to scale, as

well as the multitiplicative constant to apply to that column.

sitedata_daily(id, state; imp_fields, metric_fields, colnames, start, finish)

Return the daily SNOTEL data from a station as a DataFrame.

Arguments

• id::String: the id code of the station to access.
• state::String: the state abbreviation of the station to access.
• imp_fields::Vector{String}: Parameters to return in imperial units. Default is ["WTEQ", "SNWD", "PREC"].
• metric_fields::Vector{String}: Parameters to return in metric units. Default is ["RHUMV", "SRADV", "WSPDV", "TAVG"].
• colnames::Vector{String}: Optional column names to change header after scraping data. Default follows that of the paper,

which is ["date", "SWE", "z", "precip", "relhumavg", "solradavg", "windspeedavg", "airtempavg"].

• start::String: Optional string to specify starting date of data collection. Default is "start".
• finish::String: Optional string to specify ending date of data collection. Default is "end".

sitedata_hourly(id, state; imp_fields, metric_fields, colnames, start, finish)

Return the hourly SNOTEL data from a station as a DataFrame.

Arguments

• id::String: the id code of the station to access.
• state::String: the state abbreviation of the station to access.
• imp_fields::Vector{String}: Parameters to return in imperial units. Default is ["WTEQ", "SNWD", "PREC"].
• metric_fields::Vector{String}: Parameters to return in metric units. Default is ["RHUMV", "SRADV", "WSPDV", "TAVG"].
• colnames::Vector{String}: Optional column names to change header after scraping data. Default follows that of the paper,

which is ["date", "SWE", "z", "precip", "relhumavg", "solradavg", "windspeedavg", "airtempavg"].

• start::String: Optional string to specify starting date of data collection. Default is "start".
• finish::String: Optional string to specify ending date of data collection. Default is "end".

snotel_metadata(; fields)

Return a database of snotel station metadata for usage in dataset creation.

Arguments

• fields::Vector{String}: optional list of specific metadata fields to extract. Default is

[stationID, state.code, "elevation", "latitude", "longitude"].

snowsplit(air_temp, hum, precip)

Engineer total water content of precipitation into snow and rain portions, accoridng to the paper outlined in https://www.nature.com/articles/s41467-018-03629-7.

Arguments

• air_temp::Vector{<:Real}: the air temperature data.
• hum::Vector{<:Real}: the relative humidity data.
• precip::Vector{<:Real}: the precipitation data.

stack2DF(stack, colnames)

Convert a vector of vectors into a DataFrame, with specified column names.

Arguments

• stack::Vector{Vector{Any}}: the data stack to convert.
• colnames::Vector{String}: The names to give the columns of the DataFrame.

AbstractInterpolationMethod

Defines how to perform interpolation.

Not all the TimeVaryingInputs support all the interpolation methods (e.g., no interpolation methods are supported when the given function is analytic).

AbstractTimeVaryingInput

Note

TimeVaryingInputs should be considered implementation details. The exposed public interface should only be considered

• TimeVaryingInput(input; method, context) for construction,
• evaluate!(dest, input, time) for evaluation

InterpolatingTimeVaryingInput0D

The constructor for InterpolatingTimeVaryingInput0D is not supposed to be used directly, unless you know what you are doing. The constructor does not perform any check and does not take care of GPU compatibility. It is responsibility of the user-facing constructor TimeVaryingInput() to do so.

times and vales may have different float types, but they must be the same length, and we assume that they have been sorted to be monotonically increasing in time, without repeated values for the same timestamp.

LinearInterpolation

Perform linear interpolation between the two neighboring points.

NearestNeighbor

Return the value corresponding to the point closest to the input time.

in(time, itp::InterpolatingTimeVaryingInput0D)

Check if the given time is in the range of definition for itp.

TimeVaryingInput(func)
TimeVaryingInput(times, vals; method, context)

Construct on object that knows how to evaluate the given function/data on the model times.

When passing a function

When a function func is passed, the function has to be GPU-compatible (e.g., no splines).

When passing single-site data

When a times and vals are passed, times have to be sorted and the two arrays have to have the same length.

evaluate!(dest, input, time)

Evaluate the input at the given time, writing the output in-place to dest.

Depending on the details of input, this function might do I/O and communication.

evaluate!(
    dest,
    itp::InterpolatingTimeVaryingInput0D,
    time,
    ::LinearInterpolation,
    )

Write to dest the result of a linear interpolation of itp on the given time.

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<: ClimaLSM.Domains.AbstractDomain}

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

1. The bucket model domain is of type <: ClimaLSM.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

• W_f: Capacity of the land bucket (m)

• 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

BulkAlbedoFunction{FT, F <: FUnction} <: AbstractLandAlbedoModel

An albedo model where the albedo of different surface types is specified. Snow albedo is treated as constant across snow location and across wavelength. Surface albedo (sfc) is specified as a function of latitude and longitude, but is also treated as constant across wavelength; surface is this context refers to soil and vegetation.

BulkAlbedoStatic{FT, PDS <: PrescribedDataStatic} <: AbstractLandAlbedoModel

An albedo model where the albedo of different surface types is specified. Snow albedo is treated as constant across snow location and across wavelength. Surface albedo is specified via a NetCDF file, which can be a function of time, but is treated as constant across wavelengths; surface is this context refers to soil and vegetation. This albedo type is static in time.

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

BulkAlbedoStatic{FT}(
    regrid_dirpath::String,
    comms_ctx::ClimaComms.AbstractCommsContext;
    α_snow = FT(0.8),
    varname = "sw_alb",
    get_infile::Function = Bucket.bareground_albedo_dataset_path,
) where {FT}

Constructor for the BulkAlbedoStatic that implements a default albedo map, comms context, and value for α_snow. The varname must correspond to the name of the variable in the NetCDF file retrieved by infile_path. infile_path is a function that 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 bareground_albedo_dataset_path artifact will be used as a default with this type.

BulkAlbedoTemporal{FT, FR <: FileReader.PrescribedDataTemporal}
                   <: AbstractLandAlbedoModel

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 ClimaLSM.LSMSphericalShellDomain.

BulkAlbedoTemporal{FT}(
    regrid_dirpath::String,
    date_ref::Union{DateTime, DateTimeNoLeap},
    t_start,
    Space::ClimaCore.Spaces.AbstractSpace;
    get_infile = Bucket.cesm2_albedo_dataset_path,
    varname = "sw_alb"
) where {FT}

Constructor for the BulkAlbedoTemporal 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; otherwise BulkAlbedoStatic should be used.

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, W_f::FT) where {FT}

Computes the beta factor which scales the evaporation from the potential rate.

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(model_albedo::BulkAlbedoTemporal{FT}, parameters, Y, p, t)

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

next_albedo(model_albedo::Union{BulkAlbedoFunction{FT}, BulkAlbedoStatic{FT}},
    parameters, Y, p, t)

Update the surface albedo for time t. These albedo model types aren't explicitly dependent on t, but depend on quantities which may change over time.

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

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

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.

function set_initial_parameter_field!(
    albedo::BulkAlbedoFunction{FT},
    p,
    surface_coords,
) where {FT}

Updates the spatially-varying but constant in time surface albedo stored in the auxiliary vector p in place, according to the passed function of latitute and longitude stored in albedo.α_sfc.

function set_initial_parameter_field!(
    albedo::BulkAlbedoStatic{FT},
    p,
    surface_coords,
) where {FT}

Initializes spatially-varying surface albedo stored in the auxiliary vector p in place, according to a NetCDF file.

The NetCDF file is read in, regridded, and projected onto the surface space of the LSM using ClimaCoreTempestRemap. The result is a ClimaCore.Fields.Field of albedo values.

function set_initial_parameter_field!(
    albedo::BulkAlbedoTemporal{FT},
    p,
    surface_coords,
) where {FT}

Initializes spatially- and temporally-varying surface albedo stored in the auxiliary vector p in place, according to a NetCDF file. This data file is encapsulated in an object of type ClimaLSM.FileReader.PrescribedDataTemporal in the field albedo.albedo_info. This object contains a reference date and start time, which are used to get the start date.

The NetCDF file is read in at the dates closest to this start date, regridded, and projected onto the surface space of the LSM using ClimaCoreTempestRemap. The result is a ClimaCore.Fields.Field of albedo values.

β(W::FT, W_f::FT) where {FT}

Returns the coefficient which scales the saturated specific humidity at the surface based on the bucket water levels, which is then used to obtain the true specific humidity of the soil surface <= q_sat.

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

Creates the computeexptendency! function for the bucket model.

ClimaLSM.make_set_initial_cache(model::BucketModel{FT}) where{FT}

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

In this case, we also use this method to update the initial values for the spatially varying parameter fields, read in from data files.

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.

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

Returns the emissivity for the bucket model (1.0).

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

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

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

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

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

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