Soil Sources and Boundary Conditions

AbstractRunoffModel

The soil runoff models are only to be used with the following boundary condition types:

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

It must have methods for

• subsurface_runoff_source (defined in this module)
• update_infiltration_water_flux! (defined in this module)
• ClimaLand.source!.

Please see the documentation for these for more details.

Your runoff model must specify the subsurface runoff sink term as well as the surface runoff implementation.

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

This is currently treated implicitly (evaluated at the next value of ϑ_l) but not included in the Jacobian approximation. This is because update_infiltration_water_flux is called as part of the implicit tendency.

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

• explicit: Explicit vs implicit stepping

subsurface_runoff_source(runoff::AbstractRunoffModel)

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

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

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

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

)

The updateinfiltrationwater_flux! 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_infiltration_water_flux!(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.

This is not tied to any boundary condition for the heat equation. To account for the energy flux resulting from free drainage of liquid water, please see EnergyWaterFreeDrainage.

EnergyWaterFreeDrainage <: AbstractEnergyHydrologyBC

A concrete type of soil boundary condition, for use at the BottomBoundary only, where the fluxes are set to be F_liq = -K∇h = -K, F_energy = -K ρe_liq.

That is, this enforces that the free drainage boundary condition for liquid water is paired the the corresponding loss of energy that that entails.

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,
    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,
    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, indicated by the value of prognostic_land_components.

soil_boundary_fluxes!(
    bc::AtmosDrivenFluxBC{<:PrescribedAtmosphere, <:PrescribedRadiativeFluxes},
    prognostic_land_components::Val{(:canopy, :soil,:soilco2,)},
    soil::EnergyHydrology,
    Y,
    p,
    t,
)

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,
    Y,
    p,
    t,
)

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