docs[next]: add a shallow water model example notebook

[havogt]

Adds the NCAR SWM shallow water benchmark as a single gt4py.next notebook. First of a small stack; this one is a pure examples/ addition with no src/ changes.

Contents

file	size
examples/swm.ipynb	15 KB	the example
examples/swm_numpy.py	4.8 KB	NumPy reference implementation
examples/swm_reference.npz	4.8 KB	u, v, p after 4000 steps, 16x16

The model is doubly periodic on an Arakawa C-grid, leapfrog with a Robert-Asselin filter, integrated by one fused field operator producing all six updated fields.

Periodicity is outside GT4Py here

The halo is refreshed in NumPy after each step. Expressing the wrap inside the field operator needs f(I + M) with M a program argument, which the frontend rejects at FOAST construction — that is deliberately deferred to a later PR in this stack so this one carries no frontend risk.

Validation

Two levels, because the full benchmark is too slow for CI:

• every run — 100 steps, GT4Py vs the NumPy reference. ~5 s.
• opt-in (RUN_FULL_BENCHMARK = True) — the full 4000 steps against swm_reference.npz. ~20 s.

I ran the opt-in check before opening this; it passes. Measured differences, against peak |u|,|v| ~ 3.8 and |p| ~ 5e4:

	100 steps	4000 steps	tolerance
u	2.1e-13	9.6e-13	atol=1e-11
v	2.0e-13	7.2e-13	atol=1e-11
p	5.1e-11	3.1e-10	atol=1e-8

The two implementations sum the same terms in a different order, so they agree to rounding rather than bit-for-bit. Tolerances are absolute because u and v cross zero, and are set with ~30x headroom for portability across the CI matrix.

The NumPy reference is itself checked against the NCAR data: it reproduces ref/16x16/{u,v,p}.step4000.final.bin to 1.1e-12 / 8.2e-13 / 2.6e-10.

Notes

• swm_reference.npz is derived from NCAR/SWM ref/16x16, which is Apache-2.0; provenance is recorded in the notebook.
• The scheme is Sadourny (1975), cited in the notebook with its DOI. The constants (dt=90, dx=1e5, alpha=0.001, …) are Swarztrauber's 1984 NCAR benchmark configuration rather than results from the paper — the notebook says so, since the distinction is easy to get wrong.
• Follows the examples/ conventions: license header as a markdown cell, embedded backend by default with compiled ones commented out, outputs and execution counts stripped.
• pytest --nbmake examples passes (5 notebooks, 21 s).

Next in the stack

1. collapse the eight *_staggered operator pairs using staggered dimensions
2. move periodicity into the field operator (needs the frontend changes)

[havogt]

Reopening from a branch on GridTools rather than my fork, so this can be the base of a stack — cross-fork stacks are unimplemented (github/gh-stack#46). Superseded by the PR below.