Add conservative_2d: conservative regrid for grids that aren't 1D-separable

.gitignore

@@ -4,7 +4,7 @@
 .ipynb_checkpoints
 .mypy_cache
 .ruff_cache
-.venv
+.venv*
 
 build
 dist
@@ -20,10 +20,11 @@ coverage.xml
 docs/_build
 docs/generated
 
-# ide
+# ide / agent tooling
 .idea
 .eclipse
 .vscode
+.claude
 
 # Mac
 .DS_Store

CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## Unreleased
+
+Added:
+ - `conservative_2d` regridding for grids that aren't 1D-separable: curvilinear (2D `lat`/`lon`) grids, unstructured meshes (`ConservativeRegridder.from_polygons`), and grid-to-polygon aggregation (e.g. gridded data → region shapes). Built on shapely 2 polygon intersection with optional `sparse` weight storage, an analytic cylindrical-equal-area `manifold="cea"` option for spherical areas on lat/lon grids, antimeridian handling, and netCDF weight-matrix caching. Exposed via the `.regrid.conservative_2d` accessor and the reusable `ConservativeRegridder` class; install with the `conservative-2d` extra ([#70](https://github.com/xarray-contrib/xarray-regrid/pull/70)).
+
 ## 0.4.2 (2026-01-28)
 
 New contributors:

README.md

@@ -3,10 +3,11 @@
 <img align="right" width="100" alt="Logo" src="./docs/assets/logo.png">
 
 
-With xarray-regrid it is possible to regrid between two rectilinear grids. The following methods are supported:
+With xarray-regrid you can regrid between rectilinear grids, and conservatively onto curvilinear grids, unstructured meshes, or arbitrary polygons (e.g. country shapes). The following methods are supported:
  - Linear
  - Nearest-neighbor
  - Conservative
+ - Conservative 2D: conservative regridding for grids that aren't 1D-separable — curvilinear coordinates, unstructured meshes, and grid-to-polygon aggregation
  - Cubic
  - "Most common value", as well as other zonal statistics (e.g., variance or median).
 
@@ -44,6 +45,12 @@ which includes optional extras such as:
 
 Benchmarking varies across different hardware specifications, but the inclusion of these extras can often provide significant speedups.
 
+For conservative regridding onto curvilinear grids, unstructured meshes, or polygons (the `conservative_2d` method), install the `conservative-2d` extra:
+```console
+pip install xarray-regrid[conservative-2d]
+```
+which adds `shapely`, `sparse`, and `h5netcdf` (the last for caching weight matrices to netCDF).
+
 ## Usage
 The xarray-regrid routines are accessed using the "regrid" accessor on an xarray Dataset:
 ```py

docs/getting_started.rst

@@ -29,9 +29,10 @@ Next load in the data you want to regrid, and the data with a grid you want to r
 Multiple regridding methods are available:
 
 * `linear interpolation <autoapi/xarray_regrid/regrid/index.html#xarray_regrid.regrid.Regridder.linear>`_ (``.regrid.linear``)
-* `nearest-neighbor <autoapi/xarray_regrid/regrid/index.html#xarray_regrid.regrid.Regridder.conservative>`_ (``.regrid.nearest``)
+* `nearest-neighbor <autoapi/xarray_regrid/regrid/index.html#xarray_regrid.regrid.Regridder.nearest>`_ (``.regrid.nearest``)
 * `cubic interpolation  <autoapi/xarray_regrid/regrid/index.html#xarray_regrid.regrid.Regridder.cubic>`_ (``.regrid.cubic``)
 * `conservative regridding <autoapi/xarray_regrid/regrid/index.html#xarray_regrid.regrid.Regridder.conservative>`_ (``.regrid.conservative``)
+* `conservative 2D regridding <autoapi/xarray_regrid/regrid/index.html#xarray_regrid.regrid.Regridder.conservative_2d>`_ (``.regrid.conservative_2d``) for curvilinear grids, unstructured meshes, and grid-to-polygon aggregation
 * `zonal statistics <autoapi/xarray_regrid/regrid/index.html#xarray_regrid.regrid.Regridder.stat>`_ (``.regrid.stat``) is available to compute statistics such as the maximum value, or variance. 
 
 Additionally, there are separate methods available to compute the

docs/index.rst

@@ -29,13 +29,14 @@ xarray-regrid: Regridding utilities for xarray
 Overview
 ========
 
-``xarray-regrid`` extends xarray with regridding methods, making it possibly to easily and effiently regrid between two rectilinear grids. 
+``xarray-regrid`` extends xarray with regridding methods, making it easy and efficient to regrid between rectilinear grids — and, with the conservative 2D method, onto curvilinear grids, unstructured meshes, or arbitrary polygons.
 
 The following methods are supported:
 
 * `Linear <autoapi/xarray_regrid/regrid/index.html#xarray_regrid.regrid.Regridder.linear>`_
 * `Nearest-neighbor <autoapi/xarray_regrid/regrid/index.html#xarray_regrid.regrid.Regridder.nearest>`_
 * `Conservative <autoapi/xarray_regrid/regrid/index.html#xarray_regrid.regrid.Regridder.conservative>`_
+* `Conservative 2D (curvilinear / unstructured / polygon aggregation) <autoapi/xarray_regrid/regrid/index.html#xarray_regrid.regrid.Regridder.conservative_2d>`_
 * `Cubic <autoapi/xarray_regrid/regrid/index.html#xarray_regrid.regrid.Regridder.cubic>`_
 * `Zonal statistics <autoapi/xarray_regrid/regrid/index.html#xarray_regrid.regrid.Regridder.stat>`_
 * `"Most common value" (zonal statistics) <autoapi/xarray_regrid/regrid/index.html#xarray_regrid.regrid.Regridder.most_common>`_