API

AbstractRRTMGPMethod

An abstract type used for different radiation methods.

These subtypes are helpful for configuring lookup tables, and pre-configuring caches for different radiation modes.

AllSkyRadiation(aerosol_radiation::Bool, reset_rng_seed::Bool)

All-sky spectral radiation: gas absorption plus cloud optics, with cloud overlap sampled by McICA. Requires the lookup tables (load NCDatasets).

Fields

• aerosol_radiation::Bool: include aerosol optics.
• reset_rng_seed::Bool: when true, update_fluxes!(s, seedval) reseeds the RNG with seedval before the solve (hosts typically pass the timestep number); with no seedval the flag has no effect. Because the McICA cloud sampler draws random numbers, reseeding makes a CPU run fully reproducible and restartable; disable it for production runs. On the GPU the sampler draws from the device RNG, which this does not seed — per-column McICA sampling is not reproducible there (see build_cloud_mask!).

AllSkyRadiationWithClearSkyDiagnostics(aerosol_radiation::Bool, reset_rng_seed::Bool)

Like AllSkyRadiation, but each call also runs a parallel cloud-free (clear-sky) solve. Those fluxes are exposed through the clear_* getters (e.g., clear_net_flux, clear_lw_flux_up); differenced against the all-sky fluxes they give the cloud radiative effect. Requires the lookup tables (load NCDatasets).

Fields

• aerosol_radiation::Bool: include aerosol optics.
• reset_rng_seed::Bool: reseed the RNG from the seedval passed to update_fluxes! (see AllSkyRadiation).

GrayRadiation()

Gray-gas radiation: a single-band ("gray") atmosphere whose optical thickness follows a prescribed analytic profile (a GrayOpticalThickness* parameter set) instead of correlated-k lookup tables. Because it needs no NetCDF data, this is the standalone/teaching mode driven by solve_gray. Takes no options.

ClearSkyRadiation(aerosol_radiation::Bool)

Clear-sky spectral radiation: molecular (gas) absorption and emission from the correlated-k lookup tables, with no clouds. Requires the lookup tables (load NCDatasets).

Fields

• aerosol_radiation::Bool: include aerosol optics.

RRTMGPGridParams(
    FT;
    context::ClimaComms.AbstractCommsContext,
    domain_nlay::Int,
    ncol::Int,
    isothermal_boundary_layer::Bool = false,
)

Grid parameters for RRTMGP, parametrized on the float type FT.

Specify domain_nlay, the number of layers in your physical grid. When isothermal_boundary_layer = true, RRTMGP adds one extra layer at the top of the domain internally, so the stored field nlay — the total number of layers RRTMGP works with — is domain_nlay + 1 (and just domain_nlay when the flag is false). Callers never add the extra layer themselves, so the boundary-layer bookkeeping cannot be got wrong; the getters return domain-sized arrays and heating_rate reports on the physical grid.

Keyword Arguments

• context: the ClimaComms context.
• domain_nlay: the number of layers in the physical domain.
• ncol: the number of columns.
• isothermal_boundary_layer = false: whether RRTMGP adds an isothermal boundary layer/level at the top of the domain.

RRTMGPSolver

Aggregate bundling everything needed to run an RRTMGP radiation calculation. It holds the radiation configuration, the atmospheric state, the longwave and shortwave solvers, the lookup tables, and the output flux buffers, and exposes getter methods (e.g., layer_temperature, net_flux) to read and write its data. Construct it with the RRTMGPSolver constructor and drive it with update_fluxes!.

Fields

• grid_params: grid and device configuration (RRTMGPGridParams).
• radiation_method: the radiation method (gray, clear-sky, or all-sky).
• interpolation: scheme for filling level values from layer values.
• bottom_extrapolation: scheme for the bottom-level value.
• params: RRTMGP physical parameters.
• sws: shortwave RTE solver and its flux/scratch buffers.
• lws: longwave RTE solver and its flux/scratch buffers.
• as: the atmospheric state (solver inputs).
• lookups: the LookupBundle from lookup_tables (for gray radiation only the band counts are carried).
• presented_flux_lw, presented_flux_sw: host-facing (nlev, ncol) FluxPresentation copies of the longwave/shortwave fluxes, refreshed at the end of update_fluxes!; the flux getters return views of these.
• clear_flux_lw: clear-sky longwave fluxes ((nlev, ncol) presentation layout), or nothing.
• clear_flux_sw: clear-sky shortwave fluxes ((nlev, ncol) presentation layout), or nothing.
• center_z: layer-center altitudes [m], or nothing.
• face_z: level (face) altitudes [m], or nothing.
• deep_atmosphere_inverse_scaling: (nlev, ncol) factor multiplied into the fluxes for deep-atmosphere geometric scaling (the host supplies the multiplicative inverse of its metric scaling), or nothing (default) for the shallow-atmosphere approximation.
• net_flux_buffer: combined longwave + shortwave net flux at each level [W/m²], the full boundary-extended (nlev, ncol) buffer (read the domain-masked view via net_flux(s)).
• clear_net_flux_buffer: combined clear-sky net-flux buffer, or nothing.

