hdrake · hdrake · Jun 25, 2026 · Jun 25, 2026 · Jun 25, 2026 · Jun 25, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## What this is
 
-`regionate` builds **xgcm-grid-consistent** regional masks and boundaries for ocean/climate model output (currently mostly MOM6, but with plans to support any ocean model). Given a geographic polygon, it snaps the polygon to a discrete model grid, producing a boolean cell mask plus the staggered (u,v) velocity faces that trace the region's boundary — so that volume/mass/heat budgets integrated over the masked region are exactly consistent with fluxes through the boundary faces. It leans heavily on its sibling package [`sectionate`](https://github.com/MOM6-community/sectionate) for the section/face-tracing math.
+`regionate` builds **xgcm-grid-consistent** regional masks and boundaries for ocean/climate model output. It supports **arbitrary `xgcm.Grid` topologies** — single-tile periodic and bipolar-fold (Arctic) MOM6 grids, and genuinely multi-tile grids defined by `face_connections` (e.g. ECCOv4r4 lat-lon-cap, cubed-sphere) — by driving all grid logic from the topology-aware `sectionate` API rather than hard-coded MOM6 specifics. Given a geographic polygon, it snaps the polygon to a discrete model grid, producing a boolean cell mask plus the staggered (u,v) velocity faces that trace the region's boundary — so that volume/mass/heat budgets integrated over the masked region are exactly consistent with fluxes through the boundary faces. It leans heavily on its sibling package [`sectionate`](https://github.com/MOM6-community/sectionate) for the section/face-tracing math (requires the topology-driven API on [`hdrake/sectionate@topology-driven-neighbors`](https://github.com/hdrake/sectionate/tree/topology-driven-neighbors), formerly PRs #47/#48), and on the bipolar north-fold boundary (`padding={..., "Y": {"fold": ...}}`, formerly xgcm#711) plus the multi-tile `face_connections` padding fix (xgcm#712) and the vector-pad fix (xgcm#749), all released in `xgcm >= 0.10.1` (on PyPI).
 
 ## AI Usage Policy
 
@@ -34,7 +34,7 @@ pytest -k <name>                                # run a single test by name
 pip install -e .                                # editable install (after creating env)
 ```
 
-Dev environment is conda-based (see README). CI (`.github/workflows/ci.yml`) installs `ci/environment.yml`, does `pip install -e .`, then runs `pytest` across Python 3.11–3.14. There is no linter configured.
+Dev environment is conda-based (see README). CI (`.github/workflows/ci.yml`) installs `ci/environment.yml`, installs `sectionate` from `hdrake/sectionate@topology-driven-neighbors` (still unreleased), does `pip install -e .` (which pulls `xgcm >= 0.10.1` straight from PyPI — 0.10.1 ships the north-fold boundary and the multi-tile padding fixes), then runs `pytest` across Python 3.11–3.14. There is no linter configured. Optional end-to-end tests against real MOM6/ECCO grids are skipped unless `REGIONATE_REALDATA_TESTS=1`.
 
 ## Versioning
 
@@ -45,29 +45,30 @@ Consequences worth remembering when editing:
 - **Never add a version literal back to the tree**, and never "fix" a `0.0.0+unknown` by hardcoding one — it means the package was imported without being built or installed.
 - **Any CI job that installs the package needs `fetch-depth: 0`.** A shallow clone cannot see the tag, so hatch-vcs silently resolves a `0.1.devN` version instead of failing. The checkouts in `ci.yml` and `publish-to-pypi.yml` set it, and `.readthedocs.yaml` unshallows in `post_checkout` for the same reason. The same applies to a `pip install git+https://…` of a fork with no tags: it reports `0.1.devN`, which can fall below a downstream floor.
 - `_version.py` **is** shipped inside the sdist, so building from the sdist (as conda-forge does) works with no git present. Do not add it to `[tool.hatch.build] exclude`.
-- conda builds run with `--no-build-isolation`, so `hatch-vcs` must sit next to `hatchling` in the recipe's `host` requirements — in `conda/meta.yaml` here and on the conda-forge feedstock.
+- conda builds run with `--no-build-isolation`, so `hatch-vcs` must sit next to `hatchling` in the recipe's `host` requirements — on the conda-forge feedstock (the in-tree `conda/meta.yaml` has been removed).
 - Releasing is just publishing a GitHub Release tagged `vX.Y.Z`; there is no bump commit. See "Releasing" in `README.md`.
 
 ## Architecture
 
 The class hierarchy in `regionate/region.py` is the spine of the package:
 
 - **`Region`** — a named polygon, just `(lons, lats)` corner arrays. Can force counterclockwise winding (`is_section_counterclockwise` from sectionate) and prune duplicate points. No grid awareness.
