ClimaLand.Soil.AbstractRunoffModelType
AbstractRunoffModel

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

  • ClimaLand.Soil.AtmosDrivenFluxBC
  • ClimaLand.Soil.RichardsAtmosDrivenFluxBC,

and for these functions: -ClimaLand.Soil.soil_surface_infiltration

  • ClimaLand.Soil.subsurface_runoff_source
  • ClimaLand.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.

ClimaLand.Soil.AbstractSoilBCType
AbstractSoilBC <: ClimaLand. AbstractBC

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

ClimaLand.Soil.AbstractSoilHydrologyClosureType
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.
ClimaLand.Soil.AbstractSoilModelType
AbstractSoilModel{FT} <: ClimaLand.AbstractImExModel{FT}

The abstract type for all soil models.

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

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

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

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

ClimaLand.Soil.AtmosDrivenFluxBCType
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.

ClimaLand.Soil.BrooksCoreyType

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

ClimaLand.Soil.EnergyHydrologyType
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

ClimaLand.Soil.EnergyHydrologyMethod
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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  • S_s: The specific storativity (1/m)

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

  • Ω: Ice impedance factor for the hydraulic conductivity

  • γ: Coefficient of viscosity factor for the hydraulic conductivity

  • γT_ref: Reference temperature for the viscosity factor

  • PAR_albedo: Soil PAR Albedo

  • NIR_albedo: Soil NIR Albedo

  • emissivity: Soil Emissivity

  • z_0m: Roughness length for momentum

  • z_0b: Roughness length for scalars

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

  • earth_param_set: Physical constants and clima-wide parameters

ClimaLand.Soil.FluxBCType

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.

ClimaLand.Soil.FreeDrainageType
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.

ClimaLand.Soil.MoistureStateBCType

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.

ClimaLand.Soil.NoRunoffType
NoRunoff <: AbstractRunoffModel

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

ClimaLand.Soil.RichardsAtmosDrivenFluxBCType

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.

ClimaLand.Soil.RichardsModelType
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

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

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

ClimaLand.Soil.RichardsParametersType
RichardsParameters{F <: Union{<: AbstractFloat, ClimaCore.Fields.Field}, 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

ClimaLand.Soil.RichardsTridiagonalWType
RichardsTridiagonalW{R, J, W, T} <: ClimaLand.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

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

)

Outer constructor for the RichardsTridiagonalW Jacobian matrix struct.

Initializes all variables to zeros.

ClimaLand.Soil.TemperatureStateBCType

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.

ClimaLand.Soil.vanGenuchtenType
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

ClimaLand.Soil.append_sourceMethod
append_source(src::AbstractSoilSource, srcs::Tuple)::Tuple

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

ClimaLand.Soil.append_sourceMethod
append_source(src::Nothing , srcs::Tuple)::Tuple

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

ClimaLand.Soil.boundary_var_domain_namesMethod
boundary_var_domain_names(::AtmosDrivenFluxBC, ::ClimaLand.TopBoundary))

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

