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.

compute_z_bcs!(tendency, progvar, grid::AbstractLandGrid, state)

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.

getbc(::Variable{name}, i::Integer, j::Integer, grid::Oceananigans.Grids.AbstractGrid, clock, fields) where {name}

Implementation of Oceananigans.BoundaryConditions.getbc for variable placeholders that retrieves the input Field from fields 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.

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

Convenience constructor that creates a SoilStratigraphy with a single ConstantSoilHorizon.

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.

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

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

Alias for FluxBoundaryCondition on internal_energy with name soil_heat_flux representing the net heat flux into the top of the soil column. Without snow this equals the surface energy balance ground_heat_flux; with snow it is the (blended) conductive flux across the snow base.

Creates a NamedTuple from the given tracer gas types.

Generation-time helper for get_fields. Given the type Vars of a tuple of AbstractVariables and Namespaces, builds an expression that retrieves all matching fields from state_ex (an expression evaluating to the state container) and vars_ex (an expression evaluating to the variable tuple). The recursion over namespaces is performed here, at expansion time, so that the generated body for get_fields contains no self-call. This is what makes the method type stable: a runtime self-recursive get_fields would otherwise trigger inference's recursion limiting and widen the return type of the nested namespace lookups to an abstract NamedTuple.

adjust_saturation_profile!(
    out,
    i,
    j,
    grid,
    hydrology::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,
    evapotranspiration::PALADYNCanopyEvapotranspiration{NF},
    _::Terrarium.AbstractVegetation
) -> 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.

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

Return the current prescribed ambient CO2 concentration level.

auxiliary(name, dims; ...)
auxiliary(name, dims, ctor; ...)
auxiliary(name, dims, ctor, params; units, bounds, 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_evaporation_conductance(
    _::PALADYNCanopyEvapotranspiration,
    f_can,
    rₐ
) -> Any

Compute the canopy evaporation vapor conductance [m/s] from canopy saturation fraction f_can and aerodynamic resistance rₐ. The canopy evaporation flux is this conductance times the humidity gradient.

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

Compute or retrieve the current canopy water storage [m].

celsius_to_kelvin(c::ThermodynamicConstants, T)

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

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

checkfinite!(field)
checkfinite!(field, name)

Check whether the given field has any NaN or Inf values and raise an error if NaNs are detected.

closure!(
    state,
    grid,
    closure::SnowEnergyTemperatureClosure,
    snow::SingleLayerSnow,
    constants::PhysicalConstants,
    args...
)

Forward closure: recover snow_temperature and snow_liquid_fraction from the prognostic snow_energy.

Compute the forward closure mapping for soil hydrology and energy, in that order.

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},
    traits::PlantTraits{NF},
    swdown,
    LAI
) -> Any

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

References

• [16] Willeit & Ganopolski, Geoscientific Model Development (2016)

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

Computes the gross photosynthesis rate Ag [gC/m²/s], [17, Eq. (2)].

References

• [17] Haxeltine & Prentice, Global Biogeochemical Cycles (1996)

compute_C_veg_tend(vegcarbon_dynamics, traits, LAI_b, NPP)

Computes the C_veg tendency based on NPP and the balanced Leaf Area Index LAI_b, [16, Eq. (72)]

References

• [16] Willeit & Ganopolski, Geoscientific Model Development (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], [17, Eqs. (3, 5)].

References

• [17] Haxeltine & Prentice, Global Biogeochemical Cycles (1996)

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,
    traits,
    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], [17, Eq. (10)] and [16, Eq. (10)].

References

• [17] Haxeltine & Prentice, Global Biogeochemical Cycles (1996)
• [16] Willeit & Ganopolski, Geoscientific Model Development (2016)

compute_Rg(autoresp, GPP, Rm)

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

