API Reference

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

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, albedo::ConstantAlbedo) -> Any

Return the surface albedo at grid point i, j.

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, grid, closure::AbstractClosureRelation, process, args...)

Apply closure for process on the given grid with additional implementation-specific args.

closure!(state, grid, proc::AbstractProcess, args...)

Apply the forward closure mappings for the process proc on the given grid with additional implementation-specific args defined by the coupling interface for the process type. The default implementation calls invclosure! with args for each closure returned by closures.

closure!(state, model::AbstractModel)

Apply all closure relations defined for the given model.

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(proc::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::LUEPhotosynthesis{NF},
    swdown,
    LAI
) -> Any

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::LUEPhotosynthesis{NF},
    c_1,
    c_2,
    APAR,
    Vc_max,
    β
) -> Any

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(_::LUEPhotosynthesis{NF}, An) -> Any

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

compute_JE_JC(
    photo::LUEPhotosynthesis{NF},
    c_1,
    c_2,
    APAR,
    Vc_max
) -> Tuple{Any, Any}

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_LAI_b(vegcarbon_dynamics, C_veg)

Computes LAI_b, the balanced Leaf Area Index based on the vegetation carbon pool C_veg (assuming with bwl = 1), Eqs. 76-79, PALADYN (Willeit 2016).

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²/s].

compute_PAR(photo::LUEPhotosynthesis{NF}, swdown) -> Any

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²/s].

compute_Rd(photo::LUEPhotosynthesis, Vc_max, β) -> Any

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²/s].

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::LUEPhotosynthesis{NF},
    c_1,
    PAR,
    Kc,
    Ko,
    Γ_star,
    pres_i,
    pres_O2
) -> Any

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_assimilation_factors(
    photo::LUEPhotosynthesis{NF},
    constants::PhysicalConstants{NF},
    Γ_star,
    T_stress,
    Kc,
    Ko,
    pres_i,
    pres_O2
) -> Tuple{Any, Any}

Computes factors for light-limited c_1 [gC/mol] and RuBisCO-limited c_2 [dimensionless] assimilation. Follows Eq. C4-C5 from PALADYN (Willeit 2016) and Haxeltine & Prentice (1996).

• c1: quantum efficiency × temperature factor × carbon mass / denominator, used in JE = c1 × APAR
• c2: dimensionless coefficient relating enzyme capacity to assimilation, used in JC = c2 × Vc_max

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!(
    out,
    i,
    j,
    grid,
    fields,
    autoresp::Terrarium.AbstractAutotrophicRespiration,
    args...
) -> Any

Mutating wrapper for compute_autotrophic_respiration that stores the results in out.

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,
    grid,
    seb::SurfaceEnergyBalance,
    atmos::Terrarium.AbstractAtmosphere,
    constants::PhysicalConstants
)
compute_auxiliary!(
    state,
    grid,
    seb::SurfaceEnergyBalance,
    atmos::Terrarium.AbstractAtmosphere,
    constants::PhysicalConstants,
    hydrology::Union{Nothing, Terrarium.AbstractSurfaceHydrology},
    args...
)

compute_auxiliary!(
    state,
    grid,
    evap::PALADYNCanopyEvapotranspiration,
    canopy_interception::Terrarium.AbstractCanopyInterception,
    atmos::Terrarium.AbstractAtmosphere,
    constants::PhysicalConstants
)
compute_auxiliary!(
    state,
    grid,
    evap::PALADYNCanopyEvapotranspiration,
    canopy_interception::Terrarium.AbstractCanopyInterception,
    atmos::Terrarium.AbstractAtmosphere,
    constants::PhysicalConstants,
    soil::Union{Nothing, Terrarium.AbstractSoil}
)

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_auxiliary!(
    state,
    grid,
    evap::GroundEvaporation,
    atmos::Terrarium.AbstractAtmosphere,
    constants::PhysicalConstants
)
compute_auxiliary!(
    state,
    grid,
    evap::GroundEvaporation,
    atmos::Terrarium.AbstractAtmosphere,
    constants::PhysicalConstants,
    soil::Union{Nothing, Terrarium.AbstractSoil}
)