ClimaLand.Soil.boundary_var_domain_namesMethod
boundary_var_domain_names(::AbstractSoilBC, ::ClimaLand.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.

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

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

ClimaLand.Soil.boundary_var_typesMethod
boundary_var_types(::Soil.EnergyHydrology{FT}, ::NamedTuple, ::ClimaLand.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.

ClimaLand.Soil.boundary_var_typesMethod
boundary_var_types(::Soil.RichardsModel{FT}, ::NamedTuple, ::ClimaLand.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.

ClimaLand.Soil.boundary_varsMethod
boundary_vars(::AtmosDrivenFluxBC, ::ClimaLand.TopBoundary)

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

These variables are updated in place in soil_boundary_fluxes.

ClimaLand.Soil.boundary_varsMethod
boundary_vars(::NamedTuple, ::ClimaLand.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.

ClimaLand.Soil.boundary_varsMethod
boundary_vars(::NamedTuple, ::ClimaLand.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.

ClimaLand.Soil.create_soil_bc_named_tupleMethod
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.

ClimaLand.Soil.dry_soil_layer_thicknessMethod
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).

ClimaLand.Soil.dψdϑMethod

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.

ClimaLand.Soil.dψdϑMethod

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

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

ClimaLand.Soil.get_bottom_surface_fieldMethod
get_bottom_surface_field(
    center_val,
    _,
)

A helper function for the case where we use get_bottom_surface_field on a parameter that is a scalar rather than a field. Returns the scalar value.

ClimaLand.Soil.get_bottom_surface_fieldMethod
get_bottom_surface_field(
    center_field::ClimaCore.Fields.Field,
    bottom_space,
)

A helper function to extract the bottom level of a center field and cast it onto the bottom face space.

ClimaLand.Soil.get_top_surface_fieldMethod
get_top_surface_field(
    center_val,
    _,
)

A helper function for the case where we use get_top_surface_field on a parameter that is a scalar rather than a field. Returns the scalar value.

ClimaLand.Soil.get_top_surface_fieldMethod
get_top_surface_field(
    center_field::ClimaCore.Fields.Field,
    surface_space,
)

A helper function to extract the top level of a center field and cast it onto the surface face space.

ClimaLand.Soil.horizontal_components!Method

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.

ClimaLand.Soil.horizontal_components!Method

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.

ClimaLand.Soil.horizontal_components!Method

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.

ClimaLand.Soil.horizontal_components!Method

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.

ClimaLand.Soil.hydraulic_conductivityMethod
 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.

ClimaLand.Soil.hydraulic_conductivityMethod
 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.

ClimaLand.Soil.impedance_factorMethod
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.

ClimaLand.Soil.inverse_matric_potentialMethod
 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.

ClimaLand.Soil.inverse_matric_potentialMethod
 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.

ClimaLand.Soil.kersten_numberMethod
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.

ClimaLand.Soil.matric_potentialMethod
 matric_potential(cm::BrooksCorey{FT}, S::FT) where {FT}

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

ClimaLand.Soil.matric_potentialMethod
 matric_potential(cm::vanGenuchten{FT}, S::FT) where {FT}

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

ClimaLand.Soil.phase_change_sourceMethod
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.

ClimaLand.Soil.pressure_headMethod
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.

ClimaLand.Soil.pressure_headMethod
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.

ClimaLand.Soil.relative_saturationMethod
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.

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

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

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

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

ClimaLand.Soil.soil_boundary_fluxesMethod
soil_boundary_fluxes(bc::NamedTuple, boundary, model, Δz, Y, p, t)

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

ClimaLand.Soil.soil_resistanceMethod
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.

ClimaLand.Soil.soil_surface_infiltrationMethod
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.

ClimaLand.Soil.soil_tortuosityMethod
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.

ClimaLand.Soil.subsurface_runoff_sourceMethod
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.

ClimaLand.Soil.temperature_from_ρe_intMethod
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.

ClimaLand.Soil.thermal_conductivityMethod
thermal_conductivity(
    κ_dry::FT,
    K_e::FT,
    κ_sat::FT
) where {FT}

Compute the expression for thermal conductivity of soil matrix.

ClimaLand.Soil.thermal_timeMethod
thermal_time(ρc::FT, Δz::FT, κ::FT) where {FT}

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

ClimaLand.Soil.viscosity_factorMethod
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.

ClimaLand.Soil.volumetric_heat_capacityMethod
volumetric_heat_capacity(
    θ_l::FT,
    θ_i::FT,
    parameters::EnergyHydrologyParameters{FT},
) where {FT}

Compute the expression for volumetric heat capacity.

ClimaLand.Soil.volumetric_internal_energyMethod
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.

ClimaLand.Soil.volumetric_internal_energy_liqMethod
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.

ClimaLand.Soil.volumetric_liquid_fractionMethod
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.

ClimaLand.Soil.κ_dryMethod
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.

ClimaLand.Soil.κ_satMethod
κ_sat(
    θ_l::FT,
    θ_i::FT,
    κ_sat_unfrozen::FT,
    κ_sat_frozen::FT
) where {FT}

Compute the expression for saturated thermal conductivity of soil matrix.

ClimaLand.Soil.κ_sat_frozenMethod
function κ_sat_frozen(
    κ_solid::FT,
    ν::FT,
    κ_ice::FT
) where {FT}

Computes the thermal conductivity for saturated frozen soil.

ClimaLand.Soil.κ_sat_unfrozenMethod
function κ_sat_unfrozen(
    κ_solid::FT,
    ν::FT,
    κ_l::FT
) where {FT}

Computes the thermal conductivity for saturated unfrozen soil.

ClimaLand.Soil.κ_solidMethod
κ_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.

ClimaLand.auxiliary_domain_namesMethod
auxiliary_domain_names(soil::RichardsModel)

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

ClimaLand.auxiliary_typesMethod
auxiliary_types(soil::EnergyHydrology{FT}) where {FT}

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

ClimaLand.auxiliary_typesMethod
auxiliary_types(soil::RichardsModel)

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

ClimaLand.auxiliary_varsMethod
auxiliary_vars(soil::EnergyHydrology)

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

ClimaLand.auxiliary_varsMethod
auxiliary_vars(soil::RichardsModel)

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

ClimaLand.boundary_fluxMethod
ClimaLand.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.

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

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

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

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

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

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

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

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

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

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

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

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

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

ClimaLand.make_compute_exp_tendencyMethod
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.

ClimaLand.make_compute_exp_tendencyMethod
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.

ClimaLand.make_compute_imp_tendencyMethod
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.

ClimaLand.make_update_auxMethod
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.

ClimaLand.make_update_auxMethod
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.

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

ClimaLand.prognostic_typesMethod
prognostic_types(soil::EnergyHydrology{FT}) where {FT}

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

ClimaLand.prognostic_varsMethod
prognostic_vars(soil::EnergyHydrology)

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

ClimaLand.prognostic_varsMethod
prognostic_vars(soil::RichardsModel)

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

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

Computes the source terms for phase change.

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

Returns the surface albedo field of the EnergyHydrology soil model.

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

Returns the surface emissivity field of the EnergyHydrology soil model.

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

Returns the surface height of the EnergyHydrology model.

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

Returns the surface resistance field of the EnergyHydrology soil model.

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

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

This models the 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.

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

Returns the surface temperature field of the EnergyHydrology soil model.

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

ClimaLand.∂tendencyBC∂YMethod
ClimaLand.∂tendencyBC∂Y(
    ::AbstractSoilModel,
    ::AbstractSoilBC,
    boundary::ClimaLand.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.

ClimaLand.∂tendencyBC∂YMethod
ClimaLand.∂tendencyBC∂Y(
    model::RichardsModel,
    ::MoistureStateBC,
    boundary::ClimaLand.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.

ClimaLand.Domains.AbstractDomainType
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.

ClimaLand.Domains.ColumnType
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

ClimaLand.Domains.ColumnMethod
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.

ClimaLand.Domains.HybridBoxType
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

ClimaLand.Domains.HybridBoxMethod
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.

ClimaLand.Domains.PlaneType
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

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

Outer constructor for the Plane domain, using keyword arguments.

ClimaLand.Domains.PointType
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

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

Constructor for the Point domain using keyword arguments.

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

ClimaLand.Domains.SphericalShellType
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

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

Outer constructor for the SphericalShell domain, using keyword arguments.

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

ClimaLand.Domains.SphericalSurfaceType
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

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

Outer constructor for the SphericalSurface domain, using keyword arguments.

ClimaLand.Domains.coordinatesMethod
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.

ClimaLand.Domains.obtain_face_spaceMethod
obtain_face_space(cs::ClimaCore.Spaces.CenterExtrudedFiniteDifferenceSpace)

Returns the face space for the CenterExtrudedFiniteDifferenceSpace cs.

ClimaLand.Domains.obtain_face_spaceMethod
obtain_face_space(cs::ClimaCore.Spaces.CenterFiniteDifferenceSpace)

Returns the face space corresponding to the CenterFiniteDifferenceSpace cs.

ClimaLand.Domains.obtain_surface_domainMethod
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.

ClimaLand.Domains.obtain_surface_domainMethod
obtain_surface_domain(s::SphericalShell{FT}) where {FT}

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

ClimaLand.Domains.obtain_surface_spaceMethod
obtain_surface_space(cs::ClimaCore.Spaces.CenterExtrudedFiniteDifferenceSpace)

Returns the horizontal space for the CenterExtrudedFiniteDifferenceSpace cs.

ClimaLand.Domains.obtain_surface_spaceMethod
obtain_surface_space(cs::ClimaCore.Spaces.CenterFiniteDifferenceSpace)

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

ClimaLand.Domains.top_center_to_surfaceMethod
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.

ClimaLand.Snow.SnowParametersType
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

ClimaLand.Snow.SnowParametersMethod

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.

ClimaLand.Snow.maximum_liquid_mass_fractionMethod
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.

ClimaLand.Snow.runoff_timescaleMethod
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.

ClimaLand.Snow.snow_bulk_temperatureMethod
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.

ClimaLand.Snow.snow_depthMethod
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.

ClimaLand.Snow.snow_liquid_mass_fractionMethod
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.

ClimaLand.Snow.snow_thermal_conductivityMethod
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).

ClimaLand.Snow.specific_heat_capacityMethod
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.

ClimaLand.SpaceVaryingInputs.SpaceVaryingInputMethod
SpaceVaryingInput(data_function::Function, space::ClimaCore.Spaces.AbstractSpace)

Returns the parameter field to be used in the model; appropriate when a parameter is defined using a function of the coordinates of the space.

Pass the `data" as a functiondata_function` which takes coordinates as arguments, and the ClimaCore space of the model simulation.

This returns a scalar field. Note that data_function is broadcasted over the coordinate field. Internally, inside your function, this must be unpacked (coords.lat, coords.lon, e.g.) for use of the coordinate values directly.

ClimaLand.SpaceVaryingInputs.SpaceVaryingInputMethod
SpaceVaryingInputs.SpaceVaryingInput(
    data_z::AbstractArray,
    data_values::NamedTuple,
    space::S,
    dest_type::Type{DT},
) where {
    S <: ClimaCore.Spaces.CenterFiniteDifferenceSpace,
    DT,
}

Returns a field of parameter structs to be used in the model; appropriate when the parameter struct values vary in depth; the dest_type argument is the struct type - we assumed that your struct as a constructor which accepts the values of its arguments by kwarg,

  • data_z is where the measured values were obtained,
  • data_values is a NamedTuple with keys equal to the argument names

of the struct, and with values equal to an array of measured values,

  • space defines the model grid.

As an example, we can create a field of vanGenuchten structs as follows. This struct requires two parameters, α and n. Let's assume that we have measurements of these as a function of depth at the locations given by data_z, called data_α and data_n. Then we can write vG_field = SpaceVaryingInput(data_z, (;α = data_α, n = data_n), space, vanGenuchten{Float32}). Under the hood, at each point in the model grid, we will create vanGenuchten{Float32}(;α = interp_α, n = interp_n), where interp indicates the interpolated value at the model depth.

Returns a ClimaCore.Fields.Field of type DT.

ClimaLand.SpaceVaryingInputs.SpaceVaryingInputMethod
function SpaceVaryingInput(
    data_z::AbstractArray,
    data_values::AbstractArray,
    space::S,
) where {S <: ClimaCore.Spaces.CenterFiniteDifferenceSpace}

Given a set of depths data_z and the observed values data_values at those depths, create an interpolated field of values at each value of z in the model grid - defined implicitly by space.

Returns a ClimaCore.Fields.Field of scalars.

ClimaLand.SpaceVaryingInputs.SpaceVaryingInputMethod
SpaceVaryingInput(data::PDS, varname::N; space::S) 
where {PDS <: FileReader.PrescribedDataStatic, N <: String, S <: ClimaCore.Spaces.SpectralElement2D}

Returns the parameter field to be used in the model; appropriate when a parameter is defined on the surface of the Earth.

Pass the data as a FileReader.PrescribedDataStatic object as well as the variable name of the variable in the data file, and the ClimaCore space of the model simulation.

Returns a ClimaCore.Fields.Field of scalars; analogous to the 1D case which also returns a ClimaCore.Fields.Field of scalars.

ClimaLand.Pond.PondModelType
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

ClimaLand.Pond.PrescribedRunoffType
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.

ClimaLand.Regridder.hdwrite_regridfile_rll_to_cgllMethod
function hdwrite_regridfile_rll_to_cgll(
    FT,
    REGRID_DIR,
    datafile_rll,
    varnames,
    space,
    outfile_root;
    mono = false,
)

Reads and regrids data of all varnames variables 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. Assumes that all variables specified by varnames have the same dates and grid.

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.
  • varnames: [Vector{String}] the name of the variable to be remapped.
  • space: [ClimaCore.Spaces.AbstractSpace] the space to which we are mapping.
  • outfile_root: [String] root of the output file name.
  • mono: [Bool] flag to specify monotone remapping.
ClimaLand.Regridder.read_from_hdf5Method
read_from_hdf5(REGIRD_DIR, hd_outfile_root, time, varname,
    space)

Read in a variable varname from an HDF5 file onto the provided space. If a CommsContext other than SingletonCommsContext is used in the space, 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.
  • space: [ClimaCore.Spaces.AbstractSpace] to read the HDF5 file onto.

Returns

  • Field or FieldVector
ClimaLand.Regridder.reshape_cgll_sparse_to_field!Method
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.
ClimaLand.Regridder.swap_spaceMethod
swap_space(field, new_space)

Update the space of a ClimaCore.Fields.Field object. Returns a new Field object with the same values as the original field, but on the new space. This is needed to correctly read in regridded files that may be reused between simulations.

Arguments

  • field: The ClimaCore.Fields.Field object to swap the space of.
  • new_space: The new ClimaCore.Spaces.AbstractSpace to assign to the field.
ClimaLand.Regridder.write_to_hdf5Function
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.
ClimaLand.Bucket.BucketModelType
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

ClimaLand.Bucket.BucketModelMethod

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

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

  1. The bucket model domain is of type <: ClimaLand.Domains.AbstractDomain
  2. Using an albedo read from a lat/lon file requires a global run.
ClimaLand.Bucket.BucketModelParametersType
struct BucketModelParameters{
    FT <: AbstractFloat,
    PSE,
}

Container for holding the parameters of the bucket model.

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

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

  • albedo: Albedo Model

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

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

  • W_f: Capacity of the land bucket (m)

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

  • p: Exponent used in β decay (unitless)

  • z_0m: Roughness length for momentum (m)

  • z_0b: Roughness length for scalars (m)

  • τc: τc timescale on which snow melts

  • earth_param_set: Earth Parameter set; physical constants, etc

ClimaLand.Bucket.BulkAlbedoFunctionType
BulkAlbedoFunction{FT, F <: ClimaCore.Fields.Field} <: 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. Bareground surface albedo is specified as a function of latitude and longitude, but is also treated as constant across wavelength; bareground surface is this context refers to soil and vegetation.

ClimaLand.Bucket.BulkAlbedoStaticType
BulkAlbedoStatic{FT, F <: ClimaCore.Fields.Field} <: 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. Bareground surface albedo is specified via a NetCDF file that 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 ClimaLand.LSMSphericalShellDomain.

ClimaLand.Bucket.BulkAlbedoStaticMethod
BulkAlbedoStatic{FT}(
    regrid_dirpath::String,
    surface_space::ClimaCore.Spaces.AbstractSpace;
    α_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.

ClimaLand.Bucket.BulkAlbedoTemporalType
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 ClimaLand.LSMSphericalShellDomain.

ClimaLand.Bucket.BulkAlbedoTemporalMethod
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.

ClimaLand.Bucket.bareground_albedo_dataset_pathMethod
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.

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

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

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

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

ClimaLand.Bucket.cesm2_albedo_dataset_pathMethod
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.

ClimaLand.Bucket.infiltration_at_pointMethod
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.

ClimaLand.Bucket.next_albedoMethod
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.

ClimaLand.Bucket.next_albedoMethod
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 bareground surface, based on the snow water equivalent S relative to the parameter S_c. The linear interpolation is taken from Lague et al 2019.

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

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

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

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

ClimaLand.Bucket.saturation_specific_humidityMethod
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.

ClimaLand.Bucket.βMethod
β(x::FT, x_c::FT, p::FT) where {FT}

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

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

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

ClimaLand.make_set_initial_cacheMethod
ClimaLand.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.

ClimaLand.make_update_auxMethod
make_update_aux(model::BucketModel{FT}) where {FT}

Creates the update_aux! function for the BucketModel.

ClimaLand.surface_albedoMethod
surface_albedo(model::BucketModel, Y, p)

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

ClimaLand.surface_emissivityMethod

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

Returns the emissivity for the bucket model (1.0).

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

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

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

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

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

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

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

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

ClimaLand.AbstractBCType
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.

ClimaLand.AbstractBoundaryType
AbstractBoundary

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

ClimaLand.AbstractExpModelType
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.

ClimaLand.AbstractImExModelType
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.

ClimaLand.AbstractLandModelType
 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.

ClimaLand.BottomBoundaryType
BottomBoundary{} <: AbstractBoundary{}

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

ClimaLand.CanopyRadiativeFluxesType
CanopyRadiativeFluxes{FT} <: AbstractRadiativeDrivers{FT}

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

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

ClimaLand.CoupledAtmosphereType
CoupledAtmosphere{FT} <: AbstractAtmosphericDrivers{FT}

To be used when coupling to an atmosphere model.

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

ClimaLand.DriverAffectMethod
(affect!::DriverAffect)(integrator)

This function is used by DriverUpdateCallback to perform the updating.

ClimaLand.LandHydrologyType
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

ClimaLand.LandHydrologyMethod
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.

ClimaLand.LandSoilBiogeochemistryType
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

ClimaLand.LandSoilBiogeochemistryMethod
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.

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

ClimaLand.PrescribedRadiativeFluxesType
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

ClimaLand.PrognosticRunoffType
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.

ClimaLand.PrognosticSoilType
 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

ClimaLand.RootExtractionType
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.

ClimaLand.RunoffBCType
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.

ClimaLand.SavingAffectType
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.

ClimaLand.SavingAffectMethod
(affect!::SavingAffect)(integrator)

This function is used by NonInterpSavingCallback to perform the saving.

ClimaLand.SoilCanopyModelType
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

ClimaLand.SoilCanopyModelMethod
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.

ClimaLand.TopBoundaryType
TopBoundary{} <: AbstractBoundary{}

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

ClimaLand.Canopy.PlantHydraulics.root_water_flux_per_ground_area!Method
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.

ClimaLand.Canopy.canopy_radiant_energy_fluxes!Method
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.

ClimaLand.Canopy.root_energy_flux_per_ground_area!Method
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.

ClimaLand.Domains.coordinatesMethod
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.

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

ClimaLand.NonInterpSavingCallbackMethod
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.

ClimaLand.Pond.surface_runoffMethod
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.

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

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

ClimaLand.add_drivers_to_cacheMethod
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.

ClimaLand.add_drivers_to_cacheMethod
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.

ClimaLand.add_dss_buffer_to_auxMethod
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.

ClimaLand.add_dss_buffer_to_auxMethod
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.

ClimaLand.add_dss_buffer_to_auxMethod
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.

ClimaLand.auxiliary_domain_namesMethod

auxiliarydomainnames(m::AbstractModel)

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

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

ClimaLand.auxiliary_typesMethod

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

ClimaLand.auxiliary_varsMethod

auxiliary_vars(m::AbstractModel)

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

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

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

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

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

ClimaLand.compute_ρ_sfcMethod
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.

ClimaLand.conditionMethod
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.

ClimaLand.construct_atmos_tsMethod
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.

ClimaLand.diffusive_fluxMethod
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.

ClimaLand.displacement_heightMethod
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.

ClimaLand.driver_initializeMethod
driver_initialize(cb, u, t, integrator)

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

ClimaLand.dss!Method
  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.

ClimaLand.dss_helper!Method
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.

ClimaLand.dss_helper!Method
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.

ClimaLand.dss_helper!Method
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).

ClimaLand.dss_helper!Method
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.

ClimaLand.get_driversMethod
get_drivers(model::AbstractModel)

Returns the driver objects for the model - atmospheric and radiative forcing - as a tuple (atmos, radiation).

ClimaLand.get_ΔzMethod
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.

ClimaLand.infiltration_at_pointMethod
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.

ClimaLand.infiltration_capacityMethod
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.

ClimaLand.initializeMethod
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.

ClimaLand.initialize_auxiliaryMethod
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.

ClimaLand.initialize_driversMethod
initialize_drivers(d::Union{AbstractAtmosphericDrivers, AbstractRadiativeDrivers, Nothing}, coords)

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

ClimaLand.initialize_driversMethod
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.

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

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

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

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

ClimaLand.initialize_driversMethod
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.

ClimaLand.initialize_lsm_auxMethod
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.

ClimaLand.initialize_prognosticMethod
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.

ClimaLand.land_componentsMethod
land_components(land::AbstractLandModel)

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

ClimaLand.linear_interpolationMethod
linear_interpolation(indep_vars, dep_vars, indep_value)

Carries out linear interpolation to obtain a value at location indep_value, using a independent variable 1-d vector indep_vars and a dependent variable 1-d vector dep_vars.

If the indep_value is outside the range of indep_vars, this returns the endpoint value closest.

ClimaLand.liquid_precipitationMethod
liquid_precipitation(atmos::AbstractAtmosphericDrivers, p, t)

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

ClimaLand.lsm_aux_domain_namesMethod

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.

ClimaLand.lsm_aux_domain_namesMethod
lsm_aux_domain_names(m::SoilCanopyModel)

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

ClimaLand.lsm_aux_typesMethod

lsmauxtypes(m::AbstractLandModel)

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

ClimaLand.lsm_aux_typesMethod
lsm_aux_types(m::SoilCanopyModel)

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

ClimaLand.lsm_aux_varsMethod

lsmauxvars(m::AbstractLandModel)

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

ClimaLand.lsm_aux_varsMethod
lsm_aux_vars(m::SoilCanopyModel)

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

ClimaLand.lsm_radiant_energy_fluxes!Method
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.

ClimaLand.make_compute_exp_tendencyMethod
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.

ClimaLand.make_compute_imp_tendencyMethod
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.

ClimaLand.make_exp_tendencyMethod
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.

ClimaLand.make_imp_tendencyMethod
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.

ClimaLand.make_imp_tendencyMethod
make_imp_tendency(model::AbstractModel)

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

ClimaLand.make_set_initial_cacheMethod
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.

ClimaLand.make_set_initial_cacheMethod
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.

ClimaLand.make_tendency_jacobianMethod

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.

ClimaLand.make_update_auxMethod
make_update_aux(model::AbstractModel)

Return an update_aux! function that updates auxiliary parameters p.

ClimaLand.make_update_boundary_fluxesMethod
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..

ClimaLand.make_update_boundary_fluxesMethod
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.

ClimaLand.make_update_boundary_fluxesMethod
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.

ClimaLand.make_update_cacheMethod
 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.

ClimaLand.make_update_driversMethod
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.

ClimaLand.make_update_driversMethod
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").

ClimaLand.make_update_driversMethod
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.

ClimaLand.make_update_driversMethod
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.

ClimaLand.make_update_jacobianMethod
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.

ClimaLand.nameMethod
name(model::AbstractModel)

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

ClimaLand.net_radiationMethod
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.

ClimaLand.net_radiationMethod
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.

ClimaLand.prognostic_domain_namesMethod

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.

ClimaLand.prognostic_typesMethod

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.

ClimaLand.prognostic_varsMethod

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.

ClimaLand.saving_initializeMethod
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.

ClimaLand.snow_precipitationMethod
snow_precipitation(atmos::AbstractAtmosphericDrivers, p, t)

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

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

A stub function, which is extended by ClimaLand.

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

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

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

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

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

ClimaLand.surface_air_densityMethod
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.

ClimaLand.surface_albedoMethod
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.

ClimaLand.surface_emissivityMethod
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.

ClimaLand.surface_evaporative_scalingMethod
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.

ClimaLand.surface_heightMethod
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.

ClimaLand.surface_resistanceMethod
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.

ClimaLand.surface_specific_humidityMethod
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.

ClimaLand.surface_temperatureMethod
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.

ClimaLand.thomas_algorithm!Method
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.

ClimaLand.to_scalar_coefsMethod
to_scalar_coefs(vector_coefs)

Helper function used in computing tendencies of vertical diffusion terms.

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

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

ClimaLand.turbulent_fluxesMethod
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.

ClimaLand.turbulent_fluxes_at_a_pointMethod
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.

ClimaLand.update_conditionMethod
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.

ClimaLand.vapor_pressure_deficitMethod
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.

ClimaLand.∂tendencyBC∂YMethod
∂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.

ClimaLand.Canopy.AbstractCanopyComponentType
AbstractCanopyComponent{FT <: AbstractFloat}

An abstract type for canopy component parameterizations.

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

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

ClimaLand.Canopy.AutotrophicRespirationParametersType
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 (-)

ClimaLand.Canopy.BeerLambertParametersType
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)

ClimaLand.Canopy.BeerLambertParametersMethod
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.

ClimaLand.Canopy.C3Type
C3 <: AbstractPhotosynthesisMechanism

Helper struct for dispatching between C3 and C4 photosynthesis.

ClimaLand.Canopy.C4Type
C4 <: AbstractPhotosynthesisMechanism

Helper struct for dispatching between C3 and C4 photosynthesis.

ClimaLand.Canopy.CanopyModelType
 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

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

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

ClimaLand.Canopy.FarquharParametersType
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

ClimaLand.Canopy.MedlynConductanceParametersType
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})

ClimaLand.Canopy.MedlynConductanceParametersMethod
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.

ClimaLand.Canopy.OptimalityFarquharModelType
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

ClimaLand.Canopy.OptimalityFarquharParametersType
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)

ClimaLand.Canopy.PrescribedCanopyTempModelType
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.

ClimaLand.Canopy.PrescribedSoilType
 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

ClimaLand.Canopy.PrescribedSoilMethod
 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.

ClimaLand.Canopy.SharedCanopyParametersType
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

ClimaLand.Canopy.TwoStreamParametersType
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 partition the canopy into when integrating the absorption over the canopy vertically. Unrelated to the number of layers in the vertical discretization of the canopy for the plant hydraulics model. (Constant, and should eventually move to ClimaParameters)

ClimaLand.Canopy.TwoStreamParametersMethod
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.

ClimaLand.Canopy.MM_KcMethod
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).

