API Reference

Convenience constructor for all AbstractModel types that allows the grid to be passed as the first positional argument.

Field(
    grid::AbstractLandGrid,
    dims::VarDims,
    boundary_conditions = nothing,
    args...;
    kwargs...
)

Auxiliary constructor for an Oceananigans Field on grid with the given Terrarium variable dims and boundary conditions. Additional arguments are passed direclty to the Field constructor. The location of the Field is determined by VarDims defined on var.

FieldTimeSeries(
    grid::AbstractLandGrid,
    dims::VarDims,
    times=eltype(grid)[]
)

Construct a FieldTimeSeries on the given land grid with the given dims and times.

Field(field, grid; fill_value)

Converts the given Oceananigans Field to a RingGrids.Field with a ring grid matching that of the given ColumnRingGrid.

Base type for surface albedo and emissivity parameterizations.

abstract type AbstractAtmosphere{NF, PR<:Terrarium.AbstractPrecipitation, IR<:Terrarium.AbstractIncomingRadiation, HM<:Terrarium.AbstractHumidity, AD<:Terrarium.AbstractAerodynamics{NF}} <: Terrarium.AbstractProcess{NF}

Base type for representations of the atmosphere that provide meterological state variables such as air temperature and pressure, humidity, precipitation, incoming solar radiation, tracer gas concentrations, wind speed, and near-surface aerodynamics.

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

Base type for autotrophic respiration schemes.

Base type for bulk weighting/mixing schemes that calculate weighted mixture of material properties such as conductivities or densities.

Base type for canopy interception process implementations.

abstract type AbstractClosureRelation

Base type for prognostic variable closure relations for differential equations of the form:

\[\frac{\partial g(u)}{\partial t} = F(u)\]

where F represents the RHS tendency as a function of the state variable u, and g(u) is a closure or constitutive relation that maps u to the physical units matching the tendency. Common examples in soil hydrothermal modeling are temperature-enthalpy and saturation-pressure relations.

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

Base type for AbstractProces implementations that define a coupling interface for (typically two or more) sub-processes.

Base type for evapotranspiration processes.

abstract type AbstractGround{NF} <: Terrarium.AbstractCoupledProcesses{NF}

Base type for coupled ground processes.

Base type for evaporation resistance parameterizations.

abstract type AbstractGroundModel{NF, GR} <: Terrarium.AbstractModel{NF, GR}

Base type for ground (e.g. soil and rock) models.

abstract type AbstractHeatOperator

Base type for formulations of the heat transfer operator.

abstract type AbstractHydrologyModel{NF, GR} <: Terrarium.AbstractModel{NF, GR}

Base type for surface hydrology models.

Base type for model initializers. Implementations should provide a dispatch of the initialize!(state, model::M, init::I) method where M corresponds to the model type and I to the initializer. An implementation of get_field_initializers can also be provided which returns a NamedTuple of initializer functions for individual state variable fields.

AbstractLandModel <: AbstractModel

Base type for full land models which couple together multiple component models.

abstract type AbstractModel{NF, Grid<:(Terrarium.AbstractLandGrid{NF})}

Base type for all Terrarium "models". Models are standalone representations of a system that consist of

(i) a spatial grid characterizing the model domain, (ii) zero or more AbstractProcesses defining the dynamics, and (iii) an AbstractInitializer responsible for defining the initial state of the model.

Implementations of AbstractModel are required to implement, at minimum, three methods:

• variables which declares the state variables requried by the model,
• compute_auxiliary! which is responsible for computing all auxiliary (non-prognostic) variables,
• compute_tendencies! which is responsible for computing the tendencies of all prognostic variables.

Note that a default implementation of variables is provided which automatically collects all variables declared by AbstractProcesses defined as fields (properties) of structs that subtype AbstractModel.

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

Base type for vegetation phenology schemes.

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

Base type for photosyntheis schemes.

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

Base type for processes that comptue the plant available water fraction in each soil layer.

abstract type AbstractProcess{NF}

Base type for all "processes". Implementations of AbstractProcess define equations, state variables, and parameterizations which characterize the dynamics of a system at for any given transient state. Note that processes should be largely agnostic to the details regarding spatial and temporal discretization of the model; i.e. they should not require specification of a specific grid or time stepping scheme but rather should be able to operate on any given set of Fields and parameters representing the state of a model at any point in time. Note that process types may also wrap/orchestrate one or more other process types.

Baste type for process state variables with specific intents, e.g. prognostic, auxiliary, or input.

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

Base type for radiative flux parameterizations.

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

Base type for vegetation root distribution schemes.

Base type for skin temperature and ground heat flux schemes.

abstract type AbstractSnowModel{NF, GR} <: Terrarium.AbstractModel{NF, GR}

Base type for snow models.

abstract type AbstractSoil{NF} <: Terrarium.AbstractGround{NF}

Base type for coupled soil processes.

abstract type AbstractSoilEnergyClosure <: Terrarium.AbstractClosureRelation

Base type for closure relations between energy and temperature in soil volumes.

abstract type AbstractSoilHydraulics{NF, RC<:SWRC, UnsatK<:Terrarium.AbstractUnsatK}

Base type for soil hydraulic properties and parameterization schemes.

abstract type AbstractSoilModel{NF, GR} <: Terrarium.AbstractGroundModel{NF, GR}

Base type for soil ground models.

abstract type AbstractSoilPorosity{NF}

Base type for parameterizations of soil porosity.

abstract type AbstractSoilTexture{NF}

Base type for mineral soil texture parameterizations.

abstract type AbstractSoilWaterClosure <: Terrarium.AbstractClosureRelation

Base type for closure relations between water saturation and potential in soil volumes.

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

Base type for stomatal conductance schemes.

abstract type AbstractStratigraphy{NF}

Base type for soil stratigraphy parameterizations.

Base type for surface energy balance schemes which couple together the relevant processes for radiative and turbulent surface energy fluxes.

abstract type AbstractSurfaceEnergyModel{NF, GR} <: Terrarium.AbstractModel{NF, GR}

Base type for land-atmosphere energy exchange models.

Base type for coupled surface hydrology processes.

Base type for surface runoff processes.

Base type for time steppers.

Base type for time-stepper state caches.

Base type for turbulent (latent and sensible) heat flux parameterizations.

abstract type AbstractUnsatK{NF}

Base type for unsaturated hydraulic conductivity parameterizations.

Base type for state variable placeholder types.

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

Base type for vegetation carbon dynamics schemes.

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

Base type for vegetation dynamics schemes.

abstract type AbstractVegetationModel{NF, GR} <: Terrarium.AbstractModel{NF, GR}

Base type for vegetation models.

Base type for implementations of soil water flow dynamics.

abstract type AbstractVerticalSpacing{NF}

Base type for vertical discretizations.

Type alias for an AbstractField with any X, Y, Z location or grid.

Type alias for a FieldTimeSeries with any X, Y, Z location or grid.

struct AuxiliaryVariable{name, VD<:Terrarium.VarDims, UT<:Unitful.Units, Var<:Terrarium.Variable{name, VD<:Terrarium.VarDims, UT<:Unitful.Units}, DT<:IntervalSets.AbstractInterval, FC<:Union{Nothing, Function}} <: Terrarium.AbstractProcessVariable{name, VD<:Terrarium.VarDims, UT<:Unitful.Units}

Represents an auxiliary (a.k.a "diagnostic") state variable with the given name and spatial dims. Auxiliary variables are those which are diagnosed directly or indirectly from the values of one or more prognostic variables.

Alias for Oceananigans AbstractBoundaryConditionClassification.

ColumnGrid{NF, Arch<:AbstractArchitecture, RectGrid<:Oceananigans.Grids.RectilinearGrid} <: AbstractLandGrid

Represents a set of laterally independent vertical columns with dimensions (x, y, z) where x is the column dimension, y=1 is constant, and z is the vertical axis.

struct ColumnRingGrid{NF, Arch, RingGrid<:RingGrids.AbstractGrid, RectGrid<:Oceananigans.Grids.RectilinearGrid, Mask<:AbstractArray} <: Terrarium.AbstractColumnGrid{NF, Arch}

Represents a global (spherical) grid of independent, vertical columns where the spatial discretization in the horizontal direction is defined by a RingGrids.AbstractGrid.

struct ConstantAerodynamics{NF} <: Terrarium.AbstractAerodynamics{NF}

Dummy implementation of aerodynamics that simply returns constant values for all drag coefficients.

struct ConstantAlbedo{NF} <: Terrarium.AbstractAlbedo{NF}

Properties:

• albedo::Any: Surface albedo, i.e. ratio of outgoing to incoming shortwave radiation [-]

• emissivity::Any: Surface emissivity, i.e. fraction of thermal radiation emitted from the surface [-]

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

Initializer for soil/ground temperature that sets the temperature profile to a constant value.

Properties:

• T₀::Any

Creates a constant soil temperature initializer.

struct ConstantSoilCarbonDensity{NF} <: Terrarium.AbstractSoilBiogeochemistry{NF}

Naive implementation of soil biogeochemistry that just assumes there to be a constant organic content in all soil layers.

Properties:

• ρ_soc::Any: Soil organic carbon density [kg/m^3]

• ρ_org::Any: Pure organic matter density [kg/m^3]

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 [-]

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

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

Marker type for a no-op initializer that leaves all Fields set to their default values.

struct DiagnosedRadiativeFluxes{NF} <: Terrarium.AbstractRadiativeFluxes{NF}

Computes outgoing shortwave and longwave radiation according to separately specified schemes for the albedo, skin temperature, and atmospheric inputs.

struct DiagnosedTurbulentFluxes{NF} <: Terrarium.AbstractTurbulentFluxes{NF}

Represents the standard case where the turbulent (sensible and latent) heat fluxes are diagnosed from atmosphere and soil conditions.

struct DirectSurfaceRunoff{NF} <: Terrarium.AbstractSurfaceRunoff{NF}

Simple surface runoff scheme that computes runoff as

\[R = P + D - I\]

where P is precipitation reaching the ground, D is drainage from accumualted excess water at the surface, and I is infiltration into the soil.

Properties:

• τ_r: Surface water removal timescale

struct ExplicitTwoPhaseHeatConduction <: Terrarium.AbstractHeatOperator