compute_Rm(
    autoresp,
    vegcarbon_dynamics,
    traits,
    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 [18] Box 2. Note: this is not the same formula as in the [16] paper, this implementaion is taken from the code

References

• [18] Harrison et al., New Phytologist (2021)
• [16] Willeit & Ganopolski, Geoscientific Model Development (2016)

compute_albedo!(
    out,
    i,
    j,
    grid,
    fields,
    albedo::DiagnosticAlbedo,
    vegetation::Union{Nothing, Terrarium.AbstractVegetation},
    snow::Union{Nothing, Terrarium.AbstractSnow},
    args...
)

compute_albedo(
    i,
    j,
    grid,
    fields,
    snow::Terrarium.AbstractSnow
) -> Any

compute_albedo(
    i,
    j,
    grid,
    fields,
    albedo::Terrarium.ConstantSnowAlbedo
) -> Any

compute_assimilation_factors(
    photo::LUEPhotosynthesis{NF},
    constants::MaterialConstants{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 [16, Eqs. (C4-C5)] and [17].

• 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

References

• [17] Haxeltine & Prentice, Global Biogeochemical Cycles (1996)
• [16] Willeit & Ganopolski, Geoscientific Model Development (2016)H

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,
    phenology::Terrarium.AbstractPhenology,
    traits::PlantTraits,
    atmos::Terrarium.AbstractAtmosphere
) -> Tuple{Any, Any}

Compute autotrophic respiration following the scheme of [16].

References

• [16] Willeit & Ganopolski, Geoscientific Model Development (2016)

compute_auxiliary!(
    state,
    grid,
    seb::SurfaceEnergyBalance,
    constants::PhysicalConstants,
    atmos::Terrarium.AbstractAtmosphere
)
compute_auxiliary!(
    state,
    grid,
    seb::SurfaceEnergyBalance,
    constants::PhysicalConstants,
    atmos::Terrarium.AbstractAtmosphere,
    hydrology::Union{Nothing, Terrarium.AbstractSurfaceHydrology}
)
compute_auxiliary!(
    state,
    grid,
    seb::SurfaceEnergyBalance,
    constants::PhysicalConstants,
    atmos::Terrarium.AbstractAtmosphere,
    hydrology::Union{Nothing, Terrarium.AbstractSurfaceHydrology},
    vegetation::Union{Nothing, Terrarium.AbstractVegetation}
)
compute_auxiliary!(
    state,
    grid,
    seb::SurfaceEnergyBalance,
    constants::PhysicalConstants,
    atmos::Terrarium.AbstractAtmosphere,
    hydrology::Union{Nothing, Terrarium.AbstractSurfaceHydrology},
    vegetation::Union{Nothing, Terrarium.AbstractVegetation},
    snow::Union{Nothing, Terrarium.AbstractSnow},
    args...
)

compute_auxiliary!(
    state,
    grid,
    hydrology::SurfaceHydrology,
    constants::PhysicalConstants,
    atmos::Terrarium.AbstractAtmosphere
)
compute_auxiliary!(
    state,
    grid,
    hydrology::SurfaceHydrology,
    constants::PhysicalConstants,
    atmos::Terrarium.AbstractAtmosphere,
    soil::Union{Nothing, Terrarium.AbstractSoil}
)
compute_auxiliary!(
    state,
    grid,
    hydrology::SurfaceHydrology,
    constants::PhysicalConstants,
    atmos::Terrarium.AbstractAtmosphere,
    soil::Union{Nothing, Terrarium.AbstractSoil},
    vegetation::Union{Nothing, Terrarium.AbstractVegetation}
)
compute_auxiliary!(
    state,
    grid,
    hydrology::SurfaceHydrology,
    constants::PhysicalConstants,
    atmos::Terrarium.AbstractAtmosphere,
    soil::Union{Nothing, Terrarium.AbstractSoil},
    vegetation::Union{Nothing, Terrarium.AbstractVegetation},
    snow::Union{Nothing, Terrarium.AbstractSnow},
    args...
)

compute_auxiliary!(
    state,
    grid,
    veg::VegetationCarbonCycle,
    constants::PhysicalConstants,
    atmos::Terrarium.AbstractAtmosphere
)
compute_auxiliary!(
    state,
    grid,
    veg::VegetationCarbonCycle,
    constants::PhysicalConstants,
    atmos::Terrarium.AbstractAtmosphere,
    soil::Union{Nothing, Terrarium.AbstractSoil},
    args...
)

Compute auxiliary variables for all vegetation component processes based on the given atmospheric inputs defined by atmos and (optionally) soil state. If soil = nothing, stress factors due to soil temperature and moisture availability will be ignored.

compute_auxiliary!(state, grid, albedo::DiagnosticAlbedo)
compute_auxiliary!(
    state,
    grid,
    albedo::DiagnosticAlbedo,
    vegetation::Union{Nothing, Terrarium.AbstractVegetation}
)
compute_auxiliary!(
    state,
    grid,
    albedo::DiagnosticAlbedo,
    vegetation::Union{Nothing, Terrarium.AbstractVegetation},
    snow::Union{Nothing, Terrarium.AbstractSnow},
    args...
)

Diagnose the blended surface albedo and emissivity, weighting the snow-free background and snow values by the snow-covered area fraction of the optional snow component.

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

Compute auxiliary variables for all vegetation component processes based on the given atmospheric inputs defined by atmos and (optionally) soil state. If soil = nothing, stress factors due to soil temperature and moisture availability will be ignored.

compute_auxiliary!(
    state,
    grid,
    runoff::DirectSurfaceRunoff,
    canopy_interception::Terrarium.AbstractCanopyInterception,
    soil::Terrarium.AbstractSoil
)
compute_auxiliary!(
    state,
    grid,
    runoff::DirectSurfaceRunoff,
    canopy_interception::Terrarium.AbstractCanopyInterception,
    soil::Terrarium.AbstractSoil,
    snow::Union{Nothing, Terrarium.AbstractSnow},
    args...
)

compute_auxiliary!(
    state,
    grid,
    evaporation::BareGroundEvaporation,
    ::NoCanopyInterception,
    constants::PhysicalConstants,
    atmos::Terrarium.AbstractAtmosphere
)
compute_auxiliary!(
    state,
    grid,
    evaporation::BareGroundEvaporation,
    ::NoCanopyInterception,
    constants::PhysicalConstants,
    atmos::Terrarium.AbstractAtmosphere,
    soil::Union{Nothing, Terrarium.AbstractSoil}
)
compute_auxiliary!(
    state,
    grid,
    evaporation::BareGroundEvaporation,
    ::NoCanopyInterception,
    constants::PhysicalConstants,
    atmos::Terrarium.AbstractAtmosphere,
    soil::Union{Nothing, Terrarium.AbstractSoil},
    snow::Union{Nothing, Terrarium.AbstractSnow}
)

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

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

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

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

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

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

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

compute_auxiliary!(
    state,
    grid,
    evapotranspiration::PALADYNCanopyEvapotranspiration,
    canopy_interception::Terrarium.AbstractCanopyInterception,
    constants::PhysicalConstants,
    atmos::Terrarium.AbstractAtmosphere,
    soil::Terrarium.AbstractSoil,
    vegetation::Terrarium.AbstractVegetation,
    args...
)

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

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

compute_auxiliary!(
    state,
    grid,
    phenol::PALADYNPhenology,
    vegcarbon::PALADYNCarbonDynamics,
    atmos::Terrarium.AbstractAtmosphere
)

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,
    snow::SingleLayerSnow,
    constants::PhysicalConstants,
    args...
)

Diagnose the snow geometric and thermal properties (snow_depth, snow_cover_fraction, snow_thermal_conductivity) from the current snow water equivalent and bulk density. The enthalpy closure (snow_temperature, snow_liquid_fraction) is added in a later phase.

Compute auxiliary variables for soil energy, water, and carbon state variables on grid based on the given values in constants.

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

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

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

compute_balanced_leaf_area_index(
    vegcarbon_dynamics,
    traits,
    C_veg
)

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

References

• [16] Willeit & Ganopolski, Geoscientific Model Development (2016)

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

Compute I_can, the canopy rain interception, following [16, Eq. (42)].

References

• [16] Willeit and Ganopolski, Geoscientific Model Development (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_canopy_water_tendency(
    _::PALADYNCanopyInterception{NF},
    I_can,
    E_can,
    R_can
) -> Any

Compute the W_can tendency and removal rate following [16, Eq. (41)].

References

• [16] Willeit and Ganopolski, Geoscientific Model Development (2016)

compute_emissivity(
    i,
    j,
    grid,
    fields,
    snow::Terrarium.AbstractSnow
) -> Any

compute_emissivity(
    i,
    j,
    grid,
    fields,
    albedo::Terrarium.ConstantSnowAlbedo
) -> Any

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

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

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

compute_energy_tendency(
    i,
    j,
    k,
    grid,
    fields,
    energy::Terrarium.AbstractThermodynamics,
    args...
) -> Any

Compute the internal energy tendency ∂U∂t as the divergence of the diffusive heat flux for the explicit two-phase heat conduction operator.

compute_evaporation_flux(
    _::Terrarium.AbstractEvapotranspiration,
    Δq,
    g
) -> Any

Compute an evapotranspiration flux (m/s, positive upwards) as the product of a vapor conductance g (m/s) and a specific humidity difference Δq (kg/kg). All evapotranspiration components — soil/canopy evaporation and transpiration — share the functional form $E = Δq · g$, differing only in which conductance and humidity difference are supplied.

compute_evapotranspiration_conductances(
    i,
    j,
    grid,
    fields,
    evaporation::BareGroundEvaporation,
    constants::PhysicalConstants,
    atmos::Terrarium.AbstractAtmosphere
) -> Any
compute_evapotranspiration_conductances(
    i,
    j,
    grid,
    fields,
    evaporation::BareGroundEvaporation,
    constants::PhysicalConstants,
    atmos::Terrarium.AbstractAtmosphere,
    soil::Union{Nothing, Terrarium.AbstractSoil}
) -> Any

Compute the skin-driven ground evaporation vapor conductance β/rₐ at grid cell i, j for the given bare-ground evaporation scheme. This conductance is independent of the skin temperature.

compute_evapotranspiration_conductances!(
    out,
    i,
    j,
    grid,
    fields,
    evaporation::BareGroundEvaporation,
    constants::PhysicalConstants,
    atmos::Terrarium.AbstractAtmosphere
) -> Any
compute_evapotranspiration_conductances!(
    out,
    i,
    j,
    grid,
    fields,
    evaporation::BareGroundEvaporation,
    constants::PhysicalConstants,
    atmos::Terrarium.AbstractAtmosphere,
    soil::Union{Nothing, Terrarium.AbstractSoil}
) -> Any

Compute and store the skin-driven ground evaporation vapor conductance on grid for the given bare-ground evaporation scheme.

compute_evapotranspiration_conductances!(
    out,
    i,
    j,
    grid,
    fields,
    evapotranspiration::PALADYNCanopyEvapotranspiration,
    canopy_interception::Terrarium.AbstractCanopyInterception,
    constants::PhysicalConstants,
    atmos::Terrarium.AbstractAtmosphere,
    soil::Terrarium.AbstractSoil,
    vegetation::Terrarium.AbstractVegetation,
    args...
) -> Any

Compute and store the skin-driven vapor conductances on grid for the given scheme evapotranspiration and process dependencies.

compute_evapotranspiration_conductances(
    i,
    j,
    grid,
    fields,
    evapotranspiration::PALADYNCanopyEvapotranspiration,
    canopy_interception::Terrarium.AbstractCanopyInterception,
    constants::PhysicalConstants,
    atmos::Terrarium.AbstractAtmosphere,
    soil::Terrarium.AbstractSoil,
    vegetation::Terrarium.AbstractVegetation,
    args...
) -> Tuple{Any, Any, Any}

Compute the skin-driven vapor conductances (ground_evaporation_conductance, canopy_evaporation_conductance, and transpiration_conductance) at grid cell i, j for the given scheme evapotranspiration and process dependencies. These conductances are independent of the skin temperature.

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

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

compute_f_temp(autoresp, T_air, T_soil)

Computes temperature factors f_temp_air and f_temp_soil for autotrophic respiration.

compute_gdd_tendency!(
    tend,
    i,
    j,
    grid,
    fields,
    phenol::PALADYNPhenology,
    atmos::Terrarium.AbstractAtmosphere
) -> Any

Mutating wrapper for compute_gdd_tendency that stores the growing-degree-day tendency in tend.

compute_gdd_tendency(phenol, gdd, T_air)

Compute the growing-degree-day tendency d(gdd)/dt [K⋅day/s] at a single grid point.

Heat above the base temperature is accumulated (in degree-days per second) and, below the base temperature, the accumulator relaxes toward zero with timescale gdd_relaxation_time. The relaxation provides a continuous surrogate for the discrete annual reset of the original scheme.

compute_ground_heat_flux!(
    out,
    i,
    j,
    grid,
    fields,
    skinT::Terrarium.AbstractSkinTemperature,
    seb::Terrarium.AbstractSurfaceEnergyBalance
)

Per-cell mutating variant used by the fused surface-energy-balance kernel: store the ground heat flux into the auxiliary output field out.

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$ (all fluxes positive upward).

compute_ground_heat_flux(
    i,
    j,
    grid,
    fields,
    skinT::Terrarium.AbstractSkinTemperature,
    _::Terrarium.AbstractSurfaceEnergyBalance
) -> 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 G that closes the surface energy balance. With all fluxes positive upward (aligned with +z), the energy arriving at the skin from below must balance the radiative and turbulent losses above, so G = R_net + H_s + H_l.

compute_heat_capacity(props, soil)

Compute the bulk heat capacity of the given soil volume.

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

Kernel function that computes dynamic soil hydraulic properties.

compute_hydraulics!(
    out,
    i,
    j,
    k,
    grid,
    fields,
    hydrology::SoilHydrology{NF, RichardsEq, SaturationClosure, SoilHydraulics} where {SaturationClosure<:Terrarium.AbstractSoilWaterClosure, SoilHydraulics<:(Terrarium.AbstractSoilHydraulics{NF})},
    strat::Terrarium.AbstractStratigraphy,
    bgc::Terrarium.AbstractSoilBiogeochemistry
)

Computes the unsaturated hydraulic conductivity for RichardsEq configurations of SoilHydrology.

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

References

• [17] Haxeltine & Prentice, Global Biogeochemical Cycles (1996)

compute_latent_heat_flux(
    i,
    j,
    grid,
    fields,
    tur::DiagnosedTurbulentFluxes,
    skinT::Terrarium.AbstractSkinTemperature,
    constants::PhysicalConstants,
    atmos::Terrarium.AbstractAtmosphere
) -> Any
compute_latent_heat_flux(
    i,
    j,
    grid,
    fields,
    tur::DiagnosedTurbulentFluxes,
    skinT::Terrarium.AbstractSkinTemperature,
    constants::PhysicalConstants,
    atmos::Terrarium.AbstractAtmosphere,
    evtr::Union{Nothing, Terrarium.AbstractEvapotranspiration}
) -> Any
compute_latent_heat_flux(
    i,
    j,
    grid,
    fields,
    tur::DiagnosedTurbulentFluxes,
    skinT::Terrarium.AbstractSkinTemperature,
    constants::PhysicalConstants,
    atmos::Terrarium.AbstractAtmosphere,
    evtr::Union{Nothing, Terrarium.AbstractEvapotranspiration},
    snow::Union{Nothing, Terrarium.AbstractSnow}
) -> Any

Compute the latent heat flux at i, j based on the current skin temperature and atmospheric conditions. When an evapotranspiration scheme is provided, uses the ET-aware humidity flux; otherwise uses bare ground evaporation.

With a snow component, the flux is partitioned by snow-covered area fraction f_snow: the snow-free fraction (1 − f_snow) evaporates from the ground/canopy (latent heat of vaporization), while the snow-covered fraction sublimates from the snowpack (latent heat of sublimation, see compute_snow_sublimation_flux). Without snow it reduces to the bare ground/canopy latent flux.

compute_latent_heat_flux(
    _::DiagnosedTurbulentFluxes,
    Q_h,
    ρₐ,
    L
) -> 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 vaporization or sublimation L [J/kg].

compute_leaf_area_index(phenol, ϕ, LAI_b)

Compute the instantaneous leaf area index LAI = ϕ·LAI_b from the phenology factor ϕ and the balanced leaf area index LAI_b.

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

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

compute_meltwater_outflow(
    hydraulics::ConstantSnowHydraulics,
    θ_liq
) -> Any

Darcy-type meltwater outflow M_r (m/s, SWE). Liquid water in excess of the capillary retention L_c drains from the snowpack with a cubic conductivity [3] (in excess-saturation form): M_r = K_sat · S*³ with S* = max(θ_liq − L_c, 0) / (1 − L_c), where θ_liq is the liquid fraction of the water substance. Outflow vanishes smoothly as θ_liq → L_c and saturates at K_sat as θ_liq → 1.

References

• [3] Tarboton et al., Report (1994)

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

Cell-level phenology computation. Implementations return phenology factors and derived LAI at the given index i, j, using atmospheric inputs (e.g. air temperature) where required by the scheme.

compute_phenology!(
    out,
    i,
    j,
    grid,
    fields,
    phenol::PALADYNPhenology,
    atmos::Terrarium.AbstractAtmosphere
) -> Any

Mutating wrapper for compute_phenology that stores the result in out.

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

Compute the phenology factor and instantaneous leaf area index (LAI) at a single grid point.

compute_phenology_factor(phenol, gdd, T_air)

Compute the phenology factor ϕ [-] from accumulated growing degree days gdd and air temperature T_air.

The cold-deciduous factor combines the growth-phase ramp gdd / gdd_crit [16, Eq. (83)] with a senescence ramp that declines linearly from 1 at T_gdd_base to 0 at T_gdd_base − T_senescence_range. Taking the minimum reproduces all three PALADYN regimes (linear green-up, held at 1 when mature and warm, temperature-driven senescence). The result is then blended with the evergreen value of 1 via the prescribed deciduous fraction.

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,
    stomcond::Terrarium.AbstractStomatalConductance,
    traits::PlantTraits,
    constants::PhysicalConstants,
    atmos::Terrarium.AbstractAtmosphere
) -> Any

Calls compute_photosynthesis and stores the results in out.

compute_photosynthesis(
    i,
    j,
    grid,
    fields,
    photo::LUEPhotosynthesis,
    stomcond::Terrarium.AbstractStomatalConductance,
    traits::PlantTraits,
    constants::PhysicalConstants,
    atmos::Terrarium.AbstractAtmosphere
) -> 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 rainfall_ground, the rate of rain reaching the ground, following a modified version of [16, Eq. (44)]. Instead of subtracting the tendency, we just directly subtract interception and add the removal rate R_can.

References

• [16] Willeit and Ganopolski, Geoscientific Model Development (2016)

compute_pres_i(photo::LUEPhotosynthesis, λc, pres_a) -> Any

Computes intercellular CO2 partial pressure [Pa], [16, Eq. (67)].

References

• [16] Willeit & Ganopolski, Geoscientific Model Development (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},
    traits::PlantTraits{NF},
    constants::MaterialConstants{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,
    constants::PhysicalConstants,
    atmos::Terrarium.AbstractAtmosphere
) -> 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 [W/m²] 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, S_down, α)

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