compute_auxiliary!(
    state,
    grid,
    rad::DiagnosedRadiativeFluxes,
    seb::Terrarium.AbstractSurfaceEnergyBalance,
    atmos::Terrarium.AbstractAtmosphere,
    consts::PhysicalConstants,
    args...
)

compute_auxiliary!(
    state,
    grid,
    tur::DiagnosedTurbulentFluxes,
    seb::Terrarium.AbstractSurfaceEnergyBalance,
    atmos::Terrarium.AbstractAtmosphere,
    constants::PhysicalConstants,
    args...
)

compute_auxiliary!(
    state,
    grid,
    runoff::DirectSurfaceRunoff,
    canopy_interception::Terrarium.AbstractCanopyInterception,
    soil::Terrarium.AbstractSoil,
    args...
)

compute_auxiliary!(
    state,
    grid,
    paw::FieldCapacityLimitedPAW,
    soil::Terrarium.AbstractSoil,
    args...
) -> Any

compute_auxiliary!(
    state,
    grid,
    skinT::ImplicitSkinTemperature,
    seb::Terrarium.AbstractSurfaceEnergyBalance,
    args...
)

compute_auxiliary!(
    state,
    grid,
    photo::LUEPhotosynthesis,
    stomcond::Terrarium.AbstractStomatalConductance,
    atmos::Terrarium.AbstractAtmosphere,
    constants::PhysicalConstants,
    args...
)

compute_auxiliary!(
    state,
    grid,
    stomcond::MedlynStomatalConductance,
    photo::LUEPhotosynthesis,
    atmos::Terrarium.AbstractAtmosphere,
    constants::PhysicalConstants,
    args...
)

compute_auxiliary!(
    state,
    grid,
    autoresp::PALADYNAutotrophicRespiration,
    vegcarbon::Terrarium.AbstractVegetationCarbonDynamics,
    atmos::Terrarium.AbstractAtmosphere
)

compute_auxiliary!(
    state,
    grid,
    canopy_interception::PALADYNCanopyInterception,
    atmos::Terrarium.AbstractAtmosphere
)

compute_auxiliary!(
    state,
    grid,
    vegcarbon_dynamics::PALADYNCarbonDynamics,
    args...
)

compute_auxiliary!(state, grid, phenol::PALADYNPhenology)

compute_auxiliary!(
    state,
    grid,
    veg_dynamics::PALADYNVegetationDynamics,
    args...
)

compute_auxiliary!(
    state,
    grid,
    rad::PrescribedRadiativeFluxes,
    seb::Terrarium.AbstractSurfaceEnergyBalance,
    atmos::Terrarium.AbstractAtmosphere,
    args...
)

compute_auxiliary!(
    state,
    grid,
    energy::SoilEnergyBalance,
    soil::Terrarium.AbstractSoil,
    args...
)

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

compute_auxiliary!(
    state,
    grid,
    hydrology::SurfaceHydrology,
    atmos::Terrarium.AbstractAtmosphere,
    constants::PhysicalConstants,
    soil::Terrarium.AbstractSoil
)

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

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

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

compute_energy_tendencies!(
    tendencies,
    i,
    j,
    k,
    grid,
    fields,
    energy::SoilEnergyBalance,
    args...
)

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

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

compute_energy_tendency(
    i,
    j,
    k,
    grid,
    fields,
    energy::SoilEnergyBalance{NF, var"#s107", EnergyClosure, ThermalProps} where {var"#s107"<:Terrarium.ExplicitTwoPhaseHeatConduction, EnergyClosure<:Terrarium.AbstractSoilEnergyClosure, ThermalProps<:(SoilThermalProperties{NF})},
    hydrology::Terrarium.AbstractSoilHydrology,
    strat::Terrarium.AbstractStratigraphy,
    bgc::Terrarium.AbstractSoilBiogeochemistry
) -> Any

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!(
    state,
    grid,
    skinT::Terrarium.AbstractSkinTemperature,
    seb::Terrarium.AbstractSurfaceEnergyBalance
)

Compute ground_heat_flux as the residual R_\text{net} - H_s - H_l.