Represents an explicit formulation of the two-phase heat conduction operator in 1D:

\[\frac{\partial U(T,\phi)}{\partial t} = \nabla \cdot \kappa(T)\nabla_x T(x,t)\]

where $T$ is temperature [K], $U$ is internal energy [J m⁻³], and $\kappa$ is the thermal conductivity [W m K⁻¹].

struct ExponentialSpacing{NF, ST<:Union{Nothing, Integer}} <: Terrarium.AbstractVerticalSpacing{NF}

Variably-spaced vertical discretization with N layers increasing quasi-exponentially in thickness from Δz_min at the top (surface) to Δz_max at the bottom. The integer property sig determines to what significant digit each layer thickness should be rounded.

Properties:

• Δz_min::Any: Minimum layer thickness at the surface

• Δz_max::Any: Maximum layer thickness at the bottom

• N::Int64: Number of layers

• sig::Union{Nothing, Integer}: Number of significant digits for rounding or nothing

Alias for a NamedTuple of FieldBC types where the keys correspond to field/variable names.

struct FieldCapacityLimitedPAW{NF} <: Terrarium.AbstractPlantAvailableWater{NF}

Implementation of vegetation water availability (a.k.a "plant available water") that computes the wilting fraction

\[W_i = \min(\frac{\theta_{\text{w},i} - \theta_{\text{wp},i}}{\theta_{\text{fc},i} - \theta_{\text{wp},i}}}, 1)\]

where $\theta_{\text{w},i}$ is the volumetric water content of the i'th soil layer, $\theta_{\text{fc},i}$ is the "field capacity", and $\theta_{\text{wp},i}$ is the "wilting point". The water availability

Properties:

struct FieldInputSource{NF, VD<:Terrarium.VarDims, names} <: InputSource{NF}

Input source that defines input state variables with the given names which can then be directly modified by the user.

struct FieldTimeSeriesInputSource{NF, VD<:Terrarium.VarDims, names, FTS<:Tuple{Vararg{FieldTimeSeries{LX, LY, LZ, TI, K, I, D, G, NF} where {LX, LY, LZ, TI, K, I, D, G}}}} <: InputSource{NF}

Input source that reads input fields from pre-specified Oceananigans FieldTimeSeries.

struct ForwardEuler{NF} <: Terrarium.AbstractTimeStepper{NF}

Simple forward Euler time stepping scheme.

GroundEvaporation{NF, GR} <: AbstractEvapotranspiration

Evaporation scheme for bare ground that calculates the humidity flux as

\[E = \beta \frac{\Delta q}{r_a}\]

where Δq is the vapor pressure deficit in terms of specific humidity, rₐ is aerodynamic resistance, and β is an evaporation limiting factor.

struct Heun{NF, Stage} <: Terrarium.AbstractTimeStepper{NF}

Simple forward 2nd order Heun / improved Euler time stepping scheme.

struct HomogeneousStratigraphy{NF, SoilPorosity<:Terrarium.AbstractSoilPorosity{NF}} <: Terrarium.AbstractStratigraphy{NF}

Represents a soil stratigraphy of well mixed material with homogeneous soil texture.

Properties:

• texture::SoilTexture: Material composition of mineral soil component

• porosity::Terrarium.AbstractSoilPorosity: Parameterization of soil porosity

struct ImplicitSkinTemperature{NF} <: Terrarium.AbstractSkinTemperature{NF}

Scheme for an implicit skin temperature $T_0$ satisfying:

\[R_{\text{net}}(T_0) = H_s(T_0) + H_l(T_0) + G(T_0, T_1)\]

where $R_{\text{net}}$ is the net radiation budget, $H_s$ is the sensible heat flux, $H_l$ is the latent heat flux from sublimation and evapotranspiration, $G$ is the ground heat flux, and $T_1$ is the ground temperature, or temperature of the uppermost subsurface (soil or snow) layer.

Properties:

• κₛ: Assumed thermal conductivity at the surface [W m⁻¹ K⁻¹]

abstract type InputSource{NF}

Base type for input data sources. Implementations of InputSource are free to load data from any arbitrary backend but are required to implement the update_inputs!(fields, ::InputSource, ::Clock) method. Implementations should additionally provide a constructor as a dispatch of InputSource.

The type argument NF corresponds to the numeric type of the input data.

InputSource(::Type{NF}, names::Symbol...; dims = XY())

Create a FieldInputSource with the given numeric type and input variable names.

Container type for wrapping multiple InputSources.

struct InputVariable{name, VD<:Terrarium.VarDims, UT<:Unitful.Units, Var<:Terrarium.Variable{name, VD<:Terrarium.VarDims, UT<:Unitful.Units}, DT<:IntervalSets.AbstractInterval, Def<:Union{Nothing, Function, Number}} <: Terrarium.AbstractProcessVariable{name, VD<:Terrarium.VarDims, UT<:Unitful.Units}

Represents an input (e.g. forcing) variable with the given name and spatial dims.

The inverse quadratic (or "quadratic parallel") bulk thermal conductivity formula (Cosenza et al. 2003):

\[k = [\sum_{i=1}^N θᵢ\sqrt{kᵢ}]^2\]

Cosenza, P., Guérin, R., and Tabbagh, A.: Relationship between thermal conductivity and water content of soils using numerical modelling, European Journal of Soil Science, 54, 581–588, https://doi.org/10.1046/j.1365-2389.2003.00539.x, 2003.

struct LUEPhotosynthesis{NF} <: Terrarium.AbstractPhotosynthesis{NF}

Photosynthesis implementation from PALADYN (Willeit 2016) for C3 PFTs following the general light use efficiency model described in Haxeltine and Prentice 1996.

Authors: Maha Badri and Matteo Willeit

Properties:

• τ25::Any: Value of τ at 25°C

• Kc25::Any: Value of Kc at 25°C

• Ko25::Any: Value of Ko at 25°C

• q10_τ::Any: q10 for temperature-sensitive parameter τ

• q10_Kc::Any: q10 for temperature-sensitive parameter Kc

• q10_Ko::Any: q10 for temperature-sensitive parameter Ko

• α_leaf::Any: Leaf albedo in PAR range [-]

• cq::Any: Conversion factor for solar radiation at 550 nm from J/m² to mol/m² [mol/J]

• k_ext::Any: Extinction coefficient for radiation through vegetation [-]

• α_a::Any: Fraction of PAR assimilated at ecosystem level, relative to leaf level [-]

• t_CO2_high::Any: Parameter, PFT specific [°C]

• t_CO2_low::Any: Parameter, PFT specific [°C]

• t_photos_high::Any: Parameter, PFT specific [°C]

• t_photos_low::Any: Parameter, PFT specific [°C]

• α_C3::Any: Intrinsic quantum efficiency of CO2 uptake in C3 plants [mol/mol]

• C_mass::Any: Atomic mass of carbon [gC/mol]

• θ_r::Any: Shape parameter [-]

Alias for numeric Quantity with type NF and units U.

struct MedlynStomatalConductance{NF} <: Terrarium.AbstractStomatalConductance{NF}

Stomatal conductance implementation from PALADYN (Willeit 2016) following the optimal stomatal conductance model (Medlyn et al. 2011).

Authors: Maha Badri and Matteo Willeit

Properties:

• g₁::Any: Parameter in optimal stomatal conductance formulation representing the quasi-linear relationship between conductance and net assimilation, Lin et al. 2015 [-], PFT specific

• g_min::Any: Minimum stomatal condutance parameter [mm s⁻¹]

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

Alias for SoilVolume{T, MineralOrganic{T}}

struct ModelIntegrator{NF, Arch<:Oceananigans.Architectures.AbstractArchitecture, Grid<:Terrarium.AbstractLandGrid{NF, Arch<:Oceananigans.Architectures.AbstractArchitecture}, TimeStepper<:Terrarium.AbstractTimeStepper{NF}, Model<:Terrarium.AbstractModel{NF, Grid<:Terrarium.AbstractLandGrid{NF, Arch<:Oceananigans.Architectures.AbstractArchitecture}}, StateVars<:Terrarium.AbstractStateVariables, Inits<:NamedTuple, Inputs<:InputSources} <: Oceananigans.AbstractModel{TimeStepper<:Terrarium.AbstractTimeStepper{NF}, Arch<:Oceananigans.Architectures.AbstractArchitecture}

Represents a "integrator" for a simulation of a given model. ModelIntegrator consists of a clock, a model, and an initialized StateVariables data structure, as well as a stage for the timestepper and any relevant inputs provided by a corresponding InputProvider. The ModelIntegrator implements the Oceananigans.AbstractModel interface and can thus be treated as a "model" in Oceananigans Simulations and output reading/writing utilities.

struct Namespace{name, Vars}

Represents a new variable namespace, typically from a subcomponent of the model.

Represents a hydrology scheme where soil water is immobile.

struct PALADYNAutotrophicRespiration{NF} <: Terrarium.AbstractAutotrophicRespiration{NF}

Autotrophic respiration implementation from PALADYN (Willeit 2016).

Authors: Maha Badri and Matteo Willeit

Properties:

• cn_sapwood::Any: Sapwood parameter

• cn_root::Any: Root parameter

• aws::Any: Ratio of total to respiring stem carbon, Cox 2001, PFT specific [-]

struct PALADYNCanopyEvapotranspiration{NF, GR<:Terrarium.AbstractGroundEvaporationResistanceFactor} <: Terrarium.AbstractEvapotranspiration{NF}

Canopy evapotranspiration scheme from PALADYN (Willeit 2016) that includes a canopy evaporation term based on the saturation fraction of canopy water defined by the canopy hydrology scheme.

\[E_g &= \beta \frac{\Delta q}{r_a} \ E_c &= f_{\text{can}} \frac{\Delta q}{r_a} \ T_c &= \frac{\Delta q}{r_a + r_s} \\]

Properties:

• C_can: Drag coefficient for the traansfer of heat and water between the ground and canopy

• ground_resistance: Parameterization for ground resistance to evaporation/sublimation

struct PALADYNCanopyInterception{NF} <: Terrarium.AbstractCanopyInterception{NF}

Canopy interception and storage implementation following PALADYN (Willeit 2016) considering only liquid water (no snow).

Properties:

