API reference

struct RadiativeTransferColumn{NF, LW, SW, PC, TC, V<:AbstractArray{NF, 1}, G<:(ColumnGrid{NF, V} where V<:AbstractArray{NF, 1}), AP<:(AtmosphereProfile{NF, V} where V<:AbstractArray{NF, 1})}

Bundles everything a single-column radiation calculation needs: grid, atmosphere profile, surface state, longwave and shortwave schemes, the thermodynamic and physical constants, and pre-allocated buffers for the temperature tendency, layer transmissivity, and diagnostic fluxes.

The high-level API is solve_longwave! and solve_shortwave! on a RadiativeTransferColumn:

rtm = RadiativeTransferColumn(; grid, profile, surface)
solve_longwave!(rtm)
solve_shortwave!(rtm)
@show rtm.longwave_diagnostics.outgoing_longwave

Fields are

• grid::ColumnGrid: Column vertical grid (sigma coordinates)

• profile::AtmosphereProfile: Atmosphere profile (temperature, humidity, geopotential, surface pressure, rain rate)

• surface::SurfaceState: Lower boundary state (SST/LST, albedos, emissivities, cos-zenith)

• longwave_scheme::Any: Longwave scheme (AnalyticBandLongwave, TransparentLongwave, …)

• shortwave_scheme::Any: Shortwave scheme (OneBandShortwave, OneBandGreyShortwave, …)

• physical_constants::Any: Physical constants (gravity, heat capacity, Stefan–Boltzmann, solar constant)

• thermodynamic_constants::Any: Thermodynamic constants (Clausius–Clapeyron parameters for saturation humidity)

• temperature_tendency::AbstractVector: Per-layer temperature tendency written by solve_longwave! / solve_shortwave!

• transmissivity_scratch::AbstractVector: Per-layer scratch for the shortwave transmissivity

• longwave_diagnostics::LongwaveDiagnostics: Scalar longwave diagnostics (OLR, surface up/down, ocean/land split)

• shortwave_diagnostics::ShortwaveDiagnostics: Scalar shortwave diagnostics (TOA up, surface up/down, albedo, clouds)

reset!(
    rtm::RadiativeTransferColumn
) -> RadiativeTransferColumn

Zero the temperature tendency and scalar diagnostics on rtm so a fresh solve_longwave! / solve_shortwave! doesn't accumulate onto stale values.

struct AtmosphereProfile{NF, V<:AbstractArray{NF, 1}}

Column thermodynamic profile and lower boundary quantities read by the radiation solvers.

The arrays are indexed top-down: k = 1 is the top of the atmosphere, k = nlayers is the bottom (surface-adjacent) layer.

struct ColumnGrid{NF, V<:AbstractArray{NF, 1}}

Vertical geometry for a single column expressed in sigma-pressure coordinates.

σ_full has length nlayers and gives the midpoint of each layer. σ_half has length nlayers + 1 and gives the layer interfaces. σ_thick = diff(σ_half) has length nlayers.

struct SurfaceState{NF}

Lower-boundary properties needed by the column radiation solvers. NaN in sea_surface_temperature or land_surface_temperature means the column has no ocean / no land respectively (the corresponding contribution is skipped).

struct PhysicalConstants{NF}

Physical constants consumed by the column radiation solvers.

struct ThermodynamicConstants{NF}

Thermodynamic constants needed for saturation-humidity calculations used by the diagnostic cloud scheme.

default_earth_constants(
    _::Type{NF}
) -> NamedTuple{(:physical, :thermodynamic), <:Tuple{PhysicalConstants, ThermodynamicConstants}}

Sensible Earth defaults for the full set of physical constants needed by the shortwave solver (constants + thermodynamic constants).

mutable struct LongwaveDiagnostics{NF}

Column longwave diagnostic outputs written by solve_longwave!.

mutable struct ShortwaveDiagnostics{NF}

Column shortwave diagnostic outputs written by solve_shortwave!.

struct AnalyticBandLongwave{NF} <: AbstractLongwaveScheme

Williams (2026) "Simple Spectral Model" (SSM) for clear-sky longwave radiative transfer.

The scheme solves Schwarzschild's two-stream equations

dℐꜛ/dτ = ℐꜛ − πB(T)
dℐꜜ/dτ = πB(T) − ℐꜜ