Constructor

RRTMGPSolver(grid_params, radiation_method, params, bcs_lw, bcs_sw, as; <keyword arguments>)

Build a solver from the grid parameters, radiation method, physical params, the longwave and shortwave boundary conditions, and the atmospheric state. Keyword arguments:

• op_lw, op_sw: longwave/shortwave optics (OneScalar or TwoStream); default TwoStream.
• center_z, face_z: layer-center and level altitudes [m], needed only for z-based interpolation; default nothing.
• interpolation: scheme for filling level values from layer values; default NoInterpolation.
• bottom_extrapolation: scheme for the bottom-level value; default SameAsInterpolation.
• deep_atmosphere_inverse_scaling: a (nlev, ncol) array multiplied into the fluxes for deep-atmosphere geometric scaling (the host supplies the multiplicative inverse of its metric scaling), or nothing (default) for the shallow-atmosphere approximation.
• lookups: prebuilt lookup tables to reuse, or nothing (default) to build them internally.
• spectral_fluxes: if true, also retain per-band fluxes (two-stream, non-gray only); default false.
• n_gauss_angles: number of Gauss-Jacobi-5 quadrature angles (1-4) for the spectral non-scattering longwave hemispheric integral; default 1 (the diffusivity approximation). Not applicable to the two-stream longwave solver or to gray radiation, which reject anything but 1.

radiation_method(s::RRTMGPSolver)

Return the radiation method the solver was constructed with: GrayRadiation, ClearSkyRadiation, AllSkyRadiation, or AllSkyRadiationWithClearSkyDiagnostics.

optical_thickness_parameter(s::RRTMGPSolver)

For a gray-radiation solver, return the gray optical-thickness parameters (an AbstractGrayOpticalThickness, e.g., GrayOpticalThicknessOGorman2008) the atmospheric state was built with; nothing for lookup-table (non-gray) radiation, which has no such parameter.

lookup_tables(grid_params::RRTMGPGridParams, radiation_method::AbstractRRTMGPMethod)

Build the lookup tables for radiation_method, returning a LookupBundle containing the gas/cloud/aerosol lookup tables, the name→index maps, and the band/gas counts. Build it once and pass it back to the RRTMGPSolver constructor via lookups = ... to reuse the tables, or cache it on disk with save_lookup_tables.

The spectral methods are provided by an extension: load NCDatasets (using NCDatasets) first (or use load_lookup_tables from a cache).

LookupBundle

Typed, immutable bundle of everything RRTMGPSolver needs from the lookup artifacts: the gas/cloud/aerosol lookup tables for each band (absent entries are nothing), the gas and aerosol name→index maps, and the band/gas counts. Built by lookup_tables; pass a prebuilt bundle back to the RRTMGPSolver constructor via lookups = ... to avoid a second NetCDF read, and use save_lookup_tables/load_lookup_tables to cache it on disk (e.g., for standalone use without NCDatasets).

Fields

• lookup_lw, lookup_sw: gas-optics lookup tables (nothing for gray).
• lookup_lw_cld, lookup_sw_cld: cloud-optics tables (all-sky methods only).
• lookup_lw_aero, lookup_sw_aero: aerosol tables (aerosol_radiation only).
• idx_gases_lw, idx_gases_sw: gas name → index maps.
• idx_aerosol_lw, idx_aerosol_sw, idx_aerosize_lw, idx_aerosize_sw: aerosol name → index and size-bin maps.
• nbnd_lw, nbnd_sw: band counts (1 for gray).
• ngas_lw, ngas_sw: gas counts (0 for gray).

save_lookup_tables(path, lookups::LookupBundle)

Serialize lookups to path (host-side copies of any device arrays), so a later session can load_lookup_tables without NCDatasets (e.g., for standalone/classroom use of the spectral methods, or to skip the NetCDF read). Uses Julia's Serialization stdlib: the file is tied to the Julia version and package layout that wrote it and serves as a cache; the NetCDF artifacts remain the authoritative data. Returns path.

load_lookup_tables(path, grid_params::RRTMGPGridParams)

Load a LookupBundle previously written by save_lookup_tables and move its tables to the device described by grid_params. See save_lookup_tables for the cache-format caveats.

