Support arbitrary xgcm topologies for boundaries and masks

[hdrake]

Summary

Generalizes regionate from single-tile MOM6 grids to arbitrary xgcm.Grid topologies — single-tile periodic, bipolar-fold (Arctic) MOM6, and genuinely multi-tile grids (ECCOv4r4 LLC90, cubed-sphere) — by driving all grid logic from the topology-aware sectionate#47 API (plus the bipolar north-fold boundary from xgcm#711) instead of hard-coded MOM6 specifics.

(1) Boundaries from masks — boundaries.py

• Single-tile path preserved byte-for-byte (shared _contour_to_corner_indices; existing tests unchanged).
• New multi-tile path: per-face boundary faces are read from a topology-aware padded mask (real-neighbour halo via the grid's own boundary/face_connections); faces internal to a tile seam are dropped; surviving directed edges are stitched into closed loops by physical coincidence. A region spanning several faces yields a single boundary loop.
• Returns a new per-corner face index f_c_list (None for single-tile).

(2) Masks from boundaries — grid_conform.py + new geometry.py

• Antimeridian-split MultiPolygon + per-piece regionmask rasterization OR-ed together (modeled on xcryocouple.geometry; the intent is for xcryocouple to depend on regionate, not the reverse).
• Pole-encircling boundaries (net |Δlon| ≈ 360°) are extended to the South Pole, then rasterized through the same split+OR path.
• Coordinate names are discovered via sectionate (get_geo_corners/get_geo_centers/coord_dict) — no hard-coded geolon/geolat.

(3) Refactor

• f_c threaded through Region/GriddedRegion/BoundedRegion, MaskRegions, and the .gr/.grs save format.
• Fixed the genuinely-broken .gr save/load (variable-name mismatch + unguarded children); it now round-trips f_c.
• Generalized corner-coordinate checks (arbitrary names).

(4) ECCO LLC90 worked example — examples/5_ECCO_LLC90_multiface_regions.ipynb

• End-to-end demonstration on the native ECCOv4r4 lat-lon-cap grid: trace the Atlantic basin into grid-conforming boundary loops spanning many tiles (across rotated seams and the Arctic cap), then verify the discrete divergence theorem with ECCO's own advective heat transport (ADVx_TH/ADVy_TH, depth-integrated).
• The check is computed two independent ways and agrees to round-off (residual 0): cell-centred convergence via xgcm's vector-aware diff_2d_vector summed over the basin mask, vs the same transport as a boundary integral via sectionate.convergent_transport(..., positive_in=region.mask) over every traced loop — the idiomatic cross-boundary-transport calculation regionate's boundary tracing exists to feed.
• Grid geometry and a month of native temperature fluxes are loaded from the regionate/sectionate example archive on Zenodo; no NASA Earthdata login is required (the loader no longer uses earthaccess/PO.DAAC). Flux components are promoted to float64 in the loader (the archive is float32, ~12 °C m³ s⁻¹ on these O(1e8) transports, which would otherwise dominate the residual).

Dependencies / CI

• Add explicit shapely and xgcm >= 0.9.0. Drop the now-unused earthaccess/pydap from docs/environment.yml (ECCO data now comes from Zenodo over plain HTTP).
• Requires sectionate#47 (topology-driven neighbour finding). That branch self-reports 0.3.3, so the floor stays >= 0.3.3 and CI installs sectionate from the PR ref (refs/pull/47/head) until it is released.
• Requires xgcm#711 (the bipolar north-fold boundary, boundary={"Y": {"fold": ...}}) for single-tile tripolar-fold masks/boundaries. That branch is a superset of the merged face_connections padding fix (xgcm#712) the multi-tile path needs, so CI installs xgcm from the tripolar-north-fold ref until it is released. This PR should not be released until both xgcm#711 and sectionate#47 merge.
• Specifically depends on the is_mask_inside multi-tile sign fix in sectionate#47 (MOM6-community/sectionate@4df149c): on multi-tile grids the face-frame Usign/Vsign diverge from the geometric Lsign, so before that fix convergent_transport(positive_in=mask) returned an inverted sign on the ECCO LLC grid (the divergence theorem closed in magnitude but with flipped sign). The ECCO example above relies on the fixed behaviour.

Tests

20 passed, 5 skipped by default. New: self-contained two-face (face_connections) fixture exercising seam-spanning (one stitched loop across faces), seam-terminating (seam edge kept), interior-cell, and MaskRegions f_c threading; plus a pole-encircling regression test; and a self-contained single-tile fold fixture (test_fold_regions.py: a fold-straddling region stitches into one loop, a genuine seam boundary face is kept, the discrete divergence theorem closes to 1e-9, and an interior region is unaffected). The five real-data end-to-end checks (the MOM6 global tripolar grid, plus three ECCOv4r4 LLC90 checks — seam stitching across rotated seams and the Arctic cap, basin boundary→velocity-face conversion, and the discrete divergence theorem), plus the MOM6 Arctic-fold check (the notebook-3 region traces as one region across the fold and closes the budget), are opt-in via REGIONATE_REALDATA_TESTS=1 with the data files present locally, so the default suite (and CI) never reaches out to the network. The multi-tile convergent_transport(positive_in=mask) sign behaviour relied on by the ECCO example is covered by a regression test in sectionate#47 (test_left_multitile_mask_orientation).

(5) Single-tile bipolar north fold — boundaries.py

Resolves the prior follow-up. Single-tile tripolar grids that declare the xgcm north-fold boundary (xgcm#711, boundary={"Y": {"fold": ...}}) now trace fold-straddling masks into a single loop. _fold_boundaries_from_mask (dispatched via _has_fold) drops fold-seam segments interior to the region — using the grid's own fold-aware halo — and stitches the surviving arcs by physical seam coincidence (a 3-D unit-sphere key, robust to the antimeridian and poles), keeping fold crossings in the coincident-seam-corner form sectionate collapses to zero-length faces. So the boundary's velocity faces reproduce the region's flux convergence exactly; the plain single-tile and multi-tile paths are unchanged.

Demonstrated in examples/3_Arctic_heat_CM4p25.ipynb: the high-Arctic cold region — previously split into two halves whose fold-normal fluxes happened to cancel — is now one region, and its advective-heat budget closes the discrete divergence theorem to round-off (boundary integral vs interior flux convergence, float64 fluxes). The example grid loader gains an opt-in fold argument.

🤖 Generated with Claude Code

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[hdrake]

Rebased this PR's environment onto the outer-lattice stack for the most complete multi-tile boundary treatment:

• sectionate → MOM6-community/sectionate#48 (outer corner-node topology + exact padded_transports; builds on #47), installed via refs/pull/48/head.
• xgcm → hdrake/xgcm@tripolar-north-fold-vectorpad = the bipolar north-fold branch (xgcm#711/#712) with the bare-DataArray other_component vector-pad fix (xgcm#749) cherry-picked on top.

Validation against that environment:

• pytest with REGIONATE_REALDATA_TESTS=1 → 35 passed (includes the ECCO LLC90 discrete-divergence-theorem checks).
• All six example notebooks re-executed cleanly; notebook 5's ECCO LLC90 divergence-theorem residual is exactly 0.00e+00.

Docstring/CLAUDE.md wording for padded_transports was nuanced: xgcm#749 fixes the bare-DataArray grid.diff(other_component=) path across rotated/reversed seams (the dict form was always exact), but padded_transports remains the exact, xgcm-independent path because it resolves edges stored on no face (walls, the lon=−115 cut, the 4th Arctic vertex) that no halo pad can supply a value for.