for the upwelling (ℐꜛˡʷ) and downwelling (ℐꜜˡʷ) spectral longwave fluxes at each of nwavenumber evenly spaced wavenumbers between wavenumber_min and wavenumber_max, with analytic mass absorption coefficients for H₂O line (rotation + vibration–rotation + combination bands, h2o_line_kappa_ref), a two-band H₂O continuum (h2o_cont_kappa_ref) and a Lorentzian CO₂ 15 μm bending mode (co2_kappa_ref). All reference constants are at (Tref, pref, RH_ref) = (260 K, 500 hPa, 100 %).

Fields and defaults follow Williams (2026), Table 1.

References:

• Williams (2026), J. Adv. Model. Earth Syst., doi:10.1029/2025MS005405.
• Armstrong (1968), doi:10.1016/0022-4073(68)90052-6 (diffusivity factor D).
• Mlawer et al. (1997), doi:10.1029/97JD00237 (continuum temperature scaling).

Fields are

• nwavenumber::Int64: Number of evenly spaced wavenumber quadrature points

• wavenumber_min::Any: Minimum wavenumber of the spectral integration range [cm⁻¹]

• wavenumber_max::Any: Maximum wavenumber of the spectral integration range [cm⁻¹]

• κ_rot::Any: Peak absorption of the pure-rotation band κ_rot [m² kg⁻¹]

• l_rot::Any: e-folding decay length of the rotation band l_rot [cm⁻¹]

• κ_vr::Any: Peak absorption of the vibration–rotation band κ_vr [m² kg⁻¹]

• l_vr1::Any: e-folding length of vibration–rotation band (low-ν side) l_vr1 [cm⁻¹]

• l_vr2::Any: e-folding length of vibration–rotation band (high-ν side) l_vr2 [cm⁻¹]

• κ_cnt1::Any: Continuum absorption below 1700 cm⁻¹ κ_cnt1 [m² kg⁻¹]

• κ_cnt2::Any: Continuum absorption above 1700 cm⁻¹ κ_cnt2 [m² kg⁻¹]

• κ_CO₂::Any: Peak absorption of the CO₂ 15 μm band κ_CO₂ [m² kg⁻¹]

• l_CO₂::Any: e-folding half-width of CO₂ band l_CO₂ [cm⁻¹]

• ν̃_CO₂::Any: Centre wavenumber of CO₂ bending mode ν̃_CO₂ [cm⁻¹]

• diffusivity::Any: Two-stream diffusivity factor D (Armstrong 1968)

• p_ref::Any: Reference pressure for pressure broadening [Pa]

• T_ref::Any: Reference temperature for absorption coefficient fits [K]

• pv_ref::Any: Reference saturation water-vapor pressure at T_ref [Pa]

• σ_cont::Any: Temperature-scaling exponent for the continuum (Mlawer et al. 1997) [K⁻¹]

solve_longwave!(
    dTdt::AbstractVector,
    diag::LongwaveDiagnostics{NF},
    scheme::AnalyticBandLongwave{NF},
    profile::AtmosphereProfile{NF, V} where V<:AbstractArray{NF, 1},
    geometry::ColumnGrid,
    surface::SurfaceState,
    constants
)

Column longwave radiative transfer for the Williams (2026) Simple Spectral Model. Tendencies are accumulated into dTdt with +=/-=; diagnostic fluxes are written into diag.

Sign convention: temperature tendency has units [K s⁻¹]; positive OLR, positive downward surface flux, positive upward surface flux.

solve_longwave!(
    rtm::RadiativeTransferColumn
) -> RadiativeTransferColumn

Column longwave radiative transfer using the scheme stored on rtm. Accumulates into rtm.temperature_tendency (call reset!(rtm) first if you want a clean slate) and writes scalars into rtm.longwave_diagnostics.

planck_wavenumber(T, ν̃)

Spectral Planck radiance at temperature T [K] and wavenumber ν̃ [cm⁻¹], in units of W m⁻² sr⁻¹ (cm⁻¹)⁻¹.

The two-stream hemispherical flux source term is π × planck_wavenumber(T, ν̃). Integrating π × planck_wavenumber(T, ν̃) over all wavenumbers recovers the Stefan–Boltzmann law σ T⁴.

Constants follow CODATA 2018.

h2o_line_kappa_ref(ν̃, scheme::AnalyticBandLongwave) -> κ  [m² kg⁻¹]

Reference H₂O line mass absorption coefficient. Piecewise-exponential fit to the pure-rotation (200–1000 cm⁻¹), vibration–rotation (1000–1700 cm⁻¹) and combination bands (1700–2500 cm⁻¹).

Reference: Williams (2026), Eq. 4 and Table 1.

