Releases · CliMA/RRTMGP.jl

Release list

v0.22.2 Latest

Latest

github-actions released this 15 Jul 04:51

v0.22.2

9b842af

RRTMGP v0.22.2

Diff since v0.22.1

Merged pull requests:

Ts/vendor dev guides (#614) (@tapios)
add set_volume_mixing_ratio for well-mixed gases (#615) (@szy21)
set z and metric_scaling for the isothermal boundary layer (#616) (@szy21)

Contributors

szy21 and tapios

Assets 2

v0.22.1

github-actions released this 14 Jul 17:10

v0.22.1

a625448

RRTMGP v0.22.1

Diff since v0.22.0

Merged pull requests:

Release v0.22.0 (#612) (@tapios)
Allocation-free copy (#613) (@tapios)

Contributors

tapios

Assets 2

v0.22.0

tapios released this 14 Jul 16:48

v0.22.0

452b4da

Internal compute buffers now use device-dependent physical layouts behind a
uniform column-first (ncol, nlay/nlev) indexing convention: optical
properties (OneScalar, TwoStream), source functions (SourceLWNoScat,
SourceLW2Str, SourceSW2Str), and the broadband flux buffers (FluxLW,
FluxSW). On the GPU the storage is column-first, giving coalesced access
(on an A100 at DYAMOND scale this cuts longwave kernel times by 25-36% and
shortwave all-sky by 14-20%); on the CPU the storage stays vertical-first
under a lazy PermutedDimsArray wrapper, preserving the stride-1 vertical
sweeps (and CPU performance) while running the same kernel code.
The Layer-2 flux getters (lw_flux_up, net_flux, ...) still present
plain (nlev, ncol) views: they read Fluxes.FluxPresentation arrays that
update_fluxes! fills from the compute buffers with one fused transposing
copy per call (so getters remain Array-materializable, broadcastable, and
reducible on the GPU). The opt-in per-band buffers (FluxBand) keep the
host-facing (nlev, ncol, n_bnd) layout. Breaking for Layer-1
(functional-core) users: code reading the workspace fields directly
(slv.flux.flux_up, op.τ, ...) must swap index order to [gcol, ilev]
or wrap the buffer in Fluxes.lazy_transpose. State inputs
(AtmosphericState arrays) and all boundary-condition arrays are
unchanged.
New TransposedStateCache: column-first copies of the hot
AtmosphericState arrays (layer pressure/temperature/dry-air column
amount/relative humidity, level temperatures), refreshed by one
permutedims! per spectral solve, so the gas-optics g-point loop reads
coalesced memory on GPUs. On by default on the GPU (the RTE workspace
constructors build one; the RRTMGPSolver shares a single cache between
the longwave and shortwave workspaces) and off (nothing) on the CPU,
where the state's vertical-first layout is already cache-friendly; pass
state_cache = nothing to opt out, or pass the same cache to several
workspaces to share the storage.
Documentation reorganized along tutorial / how-to / explanation / reference
lines: two new executable (Literate.jl) tutorials — "A first radiation
calculation" and "Radiative-convective equilibrium", which reproduces
Manabe's classic fixed-relative-humidity climate-sensitivity experiment with
RRTMGP's clear-sky optics — plus four how-to guides (driving RRTMGP from a
host model, running on GPUs, caching the lookup tables, per-band fluxes).
The README now gives a Thermodynamics.jl-style overview with quick starts.
Struct docstrings migrated off DocStringExtensions.FIELDS to explicit
# Fields sections (per the CliMA documentation policy), so field
descriptions and units render on the API pages without inline field
docstrings.
New unit tests for previously indirect paths: every interpolation /
bottom-extrapolation scheme against closed forms (including a dry-adiabat
round-trip through interpolate_levels!), solver-constructor and getter
guard errors, validate_inputs field-by-field, the incident-longwave-flux
boundary condition, pointwise deep-atmosphere flux scaling, heating-rate =
net-flux divergence, gray clip!, aerosol-only LookupBundle round-trips,
cloud-radiative-effect sign checks in the all-sky tests, and the McICA
reproducibility tests now also run in Float32.
New advisory GPU benchmark ratchet (perf/benchmark_ratchet.jl + a
soft-fail Buildkite step): the DYAMOND-scale solve_lw!/solve_sw! medians
are compared against per-GPU baselines committed under
perf/benchmark_baselines/, flagging wall-time regressions beyond 20%
without blocking merges. The three DYAMOND benchmark scripts are now
includable (their sweeps run only when executed as scripts).
New docs page "Fortran and paper concordance": tables mapping RRTMGP.jl
names (containers, RTE/gas-optics/cloud/aerosol kernels) to the Fortran
rte-rrtmgp mo_*/ty_* names and to the papers whose equations they
implement, so Fortran-literate readers can navigate instantly.
The standalone (Layer-3) path is complete: standard_atmosphere(FT; kind)
builds an idealized clear-sky AtmosphereProfile (:tropical,
:midlatitude_summer, :subarctic_winter — analytic two-segment
temperature, exact hydrostatic pressure, idealized water vapor/ozone,
present-day well-mixed gases), and solve(profile; method) solves it in one
call — ClearSkyRadiation (default) or GrayRadiation. Both solve and
solve_gray now return a documented RadiationOutput struct with stable
field names (lw_up … sw_direct_dn, net, heating_rate, solver);
solve_gray previously returned a NamedTuple with the same names, so
field access is unchanged.
New prepare_atmosphere!(solver): runs the atmospheric-state preparation
cascade (level interpolation, isothermal boundary layer, clipping, dry-air
column amounts) without solving, so hosts can inspect the prepared state —
the prepare/solve split. update_fluxes! is now literally
prepare_atmosphere! followed by the three solve/combine steps.
Breaking: lookup_tables now returns a typed [LookupBundle] instead of
a nested (; lookups, lu_kwargs) NamedTuple: stable fields
(lookup_lw, lookup_sw, cloud/aerosol tables, the name→index maps, and the
band/gas counts), nothing where a table is absent. Code that indexed the
NamedTuple (e.g. bundle.lookups.lookup_lw, bundle.lu_kwargs.nbnd_lw) drops
one level (bundle.lookup_lw, bundle.nbnd_lw).
New save_lookup_tables(path, bundle) / load_lookup_tables(path, grid_params)
cache the lookup tables on disk (Julia Serialization; a same-version cache,
not an interchange format), so the spectral methods can run without NCDatasets
once a cache has been generated — e.g. for standalone/classroom use.
The CPU and CUDA solver drivers now share device-agnostic per-(g-point,
column) bodies (*_gpt_col! in src/rte/), removing the duplicated
orchestration where backend asymmetries repeatedly crept in. As part of the
unification, the broadband shortwave direct beam sw_direct_flux_dn is now
accumulated at every level: it was previously meaningful only at the
surface row (a documented limitation inherited from PR #550), with the rows
above holding the first g-point's profile on CPU and uninitialized memory on
GPU.
Breaking (with aliases): renamed two modules for clarity — Vmrs →
VolumeMixingRatios and GrayUtils → GrayAtmosphere. The old names remain
as const aliases for one release and will be removed in 0.24.
Breaking: renamed aerosol_idx() → aerosol_index_map(), resolving the
one-character collision with aerosol_index(name) (which returns a single
index rather than the whole map).
Float32 accuracy overhaul of the RTE kernels: series-switch threshold for the
longwave no-scattering source at eps^(1/4) (was 100·eps), exact γ1 − γ2
identities in the two-stream k, expm1-based thin-layer factors, a consistent
off-resonance evaluation of the shortwave direct reflectance/transmittance,
exact non-cancelling delta-scaling forms, an addition-built direct-beam
profile, a continuous gas-optics η interpolation at η = 1, and a restructured
longwave two-stream source (exact 1 ∓ Rdif − Tdif factorizations, so no term
divides by τ and thin layers keep their real O(τ) emission instead of being
zeroed below a threshold). Measured Float32↔Float64 broadband agreement
improves 25–90×: every longwave path now sits at its ~2–5e-4 W/m²
interpolation-noise floor (from 1.1e-2–3.4e-2). A new ratcheting f32↔f64
consistency test (test/float32_consistency.jl) locks the gains, and the
Float32 longwave no-scattering reference tolerances tighten from 0.05 to
5e-3 W/m².
New RRTMGP.Numerics module: every numerical guard constant (k_min,
τ_thresh, resonance_window, μ₀_min) in one place with its derivation.
New opt-in input validation: set RRTMGP.check_values[] = true to have
update_fluxes! validate solver inputs (pressures/temperatures positive and
finite, cos_zenith ∈ [-1, 1], emissivity/albedos ∈ [0, 1], VMRs ≥ 0) via
validate_inputs; off by default and allocation-free when off.
Lookup loaders now assert the canonical gas slots the kernels hard-code
(h2o → 1, o3 → 3) and that temperature_Planck is in Kelvin (the g128 file
variants store an integer index, which would silently corrupt the Planck
interpolation).
Breaking: the public API is now centered on RRTMGPSolver plus a complete set of named
getters (layer_temperature, level_pressure, net_flux, ...), built on the functional
solve_lw!/solve_sw! core. Hosts exchange every input and output through the getters — a
documented, ClimaCore-free data-exchange contract — and drive the solve with a single
allocation-free, type-stable update_fluxes! that returns nothing (results are read back
through the getters).
Breaking: removed the deprecated positional-argument constructors that warned to use
RRTMGPGridParams: the old signatures of OneScalar, TwoStream, FluxLW, FluxSW,
SourceLWNoScat, SourceLW2Str, SourceSW2Str, NoScatLWRTE, TwoStreamLWRTE,
NoScatSWRTE, TwoStreamSWRTE, and VmrGM, plus source_func_longwave,
source_func_shortwave, and init_vmr. Construct these with RRTMGPGridParams (and
VolumeMixingRatioGlobalMean for VmrGM).
Breaking: RRTMGPGridParams now takes domain_nlay (the physical layer count) instead
of nlay, and adds the isothermal boundary layer internally; the stored nlay field is the
total. Callers no longer compute domain_nlay + 1 themselves.
Breaking: removed the internal RRTMGPData{Order} data-layout types and helpers
(NVCData/VCData/NCData/NData, set_cols!/set_domain!/domain_view, and the
index-order tags); the gette...