SurfaceFluxes.jl

SurfaceFluxes — Module

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

source

Source Code Structure

The src/ directory contains the following files organized by functionality:

Core Module Files

SurfaceFluxes.jl: Main module file containing the surface_conditions function and obukhov_similarity_solution solver
types.jl: Type definitions including AbstractSurfaceConditions, SolverScheme, RoughnessModel, and related structs
utilities.jl: Helper functions for state accessors, Richardson number computation, and thermodynamic differences
Parameters.jl: Parameter set definitions for physical constants
UniversalFunctions.jl: Universal function implementations (Businger, Gryanik, Grachev)

Flux and Exchange Coefficient Methods

physical_scale_coefficient_methods.jl: Computation of physical scale coefficients for finite difference (Byun 1990) and finite volume (Nishizawa 2018) schemes
momentum_exchange_coefficient_methods.jl: Computation of momentum exchange coefficient (Cd) for neutral and stratified conditions
heat_exchange_coefficient_methods.jl: Computation of heat exchange coefficient (Ch) for neutral and stratified conditions
friction_velocity_methods.jl: Friction velocity (u★) computation methods
sensible_heat_methods.jl: Sensible heat flux computations
latent_heat_methods.jl: Latent heat flux computations
buoyancy_flux_methods.jl: Buoyancy flux computations
evaporation_methods.jl: Evaporation rate computations

Surface Condition Input Types

coefficient_inputs.jl: Methods for surface conditions specified via exchange coefficients (Cd, Ch)
roughness_models.jl: Roughness length models (ScalarRoughness, CharnockRoughness)

Profile Recovery

profile_recovery.jl: Functions to recover vertical profiles within the surface layer using Monin-Obukhov similarity theory

Core input types

SurfaceFluxes.StateValues — Type

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)

source

Dispatch types

SurfaceFluxes.Fluxes — Type

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

source

SurfaceFluxes.FluxesAndFrictionVelocity — 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

source

SurfaceFluxes.Coefficients — 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

source

SurfaceFluxes.ValuesOnly — 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

source

User-facing methods

SurfaceFluxes.surface_conditions — Function

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

source

SurfaceFluxes.recover_profile — Function

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)

source

Parameters

Convenience constructors are provided for the SurfaceFluxesParameters and the various UniversalFunctions parameter structs. To use them, you must first import ClimaParams:

import ClimaParams as CP
import SurfaceFluxes.Parameters as SFP
import SurfaceFluxes.UniversalFunctions as UF

FT = Float64

# SurfaceFluxesParameters requires a float type and a UniversalFunctionsParameters type
SFP.SurfaceFluxesParameters(FT, UF.BusingerParams)

# Or a TOML dict instead of a float type
toml_dict = CP.create_toml_dict(Float64)
SFP.SurfaceFluxesParameters(toml_dict, UF.GrachevParams)

# UniversalFunctionsParameters only require a float type or a TOML dict.
UF.BusingerParams(FT)
UF.GryanikParams(FT)
UF.GrachevParams(FT)

Universal Functions

SurfaceFluxes.UniversalFunctions — Module

UniversalFunctions

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

Businger
Gryanik
Grachev

source

SurfaceFluxes.UniversalFunctions.GryanikParams — Type

GryanikParams{FT} <: AbstractUniversalFunctionParameters{FT}

Free parameters for the Gryanik universal stability and stability correction functions.

Fields

Pr_0::FT: Neutral Prandtl number
a_m::FT: Momentum stability parameter for stable conditions
a_h::FT: Heat stability parameter for stable conditions
b_m::FT: Momentum stability parameter for unstable conditions
b_h::FT: Heat stability parameter for unstable conditions
ζ_a::FT: Critical stability parameter
γ::FT: Stability correction parameter

source

SurfaceFluxes.UniversalFunctions.GrachevParams — Type

GrachevParams{FT} <: AbstractUniversalFunctionParameters{FT}

Free parameters for the Grachev universal stability and stability correction functions.

Fields

Pr_0::FT: Neutral Prandtl number
a_m::FT: Momentum stability parameter for stable conditions
a_h::FT: Heat stability parameter for stable conditions
b_m::FT: Momentum stability parameter for unstable conditions
b_h::FT: Heat stability parameter for unstable conditions
c_h::FT: Additional heat stability parameter
ζ_a::FT: Critical stability parameter
γ::FT: Stability correction parameter

source

SurfaceFluxes.UniversalFunctions.BusingerParams — Type

BusingerParams{FT} <: AbstractUniversalFunctionParameters{FT}

Free parameters for the Businger universal stability and stability correction functions.

Fields

Pr_0::FT: Neutral Prandtl number
a_m::FT: Momentum stability parameter for stable conditions
a_h::FT: Heat stability parameter for stable conditions
b_m::FT: Momentum stability parameter for unstable conditions
b_h::FT: Heat stability parameter for unstable conditions
ζ_a::FT: Critical stability parameter
γ::FT: Stability correction parameter

source

SurfaceFluxes.UniversalFunctions.phi — Function

phi

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

source

SurfaceFluxes.UniversalFunctions.psi — Function

psi

Universal stability correction function for momentum (ψ_m) and heat (ψ_h)

source

SurfaceFluxes.UniversalFunctions.Psi — Function

Psi

Integral of universal stability correction function for momentum (ψ_m) and heat (ψ_h)

source