Restructure the SWAN notebooks into a tutorial and examples

[rafa-guedes]

This PR replaces the SWAN notebooks with a new collection in the tutorial/examples layout of the XBeach notebooks, as agreed.

Builds on #3, now merged into wp5-1. The branch includes the latest wp5-1, with the hook import fix.

The collection

All notebooks model the coast off Perth on 1 January 2023, with ETOPO 2022 bathymetry, ERA5 winds and WAVEWATCH III boundary spectra. Every notebook that needs it runs SWAN, and the results are committed.

• notebooks/swan/tutorial/, 7 ordered lessons:

  1. a first stationary model;
  2. the grid and spectrum;
  3. input grids and SWAN's modes;
  4. wave boundaries;
  5. model settings and SWAN's defaults;
  6. a nonstationary hindcast, with checks and analysis;
  7. YAML and the rompy CLI, including rompy run.

• notebooks/swan/examples/, 12 focused notebooks:

  • grid types, input grids;
  • parametric boundaries, boundaries from spectra, nesting (a parent run feeding a child);
  • physics, numerics, output;
  • stationary vs nonstationary computations, hotstart and chained runs;
  • running SWAN (local, Docker, MPI), physics sensitivity.

• notebooks/swan/data/, 2 MB committed:

  • an ETOPO 15″ bathymetry subset from NOAA's ERDDAP server;
  • the ERA5 and WW3 files shared with the XBeach notebooks;
  • an intake catalogue.

  It is listed in data/example-data.json.

• notebooks/swan/README.md is the index, including a table of where each previous notebook's content went.

The notebooks explain the SWAN concepts they use (computational vs input grids, spectral resolution, conventions, defaults, time steps, how to check PRINT) and link to the SWAN 41.51 manual. The model-agnostic value of rompy is covered by docs/why-rompy.md and common/rompy_hands_on.ipynb from #3, so the notebooks don't repeat it.

Removed

The previous SWAN notebooks and their YAML files: tutorial_01–07, example_*, boundary/* and components/output. Their content is covered as listed in the README.

Site and tooling

• Metadata: rompy_notebooks metadata on every notebook, the same convention as XBeach.
• Audit: the SWAN checks use the lesson template and the new paths, and every example is checked, as for XBeach.
• Docs pages: swan-tutorial.md, models/swan.md, the gallery, the coverage matrix and the concept-page links are updated. The conventions page now lists XBeach and SWAN on the shared layout.
• requirements.txt installs rompy-swan from main, because the notebooks need the fixes in Fix stationary runs, boundary spreading and several rendering bugs rompy-swan#20. Change it to a release once one is published.

Dependencies in rompy-swan

• Fix stationary runs, boundary spreading and several rendering bugs rompy-swan#20: bug fixes found while writing these notebooks. Without it, stationary runs fail in SWAN, boundaries use the wrong spreading convention, and output ignores the run interval.
• Publish SWAN images with NetCDF to ghcr.io/rom-py/swan rompy-swan#21: ghcr.io/rom-py/swan:41.51, SWAN with NetCDF. The official delftwaves/swan image writes .nc output as text. The notebooks use this image; it must be published and made public before the notebooks run for users.

Checks

• All 19 notebooks executed end to end from a clean kernel, against rompy main and rompy-swan with #20, running SWAN with the locally built image of #21.
• make docs-build (audit and mkdocs build --strict) passes with no warnings. pytest tests passes.
• Crawled every internal link on the built site.