ClimaLand

struct LandModel{
    FT,
    MM <: Soil.Biogeochemistry.SoilCO2Model{FT},
    SM <: Soil.EnergyHydrology{FT},
    VM <: Canopy.CanopyModel{FT},
    SnM <: Snow.SnowModel{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
    "The snow model to be used"
    snow::SnM
end

A concrete type of land model used for simulating systems with soil, canopy, snow, soilco2.

ClimaLand v1: SoilCO2 is still under testing, but errors in soilco2 do not propagate into the other components.

• soilco2: The soil microbe model to be used

• soil: The soil model to be used

• canopy: The canopy model to be used

• snow: The snow model to be used

LandModel{FT}(
    forcing,
    LAI,
    toml_dict::CP.ParamDict,
    domain::Union{ClimaLand.Domains.Column, ClimaLand.Domains.SphericalShell},
    Δt;
    soil = Soil.EnergyHydrology{FT}(
        domain,
        forcing,
        toml_dict;
        prognostic_land_components = (:canopy, :snow, :soil, :soilco2),
        additional_sources = (ClimaLand.RootExtraction{FT}(),),
    ),
    soilco2 = Soil.Biogeochemistry.SoilCO2Model{FT}(
        domain,
        Soil.Biogeochemistry.SoilDrivers(
           PrognosticMet(soil.parameters),
            PrescribedSoilOrganicCarbon{FT}(TimeVaryingInput((t) -> 5)),
            forcing.atmos,
        ),
        toml_dict,
    ),
    canopy = Canopy.CanopyModel{FT}(
        Domains.obtain_surface_domain(domain),
        (;
            atmos = forcing.atmos,
            radiation = forcing.radiation,
            ground = ClimaLand.PrognosticGroundConditions{FT}(),
        ),
        LAI,
        toml_dict;
        prognostic_land_components = (:canopy, :snow, :soil, :soilco2),
    ),
   snow = Snow.SnowModel(
        FT,
        ClimaLand.Domains.obtain_surface_domain(domain),
        forcing,
        toml_dict,
        Δt;
        prognostic_land_components = (:canopy, :snow, :soil, :soilco2),
    ),
) where {FT}

A convenience constructor for setting up the default LandModel, where all the parameterizations and parameter values are set to default values or passed in via the toml_dict. The boundary conditions of all models correspond to forcing with the atmosphere, as specified by forcing, a NamedTuple of the form (;atmos, radiation), with atmos an AbstractAtmosphericDriver and radiation and AbstractRadiativeDriver. The leaf area index LAI must be provided (prescribed) as a TimeVaryingInput, and the domain must be a ClimaLand domain with a vertical extent. Finally, since the snow model requires the timestep, that is a required argument as well.

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, a soil, and a soilco2 component.

ClimaLand v1: SoilCO2 is still under testing, but errors in soilco2 do not propagate into the other components.

• soilco2: The soil microbe model to be used

• soil: The soil model to be used

• canopy: The canopy model to be used

SoilCanopyModel{FT}(
    forcing,
    LAI,
    toml_dict::CP.ParamDict,
    domain::Union{ClimaLand.Domains.Column, ClimaLand.Domains.SphericalShell};
    soil = Soil.EnergyHydrology{FT}(
        domain,
        forcing,
        toml_dict;
        prognostic_land_components = (:canopy, :soil, :soilco2),
        additional_sources = (ClimaLand.RootExtraction{FT}(),),
    ),
    soilco2 = Soil.Biogeochemistry.SoilCO2Model{FT}(
        domain,
        Soil.Biogeochemistry.SoilDrivers(
           PrognosticMet(soil.parameters),
            PrescribedSoilOrganicCarbon{FT}(TimeVaryingInput((t) -> 5)),
            forcing.atmos,
        ),
        toml_dict,
    ),
    canopy = Canopy.CanopyModel{FT}(
        Domains.obtain_surface_domain(domain),
        (;
            atmos = forcing.atmos,
            radiation = forcing.radiation,
            ground = ClimaLand.PrognosticGroundConditions{FT}(),
        ),
        LAI,
        toml_dict;
        prognostic_land_components = (:canopy, :soil, :soilco2),
    ),
) where {FT}

A convenience constructor for setting up the default SoilCanpyModel, where all the parameterizations and parameter values are set to default values or passed in via the toml_dict. The boundary conditions of all models correspond to forcing with the atmosphere, as specified by forcing, a NamedTuple of the form (;atmos, radiation), with atmos an AbstractAtmosphericDriver and radiation and AbstractRadiativeDriver. The leaf area index LAI must be provided (prescribed) as a TimeVaryingInput, and the domain must be a ClimaLand domain with a vertical extent.

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.

ClimaLand v1: SoilCO2 is still under testing, but errors in soilco2 do not propagate into the other components.

• soil: The soil model

• soilco2: The biochemistry model

LandSoilBiogeochemistry{FT}(
    forcing,
    toml_dict::CP.ParamDict,
    domain::Union{ClimaLand.Domains.Column, ClimaLand.Domains.SphericalShell};
    soil = Soil.EnergyHydrology{FT}(
        domain,
        forcing,
        toml_dict;
    ),
    soilco2 = Soil.Biogeochemistry.SoilCO2Model{FT}(
        domain,
        Soil.Biogeochemistry.SoilDrivers(
           Soil.Biogeochemistry.PrognosticMet(soil.parameters),
            PrescribedSoilOrganicCarbon{FT}(TimeVaryingInput((t) -> 5)),
            forcing.atmos,
        ),
    ),
) where {FT}

A convenience constructor for setting up the default LandSoilBiogeochemistry, where all the parameterizations and parameter values are set to default values or passed in via the toml_dict. The boundary conditions of all models correspond to forcing with the atmosphere, as specified by forcing, a NamedTuple of the form (;atmos, radiation), with atmos an AbstractAtmosphericDriver and radiation an AbstractRadiativeDriver. The domain must be a ClimaLand domain with a vertical extent.

struct SoilSnowModel{
    FT,
    SnM <: Snow.SnowModel{FT},
    SoM <: Soil.EnergyHydrology{FT},
} <: AbstractLandModel{FT}
    "The snow model to be used"
    snow::SnM
    "The soil model to be used"
    soil::SoM
end

A concrete type of land model used for simulating systems with snow and soil.

The inner constructor checks that the two models are consistent with respect to the forcing (atmos, radiation), the parameters, the domain, and the prognostic land components of the model.

• snow: The snow model to be used

• soil: The soil model to be used

SoilSnowModel{FT}(
    forcing,
    toml_dict::CP.ParamDict,
    domain::Union{ClimaLand.Domains.Column, ClimaLand.Domains.SphericalShell},
    Δt;
    soil = Soil.EnergyHydrology{FT}(
        domain,
        forcing,
        toml_dict;
        prognostic_land_components = (:snow, :soil),
        additional_sources = (),
    ),
    snow = Snow.SnowModel(
        FT,
        ClimaLand.Domains.obtain_surface_domain(domain),
        forcing,
        toml_dict,
        Δt;
        prognostic_land_components = (:snow, :soil,),
    ),
) where {FT}

A convenience constructor for setting up the default SoilSnowModel, where all the parameterizations and parameter values are set to default values or passed in via the toml_dict. The boundary conditions of all models correspond to forcing with the atmosphere, as specified by forcing, a NamedTuple of the form (;atmos, radiation), with atmos an AbstractAtmosphericDriver and radiation an AbstractRadiativeDriver. The domain must be a ClimaLand domain with a vertical extent. Finally, since the snow model requires the timestep, that is a required argument as well.

land_components(land::AbstractLandModel)

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

ClimaLand.land_components(land::LandModel)

Returns the components of the LandModel.

Currently, this method is required in order to preserve an ordering in how we update the component models' auxiliary states. The canopy update_aux! step depends on snow and soil albedo, but those are only updated in the snow and soil update_aux! steps. So those must occur first (as controlled by the order of the components returned by land_components!.

This needs to be fixed.

lsm_aux_vars(m::AbstractLandModel)

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

lsm_aux_vars(m::SoilCanopyModel)

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

These include the broadband albedo of the land surface α_sfc, defined as the ratio of SWu/SWd, and T_sfc, defined as the temperature a blackbody with emissivity ϵ_sfc would have in order to emit the same LW_u as the land surface does. This is called the effective temperature in some fields, and is not the same as the skin temperature (defined e.g. Equation 7.13 of Bonan, 2019, Climate Change and Terrestrial Ecosystem Modeling. DOI: 10.1017/9781107339217).

lsm_aux_vars(m::SoilSnowModel)

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

lsm_aux_vars(m::LandModel)

The names of the additional auxiliary variables that are included in the land model.

lsm_aux_types(m::AbstractLandModel)

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

lsm_aux_types(m::SoilCanopyModel)

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

lsm_aux_types(m::SoilSnowModel)

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

lsm_aux_types(m::LandModel)

The types of the additional auxiliary variables that are included in the land model.

lsm_aux_domain_names(m::AbstractLandModel)

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

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

lsm_aux_domain_names(m::SoilCanopyModel)

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

lsm_aux_domain_names(m::SoilSnowModel)

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

lsm_aux_domain_names(m::LandModel)

The domain names of the additional auxiliary variables that are included in the land model.

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.

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.

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.

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.

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; treated explicitly in all prognostic variables.

PrognosticMet <: AbstractSoilDriver

A container which holds the soil parameters needed for running biogeochemistry model with the soil model.

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

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

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