h2o_cont_kappa_ref(ν̃, scheme::AnalyticBandLongwave) -> κ  [m² kg⁻¹]

Reference H₂O continuum absorption. Two gray values split at 1700 cm⁻¹ (stronger in the main atmospheric window below).

Reference: Williams (2026), Eq. 6.

co2_kappa_ref(ν̃, scheme::AnalyticBandLongwave) -> κ  [m² kg⁻¹]

Reference CO₂ absorption coefficient. A two-sided exponential (Laplace-shaped) wing centred on the 15 μm bending mode at ν̃_CO₂ ≈ 667 cm⁻¹, active only in [500, 850] cm⁻¹.

Reference: Williams (2026), Eq. 5.

williams_delta_tau(k, ν̃, temperature, humidity, surface_pressure,
                   geometry, scheme, gravity) -> Δτ

Optical depth increment through layer k at wavenumber ν̃. Combines H₂O line absorption (Williams 2026, Eq. 7), H₂O continuum (Eq. 8) and CO₂ (Eq. 9). The result already includes the two-stream diffusivity factor D ≈ 1.5 (Armstrong 1968).

temperature and humidity are length-nlayers column vectors; geometry is a ColumnGrid.

struct TransparentShortwave <: AbstractShortwaveScheme

Zero-atmosphere shortwave: TOA insolation reaches the surface unattenuated and is reflected by the surface albedo. Temperature tendencies are zero. Useful as a baseline and for tests of the surface energy budget.

struct OneBandShortwave{C<:AbstractShortwaveClouds, T<:AbstractShortwaveTransmissivity, R<:OneBandShortwaveRadiativeTransfer} <: AbstractShortwaveScheme

Composite one-band shortwave scheme: a cloud diagnosis, a layer-transmissivity model and a radiative-transfer solver are combined into a single scheme that can be passed to solve_shortwave!.

Fields are

• clouds::AbstractShortwaveClouds

• transmissivity::AbstractShortwaveTransmissivity

• radiative_transfer::OneBandShortwaveRadiativeTransfer

OneBandGreyShortwave(
    ::Type{NF};
    clouds,
    transmissivity,
    radiative_transfer
) -> AnalyticBandRadiation.OneBandShortwave{NoClouds, T, R} where {T<:ConstantShortwaveTransmissivity, R<:(OneBandShortwaveRadiativeTransfer{_A, F} where {_A, F<:(AnalyticBandRadiation.var"#31#32")})}

Convenience constructor with a dry-atmosphere default (no clouds, constant column transmissivity).

struct OneBandShortwaveRadiativeTransfer{NF, F} <: AbstractShortwaveScheme

SPEEDY-style one-band shortwave radiative transfer (Kucharski, Molteni & Bracco, 2006, Appendix). Computes cloud albedo reflection at the diagnosed cloud top, ozone absorption in the stratosphere, layer-by-layer transmission with the configured AbstractShortwaveTransmissivity, stratocumulus reflection just above the surface, and surface-albedo reflection.

Fields are

• ozone_absorption::Any: Total ozone absorption as a fraction of incoming TOA flux

• ozone_distribution::Any: Ozone vertical distribution ζ(σ) → weight, normalised so ∫ ζ(σ) dσ = 1

AbstractShortwaveTransmissivity <: AbstractRadiationScheme

A layer-transmissivity model used by shortwave radiative-transfer solvers.

struct ConstantShortwaveTransmissivity{NF} <: AbstractShortwaveTransmissivity

Constant atmospheric transmissivity, distributed across layers proportional to their pressure thickness.

Fields are

• transmissivity::Any: Column-integrated atmospheric transmissivity (0 .. 1)

struct BackgroundShortwaveTransmissivity{NF} <: AbstractShortwaveTransmissivity

SPEEDY-style background shortwave transmissivity (Kucharski, Molteni & Bracco, 2006; cf. Fortran SPEEDY absdry, absaer, abswv1/abswv2, abscl1/abscl2, azen, nzen). The layer optical depth sums contributions from dry air, aerosols (∝ σ²), water vapour (∝ q), and clouds (active below the diagnosed cloud top); the column is weighted by a zenith correction factor 1 + azen (1 − cosθ)^nzen.

Fields are

• zenith_amplitude::Any: Zenith correction amplitude (SPEEDY azen)

• zenith_exponent::Any: Zenith correction exponent (SPEEDY nzen)

• absorptivity_dry_air::Any: Absorptivity of dry air [per 10⁵ Pa]

