ecCKD and Data

struct EcCKDDefinition{D, V, A}

Dependency-free summary of an ecCKD CKD-definition file.

This structure stores the schema-level information needed before materializing lookup tables into runtime gas-optics models. A NetCDF reader extension can populate it from reference ecCKD files without making NCDatasets.jl a hard dependency of the core package.

Fields:

• model_name: Model name from file metadata or user-provided configuration
• version: Model version from file metadata or user-provided configuration
• dimensions: Named dimensions and their lengths
• variables: Named variables and their dimension tuples
• attributes: Additional global attributes

struct EcCKDSchemaSummary

Small validation-oriented summary returned by summarize_ecckd_definition.

Fields:

• model_name: Model name from file metadata or user-provided configuration
• version: Model version from file metadata or user-provided configuration
• longwave_bands: Number of longwave bands, or 0 when the file has none
• shortwave_bands: Number of shortwave bands, or 0 when the file has none
• longwave_gpoints: Number of longwave g points, or 0 when the file has none
• shortwave_gpoints: Number of shortwave g points, or 0 when the file has none
• gases: Gas names present in the definition
• pressure_grid_size: Length of the pressure lookup grid
• temperature_grid_size: Length of the temperature lookup grid
• source_tables_present: Whether the file carries Planck source tables
• rayleigh_tables_present: Whether the file carries Rayleigh scattering tables

struct EcCKDModelSpec

Named pair of reference ecCKD longwave and shortwave CKD-definition files.

Fields:

• name: Public model-pair selector, for example :climate_32x32
• longwave: Reference longwave CKD-definition key
• shortwave: Reference shortwave CKD-definition key
• description: Human-readable summary for docs and logging

struct EcCKDSpectralMapping{FT, V, M}

Spectral mapping from ecCKD resolved wavenumber intervals to g-points.

wavenumber1 and wavenumber2 describe the resolved spectral intervals in cm^-1. gpoint_fraction has shape (wavenumber, g) and gives the fractional contribution of each interval to each gas-optics g-point.

Fields:

• wavenumber1: Lower wavenumber edge for each resolved spectral interval in cm^-1
• wavenumber2: Upper wavenumber edge for each resolved spectral interval in cm^-1
• gpoint_fraction: Fractional contribution with shape (wavenumber, g)
• interval_weight: Spectral interval weights, e.g. solar irradiance or Planck weights

struct EcCKDGasOpticsModel{FT, GasNames, LWA, SWA, LWS, LWW, SWW} <: AbstractGasOpticsModel

Small ecCKD-style forward gas-optics model for staged runtime integration.

This type is intentionally limited to fixed, already-interpolated coefficient tables. It gives host models an allocation-free runtime path from gas columns to longwave and shortwave optical properties.

longwave_absorption and shortwave_absorption are shaped (Ng, Ngases). Gas values in ColumnAtmosphere are interpreted as layer absorber amounts. A gas value may be a scalar, in which case it is applied to every layer, or a vector with one entry per layer. The gray longwave source is longwave_source_scale[g] σT⁴ with the model's stefan_boltzmann (keyword; PhysicalConstants default).

struct EcCKDTabulatedGasOpticsModel{FT, GasNames, PG, TG, HG, GREF, LWA, SWA, LHWA, SHWA, SWR, LWS, LST, LSTB, LWW, SWW, S} <: AbstractGasOpticsModel

ecCKD-style tabulated gas-optics model with bilinear pressure/temperature interpolation.

longwave_absorption and shortwave_absorption are shaped (Ng, Ngases, Npressures, Ntemperatures). The runtime method interpolates coefficients for each layer, multiplies them by layer absorber amounts from ColumnAtmosphere, and writes caller-owned optical-property arrays. The pressure and optional H₂O grids must be positive and uniformly spaced in log coordinates, matching the ecCKD file format. A matrix temperature grid is shaped (Npressures, Ntemperatures) and must use one positive temperature increment throughout. Without a Planck source table the longwave source is the gray longwave_source_scale[g] σT⁴ with the model's stefan_boltzmann (keyword; PhysicalConstants default).

Set lookup_search=FixedBinarySearch() to bracket vector temperature and Planck-source tables with a fixed number of binary-search iterations, suitable for batched kernel compilation. The default BinarySearch stops each search when its interval is found. DirectIndexing computes the bracket from the grid spacing with no search, for uniformly spaced grids (checked here), such as the Planck-source grid of the ecCKD reference tables. All use the same interpolation and endpoint behavior; pressure, H₂O, and matrix temperature grids retain their direct indexing.

abstract type AbstractLookupSearch

