[hdrake]

Targets examples-06-tripolar-fold (the branch behind #26), so the diff is only the review fixes on top of the five examples.

Acts on an independent review of the examples as of #26, against the stated goal of demonstrating xgcm's functionality for common ocean-modelling workflows. All five notebooks were re-executed end-to-end against the xgcm#711 build — 0 cell errors. The 1.1 GB ECCOv4r4 download was pulled and 01 genuinely re-run.

The one correctness bug

02_mitgcm was shipping wrong physics. The boundary→padding migration in 20bb1a1 turned the deliberate non-periodic Y from 534d73a ("make Y non-periodic (extend)") into padding={'Y': 'periodic'}. The domain is global in longitude but spans only 78°S–78°N, so periodic Y wraps the Antarctic edge (YG=−80) onto the Arctic row (YC=+78).

Measured impact — narrower than it looks, which is why it survived review:

rows differing (periodic vs extend)	[39] of 40 — the northernmost only
row 39 max|div|, periodic (wrong)	2.553e-06
row 39 max|div|, extend (correct)	3.289e-06
typical interior max|div|	6.233e-06

Only the north edge is padded by diff/interp on a left-edge Y axis, so exactly one row moves, by the same order as the interior. psi is unaffected — it passes an explicit padding='fill' to cumsum.

Plotting into modules

Per the brief: modules for plotting routines and nothing else. Every xgcm call stays inline in the notebook where a reader can see it.

• llc_plots.py — LLCMapper out of 01 (56 lines of pyresample/cartopy against ~4 lines of xgcm, reused 6×). Drops a dead else branch that built a stray unused axes; documents the antimeridian split and the radius_of_influence/dx constants.
• tripolar_plots.py — the ~250-line matplotlib layer out of 05. The notebook now computes every halo with xgcm up front; the module only draws.

A cheap first plot everywhere

• 02 — ds.THETA[0, 0].plot() before any xgcm; the grid is a plain lon/lat rectangle.
• 03 — plots in nominal index coordinates first, then explains why they mislead. The top row's nominal y reads as a single 89.95, while the true 2-D lat along that row runs 64.11°–89.94°: it is the fold seam, flattened into a straight line. That motivates the 2-D lon/lat map that follows.
• 05 — a raw index-space overview before any fold machinery.
• 01 — already had one (per-tile in index space); reframed as the honest layout view rather than a failed map.

Clarity

• 02: prose claimed xgcm found "five axes … 1RHO"; it reports four (X/Y/Z/T) and the dataset has no 1RHO dim. Rewritten, along with the pre-rename "periodic" framing. Four empty trailing cells removed.
• 01: the 13-tile face_connections dict now explains how to read a (tile, axis, reverse) triple and links to the Face Connections Spec.
• 05: dropped three dead padding= kwargs — see below.
• 05: explained autoparse_metadata=False; framed the xgcm.padding.pad use explicitly as an under-the-hood aside.
• 04: dropped the cell printing a dev version hash (0.9.1.dev59+g...) into the rendered docs.
• environment.yml: advertised the pre-rename boundary={"Y": {"fold": ...}}.
• Readme.md: documents the module convention and the cheap-plot-first guidance.

On 05's padding= kwargs — a correction worth recording

An initial review claimed 05's interp/diff never cross the fold, because padding="extend"/"fill" at the call site would override the grid's fold via defaults | user_kwargs (grid.py:311). That is false, and so was a follow-up claim that the kwarg is silently ignored on a fold axis.

What is actually true, per padding.py:53–55 and test_fold_south_edge_respects_per_call_padding:

• north edge → always folds (topology; mirrors how _pad_face_connections dispatches on grid state and likewise cannot be overridden);
• south edge → honours the per-call padding.

The kwargs in 05 are no-ops for a mundane reason: these operators pad only the north edge (padding_width=(0, 1)), so the south mode is never consulted. Verified behaviour-preserving before removal — fold vs extend gives max|diff| = 0 on real Oceananigans data for both interp and diff. 05's thesis stands and its outputs are unchanged. The kwargs go because they misled a careful reader into a false bug report.

Not done here (deliberately)

• Grid ufuncs still have zero example coverage — no notebook calls apply_as_grid_ufunc/as_grid_ufunc, despite two dedicated tutorial pages. Also uncovered: average, interp_like, get_metric/set_metrics, interp_2d_vector, Grid.min/max. Worth a follow-up.
• Nav reordering (suggested 02 → 04 → 03 → 01 → 05, renumbering files to match) — touches mkdocs.yml in the main repo, so it belongs with #711.
• Coverage is concentrated: 04 is the only notebook using metrics/derivative/integrate/cumint/transform.

Follow-up for xgcm#711

Passing padding= on a fold axis quietly does nothing whenever only the north edge is padded — the common case. It misled two consecutive readers. xgcm should warn in that situation; it would have caught these dead kwargs immediately.

🤖 Generated with Claude Code

https://claude.ai/code/session_01C2MVD2DtZLieu1zXgEoXbv

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB