Acoustic substepping cleanup: typed AcousticDampingStrategy + new default + BW example

.gitignore

@@ -29,11 +29,15 @@ Manifest.toml
 Manifest-v*.toml
 
 # output files
+validation_output/
 *.jld2
 *.nc
+*.gif
+*.pdf
 *.png
 *.mp4
 *.svg
+*.zip
 
 # other files we don't want
 *.swp
@@ -43,6 +47,7 @@ Manifest-v*.toml
 # Claude Code — ignore user-specific settings, track shared rules/skills
 .claude/settings.local.json
 .claude/debug/
+.claude/*.lock
 
 # Paper references (kept locally only)
 examples/tropical_cyclone_world.md

Project.toml

@@ -20,8 +20,8 @@ Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
 
 [weakdeps]
 CloudMicrophysics = "6a9e3e04-43cd-43ba-94b9-e8782df3c71b"
-RRTMGP = "a01a1ee8-cea4-48fc-987c-fc7878d79da1"
 ClimaComms = "3a4d1b5c-c61d-41fd-a00a-5873ba7a1b0d"
+RRTMGP = "a01a1ee8-cea4-48fc-987c-fc7878d79da1"
 Reactant = "3c362404-f566-11ee-1572-e11a4b42c853"
 SpecialFunctions = "276daf66-3868-5448-9aa4-cd146d93841b"
 
@@ -43,7 +43,7 @@ KernelAbstractions = "0.9"
 Oceananigans = "0.107.4"
 Printf = "1"
 RRTMGP = "0.21"
-SpecialFunctions = "2"
 Reactant = "0.2.203"
+SpecialFunctions = "2"
 Statistics = "<0.0.1, 1"
 julia = "1.11.9"

docs/make.jl

@@ -48,6 +48,7 @@ examples = [
     Example("Cloud formation in prescribed updraft", "kinematic_driver"; build_always=true, gpu=false),
     Example("Schär mountain wave with terrain-following coordinates", "two_dimension_mountain_wave"; build_always=false, gpu=true),
     Example("Splitting supercell", "splitting_supercell"; build_always=false, gpu=true),
+    Example("Baroclinic wave on the sphere", "baroclinic_wave"; build_always=true, gpu=false),
     Example("Tropical cyclone world", "tropical_cyclone_world"; build_always=false, gpu=true),
     Example("Diurnal cycle of radiative convection", "radiative_convection"; build_always=false, gpu=true),
 ]

docs/src/appendix/notation.md

@@ -135,13 +135,17 @@ The following table also uses a few conventions that suffuse the source code and
 | ``N_A``                             | `ℕᴬ`   |                                     | Avogadro's number, molecules per mole                                          |
 | ``\mathcal{U}``                     | `𝒰`    |                                     | Thermodynamic state struct (e.g., `StaticEnergyState`)                         |
 | ``\mathcal{M}``                     | `ℳ`    |                                     | Microphysical state struct (e.g., `WarmPhaseOneMomentState`)                   |
-| ``\psi``                            | `ψ`    | `AcousticSubstepper.pressure_coefficient` | Pressure coefficient for acoustic substepping, ``ψ = Rᵐ T``             |
-| ``{\mathbb{C}^{ac}}^2``             | `ℂᵃᶜ²` |                                           | Acoustic sound speed squared, ``ℂᵃᶜ² = γᵐ ψ = γᵐ Rᵐ T``                 |
+| ``Π^L``                             | `Πᴸ`   | `AcousticSubstepper.linearization_exner` | Stage-entry Exner function, ``Π^L = (p^L / p^{st})^κ``                  |
+| ``θ^L``                             | `θᴸ`   | `AcousticSubstepper.linearization_potential_temperature` | Stage-entry potential temperature, ``θ^L = (ρθ)^L / ρ^L`` |
+| ``γ^m R^m\vert_L``                  | `γRᵐᴸ` | `AcousticSubstepper.linearization_gamma_R_mixture` | Stage-entry equation-of-state coefficient in ``p' = γ^m R^m\vert_L Π^L (ρθ)'`` |
+| ``C^L``                             | `Cᴸ`   |                                     | Linearized pressure coefficient, ``C^L = γ^m R^m\vert_L Π^L``                 |
 | ``G^n``                             | `Gⁿ`   |                                     | Tendency fields at time step ``n``                                             |
 | ``G^s``                             | `Gˢ`   |                                     | Slow tendencies (excludes fast pressure gradient and buoyancy)                 |
-| ``N_s``                             | `Ns`   | `AcousticSubstepper.Ns`             | Number of acoustic substeps per full time step                                 |
-| ``\Delta \tau``                     | `Δτ`   |                                     | Acoustic substep time step, ``Δτ = Δt / Ns``                                   |
-| ``\kappa^d``                        | `κᵈ`   | `AcousticSubstepper.κᵈ`             | Divergence damping coefficient for acoustic substepping                        |
-| ``\rho_r``                          | `ρᵣ`   | `AcousticSubstepper.ρᵣ`             | Reference density for divergence damping (start of acoustic loop)              |
-| ``w^{avg}``                         | `averaging_weight` |                              | Time-averaging weight for velocity fields in acoustic substepping              |
-| ``\bar{u}, \bar{v}, \bar{w}``       | `ū, v̄, w̄` |                                 | Time-averaged velocities for scalar advection                                  |
+| ``N``                               | `N`    | `AcousticSubstepper.substeps`       | Acoustic substeps per outer time step, or adaptive substep count before stage partitioning |
+| ``N_τ``                             | `Nτ`   |                                     | Acoustic substeps in one Runge-Kutta stage                                     |
+| ``\Delta \tau``                     | `Δτ`   |                                     | Acoustic substep size, ``Δτ = Δt / N`` for proportional substep distribution   |
+| ``ρ'``                              | `ρ′`   | `AcousticSubstepper.density_perturbation` | Density perturbation about the stage-entry state                       |
+| ``(ρθ)'``                           | `ρθ′`  | `AcousticSubstepper.density_potential_temperature_perturbation` | Thermodynamic-density perturbation about the stage-entry state |
+| ``(ρu)', (ρv)', (ρw)'``             | `ρu′, ρv′, ρw′` | `AcousticSubstepper.momentum_perturbation` | Momentum perturbations about the stage-entry state              |
+| ``D_τ``                             | `Dτ`   |                                     | Klemp-Skamarock-Ha divergence-damping proxy, ``D_τ = ((ρθ)'_τ - (ρθ)'_{τ-\Delta τ}) / θ^L`` |
+| ``\bar{u}, \bar{v}, \bar{w}``       | `ū, v̄, w̄` | `AcousticSubstepper.time_averaged_velocities` | Time-averaged velocities for non-acoustic scalar advection |

docs/src/breeze.bib

@@ -1,3 +1,47 @@
+@article{JablonowskiWilliamson2006,
+  author = {Jablonowski, Christiane and Williamson, David L.},
+  title = {A baroclinic instability test case for atmospheric model dynamical cores},
+  journal = {Quarterly Journal of the Royal Meteorological Society},
+  volume = {132},
+  number = {621C},
+  pages = {2943--2975},
+  year = {2006},
+  doi = {10.1256/qj.06.12}
+}
+
+@article{Baldauf2010,
+  author = {Baldauf, Michael},
+  title = {Linear stability analysis of {Runge}-{Kutta}-based partial time-splitting schemes for the {Euler} equations},
+  journal = {Monthly Weather Review},
+  volume = {138},
+  number = {12},
+  pages = {4475--4496},
+  year = {2010},
+  doi = {10.1175/2010MWR3355.1}
+}
+
+@article{KlempSkamarockHa2018,
+  author = {Klemp, Joseph B. and Skamarock, William C. and Ha, So-Young},
+  title = {Damping acoustic modes in compressible horizontally explicit vertically implicit ({HEVI}) and split-explicit time integration schemes},
+  journal = {Monthly Weather Review},
+  volume = {146},
+  number = {6},
+  pages = {1911--1923},
+  year = {2018},
+  doi = {10.1175/MWR-D-17-0384.1}
+}
+
+@article{KnothWensch2014,
+  author = {Knoth, Oswald and Wensch, J{\"o}rg},
+  title = {Generalized split-explicit {Runge}-{Kutta} methods for the compressible {Euler} equations},
+  journal = {Monthly Weather Review},
+  volume = {142},
+  number = {5},
+  pages = {2067--2081},
+  year = {2014},
+  doi = {10.1175/MWR-D-13-00068.1}
+}
+
 @article{SkamarockEtAl2012,
   author = {Skamarock, William C. and Klemp, Joseph B. and Duda, Michael G. and Fowler, Laura D. and Park, Sang-Hun and Ringler, Todd D.},
   title = {A Multiscale Nonhydrostatic Atmospheric Model Using Centroidal {Voronoi} Tesselations and {C}-Grid Staggering},