ClimaLand.Canopy.MM_KoMethod
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).

ClimaLand.Canopy.arrhenius_functionMethod
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).

ClimaLand.Canopy.canopy_boundary_fluxes!Method
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
ClimaLand.Canopy.canopy_componentsMethod
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.

ClimaLand.Canopy.canopy_radiant_energy_fluxes!Method
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.

ClimaLand.Canopy.canopy_temperatureMethod
canopy_temperature(model::BigLeafEnergyModel, canopy, Y, p, t)

Returns the canopy temperature under the BigLeafEnergyModel model, where the canopy temperature is modeled prognostically.

ClimaLand.Canopy.canopy_temperatureMethod
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.

ClimaLand.Canopy.co2_compensationMethod
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).

ClimaLand.Canopy.compute_GPPMethod
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 (Ω).

ClimaLand.Canopy.compute_NIRMethod
compute_NIR(
    model::AbstractRadiationModel,
    solar_radiation::ClimaLand.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.

ClimaLand.Canopy.compute_PARMethod
compute_PAR(
    model::AbstractRadiationModel,
    solar_radiation::ClimaLand.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.

ClimaLand.Canopy.compute_VcmaxMethod
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).

ClimaLand.Canopy.compute_absorbancesMethod
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 = ))

ClimaLand.Canopy.compute_absorbancesMethod
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 = ))

