API Reference

surface_fluxes(
    param_set::APS,
    T_int,
    q_tot_int,
    q_liq_int,
    q_ice_int,
    ρ_int,
    T_sfc_guess,
    q_vap_sfc_guess,
    Φ_sfc,
    Δz,
    d,
    u_int = (0, 0),
    u_sfc = (0, 0),
    roughness_inputs = nothing,
    config = default_surface_flux_config(eltype(param_set)),
    scheme::SolverScheme = PointValueScheme(),
    solver_opts = nothing,
    flux_specs = nothing,
    update_T_sfc = nothing,
    update_q_vap_sfc = nothing,
)

Core entry point for calculating surface fluxes using Monin-Obukhov Similarity Theory (MOST).

Functionality

Calculates sensible heat flux, latent heat flux, momentum flux (stress), and friction velocity.

Can operate in four modes depending on inputs:

1. Prescribed Coefficients: If Cd and Ch are provided in flux_specs, fluxes are computed directly.
2. Fully Prescribed Fluxes: If shf, lhf, and ustar are provided, they are validated and the fluxes are returned.
3. Prescribed Heat and Drag: If shf, lhf, and Cd are provided, ustar is derived from Cd and wind speed.
4. Iterative Solver: Otherwise, iterates to find the Obukhov stability parameter ζ. Optional functions can be provided to calculate the skin temperature and skin humidity during the iteration.

Arguments

• param_set: SurfaceFluxes parameters (containing thermodynamics and universal function params).
• T_int: Interior (air) temperature [K] at height z.
• q_tot_int: Interior total specific humidity [kg/kg].
• q_liq_int, q_ice_int: Interior liquid/ice specific humidity [kg/kg].
• ρ_int: Interior air density [kg/m^3].
• T_sfc_guess: Initial guess for surface temperature [K], updated via callback if provided.
• q_vap_sfc_guess: Initial guess for surface vapor specific humidity [kg/kg], updated via callback if provided.
• Φ_sfc: Surface geopotential [m^2/s^2].
• Δz: Geometric height difference between the surface and the interior level [m], used for geopotential.
• d: Displacement height [m]. Aerodynamic calculations (MOST) use effective height Δz - d.
• u_int: Tuple of interior wind components (u, v) [m/s].
• u_sfc: Tuple of surface wind components (u, v) [m/s]. (Usually (0, 0)).
• roughness_inputs: Optional container of parameters (e.g., LAI, canopy height) that are passed directly to the specific roughness model (e.g., RaupachRoughnessParams).
• config: SurfaceFluxConfig struct containing:
  • roughness: Model for roughness lengths (e.g., ConstantRoughnessParams, COARE3RoughnessParams). Note: This package currently assumes the roughness length for heat (z0h) is equal to the roughness length for scalars (z0s).
  • gustiness: Model for gustiness (e.g., ConstantGustinessSpec).
  • moisture_model: DryModel or MoistModel.
• scheme: Discretization scheme (PointValueScheme or LayerAverageScheme).
• solver_opts: Options for the root solver (maxiter, tol, rtol, forced_fixed_iters).
• flux_specs: Optional FluxSpecs to prescribe specific constraints (e.g., ustar, shf, Cd).
• update_T_sfc: Optional callback f(T_sfc) to update surface temperature during iteration.
• update_q_vap_sfc: Optional callback f(q_vap) to update surface humidity during iteration.

Returns

A SurfaceFluxConditions struct containing:

• shf: Sensible Heat Flux [W/m^2].
• lhf: Latent Heat Flux [W/m^2].
• evaporation: Evaporation rate [kg/m^2/s].
• ustar: Friction velocity [m/s].
• ρτxz, ρτyz: Momentum flux components (stress) [N/m^2].
• ζ: Stability parameter (z-d)/L [-].
• Cd: Drag coefficient [-].
• g_h: Heat conductance [m/s].
• T_sfc, q_vap_sfc: Final iterated surface temperature [K] and vapor specific humidity [kg/kg].
• L_MO: Monin-Obukhov length [m].
• converged: Convergence status.

surface_fluxes(param_set, inputs, scheme=PointValueScheme(), solver_opts=nothing)

