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} <: 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).

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 = (:h2o, :co2),
                                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 :h2o 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 h2o and composite 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.

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 and stefan_boltzmann.

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.