compute_ground_heat_flux(
    i,
    j,
    grid,
    fields,
    skinT::Terrarium.AbstractSkinTemperature,
    _::Terrarium.AbstractRadiativeFluxes,
    _::Terrarium.AbstractTurbulentFluxes
) -> Any

Compute the ground heat flux from the surface net radiation and sensible/latent heat flux at grid cell i, j.

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_gw_can(
    stomcond::MedlynStomatalConductance{NF},
    photo::LUEPhotosynthesis{NF},
    vpd,
    An,
    co2,
    LAI,
    β
) -> Any

Compute canopy-level water conductance [m/s] from the Medlyn et al. (2011) optimal stomatal conductance model. Includes minimum conductance and light extinction effects based on LAI, scaled by soil moisture factor β.

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!(state, grid, hydrology::SoilHydrology, soil::AbstractSoil, args...)

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

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

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_kinetic_parameters(
    photo::LUEPhotosynthesis{NF},
    T_air
) -> Tuple{Any, Any, Any}

Computes kinetic parameters τ, Kc, Ko based on temperature using Q10 temperature response. Follows enzyme kinetics from Haxeltine & Prentice (1996), Appendix C.

• τ: Rubisco specificity factor (CO₂ to O₂ carboxylation ratio), dimensionless
• Kc: Michaelis-Menten constant for CO₂ [Pa]
• Ko: Michaelis-Menten constant for O₂ [Pa]

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_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_phenology!(
    out,
    i,
    j,
    grid,
    fields,
    phenol::PALADYNPhenology
) -> Any

Mutating wrapper for compute_phenology that stores the result in out.

compute_phenology(
    i,
    j,
    grid,
    fields,
    phenol::PALADYNPhenology
) -> Tuple{Any, Any}

Compute the phenology factor and instantaneous leaf area index (LAI).

compute_phenology_factor(phenol)

Computes the phenology factor ϕ [-].

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!(
    out,
    i,
    j,
    grid,
    fields,
    photo::LUEPhotosynthesis,
    atmos::Terrarium.AbstractAtmosphere,
    constants::PhysicalConstants
) -> Any

Calls compute_photosynthesis and stores the results in out.

compute_photosynthesis(
    i,
    j,
    grid,
    fields,
    photo::LUEPhotosynthesis,
    atmos::Terrarium.AbstractAtmosphere,
    constants::PhysicalConstants
) -> Tuple{Any, Any, Any}

Compute photosynthesis, leaf respiration, and gross primary production at a single grid point. Returns instantaneous rates in [gC/m²/s] and [kgC/m²/s] for integration by the timestepper.

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_plant_available_water!(
    out,
    i,
    j,
    k,
    grid,
    fields,
    paw::FieldCapacityLimitedPAW{NF},
    strat::Terrarium.AbstractStratigraphy,
    hydrology::Terrarium.AbstractSoilHydrology,
    bgc::Terrarium.AbstractSoilBiogeochemistry,
    args...
) -> Any

Mutating wrapper for compute_plant_available_water that stores the result in out.

compute_plant_available_water(
    i,
    j,
    k,
    grid,
    fields,
    paw::FieldCapacityLimitedPAW{NF},
    strat::Terrarium.AbstractStratigraphy,
    hydrology::Terrarium.AbstractSoilHydrology,
    bgc::Terrarium.AbstractSoilBiogeochemistry
) -> Any

Compute the plant avaialble water given the current soil stratigraphy, hydrology, and biogeochemistry state in fields.

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::LUEPhotosynthesis, λc, pres_a) -> Any

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

compute_radiative_fluxes!(
    out,
    i,
    j,
    grid,
    fields,
    rad::PrescribedRadiativeFluxes,
    atmos::Terrarium.AbstractAtmosphere,
    args...
) -> Any

Compute net radiation and store in auxiliary fields at a grid point.

compute_resp10(autoresp)

Computes resp10

compute_respiration_assimilation(
    photo::LUEPhotosynthesis{NF},
    constants::PhysicalConstants{NF},
    T_air,
    swdown,
    pres,
    co2,
    LAI,
    λc,
    β
) -> Tuple{Any, Any}