-- **`GriddedRegion(Region)`** — a `Region` bound to an `xgcm.Grid`. Construction calls `get_region_boundary_grid_indices` + `mask_from_grid_boundaries` (in `grid_conform.py`) to compute: corner grid indices (`i_c`, `j_c`), the boundary `(u,v)` velocity faces, and the boolean cell `mask`. This is the central object — masks and boundaries are the whole point.
+- **`GriddedRegion(Region)`** — a `Region` bound to an `xgcm.Grid`. Construction calls `get_region_boundary_grid_indices` + `mask_from_grid_boundaries` (in `grid_conform.py`) to compute: corner grid indices (`i_c`, `j_c`, and the per-corner face index `f_c` — `None` for single-tile grids), the boundary `(u,v)` velocity faces, and the boolean cell `mask`. This is the central object — masks and boundaries are the whole point.
 - **`BoundedRegion(GriddedRegion)`** — a GriddedRegion whose boundary is defined by named sections rather than a raw polygon.
 
 Supporting modules:
 - `regions.py` — **`Regions`**, a dict-like collection mapping names → `Region`/`GriddedRegion`; `overlaps.py` handles intersections between members.
-- `grid_conform.py` — the core grid-snapping logic (polygon → grid indices → mask), using `regionmask`, `shapely`, and sectionate.
-- `boundaries.py` — `grid_boundaries_from_mask` (inverse: recover boundary faces from a mask).
+- `grid_conform.py` — the core grid-snapping logic (polygon → grid indices → mask). `mask_from_grid_boundaries` rasterizes a boundary by splitting it at the antimeridian into a `[-180,180]` MultiPolygon and OR-ing per-piece `regionmask` masks (pole-encircling boundaries are extended to the South Pole first).
+- `geometry.py` — antimeridian / MultiPolygon shapely helpers (`split_at_antimeridian`, `normalize_lon`, ...) used by `grid_conform.py`.
+- `boundaries.py` — `grid_boundaries_from_mask` (inverse: recover boundary faces from a mask). A shared front-end `_trace_and_drop` traces the mask per face with `contourpy` and drops boundary segments interior to a seam (both separated cells in-mask in the topology-aware halo `_pad_center`); two back-ends then stitch the surviving arcs: `_single_tile_boundaries_from_mask` stitches by physical seam coincidence (handles walls, **periodic** axes, and the bipolar **fold** uniformly; `f_c=None`), and `_multitile_boundaries_from_mask` stitches on the grid's outer (shared-corner) corner-node graph from `sectionate.gridutils.outer_topology`: every traced corner resolves to a physical corner node (uniform across rotated/reversed seams, cube-vertex junctions, the pole, and grid cuts/folds), edges traced from both sides of an undeclared cut/fold annihilate as interior, surviving segments chain into closed loops by node identity, and each node is emitted as the native corner that stores it (`f_c_list`; `None` for single-tile). Boundaries through points stored on no face (LLC90's 4th Arctic-cap vertex, single-sided contact with its lon=-115 Antarctic cut) raise rather than fabricate indices. A region wrapping any seam yields one seam-consistent boundary (an annulus/strip may yield several loops); `_pad_center` pads only genuine seams (periodic/fold/face_connections) with real neighbours and everything else with NaN, so walls are never mistaken for seams. For the budget's *area side* on multi-tile staggered grids, use `outer_topology(grid).padded_transports(u, v)` — exact and xgcm-independent, and the only path that handles edges stored on no face (walls, grid cuts, a cap's un-stored vertex). (xgcm#749 fixes the bare-`DataArray` `grid.diff(..., other_component=)` path across rotated/reversed seams — the dict form was always exact — but even a correct pad cannot supply a halo for edges stored on no face, so `padded_transports` remains preferred here.)
 - `integrate.py` — `check_global_coverage` validates that a `Regions` set is non-overlapping and tiles the globe.
 - `utilities.py` — shared helpers (re-exported widely via `from .utilities import *`).
 
 `regionate/__init__.py` flattens everything into the top-level namespace via `import *`, so public symbols are referenced as `regionate.Region`, `regionate.GriddedRegion`, etc.
 
 ### The `.gr` save format
 
-`GriddedRegion.save()` writes a **directory** (`<name>.gr/`), not a single file: `region.nc` plus the grid dataset and section sub-directories as separate NetCDFs. `open_gr(path, ds_to_grid)` reloads it — note it takes a `ds_to_grid` callback because the `xgcm.Grid` cannot be serialized directly and must be reconstructed from the saved dataset.
+`GriddedRegion.to_gr(path)` writes a **directory** (`<name>.gr/`), not a single file: `region.nc` (boundary coords `lons_c`/`lats_c`, corner indices `i_c`/`j_c`/`f_c`, optional `lons_uv`/`lats_uv`, and the `mask`) plus the grid dataset and child-section sub-directories as separate NetCDFs. `open_gr(path, ds_to_grid)` reloads it — note it takes a `ds_to_grid` callback because the `xgcm.Grid` cannot be serialized directly and must be reconstructed from the saved dataset. The face index `f_c` is persisted and reloaded so multi-tile regions do not silently reload as single-tile.
 
 ## Conventions
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -92,6 +92,8 @@
     "2_advective_heat_convergence.ipynb",
     "3_Arctic_heat_CM4p25.ipynb",
     "4_bounded_by_named_sections.ipynb",
+    "5_ECCO_LLC90_multiface_regions.ipynb",
+    "6_idealized_corner_cases.ipynb",
 ]
 
 

