GitHub

Soil stratigraphy

Overview

Soil composition and material properties

The subsurface soil column consists of multiple material constituents that determine its physical and chemical properties. These constituents include water and ice occupying the pore space, air filling unsaturated pores, and a solid matrix composed of mineral and organic material. To accurately represent many soil processes in land surface models, it is necessary to characterize both the lateral and vertical distribution of each soil constituent along with its relevant material properties.

The stratigraphy of a soil column defines its vertical layering structure both in terms of texture as well as other properties. Soil texture refers to the relative proportions of sand, silt, and clay in the mineral soil component. Textures are characterized by their particle size distribution, which is a fundamental property affecting hydraulic conductivity, water retention, and thermal properties.

The total void space available in a soil volume controls the maximum amount of water and air that can occupy the pore space. The ratio of void space to the total soil volume is called porosity. Porosity varies depending on soil type, bulk density, and the presence of organic material. Organic soil components typically have higher porosity than mineral soil due to their loose, aggregated structure.

Soil volume composition

An elementary volume $V$ of soil can be represented as the sum of the volume of solid material and void space (soil pores),

\[\begin{equation} V = V_{\text{por}} + V_{\text{solid}} = \overbrace{V_{\text{liq}} + V_{\text{ice}} + V_{\text{air}}}^{\text{pore constituents}} + \overbrace{V_{\text{min}} + V_{\text{org}}}^{\text{solid constituents}}\,. \end{equation}\]

\[V_{\text{liq}}\]

and $V_{\text{ice}}$ correspond to the liquid and ice phases of water and ice stored in the pore space while $V_{\text{air}}$ is residual air in unsaturated conditions; $V_{\text{min}}$ and $V_{\text{org}}$ are the mineral and organic solid constituents respectively. Note that the air is here assumed to be a constant mixture of gases and thus changes in the gas phase of water are neglected.

For many physical calculations depending on soil composition, it is more convenient to work directly with volume-invariant (intensive) quantities such as volumetric (m³/m³) or characteristic fractions such as porosity $\phi = \frac{V_{\text{por}}}{V}$, saturation of pore water/ice $\xi = \frac{V_{\text{liq}} + V_{\text{ice}}}{V_{\text{por}}}$, liquid water fraction $\ell = \frac{V_{\text{liq}}}{V_{\text{liq}} + V_{\text{ice}}}$, and the organic fraction of solid material $\omega = \frac{V_{\text{org}}}{V_{\text{solid}}}$. In permafrost environments, an additional characteristic fraction for excess or segregated ground ice is sometimes included. This is, however, currently neglected in Terrarium.

Soil characteristic fractions

The total volumetric fractions of each component can then be trivially derived from the characteristic fractions:

\[\begin{align*} \theta_{\text{liq}} &= \ell \xi \phi\,,\\ \theta_{\text{ice}} &= (1 - \ell) \xi \phi \,,\\ \theta_{\text{air}} &= (1 - \xi) \phi\,,\\ \theta_{\text{org}} &= \omega (1 - \phi) \,,\\ \theta_{\text{min}} &= (1 - \omega) (1 - \phi)\,,\\ 1 &= \theta_{\text{liq}} + \theta_{\text{ice}} + \theta_{\text{air}} + \theta_{\text{org}} + \theta_{\text{min}} \end{align*}.\]

The total water/ice content is defined is $\theta = \theta_{\text{liq}} + \theta_{\text{ice}}$

Horizons and namespaced inputs

A SoilStratigraphy is built from a stack of soil horizons, ordered from the top of the vertical column downwards. Each horizon is assumed to be internally homogeneous and carries its own texture and porosity parameterization as well as a thickness. Terrarium currently provides two horizon types:

  • ConstantSoilHorizon, whose texture and porosity are fixed parameters (spatially and temporally invariant), and
  • PrescribedSoilHorizon, whose texture and thickness are supplied as spatially varying input Fields.

The depth range occupied by each horizon is determined by its thickness, and the bottommost horizon always extends to the base of the column regardless of its nominal thickness. The horizon containing a given soil volume is resolved per grid cell at runtime, so that horizon properties may vary laterally when prescribed from data.

Each horizon declares its variables inside a Namespace named after the horizon. In particular, every PrescribedSoilHorizon declares sand_fraction, silt_fraction, clay_fraction, and thickness input variables, which are matched to InputSources via namespaced names (e.g. :horizon1 => :sand_fraction). See Namespaced input variables for details.

Stratigraphy types

Terrarium.SoilStratigraphy — Type
struct SoilStratigraphy{NF, N, Horizons<:NTuple{N, Terrarium.AbstractSoilHorizon{NF}}} <: Terrarium.AbstractStratigraphy{NF}

Represents a soil stratigraphy as a stack of named soil horizons. Each soil horizon is assumed to have internally homogeneous soil properties. The number of horizons and their respective names are defined by the user.

Properties:

  • horizons::NTuple{N, Terrarium.AbstractSoilHorizon{NF}} where {NF, N}: Named tuple of soil horizons ordered from top to bottom
source

For common configurations, two convenience constructors are provided:

Terrarium.HomogeneousSoilStratigraphy — Function
HomogeneousSoilStratigraphy(
    ::Type{NF};
    texture,
    porosity
) -> SoilStratigraphy{NF, 1, Horizons} where {NF, Horizons<:Tuple{ConstantSoilHorizon{NF, _B, ConstantSoilPorosity{NF}} where _B}}

