Restructure the SCHISM notebooks into a tutorial and examples

[rafa-guedes]

This PR replaces the SCHISM notebooks with a new collection in the same tutorial and examples layout as XBeach (#3) and SWAN (#4).

The collection

All notebooks model the coast off Perth in early January 2023. Every notebook that needs it runs SCHISM, and the results are committed.

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

  1. a first tidal model;
  2. the mesh and the vertical grid;
  3. tides and open boundaries;
  4. atmospheric forcing;
  5. model settings (param.nml), SCHISM's defaults and rompy-schism's checks;
  6. a four-day tide and wind hindcast, with checks and analysis;
  7. YAML and the rompy CLI, including rompy run.

• notebooks/schism/examples/, 9 focused notebooks:

  • making a mesh;
  • tidal boundaries, ocean-model boundaries, a baroclinic 3D model started and forced from GLORYS, waves with WWM;
  • output (scribes, 2D/3D files, stations), hotstart and chained runs, running SCHISM (local, Docker, MPI), friction sensitivity.

• notebooks/schism/data/, 3.4 MB committed:

  • a mesh of the Perth coast made for the notebooks from ETOPO 2022, with its script (make_mesh.py);
  • TPXO9 tidal constituents for the area as a pyTMD database, with its script (make_tides.py);
  • ERA5 wind and pressure, GLORYS12 ocean reanalysis, and the ETOPO and WAVEWATCH III files shared with the SWAN notebooks.

  It is listed in data/example-data.json. TPXO is free for research and non-commercial use, as the data README says.

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

Removed

• The previous SCHISM notebooks (tutorial_01–07, schism_demo). They depended on a downloaded fixture bundle and did not run SCHISM successfully.
• The fixture bundle's acquisition (scripts/schism_case_data.py, --acquire-schism).
• The figures docs build and its CI step. It only executed those notebooks; the site is now built with make docs-build, like the committed outputs of the other models.

Site and tooling

• Metadata: rompy_notebooks metadata on every notebook, the same convention as XBeach and SWAN.
• Audit:
  • The SCHISM checks use the lesson template and the new paths, and every example is checked.
  • The value-narrative and forcing-depth checks and the execution-contract marker applied only to the previous SCHISM notebooks, so they are removed.
• Docs pages:
  • schism-tutorial.md, models/schism.md, the gallery, the coverage matrix and the concept-page links are updated.
  • The installation guide now lists the Docker images of all three models.
• requirements.txt installs rompy-schism from main. The notebooks need the rompy-schism fixes below; change it to a release once one is published.

Dependencies in rompy-schism

The notebooks need these open PRs:

• Write the vertical and vegetation parameters to &OPT, where SCHISM reads them rompy-schism#19, #20, #21, #22, #23, #24, #26, #27 and #28: bug fixes found while writing these notebooks. Without them, SCHISM ignores the vertical and vegetation settings, bctides.in is wrong for several boundary types, generated hotstarts are ignored, 3D models cannot be generated, and 3D boundary data has the wrong vertical profiles.
• Publish a SCHISM Docker image to run rompy-schism workspaces rompy-schism#25: ghcr.io/rom-py/schism:5.13.0, SCHISM with MPI, NetCDF, WWM and combine_hotstart7. The notebooks use this image; it must be published and made public before the notebooks run for users.

Checks

• All 16 notebooks executed end to end from a clean kernel, against rompy main and rompy-schism with the PRs above, running SCHISM with the locally built image.
• The tidal model matches the TPXO prediction at the boundary within about 1 cm RMS.
• make docs-build (audit and mkdocs build --strict) passes. pytest tests passes.