Soil Models

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.

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

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

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

A struct for storing parameters of the RichardsModel.

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

• hydrology_cm: The hydrology closure model: vanGenuchten or BrooksCorey

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

• S_s: The specific storativity (1/m)

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

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

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

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

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

roughness lengths z0, dds ) (FT)

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

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

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

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

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

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

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

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

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

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

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

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

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

• S_s: The specific storativity (1/m)

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

• Ω: Ice impedance factor for the hydraulic conductivity

• γ: Coefficient of viscosity factor for the hydraulic conductivity

• γT_ref: Reference temperature for the viscosity factor

• PAR_albedo_dry: Soil PAR Albedo dry

• NIR_albedo_dry: Soil NIR Albedo dry

• PAR_albedo_wet: Soil PAR Albedo wet

• NIR_albedo_wet: Soil NIR Albedo wet

• albedo_calc_top_thickness: Thickness of top of soil used in albedo calculations (m)

• 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

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.

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.

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.

 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.

 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.

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.

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.

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

A point-wise function computing the effective saturation.

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

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

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

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

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

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

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.

 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.

 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.

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.

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

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

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

Compute the expression for volumetric heat capacity.

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

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

Computes the thermal conductivity for saturated frozen soil.

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

Computes the thermal conductivity for saturated unfrozen soil.

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

Compute the expression for saturated thermal conductivity of soil matrix.

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.

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

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

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.

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

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

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

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

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

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

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

Compute the expression for thermal conductivity of soil matrix.

phase_change_source(
    θ_l::FT,
    θ_i::FT,
    T::FT,
    τ::FT,
    ν::FT,
    θ_r::FT,
    hydrology_earth_params::HEP
) where {FT, HEP}

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.

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

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

NoRunoff <: AbstractRunoffModel

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

SurfaceRunoff <: AbstractRunoffModel

A simple model for runoff appropriate for single column runs.

Only surface runoff is computed, using a combination of Dunne and Hortonian runoff.

TOPMODELRunoff{FT <: AbstractFloat, F <: ClimaCore.Fields.Field} <: AbstractRunoffModel

The TOPMODEL surface runoff parameterization, which is affects the surface boundary condition of the soil model.

The runoff flux is given by Equation 8 of with fsat given by Equation (11), of Niu et al. (2005), "A simple TOPMODEL-based runoff parameterization (SIMTOP) for use in global climate models".

• f_over: A calibrated parameter defining how subsurface runoff decays with depth to water table (1/m ; calibrated)

• f_max: The maximum saturated fraction of a grid cell, computed from the topographic index CDF per grid cell.

• subsurface_source: The subsurface source term corresponding to this implementation of TOPMODEL.

TOPMODELSubsurfaceRunoff{FT} <: AbstractSoilSource{FT}

The TOPMODEL subsurface runoff parameterization, which is implemented as a sink term in the soil equations.

The runoff flux is given by Equation 12 of Niu et al. (2005), "A simple TOPMODEL-based runoff parameterization (SIMTOP) for use in global climate models".

• R_sb: The subsurface runoff flux (m/s) when the depth to the water table = 1/f_over; calibrated

• f_over: A calibrated parameter defining how subsurface runoff decays with depth to water table (1/m ; calibrated)

subsurface_runoff_source(runoff::AbstractRunoffModel)

A helper function which returns the subsurface source of the runoff model runoff.

update_runoff!(p, runoff::NoRunoff, input, _...)

Updates the runoff variables in the cache p.soil in place in the case of NoRunoff: sets infiltration = precipitation.

update_runoff!(
    p,
    runoff::SurfaceRunoff,
    input,
    Y,
    t,
    model::AbstractSoilModel,

)

The update_runoff! function for the SurfaceRunoff model.

Updates the runoff model variables in place in p.soil for the SurfaceRunoff parameterization: p.soil.Rs p.soil.issaturated p.soil.infiltration

update_runoff!(p, runoff::TOPMODELRunoff, input, Y,t, model::AbstractSoilModel)

Updates the runoff model variables in place in p.soil for the TOPMODELRunoff parameterization: p.soil.Rs p.soil.Rss p.soil.h∇ p.soil.infiltration

MoistureStateBC <: AbstractWaterBC

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

HeatFluxBC <: AbstractHeatBC

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

WaterFluxBC <: AbstractWaterBC

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

TemperatureStateBC <: AbstractHeatBC

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

FreeDrainage <: AbstractWaterBC

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

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

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

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

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

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

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

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

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

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

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

Finally, because this same boundary condition type is used for the soil in integrated land surface models, we also provide a tuple of symbols indicating the prognostic land components present, as these affect how the boundary conditions are computed. The default is a tuple containing only (:soil,), indicating a standalone soil run.

For more information on the allowed values, please see the documentation

• atmos: The atmospheric conditions driving the model

• radiation: The radiative fluxes driving the model

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

• prognostic_land_components: Prognostic land components present

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

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

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

updates the boundary fluxes for ϑl and ρeint.

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.

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. It also accounts for the presence of other components, if run as part of an integrated land model, and their effect on boundary conditions.

soil_boundary_fluxes!(
    bc::AtmosDrivenFluxBC{
        <:PrescribedAtmosphere,
        <:PrescribedRadiativeFluxes,
    },
    prognostic_land_components::Val{(:soil,)},
    model::EnergyHydrology,
    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.

Here, the soil boundary fluxes are computed as if the soil is run in standalone mode.

soil_boundary_fluxes!(
    bc::AtmosDrivenFluxBC{<:PrescribedAtmosphere, <:PrescribedRadiativeFluxes},
    prognostic_land_components::Val{(:canopy, :soil,:soilco2,)},
    soil::EnergyHydrology{FT},
    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 when a canopy and Soil CO2 model is also included, though only the presence of the canopy modifies the soil BC.

soil_boundary_fluxes!(
    bc::AtmosDrivenFluxBC{<:PrescribedAtmosphere, <:PrescribedRadiativeFluxes},
     prognostic_land_components::Val{(:snow, :soil)},
    soil::EnergyHydrology{FT},
    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, taking into account the presence of snow on the surface.

soil_boundary_fluxes!(
    bc::AtmosDrivenFluxBC{<:PrescribedAtmosphere, <:PrescribedRadiativeFluxes},
    prognostic_land_components::Val{(:canopy, :snow, :soil,:soilco2,)},
    soil::EnergyHydrology{FT},
    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 when a canopy and Soil CO2 model is also included, though only the presence of the canopy modifies the soil BC.

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

PhaseChange{FT} <: AbstractSoilSource{FT}

PhaseChange source type.

ImplicitEquationJacobian{M, S}

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

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

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