Tests and docs

.buildkite/pipeline.yml

@@ -126,3 +126,16 @@ steps:
         agents:
           slurm_ntasks: 1
           slurm_gpus: 1
+
+      # Advisory wall-time ratchet against committed per-GPU baselines
+      # (perf/benchmark_baselines/). Soft-fail: flags regressions without
+      # blocking merges; see the header of perf/benchmark_ratchet.jl.
+      - label: "GPU DYAMOND benchmark ratchet"
+        command: "julia --color=yes --project=test perf/benchmark_ratchet.jl"
+        soft_fail: true
+        artifact_paths: "perf/benchmark_baselines/*"
+        env:
+          CLIMACOMMS_DEVICE: "CUDA"
+        agents:
+          slurm_ntasks: 1
+          slurm_gpus: 1

.github/workflows/docs.yml

@@ -15,7 +15,7 @@ concurrency:
 jobs:
   docbuild:
     runs-on: ubuntu-latest
-    timeout-minutes: 30
+    timeout-minutes: 60
     steps:
       - uses: actions/checkout@v4
       - uses: julia-actions/setup-julia@v2

.gitignore

@@ -35,3 +35,8 @@ docs/site/
 Manifest.toml
 test/Manifest.toml
 
+# Literate.jl-generated tutorial pages
+docs/src/tutorials/
+
+# Temporary benchmark measurements
+perf/benchmark_baselines/measured_*.txt

NEWS.md

@@ -3,6 +3,31 @@ RRTMGP.jl Release Notes
 
 main
 ------
+- 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

Project.toml

@@ -7,7 +7,6 @@ version = "0.21.9"
 Adapt = "79e6a3ab-5dfb-504d-930d-738a2a938a0e"
 Artifacts = "56f22d72-fd6d-98f1-02f0-08ddc0907c33"
 ClimaComms = "3a4d1b5c-c61d-41fd-a00a-5873ba7a1b0d"
-DocStringExtensions = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 Serialization = "9e88b42a-f829-5b0c-bbe9-9e923198166b"
 
@@ -27,7 +26,6 @@ Artifacts = "1"
 CUDA = "5.9, 6"
 ClimaComms = "0.5.4, 0.6"
 ClimaParams = "1"
-DocStringExtensions = "0.8, 0.9"
 NCDatasets = "0.14.2"
 Random = "1"
 Serialization = "1"

README.md

@@ -1,45 +1,156 @@
+<div align="center">
+  <img src="docs/src/assets/logo.svg" alt="RRTMGP.jl Logo" width="128" height="128">
+</div>
+
 # RRTMGP.jl
 
-Julia implementation of Radiative Transfer for Energetics and the RRTMGP optics.
+The `RRTMGP.jl` package is a Julia implementation of the radiative transfer
+solver RTE (Radiative Transfer for Energetics) and the RRTMGP (RRTM for General
+circulation model applications—Parallel) correlated-*k* gas optics
+([Pincus et al., 2019](https://doi.org/10.1029/2019MS001621)), based on the
+reference Fortran implementation
+[rte-rrtmgp](https://github.com/earth-system-radiation/rte-rrtmgp). It computes
+longwave and shortwave radiative fluxes and heating rates for clear, cloudy,
+and aerosol-laden atmospheres, and is the radiation scheme of the
+[CliMA Earth System Model](https://clima.caltech.edu).
 
 |||
-|---------------------:|:----------------------------------------------|
-| **Documentation**    | [![latest][docs-latest-img]][docs-latest-url] |
-| **Code Coverage**    | [![codecov][codecov-img]][codecov-url]        |
-| **BuildKite**        | [![buildkite][buildkite-img]][buildkite-url]  |
-| **Downloads**        | [![downloads][downloads-img]][downloads-url]  |
-
-
-[docs-latest-img]: https://img.shields.io/badge/docs-latest-blue.svg
-[docs-latest-url]: https://CliMA.github.io/RRTMGP.jl/latest/
+|-----------------:|:-------------------------------------------------------------|
+| **Documentation**| [![stable][docs-stable-img]][docs-stable-url] [![dev][docs-dev-img]][docs-dev-url] |
+| **Version**      | [![version][version-img]][version-url]                       |
+| **License**      | [![license][license-img]][license-url]                       |
+| **Tests**        | [![gha ci][gha-ci-img]][gha-ci-url] [![buildkite][bk-ci-img]][bk-ci-url] |
+| **Code Coverage**| [![codecov][codecov-img]][codecov-url]                      |
+| **Downloads**    | [![Downloads][dlt-img]][dlt-url]                             |
 
+[docs-stable-img]: https://img.shields.io/badge/docs-stable-blue.svg
+[docs-stable-url]: https://CliMA.github.io/RRTMGP.jl/stable/
+[docs-dev-img]: https://img.shields.io/badge/docs-dev-blue.svg
+[docs-dev-url]: https://CliMA.github.io/RRTMGP.jl/dev/
+[version-img]: https://juliahub.com/docs/General/RRTMGP/stable/version.svg
+[version-url]: https://juliahub.com/ui/Packages/General/RRTMGP
+[license-img]: https://img.shields.io/badge/license-Apache%202.0-blue.svg
+[license-url]: https://github.com/CliMA/RRTMGP.jl/blob/main/LICENSE
+[gha-ci-img]: https://github.com/CliMA/RRTMGP.jl/actions/workflows/OS-UnitTests.yml/badge.svg
+[gha-ci-url]: https://github.com/CliMA/RRTMGP.jl/actions/workflows/OS-UnitTests.yml
+[bk-ci-img]: https://badge.buildkite.com/ee3a0c43cf4925ee14a966f794ac85d0b9439244d23e43b308.svg?branch=main
+[bk-ci-url]: https://buildkite.com/clima/rrtmgp-ci/builds?branch=main
 [codecov-img]: https://codecov.io/gh/CliMA/RRTMGP.jl/branch/main/graph/badge.svg
 [codecov-url]: https://codecov.io/gh/CliMA/RRTMGP.jl
+[dlt-img]: https://img.shields.io/badge/dynamic/json?url=http%3A%2F%2Fjuliapkgstats.com%2Fapi%2Fv1%2Ftotal_downloads%2FRRTMGP&query=total_requests&label=Downloads
+[dlt-url]: https://juliapkgstats.com/pkg/RRTMGP
 
-[buildkite-img]: https://badge.buildkite.com/ee3a0c43cf4925ee14a966f794ac85d0b9439244d23e43b308.svg
-[buildkite-url]: https://buildkite.com/clima/rrtmgp-ci
+## Quick Start
 
-[downloads-img]: https://img.shields.io/badge/dynamic/json?url=http%3A%2F%2Fjuliapkgstats.com%2Fapi%2Fv1%2Ftotal_downloads%2FRRTMGP&query=total_requests&suffix=%2Ftotal&label=Downloads
-[downloads-url]: http://juliapkgstats.com/pkg/RRTMGP
+### Installation
 
-This is based off of the [rte-rrtmgp](https://github.com/RobertPincus/rte-rrtmgp) repository.
+```julia
+using Pkg
+Pkg.add("RRTMGP")
+```
 
-# Install
+### Basic Usage
 
-RRTMGP.jl is registered in the general Julia registry. To install, enter the package manager by typing `]` in the Julia REPL, and then type:
+The standalone front door provides a quick start. A gray (single-band)
+atmosphere uses analytic formulas:
 
 ```julia
-pkg> add RRTMGP
+using RRTMGP
+
+out = RRTMGP.solve_gray(Float64; nlay = 60, ncol = 1)
+out.net          # net flux at each level [W/m²]
+out.heating_rate # radiative heating rate at each layer [K/s]
 ```
 
-Then, to use
+For the full correlated-*k* gas optics, build an idealized clear-sky profile
+and solve it (the lookup tables are downloaded automatically; loading
+`NCDatasets` activates them):
 
 ```julia
-julia> using RRTMGP
+using RRTMGP, NCDatasets
+
+profile = RRTMGP.standard_atmosphere(Float64; kind = :tropical)
+out = RRTMGP.solve(profile)
+out.lw_up[end, 1]   # outgoing longwave radiation at the top of the atmosphere [W/m²]
+out.heating_rate    # radiative heating rate at each layer [K/s]
 ```
 
-# Acknowledgments
+### Host-Model Usage
+
+Climate models construct an `RRTMGPSolver` once, write their state through the
+[getter contract](https://clima.github.io/RRTMGP.jl/latest/getters/), and call
+`update_fluxes!(solver)` every radiation step:
+
+```julia
+solver = RRTMGP.RRTMGPSolver(grid_params, method, params, bcs_lw, bcs_sw, as)
+RRTMGP.update_fluxes!(solver)          # allocation-free, in place
+F = RRTMGP.net_flux(solver)            # (nlev, ncol) view into solver memory
+```
+
+## Key Features
+
+- **Full RRTMGP gas optics**: longwave and shortwave correlated-*k* lookup
+  tables, clouds (with McICA sampling of partial cloudiness), and MERRA
+  aerosols, validated against the Fortran rte-rrtmgp reference fluxes.
+- **Gray radiation**: analytic single-band optics for idealized-climate and
+  teaching use.
+- **Two-stream and no-scattering solvers** for both bands, with optional
+  per-band (spectrally resolved) flux output.
+- **CPU and GPU**: the same code runs single-threaded, multi-threaded, and on
+  CUDA GPUs via [ClimaComms](https://github.com/CliMA/ClimaComms.jl).
+- **Zero-allocation driver**: `update_fluxes!` is allocation-free and
+  type-stable (asserted in CI with `@allocated` and JET), allowing it to run
+  fast within a climate simulation.
+- **Dual precision**: `Float32` and `Float64` throughout, with high accuracy
+  (~ 1e-3 W/m²) at `Float32` and an accuracy-ratchet test pinning the
+  `Float32`↔`Float64` flux differences.
+
+## Design
+
+RRTMGP.jl is organized in three layers:
+
+1. **Functional core**: `solve_lw!` / `solve_sw!` kernels acting on explicit
+   state (`AtmosphericState`, optics, sources, boundary conditions, flux
+   workspaces). See the [Functional core](https://clima.github.io/RRTMGP.jl/latest/functional_core/) page.
+2. **Solver aggregate**: `RRTMGPSolver` bundles the configuration, state, and
+   workspaces; hosts exchange data through documented
+   [getters](https://clima.github.io/RRTMGP.jl/latest/getters/) and drive it
+   with `update_fluxes!`.
+3. **Standalone front door**: `solve_gray(FT)`, `standard_atmosphere(FT)`, and
+   `solve(profile)` for classroom use, single-column experiments, and quick
+   starts.
+
+Readers coming from the Fortran implementation can use the
+[Fortran and paper concordance](https://clima.github.io/RRTMGP.jl/latest/concordance/)
+to map names between the two code bases and the underlying papers.
+
+## Documentation
+
+- **[Documentation home](https://clima.github.io/RRTMGP.jl/latest/)**: overview
+  and page index.
+- **[Functional core](https://clima.github.io/RRTMGP.jl/latest/functional_core/)**:
+  the solver kernels, with runnable gray and clear-sky examples.
+- **[Getter contract](https://clima.github.io/RRTMGP.jl/latest/getters/)**: the
+  host data-exchange interface.
+- **[API reference](https://clima.github.io/RRTMGP.jl/latest/api/)**: types and
+  functions.
+
+## Integration with Climate Models
+
+RRTMGP.jl provides radiative fluxes and heating rates for the
+[CliMA](https://github.com/CliMA) ecosystem, including:
+
+- [ClimaAtmos](https://github.com/CliMA/ClimaAtmos.jl)
+- [ClimaCoupler](https://github.com/CliMA/ClimaCoupler.jl)
+
+## Getting Help
+
+For questions, check the [documentation](https://clima.github.io/RRTMGP.jl/latest/)
+or open an issue on [GitHub](https://github.com/CliMA/RRTMGP.jl).
+
+## Acknowledgments
 
- - [Robert Pincus](https://github.com/RobertPincus) for his invaluable help
- - The authors of the [Fortran implementation](https://github.com/earth-system-radiation/rte-rrtmgp) of RTE-RRTMGP on which this code is based
- - NASA for images of the sun (for our [logo](https://clima.github.io/RRTMGP.jl/latest/assets/logo.png))
+- [Robert Pincus](https://github.com/RobertPincus) for his invaluable help.
+- Robert Pincus, Eli Mlawer, and Jennifer Delamere, the developers of RTE+RRTMGP
+  and its reference [Fortran implementation](https://github.com/earth-system-radiation/rte-rrtmgp),
+  on which this code is based.