Dispatch to the appropriate solver mode based on the availability of inputs (coefficients, fluxes, or state).

SurfaceFluxConditions{FT}

Surface flux conditions returned by surface_fluxes.

All floating-point fields share the type FT, obtained by promoting the inputs. Momentum-flux components are the kinematic stress times density, i.e. ρτ = ρ u_* u_*, with units [kg/(m·s²)] = [N/m²].

Fields

• shf: Sensible heat flux [W/m²].
• lhf: Latent heat flux [W/m²].
• evaporation: Evaporation rate [kg/(m²·s)].
• ρτxz: Momentum flux, eastward component [kg/(m·s²)].
• ρτyz: Momentum flux, northward component [kg/(m·s²)].
• ustar: Friction velocity [m/s].
• ζ: Monin-Obukhov stability parameter (z - d)/L [-].
• Cd: Momentum exchange (drag) coefficient [-].
• g_h: Heat conductance Ch * U_eff [m/s].
• T_sfc: Surface temperature [K].
• q_vap_sfc: Surface air vapor specific humidity [kg/kg].
• L_MO: Monin-Obukhov length [m].
• converged: Solver convergence status.

SurfaceFluxConfig

Configuration for surface flux calculation components.

Fields

• roughness: The roughness length parameterization to use (e.g., ConstantRoughnessParams).
• gustiness: The gustiness parameterization to use (e.g., ConstantGustinessSpec).
• moisture_model: The moisture model (e.g., MoistModel or DryModel).

FluxSpecs{FT}

Container for prescribed surface flux boundary conditions.

Fields

• shf: Sensible Heat Flux [W/m^2].
• lhf: Latent Heat Flux [W/m^2].
• ustar: Friction velocity [m/s].
• Cd: Momentum exchange coefficient.
• Ch: Heat exchange coefficient.

SolverOptions{FT}

Options for the Monin-Obukhov similarity theory solver.

Fields

• tol: Absolute tolerance on the change in the stability parameter for determining convergence.
• rtol: Relative tolerance on the change in the stability parameter for determining convergence.
• maxiter: Maximum number of iterations.
• forced_fixed_iters: If true, disables the tolerance check and forces the solver to run for exactly maxiter iterations (or until machine precision is reached/bypassed). Default is true.

SolverScheme

Abstract type for surface flux solver schemes.

PointValueScheme <: SolverScheme

Standard finite difference scheme using point values.

LayerAverageScheme <: SolverScheme

Finite volume approximation scheme following Nishizawa & Kitamura (2018).

Supported with BusingerParams and GryanikParams. Not supported with GrachevParams (use PointValueScheme instead).

compute_profile_value(param_set, L_MO, z0, Δz_eff, scale, val_sfc, transport, scheme)

Compute the (nondimensional) value of a variable (momentum or scalar) at effective aerodynamic height Δz_eff (height above surface minus displacement height).

Arguments

• param_set: Parameter set.
• L_MO: Monin-Obukhov length [m].
• z0: Roughness length [m].
• Δz_eff: Effective aerodynamic height z - d [m].
• scale: Similarity scale (ustar, thetastar, etc.).
• val_sfc: Surface value of the variable.
• transport: Transport type (MomentumTransport or HeatTransport).
• scheme: Discretization scheme (default: PointValueScheme()).

Formula:

X(Δz_eff) = (scale / κ) * F_z + val_sfc

where F_z is the dimensionless profile at height Δz_eff.

build_surface_flux_inputs(args...)

Centralized helper that normalizes user-facing specifications (winds, roughness, gustiness, flux constraints) into a NamedTuple containing inputs for surface flux calculations. Input types are preserved (no promotion), and users should ensure consistent input types for best performance.

Returns

A NamedTuple with the following fields:

Atmospheric and Surface State

• T_int: Interior air temperature [K]
• q_tot_int: Interior total specific humidity [kg/kg]
• q_liq_int: Interior liquid specific humidity [kg/kg]
• q_ice_int: Interior ice specific humidity [kg/kg]
• ρ_int: Interior air density [kg/m³]
• T_sfc_guess: Initial guess for surface temperature [K]. Can be nothing for default fallback.
• q_vap_sfc_guess: Initial guess for surface vapor specific humidity [kg/kg]. Can be nothing for default fallback.

