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

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.

RichardsModel{FT}(domain, forcing;
                     runoff =  ClimaLand.Soil.Runoff.TOPMODELRunoff{FT}(f_over = FT(3.28),
                                                                        R_sb = FT(1.484e-4 / 1000),
                                                                        f_max = topmodel_fmax(domain.space.surface,FT),
                                                                        ),
                     retention_parameters = rosetta_soil_vangenuchten_parameters(domain.space.subsurface, FT),
                     S_s = ClimaCore.Fields.zeros(domain.space.subsurface) .+ 1e-3,
                     )

Creates a RichardsModel model with the given float type FT, domain and forcing. Here, forcing should be a NamedTuple containing a field atmos with the atmospheric forcing.

Default spatially varying parameters (for retention curve parameters and specific storativity) are provided but can be changed with keyword arguments.

The runoff parameterization is also provided and can be changed via keyword argument.

EnergyHydrology <: AbstractSoilModel

A model for simulating the flow of water and heat in a porous medium by solving the Richardson-Richards equation and the heat equation, including terms for phase change.

A variety of boundary condition types are supported, including FluxBC, MoistureStateBC/TemperatureStateBC, FreeDrainage (only for the bottom of the domain), and an AtmosDrivenFluxBC (under which radiative fluxes and turbulent surface fluxes are computed and used as boundary conditions). Please see the documentation for this boundary condition type for more details.

• parameters: The parameter sets

• domain: the soil domain, using ClimaCore.Domains

• boundary_conditions: the boundary conditions for RRE and heat, of type AbstractSoilBoundaryConditions

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

• lateral_flow: A boolean flag which, when false, turns off the horizontal flow of water and heat

EnergyHydrology{FT}(;
    parameters::PS
    domain::D,
    boundary_conditions::NamedTuple,
    sources::Tuple,
    lateral_flow::Bool = false,
) where {FT, D, PS}

A constructor for a EnergyHydrology model, which sets the default value of the lateral_flow flag to false.

EnergyHydrology{FT}(domain, forcing, toml_dict::CP.ParamDict;
                     prognostic_land_components = (:soil),
                     albedo = CLMTwoBandSoilAlbedo{FT}(; clm_soil_albedo_parameters(domain.space.surface)...),
                     runoff::Runoff.AbstractRunoffModel = Runoff.TOPMODELRunoff(toml_dict,
                                                            f_max = topmodel_fmax(domain.space.surface, FT),
                                                        ),
                     retention_parameters = rosetta_soil_vangenuchten_parameters(domain.space.subsurface, FT),
                     composition_parameters = soil_composition_parameters(domain.space.subsurface, FT),
                     S_s = ClimaCore.Fields.zeros(domain.space.subsurface) .+ 1e-3,
                     z_0m = toml_dict["soil_momentum_roughness_length"],
                     z_0b = toml_dict["soil_scalar_roughness_length"],
                     emissivity = toml_dict["emissivity_bare_soil"],
                     additional_sources = (),
                     bottom_bc =
                         WaterHeatBC(; water = WaterFluxBC((p, t) -> 0.0), heat = HeatFluxBC((p, t) -> 0.0)),
                     ) where {FT <: AbstractFloat}

Creates a EnergyHydrology model with the given float type FT, domain, toml_dict, forcing, and prognostic land components.

The argument forcing should be a NamedTuple containing two fields: atmos and radiation.

When running the soil model in standalone mode, prognostic_land_components = (:soil,), while for running integrated land models, this should be a list of the component models. This value of this argument must be the same across all components in the land model.

Default spatially varying parameters (for retention curve parameters, composition, and specific storativity) are provided but can be changed with keyword arguments. Note that these parameters must all be of the same type: either FT or ClimaCore Fields. By default they are Fields read in from data, so in practice this means if some values are provided as Floats, all of these parameter defaults must be overwritten as Floats.

retention_parameters should be a NamedTuple with the following fields:

• ν: soil porosity
• hydrology_cm: the hydrology closure model being used
• K_sat: saturated hydraulic conductivity
• θ_r: residual water content

composition_parameters should be a NamedTuple with the following fields:

• ν_ss_om: soil organic matter volume fraction
• ν_ss_quartz: soil quartz volume fraction
• ν_ss_gravel: soil gravel volume fraction

The runoff and albedo parameterizations are also provided and can be changed via keyword argument; additional sources may be required in your model if the soil model will be composed with other component models.

Roughness lengths and soil emissivity are currently treated as constants; these can be passed in as Floats by kwarg; otherwise the default values are used.

This sets the bottom boundary conditions to be no flux by default, but these can be changed using the bottom_bc kwarg.

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)

RichardsParameters(;
    hydrology_cm::C,
    ν::F,
    K_sat::F,
    S_s::F,
    θ_r::F,
) where {F <: Union{<:AbstractFloat, ClimaCore.Fields.Field}, C}

Construct a RichardsParameters.

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

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

• soil composition and retention model parameters defined in the interior
• an albedo parameterization
• Scalar parameters: emissivity, α, β, γ, γT_ref, Ω,

roughness lengths z0, dds ) (FT)

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

• albedo: Soil Albedo Parameterization

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

• evap_p: Exponent used in soil resistance to evaporation (unitless)

• evap_α: Multiplicative scalar used as fitting parameter in critical soil water content for evaporation (unitless)

• earth_param_set: Physical constants and clima-wide parameters

EnergyHydrologyParameters(
    toml_dict;
    ν,
    ν_ss_om,
    ν_ss_quartz,
    ν_ss_gravel,
    hydrology_cm,
    K_sat,
    S_s,
    θ_r,
    albedo = Soil.ConstantTwoBandSoilAlbedo{FT}(),
    kwargs...,)