• α_int: Canopy water interception factor for tree PFTs

• k_ext: Extinction coefficient for radiation through vegetation [-]

• w_can_max: Canopy interception capacity parameter, Verseghy 1991 [kg/m²]

• τ_w: Canopy water removal timescale [s]

struct PALADYNCarbonDynamics{NF} <: Terrarium.AbstractVegetationCarbonDynamics{NF}

Vegetation carbon dynamics implementation following PALADYN (Willeit 2016) but considering only the sum of the vegetation carbon pools. The subsequent splitting into Cleaf, Cstem, C_root is not implemented for now.

Authors: Maha Badri

Properties:

• SLA::Any: Specific leaf area (Kattge et al. 2011) [m²/kgC], PFT specific

• awl::Any: Allometric coefficient, modified from Cox 2001 to account for bwl=1 [kgC/m²], PFT specific

• LAI_min::Any: Minimum Leaf Area Index modified from Clark et al. 2011 [m²/m²], PFT specific

• LAI_max::Any: Maximum Leaf Area Index modified from Clark et al. 2011 [m²/m²], PFT specific

• γL::Any: Leaf turnover rate (Kattge et al. 2011) [1/year], PFT specific

• γR::Any: Root turnover rate [1/year], PFT specific

• γS::Any: Stem turnover rate modified from Clark et al. 2011 [1/year], PFT specific

struct PALADYNPhenology{NF} <: Terrarium.AbstractPhenology{NF}

Vegetation phenology implementation from PALADYN (Willeit 2016).

Authors: Maha Badri and Matteo Willeit

Properties:

struct PALADYNVegetationDynamics{NF} <: Terrarium.AbstractVegetationDynamics{NF}

Vegetation dynamics implementation following PALADYN (Willeit 2016) for a single PFT based on the Lotka–Volterra approach.

Authors: Maha Badri

Properties:

• ν_seed::Any: Vegetation seed fraction [-]

• γv_min::Any: Minimum vegetation disturbance rate [1/year]

struct PhysicalConstants{NF}

A collection of general physical constants that do not (usually) need to be varied in parameter calibration.

struct PiecewiseLinearInitialSoilTemperature{NF, N}

Represents a piecewise linear temperature initializer specified from the given knots.

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,
    ...
)

Properties:

• knots::NTuple{N, NF} where {NF, N}

struct PrescribedAlbedo{NF} <: Terrarium.AbstractAlbedo{NF}

Properties:

struct PrescribedAtmosphere{NF, tracernames, Precip<:Terrarium.AbstractPrecipitation, IncomingRad<:Terrarium.AbstractIncomingRadiation, Humidity<:Terrarium.AbstractHumidity, Aerodynamics<:Terrarium.AbstractAerodynamics, Tracers<:(NamedTuple{tracernames, <:Tuple{Vararg{TracerGas}}})} <: Terrarium.AbstractAtmosphere{NF, Precip<:Terrarium.AbstractPrecipitation, IncomingRad<:Terrarium.AbstractIncomingRadiation, Humidity<:Terrarium.AbstractHumidity, Aerodynamics<:Terrarium.AbstractAerodynamics}

Represents prescribed atmospheric conditions given by the following input variables: - Air temperature - Humidity - Atmospheric pressure - Windspeed - Precipitation - Solar radiation - Zero or more tracer gases (defaults to CO2 only)

Precpitation and solar radiation are specified according to specialized subtypes which dictate the form of the input data; for precipitation, this defaults to RainSnow, i.e. rain- and snowfall given as separate inputs, while for solar radiation, the default is LongShortWaveRadiation which partitions downwelling radiation into the common short- and long wave lengths representing solar and thermal (infrared) radiation.

struct PrescribedRadiativeFluxes{NF} <: Terrarium.AbstractRadiativeFluxes{NF}

Represents the simplest scheme for the radiative budget where outgoing shortwave and longwave radiation are given as input variables. Net radiation is diagnosed by summing all radiative fluxes:

\[R_{\text{net}} = S_{\uparrow} - S_{\downarrow} + L_{\uparrow} - L_{\downarrow}\]

struct PrescribedSkinTemperature{NF} <: Terrarium.AbstractSkinTemperature{NF}

Simple scheme for prescribed skin temperatures from input variables.

Properties:

• κₛ: Assumed thermal conductivity at the surface [W m⁻¹ K⁻¹]

struct PrescribedSpacing{NF} <: Terrarium.AbstractVerticalSpacing{NF}

Vertical discretization with prescribed thicknesses for each layer. The number of layers is equal to the length of the given vector.

Properties:

• Δz::Vector

struct PrescribedTurbulentFluxes{NF} <: Terrarium.AbstractTurbulentFluxes{NF}

Represents the simplest case where the turbulent (sensible and latent) heat fluxes are prescribed via input variables.

struct PrognosticVariable{name, VD<:Terrarium.VarDims, UT<:Unitful.Units, Var<:Terrarium.Variable{name, VD<:Terrarium.VarDims, UT<:Unitful.Units}, CL<:Union{Nothing, Terrarium.AbstractClosureRelation}, TV<:Union{Nothing, AuxiliaryVariable}, DT<:IntervalSets.AbstractInterval} <: Terrarium.AbstractProcessVariable{name, VD<:Terrarium.VarDims, UT<:Unitful.Units}

Represents a prognostic state variable with the given name and spatial dims.

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

Initializer that sets soil/ground temperature to a thermal quasi-steady state based on the given surface temperature, geothermal heat flux, and bulk (constant) thermal conductivity. Note that this is not a true thermal steady state, which would require iterative calculation of the thermal conductivity from the soil properties and initial temperature profile.

Properties:

• T₀::Any

• Qgeo::Any

• k_eff::Any

RichardsEq{PS} <: AbstractVerticalFlow

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

\[\phi(z) \frac{\partial s_{\mathrm{wi}}(\Psi(z,t))}{\partial t} = \n+\nabla \cdot \bigl(K(s_{\mathrm{wi}}, T) \; \n+\nabla (\psi_m + 1)\bigr)\]

which describes the vertical movement of water according to gravity-driven percolation and capillary-driven diffusion.

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 saturtion and pressure head.

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

Simple initialization scheme for soil/ground saturation that sets the initial water table at the given depth and the saturation level in all layers in the vadose (unsaturated) to a constant value.

Properties:

• vadose_zone_saturation::Any

• water_table_depth::Any

struct SoilEnergyBalance{NF, HeatOperator<:Terrarium.AbstractHeatOperator, EnergyClosure<:Terrarium.AbstractSoilEnergyClosure, ThermalProps<:(SoilThermalProperties{NF})} <: Terrarium.AbstractSoilEnergyBalance{NF}

Standard implementation of the soil energy balance accounting for freezing and thawing of pore water/ice. The closure field represents the temperature-energy closure $U(T,\phi)$ which relates temperature to internal energy via an arbitrary set of additional parameters $\phi$ which are determined by the model configuration.

Properties:

• operator::Terrarium.AbstractHeatOperator: Heat transport operator

• closure::Terrarium.AbstractSoilEnergyClosure: Closure relating energy and temperature

• thermal_properties::SoilThermalProperties: Soil thermal properties

struct SoilEnergyTemperatureClosure <: Terrarium.AbstractSoilEnergyClosure

Defines the constitutive relationship between the the internal energy and temperature of a soil volume, i.e.

\[U(T) = T\times C(T) - L_f \theta_{wi} (1 - F(T))\]

where T is temperature, C(T) is the temperature-dependent heat capacity, L_f is the volumetric latent heat of fusion, and F(T) is the constitutive relation between temperature and the unfrozen fraction of pore water. Note that, under this formulation, zero energy corresponds to 0°C with no ice, i.e. all pore water fully thawed.

The closure relation is defined as being a mapping from the conserved quantity (energy) to the continuous quantity (temperature), i.e. the inverse of U(T).

struct SoilEnergyWaterCarbon{NF, Stratigraphy<:Terrarium.AbstractStratigraphy{NF}, Energy<:Terrarium.AbstractSoilEnergyBalance{NF}, Hydrology<:Terrarium.AbstractSoilHydrology{NF}, Biogeochemistry<:Terrarium.AbstractSoilBiogeochemistry{NF}} <: Terrarium.AbstractSoil{NF}

Coupled process type that encapsulates the coupling of soil energy, water, and carbon dynamics. The stratigraphy parameterization determines how the vertical layering of the soil is parameterized.

struct SoilHeatCapacities{NF}

Properties:

• water::Any

• ice::Any

• air::Any

• mineral::Any

• organic::Any

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 [-]

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 mapping between saturation water potential (hydraulic head)

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

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

Initializer for coupled soil energy/hydrology/biogeochemistry models.

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

General implementation of a 1D column model of soil energy, water, and carbon transport.

Properties:

• grid::Terrarium.AbstractLandGrid: Spatial grid type

• soil::Terrarium.AbstractSoil: Soil processes

• constants::PhysicalConstants: Physical constants

• initializer::Terrarium.AbstractInitializer: State variable initializer

SoilMoistureResistanceFactor <: AbstractGroundEvaporationResistanceFactor

Implements the soil moisture limiting resistance factor of Lee and Pielke (1992),

\[\beta = \begin{cases} \frac{1}{4} \left(1 - \cos\left(π \frac{\theta_1}{\theta_{\text{fc}}} \right)\right) & \theta_1 < \theta_{\text{fc}} \ 1 & \text{otherwise} \end{cases}\]

struct SoilPorositySURFEX{NF} <: Terrarium.AbstractSoilPorosity{NF}

SURFEX parameterization of mineral soil porosity (Masson et al. 2013).

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.

struct SoilTexture{NF} <: Terrarium.AbstractSoilTexture{NF}

Represents soil texture as a fractional mixture of sand, silt, and clay. Accepts values

struct SoilThermalConductivities{NF}

Properties:

• water::Any

• ice::Any

• air::Any

• mineral::Any

• organic::Any

struct SoilThermalProperties{NF, FC, CondBulk}

Properties:

• conductivities::SoilThermalConductivities: Thermal conductivities for all constituents

• bulk_conductivity::Any: Method for computing bulk thermal conductivity from constituents

• heat_capacities::SoilHeatCapacities: Thermal conductivities for all constituents