Geometry

• Φ_sfc: Surface geopotential [m²/s²]
• Δz: Height difference between interior and surface reference levels [m]
• d: Displacement height [m]

Wind

• u_int: Horizontal wind components (u, v) at the interior level, as a tuple [m/s].
• u_sfc: Horizontal wind components (u, v) at the surface level, as a tuple [m/s].

Parameterizations

• roughness_model: Roughness parameterization, e.g. ConstantRoughnessParams.
• gustiness_model: Gustiness parameterization, e.g. ConstantGustinessSpec.
• moisture_model: Moisture model, MoistModel or DryModel.
• roughness_inputs: Optional inputs for roughness models.

Callbacks and Prescribed Values

• update_T_sfc: Optional callback to update surface temperature during iteration.
• update_q_vap_sfc: Optional callback to update surface vapor specific humidity during iteration.
• shf: Prescribed sensible heat flux from FluxSpecs; may be nothing [W/m²].
• lhf: Prescribed latent heat flux from FluxSpecs; may be nothing [W/m²].
• ustar: Prescribed friction velocity from FluxSpecs; may be nothing [m/s].
• Cd: Prescribed momentum exchange coefficient from FluxSpecs; may be nothing.
• Ch: Prescribed heat exchange coefficient from FluxSpecs; may be nothing.

shf = sensible_heat_flux(param_set, inputs, g_h, T_int, T_sfc, ρ_sfc, E)

Computes the sensible heat flux at the surface.

The sensible heat flux is given by

SHF = -ρ_sfc * g_h * ΔDSE + VSE_sfc * E

where ΔDSE = DSE_int - DSE_sfc is the difference in dry static energy between the interior and surface, g_h is the heat/moisture conductance, VSE_sfc is the dry static energy of water vapor at the surface temperature, and E is the evaporation rate. The second term, VSE_sfc * E, accounts for the vapor static energy VSE_sfc = cp_v * (T_sfc - T_0) + Φ_sfc (i.e., dry enthalpy cp_v * (T_sfc - T_0), or sensible heat, plus potential energy Φ_sfc) carried by evaporating water.

If inputs.shf is provided (not nothing), the function returns that value directly, allowing for prescribed sensible heat flux conditions. See the inputs container.

Arguments

• param_set: Parameter set.
• inputs: The inputs container. See build_surface_flux_inputs.
• g_h: Heat/moisture conductance [m/s].
• T_int: Interior temperature [K].
• T_sfc: Surface temperature [K].
• ρ_sfc: Surface air density [kg/m^3].
• E: Evaporation rate [kg/m^2/s]. Optional, default 0.

sensible_heat_flux(param_set, ζ, ustar, inputs, z0m, z0h, T_sfc, q_vap_sfc, ρ_sfc, scheme)

Computes the sensible heat flux given the Monin-Obukhov stability parameter ζ, friction velocity ustar, roughness lengths, and surface state. Useful for computing fluxes from variables available inside the solver loop.

Arguments

• param_set: Parameter set.
• ζ: Monin-Obukhov stability parameter.
• ustar: Friction velocity [m/s].
• inputs: The inputs container. See build_surface_flux_inputs.
• z0m: Momentum roughness length [m].
• z0h: Thermal roughness length [m].
• T_sfc: Surface temperature [K].
• q_vap_sfc: Surface vapor specific humidity [kg/kg].
• ρ_sfc: Surface air density [kg/m^3].
• scheme: Discretization scheme.

latent_heat_flux(param_set, inputs, E, model)

Computes the latent heat flux at the surface.

The latent heat flux is given by

LHF = LH_v0 * E

where LH_v0 is the latent heat of vaporization at the reference temperature and E is the evaporation rate.

If inputs.lhf is provided (not nothing), the function returns that value directly, allowing for prescribed latent heat flux conditions.

Arguments

• param_set: Parameter set.
• inputs: The inputs container. See build_surface_flux_inputs.
• E: Evaporation rate [kg/m^2/s].
• model: Moisture model (MoistModel or DryModel).

latent_heat_flux(param_set, ζ, ustar, inputs, z0m, z0h, q_vap_sfc, ρ_sfc, scheme)