Compute and return leaf respiration [gC/m²/s] and net assimilation [gC/m²/s] rates.

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

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(
    i,
    j,
    grid,
    fields,
    skinT::ImplicitSkinTemperature
) -> Any

Estimate the skin temperature from the current ground_heat_flux at grid cell i, j.

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_stomatal_conductance!(
    out,
    i,
    j,
    grid,
    fields,
    stomcond::MedlynStomatalConductance{NF},
    photo::LUEPhotosynthesis{NF},
    atmos::Terrarium.AbstractAtmosphere,
    constants::PhysicalConstants,
    args...
) -> Any

Calls compute_stomatal_conductance and stores the result in out.

compute_stomatal_conductance(
    i,
    j,
    grid,
    fields,
    stomcond::MedlynStomatalConductance{NF},
    photo::LUEPhotosynthesis{NF},
    atmos::Terrarium.AbstractAtmosphere,
    constants::PhysicalConstants,
    args...
) -> Tuple{Any, Any}

Compute stomatal conductance (gwcan) and leaf-to-air CO₂ ratio (λc) at a grid point. Returns tuple (gwcan, λc) for use in photosynthesis and transpiration calculations.

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

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_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_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_surface_upwelling_radiation(
    i,
    j,
    grid,
    fields,
    rad::PrescribedRadiativeFluxes,
    args...
) -> NamedTuple{(:surface_shortwave_up, :surface_longwave_up), <:Tuple{Any, Any}}

Compute upwelling shortwave and longwave radiation at a grid point.

compute_temperature_stress(
    photo::LUEPhotosynthesis{NF},
    T_air
) -> Any

Computes the temperature stress factor T_stress based on the air temperature.

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_tendencies!(
    state,
    grid,
    canopy_interception::PALADYNCanopyInterception,
    evapotranspiration::Terrarium.AbstractEvapotranspiration,
    args...
)

compute_tendencies!(
    state,
    grid,
    vegcarbon_dynamics::PALADYNCarbonDynamics,
    args...
)

compute_tendencies!(
    state,
    grid,
    veg_dynamics::PALADYNVegetationDynamics,
    vegcarbon_dynamics::PALADYNCarbonDynamics,
    args...
)

compute_tendencies!(
    state,
    grid,
    energy::SoilEnergyBalance,
    soil::Terrarium.AbstractSoil,
    args...
)

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

compute_tendencies!(
    state,
    grid,
    hydrology::SurfaceHydrology,
    args...
)

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

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

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

compute_thermal_conductivity(
    i,
    j,
    k,
    grid,
    fields,
    energy::SoilEnergyBalance,
    hydrology::Terrarium.AbstractSoilHydrology,
    strat::Terrarium.AbstractStratigraphy,
    bgc::Terrarium.AbstractSoilBiogeochemistry
) -> Any

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_auxiliary!(
    out,
    i,
    j,
    grid,
    fields,
    vegcarbon_dynamics::PALADYNCarbonDynamics
)

Mutating wrapper for compute_LAI_b that stores the result in out.balanced_leaf_area_index.

compute_veg_carbon_tendencies!(
    tend,
    i,
    j,
    grid,
    fields,
    vegcarbon_dynamics::PALADYNCarbonDynamics
)

Calls compute_veg_carbon_tendency and stores the result in out.

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_veg_carbon_tendency(
    i,
    j,
    grid,
    fields,
    vegcarbon_dynamics::PALADYNCarbonDynamics
) -> Any

Compute the tendency for the carbon vegetation pool given fields LAI_b and NPP.

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

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

compute_Γ_star(
    photo::LUEPhotosynthesis{NF},
    τ,
    pres_O2
) -> Any

Computes the CO₂ compensation point Γ_star [Pa]. The intercellular CO₂ partial pressure at which gross photosynthesis equals respiration. Follows 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 of the current vegetation fraction ν and the seed fraction ν_seed [-], to ensure that a PFT is always seeded.

compute_ν_tendencies!(
    tend,
    i,
    j,
    grid,
    fields,
    veg_dynamics::PALADYNVegetationDynamics,
    vegcarbon_dynamics::PALADYNCarbonDynamics
) -> Any