• aerosols::Bool: Include a constant aerosol concentration

• absorptivity_aerosol::Any: Absorptivity of aerosols [per 10⁵ Pa]

• absorptivity_water_vapor::Any: Absorptivity of water vapour [per kg/kg per 10⁵ Pa]

• absorptivity_cloud_base::Any: Base cloud absorptivity [per kg/kg per 10⁵ Pa]

• absorptivity_cloud_limit::Any: Maximum cloud absorptivity [per 10⁵ Pa]

AbstractShortwaveClouds <: AbstractRadiationScheme

A diagnostic cloud model for the shortwave.

struct NoClouds <: AbstractShortwaveClouds

Trivial cloud model that reports zero cloud cover. Returned shape matches DiagnosticClouds so downstream code can be agnostic.

struct DiagnosticClouds{NF} <: AbstractShortwaveClouds

Diagnostic clouds after the Fortran SPEEDY scheme (Kucharski, Molteni & Bracco, 2006). Cloud cover is a combination of a relative-humidity term and a precipitation term; the highest layer exceeding the RH threshold sets the cloud top. An independent stratocumulus term is diagnosed at the surface from dry-static-energy stability.

Fields are

• relative_humidity_threshold_min::Any: Relative humidity threshold for cloud cover = 0 [1]

• relative_humidity_threshold_max::Any: Relative humidity threshold for cloud cover = 1 [1]

• specific_humidity_threshold_min::Any: Specific humidity threshold for cloud cover [kg/kg]

• precipitation_weight::Any: Weight for the √precipitation term [1]

• precipitation_max::Any: Cap on precipitation contributing to cloud cover [mm/day]

• cloud_albedo::Any: Cloud albedo at CLC = 1 [1]

• stratocumulus_albedo::Any: Stratocumulus cloud albedo [1]

• stratocumulus_stability_min::Any: Static-stability lower threshold for stratocumulus (GSES0) [J/kg]

• stratocumulus_stability_max::Any: Static-stability upper threshold for stratocumulus (GSES1) [J/kg]

• stratocumulus_cover_max::Any: Maximum stratocumulus cloud cover (CLSMAX) [1]

• use_stratocumulus::Bool: Enable the stratocumulus parameterization

• stratocumulus_cloud_factor::Any: Stratocumulus cloud factor (SPEEDY clfact) [1]

solve_shortwave!(
    dTdt::AbstractVector,
    diag::ShortwaveDiagnostics{NF},
    ::AnalyticBandRadiation.TransparentShortwave,
    profile::AtmosphereProfile,
    geometry::ColumnGrid,
    surface::SurfaceState,
    constants,
    thermodynamic;
    cloud_top_convective
)

Column transparent-atmosphere shortwave.

solve_shortwave!(
    dTdt::AbstractVector,
    diag::ShortwaveDiagnostics{NF},
    scheme::AnalyticBandRadiation.OneBandShortwave,
    profile::AtmosphereProfile,
    geometry::ColumnGrid,
    surface::SurfaceState,
    constants,
    thermodynamic;
    transmissivity_scratch,
    cloud_top_convective
)

Column shortwave radiative transfer for the one-band scheme.

transmissivity_scratch (length nlayers) is overwritten with the layer transmissivities; pre-allocate it outside of hot loops for GPU kernels.

cloud_top_convective is the cloud top set upstream by convection or large-scale condensation; pass length(profile.temperature) + 1 if none.

rain_rate for the diagnostic cloud scheme comes from profile.rain_rate.

solve_shortwave!(
    rtm::RadiativeTransferColumn;
    cloud_top_convective
) -> RadiativeTransferColumn

Column shortwave radiative transfer using the scheme stored on rtm.

solar_declination(γ) -> Any

Solar declination [rad] from the fractional day of year γ ∈ [0, 2π] using the Spencer (1971) four-term Fourier series (accurate to ≈0.01°).

equation_of_time(γ) -> Any

Equation of time [rad] from the fractional day of year γ ∈ [0, 2π] (Spencer 1971).

cosine_solar_zenith(
    lon,
    lat,
    time::Dates.DateTime;
    axial_tilt,
    equinox,
    days_per_year,
    seconds_per_day
) -> Any

Cosine of the solar zenith angle at longitude lon [rad], latitude lat [rad] and UT time. Clipped to max(cosθ, 0) so the night side returns 0.

For seasonal-only (daily-average) insolation the caller should average over a day or set time to noon and absorb the daily mean separately.