Computes the latent heat flux given the Monin-Obukhov stability parameter ζ, friction velocity ustar, roughness lengths, and surface state. Calculates conductance and evaporation internally.

Arguments

• param_set: Parameter set.
• ζ: Monin-Obukhov stability parameter.
• ustar: Friction velocity [m/s].
• inputs: The inputs container. See build_surface_flux_inputs.
• z0m: Momentum roughness length [m].
• z0h: Thermal roughness length [m].
• q_vap_sfc: Surface vapor specific humidity [kg/kg].
• ρ_sfc: Surface air density [kg/m^3].
• scheme: Discretization scheme.

buoyancy_flux(param_set, shf, lhf, T_sfc, ρ_sfc, q_vap_sfc, q_liq_sfc, q_ice_sfc, model)

Computes the buoyancy flux at the surface, accounting for the presence of liquid and ice condensate.

The buoyancy flux B is defined as the vertical flux of virtual potential temperature θ_v. It is approximated by linearizing the density perturbations with respect to temperature and total water content:

B ≈ (g / ρ_sfc) * ( SHF / (cp_m * T_sfc) + (ε_vd - 1) * LHF / LH_v0 )

Where:

• cp_m is the specific heat of moist air, calculated using q_tot_sfc, q_liq_sfc, and q_ice_sfc.
• ε_vd is the ratio of gas constants for water vapor and dry air.
• The term (ε_vd - 1) (approximately 0.61) represents the density effect of water vapor relative to dry air (the virtual temperature correction factor), ensuring the buoyancy flux accounts for the fact that moist air is lighter than dry air.

Arguments

• param_set: Parameter set.
• shf: Sensible heat flux [W/m²].
• lhf: Latent heat flux [W/m²].
• T_sfc: Surface temperature [K].
• ρ_sfc: Surface air density [kg/m³].
• q_vap_sfc: Surface water vapor specific humidity; default 0 [kg/kg].
• q_liq_sfc: Surface liquid water specific humidity; default 0 [kg/kg].
• q_ice_sfc: Surface ice specific humidity; default 0 [kg/kg].
• model: Moisture model (MoistModel or DryModel).

buoyancy_flux(param_set, ζ, ustar, inputs)

Computes the buoyancy flux given the Monin-Obukhov stability parameter ζ, friction velocity ustar, and geometric inputs via the inputs container.

The relationship is derived from the definition of the Obukhov length:

L = -u_*^3 / (κ * B)
ζ = Δz / L
=> B = -(u_*^3 * ζ) / (κ * Δz)

Arguments

• param_set: Parameter set.
• ζ: Monin-Obukhov stability parameter.
• ustar: Friction velocity [m/s].
• inputs: The inputs container. See build_surface_flux_inputs.

E = evaporation(param_set, inputs, g_h, q_vap_int, q_vap_sfc, ρ_sfc, model)

Computes the evaporation rate at the surface.

The evaporation rate is given by

E = -ρ_sfc * g_h * Δq_vap

where Δq_vap = q_vap_int - q_vap_sfc is the difference in vapor specific humidity between the interior and surface, g_h is the heat/moisture conductance (heat and moisture conductances must be equal for energetic consistency), and ρ_sfc is the surface air density. Here q_vap_int and q_vap_sfc are the vapor specific humidities (not total specific humidity) at the interior and surface, respectively.

If inputs.lhf is provided (not nothing), the function returns the evaporation rate computed from the prescribed latent heat flux: E = LHF / LH_v0, where LH_v0 is the latent heat of vaporization at the reference temperature.

Arguments

• param_set: Parameter set.
• inputs: The inputs container. See build_surface_flux_inputs.
• g_h: Heat conductance [m/s].
• q_vap_int: Interior vapor specific humidity [kg/kg].
• q_vap_sfc: Surface vapor specific humidity [kg/kg].
• ρ_sfc: Surface density [kg/m^3].
• model: Moisture model (MoistModel or DryModel).

evaporation(param_set, ζ, ustar, inputs, z0m, z0h, q_vap_sfc, ρ_sfc, scheme)

Computes the evaporation rate given the Monin-Obukhov stability parameter ζ, friction velocity ustar, roughness lengths, and surface state.