Mutating wrapper for compute_ν_tendency that stores the result in tend.

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(
    i,
    j,
    grid,
    fields,
    veg_dynamics::PALADYNVegetationDynamics,
    vegcarbon_dynamics::PALADYNCarbonDynamics
) -> Any

Compute vegetation area fraction tendency at a single grid point from NPP-productivity and disturbance rates.

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

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::AbstractSoilBiogeochemistry)

Compute or return the soil organic carbon density at grid cell index i, j, k.

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.

diffusive_heat_flux(i, j, k, grid, fields, args...) -> Any

drag_coefficient(i, j, grid, fields, aero::AbstractAerodynamics)

Compute the bulk drag coefficient for heat and moisture transfer at grid cell i, j.

emissivity(
    i,
    j,
    grid,
    fields,
    albedo::ConstantAlbedo
) -> Any

Return the surface emissivity at grid point i, j.

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(
    hydrology::SoilHydrology
) -> Terrarium.AbstractSoilWaterClosure

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::AbstractSoilHydrology)

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

get_hydraulic_properties(
    hydrology::SoilHydrology
) -> Terrarium.AbstractSoilHydraulics

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

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

get_swrc(hydrology::AbstractSoilHydrology)

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

get_thermal_properties(energy::AbstractSoilEnergyBalance)

Return the thermal properites associated with the given soil energy balance process.

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.

initialize!(
    state,
    grid,
    energy::SoilEnergyBalance,
    soil::Terrarium.AbstractSoil,
    constants::PhysicalConstants,
    args...
)

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

initialize!(fields, _::InputSource, clock)

Initializes the input source. Default implementation does nothing.

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 input variables from the given input sources.

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

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

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

initialize(
    var::AuxiliaryVariable,
    grid::Terrarium.AbstractLandGrid,
    clock::Clock,
    boundary_conditions::NamedTuple,
    fields::NamedTuple
) -> Any

Initialize a Field on grid for the given AuxiliaryVariable.

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

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

initialize(
    var::Terrarium.AbstractVariable,
    grid::Terrarium.AbstractLandGrid,
    clock::Clock,
    boundary_conditions::NamedTuple,
    fields::NamedTuple
) -> Any

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.

initialize(
    model::Terrarium.AbstractModel{NF, Grid} where Grid<:(Terrarium.AbstractLandGrid{NF}),
    timestepper::Terrarium.AbstractTimeStepper,
    inputs::InputSource...;
    clock,
    boundary_conditions,
    initializers,
    fields
) -> ModelIntegrator{_A, Arch, _B, _C, _D, StateVars, @NamedTuple{}} where {_A, Arch<:Oceananigans.Architectures.AbstractArchitecture, _B<:Terrarium.AbstractLandGrid{_A, Arch}, _C<:Terrarium.AbstractTimeStepper{_A}, _D<:Terrarium.AbstractModel{_A, _B}, StateVars<:(StateVariables{NF, _A, _B, _C, _D, _E, _F, _G, _H, _I, _J, ClockType} where {NF, _A, _B, _C, _D, _E, _F, _G, _H, _I, _J, ClockType<:(Clock{_A, Float64, Int64, Int64} where _A)})}

Creates and initializes a ModelIntegrator for the given model and timestepper with input variables populated by the given inputs. This method allocates all necessary Fields for the state variables and subsequently calls initialize!(::ModelIntegrator).

Note that this method is not type stable and thus should not be called from Enzyme autodiff. To reinitialize the model for an existing state, use initialize!(state, model).

See the docstring for initialize(::AbstractModel) for further details.