ClimaLand.Canopy.dark_respirationMethod
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).

ClimaLand.Canopy.diffuse_fractionMethod
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].

ClimaLand.Canopy.electron_transportMethod
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).

ClimaLand.Canopy.extinction_coeffMethod
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).

ClimaLand.Canopy.filter_ntMethod
filter_nt(nt)

Base case for filter_nt recursion, used when this function is called on a NamedTuple with no nested NamedTuples.

ClimaLand.Canopy.filter_ntMethod
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.

ClimaLand.Canopy.intercellular_co2Method
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).

ClimaLand.Canopy.light_assimilationMethod
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).

ClimaLand.Canopy.light_assimilationMethod
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).

ClimaLand.Canopy.max_electron_transportMethod
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).

ClimaLand.Canopy.medlyn_conductanceMethod
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.

ClimaLand.Canopy.medlyn_termMethod
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.

ClimaLand.Canopy.moisture_stressMethod
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).

ClimaLand.Canopy.net_photosynthesisMethod
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).

ClimaLand.Canopy.nitrogen_contentMethod
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).

ClimaLand.Canopy.optimality_max_photosynthetic_ratesMethod

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.

ClimaLand.Canopy.penman_monteithMethod
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.

ClimaLand.Canopy.plant_absorbed_pfdMethod
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.