Arguments

• param_set: Parameter set.
• ζ: Monin-Obukhov stability parameter.
• ustar: Friction velocity [m/s].
• inputs: The inputs container. See build_surface_flux_inputs.
• z0m: Momentum roughness length [m].
• z0h: Thermal roughness length [m].
• q_vap_sfc: Surface vapor specific humidity [kg/kg].
• ρ_sfc: Surface air density [kg/m^3].
• scheme: Discretization scheme.

momentum_fluxes(Cd, inputs, ρ_sfc, gustiness)

Computes the momentum fluxes at the surface.

The momentum fluxes are calculated using the bulk aerodynamic formula:

ρτxz = -ρ_sfc * Cd * ΔU * Δu_x
ρτyz = -ρ_sfc * Cd * ΔU * Δu_y

where:

• Cd: Momentum exchange coefficient (drag coefficient)
• ΔU: Magnitude of the wind speed difference (including gustiness)
• Δu_x, Δu_y: Components of the wind speed difference
• ρ_sfc: Surface air density

Returns a tuple (ρτxz, ρτyz).

See the inputs container.

Arguments

• Cd: Drag coefficient.
• inputs: The inputs container. See build_surface_flux_inputs.
• ρ_sfc: Surface air density [kg/m^3].
• gustiness: Gustiness velocity scale [m/s].

state_bulk_richardson_number(param_set, inputs, T_sfc, ρ_sfc, ΔU, q_vap_sfc)

Computes the bulk Richardson number from the given state.

Arguments

• param_set: Parameter set.
• inputs: The inputs container. See build_surface_flux_inputs.
• T_sfc: Surface temperature [K].
• ρ_sfc: Surface air density [kg/m³].
• ΔU: Wind speed difference [m/s].
• q_vap_sfc: Surface vapor specific humidity [kg/kg]. Default: 0.

Returns the bulk Richardson number.

drag_coefficient(param_set, ζ, z0m, Δz_eff, scheme)

Compute the drag coefficient Cd for momentum exchange.

Arguments

• param_set: Parameter set
• ζ: Stability parameter ζ = Δz_eff / L_MO
• z0m: Roughness length for momentum [m]
• Δz_eff: Effective aerodynamic height Δz - d [m]
• scheme: Surface flux solver scheme (default: PointValueScheme())

Formula:

Cd = (κ / F_m)^2

where F_m is the dimensionless velocity profile.

drag_coefficient(inputs, speed)

Compute the drag coefficient Cd from friction velocity (presumed to be in inputs.ustar) and effective wind speed (including any gustiness factors).

See the inputs container.

Arguments

• inputs: The inputs container. See build_surface_flux_inputs.
• speed: Effective wind speed [m/s].

heat_exchange_coefficient(param_set, ζ, z0m, z0h, Δz_eff, scheme)

Compute the heat exchange coefficient Ch for scalar exchange.

Formula:

Ch = κ^2 / (F_m * F_h),

where F_m and F_h are the dimensionless profiles for momentum and scalars. For the finite-volume case, this corresponds to the formulation in Nishizawa & Kitamura (2018), Eqs. 21 & 22 (with Pr0 absorbed into Fh).

Arguments

• param_set: Parameter set
• ζ: Stability parameter ζ = Δz_eff / L_MO
• z0m: Roughness length for momentum [m]
• z0h: Roughness length for scalars (heat/moisture) [m]
• Δz_eff: Effective aerodynamic height Δz - d [m]
• scheme: Surface flux solver scheme (default: PointValueScheme())

heat_conductance(param_set, ζ, ustar, inputs, z0m, z0h, scheme)

Compute the heat conductance g_h (speed * Ch), including any gustiness factor in the wind speed. Calculates windspeed and exchange coefficient internally from Monin-Obukhov variables.

Arguments

• param_set: Parameter set.
• ζ: Monin-Obukhov stability parameter.
• ustar: Friction velocity [m/s].
• inputs: The inputs container. See build_surface_flux_inputs.
• z0m: Momentum roughness length [m].
• z0h: Thermal roughness length [m].
• scheme: Discretization scheme.

compute_physical_scale_coeff(
    param_set::APS,
    Δz_eff,
    ζ,
    z0,
    transport,
    scheme::SolverScheme,
)