• freezecurve::Any: Freezing characteristic curve needed for energy-temperature closure

struct SoilVolume{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

struct StateVariables{NF, prognames, closurenames, auxnames, inputnames, nsnames, ProgFields, TendFields, AuxFields, InputFields, Namespaces, ClockType} <: Terrarium.AbstractStateVariables

Container type for all Fields corresponding to state variables defined by a model. StateVariables partitions the fields into three categories: prognostic, tendencies, and auxiliary. Prognostic variables are those which characterize the state of the system and are assigned tendencies to be integrated by the timestepper. Auxiliary fields are additional state variables derived from the prognostic state variables but which are conditionally independent of their values at the previous time step given the current prognostic state. It is worth noting that tendencies are also treated internally as auxiliary variables; however, they are assigned their own category here since they need to be handled separately by the timestepping scheme.

struct StaticExponentialRootDistribution{NF} <: Terrarium.AbstractRootDistribution{NF}

Static vegetation root distribution implementation in PALADYN (Willeit 2016) based on the scheme proposed by Zeng (2001). The PDF of the root distribution is modeled as

\[\frac{\partial R}{\partial z} = \frac{1}{2} \left( a \exp(a z) + b \exp(b z) \right)\]

which is then integrated over the soil column and normalized to sum to unity. Note that this is effectively the average of two exponential distributions with rates a and b, both with units m⁻¹. The resulting CDF of this distribution determines the root distribution.

Properties:

• a: First empirical rate parameter for root distribution

• b: Second empirical rate parameter for root distribution

struct SurfaceEnergyBalance{NF, SkinTemperature<:Terrarium.AbstractSkinTemperature{NF}, TurbulentFluxes<:Terrarium.AbstractTurbulentFluxes{NF}, RadiativeFluxes<:Terrarium.AbstractRadiativeFluxes{NF}, Albedo<:Terrarium.AbstractAlbedo{NF}} <: Terrarium.AbstractSurfaceEnergyBalance{NF}

Standard implementation of the surface energy balance (SEB) that computes the radiative, turbulent, and ground energy fluxes at the surface. The SEB is also responsible for defining and solving the so-called skin temperature (effective emission temperature of the land surface) as well as the albedo.

struct SurfaceEnergyModel{NF, GridType<:(Terrarium.AbstractLandGrid{NF}), SEB<:Terrarium.AbstractSurfaceEnergyBalance, Atmosphere<:Terrarium.AbstractAtmosphere, Initializer<:Terrarium.AbstractInitializer} <: Terrarium.AbstractSurfaceEnergyModel{NF, GridType<:(Terrarium.AbstractLandGrid{NF})}

Simple model wrapper for the SurfaceEnergyBalance that couples it with an AbstractAtmosphere to provide meteorological inputs. This model type is mostly intended for testing but could also be used for simple energy balance calculations from prescribed meteorological and ground temperature conditions.

struct SurfaceHydrology{NF, CanopyInterception<:Terrarium.AbstractCanopyInterception{NF}, Evapotranspiration<:Terrarium.AbstractEvapotranspiration{NF}, SurfaceRunoff<:Terrarium.AbstractSurfaceRunoff{NF}} <: Terrarium.AbstractSurfaceHydrology{NF}

Properties:

• canopy_interception: Canopy hydrology scheme

• evapotranspiration: Canopy evapotranspiration scheme

• surface_runoff: Surface runoff scheme

Generic type representing the concentration of a particular tracer gas in the atmosphere.

struct UniformSpacing{NF} <: Terrarium.AbstractVerticalSpacing{NF}

Uniform vertical discretization with N layers of size Δz.

Properties:

• Δz::Any

• N::Int64

struct UnsatKLinear{NF} <: Terrarium.AbstractUnsatK{NF}

Simple formulation of hydraulic conductivity as a linear function of the liquid water saturated fraction, i.e. soil.water / (soil.water + soil.ice + soil.air).

struct UnsatKVanGenuchten{NF} <: Terrarium.AbstractUnsatK{NF}

Formulation of hydraulic conductivity as a function of saturated hydraulic conductivity K_sat and volumetric fractions, assumed to include those of water, ice, and air.

See van Genuchten (1980) and Westermann et al. (2023).

Alias for Type{Val{x}}

struct Variable{name, VD, UT} <: Terrarium.AbstractVariable{name, VD, UT}

Represents metadata for a generic state variable with the given name and spatial dims.

struct Variables{ProgVars, TendVars, AuxVars, InputVars, Namespaces}

Container for abstract state variable definitions. Automatically collates and merges all variables and namespaces passed into the constructor.

struct VegetationCarbon{NF, Photosynthesis<:Terrarium.AbstractPhotosynthesis{NF}, StomatalConducatance<:Terrarium.AbstractStomatalConductance{NF}, AutotrophicRespiration<:Terrarium.AbstractAutotrophicRespiration{NF}, Phenology<:Terrarium.AbstractPhenology{NF}, CarbonDynamics<:Terrarium.AbstractVegetationCarbonDynamics{NF}, VegetationDynamics<:Union{Nothing, Terrarium.AbstractVegetationDynamics}, RootDistribution<:Union{Nothing, Terrarium.AbstractRootDistribution}} <: Terrarium.AbstractVegetation{NF}

Represents a generic coupling of vegetation carbon processes.

struct VegetationModel{NF, Vegetation<:Terrarium.AbstractVegetation{NF}, Atmosphere<:(Terrarium.AbstractAtmosphere{NF, PR, IR, HM, AD} where {PR<:Terrarium.AbstractPrecipitation, IR<:Terrarium.AbstractIncomingRadiation, HM<:Terrarium.AbstractHumidity, AD<:Terrarium.AbstractAerodynamics{NF}}), GridType<:(Terrarium.AbstractLandGrid{NF}), Constants<:PhysicalConstants{NF}, Initializer<:Terrarium.AbstractInitializer} <: Terrarium.AbstractVegetationModel{NF, GridType<:(Terrarium.AbstractLandGrid{NF})}

Model for natural (unmanaged) vegetation processes for a single plant functional type (PFT). Multiple PFTs can be later handled with a TiledVegetationModel type that composes multiple VegetationModels with different parameters for each PFT.

Properties:

• grid::Terrarium.AbstractLandGrid: Spatial grid type

• atmosphere::Terrarium.AbstractAtmosphere: Atmospheric input configuration

• vegetation::Terrarium.AbstractVegetation: Vegetation processes

• constants::PhysicalConstants: Physical constants

• initializer::Terrarium.AbstractInitializer: State variable initializer

XY <: VarDims

Indicator type for variables that should be assigned a 2D (lateral only) field on their associated grid.

XYZ <: VarDims

Indicator type for variables that should be assigned a 3D field on their associated grid.

Adapt.adapt(::NumberFormatAdaptor{NF}, obj) where {NF<:Number}

Adaptor that reconstructs arbitrary data structures with all numeric values converted to the specified number format NF.

Merges all of the given Variables containers into a single container.

Convenience alias for Oceananigans.BoundaryConditions.compute_z_bcs! that adds flux BCs for progvar to its corresponding tendency.

Invoke fill_halo_regions! for all prognostic Fields in state.

Implementation of Oceananigans.BoundaryConditions.getbc for variable placeholders that retrieves the input Field from state and returns the value at the given index.

run!(integrator; steps, period, Δt)

Run the simulation for steps or a given time period with timestep size Δt (in seconds or Dates.Period).

Reset all Fields in state to zero.

update_state!(state::StateVariables, model::AbstractModel, inputs::InputSources; compute_tendencies = true)

Update the state for the given model and inputs; this includes calling update_inputs! and fill_halo_regions! followed by compute_auxiliary! and compute_tendencies!, if compute_tendencies = true.

Creates a TracerGas for ambient CO2 with concentration prescribed by an input variable with the given name.

Alias for PrescribedGradient representing a Neumann-type zero pressure gradient at the bottom of the soil column, thereby allowing free drainage of water.

Alias for FluxBoundaryCondition on internal_energy with name geothermal_heat_flux representing the geothermal heat flux at the bottom boundary of the soil column.

Alias for FluxBoundaryCondition on internal_energy with name ground_heat_flux representing the net ground heat flux at the soil surface.

Alias for NoFlux representing a zero-flux bottom boundary condition for water flow (prognostic variable saturation_water_ice).

Alias for PrescribedFlux with name infiltration representing liquid water infiltration at the soil surface.

Alias for ValueBoundaryCondition on top temperature (in °C) with the given variable name.

Alias for ValueBoundaryCondition on top temperature (in °C) with the given variable name.

Creates a NamedTuple from the given tracer gas types.

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

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.

aerodynamic_resistance(i, j, grid, fields, atmos::PrescribedAtmosphere)

Compute the aerodynamic resistance (inverse conductance) at grid cell i, j.

aerodynamic_resistance(
    i,
    j,
    grid,
    fields,
    atmos::Terrarium.AbstractAtmosphere,
    evtr::PALADYNCanopyEvapotranspiration
) -> Any

Compute the aerodynamic resistance between the ground and canopy as a function of LAI and SAI.

air_pressure(i, j, grid, fields, ::PrescribedAtmosphere)

Retrieve or compute the air pressure at the current time step.

air_temperature(i, j, grid, fields, ::PrescribedAtmosphere)

Retrieve or compute the air temperature at the current time step.

albedo(i, j, grid, fields, ::AbstractAlbedo)

Return the current albedo at the given indices.

auxiliary(name, dims; ...)
auxiliary(name, dims, ctor; ...)
auxiliary(name, dims, ctor, params; units, domain, desc)

Convenience constructor method for AuxiliaryVariable.

auxiliary_fields(state, components)

Retrieves all Fields from state corresponding to auxiliary variables defined on the given components.

Helper method that selects only auxiliary variables declared on obj.

canopy_water(i, j, grid, fields, ::AbstractCanopyInterception)

Compute or retrieve the current canopy water storage [kg/m^2].

celsius_to_kelvin(c::PhysicalConstants, T)

Convert the given temperature in °C to Kelvin based on the constant Tref.

Check for variables/namespaces with duplicate names and raise an error if duplicates are detected.

closure!(state, model::AbstractModel)

Apply all closure relations defined for the given model.

closure!(state, grid, [closure,] process, args...)

Apply the closure for process with the given grid and additional implementation-specific args. If closure is not specified, it is automatically inferred from first(closures(process)).

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

Computes pressure_head $Ψ = ψm + ψz + ψh$ from the current saturation_water_ice state.

closure_fields(state, components)

Retrieves all Fields from state corresponding to closure variables defined on the given components.

Helper method that selects only closure (auxiliary) variables declared on obj.

closures(process::AbstractProcess)

Return a tuple of AbstractClosureRelations defined by the given processes type. Note that this is a type-stable, @generated function that is compiled for each argument type.

compute_APAR(photo, swdown, LAI)

Computes absorbed PAR limited by the fraction of PAR assimilated at ecosystem level APAR [mol/m²/s], Eq. 62, PALADYN (Willeit 2016).

compute_Ag(photo, c_1, c_2, APAR, Vc_max, β)

Computes the gross photosynthesis rate Ag [gC/m²/s], Eqn 2, Haxeltine & Prentice 1996

compute_C_veg_tend(vegcarbon_dynamics, LAI_b, NPP)

Computes the C_veg tendency based on NPP and the balanced Leaf Area Index LAI_b, Eq. 72, PALADYN (Willeit 2016)

compute_GPP(_, An)

Compute the Gross Primary Production [kgC/m²/s].

compute_JE_JC(photo, c_1, c_2, APAR, Vc_max)

Computes the PAR-limited and the rubisco-activity-limited photosynthesis rates JE and JC [gC/m²/s], Eqn 3+5, Haxeltine & Prentice 1996.

compute_LAI(phenol, LAI_b)

Computes LAI, based on the balanced Leaf Area Index LAI_b:

compute_NPP(autoresp, GPP, Ra)

Computes Net Primary Productivity NPP as the difference between Gross Primary Production GPP and autotrophic respiration Ra in [kgC/m²/day].

compute_PAR(photo, swdown)

Computes NET Photosynthetically Active Radiation PAR [mol/m²/s].

compute_Ra(
    autoresp,
    vegcarbon_dynamics,
    T_air,
    T_soil,
    Rd,
    phen,
    C_veg,
    GPP
)

Computes autotrophic respiration Ra as the sum of maintenance respiration Rm and growth respiration Rg in [kgC/m²/day].

compute_Rd(photo, Vc_max, β)

Computes the leaf respiration rate Rd [gC/m²/s], Eqn 10, Haxeltine & Prentice 1996 and Eq. 10 PALADYN (Willeit 2016).

compute_Rg(autoresp, GPP, Rm)

Computes growth respiration Rg in [kgC/m²/day].

compute_Rm(
    autoresp,
    vegcarbon_dynamics,
    T_air,
    T_soil,
    Rd,
    phen,
    C_veg
)

Computes maintenance respiration Rm in [kgC/m²/day].

compute_Vc_max(
    photo,
    c_1,
    PAR,
    Kc,
    Ko,
    Γ_star,
    pres_i,
    pres_O2
)

Computes the maximum rate of net photosynthesis Vc_max [gC/m²/s], following the coordination hypothesis (acclimation), see Harrison 2021 Box 2. Note: this is not the same formula in PALADYN paper, this implementaion is taken from the code

compute_autotrophic_respiration(
    i, j, grid, fields,
    autoresp::AbstractAutotrophicRespiration,
    vegcarbon::AbstractVegetationCarbonDynamics,
    atmos::AbstractAtmosphere,
    args...
)

Cell-level autotrophic respiration computation. Implementations should compute autotrophic respiration and related diagnostics (e.g. NPP) for the given cell.

compute_autotrophic_respiration(
    i,
    j,
    grid,
    fields,
    autoresp::PALADYNAutotrophicRespiration,
    vegcarbon_dynamics::PALADYNCarbonDynamics,
    atmos::Terrarium.AbstractAtmosphere
) -> Tuple{Any, Any}

Compute autotrophic respiration following the scheme of PALADYN (Willeit 2016).

compute_auxiliary!(state, model::AbstractModel)

Compute updates to all auxiliary variables based on the current prognostic state of the model.

compute_auxiliary!(state, grid, process::AbstractProcess, args...)

Compute all auxiliary state variables for the given process on grid. Implementations of AbstractProcess may define additional args that correspond to different process coupling interfaces.

compute_c1_c2(photo, T_air, Γ_star, Kc, Ko, pres_i, pres_O2)

Computes factor for light-limited assimilation c_1 and factor for RuBisCO-limited assimilation c_2, Eqs. C4+C5, PALADYN (Willeit 2016).

compute_canopy_interception(
    canopy_interception::PALADYNCanopyInterception{NF},
    precip,
    LAI,
    SAI
) -> Any

Compute I_can, the canopy rain interception, following Eq. 42, PALADYN (Willeit 2016).

compute_canopy_saturation_fraction(
    canopy_interception::PALADYNCanopyInterception{NF},
    w_can,
    LAI,
    SAI
) -> Any

Compute the canopy saturation fraction as w_can / w_can_max.

compute_canopy_water_removal(
    canopy_interception::PALADYNCanopyInterception{NF},
    constants::PhysicalConstants{NF},
    w_can
) -> Any

Compute the canopy water removal rate as w_can / ρw / τw.

compute_energy_tendency(i, j, k, grid, ::SoilEnergyBalance, args...)

Compute the internal energy tendency ∂U∂t at index i, j, k.

compute_evaporation_canopy(
    _::PALADYNCanopyEvapotranspiration,
    Δq,
    f_can,
    rₐ
) -> Any

Compute evaporation of water intercepted by the canopy from humidity gradient Δq, canopy saturation fraction f_can, and aerodynamic resistance rₐ.

compute_evaporation_ground(
    _::PALADYNCanopyEvapotranspiration,
    Δq,
    β,
    rₐ,
    rₑ
) -> Any

Compute potential evaporation from the ground below the canopy, following Eq. 5, PALADYN (Willeit 2016); Δq is the humidity gradient, β is the ground evaporation resistance factor, rₐ is aerodynamic resistance, and rₑ is aerodynamic resistance between the ground and canopy.

Compute transpiration, evaporation_ground, and evaporation_canopy fluxes on grid for the given scheme evtr and process dependencies.

compute_f_deciduous(phenol)

Computes f_deciduous, a factor for smooth transition between evergreen and deciduous [-].

compute_f_temp(autoresp, T_air, T_soil)

Computes temperature factors f_temp_air and f_temp_soil for autotrophic respiration.

compute_ground_heat_flux(
    _::Terrarium.AbstractSkinTemperature,
    R_net,
    H_s,
    H_l
) -> Any

Compute the ground heat flux as the residual of the net radiation R_net and the sensible H_s and latent H_l heat flux.

compute_humidity_vpd(
    i,
    j,
    grid,
    fields,
    atmos::Terrarium.AbstractAtmosphere,
    c::PhysicalConstants
) -> Any
compute_humidity_vpd(
    i,
    j,
    grid,
    fields,
    atmos::Terrarium.AbstractAtmosphere,
    c::PhysicalConstants,
    Ts
) -> Any

Computes the specific humidity (vapor pressure) deficit over a surface at temperature Ts from the current atmospheric fields.

compute_hydraulics!(
    out,
    i,
    j,
    k,
    grid,
    fields,
    hydrology::SoilHydrology,
    strat::Terrarium.AbstractStratigraphy,
    bgc::Terrarium.AbstractSoilBiogeochemistry
) -> Any

Kernel function that computes soil hydraulics and unsaturated hydraulic conductivity.

compute_infiltration(
    runoff::DirectSurfaceRunoff{NF},
    influx,
    sat_top,
    max_infil
) -> Any

Compute infiltration from the given influx (water available for infiltration), saturation of the uppermost soil layer sat_top, and the maximum allowed infiltration max_infil.

compute_latent_heat_flux(
    i,
    j,
    grid,
    fields,
    tur::DiagnosedTurbulentFluxes,
    evtr::Terrarium.AbstractEvapotranspiration,
    constants::PhysicalConstants
) -> Any

Compute the latent heat flux at i, j based on the given evapotranspiration scheme. This implementation derives the latent heat flux from the surface_humidity_flux defined by evtr which is assumed to be already computed.

compute_latent_heat_flux(
    i,
    j,
    grid,
    fields,
    tur::DiagnosedTurbulentFluxes,
    skinT::Terrarium.AbstractSkinTemperature,
    atmos::Terrarium.AbstractAtmosphere,
    constants::PhysicalConstants
) -> Any

Compute the bare ground latent heat flux at i, j based on the current skin temperature and atmospheric conditions. This imlementation assumes that evaporation is the only contributor to the latent heat flux.

compute_latent_heat_flux(
    _::DiagnosedTurbulentFluxes,
    Q_h,
    ρₐ,
    Lsl
) -> Any

Compute the latent heat flux as a function of the humidity flux Q_h [m/s], the density ρₐ [kg/m³] of air, and the specific latent heat of fusion Lsl [J/kg].

compute_longwave_up(::DiagnosedRadiativeFluxes, constants::PhysicalConstants, surface_longwave_down, Ts, ϵ)

Compute outgoing longwave radiation from incoming surface_longwave_down, surface temperature Ts, and emissivity ϵ.

compute_phen(phenol)

Computes phen, the phenology factor [-].

compute_phenology(i, j, grid, fields, phenol::AbstractPhenology)

Cell-level phenology computation. Implementations return phenology factors and derived LAI at the given index i, j.

compute_photosynthesis(i, j, grid, fields, photo::AbstractPhotosynthesis, atmos::AbstractAtmosphere)

Cell-level photosynthesis computation. Implementations compute leaf respiration and net assimilation for a single horizontal cell and return the pair (Rd, An, GPP) or similar outputs as required by the photosynthesis scheme.

compute_photosynthesis(
    photo,
    T_air,
    swdown,
    pres,
    co2,
    LAI,
    λc,
    β
)

Computes Gross Primary Production GPPin [kgC/m²/day] and leaf respiration Rd in [gC/m²/day]

compute_plant_available_water(
    i, j, k, grid, fields,
    paw::AbstractPlantAvailableWater,
    soil::AbstractSoil
)

Comptue the plant-available water fraction for grid cell i, j and soil layer k.

compute_precip_ground(_, precip, I_can, R_can)

Compute precip_ground, the rate of rain reaching the ground, following a modified version of Eq. 44, PALADYN (Willeit 2016). Instead of subtracting the tendency, we just directly subtract interception and add the removal rate R_can.

compute_pres_i(photo, λc, pres_a)

Computes intercellular CO2 partial pressure [Pa], Eq. 67, PALADYN (Willeit 2016).

compute_resp10(autoresp)

Computes resp10

compute_saturation_tendency!(
    saturation_water_ice_tendency,
    i,
    j,
    k,
    grid,
    clock,
    fields,
    hydrology::SoilHydrology,
    strat::Terrarium.AbstractStratigraphy,
    bgc::Terrarium.AbstractSoilBiogeochemistry,
    constants::PhysicalConstants,
    evtr::Union{Nothing, Terrarium.AbstractEvapotranspiration}
) -> Any

compute_sensible_heat_flux(
    i,
    j,
    grid,
    fields,
    tur::DiagnosedTurbulentFluxes,
    skinT::Terrarium.AbstractSkinTemperature,
    atmos::Terrarium.AbstractAtmosphere,
    constants::PhysicalConstants
) -> Any

Compute the sensible heat flux at i, j based on the current skin temperature and atmospheric conditions.

compute_sensible_heat_flux(
    _::DiagnosedTurbulentFluxes,
    Q_T,
    ρₐ,
    cₐ
) -> Any

Compute the sensible heat flux as a function of the bulk aerodynamic temperature gradient Q_T [K m/s] and the density ρₐ [kg/m³] and specific heat capacity cₐ [J/kg K] of air.

compute_shortwave_up(::DiagnosedRadiativeFluxes, surface_shortwave_down, α)

Compute outgoing shortwave radiation from the incoming surface_shortwave_down and albedo α.

compute_skin_temperature(
    skinT::ImplicitSkinTemperature,
    Tg,
    G,
    Δz
) -> Any

Compute the implicit update of the skin temperature from the given ground surface temperature Tg, ground heat flux G, and distance Δz.

compute_stomatal_conductance(
    i, j, grid, fields,
    stomcond::AbstractStomatalConductance,
    photo::AbstractPhotosynthesis,
    atmos::AbstractAtmosphere,
    constants::PhysicalConstants,
    args...
)

Cell-level stomatal conductance computation. Returns stomatal/canopy conductance and internal CO₂ ratio for the specified cell.

compute_surface_drainage(
    runoff::DirectSurfaceRunoff{NF},
    surface_excess_water
) -> Any

Compute surface drainage flux from the current surface_excess_water resevoir state.

compute_surface_energy_fluxes!(
    state,
    grid,
    seb::SurfaceEnergyBalance,
    atmos::Terrarium.AbstractAtmosphere,
    constants::PhysicalConstants
)
compute_surface_energy_fluxes!(
    state,
    grid,
    seb::SurfaceEnergyBalance,
    atmos::Terrarium.AbstractAtmosphere,
    constants::PhysicalConstants,
    hydrology::Union{Nothing, Terrarium.AbstractSurfaceHydrology},
    args...
)

Compute the surface energy fluxes on grid based on the current atmospheric state.

compute_surface_energy_fluxes!(
    out,
    i,
    j,
    grid,
    fields,
    seb::SurfaceEnergyBalance,
    atmos::Terrarium.AbstractAtmosphere,
    constants::PhysicalConstants
) -> Any
compute_surface_energy_fluxes!(
    out,
    i,
    j,
    grid,
    fields,
    seb::SurfaceEnergyBalance,
    atmos::Terrarium.AbstractAtmosphere,
    constants::PhysicalConstants,
    evtr::Union{Nothing, Terrarium.AbstractEvapotranspiration},
    args...
) -> Any

Fused kernel function that computes the radiative and turbulent fluxes, as well as the ground heat flux.

compute_surface_energy_fluxes!(state, grid, ::AbstractSurfaceEnergyBalance, args...)

Compute the surface energy fluxes and skin temperature from the current state and grid. The required args are implementation dependent.

compute_surface_excess_water_tendency!(
    surface_excess_water_tendency,
    i,
    j,
    k,
    grid,
    clock,
    fields,
    hydrology::SoilHydrology,
    runoff::Union{Nothing, Terrarium.AbstractSurfaceRunoff}
) -> Any

compute_surface_excess_water_tendency(
    i,
    j,
    k,
    grid,
    clock,
    fields,
    hydrology::SoilHydrology,
    runoff::Union{Nothing, Terrarium.AbstractSurfaceRunoff}
) -> Any

Kernel function for computing the tendency of the prognostic surface_excess_water variable in all grid cells.

Compute the net radiation budget given incoming and outgoing shortwave and longwave radiation.

compute_surface_runoff(
    runoff::DirectSurfaceRunoff,
    precip_ground,
    surface_drainage,
    infil
) -> Any

Compute surface runoff as precipitation + surface_drainage - infiltration.

compute_tendencies!(state, model::AbstractModel)

Compute tendencies for all prognostic state variables for model stored in the given state. This method should be called after compute_auxiliary!.

compute_tendencies!(state, grid, process::AbstractProcess, args...)

Compute the tendencies of all prognostic state variables for the given process on grid. Implementations of AbstractProcess may define additional args that correspond to different process coupling interfaces.

compute_thermal_conductivity(i, j, k, grid, ::SoilEnergyBalance, args...)

Compute the thermal conductivity at index i, j, k.

compute_thermal_conductivity(props, soil)

Compute the bulk thermal conductivity of the given soil volume.

compute_transpiration(
    _::PALADYNCanopyEvapotranspiration{NF},
    Δq,
    rₐ,
    gw_can
) -> Any

Compute potential transpiration from the given humidity gradient, aerodynamic resistance rₐ and stomatal conductance gw_can.

compute_veg_carbon_tendency(i, j, grid, fields, vegcarbon::AbstractVegetationCarbonDynamics)

Cell-level vegetation-carbon tendency computation. Implementations compute the tendency for the total vegetation carbon pool at the given index i, j.

compute_volumetric_water_content_tendency(
    i,
    j,
    k,
    grid,
    clock,
    fields,
    hydrology,
    constants,
    evapotranspiration
)

Compute the volumetric water content (VWC) tendency at grid cell i, j k according to the Richardson-Richards equation. Note that the VWC tendency is not scaled by the porosity and is thus not the same as the saturation tendency.

compute_volumetric_water_content_tendency(
    i,
    j,
    k,
    grid,
    clock,
    fields,
    hydrology::SoilHydrology{NF, VerticalFlow, SaturationClosure, SoilHydraulics} where {VerticalFlow<:Terrarium.AbstractVerticalFlow, SaturationClosure<:Terrarium.AbstractSoilWaterClosure, SoilHydraulics<:(Terrarium.AbstractSoilHydraulics{NF})},
    constants::PhysicalConstants,
    evtr::Union{Nothing, Terrarium.AbstractEvapotranspiration}
) -> Any

Compute the volumetric water content (VWC) tendency at grid cell i, j k f. Note that the VWC tendency is not scaled by the porosity and is thus not the same as the saturation tendency.

compute_vpd(
    i,
    j,
    grid,
    fields,
    atmos::Terrarium.AbstractAtmosphere,
    c::PhysicalConstants
) -> Any
compute_vpd(
    i,
    j,
    grid,
    fields,
    atmos::Terrarium.AbstractAtmosphere,
    c::PhysicalConstants,
    Ts
) -> Any

Computes the vapor pressure deficit over a surface at temperature Ts from the current atmospheric fields.

compute_vpd(c, pres, q_air, T)

Computes the vapor pressure deficit over a surface at temperature T from the given surface pressure pres and specific humidity of air q_air.

compute_w_can_tendency(
    _::PALADYNCanopyInterception{NF},
    I_can,
    E_can,
    R_can
) -> Any

Compute the w_can tendency and removal rate following Eq. 41, PALADYN (Willeit 2016).

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})}
) -> Any

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