initialize(
    process::Terrarium.AbstractProcess{NF},
    grid::Terrarium.AbstractLandGrid{NF};
    clock,
    input_variables,
    boundary_conditions,
    initializers,
    fields
) -> StateVariables{NF, _A, _B, _C, _D, _E, _F, _G, _H, _I, _J, ClockType} where {NF, _A, _B, _C, _D, _E, _F, _G, _H, _I, _J, ClockType<:(Clock{_A, Float64, Int64, Int64} where _A)}

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::Terrarium.Variables,
    grid::Terrarium.AbstractLandGrid{NF};
    clock,
    boundary_conditions,
    initializers,
    fields
) -> StateVariables{NF, _A, _B, _C, _D, _E, _F, _G, _H, _I, _J, Clock{Float64, Float64, Int64, Int64}} where {NF, _A, _B, _C, _D, _E, _F, _G, _H, _I, _J}

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(
    model::Terrarium.AbstractModel{NF, Grid} where Grid<:(Terrarium.AbstractLandGrid{NF});
    clock,
    input_variables,
    boundary_conditions,
    initializers,
    fields
) -> StateVariables{NF, _A, _B, _C, _D, _E, _F, _G, _H, _I, _J, ClockType} where {NF, _A, _B, _C, _D, _E, _F, _G, _H, _I, _J, ClockType<:(Clock{_A, Float64, Int64, Int64} where _A)}

Initialize a StateVariables data structure containing Fields for all variables defined by model defined on its associated grid. The clock specifies the initial simulation time and is mutated on each time step. User-specified boundary_conditions and initializers can be provided as NamedTuples with keys corresponding to the names of state variables to which they should be applied. If the state variables are defined within namespaces, the given NamedTuple must follow the same structure. The fields argument allows for manual preconstruction of Fields for the named state variables.

initialize(
    vars::NamedTuple{names, <:Tuple{Vararg{Terrarium.AbstractVariable}}},
    grid::Terrarium.AbstractLandGrid,
    clock::Clock,
    boundary_conditions::NamedTuple,
    fields::NamedTuple
) -> @NamedTuple{}

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, grid, closure::AbstractClosureRelation, process::AbstractProcess, args...)

Apply the inverse of closure for the process proc on the given grid with additional implementation-specific args defined by the coupling interface for the process type.

invclosure!(state, grid, proc::AbstractProcess, args...)

Apply the inverse closure mappings for the process proc on the given grid with additional implementation-specific args defined by the coupling interface for the process type. The default implementation calls invclosure! with args for each closure returned by closures.

invclosure!(state, model::AbstractModel)

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

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.

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

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

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.

organic_fraction(::AbstractSoilMatrix)

Return the SoilTexture describing the mineral component of the soil matrix.

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_fraction(::AbstractSoilMatrix)

Return the fraction of the soil matrix that is organic material.

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

Compute the organic fraction of solid material in the soil volume at index i, j, k.

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

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

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

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 SoilVolume describing 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_excess_water(i, j, k, grid, fields, ::AbstractSoilHydrology)

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

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::ModelIntegrator; 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, _::InputSource, _::Clock)

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.

update_skin_temperature!(
    state,
    grid,
    skinT::ImplicitSkinTemperature
)

Update skin_temperature according to the current state of ground_heat_flux.

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)
variables(process::AbstractProcess)

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

variables(
    _::InputSource
) -> Tuple{InputVariable{_A, VD, UT, _B, DomainSets.RealLine{Float64}, Nothing} where {_A, VD<:Terrarium.VarDims, UT<:Unitful.Units, _B<:Terrarium.Variable{_A, VD, UT}}}

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

Defines temperature as the closure variable for SoilEnergyTemperatureClosure.

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

Default implementation of variables for composite AbstractModel and AbstractCoupledProcesses types that automatically collects all variables from all processes defined as properties/fields on the given obj.

Alias for Variables(vars...)

varname(_::InputSource{NF, name}) -> Any

Returns the name of the input source.

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

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

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

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{Model})(grid::AbstractLandGrid, args...; kwargs...) where {Model <: AbstractModel}

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.

Field(ring_field, grid; default_value)

Converts a RingGrids.Field to an Oceananigans Field using the given ColumnRingGrid. Only masked grid points are copied to the Oceananigans field. For 2D RingGrids fields, returns a 2D Oceananigans field. For 3D fields, returns a 3D field.

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.

abstract type AbstractAerodynamics{NF}

Base type for aerodynamic parameterizations that compute the bulk drag coefficient for turbulent heat and moisture exchange between the land surface and atmosphere.

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 AbstractHumidity

Base type for representations of near-surface atmospheric humidity. Subtypes define which form of humidity (e.g. specific or relative humidity) is used as input.

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

Base type for surface hydrology models.

