Picket-fence radiation: multi-planet correlated-k scheme, CO2-adjustable Earth LW, numba acceleration, and the Experiments write-up

[JoyMonteiro]

Overview

This PR lands the full picket-fence radiation body of work and everything built around it since #207 merged. It is large (130 commits) because it spans a new radiation scheme, multi-planet support, a correlated-k table toolchain, performance work, a general condensibles framework for Emanuel convection, and a Quarto "Experiments" write-up with a reproducible notebook.

The bulk of the line count is shipped data and tooling output, not source: binary correlated-k .nc tables, the pre-executed companion notebook, and the graphify-out/ knowledge-graph artifacts.

Warning

Breaking change — radiation diagnostic names. GrayLongwaveRadiation and PicketFenceShortwave now emit sympl's canonical air_temperature_tendency_from_longwave / air_temperature_tendency_from_shortwave (and ..._per_band) instead of the old longwave_heating_rate / shortwave_heating_rate. The PicketFenceShortwave cloud input alias tau_cloud was likewise renamed to tau_cloud_sw. Any downstream code reading the old names must be updated. In-repo tests and experiment scripts are already migrated.

Note

Also breaking (API surface): EmanuelConvectionPythonV3 is removed. The V3 implementation is now exported simply as EmanuelConvectionPython; the original pure-Python component was retired.

What's in here

New: picket-fence radiation scheme

• PicketFenceLongwave and PicketFenceShortwave tendency components, each with two modes:
  • Parmentier mode — analytic Parmentier/Freedman-2014 Rosseland-mean gas optics with coefficient lookup.
  • Correlated-k mode — band/g-point gas optics loaded from shipped .nc k-tables.
• Two-stream SW solver, ESFT band overlap, direct-beam kernel, LW transport kernel, and a bit-exact grey-limit check against GrayLongwaveRadiation.
• SW cloud optical-property inputs (tau_cloud_sw, ssa_cloud, g_cloud) and a per-band optical-depth / transmittance / heating-rate diagnostics tier (diagnostics_level).

Multi-planet support

• TOML-driven atmospheric profiles and a multi-planet atmospheric_properties API, with profiles for Titan, TRAPPIST-1e (Hab1/Hab2), Mars, and Venus.
• Shipped LW+SW correlated-k tables per planet (Titan N2+CH4+CIA via HITRAN, TRAPPIST-1e CO2/H2O, etc.).
• TRAPPIST-1 blackbody stellar spectrum; stellar-spectrum loading wired through the SW component.

Correlated-k table toolchain (scripts/generate_picket_fence_tables.py + helpers)

• Chaverot→climt k-table converter (CC-BY), k-distribution builder with Gauss-Legendre quadrature, plus a new --quadrature two-stretch / --g-split option that densely samples the strong-line tail (g→1).
• Line-by-line kappa sampler over (T, p[, X_H2O]) grids, HITRAN CIA loader, SW solar source + Rayleigh utilities, and a netCDF writer.

CO2-adjustable Earth LW table

• New default earth_low_res_lw is a 14-band table with a runtime CO2 axis: CO2 VMR is read from state and threaded through correlated-k optical-depth assembly via quadrilinear (geometric log-k) interpolation. Ships earth_hifi_lw as the high-fidelity RRTMG-matched variant.

Performance (numba)

• njit(parallel) kernels for the 7D CO2 optical-depth assembly, Planck-source assembly, and a consolidated LW transport kernel — roughly 540× speedups, benchmarked faster than RRTMG-LW for many columns. A no-numba njit stub keeps the package importable without numba.

General condensibles (Emanuel convection)

• CondensibleParams / get_condensible_params / get_active_condensible API, condensible species tracking, parallelised saturation-specific-humidity (compute_qs), and kernel helpers wired through the vectorized Emanuel path. Enables non-H2O condensibles (e.g. Titan CH4).

Docs / experiments

• A Quarto "Experiments" discovery post (the picket-fence story) with a pre-executed companion notebook that reproduces every figure, a hash-gated artifact regenerator, and a single figure-generation pipeline.
• Design specs and implementation plans for the sub-projects.

CI / deps

• Declares numba, netcdf4, and importlib_resources; flake8 cleanups; excludes slow RCE / line-by-line builder tests from routine CI while shipping the earth_hifi_lw integration table.

Validation

• Bit-exact grey-limit agreement with GrayLongwaveRadiation.
• RRTMG broadband LW/SW agreement within tolerance; moist/dry RCE validation (dry +0.8 K, moist +1.9–2.1 K vs a +11.9 K baseline error).
• Per-band and leave-one-out CO2-interpolation accuracy probes against line-by-line references.

Reviewer notes

• The two most recent commits (bd1a95a, 04b2cc3) are the breaking renames called out above and are the smallest, most reviewable units.
• graphify-out/ (≈450 files) is a committed knowledge-graph artifact, shipped on purpose: it lets an LLM build climt models from a plain-text description by querying the graph for components, signatures, and relationships (see CLAUDE.md for the workflow). It inflates the file count but is intentional, not stray tooling output.