Convenience constructor that creates a SoilStratigraphy with a single ConstantSoilHorizon.

source
Terrarium.SoilGridsStratigraphy — Function
SoilGridsStratigraphy(
    ::Type{NF};
    porosity,
    horizon1,
    horizon2,
    horizon3,
    horizon4,
    horizon5,
    horizon6
) -> SoilStratigraphy{NF, 6, _B} where {NF, _B<:NTuple{6, Terrarium.AbstractSoilHorizon{NF}}}

Convenience constructor that creates a SoilStratigraphy with six horizons corresponding to the six depth intervals defined by the SoilGridsV2 dataset. The porosity parameterization is applied to all six default horizons; pass explicit horizon* arguments to override individual horizons (in which case porosity does not apply to those).

source

Soil horizons

Terrarium.ConstantSoilHorizon — Type
struct ConstantSoilHorizon{NF, name, Porosity<:Terrarium.AbstractSoilPorosity{NF}} <: Terrarium.AbstractSoilHorizon{NF, name}

Represents an arbitrary soil horizon whose properties (texture and porosity) are assumed to be constant across both space and time.

source
Terrarium.PrescribedSoilHorizon — Type
struct PrescribedSoilHorizon{NF, name, Porosity<:Terrarium.AbstractSoilPorosity{NF}} <: Terrarium.AbstractSoilHorizon{NF, name}

Represents an arbitrary soil horizon whose properties (texture and porosity) are prescribed via input Fields and can therefore vary across space and (less commonly) time.

source

Soil texture

Soil porosity

Terrarium.ConstantSoilPorosity — Type
struct ConstantSoilPorosity{NF} <: Terrarium.AbstractSoilPorosity{NF}

Parameterization of soil porosity that simply specifies constant values for the mineral and organic components.

source
Terrarium.SoilPorositySURFEX — Type
struct SoilPorositySURFEX{NF} <: Terrarium.AbstractSoilPorosity{NF}

SURFEX parameterization of mineral soil porosity [4, Eq. (27)].

References

  • [4] Noilhan & Mahfouf, Global and Planetary Change (1996)
source

Soil volume

Terrarium.SoilComposition — Type
struct SoilComposition{NF, Solid<:Terrarium.AbstractSoilMatrix{NF}}

Represents the material composition of an elementary volume of soil. The volume is decomposed into the key constitutents of water, ice, air, and a mixture of organic and mineral solid material.

Properties:

  • porosity: Natural porosity or void space of the soil

  • saturation: Fraction of the soil pores occupied by water or ice

  • liquid: Liquid (unfrozen) fraction of pore water

  • solid: Parameterization of the solid phase (matrix) of the soil

source

Solid matrix

Terrarium.MineralOrganic — Type
struct MineralOrganic{NF} <: Terrarium.AbstractSoilMatrix{NF}

Soil matrix consisting of a simple, homogeneous mixture of mineral and organic material.

Properties:

  • texture::SoilTexture: Mineral soil texture

  • organic::Any: Organic soil fraction

source

Kernel functions

Terrarium.soil_texture — Function
soil_texture(i, j, grid, fields, ::AbstractSoilHorizon, args...)
soil_texture(i, j, k, grid, fields, ::AbstractStratigraphy, args...)

Return the texture of the soil at index i, j, k for the given stratigraphy parameterization.

source
Terrarium.soil_matrix — Function
soil_matrix(i, j, grid, fields, ::AbstractSoilHorizon, args...)
soil_matrix(i, j, k, grid, fields, ::AbstractStratigraphy, args...)

Return the solid matrix of the soil at index i, j, k for the given stratigraphy parameterization.

source
Terrarium.soil_volume — Function
soil_volume(i, j, k, grid, fields, ::AbstractStratigraphy, args...)

Return a SoilComposition describing the full material composition of the soil volume at index i, j, k for the given stratigraphy parameterization.

source
Terrarium.mineral_porosity — Function
mineral_porosity(::AbstractSoilPorosity, texture::SoilTexture)

Compute or retrieve the natural porosity of the mineral soil constitutents, i.e. excluding organic material.

source
Terrarium.organic_porosity — Function
organic_porosity(::AbstractSoilPorosity, texture::SoilTexture)

Compute or retrieve the natural porosity of the organic soil constitutents, i.e. excluding mineral material.

source
Terrarium.volumetric_fractions — Function
volumetric_fractions(soil::SoilComposition) -> NamedTuple

Calculates the volumetric fractions of all constituents in the given soil volume and returns them as a named tuple of the form (; water, ice, air, solids...), where solids corresponds to the volumetric fractions defined by the solid phase soil.solid.

source
volumetric_fractions(
    solid::MineralOrganic{NF},
    solid_frac
) -> NamedTuple{(:organic, :mineral), <:Tuple{Any, Any}}

Compute the volumetric fractions of the solid phase scaled by the overall solid fraction of the soil solid_frac.

source
Terrarium.porosity — Function
porosity(horizon::Terrarium.AbstractSoilHorizon) -> Any

Return the porosity parameterization for the given soil horizon.

source
porosity(
    i,
    j,
    k,
    grid,
    fields,
    strat::SoilStratigraphy,
    bgc::Terrarium.AbstractSoilBiogeochemistry
) -> Any

Compute the porosity of the soil volume at the given indices.

source