compute_Γ_star(photo, τ, pres_O2)

Computes the CO2 compensation point Γ_star, Eq. C6, PALADYN (Willeit 2016).

compute_Λ_loc(vegcarbon_dynamics, LAI_b)

Computes the local litterfall rate Λ_loc based on the balanced Leaf Area Index LAI_b (assuming evergreen PFTs), Eq. 75, PALADYN (Willeit 2016).

compute_γv(veg_dynamics)

Computes the disturbance rateγv, Eq. 80, PALADYN (Willeit 2016).

compute_λ_NPP(vegcarbon_dynamics, LAI_b)

Computes λ_NPP,a factor determining the partitioning of NPP between increase of vegetation carbon of the existing vegetated area and spreading of the given PFT based on the balanced Leaf Area Index LAI_b, Eq. 74, PALADYN (Willeit 2016).

compute_λc(stomcond, vpd)

Computes the ratio of leaf-internal and air CO2 concentration λc, derived from the optimal stomatal conductance model (Medlyn et al. 2011), Eq. 71, PALADYN (Willeit 2016).

compute_ν_star(veg_dynamics, ν)

Computes ν_star which is the maximum between the current vegetation fraction ν and the seed fraction ν_seed [-], to ensure that a PFT is always seeded.

compute_ν_tendency(
    i, j, grid, fields,
    veg_dynamics::AbstractVegetationDynamics,
    vegcarbon::AbstractVegetationCarbonDynamics
)