Compute the coefficient relating a bulk difference to its similarity scale.

Returns ϕ such that scale = Δvalue * ϕ; for example, u★ = ΔU * ϕ_m. It is given by

\[ϕ = \frac{κ}{F(Δz_{eff}, ζ, z_0)}\]

where κ is the von Kármán constant and F is the dimensionless profile function from UniversalFunctions for the requested transport and scheme.

Arguments

• param_set: Parameter set.
• Δz_eff: Effective aerodynamic height Δz - d [m].
• ζ: Monin-Obukhov stability parameter [-].
• z0: Roughness length for the transported variable [m].
• transport: Transport type (MomentumTransport or HeatTransport).
• scheme: Discretization scheme (PointValueScheme or LayerAverageScheme).

compute_ustar(param_set, ζ, z0, inputs, scheme, gustiness)

Return the friction velocity implied by the Monin-Obukhov solution.

If a friction velocity is prescribed via inputs.ustar (in the inputs container), it is returned directly; otherwise it is recomputed from the similarity coefficients.

Arguments

• param_set: Parameter set.
• ζ: Monin-Obukhov stability parameter.
• z0: Momentum roughness length [m].
• inputs: The inputs container. See build_surface_flux_inputs.
• scheme: Discretization scheme.
• gustiness: Gustiness velocity scale [m/s].

compute_theta_star(param_set, ζ, z0h, inputs, scheme, T_sfc)

Return the potential temperature scale implied by the Monin-Obukhov solution, where z0h is the roughness length for heat.

Arguments

• param_set: Parameter set.
• ζ: Monin-Obukhov stability parameter.
• z0h: Thermal roughness length [m].
• inputs: The inputs container. See build_surface_flux_inputs.
• scheme: Discretization scheme.
• T_sfc: Surface temperature [K]. Optional; defaults to inputs.T_sfc_guess, falling back to the interior temperature inputs.T_int when the guess is nothing.

compute_q_star(param_set, ζ, z0h, inputs, scheme, q_vap_sfc)

Return the specific humidity scale implied by the current Monin-Obukhov solution, where z0h is the roughness length for scalars (assumed equal to heat).

Arguments

• param_set: Parameter set.
• ζ: Monin-Obukhov stability parameter.
• z0h: Thermal/scalar roughness length [m].
• inputs: The inputs container. See build_surface_flux_inputs.
• scheme: Discretization scheme.
• q_vap_sfc: Surface vapor specific humidity [kg/kg]. Optional; defaults to inputs.q_vap_sfc_guess, falling back to the interior total specific humidity inputs.q_tot_int when the guess is nothing.

surface_tke(param_set, Δz_eff, ustar, ζ)

Compute the surface-layer turbulent kinetic energy (TKE) (u_* ϕ)^2 following Tan et al. (2018).

Returns (u_* ϕ)^2 [m²/s²], where ϕ = sqrt(TKE)/u_* is the TKE-based velocity similarity function. In unstable conditions this is TKE = 3.75 u_*^2 + 0.2 w_*^2 + u_*^2 (-ζ)^{2/3}, and in stable/neutral conditions it reduces to 3.75 u_*^2. The convective (Deardorff) velocity scale w_* is computed from the mixed-layer height zi (a fixed parameter) and the buoyancy flux implied by ζ.

Arguments

• param_set: Parameter set.
• Δz_eff: Effective aerodynamic height Δz - d [m].
• ustar: Friction velocity [m/s].
• ζ: Monin-Obukhov stability parameter [-].

scalar_variance(param_set, scale, ζ)

Compute the scalar variance σ_s^2 = (scale * ϕ_σs)^2, using the temperature-variance similarity ϕ_σs = ϕ_σθ (Wyngaard et al. 1971; Tan et al. 2018).

Arguments

• param_set: Parameter set.
• scale: Similarity scale of the scalar (e.g., theta_star, q_star).
• ζ: Monin-Obukhov stability parameter.

theta_variance(param_set, inputs, shf, ustar, ζ, rho_sfc)

Computes potential temperature variance from sensible heat flux shf. Calculates θ_* = -shf / (ρ * c_p * u_*) and calls scalar_variance.

