[Example] Tropical cyclone with stationary stratiform rainband (YD19)

[bischtob]

Summary

Self-contained literate example that reproduces the idealized tropical-cyclone rainband experiment of Yu & Didlake (2019, J. Atmos. Sci. 76, 3169–3189) — modeled on the form of our mature examples (bomex.jl, splitting_supercell.jl, dry_thermal_bubble.jl).

The simulation asks YD19's question: given a mature hurricane, what happens when you paint a steady stationary heating pattern in one of its stratiform rainbands? The answer — both in YD19's full-physics WRF run and in the Breeze anelastic reproduction here — is a quadrupole of secondary-circulation anomalies and a few-m/s dipole in the tangential wind.

Buidls on earlier WIP #440 by @nrb171. Closes #439.

@nrb171 feel free to do whatever you want with this.

What's in the PR (4 files, +1465 / −0)

File	Change
examples/tropical_cyclone_with_rainband.jl	+1384 — the literate example
docs/src/breeze.bib	+66 — 6 new bib entries (YuDidlake2019, MoonNolan2010, SternNolan2009, Nolan2001, Jordan1958, Emanuel1986)
examples/.gitignore	+14 — keeps output_tc_*/, *.jld2, *.mp4, *.png out of git (the example writes ~5 GB of output)
docs/make.jl	+1 — registers the example (build_always=false, gpu=true, consistent with the other heavy GPU examples)

Simulation

Single hardwired configuration, 214² × 75 cells on a 642 km × 642 km × 25 km periodic-in-x-y box at 3 km horizontal resolution (Δz ≈ 333 m). Three back-to-back 24 h stages run end-to-end in one script:

1. Spinup — balanced vortex IC relaxes under the upper-level sponge only.
2. Control — 24 h continuation from the post-spinup state, no heating.
3. Heated — 24 h continuation from the same post-spinup state with the MN10 stratiform heating switched on.

The response is (heated − control) in the hour 5–7 analysis window. An F06 diagnostic tracks the response amplitude vs time; saturation past ~7 h reflects the absence of explicit horizontal diffusivity (documented known limitation).

Physics

• Environment: Jordan (1958) West Indies mean hurricane-season sounding, tabulated inline and interpolated onto z_centers.
• Vortex: modified-Rankine profile (YD19 Eq. 2) with Stern & Nolan (2009) Eq. 4.4 RMW(z) slope, cos² taper outside 250 km for periodic-box compatibility.
• Initial condition: Picard iteration of the gradient-wind + hydrostatic + ideal-gas fixed point (Nolan 2001 / WRF em_tropical_cyclone initializer — the procedure YD19 §3a2 prescribe). Converges in ~15 iterations to gradient-wind residual ~10⁻³ Pa/m and hydrostatic residual ~10⁻⁵ Pa/m — a 10⁴× collapse over a one-shot linearized baseline.
• Rainband heating: YD19 Eq. 3 — spiral radial centerline r_bs(λ,z) = [60 − 10(λ/(π/4))] km + z, Gaussian radial shape with σ_r = 6 km, sinusoidal vertical shape with σ_zs = 2 km centered at z_bs = 4 km, super-Gaussian azimuthal window at λ = −π/4, 1-h linear ramp from zero to full strength.
• Upper-level sponge: WRF damp_opt=2 analog. Rayleigh damping of ρu/ρv/ρw toward zero and ρe toward the reference dry-static-energy-density profile ρᵣ(z)[cᵖᵈ Tᵣ(z) + gz], sin² ramp from z = 20 km to max at z = 25 km.

Scientific outcome

Reproduced on NVIDIA H200 (GPU), 214² × 75, Float64:

Metric	YD19 target	This reproduction
F02a surface v̄ peak	≈ 40 m/s	37.94 m/s at r = 31.5 km
F02b θ′ peak	≈ 10–12 K at 10–12 km	7.63 K at (r, z) = (1.5, 9.8) km
F03a response range (hour 5–7)	≈ ±1.5 m/s	[−1.00, +1.61] m/s
F04 per-panel |w′|	< 1 m/s	[0.213, 0.183, 0.217] m/s at z = 6 / 3.6 / 2 km

The quadrupole pattern and dipole in v̄′ are reproduced. The θ′ magnitude shortfall is a known formulation caveat (mass-coord vs z-coord Picard closure) that survives the 24 h spinup roughly unchanged.

What the example teaches

• Building a balanced-vortex initial condition via Picard iteration (Nolan 2001 / WRF em_tropical_cyclone).
• Wiring a spatially structured, time-varying heat source into the energy equation with Forcing.
• Running three related stages in one script with in-memory state handoff between them.
• Isolating a forced response via a control experiment.

Figures produced

• F01_preflight.png — vortex IC sanity check
• F02ab_vortex.png — basic-state vortex (YD19 Fig 2a,b)
• F02cd_heating.png — analytic heating (YD19 Fig 2c,d)
• F03a_axisym_response.png — axisymmetric response (YD19 Fig 3a)
• F04_plan_response.png — plan-view response (YD19 Fig 4a-c)
• F05_cross_sections.png — cross sections (YD19 Fig 5)
• F06_response_timeseries.png — response amplitude vs time (diagnostic)
• response_w_z3km.mp4 — 25-frame animation of the w′ response at z ≈ 3 km

