Staged Runtime

AbstractRadiationScheme

Root type for column radiation schemes defined by NumericalRadiation.

AbstractAtmosphericState

Root type for atmospheric states accepted by the staged radiation interface. Host models may provide their own state/view types when they implement the required component methods.

AbstractGasOpticsModel

Root type for gas-optics models that can materialize optical properties or source terms independently of a radiative-transfer solver.

AbstractCloudOpticsModel

Root type for cloud-optics models that can be evaluated independently of gas optics and solvers.

AbstractAerosolOpticsModel

Root type for aerosol-optics models that can be evaluated independently of gas optics and solvers.

AbstractRadiativeTransferSolver

Root type for solvers that consume optical properties/source terms and produce fluxes.

AbstractRadiationBackend

Root type for runtime backends such as CPU, CUDA, or host-model-specific kernel launch paths.

struct ColumnAtmosphere{FT, A, G, S, Geo, C} <: AbstractAtmosphericState

Generic column atmosphere container for the staged radiation interface.

The existing analytic-band solvers use AtmosphereProfile, ColumnGrid, and SurfaceState directly. ColumnAtmosphere is a host-model-facing container for newer gas-optics and solver paths where layer/interface pressure and temperature arrays need to be carried together.

Fields:

• pressure_layers: Layer pressures, indexed top-down
• pressure_interfaces: Interface pressures, indexed top-down
• temperature_layers: Layer temperatures, indexed top-down
• temperature_interfaces: Interface temperatures, indexed top-down
• gases: Symbol-keyed gas concentrations or host-model property view
• surface: Lower-boundary state
• geometry: Geometry, solar angles, or host-model geometry view
• constants: Physical constants of the host (PhysicalConstants in the column's element type by default): gravity and the dry-air molar mass for the hydrostatic layer air amounts of optical_properties!, gravity and the heat capacity for heating_rates!

struct RadiativeFluxes{FT, A}

Flux container for component radiation APIs.

Arrays are caller-owned and may be package work arrays, host-model views, or device arrays. Interface flux arrays should have one more vertical point than layer-centered heating arrays.

Fields:

• longwave_up: Upwelling longwave flux at interfaces
• longwave_down: Downwelling longwave flux at interfaces
• shortwave_up: Upwelling shortwave flux at interfaces
• shortwave_down: Downwelling shortwave flux at interfaces

struct LongwaveOptics{FT, A, ST, SB, SA, SG, W}

Precomputed longwave optical properties for clear-sky solver tests and future ecCKD gas-optics outputs.

optical_depth and source may be vectors of length Nz or matrices with shape (Ng, Nz). source is the layer source function in flux units for each spectral point. Optional source_top and source_bottom arrays with the same shape enable ecRad-style no-scattering longwave emission from half-level Planck functions. Optional single_scattering_albedo and scattering_asymmetry arrays activate the ecRad-style longwave scattering adding path. weights has length Ng and is applied while accumulating broadband fluxes.

Fields:

• optical_depth: Layer optical depth
• source: Layer source function in flux units
• source_top: Top-interface source function for each layer, or nothing
• source_bottom: Bottom-interface source function for each layer, or nothing
• single_scattering_albedo: Layer single-scattering albedo, or nothing for no scattering
• scattering_asymmetry: Layer scattering asymmetry factor, or nothing for no scattering
• weights: Spectral weights

struct CloudlessLongwave <: AbstractRadiativeTransferSolver

Cloudless longwave two-stream solver for precomputed optical properties.

This solver is intentionally small and explicit: it is the first component solver behind the staged radiative_fluxes! API and provides a validation target before ecCKD gas optics are implemented.

struct LongwaveBoundaryConditions{FT, S, A}

Longwave boundary fluxes for CloudlessLongwave.

For spectral (multi-g) optics such as the tabulated ecCKD models, surface_longwave_up must be a length-Ng vector in the same per-unit-weight convention as the optics' Planck sources — build it with surface_longwave_emission. A scalar is interpreted as spectrally-gray emission (every g point emits the same flux), a gray approximation that does not reproduce a tabulated model's Planck spectrum and may bias outgoing longwave fluxes.

Fields:

• surface_longwave_up: Upwelling longwave flux entering the bottom interface
• toa_longwave_down: Downwelling longwave flux entering the top interface
• surface_albedo: Diffuse longwave surface albedo

struct ShortwaveOptics{FT, A, R, G, W}

Precomputed shortwave optical properties for clear-sky solver tests and future ecCKD gas-optics outputs.

optical_depth may be a vector of length Nz or a matrix with shape (Ng, Nz). weights has length Ng and is applied while accumulating broadband fluxes.

Fields:

• optical_depth: Layer absorptive optical depth
• rayleigh_optical_depth: Layer shortwave scattering optical depth. Historically this was Rayleigh-only
• scattering_asymmetry: Layer shortwave scattering asymmetry factor
• weights: Spectral weights

struct CloudlessShortwave <: AbstractRadiativeTransferSolver

Cloudless shortwave solver for precomputed absorptive optical depths.

This is a deterministic clear-sky component solver. It transmits downwelling TOA shortwave flux through the column, reflects a configurable fraction at the surface, and transmits that reflected flux upward through the same optical depths.

struct ShortwaveBoundaryConditions{FT, A, D}

Shortwave boundary conditions for CloudlessShortwave.

Fields:

• toa_shortwave_down: Downwelling shortwave flux entering the top interface
• surface_albedo: Lambertian surface albedo for diffuse radiation, either broadband scalar or per-g-point vector
• surface_albedo_direct: Lambertian surface albedo for direct radiation, either broadband scalar or per-g-point vector

struct CloudOptics{FT, A}

Layer cloud optical properties for the staged runtime interface.

This first cloud-optics container stores longwave absorption, shortwave absorption, and shortwave scattering optical depth at model layers so host models can test all-sky plumbing independently from gas optics and radiative-transfer solvers. More complete phase functions and overlap properties can extend this interface without changing the gas-optics API.

Fields:

• longwave_optical_depth: Layer longwave cloud optical depth
• shortwave_optical_depth: Layer shortwave absorptive cloud optical depth
• shortwave_scattering_optical_depth: Layer shortwave scattering cloud optical depth
• shortwave_scattering_asymmetry: Layer shortwave cloud scattering asymmetry factor

struct LayerCloudOpticsModel{FT, CWP} <: AbstractCloudOpticsModel

Simple layer-cloud optical model.

cloud_water_path may be a scalar, a vector with one entry per layer, or an object supporting getproperty(..., :cloud_water_path). Optical depths are

τˡʷ = κˡʷ W,    τₐˢʷ = (1 - ω) κˢʷ W,    τₛˢʷ = ω κˢʷ W

with W = cloud_water_path, κˡʷ = longwave_mass_absorption, κˢʷ = shortwave_mass_extinction and ω = shortwave_single_scattering_albedo.

Fields:

• cloud_water_path: Layer cloud water path, or fallback value when the atmosphere does not provide one
• longwave_mass_absorption: Longwave mass absorption coefficient
• shortwave_mass_extinction: Shortwave mass extinction coefficient
• shortwave_single_scattering_albedo: Shortwave single-scattering albedo
• shortwave_scattering_asymmetry: Shortwave scattering asymmetry factor

struct LayerLiquidIceCloudOpticsModel{FT, LWP, IWP, CF} <: AbstractCloudOpticsModel

Layer liquid/ice cloud optical model for all-sky host integrations.

This keeps liquid water path, ice water path, and cloud fraction as separate inputs instead of collapsing them before the cloud-optics API. The current model is still absorptive/extinctive-only, but it gives later IFS-compatible cloud optics a stable place to add phase-dependent scattering, asymmetry, effective-radius, and overlap conventions.

Optical depths are

τˡʷ  = f (κˡ Wˡ + κⁱ Wⁱ)
τₐˢʷ = f ((1 - ωˡ) κˡ Wˡ + (1 - ωⁱ) κⁱ Wⁱ)
τₛˢʷ = f (ωˡ κˡ Wˡ + ωⁱ κⁱ Wⁱ)

with f = cloud_fraction^cloud_fraction_exponent (1 for the cloudy-region variant), Wˡ, Wⁱ the liquid and ice water paths, κˡ, κⁱ the phases' longwave mass absorptions in the first line and shortwave mass extinctions in the other two, and ωˡ, ωⁱ their shortwave single-scattering albedos; the layer asymmetry factor is the scattering-weighted mean of 𝒢ˡ and 𝒢ⁱ.

Fields:

• liquid_water_path: Layer liquid water path, or fallback value when the atmosphere does not provide one
• ice_water_path: Layer ice water path, or fallback value when the atmosphere does not provide one
• cloud_fraction: Layer cloud fraction, or fallback value when the atmosphere does not provide one
• liquid_longwave_mass_absorption: Liquid longwave mass absorption coefficient
• ice_longwave_mass_absorption: Ice longwave mass absorption coefficient
• liquid_shortwave_mass_extinction: Liquid shortwave mass extinction coefficient
• ice_shortwave_mass_extinction: Ice shortwave mass extinction coefficient
• liquid_shortwave_single_scattering_albedo: Liquid shortwave single-scattering albedo
• ice_shortwave_single_scattering_albedo: Ice shortwave single-scattering albedo
• liquid_shortwave_scattering_asymmetry: Liquid shortwave scattering asymmetry factor
• ice_shortwave_scattering_asymmetry: Ice shortwave scattering asymmetry factor
• cloud_fraction_exponent: Exponent applied to cloud fraction before scaling optical depth

struct CloudyRegionCloudOptics{FT, A}

Cloudy-region cloud optical properties for all-sky solvers.

Unlike CloudOptics, these optical depths are not scaled by cloud fraction. They describe the cloudy region of each layer, while cloud_fraction and overlap_parameter are carried separately for Tripleclouds/McICA-style solvers. This avoids the grid-mean shortcut that is useful for simple smoke tests but inconsistent with ecRad's all-sky cloud-region optical-property convention.

Fields:

• cloud_fraction: Layer cloud fraction
• overlap_parameter: Interface cloud-overlap parameter between adjacent layers
• longwave_optical_depth: Cloudy-region longwave cloud optical depth
• shortwave_optical_depth: Cloudy-region shortwave absorptive cloud optical depth
• shortwave_scattering_optical_depth: Cloudy-region shortwave scattering cloud optical depth
• shortwave_scattering_asymmetry: Cloudy-region shortwave cloud scattering asymmetry factor

struct LongwaveCloudOverlapOptics{FT, L, F, O, D}

Longwave optical properties for a two-region all-sky column.

clear contains gas/aerosol optical properties for the clear region. cloudy contains cloudy-region optical properties, including gas plus in-cloud optical properties. cloud_fraction is kept separate so validation and host-model integrations do not have to represent cloud cover by weakening cloudy optical depth before transport.

Fields:

• clear: Clear-region longwave optical properties
• cloudy: Cloudy-region longwave optical properties
• cloud_fraction: Layer cloud fraction
• overlap_parameter: Interface overlap parameter between adjacent cloudy layers
• fractional_standard_deviation: Layer fractional standard deviation of in-cloud condensate

struct ShortwaveCloudOverlapOptics{FT, S, F, O, D}

Shortwave optical properties for a two-region all-sky column.

clear contains gas/aerosol optical properties for the clear region. cloudy contains the cloudy-region optical properties, including gas plus cloud scattering/absorption. cloud_fraction is kept separate so host models and all-sky solvers do not have to encode cloud fraction by weakening the cloudy-region optical depth.

Fields:

• clear: Clear-region shortwave optical properties
• cloudy: Cloudy-region shortwave optical properties
• cloud_fraction: Layer cloud fraction
• overlap_parameter: Interface overlap parameter between adjacent cloudy layers
• fractional_standard_deviation: Layer fractional standard deviation of in-cloud condensate

struct CloudOverlapLongwave{FT} <: AbstractRadiativeTransferSolver

First deterministic all-sky longwave overlap solver.

overlap=:adding mixes clear/cloudy layer reflectance, transmittance, and source terms before a scalar longwave adding pass. overlap=:tripleclouds_alpha splits cloudy layers into thin and thick regions using the same gamma inhomogeneity scaling as the staged shortwave Tripleclouds access point. This is still a diagnostic solver, not a bit-for-bit ecRad McICA implementation.

Fields:

• overlap: Cloud-fraction overlap rule
• cloud_fraction_exponent: Exponent applied to layer cloud fraction before mixing
• inhomogeneity_overlap_exponent: Exponent applied to the $α$ overlap inside the Tripleclouds inhomogeneity split

struct CloudOverlapShortwave{FT, S} <: AbstractRadiativeTransferSolver

First deterministic all-sky shortwave overlap solver.

This solver computes clear-region and cloudy-region fluxes independently using CloudlessShortwave, then blends each interface by an explicit interface cloud fraction. It is a staged all-sky access point, not a full ecRad McICA/Tripleclouds implementation.

overlap=:maximum uses the maximum adjacent layer cloud fraction at interior interfaces, which preserves vertically contiguous cloud cover more strongly than averaging. overlap=:average uses the arithmetic mean. overlap=:adding mixes clear/cloudy layer reflectance and transmittance before the adding pass. overlap=:matrix_maximum carries separate clear/cloudy region fluxes through a two-region maximum-overlap matrix during the adding pass. overlap=:matrix_alpha uses the supplied ecRad/Hogan-Illingworth $α$ overlap parameter between adjacent layers. overlap=:tripleclouds_alpha additionally splits the cloudy region into thin and thick regions using ecRad's gamma optical-depth scaling. These latter modes are diagnostics between final-flux blending and a full Tripleclouds/McICA solver.

Fields:

• clear_solver: Underlying two-stream shortwave solver
• overlap: Cloud-fraction overlap rule, :maximum or :average
• cloud_fraction_exponent: Exponent applied to layer cloud fraction before interface blending
• inhomogeneity_overlap_exponent: Exponent applied to the $α$ overlap inside the Tripleclouds inhomogeneity split

struct CloudScatteringTable{FT, V, M}

Dependency-light cloud scattering table.

The table stores raw ecRad-style scattering properties as a function of wavenumber and effective radius. Spectral mapping to radiation bands or g-points is a separate operation because it depends on the gas-optics spectral definition and averaging convention.

Fields:

• medium: Hydrometeor medium, for example liquid-water or ice
• particle_type: Particle type from file metadata
• wavenumber: Wavenumber grid in cm^-1
• effective_radius: Effective-radius grid in m
• mass_extinction_coefficient: Mass-extinction coefficient with shape (wavenumber, effective_radius)
• single_scattering_albedo: Single-scattering albedo with shape (wavenumber, effective_radius)
• asymmetry_factor: Scattering asymmetry factor with shape (wavenumber, effective_radius)

add_cloud_optical_depths!(longwave, shortwave, cloud)

Add layer cloud optical depths to precomputed gas optical properties. Longwave and shortwave absorption are added to the absorption optical-depth arrays; shortwave cloud scattering is added to the solver's scattering optical-depth array. This keeps gas optics, cloud optics, and solvers independently testable while providing an initial all-sky composition path.

add_mapped_cloud_scattering!(shortwave, liquid_properties, ice_properties,
                             liquid_water_path, ice_water_path, cloud_fraction; kwargs...)

Add g-point mapped liquid and ice cloud scattering to shortwave optical properties. The input liquid_properties and ice_properties are per-g-point scattering tables (anything with mass_extinction_coefficient, single_scattering_albedo, and asymmetry_factor indexable by g point, such as the output of cloud_scattering_gpoint_properties), while the water paths and cloud fraction are layer fields. The function adds absorptive optical depth to shortwave.optical_depth and mixes scattering optical depth/asymmetry into shortwave.rayleigh_optical_depth and shortwave.scattering_asymmetry.

The keyword scale factors enter as follows: the extinction scales multiply each phase's mass-extinction coefficient; the cloud-fraction weight cloud_fraction^cloud_fraction_exponent multiplies both water paths; shortwave_scattering_scale multiplies each phase's single-scattering albedo (clamped to [0, 1]); and delta_eddington_scale removes the forward-scattering peak of the combined liquid+ice mixture once with delta_eddington, after the phases are mixed and before the mixture is folded into the layer, as ecRad does (f = 𝒢² is nonlinear, so scaling the phases separately would differ whenever their asymmetries differ).

struct AerosolOptics{FT, A}

Layer aerosol optical properties for the staged runtime interface.

This first aerosol-optics container mirrors CloudOptics: it stores absorptive longwave and shortwave optical depth at model layers so host models can compose gas, cloud, and aerosol optics without accepting a single end-to-end radiation path.

Fields:

• longwave_optical_depth: Layer longwave aerosol optical depth
• shortwave_optical_depth: Layer shortwave absorptive aerosol optical depth
• shortwave_scattering_optical_depth: Layer shortwave scattering aerosol optical depth
• shortwave_scattering_asymmetry: Layer shortwave aerosol scattering asymmetry factor

struct LayerAerosolOpticsModel{FT, AP} <: AbstractAerosolOpticsModel

Simple layer-aerosol optical model.

aerosol_path may be a scalar, a vector with one entry per layer, or a value provided by getproperty(atmosphere, :aerosol_path). Optical depths are

τˡʷ = κˡʷ W,    τₐˢʷ = (1 - ω) κˢʷ W,    τₛˢʷ = ω κˢʷ W

with W = aerosol_path.

with κˡʷ = longwave_mass_absorption, κˢʷ = shortwave_mass_extinction and ω = shortwave_single_scattering_albedo.

Fields:

• aerosol_path: Layer aerosol path, or fallback value when the atmosphere does not provide one
• longwave_mass_absorption: Longwave mass absorption coefficient
• shortwave_mass_extinction: Shortwave mass extinction coefficient
• shortwave_single_scattering_albedo: Shortwave single-scattering albedo
• shortwave_scattering_asymmetry: Shortwave scattering asymmetry factor

add_aerosol_optical_depths!(longwave, shortwave, aerosol)

Add layer aerosol optical depths to precomputed gas optical properties. This keeps aerosol optics independently testable while providing an initial absorptive gas+cloud+aerosol composition path.

optical_properties!(optics, gas_model, atmosphere[, workspace])

Materialize gas optical properties. Concrete gas-optics models should overload this method so host models can use gas optics without accepting the package's solver or tendency path.

optical_properties!(longwave, shortwave, model::EcCKDGasOpticsModel, atmosphere)

Fill caller-owned longwave and shortwave optical-property arrays from an already-interpolated ecCKD-style model. This method performs no NetCDF I/O and does not allocate output arrays.

optical_properties!(longwave, shortwave, model::EcCKDTabulatedGasOpticsModel, atmosphere)

Fill caller-owned longwave and shortwave optical-property arrays from pressure/temperature coefficient tables using bilinear interpolation. This is the lightweight runtime LUT path for ecCKD-style gas optics.

struct GasOpticsStencil{FT}

Per-layer interpolation stencil for the coefficient tables of an EcCKDTabulatedGasOpticsModel: the (i₀, i₁, w) brackets on the log-pressure axis, the temperature axis (vector or pressure-dependent matrix grid) and the optional H₂O mole-fraction axis. The stencil depends only on the layer state, so a host builds it once per layer with gas_optics_stencil and reuses it across every g point and gas.

FT is the model's element type; the struct is isbits, and the six stored scalars (i₀ᵖ, wᵖ, i₀ᵀ, wᵀ, i₀ᴴ, wᴴ) rebuild it through GasOpticsStencil(i₀ᵖ, wᵖ, i₀ᵀ, wᵀ, i₀ᴴ, wᴴ). Without an H₂O table the H₂O bracket is a placeholder that is never indexed.

gas_optics_stencil(
    model::EcCKDTabulatedGasOpticsModel{FT},
    pressure,
    temperature,
    water_vapor_mole_fraction
) -> GasOpticsStencil

Interpolation stencil of model for one layer at pressure (Pa), temperature (K) and H₂O mole fraction water_vapor_mole_fraction (mol mol⁻¹, relative to dry air; ignored by models without an H₂O table). Off-table inputs clamp to the table edges. The stencil is built in the model's element type, so the coefficient tables are expected to share it.

Returns nothing for an EcCKDGasOpticsModel, whose coefficients are not interpolated.

layer_gases(
    gases::NamedTuple{Keys},
    _::Val{Names},
    k
) -> Any

Scalar gas amounts of layer k as a NamedTuple keyed by Names (the model's gas names), picked from a column gas container whose entries are per-layer vectors or column-wide scalars. A composite (dry air) entry the container carries outside Names is kept, since the relative-linear convention reads it.

gas_names(_::EcCKDGasOpticsModel{<:Any, GasNames}) -> Any

Gas names of an ecCKD gas-optics model as a Tuple of Symbols, in the gas order of its absorption tables. Layer gas containers passed to the layer optical-depth functions are keyed by these names.

longwave_optical_depth(
    model::EcCKDTabulatedGasOpticsModel,
    g,
    gases::NamedTuple,
    stencil::GasOpticsStencil
) -> Any

Longwave gas optical depth of one layer for g point g. gases is a NamedTuple of scalar layer amounts (mol m⁻²) keyed by the model's gas names, plus composite (dry air) when the model applies the ecCKD relative-linear convention; stencil is the layer's gas_optics_stencil. The total is clamped at zero.

shortwave_optical_depth(
    model::EcCKDTabulatedGasOpticsModel,
    g,
    gases::NamedTuple,
    stencil::GasOpticsStencil
) -> Any

Shortwave gas optical depth of one layer for g point g, with the same arguments as the longwave method.

water_vapor_table_optical_depth(
    model::EcCKDTabulatedGasOpticsModel{FT},
    table,
    water_vapor_moles,
    g,
    stencil::GasOpticsStencil
) -> Any

Contribution of the H₂O-mole-fraction-dependent table (longwave_water_vapor_absorption or shortwave_water_vapor_absorption) to a layer's optical depth for g point g: the trilinearly interpolated coefficient times the layer's H₂O amount water_vapor_moles (mol m⁻²). Zero when the model has no H₂O grid or the table is empty.

rayleigh_optical_depth(
    model::EcCKDTabulatedGasOpticsModel{FT},
    g,
    air_moles
) -> Any

Rayleigh scattering optical depth of one layer for shortwave g point g: the model's molar scattering coefficient times the layer's molar amount of air air_moles (mol m⁻²; Δp / (g mᵈ) for a hydrostatic layer). Zero when the model carries no Rayleigh table, and always zero for an EcCKDGasOpticsModel.

hydrostatic_air_moles(Δp, g, mᵈ) -> Any

Molar amount of air (mol m⁻²) in a layer of pressure thickness Δp (Pa) under hydrostatic balance, Δp / (g mᵈ), with the gravitational acceleration g and dry-air molar mass mᵈ (a PhysicalConstants carries both as gravity and dry_air_molar_mass). The result takes the promoted type of the arguments.

longwave_source(
    model::EcCKDGasOpticsModel{FT},
    g,
    temperature,
    _::Nothing
) -> Any

Longwave Planck source of g point g at temperature, in the model's per-unit-weight flux convention: the tabulated source interpolated with source_bracket from source_table_bracket, or longwave_source_scale[g] σT⁴ without a table, with σ the model's stefan_boltzmann field (set at construction, PhysicalConstants default).

source_table_bracket(_::EcCKDGasOpticsModel, temperature)

Bracket of temperature on the model's Planck source-table temperature grid, to pass to longwave_source; nothing when the model has no source table (an EcCKDGasOpticsModel, or a tabulated model without one), in which case the source is the scaled gray σT⁴. Off the table the source follows ecRad: above the last node (350 K in the reference tables) it is extrapolated linearly from the last interval, below the first node (120 K) it is scaled linearly to zero.

struct TabulatedSurfaceEmission{FT, M, B} <: AbstractArray{FT, 1}

Per-g-point surface longwave source of an ecCKD gas-optics model at one surface temperature, with the surface emissivity folded in: e[g] = ε B(Tˢ), where B is the model's longwave_source at that g point in its per-unit-weight flux convention. The Planck source-table bracket is taken once at construction, so indexing is one table interpolation per g point. An AbstractVector, it serves as surface_longwave_up of a LongwaveBoundaryConditions or as the surface_emission of streaming_longwave_fluxes!.

streaming_longwave_fluxes!(
    flux_up,
    flux_down,
    layer_optics,
    surface_emission,
    surface_albedo,
    toa_down,
    weights,
    Ng,
    Nz,
    transmittance,
    source_up
) -> Tuple{Any, Any}

No-scattering longwave interface fluxes of one column, streamed over g points and accumulated into flux_up and flux_down (length Nz + 1, top-down, interface 1 at the top of the atmosphere; both are zeroed here). Each layer is the ecRad half-level Planck path of CloudlessLongwave: with diffusivity D = 1.66 and the layer's (τ, Bₖ, Bₖ₊₁) from layer_optics(g, k), the layer transmittance is e^{-Dτ} and its emission is that of a Planck function linear in optical depth between the two interfaces (the thin-layer limit below τ = 10⁻³).

The column is swept downward first, from toa_down (the downwelling flux entering the top interface, the same for every g point), then upward from the surface, where up = surface_emission[g] + surface_albedo * down: surface_emission is indexable per g point with the emissivity already included (a TabulatedSurfaceEmission) and surface_albedo is the diffuse longwave surface albedo. Each g point's fluxes are added with weights[g] for g in 1:Ng. transmittance and source_up are caller scratch of length Nz that carry the layer coefficients from the downward sweep to the upward one. Allocation-free.

struct ShortwaveColumnScratch{V}

Per-column scratch storage for streaming_shortwave_fluxes!: five layer vectors of length Nz and two interface vectors of length Nz + 1. On the host V is a Vector{FT}; a host kernel hands in views of one row of its own device matrices instead, so the solver never allocates. Every element is written before it is read, so the storage need not be initialized.

Fields:

• reflectance: Layer diffuse reflectance, length Nz
• transmittance: Layer diffuse transmittance, length Nz
• direct_reflectance: Layer reflectance of the direct beam into the diffuse upward stream, length Nz
• direct_diffuse_transmittance: Layer transmittance of the direct beam into the diffuse downward stream, length Nz
• direct_flux: Normal-incidence direct-beam flux (W m⁻²) at the bottom of each layer, length Nz
• stack_albedo: Diffuse albedo of the stack below each interface, length Nz + 1
• source: Upward diffuse source (W m⁻²) of the stack below each interface, length Nz + 1

streaming_shortwave_fluxes!(
    flux_up,
    flux_down,
    layer_optics,
    μ₀,
    toa_irradiance,
    direct_albedo,
    diffuse_albedo,
    weights,
    Ng,
    Nz,
    scratch::ShortwaveColumnScratch
)

Clear-sky shortwave interface fluxes of one column by the two-stream adding method of ecRad, with every g point streamed through one ShortwaveColumnScratch and accumulated in place. flux_up and flux_down have length Nz + 1, are ordered top down (index 1 at the top of the atmosphere), and are zeroed here; FT = eltype(flux_up).

layer_optics(g, k) returns the tuple (τₐ, τₛ, 𝒢) of layer k for g point g; the single-scattering albedo ω = τₛ / (τₐ + τₛ) and the total optical depth are formed here, and every layer passes through shortwave_two_stream_layer, which applies delta-Eddington scaling. weights[g] scales the g point's contribution. direct_albedo and diffuse_albedo are broadband numbers or per-g-point indexables.

toa_irradiance is the downwelling shortwave flux through a horizontal surface at the top of the atmosphere, S₀ μ₀ for solar constant S₀, so the normal-incidence flux entering the adding sweeps is toa_irradiance / max(μ₀, √eps(FT)). The same clamped μ₀ is used throughout, matching shortwave_path_factor. A host that passes toa_irradiance = S₀ max(μ₀, 0) therefore gets exact zeros, and no NaN, at night (μ₀ ≤ 0).

Allocation-free; scratch may hold views into a host's own arrays.

shortwave_two_stream_layer(
    ::Type{FT},
    μ₀,
    τ,
    ω,
    𝒢
) -> NTuple{5, Any}
shortwave_two_stream_layer(
    ::Type{FT},
    μ₀,
    τ,
    ω,
    𝒢,
    direct_source_limit
) -> NTuple{5, Any}

Delta-Eddington-scale a layer and return its two-stream reflectance and transmittance. This is the single entry point every shortwave two-stream path uses, so the scaling cannot be skipped by one caller and applied by another.

shortwave_path_factor(_::Type{FT}, atmosphere) -> Any

Direct-beam slant-path factor 1 / μ₀ of a column, with μ₀ read from atmosphere.geometry.cos_zenith and clamped to √eps(FT) so that a sun on or below the horizon gives a finite path; 1 (a vertical path) when the atmosphere carries no solar geometry. streaming_shortwave_fluxes! applies the same clamp to the μ₀ it is handed directly.

struct SpectralCloudOptics{FT, V, M}

Cloud scattering properties of one hydrometeor phase mapped onto the g points of one EcCKDSpectralMapping, tabulated on Nr effective-radius nodes. The mass-extinction coefficient κ (m² kg⁻¹), single-scattering albedo ω, and asymmetry factor 𝒢 have shape (Ng, Nr); a layer's values are read by bracketing its effective radius with effective_radius_bracket and interpolating with cloud_layer_optics. The element type FT follows the stored arrays, so Adapt.adapt(Array{Float32}, cloud) yields a Float32 model.

Fields:

• effective_radius: Effective-radius nodes in m, strictly increasing, shape (Nr,)
• mass_extinction_coefficient: Mass-extinction coefficient in m² kg⁻¹, shape (Ng, Nr)
• single_scattering_albedo: Single-scattering albedo, shape (Ng, Nr)
• asymmetry_factor: Scattering asymmetry factor, shape (Ng, Nr)

effective_radius_bracket(
    cloud::SpectralCloudOptics{FT},
    radius
) -> Tuple{Any, Any, Any}

Bracket radius (m) on the effective-radius nodes of cloud: the tuple (i₀, i₁, w) such that a property p interpolates as (1 - w) p[g, i₀] + w p[g, i₁], clamped to the edge nodes off the grid. A one-node model brackets to (1, 1, 0) for every radius, and so does a Nothing phase, whose bracket is never indexed.

cloud_layer_optics(
    cloud::SpectralCloudOptics{FT},
    g,
    radius_bracket
) -> Tuple{Any, Any, Any}

Mass-extinction coefficient κ (m² kg⁻¹), single-scattering albedo ω, and asymmetry factor 𝒢 of cloud at g point g, interpolated on the effective-radius bracket (i₀, i₁, w) from effective_radius_bracket. On a one-node model (w = 0) the node values are returned exactly.

add_scattering_layer(
    τₐ,
    τₛ,
    𝒢,
    κ,
    ω,
    𝒢ᶜ,
    W
) -> Tuple{Any, Any, Any}

Fold one scattering constituent with mass-extinction coefficient κ, single-scattering albedo ω, asymmetry factor 𝒢ᶜ, and mass path W (kg m⁻²) into a layer's absorption optical depth τₐ, scattering optical depth τₛ, and scattering-weighted asymmetry factor 𝒢, returning the updated triple:

τₐ′ = τₐ + κ (1 - ω) W
τₛ′ = τₛ + κ ω W
𝒢′ = (𝒢 τₛ + 𝒢ᶜ κ ω W) / τₛ′,    or 0 when τₛ′ = 0

The asymmetry update is evaluated as 𝒢 + (𝒢ᶜ - 𝒢) κ ω W / τₛ′, which is the same number and leaves the layer bit-for-bit unchanged when W = 0.

add_cloud_scattering_layer(
    τₐ,
    τₛ,
    𝒢,
    cloud::SpectralCloudOptics,
    g,
    radius_bracket,
    W
) -> Tuple{Any, Any, Any}

Fold cloud at g point g on the effective-radius bracket from effective_radius_bracket with mass path W (kg m⁻²) into a layer's (τₐ, τₛ, 𝒢), returning the updated triple. A Nothing phase returns the layer unchanged.

cloud_absorption_optical_depth(
    cloud::SpectralCloudOptics,
    g,
    radius_bracket,
    W
) -> Any

Longwave cloud absorption optical depth κ (1 - ω) W of cloud at g point g for mass path W (kg m⁻²) on the effective-radius bracket from effective_radius_bracket; longwave cloud scattering is neglected. Zero for a Nothing phase.

cloud_optical_properties!(optics, cloud_model, atmosphere[, workspace])

Materialize cloud optical properties independently of gas optics and solvers.

cloud_optical_properties!(cloud, model::LayerCloudOpticsModel, atmosphere)

Fill caller-owned cloud optical depth arrays from a simple layer cloud-water path model.

cloud_optical_properties!(cloud, model::LayerLiquidIceCloudOpticsModel, atmosphere)

Fill caller-owned cloud optical depth arrays from phase-separated liquid/ice water paths and cloud fraction. This existing method returns grid-mean cloud optical depth for simple homogeneous-column composition. Use cloudy_region_optical_properties! for all-sky solvers that carry cloud fraction and overlap separately.

cloudy_region_optical_properties!(cloud, model::LayerLiquidIceCloudOpticsModel, atmosphere)

Fill caller-owned cloudy-region cloud optical properties from phase-separated liquid/ice water paths. Cloud fraction and overlap are stored separately and optical depths are not multiplied by cloud fraction.

aerosol_optical_properties!(optics, aerosol_model, atmosphere[, workspace])

Materialize aerosol optical properties independently of gas optics and solvers.

aerosol_optical_properties!(aerosol, model::LayerAerosolOpticsModel, atmosphere)

Fill caller-owned aerosol optical depth arrays from a simple layer aerosol-path model.

radiative_fluxes!(fluxes, solver, optics, atmosphere, boundary_conditions[, workspace])

Compute radiative fluxes from optical properties/source terms. Concrete solvers should overload this method.

radiative_fluxes!(fluxes, CloudlessLongwave(), optics, atmosphere, boundary_conditions)

Compute clear-sky longwave interface fluxes from precomputed optical depth and source terms. Arrays in fluxes are overwritten. The atmosphere argument is accepted for interface consistency and is not inspected by this solver.

radiative_fluxes!(fluxes, CloudlessShortwave(), optics, atmosphere, boundary_conditions)

Compute clear-sky shortwave interface fluxes from precomputed optical depth. Arrays in fluxes.shortwave_up and fluxes.shortwave_down are overwritten. When atmosphere.geometry.cos_zenith is present, optical depths are scaled by the direct-beam path length 1 / μ₀; otherwise the solver preserves the historical vertical-path convention.

Every g point with scattering runs the two-stream adding method of streaming_shortwave_fluxes!, so those g points match the streaming path bit for bit. A g point with no scattering at all takes a closed-form Beer–Lambert branch instead: the direct beam down the slant path, one Lambertian reflection, and the reflected flux attenuated back up along the same slant path, e^{-τ/μ₀}. The adding method treats the reflected flux as diffuse and attenuates it with the two-stream diffusivity factor 2, e^{-2τ}, so for such a g point the two paths agree on the downwelling flux but differ in the reflected flux except at μ₀ = 1/2, where the two attenuations coincide.

radiative_fluxes!(fluxes, CloudOverlapShortwave(), optics, atmosphere, boundary_conditions)

Compute clear and cloudy shortwave fluxes independently and blend the results with an explicit cloud-fraction overlap rule.

radiative_fluxes!(fluxes, CloudOverlapLongwave(), optics, atmosphere, boundary_conditions)

Compute all-sky longwave interface fluxes from clear/cloudy-region optical properties and explicit layer cloud fractions.

heating_rates!(heating, fluxes, atmosphere[, workspace])

Convert flux divergence to heating rates. Concrete atmosphere/flux pairings should overload this method when they do not use the existing column tendency helpers.

heating_rates!(heating, fluxes::RadiativeFluxes, atmosphere::ColumnAtmosphere;
               gravity = atmosphere.constants.gravity,
               heat_capacity = atmosphere.constants.heat_capacity)

Convert interface fluxes to layer heating rates in K s^-1. gravity and heat_capacity default to the column's PhysicalConstants; pass them to override.

Conventions:

• vertical indexing is top-down;
• pressure interfaces increase downward;
• net flux is positive downward;
• positive heating means atmospheric warming.

For layer k, the heating rate is

Ṫ[k] = g / cᵖ (ℐ[k] - ℐ[k + 1]) / Δp[k]

where ℐ = ℐꜜˡʷ - ℐꜛˡʷ + ℐꜜˢʷ - ℐꜛˢʷ is the net downward flux (longwave_down - longwave_up + shortwave_down - shortwave_up), and g and cᵖ are gravity and heat_capacity.

heating_rates!(heating, column::RadiativeTransferColumn)

Copy the current column temperature tendency into heating. This method gives the staged interface an allocation-free bridge to the existing analytic-band workspace.

diagnose_clouds(
    _::NoClouds,
    profile::AtmosphereProfile,
    geometry::ColumnGrid,
    surface::SurfaceState,
    constants::PhysicalConstants,
    thermodynamic::ThermodynamicConstants,
    cloud_top_convective::Integer
) -> NamedTuple{(:cloud_cover, :cloud_top, :cloud_albedo, :stratocumulus_cover, :stratocumulus_albedo), <:NTuple{5, Any}}

Returned tuple from cloud diagnosis: (cloud_cover, cloud_top, cloud_albedo, stratocumulus_cover, stratocumulus_albedo).

For NoClouds, cloud_top = Nz + 1 (below the surface) so downstream shortwave code skips the cloud-reflection branch.

read_cloud_scattering_table(path)

Read an ecRad-style cloud scattering NetCDF file. The core package does not depend on NetCDF libraries; NetCDF-backed loading is provided by the NCDatasets extension.

cloud_scattering_properties(table, iwavenumber, effective_radius)

Interpolate raw cloud scattering properties at one wavenumber-grid index and effective radius. Returns mass extinction, single-scattering albedo, and asymmetry factor.

cloud_scattering_gpoint_properties(table, mapping, effective_radius)

Map raw cloud-scattering table properties onto an ecCKD g-point grid using the resolved spectral intervals and gpoint_fraction weights from an EcCKDSpectralMapping. Returns vectors of mass extinction, single-scattering albedo, and asymmetry factor with one entry per g-point.

The current mapper samples the nearest cloud-scattering table wavenumber at each ecCKD interval midpoint and uses interval width times g-point fraction as the quadrature weight. Single-scattering albedo is extinction-weighted, and asymmetry is scattering-extinction-weighted.