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.

• 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}(;
    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 = (;),
    snow_model_type::Type{SnM},
    snow_args::NamedTuple = (;),
    ) where {
        FT,
        SM <: Soil.EnergyHydrology{FT},
        MM <: Soil.Biogeochemistry.SoilCO2Model{FT},
        SnM <: Snow.SnowModel{FT}
        }

A constructor for the LandModel, which takes in the concrete model type and required arguments for each component, constructs those models, and constructs the LandModel 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.

LandModel{FT}(
    forcing,
    LAI,
    toml_dict::CP.AbstractTOMLDict,
    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(
           Soil.Biogeochemistry.PrognosticMet(soil.parameters),
            PrescribedSoilOrganicCarbon{FT}(TimeVaryingInput((t) -> 5)),
            forcing.atmos,
        ),
    ),
    canopy = Canopy.CanopyModel{FT}(
        Domains.obtain_surface_domain(domain),
        (;
            atmos = forcing.atmos,
            radiation = forcing.radiation,
            ground = ClimaLand.PrognosticSoilConditions{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 and a soil component.

• soilco2: The soil microbe model to be used

• soil: The soil model to be used

• canopy: The canopy model to be used

SoilCanopyModel{FT}(
    forcing,
    LAI,
    toml_dict::CP.AbstractTOMLDict,
    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(
           Soil.Biogeochemistry.PrognosticMet(soil.parameters),
            PrescribedSoilOrganicCarbon{FT}(TimeVaryingInput((t) -> 5)),
            forcing.atmos,
        ),
    ),
    canopy = Canopy.CanopyModel{FT}(
        Domains.obtain_surface_domain(domain),
        (;
            atmos = forcing.atmos,
            radiation = forcing.radiation,
            ground = ClimaLand.PrognosticSoilConditions{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 LandHydrology{
    FT,
    SM <: Soil.AbstractSoilModel{FT},
    SW <: Pond.AbstractSurfaceWaterModel{FT},
} <: AbstractLandModel{FT}

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

• soil: The soil model

• surface_water: The surface water model

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

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

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

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

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

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

• soil: The soil model

• soilco2: The biochemistry model

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

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

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

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

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

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 updateaux! step depends on snow and soil albedo, but those are only updated in the snow and soil updateaux! steps. So those must occur first (as controlled by the order of the components returned by land_components!.

This needs to be fixed.

lsmauxvars(m::AbstractLandModel)

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

lsm_aux_vars(m::SoilCanopyModel)

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

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 LWu as the land surface does. This is called the [effective temperature](https://en.wikipedia.org/wiki/Effectivetemperature) 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.

lsmauxtypes(m::AbstractLandModel)

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

lsm_aux_types(m::SoilCanopyModel)

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

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.

lsmauxdomain_names(m::AbstractLandModel)

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

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

lsm_aux_domain_names(m::SoilCanopyModel)

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

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.

 PrognosticSoilConditions <: AbstractGroundConditions

A type of AbstractGroundConditions to use when the soil model is prognostic and of type EnergyHydrology. PrognosticSoilConditions functions as a flag and is used for dispatch with the canopy model.

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)