Search strategy for bracketing lookup-table queries. Pass a concrete strategy as lookup_search when constructing gas or cloud optics.

Binary search that exits when the interpolation interval is found. This is the default lookup_search for gas and cloud optics.

Binary search with a fixed iteration count determined by the table size. Completed intervals stay unchanged during the remaining iterations. Use lookup_search=FixedBinarySearch() for batched kernel compilation that cannot raise a data-dependent search loop. Interpolation and endpoint behavior match BinarySearch.

Direct indexing of a uniformly spaced table: the bracket is computed from the first node and the spacing, with no search and no loop. Requires uniformly spaced vector temperature and Planck-source grids (or effective-radius nodes, for cloud optics), which the constructors check. The ecCKD reference tables' Planck-source grid is uniform. Interpolation and endpoint behavior match BinarySearch, except that a NaN query brackets the first interval (its weight is NaN, as for the searches).

read_ecckd_definition(path)

Read an ecCKD CKD-definition file. The core package intentionally does not depend on NetCDF libraries; NetCDF-backed loading should be provided by a package extension. Until that extension is loaded, this method errors with a clear message.

read_ecckd_definition(data)

Build an EcCKDDefinition from schema metadata. This method is intended for tests and for reader extensions that have already extracted dimensions, variables, and attributes from a backing file.

read_ecckd_spectral_mapping(path)

Read the ecCKD resolved-spectral to g-point mapping from a CKD-definition NetCDF file. NetCDF-backed loading is provided by the NCDatasets extension.

read_ecckd_tabulated_gas_optics([FT = Float64,] longwave_path, shortwave_path;
                                names = (:H₂O, :CO₂),
                                water_vapor_mole_fraction = 0.005)

Read reference ecCKD CKD-definition files into a lightweight runtime EcCKDTabulatedGasOpticsModel with element type FT, passed as the first positional argument (default Float64). The core package does not depend on NetCDF libraries, so NetCDF-backed loading is provided by the NCDatasets extension.

This loader is a runtime-ingestion bridge, not a full ecRad-equivalent ingestion path: it materializes coefficient tables for the requested names only, together with each gas's reference mole fraction for the ecCKD relative-linear convention, the shortwave Rayleigh molar scattering table, and the longwave Planck source table. When :H₂O is requested, the reference H₂O mole-fraction table dimension is kept; at runtime optical_properties! computes the layer H₂O mole fraction from the H₂O and dry_air gas amounts and interpolates the table per layer. The water_vapor_mole_fraction keyword is not a gas input on that path — it is accepted for compatibility/fallback sampling of non-dynamic four-dimensional H₂O tables. Longwave spectral weights are uniform over g-points; shortwave weights are the file's per-g-point solar irradiance normalized to unit sum. Every table, grid and weight vector is converted to FT, so read_ecckd_tabulated_gas_optics(Float32, longwave_path, shortwave_path) yields a model whose optical properties are computed in single precision; the files store their coefficients in single precision, so that model carries them exactly.

Pass lookup_search=FixedBinarySearch() to use a fixed-count binary search for the temperature and Planck-source tables. The default is BinarySearch(); see EcCKDTabulatedGasOpticsModel.

read_reference_ecckd_gas_optics([FT = Float64,] model = :climate_64x32; require = true, kwargs...)

Load an reference ecCKD model pair into an EcCKDTabulatedGasOpticsModel with element type FT, passed as the first positional argument (default Float64), so read_reference_ecckd_gas_optics(Float32, "32x32") loads the tables in single precision. model accepts selectors such as :climate_32x32, :climate_64x32, or "32x96". Keyword arguments other than require are forwarded to read_ecckd_tabulated_gas_optics, for example names, water_vapor_mole_fraction, stefan_boltzmann, and lookup_search.

This method resolves the package's lazy ecRad artifact when needed. Load NCDatasets.jl before calling it so the NetCDF reader extension is active.

surface_longwave_emission(
    model::Union{EcCKDGasOpticsModel{FT}, EcCKDTabulatedGasOpticsModel{FT}},
    temperature;
    emissivity
) -> Vector

Per-g-point surface longwave emission of model at the surface temperature, scaled by emissivity, in the same per-unit-weight flux convention as the model's Planck source tables, as a host Vector for surface_longwave_up in LongwaveBoundaryConditions.

For multi-g spectral models a scalar $σT⁴$ boundary is a gray approximation: it does not reproduce the model's tabulated Planck spectrum across g points and may bias outgoing longwave fluxes.

summarize_ecckd_definition(definition)

Return schema-level ecCKD metadata used by examples, validation reports, and benchmark metadata.

