Soil hydrology

Overview

Soil hydrology processes characterize the dynamics of ground water in both saturated and unsaturated soil. It defines parameters and methods needed to compute water fluxes between layers and grid cells within the soil domain. Implementations should extend AbstractSoilHydrology and should generally consist of at least four components:

A scheme for computing vertical water fluxes between soil layers
A closure parameterization linking soil saturation and pressure head
A parameterization for soil hydraulic properties
A forcing term representing user-defined, internal sources/sinks in the soil domain (not including evapotranspiration)

Terrarium.AbstractSoilHydrology — Type

abstract type AbstractSoilHydrology{NF} <: Terrarium.AbstractProcess{NF}

Base type for soil hydrology implementations. Subtypes should define state variables for saturation_water_ice, hydraulic_conductivity, liquid_water_fraction, and the current water_table level, along with any other implementation-specific state variables.

subtypes(Terrarium.AbstractSoilHydrology)

1-element Vector{Any}:
 SoilHydrology

Terrarium currently provides a single general implementation of SoilHydrology following the above interface:

Terrarium.SoilHydrology — Type

struct SoilHydrology{NF, VerticalFlow<:Terrarium.AbstractVerticalFlow, SaturationClosure<:Terrarium.AbstractSoilWaterClosure, SoilHydraulics<:(Terrarium.AbstractSoilHydraulics{NF}), VWCForcing<:Union{Nothing, Oceananigans.Forcings.ContinuousForcing{LX, LY, LZ, P} where {P, LX, LY, LZ}, Oceananigans.Forcings.DiscreteForcing}} <: Terrarium.AbstractSoilHydrology{NF}

Properties:

vertflow::Terrarium.AbstractVerticalFlow: Soil water vertical flow operator
closure::Terrarium.AbstractSoilWaterClosure: Closure relation for the soil hydrology state
hydraulic_properties::Terrarium.AbstractSoilHydraulics: Soil hydraulic properties parameterization
vwc_forcing::Union{Nothing, Oceananigans.Forcings.ContinuousForcing{LX, LY, LZ, P} where {P, LX, LY, LZ}, Oceananigans.Forcings.DiscreteForcing}: Forcing for soil moisture (volumetric water content)

Process interface

Dispatches for NoFlow:

Terrarium.initialize! — Method

initialize!(
    state,
    grid,
    hydrology::SoilHydrology,
    soil::Terrarium.AbstractSoil,
    args...
)

Terrarium.compute_auxiliary! — Method

compute_auxiliary!(
    state,
    grid,
    hydrology::SoilHydrology,
    soil::Terrarium.AbstractSoil,
    args...
)

Terrarium.compute_tendencies! — Method

compute_tendencies!(
    state,
    grid,
    hydrology::SoilHydrology,
    soil::Terrarium.AbstractSoil,
    args...
)

Dispatches for RichardsEq:

Terrarium.initialize! — Method

initialize!(
    state,
    grid,
    hydrology::SoilHydrology{NF, RichardsEq, SaturationClosure, SoilHydraulics} where {SaturationClosure<:Terrarium.AbstractSoilWaterClosure, SoilHydraulics<:(Terrarium.AbstractSoilHydraulics{NF})},
    soil::Terrarium.AbstractSoil,
    constants::PhysicalConstants,
    args...
)

Terrarium.compute_auxiliary! — Method

compute_auxiliary!(
    state,
    grid,
    hydrology::SoilHydrology{NF, RichardsEq, SaturationClosure, SoilHydraulics} where {SaturationClosure<:Terrarium.AbstractSoilWaterClosure, SoilHydraulics<:(Terrarium.AbstractSoilHydraulics{NF})},
    soil::Terrarium.AbstractSoil,
    args...
)

Terrarium.compute_tendencies! — Method

compute_tendencies!(
    state,
    grid,
    hydrology::SoilHydrology{NF, RichardsEq, SaturationClosure, SoilHydraulics} where {SaturationClosure<:Terrarium.AbstractSoilWaterClosure, SoilHydraulics<:(Terrarium.AbstractSoilHydraulics{NF})},
    soil::Terrarium.AbstractSoil,
    constants::PhysicalConstants
)
compute_tendencies!(
    state,
    grid,
    hydrology::SoilHydrology{NF, RichardsEq, SaturationClosure, SoilHydraulics} where {SaturationClosure<:Terrarium.AbstractSoilWaterClosure, SoilHydraulics<:(Terrarium.AbstractSoilHydraulics{NF})},
    soil::Terrarium.AbstractSoil,
    constants::PhysicalConstants,
    evtr::Union{Nothing, Terrarium.AbstractEvapotranspiration}
)
compute_tendencies!(
    state,
    grid,
    hydrology::SoilHydrology{NF, RichardsEq, SaturationClosure, SoilHydraulics} where {SaturationClosure<:Terrarium.AbstractSoilWaterClosure, SoilHydraulics<:(Terrarium.AbstractSoilHydraulics{NF})},
    soil::Terrarium.AbstractSoil,
    constants::PhysicalConstants,
    evtr::Union{Nothing, Terrarium.AbstractEvapotranspiration},
    runoff::Union{Nothing, Terrarium.AbstractSurfaceRunoff},
    args...
)