Cell-level vegetation-fraction tendency computation used by vegetation dynamics. Implementations compute the local tendency value for ν at the given index i, j.

compute_ν_tendency(
    veg_dynamics,
    vegcarbon_dynamics,
    LAI_b,
    C_veg,
    ν
)

Computes the vegetation fraction tendency for a single PFT, Eq. 73, PALADYN (Willeit 2016).

convert_dt(Δt)

Convert Δts of type Period to a numeric value in seconds. Return Δt if already a number.

darcy_flux(i, j, k, grid, ψ, K)

Kernel function for computing the Darcy flux over layer faces from the pressure head ψ and hydraulic conductivity K.

daytime_length(i, j, grid, fields, ::AbstractAtmosphere{PR, <:LongShortWaveRadiation})

Retrieve the length of the day (in hours) at grid cell i, j. Defaults to a constant 12 hours if no input is provided.

debug!(debug::Bool)

Enable or disable global debug mode for Terrarium. Debug mode

debughook!(args)

Provides a "hook" for handling debug calls from relevant callsites. Default implementations for Field and NamedTuple (assumed to be of Fields) simply forward to nancheck!.

debugsite!(args)

Utility method that forwards args to debughook! if and only if debug mode is enabled. Debug mode is set by the global variable DEBUG which can be toggled by the user facing API debug!.