validate_ecckd_definition(definition; throw_on_error=true)

Validate required ecCKD schema metadata. Returns true when valid. When throw_on_error=false, returns (valid, errors).

reference_ecckd_model_inventory()

Return the reference ecCKD CKD-definition filenames distributed with the pinned ecRad data artifact.

reference_ecckd_model_specs()

Return the named reference ecCKD model pairs supported by the high-level selection interface. Each value is an EcCKDModelSpec.

reference_ecckd_model_spec(name=:climate_64x32)

Return an EcCKDModelSpec for an reference ecCKD model pair. name may be a full selector such as :climate_32x32 or a compact string such as "32x32".

reference_ecckd_definition_path(name; require=true)

Return the path to an reference ecCKD CKD-definition file. name may be a full filename from reference_ecckd_model_inventory or one of :longwave_32, :shortwave_32, :longwave_64, :shortwave_64, or :shortwave_96.

reference_ecckd_definition_paths(; longwave=:longwave_64, shortwave=:shortwave_32)

Return (longwave=..., shortwave=...) paths for the default reference ecCKD runtime pair used by validation and examples.

reference_ecckd_definition_paths(model; require=true)

Return (longwave=..., shortwave=...) paths for an reference ecCKD model pair. model accepts the same selectors as reference_ecckd_model_spec. With require=false, this function returns nothing paths instead of downloading lazy artifacts or throwing when the data are not already installed.

ecrad_data_path(; require=false)

Return the root directory containing ecRad data files. Resolution order is: RH_ECRAD_DATA_PATH, the lazy ecrad_data artifact in Artifacts.toml, then the local validation checkout at validation/external/ecrad. GitHub archive artifacts may contain the data under one top-level child directory; individual file resolution handles both <root>/data and <root>/<archive>/data.

ecrad_test_file(
    relative_path::AbstractString;
    require
) -> Union{Nothing, String}

Path of a file under the test/ directory of the ecRad checkout that the ecrad_data artifact carries, resolved as <root>/test/<relative_path> with the same root as ecrad_data_path (RH_ECRAD_DATA_PATH, the lazy artifact, or the local validation/external/ecrad checkout; an archive whose files live under one top-level child directory is handled too). This is where the CKDMIP "Evaluation-1" profiles and their line-by-line fluxes live, for example ecrad_test_file("ckdmip/ckdmip_evaluation1_lw_fluxes_present_reduced.nc").

With require = true (the default) a missing root or file throws an ArgumentError, and the lazy artifact is downloaded if needed; with require = false the function returns nothing instead and never downloads.

ecckd_source_path(; require=false)

Return the root directory containing the reference ecCKD source tree. Resolution order is RH_ECCKD_SOURCE_PATH, the lazy ecckd_source artifact in Artifacts.toml, then the local validation checkout at validation/external/ecckd.

ClearSkyEcCKDRadiation{FT} <: AbstractRadiationScheme

Clear-sky ecCKD radiation as one configured column scheme: tabulated correlated-k gas_optics (EcCKDTabulatedGasOpticsModel) for both streams, the prescribed mole_fractions of the gases the host does not carry, and the longwave surface_emissivity. Longwave and shortwave are solved clear-sky (CloudlessLongwave, CloudlessShortwave) from one evaluation of the gas optics.

Gas composition: dry_air (dry air) and H₂O always come from the host's state. Every other gas of the ecCKD model needs an entry in mole_fractions, a number (mole fraction) or a function of pressure [Pa]; O₃ defaults to default_ozone_profile and CO₂ to 280 ppm, and a host that carries CO₂ (SpeedyWeather's greenhouse gases) overrides CO₂. Gases the ecCKD model knows but that were not requested when loading it stay at their reference concentration.

using NumericalRadiation, NCDatasets
scheme = ClearSkyEcCKDRadiation(Float32, "32x32")                                  # reference tables
scheme = ClearSkyEcCKDRadiation(Float32, "64x96"; mole_fractions = (; CO₂ = 400e-6), surface_emissivity = 0.97)
gas_optics = read_reference_ecckd_gas_optics("32x32"; names = (:dry_air, :H₂O, :O₃, :CO₂, :CH₄))
scheme = ClearSkyEcCKDRadiation(gas_optics; mole_fractions = (; CH₄ = 1.8e-6))     # every extra gas must be prescribed

default_ozone_profile(p)

Ozone mole fraction as a function of pressure p [Pa]: a Chapman-layer shape peaking at 8 ppmv near 30 hPa and vanishing towards the surface. The default O₃ prescription of ClearSkyEcCKDRadiation for hosts without an ozone field; a crude stand-in for a climatology.