Arguments

• param_set: Parameter set.
• inputs: The inputs container. See build_surface_flux_inputs.
• shf: Sensible heat flux [W/m^2].
• ustar: Friction velocity [m/s].
• ζ: Monin-Obukhov stability parameter.
• rho_sfc: Surface density [kg/m^3].

obukhov_length(param_set, ustar, buoy_flux)

Computes the Monin-Obukhov length [m].

Returns zero if ustar is zero.

Arguments

• param_set: Parameter set.
• ustar: Friction velocity [m/s].
• buoy_flux: Surface buoyancy flux [m^2/s^3].

obukhov_stability_parameter(param_set, Δz_eff, ustar, buoy_flux)

Computes the Monin-Obukhov stability parameter ζ = Δz_eff / L_MO, where Δz_eff is the effective aerodynamic height ($z-d$).

Returns zero if ustar and hence L_MO are zero.

Arguments

• param_set: Parameter set.
• Δz_eff: Effective aerodynamic height [m].
• ustar: Friction velocity [m/s].
• buoy_flux: Surface buoyancy flux [m^2/s^3].

surface_density(param_set, T_int, ρ_int, T_sfc, Δz, q_tot_int=0, q_liq_int=0, q_ice_int=0, q_vap_sfc=nothing)

Estimates the surface air density assuming hydrostatic balance between the interior and surface. It effectively extrapolates the interior pressure to the surface using the hydrostatic equation with an average virtual temperature, and then computes the surface density using the ideal gas law.

Arguments

• param_set: AbstractSurfaceFluxesParameters.
• T_int: Interior temperature [K].
• ρ_int: Interior density [kg/m^3].
• T_sfc: Surface temperature [K].
• Δz: Height difference [m].
• q_tot_int: Interior total specific humidity.
• q_liq_int: Interior liquid specific humidity.
• q_ice_int: Interior ice specific humidity.
• q_vap_sfc: Surface vapor specific humidity (optional, defaults to q_vap_int).

Returns ρ_sfc [kg/m^3].

ConstantRoughnessParams{FT} <: AbstractRoughnessParams

Roughness lengths fixed to constant values.

Fields

• z0m: Momentum roughness length [m].
• z0s: Scalar roughness length [m]. Used for both heat (z0h) and humidity (z0q).

The keyword defaults shown here (z0m = 2e-4 m, z0s = 2e-5 m) are also the roughness lengths used by surface_fluxes when config is omitted, via default_surface_flux_config. When loading via ClimaParams, the values are read from the TOML file. Most applications pass z0m/z0s explicitly or load them from ClimaParams.

COARE3RoughnessParams{FT} <: AbstractRoughnessParams

COARE 3.0 roughness parameterization (Fairall et al. 2003).

References

• Fairall, C. W., Bradley, E. F., Hare, J. E., Grachev, A. A., & Edson, J. B. (2003). Bulk parameterization of air–sea fluxes: Updates and verification for the COARE algorithm. Journal of Climate, 16, 571–591. DOI: 10.1175/1520-0442(2003)016<0571:BPOASF>2.0.CO;2

The default values specified here are used when constructing the struct manually. When loading via ClimaParams, these values are overwritten by the parameters in the TOML file.

RaupachRoughnessParams <: AbstractRoughnessParams

Raupach (1994) canopy roughness model.

References

• Raupach, M. R. (1994). Simplified expressions for vegetation roughness length and zero-plane displacement as functions of canopy height and area index. Boundary-Layer Meteorology, 71, 211–216. DOI: 10.1007/BF00709229

The default values specified here are used when constructing the struct manually. When loading via ClimaParams, stanton_number is overwritten by the parameter in the TOML file, while other parameters (C_R, C_S, c_d1) retain their default values.

ConstantGustinessSpec{TG <: Real}

A gustiness model where the gustiness velocity is a constant value.

Fields

• value: The constant gustiness velocity [m/s].

DeardorffGustinessSpec

A gustiness model based on Deardorff (1970) scaling with convective velocity scale $w_*$. The gustiness velocity is computed as: $U_{gust} = \beta w_*$ where $w_* = (B z_i)^{1/3}$.

MoistModel

