WIP: Add s2 manifold to conservative_2d (stacks on #70)

[thodson-usgs]

Summary

Adds a manifold kwarg to ConservativeRegridder / .regrid.conservative_2d with three values:

• "planar" (default, existing behavior): raw planar shapely intersection
• "cea" (existing): analytic Lambert cylindrical equal-area projection before planar intersection — correct spherical areas with the planar fast-path cost, straight-line edges in the projected plane
• "s2" (new): true great-circle edges via the optional spherely package (Google's s2geometry bindings). Full spherical geometry — correct for cells at any latitude or longitude extent.

Install with pip install xarray-regrid[spherical]. spherely ships pre-built wheels on PyPI for macOS / Linux x86_64 / Windows (Python 3.10–3.14), so no C library build needed for typical users. If spherely isn't installed, manifold="s2" raises ImportError with a clear install hint; the rest of the module keeps working.

Stacks on #70

This PR targets main because GitHub doesn't support cross-fork PRs with non-main bases, but the real delta vs #70 is small. Useful views:

• Stacked delta (review this): thodson-usgs/xarray-regrid@conservative...spherely-integration
  — 5 files changed, ~550 additions, ~100 deletions
• Full diff vs main: this PR
• Add conservative_2d: conservative regrid for grids that aren't 1D-separable #70 must land first

Design notes

• spherely bridging: _Grid gets an optional s2_polys: np.ndarray | None field. When both source and target carry s2_polys, _build_intersection_areas routes through spherely.intersection + spherely.area (both vectorized ufuncs) instead of planar shapely. The shapely STRtree on planar bboxes remains as the candidate-pair filter — necessary because spherely has no spatial index yet (tracked upstream at benbovy/spherely#72). Planar bboxes are a lossless over-estimate of spherical overlap, so the coarse filter is safe.
• Manifold = Literal["planar", "cea", "s2"] type alias on public signatures; runtime _check_manifold retained for defense on deserialization paths (e.g. loading a netCDF file with a corrupted attribute).
• Vectorized polygon construction fast-path: _s2_cell_polys checks hasattr(spherely, "polygons") and uses the batched ufunc when available. Upstream PR benbovy/spherely#52 (draft on my fork) adds this — measured ~2× speedup on construction, not blocking.
• Schema version bump 1 → 2 on the persisted netCDF format (since spherical: bool became manifold: str on RegridderMetadata). Old files raise a clear schema-mismatch error.

Optional dependency layout

The spherical extra builds on top of conservative_2d:

conservative_2d = ["shapely>=2.0", "h5netcdf"]
spherical = ["xarray-regrid[conservative_2d]", "spherely>=0.1.1"]

Users can install either independently:

• pip install xarray-regrid[conservative_2d] — 2D regrid without s2
• pip install xarray-regrid[spherical] — full s2 support (transitively pulls the 2d stack)

Performance

s2 grid construction dominates one-time build cost. Measurements on benbovy/spherely vectorized-polygons branch (not yet released):

cells	scalar (0.1.1)	vectorized (polygons())
16,200	0.85s	0.56s
1,036,800	~50s (extrapolated)	~30s

Smaller than my original 10-50× forecast because the s2geometry polygon construction itself is the floor; the vectorized ufunc only eliminates pybind11 per-call overhead. Details in docs/spherical_performance_plan.md (not included in this PR — in the repo as uncommitted scratch).

Apply-path cost is negligible; spherical weight matrix is ~ same size as planar.

Test plan

• Correctness: manifold="s2" on a constant field roundtrips to the constant at machine precision.
• Conservation: out · a_dst = A · s to 1e-12 on a random field with the s2 area matrix.
• Pole-touching cells (outer lat edges at ±90°): the oriented=True s2 path picks the correct cap orientation — regression-tested.
• Manifold enum rejection: manifold="bogus" raises ValueError at construction and again in _from_state for loaded files.
• Install hint: manifold="s2" without spherely raises ImportError with the pip install xarray-regrid[spherical] hint.
• netCDF save/load preserves the manifold choice; manifold="s2" survives roundtrip.
• 105 tests pass on the branch (100 from conservative + 5 new s2-specific tests).

Docs

Fourth demo notebook docs/notebooks/demos/demo_conservative_2d_spherical.ipynb, structured to match the other three in the conservative_2d family:

• Intro + three-manifold menu + install hint
• cos²(lat) source on a 1° grid
• All three manifolds integrated against analytic truth (8π/3)
• Spatial s2 − cea diff map on a coarse grid (where great-circle vs straight-line edges diverge most)
• .to_netcdf / .from_netcdf roundtrip preserving the manifold choice

Follow-ups (out of scope)

• Curvilinear s2 (2D lat/lon coord arrays): not supported yet. Trivial extension once spherely ships a spatial index (so we can drop the shapely STRtree bridge that currently requires planar bboxes).
• Antimeridian-crossing rectilinear cells: s2 handles these correctly (the oriented=True orientation is unambiguous), but the shapely planar bbox used for candidate filtering doesn't. A small lon-wrap fix would plug the gap; not critical for typical global grids.
• Upstream contributions:
  • benbovy/spherely#52 — vectorized spherely.polygons(...) constructor. Draft branch exists; would give ~2× on build.
  • benbovy/spherely#72 — s2 spatial index. Larger contribution; would let us drop the shapely bridge entirely.

🤖 Generated with Claude Code