ClimaLand.Canopy.plant_absorbed_pfdMethod
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.

ClimaLand.Canopy.plant_respiration_growthMethod
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.

ClimaLand.Canopy.plant_respiration_maintenanceMethod
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 (β).

ClimaLand.Canopy.root_energy_flux_per_ground_area!Method
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.

ClimaLand.Canopy.rubisco_assimilationMethod
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).

ClimaLand.Canopy.rubisco_assimilationMethod
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).

ClimaLand.Canopy.set_canopy_prescribed_field!Method
 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.

ClimaLand.Canopy.update_canopy_prescribed_field!Method
 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.

ClimaLand.Canopy.update_photosynthesis!Method
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.

ClimaLand.Canopy.update_photosynthesis!Method
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.

ClimaLand.Canopy.upscale_leaf_conductanceMethod
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.

ClimaLand.auxiliary_domain_namesMethod

auxiliarydomainnames(m::AbstractCanopyComponent)

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

ClimaLand.auxiliary_typesMethod
ClimaLand.auxiliary_types(::AbstractCanopyComponent)

Returns the auxiliary types of the canopy component passed in as an argument.

ClimaLand.auxiliary_typesMethod
auxiliary_types(canopy::CanopyModel)

Returns the auxiliary types for the canopy model by looping over each sub-component name in canopy_components.