Indicates that moisture effects (latent heat, virtual temperature) should be included in the flux calculations.

DryModel

Indicates that moisture effects should be ignored (sensible heat and momentum only).

UniversalFunctions

Universal stability and stability correction functions for the SurfaceFluxes module.

Supports the following flux-profile (ϕ, ψ, Ψ) parameterizations:

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

Both standard finite-difference (point-value) and finite-volume (layer-averaged) schemes are supported; the finite-volume scheme follows Nishizawa & Kitamura (2018).

The module also provides variance/TKE similarity functions (MomentumVariance, HeatVariance) from Panofsky et al. (1977), Wyngaard et al. (1971), and Tan et al. (2018). These are empirical surface-layer closures that are independent of the flux-profile parameterization above (see the phi(..., MomentumVariance()) / phi(..., HeatVariance()) docstrings for their range of validity).

References

• Businger, J. A., Wyngaard, J. C., Izumi, Y., & Bradley, E. F. (1971). Flux-profile relationships in the atmospheric surface layer. Journal of the Atmospheric Sciences, 28, 181–189. DOI: 10.1175/1520-0469(1971)028<0181:FPRITA>2.0.CO;2
• Dyer, A. J. (1974). A review of flux-profile relationships. Boundary-Layer Meteorology, 7, 363–372. DOI: 10.1007/BF00240838
• Gryanik, V. M., Lüpkes, C., Grachev, A., & Sidorenko, D. (2020). New modified and extended stability functions for the stable boundary layer based on SHEBA and parametrizations of bulk transfer coefficients for climate models. Journal of the Atmospheric Sciences, 77, 2687–2716. DOI: 10.1175/JAS-D-19-0255.1
• Grachev, A. A., Andreas, E. L., Fairall, C. W., Guest, P. S., & Persson, P. O. G. (2007). SHEBA flux–profile relationships in the stable atmospheric boundary layer. Boundary-Layer Meteorology, 124, 315–333. DOI: 10.1007/s10546-007-9177-6
• Nishizawa, S., & Kitamura, Y. (2018). A surface flux scheme based on the Monin-Obukhov similarity for finite volume models. Journal of Advances in Modeling Earth Systems, 10, 3159–3175. DOI: 10.1029/2018MS001534
• Panofsky, H. A., Tennekes, H., Lenschow, D. H., & Wyngaard, J. C. (1977). The characteristics of turbulent velocity components in the surface layer under convective conditions. Boundary-Layer Meteorology, 11, 355–361. DOI: 10.1007/BF02186086
• Wyngaard, J. C., Coté, O. R., & Izumi, Y. (1971). Local free convection, similarity, and the budgets of shear stress and heat flux. Journal of the Atmospheric Sciences, 28, 1171–1182. DOI: 10.1175/1520-0469(1971)028<1171:LFCSAT>2.0.CO;2
• Panofsky, H. A., & Dutton, J. A. (1984). Atmospheric Turbulence: Models and Methods for Engineering Applications. Wiley, New York, 397 pp.
• Tan, Z., Kaul, C. M., Pressel, K. G., Cohen, Y., Schneider, T., & Teixeira, J. (2018). An extended eddy-diffusivity mass-flux scheme for unified representation of subgrid-scale turbulence and convection. Journal of Advances in Modeling Earth Systems, 10, 770–800. DOI: 10.1002/2017MS001162

phi(p, ζ, transport)

Universal (similarity) function: the non-dimensional vertical gradient of wind shear (ϕ_m, MomentumTransport) or of temperature/scalars (ϕ_h, HeatTransport) at stability parameter ζ.

Dispatches on the parameterization type of p (BusingerParams, GryanikParams, GrachevParams) and on transport.

psi(p, ζ, transport_type)

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

This is the standard correction used in point-based Monin-Obukhov similarity theory.

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.

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_h, b_h, c_h: Coefficients for heat/scalar stability function (Eq. 9b). Note: c_h is the coefficient for the linear ζ term in the denominator.
• Pr_0: Neutral Prandtl number. In the original Grachev et al. (2007) derivation, this is 1.0. It is included here for structural consistency with other parameterizations.

Reference: Grachev et al. (2007).

MomentumTransport

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

HeatTransport

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