compute_skin_temperature(
    i,
    j,
    grid,
    fields,
    skinT::ImplicitSkinTemperature,
    constants::PhysicalConstants
) -> Any
compute_skin_temperature(
    i,
    j,
    grid,
    fields,
    skinT::ImplicitSkinTemperature,
    constants::PhysicalConstants,
    snow::Union{Nothing, Terrarium.AbstractSnow}
) -> Any

Estimate the skin temperature from the current ground_heat_flux at grid cell i, j, using the effective conduction target of the medium below the skin. The optional snow argument enables the snow-covered blend (see ground_thermal_interface); with snow === nothing this is the snow-free soil conduction.

compute_skin_temperature!(
    state,
    grid,
    skinT::ImplicitSkinTemperature,
    constants::PhysicalConstants
)
compute_skin_temperature!(
    state,
    grid,
    skinT::ImplicitSkinTemperature,
    constants::PhysicalConstants,
    snow::Union{Nothing, Terrarium.AbstractSnow}
)

Compute skin_temperature from the current ground_heat_flux using the (optionally snow-aware) conduction target. constants supplies the material properties for the conduction blend; passing a snow component (default nothing) selects the snow-covered ground_thermal_interface, while snow === nothing recovers the snow-free soil conduction.

compute_skin_temperature!(
    out,
    i,
    j,
    grid,
    fields,
    skinT::ImplicitSkinTemperature,
    seb::Terrarium.AbstractSurfaceEnergyBalance,
    constants::PhysicalConstants
)
compute_skin_temperature!(
    out,
    i,
    j,
    grid,
    fields,
    skinT::ImplicitSkinTemperature,
    seb::Terrarium.AbstractSurfaceEnergyBalance,
    constants::PhysicalConstants,
    snow::Union{Nothing, Terrarium.AbstractSnow},
    seb_args...
)

Recompute surface energy fluxes using compute_surface_energy_fluxes! and update the skin temperature based on the resulting ground heat flux.

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

Compute the implicit update of the skin temperature from the sub-surface temperature Tg, ground heat flux G, half-cell distance Δz, and effective conductivity κ, by equating G to the half-cell conductive flux 2κ(Tg − Ts)/Δz.

compute_skin_temperature_residual!(
    out,
    i,
    j,
    grid,
    fields,
    skinT::ImplicitSkinTemperature,
    seb::Terrarium.AbstractSurfaceEnergyBalance,
    snow,
    constants,
    seb_args...
) -> Any

Same as compute_skin_temperature! but returns the residual instead of updating the skin_temperature Field.

compute_snow_basal_heat_flux(
    κ_snow,
    T_soil,
    T_snow,
    d_snow
) -> Any

Snow→soil basal conductive heat flux Q_base [W/m²], positive upward (soil → snow). The snowpack is a strong insulator, so only its resistance is retained (snow-resistance-only closure): Q_base = 2·κ_snow·(T_soil − T_snow)/d_snow. The depth is regularized with a machine-eps offset so the flux stays finite as the snowpack vanishes.

compute_snow_cover_fraction(
    cover::FractionalSnowCover{NF},
    swe
) -> Any

Sub-grid snow-covered area fraction f_snow = W_snow/(W_snow + W_ref) ∈ [0,1) from the snow water equivalent W_snow [m] and the reference level W_ref (half_coverage), clamping negative SWE (which can occur transiently in the prognostic state) to zero cover.

snow_density(i, j, grid, fields, ::AbstractSnowDensity)

Compute or retrieve the bulk snow density ρ_snow [kg/m³].

compute_snow_depth(
    _::Terrarium.AbstractSnow,
    W_snow,
    ρ_snow,
    ρ_w
) -> Any

Snow layer depth d_snow = W_snow·ρ_w/ρ_snow [m], converting the water-equivalent depth W_snow [m] to the physical snow depth using the water density ρ_w and the bulk snow density ρ_snow.

compute_snow_energy_tendency(
    i,
    j,
    grid,
    fields,
    snow::SingleLayerSnow,
    atmos::Terrarium.AbstractAtmosphere,
    constants::PhysicalConstants
) -> Any

Depth-integrated snow energy tendency [W/m²] at grid cell i, j (all fluxes positive upward):

dŪ_snow/dt = Q_base − Q_top + Q_precip + Q_subl

where Q_top/Q_base are the surface/basal heat fluxes, Q_precip the advected precipitation heat (see compute_snow_precip_heat_flux), and Q_subl an advective correction for sublimation.

The sublimation correction Q_subl = ρ_w·L_sl·E_subl is required because the latent heat flux carries the full sublimation enthalpy ρ_w·L_sg·E_subl, whereas the mass leaving the snowpack departs as ice, whose specific enthalpy relative to the liquid-water reference is −L_sl. Adding back ρ_w·L_sl·E_subl leaves the snowpack with a net loss of ρ_w·(L_sg − L_sl)·E_subl = ρ_w·L_lg·E_subl, the vaporization enthalpy carried by the departing vapor.

Note that no explicit meltwater energy term appears because meltwater drains as liquid water at 0 °C, which is the zero-enthalpy reference (U = 0) of the FreeWater closure, so it carries no enthalpy out of the snowpack.

compute_snow_interface_fluxes!(
    out,
    i,
    j,
    grid,
    fields,
    snow::SingleLayerSnow,
    seb::Terrarium.AbstractSurfaceEnergyBalance,
    soil::Terrarium.AbstractSoil,
    constants::PhysicalConstants,
    atmos::Terrarium.AbstractAtmosphere
)

Diagnose the snow↔surface/soil coupling fluxes at grid cell i, j, run after the surface energy balance: the blended soil-top heat flux (see compute_snow_soil_heat_flux) and the snow surface sublimation rate (see compute_snow_sublimation_flux, the same snow-fraction vapor flux the surface energy balance uses for the latent-flux partition).

compute_snow_interface_fluxes!(
    state,
    grid,
    _::Nothing,
    args...
)