Vertical flow

Static soil hydrology ("No Flow")

The simplest possible soil hydrology scheme is one in which the soil saturation state remains constant over time. This can be appropriate for simulations in regions where the soil is normally waterlogged or where changes in the hydrological state can be otherwise assumed to play a negligible role.

Terrarium.NoFlow — Type

struct NoFlow <: Terrarium.AbstractVerticalFlow

Represents a hydrology scheme where soil water is immobile.

variables(SoilHydrology(Float32, NoFlow()))

Variables
├─ Prognostic: 
├─ Auxiliary: 
├── saturation_water_ice [-] on XYZ{Center, Center, Center}
├── water_table [m] on XY{Center, Center}
├── hydraulic_conductivity [m s^-1] on XYZ{Center, Center, Face}
├─ Inputs: 
├── liquid_water_fraction [-] on XYZ{Center, Center, Center}
├─ Namespaces:

Richardson-Richards equation for variably saturated flow

The vertical flow of water in porous media, such as soils, can be formulated as following the conservation law

\[ \phi\frac{\partial\vartheta(\psi)}{\partial t} - \boldsymbol{\nabla} \cdot \textbf{j}_{\text{w}} - F_{\text{w}}(z,t) = 0,\]

where $\phi$ is the natural porosity (or saturated water content) of the soil volume and $F_{\text{w}}(z,t)$ is an inhomogeneous source/sink (forcing) term (m/s).

Vertical fluxes in the soil column be represented by combining gravity-driven advection with Darcy's law

\[\begin{equation} \textbf{j}_{\text{w}} \cdot \mathbf{n} = -\kappa_{\text{w}}\frac{\partial \left(\psi + z\right)}{\partial z}, \end{equation}\]

where $\psi$ is the matric potential (m). Substituting this equation into the aforementioned conservation law yields the widely known Richardson-Richards equation for variably saturated flow in porous media [1].

Terrarium.RichardsEq — Type

RichardsEq{PS} <: AbstractVerticalFlow

SoilHydrology flow operator implementing the mixed saturation-pressure form of the Richardson-Richards equation.

State variables defined by the Richards' formulation of SoilHydrology:

saturation_water_ice: saturation level of water and ice in the pore space.
surface_excess_water: excess water at the soil surface (m^3/m^2).
hydraulic_conductivity: hydraulic conductivity at cell centers (m/s).
water_table`: elevation of the water table (m).
liquid_water_fraction: fraction of unfrozen liquid water in the pore space (dimensionless).

See also SoilSaturationPressureClosure and AbstractSoilHydraulics for details regarding the closure relating saturation and pressure head.

variables(SoilHydrology(Float32, RichardsEq()))

Variables
├─ Prognostic: 
├── saturation_water_ice [-] on XYZ{Center, Center, Center}
├── surface_excess_water [m] on XY{Center, Center}
├─ Auxiliary: 
├── pressure_head [m] on XYZ{Center, Center, Center}
├── hydraulic_conductivity [m s^-1] on XYZ{Center, Center, Face}
├── water_table [m] on XY{Center, Center}
├─ Inputs: 
├── liquid_water_fraction [-] on XYZ{Center, Center, Center}
├─ Namespaces:

Hydraulic properties

Terrarium.ConstantSoilHydraulics — Type

struct ConstantSoilHydraulics{NF, RC, UnsatK<:Terrarium.AbstractUnsatK{NF}} <: Terrarium.AbstractSoilHydraulics{NF, RC, UnsatK<:Terrarium.AbstractUnsatK{NF}}

Represents a simple case where soil hydraulic properties are given as constant values. This is mostly provided just for testing, although it may be useful in certain cases where direct measurements of hydraulic properites are available.

Properties:

swrc::Any: Soil water retention curve
unsat_hydraulic_cond::Terrarium.AbstractUnsatK: Unsaturated hydraulic conductivity formulation; defaults to sat_hydraulic_cond
sat_hydraulic_cond::Any: Hydraulic conductivity at saturation [m/s]
field_capacity::Any: Prescribed field capacity [-]
wilting_point::Any: Prescribed wilting point [-]

Terrarium.SoilHydraulicsSURFEX — Type

struct SoilHydraulicsSURFEX{NF, RC, UnsatK<:Terrarium.AbstractUnsatK{NF}} <: Terrarium.AbstractSoilHydraulics{NF, RC, UnsatK<:Terrarium.AbstractUnsatK{NF}}

Soil hydraulics parameterization that includes the SURFEX (Masson et al. 2013) formulation of field capacity and wilting point as a function of soil texture.

Properties:

swrc::Any: Soil water retention curve
unsat_hydraulic_cond::Terrarium.AbstractUnsatK: Unsaturated hydraulic conductivity formulation; defaults to sat_hydraulic_cond
sat_hydraulic_cond::Any: Hydraulic conductivity at saturation [m/s]
wilting_point_coef::Any: Linear coeficient of wilting point adjustment due to clay content [-]
field_capacity_coef::Any: Linear coeficient of field capacity adjustment due to clay content [-]
field_capacity_exp::Any: Exponent of field capacity adjustment due to clay content [-]

Closures

Terrarium.SoilSaturationPressureClosure — Type

struct SoilSaturationPressureClosure <: Terrarium.AbstractSoilWaterClosure

Represents a closure relating saturation of water/ice in soil pores to a corresponding pressure (or hydraulic) head. Note that here "pressure head" is defined to be synonymous with hydraulic head, i.e. including all both elevation and hydrostatic pressure contributions. This relation is typically described by soil property-dependent soil-water retention curve (SWRC) which is here defined in implementations of AbstractSoilHydraulics.

Methods

Terrarium.get_hydraulic_properties — Function

get_hydraulic_properties(hydrology::AbstractSoilHydrology)

Return the soil hydraulic properties defined by the given soil hydrology configuration.

Terrarium.get_swrc — Function

get_swrc(::AbstractUnsatK)

Return the soil water retention curve associated with the given unsaturated hydraulic conductivity scheme.

Terrarium.get_closure — Function

get_closure(
    hydrology::SoilHydrology
) -> Terrarium.AbstractSoilWaterClosure

Return the saturation-pressure closure defined by the given hydrology process, or nothing if not defined for the given configuration.

Terrarium.compute_water_table! — Function

compute_water_table!(
    water_table,
    i,
    j,
    grid,
    sat,
    _::SoilHydrology{NF, VerticalFlow, SaturationClosure, SoilHydraulics} where {VerticalFlow<:Terrarium.AbstractVerticalFlow, SaturationClosure<:Terrarium.AbstractSoilWaterClosure, SoilHydraulics<:(Terrarium.AbstractSoilHydraulics{NF})}
)

Kernel function that diagnoses the water table at grid cell i, j given the current soil saturation profile.

Terrarium.adjust_saturation_profile! — Function

adjust_saturation_profile!(
    out,
    i,
    j,
    grid,
    _::SoilHydrology{NF, VerticalFlow, SaturationClosure, SoilHydraulics} where {VerticalFlow<:Terrarium.AbstractVerticalFlow, SaturationClosure<:Terrarium.AbstractSoilWaterClosure, SoilHydraulics<:(Terrarium.AbstractSoilHydraulics{NF})}
)

Kernel function that adjusts saturation profiles to account for oversaturation and undersaturation arising due to numerical error. This implementation scans over the saturation profiles at each lateral grid cell and redistributes excess water upward layer-by-layer until reaching the topmost layer, where any remaining excess water is added to the surface_excess_water pool.

Terrarium.compute_hydraulics! — Function

compute_hydraulics!(state, grid, hydrology::SoilHydrology, soil::AbstractSoil, args...)

Compute all state-dependent hydraulic auxiliaries such as hydraulic conductivity and field capacity, and wilting point.

Kernel functions

Terrarium.saturation_water_ice — Function

saturation_water_ice(i, j, k, grid, fields, ::AbstractSoilHydrology)

Compute or retrieve the current saturation level of water + ice in the pore space.

Terrarium.hydraulic_conductivity — Function

Compute (variably saturated) hydraulic conductivity based on the given hydraulic properties, soil water retention curve (SWRC), and volumetric fractions.

Terrarium.liquid_water_fraction — Function

liquid_water_fraction(i, j, k, grid, fields, ::AbstractSoilHydrology)

Compute or retrieve the current fraction of unfrozen water in the pore space.

Terrarium.water_table — Function

water_table(i, j, k, grid, fields, ::AbstractSoilHydrology)

Compute or retrieve the current water table level relative to the surface.

Terrarium.surface_excess_water — Function

surface_excess_water(i, j, k, grid, fields, ::AbstractSoilHydrology)

Retrieve the current saturation level of water + ice in the pore space.

References

[1]: L. A. Richards. Capillary Conduction of Liquids through Porous Mediums. Physics 1, 318–333 (1931).