deduplicate(values)

Filter out duplicates from the given tuple. Note that this method is not type stable or allocation-free!

deduplicate_vars(vars::Tuple{Vararg{AbstractVariable}})

Type-stable equivalent of deduplicate for tuples of AbstractVariables.

default_dt(timestepper::AbstractTimeStepper)

Get the current timestep size for the time stepper.

density_soc(i, j, k, grid, fields, bgc)

Calculate the organic solid fraction based on the prescribed SOC and natural porosity/density of the organic material.

emissivity(i, j, grid, fields, ::AbstractAlbedo)

Return the current emissivity at the given indices.

Calculate the inverse enthalpy function given the internal energy, latent heat content, and heat capacity under the free water freezing characteristic.

explicit_step!(state, grid, timestepper, Δt)

Evaluate an explicit update u += ∂u∂t*Δt for all prognostic fields and their corresponding tendencies. By default, this is implemented as a simple Euler update u += dudt*Δt which can serve as a building block for more complex, multi-stage timesteppers. Where necessary, additional dispatches of explicit_step_kernel!(field, tendency, ::AbstractLandGrid, ::TimeStepper, Δt) can be defined to implement more specialized time-stepping schemes.

Accumulate tendency*Δt in the given prognostic field. This method can be overridden by specialized timestepping schemes as needed.

fastiterate(f!::F, iters::NTuple{N,Any}...) where {F,N}

Same as fastmap but simply invokes f! on each argument set without constructing a tuple.

fastmap(f::F, iter::NamedTuple...) where {F}

Same as map for NamedTuples but with guaranteed type stability. fastmap is a @generated function which unrolls calls to f into a loop-free tuple construction expression. All named tuples must have the same keys but in no particular order. The returned NamedTuple

fastmap(f::F, iter::NTuple{N,Any}...) where {F,N}

Same as map for NTuples but with guaranteed type stability. fastmap is a @generated function which unrolls calls to f into a loop-free tuple construction expression.

Compute the empirical field capacity of the soil.

findfirst_z(i, j, condition_func, z_nodes, field)

2D kernel function that finds the first coordinate in z_nodes where condition_func(field[i, j, k]). This implementation performs a linear scan over the z-axis and thus has time complexity O(N_z).

forcing(i, j, k, grid, clock, fields, evtr::AbstractEvapotranspiration, ::AbstractSoilHydrology)

Compute and return the evapotranspiration forcing for soil moisture at the given indices i, j, k. The ET forcing is just the surface_humidity_flux rescaled by the thickness of layer k.

forcing(i, j, k, grid, clock, fields, forcing::AbstractForcing, target::AbstractProcess, args...)

Return the value computed by the given Oceananigans forcing type, which should be an instance of either DiscreteForcing or ContinuousForcing. Note that target and additional args are only included for interface consistency and are not passed through to forcing.

get_albedo(seb)

Return the albedo parameterization associated with the surface energy balance.

get_biogeochemistry(soil)

Return the biogeochemistry scheme associated with soil.

get_closure(::SoilHydrology) where {NF}

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

get_constants(model::AbstractModel)::PhysicalConstants

Return the PhysicalConstants associated with the given model.

get_energy(ground)

Return the energy balance scheme associated with ground.

get_field(
    state,
    var::Terrarium.AbstractVariable{name}
) -> Any

Retrieves the Field from state matching the name of the given variable.

get_field_grid(grid::AbstractLandGrid)::Oceananigans.AbstractGrid

Returns the underlying Oceananigans grid type for Fields defined on the given land grid.

get_field_grid(grid)

Return the underlying Oceananigans grid stored in ColumnGrid.

get_fields(
    state,
    vars::Tuple{Vararg{Terrarium.AbstractVariable}}
) -> NamedTuple

Retrieves all Fields from state matching the names of the given variables.

get_fields(state, components; except)

Retrieves all non-tendency Fields from state defined on the given components.

get_fields(state, queries::Union{Symbol, Pair}...)

Retrieves fields with names given in queries and returns them in a NamedTuple. Each argument in queries can either be a Symbol corresponding to a field/variable defined in the namespace of state or a Pair{Symbol, Tuple} where the key is the child namespace and the value is a tuple of queries from that namespace.

# initialize model
state = initialize(model)
# get the temperature and saturation_water_ice fields
fields = get_fields(state, :temperature, :saturation_water_ice)
# extract temperature as well as variables from a namespace
nested_fields = get_fields(state, :temperature, :namespace => (:subvar1, :subvar2))

get_grid(model::AbstractModel)::AbstractLandGrid

Return the spatial grid associated with the given model.

get_hydraulic_properties(hydrology::SoilHydrology)

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

get_hydrology(ground)

Return the hydrology scheme associated with ground.

get_initializer(model::AbstractModel)::AbstractInitializer

Return the initializer associated with the given model.

get_radiative_fluxes(seb)

Return the radiative_fluxes component of the surface energy balance.

get_skin_temperature(seb)

Return the skin_temperature process from the surface energy balance.

get_spacing(spacing)

Return a Vector of vertical layer thicknesses according to the given discretization.

get_stratigraphy(ground)

Return the ground stratigraphy parameterization associated with ground.

get_swrc(::AbstractUnsatK)

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

get_swrc(hydrology::SoilHydrology)

Return the soil water retention curve from the hydraulic_properties associated with the given SoilHydrology configuration.

get_turbulent_fluxes(seb)

Return the turbulent_fluxes component of the surface energy balance.

Returns the appropriate workspec for the given AbstractField or based on the given field locations.

ground_evaporation_resistance_factor(i, j, grid, fields, :AbstractGroundEvaporationResistanceFactor, args...)

Compute the resistance factor against ground evaporation [-] based on the current state and implementation-specific process dependencies in args.

ground_heat_flux(i, j, grid, fields, ::AbstractSkinTemperature)

Return the current ground heat flux at the given indices.

ground_precipitation(i, j, grid, fields, ::AbstractCanopyInterception)

Compute or retrieve the current rate of precipitation reaching the ground [m/s].

heat_capacity(props, soil)

Compute the bulk heat capacity of the given soil volume.

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

hydraulic_conductivity(
    i,
    j,
    k,
    grid,
    fields,
    hydrology,
    strat,
    bgc
)

Compute the hydraulic conductivity at the center of the grid cell i, j, k.

initialize!(state, model::AbstractModel)

Initialize all variables defined in state which are defined by model. This defaults to simply calling initialize!(state, model, get_initializer(model)).

initialize!(state, model::AbstractModel, initializer::AbstractInitializer)

Initialize the model state variables using the corresponding initializer. This method only needs to be implemented if initialization routines are necessary in addition to direct field/variable initializers.

initialize!(state, grid, process::AbstractProcess, args...)

Initialize all state variables associated with the given process on grid. Implementations of AbstractProcess may define additional args that correspond to different process coupling interfaces.

Resets the simulation clock and calls initialize!(state, model) on the underlying model which should reset all state variables to their values as defiend by the model initializer.

initialize!(state, inits::NamedTuple{names}) -> Any

Initialize the state with Field initializers (any valid argument to set!) in inits.

initialize(::AbstractTimeStepper, model, state) where {NF}

Initialize and return the time stepping state cache for the given time stepper.

initialize(var::AbstractVariable, grid::AbstractLandGrid, clock::Clock, boundary_conditions::NamedTuple, fields::NamedTuple)

Initialize a Field on grid based on the given var metadata. The named tuple of boundary_conditions should follow the standard convention of (var1 = (; top, bottom, ...), var2 = (; top, bottom, ...)). If fields contains a Field matching the name of var, this field will be directly returned. Otherwise, the new Field is constructed using the given boundary_conditions with the other fields being made available to the constructor for auxiliary variables.

Creates and initializes a ModelIntegrator for the given model with the given clock state. This method allocates all necessary Fields for the state variables and calls initialize!(::ModelIntegrator). Note that this method is not type stable and should not be called in an Enzyme autodiff call.

initialize(
    process::AbstractProcess,
    grid::AbstractLandGrid{NF};
    clock = Clock(time=zero(NF)),
    input_variables = (),
    boundary_conditions = (;),
    initializers = (;),
    fields = (;)
) where {NF}

Initialize a StateVariables data structure containing Fields defined on the given grid for all variables defined by process. Any predefined boundary_conditions and fields will be passed through to initialize for each variable.

initialize(
    vars::Variables,
    grid::AbstractLandGrid{NF};
    clock::Clock = Clock(time=0.0),
    boundary_conditions = (;),
    initializers = (;),
    fields = (;)
) where {NF}

Initialize a StateVariables data structure containing Fields defined on the given grid for all variables in vars. Any predefined boundary_conditions and fields will be passed through to initialize for each variable.

initialize(
    process::AbstractProcess,
    grid::AbstractLandGrid{NF};
    clock = Clock(time=zero(NF)),
    input_variables = (),
    boundary_conditions = (;),
    initializers = (;),
    fields = (;)
) where {NF}

Initialize a StateVariables data structure containing Fields for all variables defined by model, initialized on its associated grid. Any predefined boundary_conditions and fields will be passed through to initialize for each variable.

initialize(
    vars::NamedTuple{names, <:Tuple{Vararg{AbstractVariable}}},
    grid::AbstractLandGrid,
    clock::Clock,
    boundary_conditions::NamedTuple,
    fields::NamedTuple
) where {names}

Initialize Fields on grid for each of the variables in the given named tuple vars. Any predefined boundary_conditions and fields will be passed through to initialize for each variable.

input(name, dims; default, units, domain, desc)

Convenience constructor method for InputVariable.

input_fields(state, components)

Retrieves all Fields from state corresponding to input variables defined on the given components.