EnergyHydrologyParameters has two constructors: float-type and toml dict based. Additional parameters must be added manually: ν, ν_ss_om, ν_ss_quartz, ν_ss_gravel, hydrology_cm,Ksat,Ss, andθ_r. All parameters can be manually overridden via keyword arguments. Note, however, that certain parameters must have the same type (e.g, if a field is supplied for porosity, it must be supplied for all other parameters defined in the interior of the domain). Some parameters are defined only on the surface of the domain (e.g albedo), while other are defined everywhere (e.g. porosity). These are indicated with typesFandSF`. If both dry/wet albedos and general albedos are given as keywords, the dry/wet albedos will override the general albedos.

Please see the EnergyHydrologyParameters documentation for a complete list.

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. The output is guaranteed to be in (θ_r, ν_eff].

For Richards model, ν_eff = ν; and the clipping below is not required, (and will do nothing; ν_eff_safe = ν_eff), but we leave it in for a simpler interface.

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(ν_eff::FT, ϑ_l::FT, θr::FT) where {FT}

A point-wise function computing the effective saturation given the effective porosity, augmented liquid fraction, and residual water fraction as input.

For Richards model, or any other parameterization where ice is not relevant, νeff = ν; and the clipping below is not required, (and will do nothing; νeffsafe = νeff), but we leave it in for a simpler interface.

field_capacity_saturation(cm::vanGenuchten)
field_capacity_saturation(cm::BrooksCorey)

Return the effective saturation at field capacity. For the van Genuchten retention curve this is the saturation (1 + 1/m)^(-m) at the inflection point of S(ψ) (van Genuchten, 1980), which Assouline and Or (2014) identify with field capacity; it lies between 0.54 (n = 3) and 0.63 (n = 1.5). The Brooks and Corey curve has no inflection point, and the saturation at its air entry potential, one, is returned.

 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}, ϑ, ν_eff, θ_r, S_s)

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

dψdϑ(cm::BrooksCorey{FT}, ϑ, νeff, θr, S_s)

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_cm::CM,
    _ρ_i::FT,
    _ρ_l::FT,
    _LH_f0::FT,
    _T_freeze::FT,
    _grav::FT
    ) where {FT, CM}

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.

soil_surface_temperature(bc, p)

Return the soil surface temperature [K]: the skin temperature p.soil.turbulent_fluxes.T_sfc for atmospherically driven soil, and the top layer temperature otherwise.

Called from component_temperature(::EnergyHydrology, Y, p).

update_soil_surface_temperature!(model::EnergyHydrology, SW_n, LW_d, Y, p, t;
                                 h_atmos = atmos.h, u_atmos = p.drivers.u,
                                 T_atmos = p.drivers.T, q_atmos = p.drivers.q,
                                 gustiness = ClimaLand.gustiness_spec(atmos))
update_soil_surface_temperature!(model::EnergyHydrology, Y, p, t)

Solve for the soil skin temperature from the surface energy balance and store it, with the turbulent fluxes at it from the same Monin-Obukhov solve, in p.soil.turbulent_fluxes, and update the surface specific humidity p.soil.q_sfc at it; return nothing. The top boundary condition of the soil must be an AtmosDrivenFluxBC with the atmospheric driver atmos; an ArgumentError is thrown otherwise.

Arguments

• SW_n: Net shortwave radiation at the soil surface, positive upward, i.e. minus the absorbed shortwave radiation [W/m²].
• LW_d: Downwelling longwave radiation at the soil surface [W/m²].

SW_n and LW_d may be fields or lazy broadcasts; land models with a canopy pass the radiation transmitted and emitted by the canopy. The four-argument method is for soil exposed to the sky and uses the downwelling radiation in p.drivers and the soil albedo. The atmospheric pressure is read from p.drivers, whether prescribed or supplied by a coupler, and p.soil.sfc_scratch is overwritten. The reference height h_atmos, the wind u_atmos, temperature T_atmos, and specific humidity q_atmos at it, and the gustiness model default to those of the atmospheric forcing; land models with a canopy pass the sub-canopy reference height, attenuated wind, canopy-air temperature and humidity, and gustiness model (see Canopy.subcanopy_forcing).

Called from the soil_boundary_fluxes! methods and, in integrated models, from lsm_radiant_energy_fluxes!. See also solve_soil_surface_temperature_at_a_point.

soil_turbulent_fluxes(fluxes, T_sfc, Tf_depressed)

Return the NamedTuple stored in p.soil.turbulent_fluxes from the NamedTuple fluxes of ClimaLand.turbulent_fluxes_at_a_point at the surface temperature T_sfc [K]: the vapor flux is attributed to liquid water evaporating above the depressed freezing temperature Tf_depressed [K] and to ice sublimating at and below it, the temperature derivatives are dropped, and T_sfc, the effective surface humidity q_sfc of the solve (which includes the dry soil layer resistance, see soil_evaporation_beta), and the similarity scales ustar, ζ, Δz_eff of the solve are appended after the momentum and buoyancy fluxes, if present.

soil_evaporation_beta(q_air, qsat, g_liq, g_h, β_ice, frozen)

Return the β factor [-] of the β approach to soil evaporation (Mahfouf and Noilhan, 1991): the surface specific humidity of the soil is q_sfc = β * qsat + (1 - β) * q_air, so that the vapor flux is β g_h (qsat - q_air). β is the ice weight β_ice over a frozen surface losing water (frozen_soil_vapor_weight), one over a frozen surface gaining water, and the conductance ratio g_liq / (g_liq + g_h) of the dry soil layer otherwise. This is the same parameterization as get_update_surface_humidity_function(::EnergyHydrology), which turbulent_fluxes!(dest, atmos, ::EnergyHydrology, Y, p, t) uses.

frozen_soil_vapor_weight(θ_i, ν)

Return the weight β_ice = (θ_i / ν)^4 [-] of the saturation specific humidity in the surface specific humidity of a frozen soil losing water by sublimation, given the volumetric ice content θ_i and the porosity ν [m³/m³]. The flux at given air humidity and surface temperature does not otherwise depend on the ice present, so this weight makes the sublimation vanish as the ice does, faster than θ_i itself, which keeps an explicit time step from drawing on ice that is not there; it plays the role of the dry-soil-layer conductance for an unfrozen surface. The weight is a heuristic without a published source; the exponent gives strong suppression at intermediate ice contents.

Called from update_soil_surface_temperature! and get_update_surface_humidity_function(::EnergyHydrology).

soil_skin_state(T_sfc, inputs, thermo_params, param_set, ψ_sfc, Tf_depressed, earth_param_set) -> NamedTuple

Return (; ρ_sfc, qsat, ∂qsat∂T, frozen): the surface air density [kg/m³], extrapolated over the effective height with the current surface humidity guess of the solve, the saturation specific humidity at T_sfc adjusted for the soil water potential [kg/kg], its derivative with respect to temperature [1/K], and whether the surface is frozen.

Called from the SurfaceFluxes callbacks update_soil_T_sfc_scheme and update_soil_q_vap_sfc_scheme.

update_soil_T_sfc_scheme(ζ, param_set, thermo_params, inputs, scheme, u_star, z_0m, z_0b,
                         T_top, r, ϵ, σ, SW_n, LW_d, g_liq, β_ice, ψ_sfc, Tf_depressed,
                         earth_param_set)

Return the Newton update of the soil skin temperature [K] from ClimaLand.surface_temperature_newton_update, with the layer below at T_top, capped at the depressed freezing temperature Tf_depressed when the top cell is frozen (contains ice, β_ice > 0, and T_top < Tf_depressed). Used as the update_T callback of SurfaceFluxes.surface_fluxes, which passes the first eight arguments.

Arguments

• ζ, param_set, thermo_params, inputs, scheme, u_star, z_0m, z_0b: Stability parameter [-], parameter sets, flux inputs, scheme, friction velocity [m/s], and roughness lengths [m], from SurfaceFluxes.
• T_top: Temperature of the top soil cell [K].
• r: Thermal resistance between the skin and the top cell [m² K/W].
• ϵ, σ: Surface emissivity [-] and Stefan-Boltzmann constant [W/m²/K⁴].
• SW_n, LW_d: Net shortwave (positive upward) and downwelling longwave radiation at the surface [W/m²].
• g_liq, β_ice, ψ_sfc, Tf_depressed: Dry-soil-layer vapor conductance [m/s], ice weight of the surface humidity [-], soil water potential [m], and depressed freezing temperature [K] at the surface.
• earth_param_set: Land parameters.

Called from solve_soil_surface_temperature_at_a_point.

update_soil_q_vap_sfc_scheme(ζ, param_set, thermo_params, inputs, scheme, T_sfc, u_star,
                             z_0m, z_0b, g_liq, β_ice, ψ_sfc, Tf_depressed, earth_param_set)

Return the surface specific humidity [kg/kg] of the soil at the skin temperature T_sfc. Used as the update_q callback of SurfaceFluxes.surface_fluxes in the skin temperature solve, which passes the first nine arguments.

Called from solve_soil_surface_temperature_at_a_point.

solve_soil_surface_temperature_at_a_point(return_extra_fluxes, T_top, r, ϵ, SW_n, LW_d,
                                          g_liq, β_ice, ψ_sfc, Tf_depressed, h_sfc, displ,
                                          P_atmos, T_atmos, q_atmos, u_atmos,
                                          roughness_model, atmos_h, gustiness,
                                          update_∂T_sfc∂T, update_∂q_sfc∂T,
                                          earth_param_set)

Solve the soil skin surface energy balance at a point within the Monin-Obukhov iterations of SurfaceFluxes.jl, starting from T_top, and return the skin temperature with the turbulent fluxes at it.

Arguments

• return_extra_fluxes: Val(true) to also return the momentum and buoyancy fluxes, which a coupled atmosphere needs.
• T_top: Temperature of the top soil cell [K].
• r: Thermal resistance between the skin and the top cell [m² K/W].
• ϵ: Surface emissivity [-].
• SW_n, LW_d: Net shortwave (positive upward) and downwelling longwave radiation at the surface [W/m²].
• g_liq: Conductance of the dry soil layer to water vapor [m/s].
• β_ice: Ice fraction weighting the surface humidity when frozen [-].
• ψ_sfc: Soil water potential at the surface [m].
• Tf_depressed: Depressed freezing temperature at the surface [K].
• h_sfc, displ: Surface height and displacement height [m].
• P_atmos, T_atmos, q_atmos, u_atmos: Atmospheric pressure [Pa], temperature [K], specific humidity [kg/kg], and wind (a speed or a horizontal vector) [m/s] at the reference height atmos_h [m].
• roughness_model, gustiness: SurfaceFluxes roughness and gustiness specifications.
• update_∂T_sfc∂T, update_∂q_sfc∂T: Functions for the derivatives of the surface temperature and humidity with respect to the soil temperature, as in turbulent_fluxes!.
• earth_param_set: Land parameters.

Returns

(; lhf, shf, vapor_flux_liq, vapor_flux_ice, T_sfc), with ρτxz, ρτyz, and buoyancy_flux before T_sfc if return_extra_fluxes is Val(true): the latent and sensible heat fluxes [W/m²], the vapor flux [m/s of liquid water] from liquid water or from ice (sublimation at and below the freezing temperature), and the skin temperature in K (see soil_turbulent_fluxes).

Called from update_soil_surface_temperature!.

soil_surface_vapor_conductance!(g_soil_sfc, model::EnergyHydrology, Y, p)

Compute the conductance [m/s] of the dry soil layer to water vapor at the soil surface into g_soil_sfc and return it. The liquid water content is extrapolated to the surface from the top two cells.

Called from update_soil_surface_temperature! and get_update_surface_humidity_function(::EnergyHydrology).

soil_conductance(
    S_l::FT,
    S_c::FT,
    d_ds::FT,
    p::FT,
    α::FT,
    _D_vapor::FT,
    ν::FT,
    θ_r::FT,
    θ_i::FT,
) where {FT}

Computes the conductance of the top of the soil column to water vapor diffusion, as a function of the surface effective liquid water saturation S_l, critical saturation S_c, other soil parameters, and diffusivity of vapor in air.

The conductance is the inverse of the diffusive resistance dsl / (D_vapor τ_a) of the dry soil layer of thickness dsl, with the tortuosity factor τ_a of the dry layer (see soil_tortuosity). When no dry layer has formed (dsl = 0), the resistance vanishes and the conductance is unbounded.

soil_tortuosity(ν::FT, θ_r::FT, θ_i::FT) where {FT}

Compute the tortuosity factor θ_a^2.5 / ν [-] for water vapor diffusion through the dry surface layer of the soil, following Equation (1) of Shokri, Lehmann, and Or (2008), Geophys. Res. Lett., 35, L19407, doi:10.1029/2008GL035230, with porosity ν, residual water fraction θ_r, and ice fraction θ_i.

The vapor diffuses through the air-filled pore space of the dry layer, where the liquid water content is residual, so θ_a = ν - θ_r - θ_i, independent of the moisture of the soil below the dry layer (as in Swenson and Lawrence 2014, J. Geophys. Res. Atmos., 119, 10299–10312, doi:10.1002/2014JD022314, and the Community Land Model).

dry_soil_layer_thickness(S_l::FT, αS_c::FT, d_ds::FT, p::FT)::FT where {FT}

Returns the maximum dry soil layer thickness that can develop under vapor flux; this is used when computing the soil resistance to vapor flux similar to Swenson et al (2012)/Sakaguchi and Zeng (2009).

Note that S_l ∈ (0,1].