This relies on the propertynames of CanopyModel being the same as those returned by canopy_components.

ClimaLand.auxiliary_varsMethod
ClimaLand.auxiliary_vars(::AbstractCanopyComponent)

Returns the auxiliary types of the canopy component passed in as an argument.

ClimaLand.auxiliary_varsMethod
auxiliary_vars(canopy::CanopyModel)

Returns the auxiliary variables for the canopy model by looping over each sub-component name in canopy_components.

This relies on the propertynames of CanopyModel being the same as those returned by canopy_components.

ClimaLand.displacement_heightMethod
ClimaLand.displacment_height(model::CanopyModel, Y, p)

A helper function which returns the displacement height for the canopy model.

See Cowan 1968; Brutsaert 1982, pp. 113–116; Campbell and Norman 1998, p. 71; Shuttleworth 2012, p. 343; Monteith and Unsworth 2013, p. 304.

ClimaLand.initialize_auxiliaryMethod
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.

ClimaLand.initialize_auxiliaryMethod
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.

ClimaLand.initialize_prognosticMethod
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.

ClimaLand.initialize_prognosticMethod
initialize_prognostic(
    model::CanopyModel{FT},
    coords,
) where {FT}

Creates the prognostic state vector of the CanopyModel and returns it as a ClimaCore.Fields.FieldVector.

The input state is usually a ClimaCore Field object.

This function loops over the components of the CanopyModel and appends each component models prognostic state vector into a single state vector, structured by component name.

ClimaLand.make_compute_exp_tendencyMethod
 ClimaLand.make_compute_exp_tendency(component::AbstractCanopyComponent, canopy)

Creates the computeexptendency!(dY,Y,p,t) function for the canopy component.

Since component models are not standalone models, other information may be needed and passed in (via the canopy model itself). The right hand side for the entire canopy model can make use of these functions for the individual components.

ClimaLand.make_set_initial_cacheMethod
ClimaLand.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.

ClimaLand.make_update_auxMethod
 ClimaLand.make_update_aux(canopy::CanopyModel{FT,
                                              <:AutotrophicRespirationModel,
                                              <:Union{BeerLambertModel, TwoStreamModel},
                                              <:FarquharModel,
                                              <:MedlynConductanceModel,
                                              <:PlantHydraulicsModel,},
                          ) where {FT}

Creates the update_aux! function for the CanopyModel; a specific method for update_aux! for the case where the canopy model components are of the type in the parametric type signature: AutotrophicRespirationModel, AbstractRadiationModel, FarquharModel, MedlynConductanceModel, and PlantHydraulicsModel.

Please note that the plant hydraulics model has auxiliary variables that are updated in its prognostic compute_exp_tendency! function. While confusing, this is better for performance as it saves looping over the state vector multiple times.

The other sub-components rely heavily on each other, so the version of the CanopyModel with these subcomponents has a single update_aux! function, given here.

ClimaLand.prognostic_domain_namesMethod

prognosticdomainnames(m::AbstractCanopyComponent)

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

ClimaLand.prognostic_typesMethod
ClimaLand.prognostic_types(::AbstractCanopyComponent)

Returns the prognostic types of the canopy component passed in as an argument.

ClimaLand.prognostic_typesMethod
prognostic_types(canopy::CanopyModel)

Returns the prognostic types for the canopy model by looping over each sub-component name in canopy_components.

This relies on the propertynames of CanopyModel being the same as those returned by canopy_components.