Helper method that selects only input variables declared on obj.

invclosure!(state, model::AbstractModel)

Apply the inverse of all closure relations defined for the given model.

invclosure!(state, grid, [closure,] process, args...)

Apply the closure for process with the given grid and additional implementation-specific args. If closure is not specified, it is automatically inferred from first(closures(process)).

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

Computes saturation_water_ice from the current pressure_head state.

is_adaptive(timestepper::AbstractTimeStepper)

Return true if the given time stepper is adaptive, false otherwise.

is_initialized(timestepper::AbstractTimeStepper)

Return true if the timestepper is initialized, false otherwise.

latent_heat_flux(i, j, grid, fields, ::AbstractTurbulentFluxes)

Return the current latent heat flux at the given indices.

Calculate the unfrozen water content from the given internal energy, latent heat content, and saturation.

longwave_down(i, j, grid, fields, ::AbstractAtmosphere{NF, PR, <:LongShortWaveRadiation})

Retrieve or compute the incoming/downwelling longwave radiation at the current time step.

longwave_up(i, j, grid, fields, ::AbstractRadiativeFluxes)

Return the current outgoing (upwelling) longwave radiation at the given indices i, j.

merge_boundary_conditions(bcs::FieldBCs...)

Recursively merge an arbitrary number of field/variable boundary conditions.

merge_recursive(nt1::NamedTuple, nt2::NamedTuple)

Recursively merge two nested named tuples. This implementation is loosely based on the one in NamedTupleTools authored by Jeffrey Sarnoff.

min_zᵃᵃᶠ(i, j, k, grid, x)
min_zᵃᵃᶠ(i, j, k, grid, f, args...)

Computes the field or function at the vertical (z-axis) face by taking the min of the two adjacent vertical layers.

mineral_porosity(::AbstractSoilPorosity, texture::SoilTexture)

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

namespace(name, vars)

Convenience constructor method for variable Namespaces.

nancheck!(field)
nancheck!(field, name)

Check whether the given field has any NaN values using Diagnostics.hasnan and raise an error if NaNs are detected.

ntdiff(
    nt::NamedTuple,
    other::NamedTuple{excluded}
) -> NamedTuple

Filters out all entries from nt that exist in other; like setdiff but for NamedTuple.

Return the number of vertical layers defined by the given grid.

num_layers(spacing)

Return the number of vertical layers defined by this discretization.

organic_porosity(::AbstractSoilPorosity, texture::SoilTexture)

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

partial_pressure_CO2(pres, conc_co2)

Compute partial pressure of CO2 from surface pressure and CO2 concentration in Pa.

partial_pressure_O2(pres)

Compute partial pressure of oxygen from surface pressure in Pa.

piecewise_linear(knots; extrapolation)

Return a function f(z) that linearly interpolates between the given knots.

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

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

processes(obj::Union{AbstractCoupledProcesses, AbstractModel})

Return a tuple of AbstractProceses contained in the given model or coupled processes type. Note that this is a type-stable, @generated function that is compiled for each argument type.

prognostic(name, dims; units, closure, domain, desc)

Convenience constructors for PrognosticVariable.

prognostic_fields(state, components)

Retrieves all Fields from state corresponding to prognostic variables defined on the given components.

Helper method that selects only prognostic variables declared on obj.

psychrometric_constant(c::PhysicalConstants, p)

Calcualte the psychrometric constant at the given atmospheric pressure p.

rainfall(i, j, grid, fields, ::AbstractAtmosphere{NF, <:RainSnow})

Retrieve or compute the liquid precipitation (rainfall) at the current time step.

relative_to_specific_humidity(r_h, pr, Tair)

Derives specific humidity from measured relative humidity, air pressure, and air temperature.

Reset all tendencies in state to zero.

root_density(::AbstractRootDistribution, z, args...)

Compute the continuous density function of the given root distirbution as a function of depth z. Note that this function must be integrated and normalized over the root zone in order to obtain the cumulative root fraction in each soil layer.

root_density(
    rd::StaticExponentialRootDistribution{NF},
    z
) -> Any

Compute the continuous density function of the root distirbution as a function of depth z.

Returns a FunctionField that lazily computes the static root distribution on a 1D column grid.

safediv(x, y)

Evaluates x / (y + eps(NF)) if and only if y != zero(y); returns Inf otherwise.

Compute hydraulic conductivity at saturation.

saturation_canopy_water(i, j, grid, fields, ::AbstractCanopyInterception)

Compute or retrieve the current canopy water saturation fraction [-].

saturation_vapor_pressure(T, a₁, a₂, a₃)

August-Roche-Magnus equation for saturation vapor pressure at temperature T with empirical coefficients a₁, a₂, and a₃.

saturation_vapor_pressure(T, Ts=T)

Saturation vapor pressure at the given temperature T, accounting for both frozen (T < 0°C) and unfrozen conditions.

Coefficients taken from Alduchov and Eskridge (1997).

Return the number of seconds per day in the given number format.

Return the number of seconds per hour in the given number format.

sensible_heat_flux(i, j, grid, fields, ::AbstractTurbulentFluxes)

Return the current sensible heat flux at the given indices.

shortwave_down(i, j, grid, fields, ::AbstractAtmosphere{NF, PR, <:LongShortWaveRadiation})

Retrieve or compute the incoming/downwelling shortwave radiation at the current time step.

shortwave_up(i, j, grid, fields, ::AbstractRadiativeFluxes)

Return the current outgoing (upwelling) shortwave radiation at the surface.

skin_temperature(i, j, grid, fields, ::AbstractSkinTemperature)

Return the current skin temperature at the given indices.

snowfall(i, j, grid, fields, ::AbstractAtmosphere{NF, <:RainSnow})

Retrieve or compute the frozen precipitation (snowfall) at the current time step.

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.

soil_matrix(
    i,
    j,
    k,
    grid,
    fields,
    strat::Terrarium.AbstractStratigraphy,
    bgc::Terrarium.AbstractSoilBiogeochemistry
) -> MineralOrganic

Compute and return the soil solid matrix at index i, j, k on grid. The default implementation assumes a simple MineralOrganic parameterization of the solid material.

soil_moisture_limiting_factor(
    _::FieldCapacityLimitedPAW,
    grid,
    clock,
    fields
) -> Field{LX, LY, LZ, O, G, I, D, T, B, Oceananigans.Fields.FieldStatus{Float64}} where {LX, LY, LZ, O, G, I, D, T, B}

Field constructor for the soil moisture limiting factor. Returns a derived Field that calculates the integral of W(z) * r(z) where W is the water availability coefficient and r is the root fraction.

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.

soil_volume(i, j, k, grid, fields, ::AbstractStratigraphy, args...)

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

soil_volume(i, j, k, grid, fields, strat, hydrology, bgc)

Construct a SoilVolume object summarizing the material composition of the soil volume at the given indices i, j, k on grid.

specific_humidity(i, j, grid, fields, ::PrescribedAtmosphere{PR, IR, <:SpecificHumidity})

Retrieve or compute the specific_humidity at the current time step.

stefan_boltzmann(c::PhysicalConstants, T, ϵ)

Stefan-Boltzmann law $M = \epsilon \sigma T^4$ where T is the surface temperature in Kelvin and ϵ is the emissivity.

surface_humidity_flux(i, j, grid, fields, ::AbstractEvapotranspiration)

Compute the surface humidity flux [m/s] at cell i, j based on the current state.

surface_net_radiation(i, j, grid, fields, ::AbstractRadiativeFluxes)

Return the current surface net radiation at the given indices i, j.

tendency(var)

Creates an AuxiliaryVariable for the tendency of a prognostic variable with the given name, dimensions, and physical units. This constructor is primarily used internally by other constructors and does not usually need to be called by implementations of variables.

tendency_fields(state, components)

Retrieves all Fields from state corresponding to tendencies defined on the given components.

timestep!(integrator::ModelIntegrator, timestepper::AbstractTimeStepper, Δt)

Advance prognostic variables of the integrator model by one time step based on the current state, or by Δt units of time.

timestep!(state, model::AbstractModel, timestepper::AbstractTimeStepper, Δt)

Apply any necessary corrections or model-specific time stepping logic after applying timestepper to the prognostic state variables defined by model.

timestep!(integrator; finalize)

Advance the model forward by one timestep with optional timestep size Δt. If finalize = true, compute_auxiliary! is called after the time step in order to update the values of auxiliary/diagnostic variables.

tuplejoin()

Concatenate one or more tuples together.

update_inputs!(fields, _, _)

Updates the values of input variables stored in fields from the given input source. Default implementation simply returns nothing.

Update input variables from the given input sources.

vapor_pressure_to_specific_humidity(e, p, ε)

Convert the vapor pressure e to specific humidity at the given pressure p based on the molecular weight ratio ε.

var(name, dims)
var(name, dims, units)

Convenience constructor for Variable.

vardims(var)

Retrieve the grid dimensions on which this variable is defined.

vardims(_)

Infer the appropriate VarDims from the given Field.

variables(model::AbstractModel)

Return a Tuple of AbstractVariables (i.e. PrognosticVariable, AuxiliaryVariable, etc.) defined by the model or process.

variables(_)

Returns a tuple of Symbols corresponding to variable names supported by this InputSource.

Defines temperature as the closure variable for SoilEnergyTemperatureClosure.

Alias for Variables(vars...)

State variables for SoilHydrology processes.

varname(_)

Retrieve the name of the given variable or closure. For closure relations, varname should return the name of the variable returned by the closure relation.

varunits(var)

Retrieve the physical units for the given variable.

volumetric_fractions(soil::SoilVolume) -> 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 correspodns to the volumetric fractions defined by the solid phase soil.solid.

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.

Compute the empirical wilting point of the soil.

windspeed(i, j, grid, fields, ::PrescribedAtmosphere)

Retrieve or compute the windspeed at the current time step.

Type alias for a UnionAll over DiscreteForcing and ContinuousForcing types from Oceananigans.

Alias for union type of FieldBoundaryConditions or a named tuple of BoundaryConditions with keys corresponding to boundary locations (i.e. top, bottom, etc.)

Alias for Union{Nothing, T} indicating that an argument or field of type T is optional and can be replaced with nothing.