abstract type AbstractIncomingRadiation

Base type for representations of downwelling (incoming) radiation. Subtypes define which spectral components are provided as inputs (e.g. split into shortwave and longwave).

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 AbstractPrecipitation

Base type for representations of atmospheric precipitation. Subtypes define which variables describe the precipitation input (e.g. rain and snow as separate fields).

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 AbstractSoilBiogeochemistry{NF} <: Terrarium.AbstractProcess{NF}

Base type for soil biogeochemistry process implementations.

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

Base type for soil energy balance process implementations. Subtypes should define state variables for soil temperature, internal_energy, and any other relevant thermal properties or state variables.

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 AbstractSoilHydrology{NF} <: Terrarium.AbstractProcess{NF}

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

abstract type AbstractSoilMatrix{NF}

Base type for representing the solid material composition of the soil.

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

abstract type AbstractVerticalFlow

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 ConstantEvaporationResistanceFactor{NF} <: Terrarium.AbstractGroundEvaporationResistanceFactor

Represents a spatiotemporally constant, prescribed ground evaporation resistance factor.

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

Initializer for soil water/ice sets the saturation profile to a constant value.

Properties:

• sat::Any

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.

struct ConstantSoilTemperature{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.

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} = \boldsymbol{\nabla} \cdot \left[ \kappa(T) \boldsymbol{\nabla}_x T(x,t) \right]\]

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\left(\frac{\theta_{\text{w},i} - \theta_{\text{wp},i}}{\theta_{\text{fc},i} - \theta_{\text{wp},i}} , 1\right)\]

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, name, VD<:Terrarium.VarDims, FS<:(Oceananigans.Fields.AbstractField{LX, LY, LZ, G, NF} where {LX, LY, LZ, G}), UT} <: InputSource{NF, name}

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

struct FieldTimeSeriesInputSource{NF, name, VD<:Terrarium.VarDims, FTS<:(FieldTimeSeries{LX, LY, LZ, TI, K, I, D, G, NF} where {LX, LY, LZ, TI, K, I, D, G}), UT} <: InputSource{NF, name}

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

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

Simple forward Euler time stepping scheme.

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

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_s$ satisfying:

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

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_g$ 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, name}

Base type for input data sources. Implementations of InputSource are free to load data from any arbitrary backend. They expect an initialize!(fields, ::InputSource) that is called once at model initialization and an update_inputs!(fields, ::InputSource, ::Clock) method that is called at every time step. Both default to doing nothing. Implementations should additionally provide a constructor as a dispatch of InputSource.

The type argument NF corresponds to the numeric type of the input data, name to its name that's also used in its variables definition.

InputSource(
    grid::Terrarium.AbstractLandGrid{NF},
    field::Oceananigans.Fields.AbstractField{LX, LY, LZ, G, NF} where {LX, LY, LZ, G};
    name,
    units
)

Create a FieldInputSource with the given grid and input variable fields. Use it for static input fields.

InputSource(
    grid::ColumnRingGrid{NF},
    ring_field::RingGrids.AbstractField;
    name,
    units
)

Convenience function to create a FieldInputSource from a RingGrids.Field. Converts the RingGrids field to an Oceananigans field and then creates the input source.

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 a spatially varying input (e.g. forcing) variable with the given name and spatial dims. Input variables can also be made to vary in time through the use of InputSources.

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