ClimaLand.prognostic_varsMethod
ClimaLand.prognostic_vars(::AbstractCanopyComponent)

Returns the prognostic vars of the canopy component passed in as an argument.

ClimaLand.prognostic_varsMethod
prognostic_vars(canopy::CanopyModel)

Returns the prognostic variables for the canopy model by looping over each sub-component name in canopy_components.

This relies on the propertynames of CanopyModel being the same as those returned by canopy_components.

ClimaLand.surface_heightMethod
ClimaLand.surface_height(model::CanopyModel, Y, _...)

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

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

Returns the surface resistance field of the CanopyModel canopy.

ClimaLand.surface_specific_humidityMethod
ClimaLand.surface_specific_humidity(model::CanopyModel, Y, p)

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

ClimaLand.surface_temperatureMethod
ClimaLand.surface_temperature(model::CanopyModel, Y, p, t)

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

ClimaLand.Snow.ModelTools.LinearModelMethod
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.
ClimaLand.Snow.ModelTools.LinearModelMethod
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.
ClimaLand.Snow.ModelTools.custom_lossMethod
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.
ClimaLand.Snow.ModelTools.evaluateMethod
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.
ClimaLand.Snow.ModelTools.evaluateMethod
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.
ClimaLand.Snow.ModelTools.make_modelMethod
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.
ClimaLand.Snow.ModelTools.make_timeseriesMethod
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.
ClimaLand.Snow.ModelTools.setoutscale!Method
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.
ClimaLand.Snow.ModelTools.settimescale!Method
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.
ClimaLand.Snow.ModelTools.trainmodel!Method
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.

ClimaLand.Snow.DataTools.apply_boundsMethod
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).

ClimaLand.Snow.DataTools.data_urlMethod
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:
ClimaLand.Snow.DataTools.filter_phys!Method
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.
ClimaLand.Snow.DataTools.get_dataMethod
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".
ClimaLand.Snow.DataTools.hourly2dailyMethod
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.
ClimaLand.Snow.DataTools.makediffsMethod
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].
ClimaLand.Snow.DataTools.prep_dataMethod
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.
ClimaLand.Snow.DataTools.rectify_daily_hourlyMethod
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.
ClimaLand.Snow.DataTools.rolldataMethod
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].
ClimaLand.Snow.DataTools.scale_colsMethod
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.

ClimaLand.Snow.DataTools.sitedata_dailyMethod
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".
ClimaLand.Snow.DataTools.sitedata_hourlyMethod
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".
ClimaLand.Snow.DataTools.snotel_metadataMethod
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"].

ClimaLand.Snow.DataTools.snowsplitMethod
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.
ClimaLand.Snow.DataTools.stack2DFMethod
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.
ClimaLand.FileReaderModule
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.

ClimaLand.FileReader.AbstractPrescribedDataType
abstract type AbstractPrescribedData

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

ClimaLand.FileReader.FileInfoType
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
  • varnames::Vector{String} # names of the variables we're reading from the input file
  • 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
ClimaLand.FileReader.FileStateType
FileState

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

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
ClimaLand.FileReader.PrescribedDataStaticType
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
ClimaLand.FileReader.PrescribedDataStaticMethod
PrescribedDataStatic{FT}(
    get_infile::Function,
    regrid_dirpath::String,
    varnames::Vector{String},
    surface_space::Spaces.AbstractSpace,
    mono::Bool = true,
) where {FT <: AbstractFloat}

Constructor for the PrescribedDataStatictype. Regrids from the input lat-lon grid to the simulation cgll grid, saving the regridded output in new files found atregrid_dirpath. Themono` flag here is used to determine whether or not the remapping is monotone.

Creates a FileInfo 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 passed to FileInfo) are unused for static data maps.

ClimaLand.FileReader.PrescribedDataTemporalType
PrescribedDataTemporal <: AbstractPrescribedData

Stores information to read in prescribed data from a file. Contains sufficient information to read in the variables at various timesteps, and to coordinate this reading between data coming from different files. This type is meant to be used with input data that has a time dimension. The file_states field is a dictionary mapping variable names to FileState structs, which contain information about the current data for that variable.

Inputs:

  • file_info::FI # unchanging info about the input data file
  • file_states::Dict{S, FS} # info about the data currently being read from file for each variable
  • sim_info::SI # unchanging info about the start date/time of the simulation
ClimaLand.FileReader.PrescribedDataTemporalMethod
PrescribedDataTemporal{FT}(
    regrid_dirpath,
    get_infile,
    varnames,
    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.
  • varnames # names of the variables 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
ClimaLand.FileReader.SimInfoType
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`
ClimaLand.FileReader.get_data_at_dateMethod
get_data_at_date(
    prescribed_data::PrescribedDataStatic,
    space::Spaces.AbstractSpace,
    varname::String,
)

Returns the data at a given date, interpolated if necessary.

Arguments

  • prescribed_data # contains fields to be interpolated.
  • space # the space of our simulation.
  • varname # the name of the variable we want to read in.

Returns

  • Fields.field
ClimaLand.FileReader.get_data_at_dateMethod
get_data_at_date(
    prescribed_data::PrescribedDataTemporal,
    space::Spaces.AbstractSpace,
    varname::String,
    date::Union{DateTime, DateTimeNoLeap},
)

Returns the data for a specific variable at a given date, interpolated if necessary.

Arguments

  • prescribed_data # contains fields to be interpolated.
  • space # the space of our simulation.
  • varname # the name of the variable we want to read in.
  • date # start date for data.

Returns

  • Fields.field
ClimaLand.FileReader.interpolMethod
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
ClimaLand.FileReader.next_date_in_fileMethod
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. Assumes that all variables in prescribed_data have the same dates.

Arguments

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

Returns

  • DateTime or DateTimeNoLeap
ClimaLand.FileReader.read_data_fields!Method
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 data and file information.
  • date # current date to read in data for.
  • space # space we're remapping the data onto.
ClimaLand.FileReader.to_datetimeMethod
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
ClimaLand.Soil.Biogeochemistry.AbstractSoilDriverType
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).

ClimaLand.Soil.Biogeochemistry.PrescribedMetType
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

ClimaLand.Soil.Biogeochemistry.PrescribedSOCType
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
ClimaLand.Soil.Biogeochemistry.SoilCO2ModelType
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

ClimaLand.Soil.Biogeochemistry.SoilCO2ModelMethod

