Soil models

Overview

SoilModel is a model of soil physics that couples the relevant processes governing energy, water, and carbon in natural soils. It is the primary model type for simulating heat conduction, freeze-thaw processes (e.g. permafrost), and variably saturated water flow in the subsurface.

arch = CPU()
grid = ColumnGrid(arch, Float32, ExponentialSpacing(N = 10)) # 10 soil layers
model = SoilModel(grid)
integrator = initialize(model, ForwardEuler(eltype(grid)))

Integrator of SoilModel{Float32, ColumnGrid{Float32, CPU, Oceananigans.Grids.RectilinearGrid{Float32, Oceananigans.Grids.Periodic, Oceananigans.Grids.Flat, Oceananigans.Grids.Bounded, Oceananigans.Grids.StaticVerticalDiscretization{OffsetArrays.OffsetVector{Float32, Vector{Float32}}, OffsetArrays.OffsetVector{Float32, Vector{Float32}}, OffsetArrays.OffsetVector{Float32, Vector{Float32}}, OffsetArrays.OffsetVector{Float32, Vector{Float32}}}, Float32, Float32, OffsetArrays.OffsetVector{Float32, StepRangeLen{Float32, Float64, Float64, Int64}}, Nothing, CPU}}, SoilEnergyWaterCarbon{Float32, HomogeneousStratigraphy{Float32, ConstantSoilPorosity{Float32}}, SoilEnergyBalance{Float32, Terrarium.ExplicitTwoPhaseHeatConduction, SoilEnergyTemperatureClosure, SoilThermalProperties{Float32, FreeWater, InverseQuadratic}}, SoilHydrology{Float32, NoFlow, SoilSaturationPressureClosure, SoilHydraulicsSURFEX{Float32, BrooksCorey{FreezeCurves.SoilWaterVolume{Float32, Float32, Float32}, Float32, Float32}, UnsatKLinear{Float32}}, Nothing}, ConstantSoilCarbonDensity{Float32}}, DefaultInitializer{Float32}} with ForwardEuler{Float32}
├── Current time: 0.0
├── StateVariables{Float32}(clock = Clock{Float32, Float64}(time=0 seconds, iteration=0, last_Δt=Inf days), prognostic = (:internal_energy,), auxiliary = (:temperature, :liquid_water_fraction, :ground_temperature, :saturation_water_ice, :water_table, :hydraulic_conductivity), inputs = (), namespaces = (), timestepper_cache = ())

struct SoilModel{NF, GridType<:(Terrarium.AbstractLandGrid{NF}), Soil<:Terrarium.AbstractSoil{NF}, Initializer<:Terrarium.AbstractInitializer} <: Terrarium.AbstractSoilModel{NF, GridType<:(Terrarium.AbstractLandGrid{NF})}

variables(model)

Variables
├─ Prognostic: 
├── internal_energy [J m^-3] on XYZ{Center, Center, Center}
├─ Auxiliary: 
├── temperature [°C] on XYZ{Center, Center, Center}
├── liquid_water_fraction [-] on XYZ{Center, Center, Center}
├── ground_temperature [°C] on XY{Center, Center}
├── 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: 
├─ Namespaces:

Components

Each component is summarized briefly below. Follow the linked process pages for full theoretical background, available concrete types, state variables, and method signatures.

Stratigraphy

The strat component parameterizes the vertical distribution of soil material properties (texture, porosity, organic content). It provides kernel functions used by the energy and hydrology sub-processes to look up spatially varying material properties at each grid cell. By default HomogeneousStratigraphy is used, which assumes a single uniform material throughout the profile. See Soil stratigraphy for details.

Energy balance

The energy component represents heat conduction in the soil column, including the latent heat of freeze-thaw phase change. The default implementation is SoilEnergyBalance, which evolves the volumetric internal energy $U$ (J m⁻³) as the prognostic variable and derives temperature via the SoilEnergyTemperatureClosure. See Soil energy balance for details.

Hydrology

The hydrology component governs the vertical movement of water in the soil column. The default implementation is SoilHydrology, which evolves total saturation (liquid + ice) as the prognostic variable. Vertical flow is disabled by default (NoFlow); enabling the Richards equation requires selecting RichardsEq as the vertical_flow operator. See Soil hydrology for details.

Biogeochemistry

The biogeochem component simulates the spatial distribution of soil organic carbon and associated biogeochemical fluxes. The default implementation is ConstantSoilCarbonDensity, which prescribes a spatially homogeneous organic carbon density and does not define any prognostic variables.

Initializers

Terrarium provides a hierarchy of initializers for SoilModel. The top-level initializer is SoilInitializer, which composes separate sub-initializers for energy, hydrology, and biogeochemistry. It is the recommended initializer for most use cases:

struct SoilInitializer{NF, EnergyInit<:Terrarium.AbstractInitializer{NF}, HydrologyInit<:Terrarium.AbstractInitializer{NF}, BGCInit<:Terrarium.AbstractInitializer{NF}} <: Terrarium.AbstractInitializer{NF}

Passing a SoilInitializer to SoilModel overrides the DefaultInitializer:

initializer = SoilInitializer(Float32;
    energy    = QuasiThermalSteadyState(Float32; T₀ = 2.0f0),
    hydrology = SaturationWaterTable(Float32; water_table_depth = 3.0f0),
)
model = SoilModel(grid; initializer)

SoilModel{Float32} on CPU()
├── grid:  ColumnGrid{Float32, CPU} with dimensions (1, 1, 10)
├── soil:  SoilEnergyWaterCarbon{Float32, HomogeneousStratigraphy{Float32, ConstantSoilPorosity{Float32}}, SoilEnergyBalance{Float32, Terrarium.ExplicitTwoPhaseHeatConduction, SoilEnergyTemperatureClosure, SoilThermalProperties{Float32, FreeWater, InverseQuadratic}}, SoilHydrology{Float32, NoFlow, SoilSaturationPressureClosure, SoilHydraulicsSURFEX{Float32, BrooksCorey{FreezeCurves.SoilWaterVolume{Float32, Float32, Float32}, Float32, Float32}, UnsatKLinear{Float32}}, Nothing}, ConstantSoilCarbonDensity{Float32}}
├── constants:  PhysicalConstants{Float32}
├── initializer:  SoilInitializer{Float32, QuasiThermalSteadyState{Float32}, SaturationWaterTable{Float32}, DefaultInitializer{Float32}}

Energy initializers

struct ConstantSoilTemperature{NF} <: Terrarium.AbstractInitializer{NF}

struct QuasiThermalSteadyState{NF} <: Terrarium.AbstractInitializer{NF}

struct PiecewiseLinearInitialSoilTemperature{NF, N}

initializer = PiecewiseLinearInitialSoilTemperature(
    0.0u"m" => 5.0, # always in °C!
    0.5u"m" => 2.0,
    1.0u"m" => 1.0,
    10.0u"m" => 1.5,
    ...
)

Hydrology initializers

struct SaturationWaterTable{NF} <: Terrarium.AbstractInitializer{NF}

Fallback

Boundary conditions

Terrarium provides a set of named boundary condition aliases for the most common SoilModel configurations. These return NamedTuples in the format expected by the boundary_conditions keyword argument of initialize.

Energy boundary conditions

Hydrology boundary conditions