API Reference

SurfaceFluxes

Interface

• surface_conditions computes
  • Monin-Obukhov length
  • Potential temperature flux (if not given) using Monin-Obukhov theory
  • transport fluxes using Monin-Obukhov theory
  • friction velocity/temperature scale/tracer scales
  • exchange coefficients

References

• [1]
• [2]

StateValues

Input container for state variables at either first / interior nodes.

Fields

• z::FT: Height [m]
• u::A: Wind velocity vector
• ts::TS: Thermodynamic state
• args::NT: Additional arguments (optional)

Fluxes

Input container for state variables, latent and sensible heat fluxes roughness lengths, initial obukhov length and gustiness.

Fields

• state_in::SVA: State values at interior/input height
• state_sfc::SVB: State values at surface
• shf::FT: Sensible heat flux [W/m²]
• lhf::FT: Latent heat flux [W/m²]
• z0m::FT: Momentum roughness length [m]
• z0b::FT: Scalar (heat/moisture) roughness length [m]
• gustiness::FT: Gustiness parameter [m/s]
• roughness_model::RM: Roughness model type

FluxesAndFrictionVelocity

Input container, given surface state variables, latent and sensible heat fluxes, and the friction velocity, roughness lengths, initial obukhov length and gustiness.

Fields

• state_in::SVA: State values at interior/input height
• state_sfc::SVB: State values at surface
• shf::FT: Sensible heat flux [W/m²]
• lhf::FT: Latent heat flux [W/m²]
• ustar::FT: Friction velocity [m/s]
• z0m::FT: Momentum roughness length [m]
• z0b::FT: Scalar (heat/moisture) roughness length [m]
• gustiness::FT: Gustiness parameter [m/s]
• roughness_model::RM: Roughness model type

Coefficients

Input container, given surface state variables, and exchange coefficients,roughness lengths, initial obukhov length and gustiness.

Fields

• state_in::SVA: State values at interior/input height
• state_sfc::SVB: State values at surface
• Cd::FT: Momentum exchange coefficient
• Ch::FT: Heat exchange coefficient
• gustiness::FT: Gustiness parameter [m/s]
• beta::FT: Evaporation efficiency factor
• roughness_model::RM: Roughness model type

ValuesOnly

Input container, given only surface state variables, roughness lengths, initial obukhov length and gustiness.

Fields

• state_in::SVA: State values at interior/input height
• state_sfc::SVB: State values at surface
• z0m::FT: Momentum roughness length [m]
• z0b::FT: Scalar (heat/moisture) roughness length [m]
• gustiness::FT: Gustiness parameter [m/s]
• beta::FT: Evaporation efficiency factor
• roughness_model::RM: Roughness model type

surface_conditions(
    param_set::AbstractSurfaceFluxesParameters,
    sc::SurfaceFluxes.AbstractSurfaceConditions,
    scheme::SurfaceFluxes.SolverScheme = PointValueScheme();
    tol_neutral = SFP.cp_d(param_set) / 100,
    tol = sqrt(eps(FT)),
    maxiter::Int = 10,
)

The main user-facing function of the module. Computes surface conditions based on Monin-Obukhov similarity theory.

Arguments

• param_set: Parameter set containing physical and thermodynamic constants
• sc: Surface conditions container (Fluxes, ValuesOnly, Coefficients, or FluxesAndFrictionVelocity)
• scheme: Discretization scheme (PointValueScheme for finite difference or LayerAverageScheme for finite volume)
• tol_neutral: Tolerance for neutral stability detection based on ΔDSEᵥ (default: cp_d / 100)
• tol: Convergence tolerance for iterative solver (default: sqrt(eps(FT)))
• maxiter: Maximum number of iterations (default: 10)

Returns

Returns a SurfaceFluxConditions struct containing:

• L_MO: Monin-Obukhov lengthscale [m]
• shf: Sensible heat flux [W/m²]
• lhf: Latent heat flux [W/m²]
• ρτxz: Momentum flux, eastward component [kg/(m·s²)]
• ρτyz: Momentum flux, northward component [kg/(m·s²)]
• ustar: Friction velocity [m/s]
• Cd: Momentum exchange coefficient
• Ch: Heat exchange coefficient
• E: Evaporation rate [kg/(m²·s)]

recover_profile(param_set, sc, L_MO, Z, X_in, X_sfc, transport, scheme)

Recover profiles of variable X given values of Z coordinates. Follows Nishizawa equation (21,22)

Arguments

• param_set: Abstract Parameter Set containing physical, thermodynamic parameters.
• sc: Container for surface conditions based on known combination of the state vector, and {fluxes, friction velocity, exchange coefficients} for a given experiment
• L_MO: Monin-Obukhov length
• Z: Z coordinate(s) (within surface layer) for which variable values are required
• X_star: Scale parameter for variable X
• X_sfc: For variable X, values at surface nodes
• transport: Transport type, (e.g. Momentum or Heat, used to determine physical scale coefficients)
• scheme: Discretization scheme (currently supports FD and FV)

UniversalFunctions

Universal stability and stability correction functions for SurfaceFluxes module. Supports the following universal functions:

• Businger: Businger et al. (1971), Dyer (1974)
• Gryanik: Gryanik et al. (2020)
• Grachev: Grachev et al. (2007)

BusingerParams{FT}

Parameter bundle for the Businger (1971) similarity relations. Mappings to Nishizawa & Kitamura (2018) coefficients:

• a_m, a_h: The linear coefficients for stable conditions (β in some texts).
• b_m, b_h: The coefficients γ inside the unstable sqrt/cbrt terms (e.g., (1 - γζ)).
• Pr_0: The neutral Prandtl number.

See Businger et al. (1971) and Nishizawa & Kitamura (2018).

GryanikParams{FT}

Parameter bundle for the Gryanik et al. (2020) similarity relations. These functions are designed to be valid across the entire stability range, including very stable conditions.

• a_m, b_m: Coefficients for momentum stability function (Eq. 32).
• a_h, b_h: Coefficients for heat stability function (Eq. 33).
• Pr_0: Neutral Prandtl number. (The paper recommends Pr_0 ≈ 0.98.)

Reference: Gryanik et al. (2020).

GrachevParams{FT}

Parameter bundle for the Grachev et al. (2007) similarity relations, based on SHEBA data.

• a_m, b_m: Coefficients for momentum stability function (Eq. 9a).
• a_h, b_h, c_h: Coefficients for heat stability function (Eq. 9b). Note: c_h is the coefficient for the linear ζ term in the denominator.

Reference: Grachev et al. (2007).

MomentumTransport

Type selecting momentum-transfer stability functions (ϕₘ, ψₘ, Ψₘ).

HeatTransport

Type selecting heat-transfer stability functions (ϕₕ, ψₕ, Ψₕ).

phi

Universal stability function for wind shear (ϕ_m) and temperature gradient (ϕ_h)

psi(p, ζ, transport_type)

The standard integrated stability correction function ψ(ζ). Defined as: ψ(ζ) = ∫0 to ζ / x dx

This is the standard correction used in point-based Monin-Obukhov similarity theory. Note that while ϕ(0) is typically 1, it may differ (e.g. ϕh(0) = Pr0 in Gryanik et al., 2020).

Psi(p, ζ, transport_type)

The volume-averaged stability correction function Ψ(ζ). Mathematically, this is defined as: Ψ(ζ) = (1/ζ) ∫[0 to ζ] ψ(x) dx

This function is required for finite-volume models where fluxes are calculated using cell-averaged values rather than point values at the cell center.

See Nishizawa & Kitamura (2018), Eqs. 14 & 15.