Launch compute_snow_interface_fluxes! to diagnose the snow↔surface/soil coupling fluxes from the snow state and the surface energy balance outputs: the blended soil-top heat flux (soil_heat_flux) and the snow surface sublimation rate (sublimation, the snow-fraction bulk-aerodynamic vapor flux at the converged skin temperature). Must run after the surface energy balance (which sets ground_heat_flux and the skin temperature). No-op when there is no snowpack (snow === nothing).

compute_snow_precip_heat_flux(
    _::Terrarium.AbstractSnow,
    constants::PhysicalConstants,
    P_s,
    R_on_snow,
    T_air
) -> Any

Advected heat flux [W/m²] carried into the snowpack by precipitation, relative to liquid water at 0 °C (the U = 0 reference of the FreeWater enthalpy closure). Fresh snow P_s arrives as ice, which sits L_sl below the liquid reference, plus sensible heat for T_air < 0; rain-on-snow R_on_snow arrives as liquid carrying only its sensible heat for T_air > 0. The latent heat released when rain refreezes in a cold pack is captured implicitly by the enthalpy closure, so it is not added here (adding L_sl would double-count relative to the liquid-water reference).

compute_snow_properties!(
    out,
    i,
    j,
    grid,
    fields,
    snow::SingleLayerSnow,
    constants::PhysicalConstants
)

Compute the snow depth, cover fraction, and thermal conductivity at grid cell i, j.

compute_snow_soil_heat_flux(
    i,
    j,
    grid,
    fields,
    snow::SingleLayerSnow,
    constants::PhysicalConstants,
    soil::Terrarium.AbstractSoil
) -> Any

Blended soil-top heat flux [W/m²] at grid cell i, j: the snow-cover-fraction-weighted combination of the snow→soil basal conductive flux Q_base and the bare-ground surface energy balance closure flux G (ground_heat_flux), f_snow·Q_base + (1 − f_snow)·G. The bulk snow thermal conductivity entering Q_base is recovered lazily from the density scheme rather than stored.

compute_snow_sublimation_flux(
    i,
    j,
    grid,
    fields,
    _::Nothing,
    atmos,
    constants,
    skinT
) -> Any

Snow-surface sublimation rate [m/s SWE] at grid cell i, j, area-weighted by the snow-covered fraction f_snow. The snow surface is treated as saturated: a bulk-aerodynamic vapor flux Δq/rₐ evaluated at the skin temperature, with Δq taken over ice for a sub-freezing surface (the saturation humidity already dispatches over ice for T ≤ 0 — see saturation_specific_humidity_vapor). The water-vapor mass flux ρₐ·Δq/rₐ is converted to a snow-water-equivalent rate via ρ_w. Zero without snow (snow === nothing).

compute_snow_tendencies!(
    tendencies,
    i,
    j,
    grid,
    fields,
    snow::SingleLayerSnow,
    atmos::Terrarium.AbstractAtmosphere,
    constants::PhysicalConstants
)

Accumulate the snow water-equivalent and depth-integrated energy tendencies at grid cell i, j from the mass and energy balances (see compute_snow_water_tendency and compute_snow_energy_tendency).

compute_snow_volumetric_heat_capacity(
    _::Terrarium.AbstractSnow{NF},
    constants::PhysicalConstants,
    ρ_snow,
    liq
) -> Any

Bulk volumetric heat capacity C_snow [J/m³/K] of the snowpack treated as an ice–liquid–air mixture, given the bulk snow density ρ_snow [kg/m³] and the liquid water fraction liq ∈ [0,1] of the water substance. The water-substance mass per unit snow volume is ρ_snow, of which (1 − liq) is ice and liq is liquid; the remaining void space is dry air. The corresponding constituent volume fractions are

\[\begin{aligned} θ_{ice} &= ρ_{snow}·(1 − liq)/ρ_i,\ θ_{liq} &= ρ_{snow}·liq/ρ_w,\ θ_{air} &= 1 − θ_{ice} − θ_{liq} \end{aligned}\]

and the heat capacity is the volume-weighted sum over the ice and liquid constituents, C_snow = cp_i·ρ_i·θ_ice + cp_w·ρ_w·θ_liq. The air's own sensible-heat storage (≈0.1%) is neglected; note the air is still reflected in the bulk density ρ_snow < ρ_ice.

compute_snow_water_tendency(
    i,
    j,
    grid,
    fields,
    snow::SingleLayerSnow,
    atmos::Terrarium.AbstractAtmosphere
) -> Any

Snow water equivalent (SWE) tendency (m/s) at grid cell i, j:

dW_snow/dt = S + R_snow − M − E_subl

where S is snowfall, R_snow = f_snow · rainfall the rain intercepted by the snow-covered fraction, M the Darcy meltwater outflow (see snow_meltwater_flux), and E_subl the sublimation rate.

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

Computes the specific humidity difference [kg/kg] between a saturated surface at temperature T [°C] and the current atmospheric fields.

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},
    traits::PlantTraits{NF},
    constants::PhysicalConstants,
    atmos::Terrarium.AbstractAtmosphere,
    args...
) -> Any

Calls compute_stomatal_conductance and stores the result in out.

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

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

compute_stomatal_conductance(
    stomcond::MedlynStomatalConductance{NF},
    traits::PlantTraits{NF},
    vpd,
    An,
    co2,
    LAI,
    β
) -> Any

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

References

• [19] Medlyn et al., Global Change Biology (2011)

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

Compute surface drainage flux from the current surface_excess_water resevoir state.

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

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

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

Fused kernel function that computes the radiative and turbulent fluxes, as well as the ground heat flux based on the current skin temperature and humidity fluxes.

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

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

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

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

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

compute_surface_humidity_flux(
    i,
    j,
    grid,
    fields,
    _::BareGroundEvaporation,
    atmos::Terrarium.AbstractAtmosphere,
    constants::PhysicalConstants
) -> Any

Evaluate the bare-ground surface humidity flux [m/s] from the current skin temperature and evaporation conductance in fields.

compute_surface_humidity_flux(
    i,
    j,
    grid,
    fields,
    evtr::PALADYNCanopyEvapotranspiration,
    constants::PhysicalConstants,
    atmos::Terrarium.AbstractAtmosphere,
    args...
) -> Any

Compute the surface humidity flux [m/s] from the current skin temperature and conductances in fields.

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

compute_surface_runoff!(
    out, i, j, grid, fields,
    runoff::DirectSurfaceRunoff{NF},
    canopy_interception::AbstractCanopyInterception,
    soil_hydrology::AbstractSoilHydrology
) where {NF}

Compute surface runoff in grid cell i, j and store the result in out.surface_runoff. Runoff is computed based on the ground-reaching precipitation rate provided by canopy_interception and the soil saturation state provided by soil_hydrology.

compute_surface_runoff(
    runoff::DirectSurfaceRunoff,
    influx,
    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,
    traits::PlantTraits,
    args...
)

compute_tendencies!(
    state,
    grid,
    phenol::PALADYNPhenology,
    atmos::Terrarium.AbstractAtmosphere
)

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

compute_tendencies!(
    state,
    grid,
    snow::SingleLayerSnow,
    constants::PhysicalConstants,
    atmos::Terrarium.AbstractAtmosphere,
    args...
)

Compute the snow water-equivalent and depth-integrated energy tendencies (see compute_snow_tendencies!), driven by the atmospheric precipitation inputs and the prescribed surface/basal heat fluxes and sublimation.

Compute tendencies for soil energy, water, and carbon state variables on grid based on the given values in constants.

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

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

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

compute_tendencies!(
    state,
    grid,
    veg::VegetationCarbonCycle,
    constants::PhysicalConstants,
    atmos::Terrarium.AbstractAtmosphere,
    args...
)

Compute tendencies for carbon and vegetation dynamics.

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, ::AbstractThermodynamics, args...)

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

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

compute_thermal_conductivity(
    i,
    j,
    k,
    grid,
    fields,
    energy::Terrarium.AbstractThermodynamics,
    args...
) -> Any

compute_thermal_conductivity(
    snow::SingleLayerSnow,
    constants::MaterialConstants,
    ρ_snow
) -> Any

Bulk snow thermal conductivity κ_snow [W/m/K], delegating to the process's thermal conductivity scheme with the bulk density ρ_snow.

compute_thermal_conductivity(props, soil)

Compute the bulk thermal conductivity of the given soil volume.

compute_thermal_conductivity(
    cond::PowerLawSnowThermalConductivity{NF},
    constants::MaterialConstants{NF},
    ρ_snow
) -> Any

Bulk snow thermal conductivity via the density power law κ_snow = a·(ρ_snow/ρ_w)^b ([13]).

compute_turbulent_fluxes!(
    out,
    i,
    j,
    grid,
    fields,
    tur::DiagnosedTurbulentFluxes,
    skinT,
    constants,
    atmos,
    evtr,
    snow
)

Compute the turbulent (sensible and latent) heat fluxes from the current skin temperature and store them into the auxiliary output fields out.

compute_turbulent_fluxes!(
    out,
    i,
    j,
    grid,
    fields,
    _::PrescribedTurbulentFluxes,
    skinT,
    constants,
    atmos,
    evtr,
    snow
)

Prescribed turbulent fluxes are input fields supplied by an external coupler (already present in fields), so there is nothing to compute or store.

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

Computes the vapor pressure deficit (VPD) [Pa] at atmospheric reference level given the current atmospheric fields

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

Computes the vapor pressure difference [Pa] between a saturated surface at temperature T [°C] and the current atmospheric fields.

compute_veg_carbon_auxiliary!(
    out,
    i,
    j,
    grid,
    fields,
    vegcarbon_dynamics::PALADYNCarbonDynamics,
    traits::PlantTraits
)

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

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

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,
    traits::PlantTraits
) -> Any

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

compute_volumetric_snow_energy(Ū_snow, d_snow) -> Any