SoilCO2Model{FT}(; parameters::SoilCO2ModelParameters{FT}, domain::ClimaLand.AbstractDomain, boundary_conditions::NamedTuple, sources::Tuple, drivers::DT, ) where {FT, BC, DT}

A constructor for SoilCO2Model.

ClimaLand.Soil.Biogeochemistry.SoilCO2ModelParametersType
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

ClimaLand.Soil.Biogeochemistry.SoilCO2ModelParametersMethod
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.

ClimaLand.Soil.Biogeochemistry.SoilCO2StateBCType
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.

ClimaLand.Soil.Biogeochemistry.SoilDriversType
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

ClimaLand.Soil.Biogeochemistry.co2_diffusivityMethod
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.

ClimaLand.Soil.Biogeochemistry.microbe_sourceMethod
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).

ClimaLand.Soil.Biogeochemistry.volumetric_air_contentMethod
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).

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

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

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

A method of ClimaLand.boundary_flux which returns the soilco2 flux (kg CO2 /m^2/s) in the case of a prescribed flux BC at either the top or bottom of the domain.

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

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

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

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

ClimaLand.make_compute_exp_tendencyMethod
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.

ClimaLand.make_update_auxMethod
make_update_aux(model::SoilCO2Model)

An extension of the function make_update_aux, for the soilco2 equation. This function creates and returns a function which updates the auxiliary variables p.soil.variable in place. This has been written so as to work with Differential Equations.jl.

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

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

ClimaLand.Canopy.PlantHydraulics.DiagnosticTranspirationType
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.

ClimaLand.Canopy.PlantHydraulics.LinearRetentionCurveType
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.
ClimaLand.Canopy.PlantHydraulics.PlantHydraulicsModelType
PlantHydraulicsModel{FT, PS, T, AA} <: AbstractPlantHydraulicsModel{FT}

Defines, and constructs instances of, the PlantHydraulicsModel type, which is used for simulation flux of water to/from soil, along roots of different depths, along a stem, to a leaf, and ultimately being lost from the system by transpiration. Note that the canopy height is specified as part of the PlantHydraulicsModel, along with the area indices of the leaves, roots, and stems.

This model can also be combined with the soil model using ClimaLand, in which case the prognostic soil water content is used to determine root extraction, and the transpiration is also computed diagnostically. In global run with patches of bare soil, you can "turn off" the canopy model (to get zero root extraction, zero absorption and emission, zero transpiration and sensible heat flux from the canopy), by setting:

  • n_leaf = 1
  • n_stem = 0
  • LAI = SAI = RAI = 0.

A plant model can have leaves but no stem, but not vice versa. If n_stem = 0, SAI must be zero.

Finally, the model can be used in Canopy standalone mode by prescribing the soil matric potential at the root tips or flux in the roots. There is also the option (intendend only for debugging) to use a prescribed transpiration rate.

  • n_stem: The number of stem compartments for the plant; can be zero

  • n_leaf: The number of leaf compartments for the plant; must be >=1

  • compartment_midpoints: The height of the center of each leaf compartment/stem compartment, in meters

  • compartment_surfaces: The height of the compartments' top faces, in meters. The canopy height is the last element of the vector.

  • compartment_labels: The label (:stem or :leaf) of each compartment

  • parameters: Parameters required by the Plant Hydraulics model

  • transpiration: The transpiration model, of type AbstractTranspiration

ClimaLand.Canopy.PlantHydraulics.PlantHydraulicsParametersType
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)

ClimaLand.Canopy.PlantHydraulics.PrescribedSiteAreaIndexType

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)

ClimaLand.Canopy.PlantHydraulics.WeibullType
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).

ClimaLand.Canopy.PlantHydraulics.augmented_liquid_fractionMethod
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.

ClimaLand.Canopy.PlantHydraulics.fluxMethod
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.

ClimaLand.Canopy.PlantHydraulics.lai_consistency_checkMethod
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.

ClimaLand.Canopy.PlantHydraulics.root_water_flux_per_ground_area!Method
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.

ClimaLand.Canopy.PlantHydraulics.transpiration_per_ground_areaMethod
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.

ClimaLand.Canopy.PlantHydraulics.transpiration_per_ground_areaMethod
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.

ClimaLand.Canopy.PlantHydraulics.water_retention_curveMethod
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.

ClimaLand.Canopy.set_canopy_prescribed_field!Method
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.

ClimaLand.Canopy.update_canopy_prescribed_field!Method
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.

ClimaLand.auxiliary_typesMethod
ClimaLand.auxiliary_types(model::PlantHydraulicsModel{FT}) where {FT}

Defines the auxiliary types for the PlantHydraulicsModel.

ClimaLand.auxiliary_varsMethod
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.

ClimaLand.make_compute_exp_tendencyMethod
make_compute_exp_tendency(model::PlantHydraulicsModel, _)

A function which creates the computeexptendency! function for the PlantHydraulicsModel. The computeexptendency! function must comply with a rhs function of SciMLBase.jl.

Below, fa denotes a flux multiplied by the relevant cross section (per unit area ground, or area index, AI). The tendency for the ith compartment can be written then as: ∂ϑ[i]/∂t = 1/(AI*dz)[fa[i]-fa[i+1]).

Note that if the area_index is zero because no plant is present, AIdz is zero, and the fluxes fa appearing in the numerator are zero because they are scaled by AI.

To prevent dividing by zero, we change AI/(AI x dz)" to "AI/max(AI x dz, eps(FT))"

ClimaLand.prognostic_typesMethod
ClimaLand.prognostic_types(model::PlantHydraulicsModel{FT}) where {FT}

Defines the prognostic types for the PlantHydraulicsModel.

ClimaLand.prognostic_varsMethod
prognostic_vars(model::PlantHydraulicsModel)

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

ClimaLand.TimeVaryingInputs.AbstractInterpolationMethodType
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).

ClimaLand.TimeVaryingInputs.AbstractTimeVaryingInputType
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
ClimaLand.TimeVaryingInputs.InterpolatingTimeVaryingInput0DType
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.

Base.inMethod
in(time, itp::InterpolatingTimeVaryingInput0D)

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

ClimaLand.TimeVaryingInputs.TimeVaryingInputFunction
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.

ClimaLand.TimeVaryingInputs.evaluate!Function
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.

ClimaLand.TimeVaryingInputs.evaluate!Method
evaluate!(
    dest,
    itp::InterpolatingTimeVaryingInput0D,
    time,
    ::LinearInterpolation,
    )

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