update_fluxes!(s::RRTMGPSolver, seedval = nothing)

Run the radiation update: prepare the atmospheric state (interpolate levels, add the isothermal boundary layer, clip pressures/temperatures/humidity to the range the optics support, and compute concentrations), solve the longwave and shortwave problems (applying deep_atmosphere_inverse_scaling if present), and combine them into the net flux. Mutates s in place (its atmospheric state and flux buffers) and returns nothing (read results via net_flux(s) and the other flux getters). When the radiation method requests reproducible seeding, seedval reseeds the RNG used for cloud sampling.

This is designed to be allocation-free and type-stable, which matters because a host calls it every radiation step. CI asserts @allocated == 0 and JET.@test_opt for the gray Layer-2 aggregate and for the Layer-1 solve_lw!/solve_sw! kernels of the spectral modes (single-threaded CPU).

See also prepare_atmosphere!, update_lw_fluxes!, update_sw_fluxes!, and update_net_fluxes!.

prepare_atmosphere!(s::RRTMGPSolver)

Run the atmospheric-state preparation cascade without solving: interpolate level pressures/temperatures from layer values (per the solver's interpolation/bottom_extrapolation configuration; a no-op for NoInterpolation), fill the isothermal boundary layer (when configured), clip unphysical inputs (pressures below the lookup tables' minimum, negative water vapor, and — for non-gray optics — temperatures outside the lookup tables' range), and compute the dry-air column amounts. Mutates the solver's atmospheric state in place and returns nothing.

update_fluxes! calls this before solving; call it to inspect the prepared state (interpolated level values, column amounts) without running the radiative transfer (the prepare/solve split familiar from other radiation drivers). Relative humidity is managed by the host (see update_concentrations!).

update_sw_fluxes!(s::RRTMGPSolver)

Update the shortwave fluxes, leaving the shortwave flux getters consistent (the (ncol, nlev) compute buffers are transposed into the (nlev, ncol) presentation the getters expose).

update_lw_fluxes!(s::RRTMGPSolver)

Update the longwave fluxes, leaving the longwave flux getters consistent (the (ncol, nlev) compute buffers are transposed into the (nlev, ncol) presentation the getters expose).

update_net_fluxes!(s::RRTMGPSolver)

Combine the longwave and shortwave net fluxes into net_flux(s) (and, for AllSkyRadiationWithClearSkyDiagnostics, the clear-sky pair into clear_net_flux(s)).

check_values

Global toggle for input validation: when enabled with RRTMGP.check_values[] = true, update_fluxes! calls validate_inputs before each solve. Off by default; the checks reduce over device arrays, so they are intended for development and debugging. With the toggle off, update_fluxes! remains allocation-free.

validate_inputs(s::RRTMGPSolver)

Validate the solver's host-provided inputs against their physical ranges, raising an informative error on the first violation:

• level/layer pressures and temperatures: positive and finite,
• cos_zenith ∈ [-1, 1], toa_sw_flux_dn ≥ 0,
• surface emissivity and the two shortwave surface albedos ∈ [0, 1],
• gas volume mixing ratios ≥ 0 (spectral states).

Runs automatically inside update_fluxes! when check_values[] = true; can also be called directly at any time. Reduces over the solver's device arrays (not allocation-free).

Numerics

The numerical policy of RRTMGP.jl in one place: every floating-point guard constant used by the optics/RTE kernels, with its derivation, plus small numerical utilities. All constants scale with the working precision FT (compare epsilon(1._wp)-based parameters in the Fortran reference, rte-rrtmgp), so kernels behave consistently at Float32 and Float64.

k_min(::Type{FT})

Floor for the two-stream diffusion eigenvalue k = sqrt((γ1−γ2)(γ1+γ2)), applied under the square root. k → 0 for isotropic, conservative scattering (ssa → 1, the (γ1−γ2) factor vanishes); flooring k² at sqrt(eps(FT)) keeps k ≥ eps^(1/4) so the e^{−2kτ} cancellations in the diffuse reflectance/transmittance stay resolvable. The relative error with respect to the conservative-scattering limit is < 0.1% down to τ ~ 1e-9 (see the analogous min_k = 1e4·epsilon bound and note in rte-rrtmgp, credited to Chiel van Heerwaarden; swirl-lm floors k itself at 1e-2 for the same reason).

τ_thresh(::Type{FT})

Optical-depth threshold at which the longwave no-scattering source factor fact = (1 − T)/τ − T (Clough et al. 1992, Eq 13) switches to its 3rd-order series τ(1/2 − τ/3 + τ²/8). The direct form loses ~eps/τ² to cancellation; the series truncates at ~τ³. The two error curves cross at τ ~ eps^(1/4) (≈ 1.9e-2 at Float32, ≈ 1.2e-4 at Float64) — matching rte-rrtmgp's tau_thresh = sqrt(sqrt(epsilon(tau))), credited to Peter Blossey and Dmitry Alexeev.

resonance_window(::Type{FT})

Half-width of the window around the removable singularity of the shortwave direct reflectance/transmittance (Meador & Weaver 1980, Eqs 14–15) at k·μ₀ = 1, inside which k·μ₀ is nudged off resonance. At the window edge |1 − k²μ₀²| = sqrt(eps), the directly computed denominator still carries ≤ sqrt(eps) relative rounding, matching the O(sqrt(eps)) perturbation from the nudge — the balanced choice.

μ₀_min(::Type{FT})

Floor for the cosine of the solar zenith angle wherever the shortwave solvers divide by μ₀ (exp(−τ/μ₀) arguments). Columns with μ₀ ≤ 0 are excluded from the solve and zeroed, so the floor only guards against division by a zero/denormal μ₀ at the day–night terminator; the resulting exp argument overflows negative and the flux underflows to zero, as it should. (The Fortran reference uses sqrt(eps) for its round-earth path, where deep layers with μ₀ ≤ 0 are computed nominally and masked afterwards; RRTMGP.jl skips those columns instead, so a smaller floor suffices.)

pow_fast(x, y)

x^y via exp(y·log(x)) for x > 0. Julia's generic x^y hits a slow path for bases very close to 1, which the gray optical-depth profile evaluates often.

spectral_lw_flux_up(s::RRTMGPSolver)

Return the per-band upward longwave flux [W/m²]: a domain-masked (nlev, ncol, n_bnd) view. Requires spectral_fluxes = true; see lw_band_bounds for each band's wavenumber range.

spectral_lw_flux_dn(s::RRTMGPSolver)

Return the per-band downward longwave flux [W/m²]: a domain-masked (nlev, ncol, n_bnd) view. Requires spectral_fluxes = true; see lw_band_bounds for each band's wavenumber range.

spectral_lw_flux_net(s::RRTMGPSolver)

Return the per-band net (up - down) longwave flux [W/m²]: a domain-masked (nlev, ncol, n_bnd) view. Requires spectral_fluxes = true; see lw_band_bounds for each band's wavenumber range.

spectral_sw_flux_up(s::RRTMGPSolver)

Return the per-band upward shortwave flux [W/m²]: a domain-masked (nlev, ncol, n_bnd) view. Requires spectral_fluxes = true; see sw_band_bounds for each band's wavenumber range.

spectral_sw_flux_dn(s::RRTMGPSolver)

Return the per-band downward shortwave flux [W/m²]: a domain-masked (nlev, ncol, n_bnd) view. Requires spectral_fluxes = true; see sw_band_bounds for each band's wavenumber range.

spectral_sw_flux_net(s::RRTMGPSolver)

Return the per-band net (up - down) shortwave flux [W/m²]: a domain-masked (nlev, ncol, n_bnd) view. Requires spectral_fluxes = true; see sw_band_bounds for each band's wavenumber range.

lw_band_bounds(s::RRTMGPSolver)

Return the (2, n_bnd) lower/upper wavenumber edges [cm⁻¹] of the longwave bands, identifying the spectral range of each band in the per-band fluxes (e.g., spectral_lw_flux_up).

sw_band_bounds(s::RRTMGPSolver)

Return the (2, n_bnd) lower/upper wavenumber edges [cm⁻¹] of the shortwave bands, identifying the spectral range of each band in the per-band fluxes (spectral_sw_flux_up and companions).

FluxBand{FT, FTA3D}

Optional per-band upward, downward, and net radiative fluxes at each level, (nlev, ncol, n_bnd). Only allocated when spectrally-resolved fluxes are requested. Summing over the band dimension recovers the broadband fluxes.

Unlike the broadband compute buffers, the band buffers keep the host-facing vertical-first layout: they are an opt-in diagnostic that the spectral_* getters expose as plain views, and keeping them (nlev, ncol, n_bnd) avoids doubling their (large) memory with separate presentation copies. The accumulation writes are uncoalesced on the GPU, a cost paid only when per-band fluxes are requested.

Fields

• flux_up: upward flux per band [W/m²], (nlev, ncol, n_bnd).
• flux_dn: downward flux per band [W/m²], (nlev, ncol, n_bnd).
• flux_net: net flux per band (flux_up - flux_dn) [W/m²], (nlev, ncol, n_bnd).

AbstractInterpolation

Strategy for obtaining cell-face (level) pressures and temperatures from cell-center (layer) values, or vice versa, used when only one of the two is provided. The scheme interpolates on interior faces and extrapolates on boundary faces.

Subtypes:

• NoInterpolation: levels are supplied directly; do not interpolate.
• ArithmeticMean: arithmetic mean of the two adjacent layers.
• GeometricMean: geometric mean of the two adjacent layers.
• UniformZ: assume the face lies midway in height between the layers.
• UniformP: assume the face lies midway in pressure between the layers.
• BestFit: constant-lapse-rate fit using layer altitudes; requires center_z and face_z.

The derivations, and guidance on choosing a scheme, are on the "Level interpolation" docs page.

AbstractBottomExtrapolation

Strategy for obtaining the bottom cell-face (level) pressure and temperature from the layer values above it.

Subtypes:

• SameAsInterpolation: extrapolate using the interpolation scheme.
• UseSurfaceTempAtBottom: set the bottom-face air temperature to the surface temperature.
• HydrostaticBottom: assume a dry-adiabatic lapse rate; requires center_z and face_z.

interpolate_levels!(as, interpolation, bottom_extrapolation, params;
                    center_z = nothing, face_z = nothing,
                    isothermal_boundary_layer = false)

Fill the level (cell-face) pressures and temperatures of as by interpolating and extrapolating its layer (cell-center) values: interpolation is used on the interior faces and the top face, and bottom_extrapolation on the bottom face. A no-op for NoInterpolation (the caller is assumed to have provided level values directly). center_z / face_z are required only for z-based methods (BestFit, HydrostaticBottom). Mutates as in place and returns it.

add_isothermal_boundary_layer!(as, p_min)

Fill the extra (top) isothermal layer of as: its top level pressure is set to p_min, while its layer/level temperatures, relative humidity, volume mixing ratios, cloud properties, and aerosol properties are copied from the layer below. Mutates as in place and returns it.

clip!(as, p_min[, idx_h2o]; t_min = nothing, t_max = nothing)

Clip the layer/level pressures of as to be at least p_min, and (for non-gray states) clip the water-vapor volume mixing ratio to be nonnegative and clamp the layer/level temperatures into [t_min, t_max] (pass the valid range of the optics lookup tables; nothing skips the temperature clamp). Mutates as in place and returns it.

The gray state applies no temperature clamp: it uses no lookup tables, and its analytic optics remain valid for temperatures an idealized atmosphere may reach outside the lookup range.

update_concentrations!(as, params, device[, idx_h2o])

Compute the column dry-air amount of as from its level pressures and water-vapor volume mixing ratio. A no-op for gray radiation. Mutates as in place and returns it.

This updates only the dry-air column amount (compute_col_gas!); it does not recompute relative humidity. Relative humidity is a host responsibility: a caller that needs an up-to-date layer_relative_humidity (e.g., for RH-dependent aerosol optics) must call compute_relative_humidity! itself after updating temperature, pressure, or humidity.

get_p_min(as, lookup_lw)

Return the minimum pressure supported by the radiation scheme: zero for gray radiation, and the longwave lookup table's reference minimum pressure otherwise.

get_t_min(as, lookup_lw)

Return the lower temperature bound of the radiation scheme's valid interpolation range: the longwave lookup table's first reference temperature for non-gray radiation, and nothing for gray radiation (which has no temperature lookup and whose temperatures are left unclipped). Pass to clip!; nothing makes its temperature clamp a no-op. See also get_t_max.

get_t_max(as, lookup_lw)

Return the upper temperature bound of the radiation scheme's valid interpolation range: the longwave lookup table's last reference temperature for non-gray radiation, and nothing for gray radiation. Pass to clip!; nothing makes its temperature clamp a no-op. See also get_t_min.

NoInterpolation()

Take the level (cell-face) pressures and temperatures as the caller supplied them; interpolate nothing.

ArithmeticMean()

Set each interior face to the arithmetic mean of its two adjacent layers, in both pressure and temperature, and extrapolate linearly at boundary faces.

GeometricMean()

Set each interior face to the geometric mean of its two adjacent layers, in both pressure and temperature (the constant-lapse-rate state at the log-pressure midpoint), and extrapolate logarithmically at boundary faces.

UniformZ()

Place each interior face midway in height between its two adjacent layers: average the temperature, then take the pressure from the constant-lapse-rate power law.

UniformP()

Place each interior face midway in pressure between its two adjacent layers: average the pressure, then invert the constant-lapse-rate power law for the temperature.

BestFit()

Place each face at its true altitude on the constant-lapse-rate profile through the two adjacent layers. Requires center_z and face_z.

SameAsInterpolation()

Extrapolate the bottom face with the same scheme used for the other boundary faces, so its air temperature is set by the atmosphere alone and may differ from the ground temperature.

UseSurfaceTempAtBottom()

Set the bottom-face air temperature to the surface temperature (the limit of strong turbulent heat exchange at the surface) and take the pressure from the dry isentrope through the first layer.

HydrostaticBottom()

Extend the first layer down to the bottom face at the dry-adiabatic lapse rate, with the isentropic pressure. Requires center_z and face_z.

requires_z(scheme)

Return whether scheme needs layer and face altitudes (center_z, face_z) at construction: true for BestFit and HydrostaticBottom, false for every other scheme.

interp!(scheme, p, T, pꜜ, Tꜜ, pꜛ, Tꜛ)
interp!(::BestFit, p, T, z, pꜜ, Tꜜ, zꜜ, pꜛ, Tꜛ, zꜛ)

Fill the interior-face pressures p and temperatures T from the layers below (pꜜ, Tꜜ) and above (pꜛ, Tꜛ) according to scheme. Add a method to support a new AbstractInterpolation.

extrap!(scheme, p, T, p⁺, T⁺, p⁺⁺, T⁺⁺, Tₛ, params)
extrap!(::BestFit, p, T, z, p⁺, T⁺, z⁺, p⁺⁺, T⁺⁺, z⁺⁺, Tₛ, params)

Fill a boundary-face pressure p and temperature T from the nearest layer (p⁺, T⁺), the next one in (p⁺⁺, T⁺⁺), the surface temperature Tₛ, and params, according to scheme. Add a method to support a new AbstractInterpolation or AbstractBottomExtrapolation.

uniform_z_p(T, p₁, T₁, p₂, T₂)

Return the pressure at temperature T on the constant-lapse-rate hydrostatic power law through (p₁, T₁) and (p₂, T₂), degenerating to the geometric mean of the pressures in the isothermal limit T₁ == T₂.

best_fit_p(T, z, p₁, T₁, z₁, p₂, T₂, z₂)

Return the pressure at temperature T and altitude z on the constant-lapse-rate hydrostatic power law through (p₁, T₁, z₁) and (p₂, T₂, z₂), using the altitudes in the isothermal limit T₁ == T₂.

aerosol_radius(s::RRTMGPSolver, name::AbstractString)

Return the aerosol radius for the given aerosol name.

Available names are: ["dust1", "sea_salt1", "sulfate", "black_carbon_rh", "black_carbon", "organic_carbon_rh", "organic_carbon", "dust2", "dust3", "dust4", "dust5", "sea_salt2", "sea_salt3", "sea_salt4", "sea_salt5"]

aerosol_column_mass_density(s::RRTMGPSolver, name::AbstractString)

Return the aerosol column mass density [kg/m²] for the given aerosol name.

Available names are: ["dust1", "sea_salt1", "sulfate", "black_carbon_rh", "black_carbon", "organic_carbon_rh", "organic_carbon", "dust2", "dust3", "dust4", "dust5", "sea_salt2", "sea_salt3", "sea_salt4", "sea_salt5"]

aerosol_index_map()

Return the canonical mapping from aerosol species name to its index in the AerosolState arrays (aero_mass, aero_size). This ordering is shared by the optics kernel, the lookup-table loader, and the state accessors. Returns a fresh copy; mutating it does not affect RRTMGP.

canonical_aerosol_name(name)

Resolve an aerosol name to its canonical name. Throws if name is unknown.

aerosol_index(name)

Return the index, into the AerosolState arrays, of aerosol name.

volume_mixing_ratio(s::RRTMGPSolver, name::AbstractString)

Return the volume mixing ratio for gas name. "h2o" and "o3" vary by layer and column (a domain-masked (nlay, ncol) view); with the global-mean VmrGM storage every other (well-mixed) gas is a single scalar.

A well-mixed scalar is returned as a host Number copied off the device, so each call triggers a device→host synchronization on the GPU. Read these during setup to maintain performance.

Available names are: ["h2o", "cfc11", "h2o_self", "co2", "cfc12", "hfc134a", "cfc22", "ch4", "hfc23", "ccl4", "hfc143a", "co", "no2", "n2", "o2", "o3", "h2o_frgn", "hfc32", "n2o", "cf4", "hfc125"]

set_volume_mixing_ratio!(s::RRTMGPSolver, name::AbstractString, value)

Set the volume mixing ratio for gas name to value, returning value.

This is the write counterpart to volume_mixing_ratio. For "h2o"/"o3" (and, with per-layer Vmr storage, every gas), value broadcasts over the (nlay, ncol) field, so it may be a scalar or a domain-sized array. For a well-mixed gas with the default global-mean (VmrGM) storage, the mixing ratio is a single scalar; pass a scalar value.

Unlike volume_mixing_ratio, this is the supported way to update a well-mixed gas: that getter returns a read-only host copy, so volume_mixing_ratio(s, name) .= value does not write back. Use this to update time-varying trace gases (e.g. prescribed CO₂).

Available names are: ["h2o", "cfc11", "h2o_self", "co2", "cfc12", "hfc134a", "cfc22", "ch4", "hfc23", "ccl4", "hfc143a", "co", "no2", "n2", "o2", "o3", "h2o_frgn", "hfc32", "n2o", "cf4", "hfc125"]

VolumeMixingRatioGlobalMean(grid_params::RRTMGPGridParams; vmr_h2o, vmr_o3, vmr)

Return a VmrGM given:

• grid_params::RRTMGPGridParams: grid parameters
• vmr_h2o: (nlay, ncol) volume mixing ratio of H₂O
• vmr_o3: (nlay, ncol) volume mixing ratio of O₃
• vmr: (ngas,) global-mean volume mixing ratios of the well-mixed gases

default_parameters(FT)

Return Earth-like RRTMGP physical parameters as an RRTMGPParameters{FT}, so the gray standalone path needs neither NCDatasets nor ClimaParams. Override individual values by constructing RRTMGP.Parameters.RRTMGPParameters directly.

AtmosphereProfile

A self-contained, host-side description of a clear-sky atmospheric column (or ncol identical columns), as produced by standard_atmosphere and consumed by solve. All arrays are plain Array{FT} on the host; solve moves them to the compute device.

Fields

• p_lay, p_lev: layer-center and level pressures [Pa], (nlay, ncol) and (nlay + 1, ncol).
• t_lay, t_lev: layer-center and level temperatures [K], (nlay, ncol) and (nlay + 1, ncol).
• z_lev: level altitudes [m], (nlay + 1, ncol).
• t_sfc: surface temperature [K], (ncol,).
• lat: latitude [degrees], (ncol,).
• vmr_h2o, vmr_o3: water-vapor and ozone volume mixing ratios, (nlay, ncol).
• well_mixed_vmr: Dict of global-mean volume mixing ratios for the well-mixed gases, keyed by the RRTMGP gas names (see gas_names_sw); gases not listed are taken as zero.

standard_atmosphere(FT; kind = :midlatitude_summer, nlay = 60, ncol = 1,
                    z_top = 45.0e3, p_sfc = 101325.0,
                    params = default_parameters(FT))

Build an idealized clear-sky AtmosphereProfile on nlay layers with levels uniformly spaced in altitude from the surface to z_top [m]:

• temperature: a constant tropospheric lapse rate up to an idealized tropopause, linear warming above (per-kind parameters);
• pressure: the exact hydrostatic profile for that temperature structure;
• water vapor: exponential decay (2 km scale height) to a 4 ppmv stratospheric floor; ozone: a log-pressure Gaussian layer peaking near 30 km; well-mixed gases at present-day global means (CO₂ 420 ppmv, CH₄ 1.9 ppmv, N₂O 0.34 ppmv, CO 0.1 ppmv, O₂ 0.209, N₂ 0.781).

kind selects the idealized climatology: :tropical, :midlatitude_summer (default), or :subarctic_winter. The profiles are analytic and idealized (made for teaching and testing). All ncol columns are identical.

solve(profile::AtmosphereProfile; method = ClearSkyRadiation(false), kwargs...)

Solve the radiative-transfer problem for an AtmosphereProfile and return a RadiationOutput. Builds the atmospheric state, boundary conditions, and an RRTMGPSolver internally, then runs update_fluxes!:

using RRTMGP, NCDatasets
profile = RRTMGP.standard_atmosphere(Float64; kind = :tropical)
out = RRTMGP.solve(profile)
out.net_flux     # net flux at each level [W/m²]
out.heating_rate # heating rate at each layer [K/s]

method selects the radiation model: ClearSkyRadiation(false) (the default; requires lookup tables, so load NCDatasets first or pass cached lookups) or GrayRadiation() (runs after using RRTMGP). For cloud and aerosol methods, construct an RRTMGPSolver.

Keyword Arguments

• method = ClearSkyRadiation(false): the radiation method (see above).
• context = ClimaComms.context(): the ClimaComms context (CPU or GPU); the profile's host arrays are copied to the device.
• params = default_parameters(FT): RRTMGP physical parameters.
• lookups = nothing: prebuilt LookupBundle to reuse (avoids the NetCDF read when solving many profiles); nothing builds them internally.
• surface_emissivity = 1: longwave surface emissivity [-].
• cos_zenith = 0.5: cosine of the solar zenith angle [-].
• toa_flux = 1361: top-of-atmosphere solar flux [W/m²].
• surface_albedo = 0.2: shortwave surface albedo [-].
• optical_thickness = GrayOpticalThicknessOGorman2008(FT): gray optical-thickness parameters (GrayRadiation only).
• interpolation = NoInterpolation(): how update_fluxes! rebuilds the level (cell-face) pressures and temperatures from the layer values on each call (see AbstractInterpolation); the default uses the profile's level values as given. Useful when a driver marches the layer temperatures and wants the faces kept consistent automatically.
• bottom_extrapolation = SameAsInterpolation(): scheme for the bottom face (see AbstractBottomExtrapolation).
• isothermal_boundary_layer = false: extend the column above the profile with one isothermal layer reaching the lookup tables' minimum pressure (zero pressure for GrayRadiation), so the radiation sees the mass above the profile's top instead of truncating there (see RRTMGPGridParams). The returned fluxes and heating rates stay on the profile's own grid.

RadiationOutput

The result of a standalone radiation solve (solve or solve_gray): the broadband fluxes, the heating rate, and the underlying solver. The flux fields are views into the solver's buffers; heating_rate is a freshly allocated array.

Fields

The field names match the getters of the same name, so one vocabulary covers both the standalone and the solver-driven paths.

• lw_flux_up, lw_flux_dn, lw_flux_net: longwave up/down/net flux [W/m²], (nlev, ncol).
• sw_flux_up, sw_flux_dn, sw_direct_flux_dn, sw_flux_net: shortwave up/down/direct-beam/net flux [W/m²], (nlev, ncol).
• net_flux: combined longwave + shortwave net flux [W/m²], (nlev, ncol).
• heating_rate: radiative heating rate [K/s], (nlay, ncol).
• solver: the RRTMGPSolver, for getter access and re-solves.

solve_gray(FT; kwargs...)

Set up and solve a gray-atmosphere radiation problem in a single call. Requires no NetCDF lookup tables, so it runs standalone after using RRTMGP. Builds the pressure/temperature profile (Schneider-2004-style), the surface boundary conditions, and an RRTMGPSolver, then runs update_fluxes!.

Keyword Arguments

• context = ClimaComms.context(): the ClimaComms context (CPU or GPU).
• nlay = 60: number of (physical) layers. The standalone path adds no isothermal boundary layer, so this is the whole grid; the Layer-2 RRTMGPGridParams constructor names the same physical quantity domain_nlay.
• ncol = 1: number of columns (ignored if latitude is given).
• latitude = nothing: latitudes [degrees]; defaults to the equator for a single column, or an evenly spaced pole-to-pole range otherwise.
• surface_pressure = 1.0e5: surface pressure [Pa].
• top_pressure = 9.0e3: top-of-atmosphere pressure [Pa].
• optical_thickness = GrayOpticalThicknessOGorman2008(FT): gray optical-thickness parameters.
• params = default_parameters(FT): RRTMGP physical parameters.
• surface_emissivity = 1: longwave surface emissivity [-].
• cos_zenith = 0.5: cosine of the solar zenith angle [-].
• toa_flux = 1361: top-of-atmosphere solar flux [W/m²].
• surface_albedo = 0.2: shortwave surface albedo [-].

Returns

A RadiationOutput with the level fluxes, the layer heating rate, and the underlying solver.

Examples

using RRTMGP
out = RRTMGP.solve_gray(Float64; nlay = 60, ncol = 1)
out.net_flux     # net flux at each level [W/m²]
out.heating_rate # heating rate at each layer [K/s]

heating_rate(s::RRTMGPSolver)

Return the radiative heating rate at each layer [K/s], computed from the net flux divergence (g / cₚ) ∂F_net/∂p. Call update_fluxes!(s) first. Allocates and returns a fresh (nlay, ncol) array.

gas_names_sw()

Return a vector containing the gas names in the shortwave lookup tables.

This should be the same list of gases returned from the following code, and is tested in lookup_tables

function gas_names_sw_from_artifacts()
   artifact(t, b, n) =
       NC.Dataset(RRTMGP.ArtifactPaths.get_lookup_filename(t, b)) do ds
           getproperty(RRTMGP.LookUpTables, n)(ds, Float64, Array)
       end
   _, idx_gases_sw = artifact(:gas, :sw, :LookUpSW)
   return keys(idx_gases_sw)
end

aerosol_names()

Return the canonical aerosol species names, ordered by their index, so that aerosol_names()[i] is the species stored at index i of the AerosolState arrays. Returns a fresh copy — mutating it does not affect RRTMGP.