Volumetric snow internal energy U_snow = Ū_snow/d_snow [J/m³] from the depth-integrated energy Ū_snow [J/m²] and the snow depth d_snow [m]. The denominator is regularized with a machine-eps offset so the result stays finite (and differentiable) as W_snow → 0: with Ū_snow → 0 and d_snow → 0 together, U_snow → 0. The thin-snow indeterminacy is additionally masked downstream by f_snow → 0. A finite offset is used rather than safediv because safediv returns Inf at exactly d_snow = 0 (even for Ū_snow = 0), which would produce NaN when multiplied by f_snow = 0 in the surface energy balance blend.

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_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 [16, Eq. (C6)].

References

• [16] Willeit & Ganopolski, Geoscientific Model Development (2016)

compute_Λ_loc(vegcarbon_dynamics, traits, LAI_b)

Computes the local litterfall rate Λ_loc based on the balanced Leaf Area Index LAI_b (assuming evergreen PFTs), [16, Eq. (75)].

References

• [16] Willeit & Ganopolski, Geoscientific Model Development (2016)

compute_γv(veg_dynamics)

Computes the disturbance rateγv, [16, Eq. (80)].

References

• [16] Willeit & Ganopolski, Geoscientific Model Development (2016)

compute_λ_NPP(vegcarbon_dynamics, traits, 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, [16, Eq. (74)].

References

• [16] Willeit & Ganopolski, Geoscientific Model Development (2016)

compute_λc(stomcond, vpd)

Computes the ratio of leaf-internal and air CO2 concentration λc, derived from the optimal stomatal conductance model ([19]), [16, Eq. (71)].

References

• [19] Medlyn et al., Global Change Biology (2011)
• [16] Willeit & Ganopolski, Geoscientific Model Development (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,
    traits::PlantTraits
) -> 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,
    traits::PlantTraits
) -> Any

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

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

Computes the vegetation fraction tendency for a single PFT, [16, Eq. (73)].

References

• [16] Willeit & Ganopolski, Geoscientific Model Development (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 checkfinite!.

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{Union{AbstractVariable, Namespace}}})

Type-stable equivalent of deduplicate for tuples of AbstractVariables and Namespaces.

default_clock(
    model::Terrarium.AbstractModel{NF, Grid} where Grid<:(Terrarium.AbstractLandGrid{NF})
) -> Clock{_A, _B, Float64, Int64, Int64} where {_A, _B}

Return the default Clock used by initialize for the given model. The generic method returns a plain host clock starting at time zero; architecture extensions may specialize on the model's grid to return an architecture-specific clock (e.g. TerrariumReactantExt returns a traced ConcreteRNumber-backed clock so that time advances inside the compiled step).

default_dt(timestepper::AbstractTimeStepper)

Get the current timestep size for the time stepper.

default_dt(integrator::ModelIntegrator)

Return the default timestep size for the given integrator, taken from its model's timestepper.

default_skin_temperature_solver(
    _::Type{NF}
) -> Terrarium.RootSolver{NF, RootSolvers.NewtonsMethod{T}, RootSolvers.CompactSolution, RootSolvers.ResidualTolerance{NF}} where {NF, T<:Union{Real, AbstractArray}}

Construct the default solver for the implicit skin temperature: a Newton root-finder (RootSolver backed by RootSolvers.jl) with a small iteration budget.

default_timestepper(_)

Default timestepper for models: a single explicit ForwardEuler 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,
    energy::Terrarium.AbstractThermodynamics,
    args...
) -> Any

Compute the diffusive (Fourier) heat flux q = -κ ∂T/∂z at the cell face i, j, k, interpolating the medium-specific thermal conductivity to the face.

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.

energy_to_temperature!(
    out,
    i,
    j,
    grid,
    fields,
    _::SnowEnergyTemperatureClosure,
    snow::SingleLayerSnow,
    constants::PhysicalConstants
)

Recover the snow temperature and liquid water fraction from the depth-integrated energy at grid cell i, j.

energy_to_temperature(_::FreeWater, U, ρLθ, C) -> Any

Calculate the inverse enthalpy function given the internal energy U (J/m³), volumetric latent heat content ρLθ (J/m³), and volumetric heat capacity C (J/m³/K) under the free water freezing characteristic.

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

Evaluate an explicit update u += ∂u∂t*Δt for the prognostic fields of state listed in names 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.

explicit_timestepper(imex::AbstractIMEX)

Return the explicit sub-stepper of the AbstractIMEX timestepper imex.

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.

field_indices(
    indices::Tuple{Integer, Integer, Integer}
) -> Tuple{Integer, Integer, Integer}

Pad the grid indices to the three indices required to write to a Field. A 2D (XY) solve passes (i, j), but Oceananigans only defines setindex!(::Field, val, i, j, k) for exactly three indices.

file_extension(_::Terrarium.NetCDF) -> String

File extension (including the leading dot) used by files of the given FileFormat.

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, evapotranspiration::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_artifact(name::String) -> String

Retrieve the path to the artifact with the given name. Throws an AssertionError if no artifact with name exists in Artifacts.toml.

get_asset(asset::Terrarium.AbstractLandAsset) -> String

Download (if necessary) the given asset and return the path to its data file within the installed artifact directory. The artifact is installed via get_artifact and the data file is located by its file_extension. Reading the file is left to the caller; use load_asset to read a variable into a data Field wrapped on the asset's native_grid.

get_biogeochemistry(soil::AbstractSoil)

Return the biogeochemistry scheme associated with soil.

get_cache(cache::AbstractTimeStepperCache, timestepper::AbstractTimeStepper)

Return the working cache for timestepper given the model's state.timestepper_cache. For a single timestepper this is the cache itself; an IMEX cache returns the sub-cache matching the timestepper's class.

get_closure(snow::SingleLayerSnow) -> Any

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_balance(soil::AbstractSoil)

Return the energy balance scheme associated with soil.