diff --git a/docs/environment.yml b/docs/environment.yml
@@ -9,7 +9,7 @@ dependencies:
   - jupyterlab
   - matplotlib
   - netcdf4
-  - pydap
+  - pandoc
   - pytest
   - ipykernel
   # Docs toolchain (standardized "xeos stack": Sphinx + Furo + myst-nb).

diff --git a/docs/index.md b/docs/index.md
@@ -10,6 +10,11 @@ or heat budget integrated over the masked region is exactly consistent with the
 fluxes through its boundary — the property that makes closed regional budgets
 possible.
 
+All grid logic is driven by the grid's own topology, so this works on **arbitrary
+`xgcm.Grid` topologies**: single-tile periodic grids, bipolar-fold (Arctic) MOM6
+grids, and genuinely multi-tile grids defined by `face_connections` (e.g. the
+ECCOv4r4 lat-lon-cap grid, cubed spheres).
+
 It leans on its sibling package
 [`sectionate`](https://github.com/MOM6-community/sectionate) for the
 section- and face-tracing math, and builds on
@@ -29,6 +34,8 @@ examples/1_thickness_budget
 examples/2_advective_heat_convergence
 examples/3_Arctic_heat_CM4p25
 examples/4_bounded_by_named_sections
+examples/5_ECCO_LLC90_multiface_regions
+examples/6_idealized_corner_cases
 contributing
 api
 ```
diff --git a/docs/installation.md b/docs/installation.md
@@ -3,9 +3,18 @@
 ## Requirements
 
 regionate is compatible with python 3 (>= version 3.11). It requires
-[xgcm](https://xgcm.readthedocs.io/en/stable/) and its sibling package
+[xgcm](https://xgcm.readthedocs.io/en/stable/) (>= 0.10.1, which ships the
+bipolar north-fold boundary and the multi-tile `face_connections` padding fixes)
+and the topology-driven API of its sibling package
 [sectionate](https://github.com/MOM6-community/sectionate).
 
+The topology-driven sectionate API is not on PyPI yet, so install it from its
+development branch first:
+
+```bash
+pip install "sectionate @ git+https://github.com/hdrake/sectionate.git@topology-driven-neighbors"
+```
+
 ## From conda-forge
 
 ```bash

diff --git a/examples/1_thickness_budget.ipynb b/examples/1_thickness_budget.ipynb
diff --git a/examples/2_advective_heat_convergence.ipynb b/examples/2_advective_heat_convergence.ipynb
diff --git a/examples/3_Arctic_heat_CM4p25.ipynb b/examples/3_Arctic_heat_CM4p25.ipynb
diff --git a/examples/4_bounded_by_named_sections.ipynb b/examples/4_bounded_by_named_sections.ipynb
diff --git a/examples/5_ECCO_LLC90_multiface_regions.ipynb b/examples/5_ECCO_LLC90_multiface_regions.ipynb