Mature-example form

• Self-contained in one file: Jordan sounding, YD19 constants, kinematics, Picard solver, residuals diagnostic — no external includes.
• Dense Literate prose with five LaTeX math blocks (gradient wind, modified-Rankine, Picard fixed point, YD19 Eq. 3 heating, dry-static-energy target).
• 24 inline [Author](@citet) / @cite markers for every scientific reference; six bib entries added.
• @ref cross-refs for Breeze API (ReferenceState).
• ![](…mp4) embed for the animation so Documenter renders it inline.
• Analysis block uses streaming FieldTimeSeries(...; backend=Oceananigans.OnDisk()) and preallocated Float32 scratch buffers — peak RSS during analysis is bounded to a handful of 3D fields (~50 MB at this resolution) regardless of snapshot count.

Implementation notes & caveats

• Float64 default. Float32 was attempted and deferred: the anelastic pressure solve NaN's in ρu within 100–300 spinup steps at 3 km on GPU with the YD19 vortex intensity. Smoke-domain (12 km) Float32 runs were stable. Worth a separate Breeze-level stability investigation.
• Explicit horizontal diffusivity is absent. Without it, the response amplitude likely inflates past the paper's quasi-steady ±1.5 m/s after ~7 h (F06 diagnostic). YD19's WRF setup has a subgrid closure that damps the response; we don't. Analysis window is chosen accordingly.
• The example is gated build_always=false, gpu=true, it only runs when BREEZE_BUILD_ALL_EXAMPLES=true on a GPU runner.
• Worth also looking if stretched grid is appropriate here.

Test plan

• Full GPU run reproduces the numbers in the table above.
• Meta.parseall passes.
• Local Documenter draft build: Literate parses the script, all six new @cite markers resolve, @ref resolves for ReferenceState, no example-specific errors.
• CI green on a GPU-enabled run (requires reviewer to trigger BREEZE_BUILD_ALL_EXAMPLES=true or equivalent).
• Run at a high resolution for benchmarking/pretty pictures purposes.

References

• Yu, C.-K. and Didlake, A. C. (2019). J. Atmos. Sci., 76, 3169–3189. doi:10.1175/JAS-D-18-0259.1
• Moon, Y. and Nolan, D. S. (2010). J. Atmos. Sci., 67, 1779–1805. doi:10.1175/2010JAS3284.1
• Stern, D. P. and Nolan, D. S. (2009). J. Atmos. Sci., 66, 3579–3600. doi:10.1175/2009JAS3021.1
• Nolan, D. S. (2001). Physics of Fluids, 13, 1724–1738. doi:10.1063/1.1369646
• Jordan, C. L. (1958). J. Meteor., 15, 91–97.
• Emanuel, K. A. (1986). J. Atmos. Sci., 43, 585–605.

[bischtob]

[bischtob]

response_w_z3km.mp4

[navidcy]

I don't think we need this, right?

Suggested change

example_dir = @__DIR__

[giordano]

Float64 default. Float32 was attempted and deferred: the anelastic pressure solve NaN's in ρu within 100–300 spinup steps at 3 km on GPU with the YD19 vortex intensity. Smoke-domain (12 km) Float32 runs were stable. Worth a separate Breeze-level stability investigation.

Unfortunately the L4 really struggles with intensive Float64 workloads. This example alone (I disabled all the other GPU ones) took 80 minutes (before erroring during the plotting part due to a literate syntax error)

[giordano]

https://github.com/NumericalEarth/Breeze.jl/actions/runs/24929552701/job/73004993549#step:7:82

┌ Error: Generated HTML over size_threshold limit: literated/tropical_cyclone_with_rainband.md
│     Generated file size: 568.2 (MiB)
│     size_threshold_warn: 512.0 (KiB)
│     size_threshold:      1.0 (MiB)
│     HTML file:           literated/tropical_cyclone_with_rainband/index.html
└ @ Documenter.HTMLWriter /usr/local/share/julia/packages/Documenter/AXNMp/src/html/HTMLWriter.jl:2000

Half a GB for a webpage is indeed quite a lot 😳

[nrb171]

Ok. I think I found the issue. I'm testing it on my end before I push anything up.

[giordano]

Docs building finally works: https://numericalearth.github.io/BreezeDocumentation/previews/PR657/literated/tropical_cyclone_with_rainband/ 🥳 only problem now is that the new example takes over one hour to run (and it'll be a lot worse when we restore all other examples), because fp64 performance is pretty bad on this GPU 🫠

[navidcy]

Docs building finally works: https://numericalearth.github.io/BreezeDocumentation/previews/PR657/literated/tropical_cyclone_with_rainband/ 🥳 only problem now is that the new example takes over one hour to run (and it'll be a lot worse when we restore all other examples), because fp64 performance is pretty bad on this GPU 🫠

What if we run on Float32?

[giordano]

Apparently it wasn't stable: #657 (comment)