get_field(
    state,
    _::Union{Terrarium.AbstractVariable{name}, Terrarium.Namespace{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, ns::Terrarium.Namespace) -> Any

Retrieves all Fields declared by the given Namespace from state, where state is assumed to correspond to the (nested) StateVariables of the namespace itself.

get_fields(state, vars)

Retrieves all Fields from state matching the names of the given variables. Any Namespaces in vars are resolved recursively and their fields are merged into the returned NamedTuple keyed by namespace name, with the namespace's own fields collected into a nested NamedTuple.

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
state = StateVariables(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(soil::AbstractSoil)

Return the hydrology scheme associated with soil.

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(soil::AbstractSoil)

Return the stratigraphy parameterization associated with soil.

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

Return the thermal properties associated with the given energy balance process.

get_timestepper(model::AbstractModel)::AbstractTimeStepper

Return the timestepper associated with the given model. All AbstractModels are required to define a timestepper field holding an AbstractTimeStepper (e.g. ForwardEuler, Heun, or IMEX).

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_conductance(
    ET::Terrarium.AbstractEvapotranspiration,
    β,
    rₐ
) -> Any

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_thermal_interface(
    i,
    j,
    grid,
    fields,
    skinT::ImplicitSkinTemperature,
    snow::Nothing
) -> Tuple{Any, Any, Any}
ground_thermal_interface(
    i,
    j,
    grid,
    fields,
    skinT::ImplicitSkinTemperature,
    snow::Nothing,
    constants
) -> Tuple{Any, Any, Any}

Return the effective conduction target (Tg, κ, Δz) seen by the skin-temperature solve: the temperature of the medium directly beneath the skin, its thermal conductivity, and the half-cell thickness. Without snow (snow === nothing) these are the uppermost ground layer's ground_temperature, the assumed surface conductivity κₛ, and the top ground cell thickness — i.e. the snow-free behavior is unchanged.

ground_thermal_interface(
    i,
    j,
    grid,
    fields,
    skinT::ImplicitSkinTemperature,
    snow::Terrarium.AbstractSnow,
    constants::PhysicalConstants
) -> Tuple{Any, Any, Any}

Snow-covered variant: the conduction target is the snow-cover-fraction-weighted blend of the snow layer and the underlying ground, x_eff = (1 − f_snow)·x_ground + f_snow·x_snow for the temperature, conductivity, and half-cell thickness.

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.

implicit_timestepper(imex::AbstractIMEX)

Return the implicit sub-stepper of the AbstractIMEX timestepper imex.

Initialize input variables from the given input sources. The scope corresponds to the path of namespace names from the root namespace to state and is used to match namespaced input sources to their target variables; see varpath.

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!(inputs, grid, clock, fields, _::InputSource)

Initializes the input source, writing into the input inputs fields at model start. The grid and the full model state fields (read-only) are provided so that sources may compute their inputs from the grid geometry or other state variables. Namespace routing is handled by the caller (see [InputSources]). Default implementation does nothing.

initialize!(
    state,
    grid,
    _::ImplicitSkinTemperature,
    args...
)

Seed the prognostic skin_temperature with the current ground_temperature so the implicit nonlinear solve starts from a physically sensible guess close to the root.

initialize!(
    state,
    grid,
    snow::SingleLayerSnow,
    constants::PhysicalConstants,
    args...
)

Initialize the snow internal energy by evaluating the inverse closure (temperature → energy). Assumes snow_temperature and snow_water_equivalent have already been initialized.

Initialize the soil energy, water, and carbon state variables on grid given the parameter values in constants.

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

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

initialize!(state, grid, seb::SurfaceEnergyBalance, args...)

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

initialize!(
    state,
    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(integrator, params; clock, inputs)

Reconstruct the given integrator using the same underlying model populated with the given params. The clock and inputs can also optionally be updated via their respective keyword arguments.

initialize(timestepper::AbstractTimeStepper, state, progvars, model)

Allocate the time stepper cache for timestepper against the given state. progvars is the named tuple of prognostic variable metadata and model the owning AbstractModel; both are needed e.g. by AbstractIMEX timesteppers to resolve each variable's timestepping class.

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(
    var::Terrarium.AuxiliaryVariable,
    grid::Terrarium.AbstractLandGrid,
    clock::Clock,
    boundary_conditions::NamedTuple,
    fields::NamedTuple
) -> Any

Initialize a Field on grid for the given AuxiliaryVariable.

initialize(::AbstractTimeStepper, state)

Initialize and return the AbstractTimeStepperCache holding any intermediate fields/state required by the given timestepper. Time steppers that need no working state fall back to the default implementation, which returns an EmptyCache.

initialize(
    model::Terrarium.AbstractModel{NF, Grid} where Grid<:(Terrarium.AbstractLandGrid{NF});
    ...
) -> Union{ModelIntegrator{_A, _B, _C, _D, var"#s179", StateVariables{NF, prognames, closurenames, auxnames, inputnames, nsnames, ProgFields, TendFields, AuxFields, InputFields, Namespaces, Cache, ClockType}, Clock{_A1, _B1, Float64, Int64, Int64}, @NamedTuple{}, InputSources{NF1, name, Sources}} where {_B<:Oceananigans.Architectures.AbstractArchitecture, _C<:Terrarium.AbstractLandGrid{_A, _B}, _D<:Terrarium.AbstractTimeStepper{_A}, var"#s179"<:Terrarium.AbstractModel{_A, _C}, NF, prognames, closurenames, auxnames, inputnames, nsnames, ProgFields, TendFields, AuxFields, InputFields, Namespaces, Cache, ClockType, _A1, _B1, NF1, name, Sources<:Tuple{Vararg{InputSource{NF1}}}}, ModelIntegrator{_A, Arch, _C, _D, var"#s179", StateVariables{NF, prognames, closurenames, auxnames, inputnames, nsnames, ProgFields, TendFields, AuxFields, InputFields, Namespaces, Cache, ClockType}, Clock{_A1, _B, Float64, Int64, Int64}, @NamedTuple{}, InputSources{NF1, name, Sources}} where {Arch<:Oceananigans.Architectures.AbstractArchitecture, _C<:Terrarium.AbstractLandGrid{_A, Arch}, _D<:Terrarium.AbstractTimeStepper{_A}, var"#s179"<:Terrarium.AbstractModel{_A, _C}, NF, prognames, closurenames, auxnames, inputnames, nsnames, ProgFields, TendFields, AuxFields, InputFields, Namespaces, Cache, ClockType, _A1, _B, NF1, name, Sources<:Tuple{Vararg{InputSource{NF1}}}}} where _A
initialize(
    model::Terrarium.AbstractModel{NF, Grid} where Grid<:(Terrarium.AbstractLandGrid{NF}),
    params;
    clock,
    inputs,
    boundary_conditions,
    initializers,
    fields
) -> Union{ModelIntegrator{_A, _B, _C, _D, var"#s179", StateVariables{NF, prognames, closurenames, auxnames, inputnames, nsnames, ProgFields, TendFields, AuxFields, InputFields, Namespaces, Cache, ClockType}, Clock{_A1, _B1, Float64, Int64, Int64}, @NamedTuple{}, InputSources{NF1, name, Sources}} where {_B<:Oceananigans.Architectures.AbstractArchitecture, _C<:Terrarium.AbstractLandGrid{_A, _B}, _D<:Terrarium.AbstractTimeStepper{_A}, var"#s179"<:Terrarium.AbstractModel{_A, _C}, NF, prognames, closurenames, auxnames, inputnames, nsnames, ProgFields, TendFields, AuxFields, InputFields, Namespaces, Cache, ClockType, _A1, _B1, NF1, name, Sources<:Tuple{Vararg{InputSource{NF1}}}}, ModelIntegrator{_A, Arch, _C, _D, var"#s179", StateVariables{NF, prognames, closurenames, auxnames, inputnames, nsnames, ProgFields, TendFields, AuxFields, InputFields, Namespaces, Cache, ClockType}, Clock{_A1, _B, Float64, Int64, Int64}, @NamedTuple{}, InputSources{NF1, name, Sources}} where {Arch<:Oceananigans.Architectures.AbstractArchitecture, _C<:Terrarium.AbstractLandGrid{_A, Arch}, _D<:Terrarium.AbstractTimeStepper{_A}, var"#s179"<:Terrarium.AbstractModel{_A, _C}, NF, prognames, closurenames, auxnames, inputnames, nsnames, ProgFields, TendFields, AuxFields, InputFields, Namespaces, Cache, ClockType, _A1, _B, NF1, name, Sources<:Tuple{Vararg{InputSource{NF1}}}}} where _A

Creates and initializes a ModelIntegrator for the given model with input variables populated by the given inputs and optionally params . InputSources can be specified via the inputs keyword argument. 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(
    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, bounds, 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::SnowEnergyTemperatureClosure,
    snow::SingleLayerSnow,
    constants::PhysicalConstants,
    args...
)

Inverse closure: compute the prognostic snow_energy from a prescribed snow_temperature (used for initialization). snow_water_equivalent must be initialized first, since the snow depth d_snow enters the depth-integrated energy.

Compute the inverse closure mapping for soil hydrology and energy, in that order.

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.

kernel(func, args...; clock = false)

Return a KernelFunction that lazily constructs a KernelFunctionOperation from the given func and tuple of args when invoked, i.e:

ctor = kerenl(my_function, arg1, arg2)
...
kfo = ctor(grid, clock, fields)

This is intended to be used as a constructor for AuxiliaryVariables:

myvar(i, j, k, grid, fields) = clamp(fields.x[i, j, k], zero(eltype(grid)), one(eltype(grid)))

auxvar = auxiliary(:myvar, XYZ(), kernel(myvar))

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.

liquid_water_fraction(_::FreeWater, U, ρLθ) -> Any

Calculate the unfrozen water content from the given internal energy U (J/m³) and volumetric latent heat content ρLθ (J/m³).

load_asset(
    asset::Terrarium.AbstractLandAsset,
    name::String;
    NF,
    fill_value
) -> Union{RingGrids.FullGaussianField{_A, _B, <:AbstractArray{T, N}, RingGrids.FullGaussianGrid{SpeedyWeatherInternals.Architectures.CPU{KernelAbstractions.CPU}, Vector{UnitRange{Int64}}, Vector{Int64}, Int64}} where {_A, _B}, RingGrids.FullClenshawField{_A, _B, <:AbstractArray{T, N}, RingGrids.FullClenshawGrid{SpeedyWeatherInternals.Architectures.CPU{KernelAbstractions.CPU}, Vector{UnitRange{Int64}}, Vector{Int64}, Int64}} where {_A, _B}}

Download (if necessary) the given asset via get_asset and read the variable name from its data file, returning a suitable Field based on the asset's native_grid with element type NF. The asset's indices are applied when reading (e.g. to select a single time record), and fill_value replaces missing data; it defaults to NF(NaN).

The underlying read is dispatched to an I/O extension based on the asset's format; load Rasters.jl and NCDatasets.jl to enable reading NetCDF and other raster files.

locate_asset_file(
    dir::String,
    format::Terrarium.FileFormat
) -> String

Locate the single data file of the given format within an installed artifact directory dir, searching recursively. Errors unless exactly one matching file is found.

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.

matches_scope(
    source::InputSource,
    scope::Tuple{Vararg{Symbol}}
) -> Union{Missing, Bool}

Determine whether the given source provides an input variable for the namespace at the given scope, where scope is the path of namespace names from the root namespace, i.e. () for the root namespace itself, (:ns1,) for its child namespace ns1, and so on.

merge_boundary_conditions(bcs::FieldBCs...)

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

merge_namespaces(namespaces)

Merge all Namespaces with matching names into a single Namespace containing the union of their variables.

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.

mineral_thermal_conductivity(conductivities, texture)

Compute the thermal conductivity of the mineral grains for the given texture as the quartz-weighted geometric mean of the quartz and non-quartz mineral endpoints ([31]; [32]):

\[\lambda_{\text{min}} = \lambda_q^{\,q} \, \lambda_o^{\,1 - q}\]

where the quartz volume fraction $q$ is assumed equal to the sand fraction.

namespace(name, vars)

Convenience constructor method for variable Namespaces.

namespaces(nt)

Convert the given NamedTuple of variables into a tuple of Namespaces.

normalize_texture!(
    sand::Oceananigans.Fields.AbstractField{LX, LY, LZ, G, NF},
    silt::Oceananigans.Fields.AbstractField{LX, LY, LZ, G, NF},
    clay::Oceananigans.Fields.AbstractField{LX, LY, LZ, G, NF};
    default
)

Normalize the given sand, silt, and clay fraction Fields in place such that the fractions sum to unity in each element, as required by the SoilTexture constructor.

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::SoilStratigraphy,
    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::SoilStratigraphy,
    bgc::Terrarium.AbstractSoilBiogeochemistry
) -> Any

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

porosity(horizon::Terrarium.AbstractSoilHorizon) -> Any

Return the porosity parameterization for the given soil horizon.

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, bounds, 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::ThermodynamicConstants, 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.

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

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

relative_to_specific_humidity(r_h, pr, T, c::ThermodynamicConstants)

Derives specific humidity from measured relative humidity r_h [%], air pressure pr [Pa], air temperature T [°C], and physical constants c. Assumes saturation over ice for T <= 0°C and over liquid water otherwise. Wrapper around q_vap_from_RH.

relaxed_update(
    relax::Terrarium.RelaxationFactor{NF},
    x_target,
    x_old
) -> Any

Apply the under-relaxed fixed-point update to the skin temperature.

Reset all tendencies in state to zero.

Compute the (numerical) residual saturation level of the soil.

resolve_timestepping(imex, progvars, model)

Resolve the timestepping class of each prognostic variable in progvars (a NamedTuple of PrognosticVariables) for the IMEX timestepper imex and owning model, returned as a tuple of Explicit/Implicit instances in the same order as progvars. Each variable's class is given by timestepping(var, model, imex).

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.

run_timesteps!(integrator, Δt, Nt, checkpointing = false)

Advance integrator by Nt steps of size Δt.

The generic (host) implementation is a plain loop and ignores checkpointing. ReactantState integrators override this method in TerrariumReactantExt, compiling the loop into a single traced program in which checkpointing selects the reverse-mode-AD checkpointing scheme (false, or a scheme such as Reactant.Periodic(n)).

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_specific_humidity_vapor(c::ThermodynamicConstants, T, ρ)

Saturation specific humidity at temperature T [°C] and density ρ [kg/m³]. Dispatches over ice for T <= 0°C and over liquid water otherwise. Wrapper around q_vap_saturation.

saturation_vapor_pressure(T)

Saturation vapor pressure of an air parcel at the given temperature T in °C. By default, the saturation vapor pressure is computed over ice for T <= 0°C and over water for T > 0°C. Wrapper around saturation_vapor_pressure.

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.

snow_cover_fraction(i, j, grid, fields, ::AbstractSnow)

Compute or retrieve the sub-grid snow-covered area fraction f_snow ∈ [0,1].

snow_density(density::ConstantSnowDensity) -> Any

Return the constant bulk snow density ρ_snow [kg/m³].

snow_density(snow::SingleLayerSnow) -> Any

Bulk snow density ρ_snow [kg/m³] of the snowpack, delegating to the process's density scheme.

snow_depth(i, j, grid, fields, ::AbstractSnow)

Compute or retrieve the snow layer depth d_snow [m].

snow_energy(i, j, grid, fields, ::AbstractSnow)

Retrieve the depth-integrated (column) snow internal energy Ū_snow [J/m²] relative to ice at 0°C.

snow_meltwater_flux(
    i,
    j,
    grid,
    fields,
    snow::SingleLayerSnow
) -> Any

Snow meltwater outflow M_r [m/s SWE] at grid cell i, j: the Darcy-type drainage (see compute_meltwater_outflow) evaluated at the diagnosed liquid water fraction.

snow_thermal_conductivity(i, j, grid, fields, ::AbstractSnow)

Compute or retrieve the bulk snow thermal conductivity κ_snow [W/m/K].

snow_water_equivalent(i, j, grid, fields, ::AbstractSnow)

Retrieve the snow water equivalent (SWE) W (m) — the total water substance (ice + retained liquid).

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

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

soil_horizon(
    i,
    j,
    k,
    grid,
    fields,
    strat::SoilStratigraphy{NF, N, Horizons} where {N, Horizons<:NTuple{N, Terrarium.AbstractSoilHorizon{NF}}}
) -> Any

Retrieve the soil horizon for the soil volume at index i, j, k. The last soil horizon in strat is assumed to extend to the bottom of the vertical column regardless of its associated thickness. Note that, since SoilStratigraphy uses namespaces for the state variables of each horizon, any methods defined on AbstractSoilHorizon types should be passed the namespace, e.g:

horizon = soil_horizon(i, j, k, grid, fields, strat)
texture = soil_texture(i, j, grid, getproperty(fields, nameof(horizon)), horizon)

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

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

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(
    grid,
    clock,
    fields,
    _::FieldCapacityLimitedPAW
) -> 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_surface_water_flux(
    i,
    j,
    grid,
    fields,
    canopy_interception::Terrarium.AbstractCanopyInterception
) -> Any
soil_surface_water_flux(
    i,
    j,
    grid,
    fields,
    canopy_interception::Terrarium.AbstractCanopyInterception,
    snow::Union{Nothing, Terrarium.AbstractSnow}
) -> Any

Meltwater flux [m/s] reaching the soil surface, accounting for the snowpack. Without snow this is just the rainfall reaching the ground; with snow the snow-covered fraction f_snow intercepts rain into the snowpack, so only the bare-ground fraction (1 − f_snow)·rain_ground reaches the soil directly, plus the snow meltwater outflow M draining from the snowpack base.

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

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

soil_texture(
    i,
    j,
    k,
    grid,
    fields,
    strat::SoilStratigraphy{NF, N, Horizons} where {N, Horizons<:NTuple{N, Terrarium.AbstractSoilHorizon{NF}}}
) -> Any

Retrieve the soil texture of the soil volume at index i, j, k in the given stratigraphy strat.

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

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

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

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

solve!(out, indices, grid, fields, objective_func!::ObjectiveFunction, solver, args...; kwargs...)

Solve the nonlinear problem defined by objective_func! for its target field at the given indices, mutating out in place. The objective returns the residual F(x) whose root is sought; on return, the target field holds the converged estimate and the method returns the root (and, for some solvers, the number of iterations performed). Dispatches on the concrete solver type, e.g. RootSolver or FixedPointSolver.

solve_skin_temperature!(
    out,
    i,
    j,
    grid,
    fields,
    skinT::ImplicitSkinTemperature,
    seb::Terrarium.AbstractSurfaceEnergyBalance,
    snow,
    seb_args...
) -> Any

Run a full nonlinear solve to determine the skin_temperature at grid cell i, j that solves the surface energy balance.

solve_surface_energy_balance!(
    state,
    grid,
    seb::SurfaceEnergyBalance{NF, SkinTemperature, TurbulentFluxes, RadiativeFluxes, Albedo} where {SkinTemperature<:Terrarium.AbstractSkinTemperature{NF}, TurbulentFluxes<:Terrarium.AbstractTurbulentFluxes{NF}, RadiativeFluxes<:Terrarium.AbstractRadiativeFluxes{NF}, Albedo<:Terrarium.AbstractAlbedo{NF}},
    constants::PhysicalConstants,
    atmos::Terrarium.AbstractAtmosphere
)
solve_surface_energy_balance!(
    state,
    grid,
    seb::SurfaceEnergyBalance{NF, SkinTemperature, TurbulentFluxes, RadiativeFluxes, Albedo} where {SkinTemperature<:Terrarium.AbstractSkinTemperature{NF}, TurbulentFluxes<:Terrarium.AbstractTurbulentFluxes{NF}, RadiativeFluxes<:Terrarium.AbstractRadiativeFluxes{NF}, Albedo<:Terrarium.AbstractAlbedo{NF}},
    constants::PhysicalConstants,
    atmos::Terrarium.AbstractAtmosphere,
    hydrology::Union{Nothing, Terrarium.AbstractSurfaceHydrology}
)
solve_surface_energy_balance!(
    state,
    grid,
    seb::SurfaceEnergyBalance{NF, SkinTemperature, TurbulentFluxes, RadiativeFluxes, Albedo} where {SkinTemperature<:Terrarium.AbstractSkinTemperature{NF}, TurbulentFluxes<:Terrarium.AbstractTurbulentFluxes{NF}, RadiativeFluxes<:Terrarium.AbstractRadiativeFluxes{NF}, Albedo<:Terrarium.AbstractAlbedo{NF}},
    constants::PhysicalConstants,
    atmos::Terrarium.AbstractAtmosphere,
    hydrology::Union{Nothing, Terrarium.AbstractSurfaceHydrology},
    snow::Union{Nothing, Terrarium.AbstractSnow},
    args...
)

Solve the surface energy balance for skin temperature on grid based on the current atmospheric and surface hydrology state.

specific_heat_capacity_moist_air(c::ThermodynamicConstants, q)

Compute the isobaric specific heat capacity [J/(kg*K)] of moist air as a function of the total specific humidity q [kg/kg]. Wrapper around cp_m.

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

Retrieve or compute the specific_humidity at the current time step.

specific_humidity_difference(
    c::ThermodynamicConstants,
    p,
    q_air,
    T
) -> Any

Computes the difference in specific humidity between a saturated surface at temperature T [°C] and the atmosphere, defined by its specific humidity q_air [kg/kg] and pressure p [Pa].

stefan_boltzmann(c::UniversalConstants, T, ϵ)

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

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.

temperature_to_energy!(
    out,
    i,
    j,
    grid,
    fields,
    _::SnowEnergyTemperatureClosure,
    snow::SingleLayerSnow,
    constants::PhysicalConstants
)

Compute the depth-integrated snow energy from a prescribed temperature at grid cell 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, timestepper::AbstractIMEX, Δt)

Advance the model forward by one timestep of size Δt using an AbstractIMEX timestepper. Each prognostic variable is routed to the explicit or implicit sub-stepper according to the resolved classes stored in the IMEXCache type; each sub-stepper fetches its own sub-cache via get_cache. The clock is advanced once for the whole step.

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

Advance the model forward by one timestep of size Δt using a single timestepper, which integrates all prognostic variables. Dispatches on the timestepper's timestepping trait (Explicit/Implicit) to timestep!(integrator, timestepper, ::Timestepping, Δt).

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

Trait-dispatched single-timestepper step: forward the prognostic variable names to the scheme's timestep!(integrator, timestepper, Δt, names) method and advance the clock once for the whole step.

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.

timestepping(timestepper::AbstractTimeStepper)::Timestepping

Return the Timestepping trait — Explicit or Implicit — of the given timestepper. Every concrete timestepper must define this trait (e.g. timestepping(::ForwardEuler) = Explicit()); there is no default so that a new scheme declares its class explicitly. It is used, among other things, to route each sub-stepper of an AbstractIMEX to its slice of the IMEXCache.

timestepping(var::AbstractVariable, model::AbstractModel, timestepper::AbstractTimeStepper)::Timestepping

Return the Timestepping class with which the prognostic variable var of model is integrated under timestepper. Defaults to Explicit() for all variables; specialize this method (typically on an AbstractIMEX timestepper together with particular variable and/or model types) to route selected variables to the implicit sub-stepper.

timestepping(cache::IMEXCache)

Return the resolved timestepping class of every prognostic variable (a tuple of Explicit/Implicit instances, in prognostic-variable order) held in the IMEXCache type parameter.

transpiration_conductance(
    _::PALADYNCanopyEvapotranspiration{NF},
    rₐ,
    g_stm
) -> Any

Compute the transpiration vapor conductance [m/s] from aerodynamic resistance rₐ and stomatal conductance g_stm. The transpiration flux is this conductance times the humidity gradient.

tuplejoin()

Concatenate one or more tuples together.

Update input variables from the given input sources. The scope corresponds to the path of namespace names from the root namespace to state and is used to match namespaced input sources to their target variables; see varpath.

update_inputs!(inputs, grid, clock, fields, _::InputSource)

Updates the values of the input variables stored in inputs from the given input source, called at every time step. The grid and the full model state fields (read-only) are provided so that sources may compute their inputs from the grid geometry or other state variables. Namespace routing is handled by the caller (see [InputSources]). Default implementation returns nothing.

vapor_pressure_deficit(c, T, pres, q_air)

Computes the vapor pressure deficit for an air parcel at temperature T [°C] with pressure pres [Pa] and specific humidity q_air [kg/kg]. Assumes that air parcel is over water when T > 0°C and over ice when T < 0°C. Wrapper around vapor_pressure_deficit.

vapor_pressure_difference(
    c::ThermodynamicConstants,
    p,
    q_air,
    T
) -> Any

Computes the difference in vapor pressure between a saturated surface at temperature T [°C] and the atmosphere, defined by its specific humidity q_air [kg/kg] and pressure p [Pa]. Relies on Thermodynamics.jl via partial_pressure_vapor and saturation_vapor_pressure.

vapor_pressure_to_specific_humidity(c::ThermodynamicConstants, e, pr)

Derives specific humidity from measured vapor pressure e [Pa] and air pressure pr [Pa].

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{Union{Terrarium.InputVariable{_A, VD, UT, _B, DomainSets.RealLine{Float64}, Nothing} where {_A, VD<:Terrarium.VarDims, UT<:Unitful.Units, _B<:Terrarium.Variable{_A, VD, UT}}, Terrarium.Namespace}}

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(source::InputSource)

Returns the name of the input variable provided by this source, i.e. the last entry of its varpath.

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.

varpath(name::Symbol)
varpath(path::Pair)
varpath(path::Tuple{Vararg{Symbol}})

Normalize the given variable name into a path of the form (namespace_1, ..., namespace_N, varname). Plain Symbol names correspond to variables in the root namespace, i.e. the path (varname,). Namespaced variables can be specified either as Pairs, e.g. :ns1 => :ns2 => :varname, or directly as a tuple of Symbols, e.g. (:ns1, :ns2, :varname).

varunits(var)

Retrieve the physical units for the given variable.

vegetation_area_fraction(i, j, grid, fields, ::AbstractVegetationDynamics)

Return the fraction of the grid cell i, j covered by vegetation of any type.

volumetric_fractions(soil::SoilComposition) -> NamedTuple

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

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.

with_scope(path, var)

Wrap the given variable var in nested Namespaces according to the path, where path is the namespace scope (i.e. the sequence of enclosing namespace names, excluding the variable's own name). An empty path returns var unwrapped.

with_soil_horizon(
    func,
    i,
    j,
    k,
    grid,
    fields,
    strat::SoilStratigraphy,
    args...;
    kwargs...
) -> Any

Convenience method that invokes func(i, j, grid, horizon_fields, horizon, args...; kwargs...) where horizon is the soil horizon returned by soil_horizon and horizon_fields is getproperty(fields, nameof(horizon)).

(::Type{Model})(grid::AbstractLandGrid; kwargs...) where {Model <: AbstractModel}

Convenience constructor for all AbstractModel types that accepts grid as a 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.

abstract type AbstractEnergyClosure <: Terrarium.AbstractClosureRelation

Base type for closure relations between internal energy and temperature in a material volume.

Base type for evapotranspiration processes.

Base type for evaporation resistance parameterizations.

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 AbstractIMEX{NF} <: Terrarium.AbstractTimeStepper{NF}

Base type for implicit-explicit (IMEX) time steppers. An AbstractIMEX integrates each prognostic variable with one of two sub-steppers depending on its timestepping class: variables of class Explicit are stepped by the explicit sub-stepper and those of class Implicit by the implicit sub-stepper.

Concrete subtypes (e.g. IMEX) must provide the explicit and implicit sub-steppers via explicit_timestepper and implicit_timestepper; most other behavior is defined here against AbstractIMEX.

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.

abstract type AbstractLandAsset

Lightweight base type for Terrarium land data assets.

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

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 AbstractSnow{NF} <: Terrarium.AbstractCoupledProcesses{NF}

Base type for coupled snow processes. Implementations should typically couple an energy balance and a mass (water equivalent) balance for a snowpack overlying the ground surface. Snow is modeled as its own coupled process (a sibling of soil), reusing the medium-agnostic FreeWater enthalpy relations for the energy↔temperature closure (the same closure used for the soil; see Soil energy balance).

abstract type AbstractSnowCover{NF}

Base type for snow areal-coverage parameterizations.

abstract type AbstractSnowDensity{NF}

Base type for snow density schemes.

abstract type AbstractSnowHydraulics{NF}

Base type for snow hydraulic properties and parameterization schemes.

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

Base type for snow models.

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

Base type for coupled soil processes.

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

Base type for soil biogeochemistry process implementations.

abstract type AbstractSoilHorizon{NF, name}

Base type for soil "horizons", i.e. vertical segments of soil with homogeneous soil properties and a user-defined name.

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.AbstractModel{NF, GR}

Base type for soil models.

abstract type AbstractSoilPorosity{NF}

Base type for parameterizations of soil porosity.

abstract type AbstractSoilThermodynamics{NF} <: Terrarium.AbstractThermodynamics{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. Soil energy balances evolve the soil internal energy and therefore subtype AbstractThermodynamics.

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

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

Base type for energy balance process implementations that evolve the internal energy of a solid or porous material medium.

Base type for time steppers.

abstract type AbstractTimeStepperCache{NF}

Base type for time stepper caches. Each AbstractTimeStepper allocates a corresponding AbstractTimeStepperCache subtype (via initialize) to hold any working state it needs between stages/steps.

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 AbstractVegetation{NF} <: Terrarium.AbstractCoupledProcesses{NF}

Base type for coupled vegetation (carbon) processes.

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}, BT<:IntervalSets.AbstractInterval, FC} <: 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

BareGroundEvaporation{NF, GR} <: AbstractEvapotranspiration

Evaporation scheme for bare ground that calculates the humidity flux as

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

where Δq is the specific humidity difference, rₐ is aerodynamic resistance, and β is an evaporation limiting factor.

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 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 ConstantSnowAlbedo{NF}

Basic constant albedo scheme for snow that treats both albedo and emissivity as both spatially and temporally constants. The default values are for freshly fallen snow, taken from [12].

struct ConstantSnowDensity{NF} <: Terrarium.AbstractSnowDensity{NF}

Constant, spatially homogeneous bulk snow density ρ_snow. This is the default (and currently only) snow density scheme for SingleLayerSnow. Default bulk snow density follows [12].

Properties:

• density::Any: Bulk snow density ρ_snow

References

• [12] Westermann et al., Geoscientific Model Development (2016)

struct ConstantSnowHydraulics{NF} <: Terrarium.AbstractSnowHydraulics{NF}

Constant, spatially homogeneous snow hydraulic properties: a saturated hydraulic conductivity K_sat and a capillary retention L_c, setting the Darcy-type meltwater outflow (see compute_meltwater_outflow). Default values follow [3].

Properties:

• saturated_conductivity::Any: Hydraulic conductivity at saturation

• capillary_retention::Any: Capillary retention liq_c: liquid fraction held against gravity before meltwater drains

References

• [3] Tarboton, Chowdhury and Jackson (1994)

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

• ρ_org::Any: Pure organic matter density

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

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

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 saturated_conductivity

• saturated_conductivity::Any: Hydraulic conductivity at saturation

• field_capacity::Any: Constant field capacity

• wilting_point::Any: Constant wilting point

• residual::Any: Residual (minimum) saturation level

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 DiagnosticAlbedo{NF} <: Terrarium.AbstractAlbedo{NF}

Diagnosed surface albedo and emissivity. The values are computed in compute_auxiliary! as a snow-cover-weighted blend of a snow-free background and snow, α = (1 − f_snow)·α_bg + f_snow·α_snow (and likewise for emissivity), where f_snow is the snow-covered area fraction of the optional snow component passed to compute_auxiliary!. Without a snow component (snow === nothing), f_snow = 0 and the background values are used.

Properties:

• background_albedo::Any: Snow- and vegetation-free (background) albedo of bare ground

• background_emissivity::Any: Snow- and vegetation-free (background) emissivity of bare ground

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 ERA5LandForcings <: Terrarium.AbstractLandAsset

One year of ERA5-Land hourly meterological variables regridded to approximately 1° x 1° resolution (72 Gaussian rings).

struct ERA5LandInvariants <: Terrarium.AbstractLandAsset

Time-invariant spatial fields from ERA5-Land at the native 0.1° x 0.1° resolution.

struct ERA5LandLeafAreaIndex <: Terrarium.AbstractLandAsset

Leaf area index daily climatology for 1980-2010 from ERA5-Land at the native 0.1° x 0.1° resolution.

struct EmptyCache{NF} <: Terrarium.AbstractTimeStepperCache{NF}

Trivial cache for time steppers that require no working state (e.g. ForwardEuler).