\[k = \left[\sum_{i=1}^N θᵢ\sqrt{kᵢ}\right]^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 mechanistic approach of Haxeltine and Prentice (1996). Computes instantaneous photosynthetic rates as differential equations that are integrated over arbitrary timesteps by the timestepper.

Authors: Maha Badri and Matteo Willeit

Properties:

• τ25::Any: Rubisco specificity factor at 25°C [dimensionless]. Ratio of carboxylation to oxygenation rates.

• Kc25::Any: Michaelis-Menten constant for CO₂ at 25°C [Pa]. PALADYN value for needleleaf trees.

• Ko25::Any: Michaelis-Menten constant for O₂ at 25°C [Pa]. PALADYN value for needleleaf trees.

• q10_τ::Any: Q10 temperature sensitivity for τ [dimensionless]. Controls temperature dependence of specificity.

• q10_Kc::Any: Q10 temperature sensitivity for Kc [dimensionless]. Controls temperature dependence of CO₂ affinity.

• q10_Ko::Any: Q10 temperature sensitivity for Ko [dimensionless]. Controls temperature dependence of O₂ affinity.

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

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

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

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

• T_CO2_high::Any: Upper temperature threshold for CO₂/O₂ specificity factor [°C]. Above this, photosynthesis rapidly declines. PFT-specific, needleleaf tree value.

• T_CO2_low::Any: Lower temperature threshold for CO₂/O₂ specificity factor [°C]. Below this, photosynthesis rapidly declines. PFT-specific, needleleaf tree value.

• T_photos_high::Any: Upper temperature threshold for light-limited photosynthesis rate [°C]. Peak photosynthesis capacity. PFT-specific, needleleaf tree value.

• T_photos_low::Any: Lower temperature threshold for light-limited photosynthesis rate [°C]. Minimum for photosynthesis. PFT-specific, needleleaf tree value.

• θ_r::Any: Root of quadratic mean shape parameter [-]. Controls smoothness of interpolation between light and RuBisCO limitations (0.7 for smooth, 0.5 for arithmetic mean).

Alias for numeric Quantity with type NF and units U.

struct LongShortWaveRadiation <: Terrarium.AbstractIncomingRadiation

Incoming radiation parameterization in which downwelling shortwave [W/m²] and longwave [W/m²] radiation are provided as separate input fields, along with daytime length [hr].

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.

struct NoFlow <: Terrarium.AbstractVerticalFlow

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

Properties:

• ρw: Density of water in kg/m^3

• ρi: Density of ice in kg/m^3

• ρₐ: Density of air at standard pressure and 0°C in kg/m^3

• cₐ: Specific heat capacity of dry air at standard pressure and 0°C in J/(m^3*K)

• Lsl: Sepcific latent heat of fusion of water in J/kg

• Llg: Specific latent heat of vaporization of water in J/kg

• Lsg: Specific latent heat of sublimation of water in J/kg

• g: Gravitational constant in m/s^2

• Tref: Reference temperature (0°C in Kelvin)

• σ: Stefan-Boltzmann constant in J/(sm^2K^4)

• κ: von Kármán constant

• ε: Ratio of molecular weight of water vapor to dry air

• Rₐ: Specific gas constant of air in J/(kg*K)

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

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. Prognostic variables are those which are integrated by the timestepper and fully define the state of the system at any given point in (simulation) time. From a computational perspective, they can be seen as the "roots" of the computational graph for update_state!/timestep!. Prognostic variables generally should not be modified by any code not belonging to the timestepper or user. They automatically define a tendency (auxiliary) variable which is used to hold the value of their instantaneous time derivative computed by compute_tendencies!.

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

struct RainSnow <: Terrarium.AbstractPrecipitation

Precipitation parameterization in which liquid rainfall [m/s] and frozen snowfall [m/s] are provided as separate input fields.

RichardsEq{PS} <: AbstractVerticalFlow

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

State variables defined by the Richards' formulation of SoilHydrology:

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

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

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 the soil hydrology state

• hydraulic_properties::Terrarium.AbstractSoilHydraulics: Soil hydraulic properties parameterization

• vwc_forcing::Union{Nothing, Oceananigans.Forcings.ContinuousForcing{LX, LY, LZ, P} where {P, LX, LY, LZ}, Oceananigans.Forcings.DiscreteForcing}: Forcing for soil moisture (volumetric water content)

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

struct SoilMoistureResistanceFactor{NF} <: Terrarium.AbstractGroundEvaporationResistanceFactor

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

\[\beta = \frac{1}{4} \left[1 - \cos\left(π \theta_1/\theta_{\text{fc}} \right)\right] \quad \text{for } \theta_1 < \theta_{\text{fc}}\]

otherwise $\beta=1$.

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}

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 SpecificHumidity <: Terrarium.AbstractHumidity

Humidity parameterization in which the near-surface specific humidity [kg/kg] is provided directly as an input field.

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 continuous density 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}, StomatalConductance<: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.

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.