### Compute grid cell area with xesmf.util.cell_area

Source: https://context7.com/pangeo-data/xesmf/llms.txt

Calculate the area of each grid cell using ESMF's spherical geometry. Specify `earth_radius` to get area in km²; otherwise, units are steradians.

```python
import xesmf as xe

ds = xe.util.grid_global(5, 5)

# Area in steradians (default)
area_sr = xe.util.cell_area(ds)
print(area_sr.attrs["units"])

# Area in km²
area_km2 = xe.util.cell_area(ds, earth_radius=6371.0)
print(area_km2.attrs["units"])
print(area_km2.sum().values)
```

--------------------------------

### Open gridded dataset

Source: https://github.com/pangeo-data/xesmf/blob/master/doc/notebooks/Using_LocStream.ipynb

Load a sample gridded dataset for demonstration.

```python
airtemps = xr.tutorial.open_dataset("air_temperature")
```

--------------------------------

### Parallel Weight Generation with Dask

Source: https://context7.com/pangeo-data/xesmf/llms.txt

Demonstrates how to generate regridding weights in parallel using Dask. This is beneficial for very large output grids that may not fit into memory. The output dataset must be chunked along spatial dimensions for this to work.

```python
import dask.array as da
import numpy as np
import xarray as xr
import xesmf as xe

ds_in = xr.tutorial.open_dataset("air_temperature", chunks={"time": 500})

# Output dataset must be chunked along spatial dimensions for parallel=True
ds_out = xr.tutorial.open_dataset("rasm").chunk({"y": 50, "x": 50})

# Generate weights in parallel using Dask processes
para_regridder = xe.Regridder(ds_in, ds_out, "bilinear", parallel=True)
print(para_regridder)
# Input grid shape:  (25, 53)
# Output grid shape: (205, 275)
```

--------------------------------

### Basic Regridding with xesmf

Source: https://context7.com/pangeo-data/xesmf/llms.txt

Demonstrates a basic regridding operation using xesmf. It shows how to define input and output datasets, create a regridder, and perform the regridding. The output shows the lazy dask graph and the shape of the computed result.

```python
ds_out = xr.Dataset({
    "lat": (["lat"], np.arange(16, 75, 1.0)),
    "lon": (["lon"], np.arange(200, 330, 1.5)),
})

regridder = xe.Regridder(ds, ds_out, "bilinear")

# Build lazy dask graph (very fast)
ds_regridded = regridder(ds)
print(ds_regridded["air"].data)
# dask.array<...> shape=(2920, 59, 87) chunksize=(500, 59, 87)

# Trigger actual computation
result = ds_regridded["air"].compute()
print(result.shape)  # (2920, 59, 87)
```

--------------------------------

### Parallel Weight Generation with 1D Output Grids

Source: https://context7.com/pangeo-data/xesmf/llms.txt

Shows how to enable parallel weight generation when the output grid is 1D. This requires adding a boolean mask to the output dataset to facilitate chunking.

```python
# For 1D-coordinate output grids with no variables, add a boolean mask to enable chunking
ds_out_1d = xr.Dataset({
    "lat": (["lat"], np.arange(16, 75, 1.0), {"units": "degrees_north"}),
    "lon": (["lon"], np.arange(200, 330, 1.5), {"units": "degrees_east"}),
})
mask = da.ones((ds_out_1d.lat.size, ds_out_1d.lon.size), dtype=bool, chunks=(25, 25))
ds_out_1d["mask"] = (ds_out_1d.dims, mask)

para_regridder2 = xe.Regridder(ds_in, ds_out_1d, "bilinear", parallel=True)
result = para_regridder2(ds_in["air"]).compute()
```

--------------------------------

### Generate tripolar ocean grid with xesmf.util.simple_tripolar_grid

Source: https://context7.com/pangeo-data/xesmf/llms.txt

Create a simple tripolar grid suitable for ocean models. It features a bipolar cap north of `lat_cap` and a regular grid to the south. Can be used as input for regridding.

```python
import xesmf as xe

# 360 x 180 tripolar grid with bipolar cap north of 60°N
lon, lat = xe.util.simple_tripolar_grid(360, 180, lat_cap=60, lon_cut=-300)
print(lon.shape)
print(lat.shape)

# Use as input grid for regridding from ocean model output
import xarray as xr
ds_ocean = xr.Dataset(
    coords={"lon": (["y", "x"], lon), "lat": (["y", "x"], lat)}
)
ds_out = xe.util.grid_global(1, 1)
regridder = xe.Regridder(ds_ocean, ds_out, "bilinear")
```

--------------------------------

### Loading and Applying Saved Weights

Source: https://github.com/pangeo-data/xesmf/blob/master/doc/notebooks/Reuse_regridder.ipynb

Load previously saved regridder weights from a NetCDF file and apply them to new data. This process is significantly faster than recomputing weights.

```python
regridder2 = xe.Regridder(ds_in, ds_out, 'bilinear', weights=fn)
```

--------------------------------

### xe.util.grid_global — Create a global rectilinear grid

Source: https://context7.com/pangeo-data/xesmf/llms.txt

Details on how to use `xe.util.grid_global` to generate global 2D rectilinear grids, including options for bounds and CF-compliance.

```APIDOC
## `xe.util.grid_global` — Create a global rectilinear grid

Generates a global 2D rectilinear grid with cell centers and optional corner coordinates for conservative regridding.

```python
import xesmf as xe

# Global grid at 2° x 2° resolution (with bounds for conservative regridding)
ds = xe.util.grid_global(2, 2)
print(ds)
# Coordinates: lon (y, x), lat (y, x), lon_b (y_b, x_b), lat_b (y_b, x_b)

# Using 0–360 longitude convention
ds_360 = xe.util.grid_global(2, 2, lon1=360)

# CF-compliant version (1D coords with bounds attribute)
ds_cf = xe.util.grid_global(2, 2, cf=True)
print(ds_cf)
# Coordinates: lon(lon), lat(lat), lon_bounds(bound, lon), lat_bounds(bound, lat)
```
```

--------------------------------

### Create global rectilinear grid

Source: https://context7.com/pangeo-data/xesmf/llms.txt

Shows how to generate a global 2D rectilinear grid using `xe.util.grid_global`. Supports standard longitude conventions and CF-compliant output.

```python
import xesmf as xe

# Global grid at 2° x 2° resolution (with bounds for conservative regridding)
ds = xe.util.grid_global(2, 2)
print(ds)

# Using 0–360 longitude convention
ds_360 = xe.util.grid_global(2, 2, lon1=360)

# CF-compliant version (1D coords with bounds attribute)
ds_cf = xe.util.grid_global(2, 2, cf=True)
print(ds_cf)
```

--------------------------------

### Import xarray and xesmf

Source: https://github.com/pangeo-data/xesmf/blob/master/doc/notebooks/Using_LocStream.ipynb

Import necessary libraries for data manipulation and remapping.

```python
import xarray as xr
import xesmf as xe
```

--------------------------------

### xe.util.simple_tripolar_grid

Source: https://context7.com/pangeo-data/xesmf/llms.txt

Generates a simple tripolar ocean grid with a bipolar cap north of `lat_cap`.

```APIDOC
## `xe.util.simple_tripolar_grid` — Generate a tripolar ocean grid

Generates a simple tripolar grid with a bipolar cap north of `lat_cap` and a regular grid south of it, representative of many ocean model grids.

```python
import xesmf as xe

# 360 x 180 tripolar grid with bipolar cap north of 60°N
lon, lat = xe.util.simple_tripolar_grid(360, 180, lat_cap=60, lon_cut=-300)
print(lon.shape)   # (180, 360)
print(lat.shape)   # (180, 360)

# Use as input grid for regridding from ocean model output
import xarray as xr
ds_ocean = xr.Dataset(
    coords={"lon": (["y", "x"], lon), "lat": (["y", "x"], lat)}
)
ds_out = xe.util.grid_global(1, 1)
regridder = xe.Regridder(ds_ocean, ds_out, "bilinear")
```
```

--------------------------------

### Create input grid

Source: https://github.com/pangeo-data/xesmf/blob/master/doc/notebooks/Reuse_regridder.ipynb

Generates a 2D input grid using xesmf.util.grid_2d with specified longitude and latitude ranges and resolutions.

```python
ds_in = xe.util.grid_2d(
    -120, 120, 0.4, -60, 60, 0.3  # longitude range and resolution
)  # latitude range and resolution
ds_in
```

--------------------------------

### Regridding to Scattered Points (LocStream Output)

Source: https://context7.com/pangeo-data/xesmf/llms.txt

Demonstrates regridding from a regular grid to a set of scattered observation locations. This is achieved by setting `locstream_out=True` and providing an output dataset with 1D `lon`/`lat` arrays. Supported methods include `bilinear`, `patch`, `nearest_s2d`, and `nearest_d2s`.

```python
import xarray as xr
import xesmf as xe

# Input: regular grid
ds_in = xe.util.grid_global(20, 12)
ds_in["data"] = xe.data.wave_smooth(ds_in["lon"], ds_in["lat"])

# Output: scattered observation locations
import xarray as xr
ds_locs = xr.Dataset()
ds_locs["lat"] = xr.DataArray([-20.0, -10.0, 0.0, 10.0], dims=("locations",))
ds_locs["lon"] = xr.DataArray([  0.0,   5.0, 10.0, 15.0], dims=("locations",))

# Build regridder with locstream output
regridder = xe.Regridder(ds_in, ds_locs, "bilinear", locstream_out=True)
print(regridder.shape_out)   # (1, 4)

# Apply — returns DataArray with 'locations' dimension
out = regridder(ds_in["data"])
print(out.shape)   # (4,)
print(out.dims)    # ('locations',)
```

--------------------------------

### Visualizing Weight Matrix Sparsity

Source: https://github.com/pangeo-data/xesmf/blob/master/doc/notebooks/Reuse_regridder.ipynb

Use matplotlib to visualize the sparsity pattern of the regridder weights matrix. This helps understand how source and destination grid points interact.

```python
plt.spy(regridder.weights)
plt.xlabel("input grid indices")
plt.ylabel("output grid indices")
```

--------------------------------

### Create regional 2D grid

Source: https://context7.com/pangeo-data/xesmf/llms.txt

Demonstrates creating a regional 2D rectilinear grid with cell centers and bounds using `xe.util.grid_2d`. Useful for specifying input or output grids for regridding.

```python
import xesmf as xe

# Regional grid: lon from -30 to 30 at 1° resolution, lat from -20 to 20 at 1°
ds = xe.util.grid_2d(-30, 30, 1.0, -20, 20, 1.0)
print(ds)
```

--------------------------------

### xe.Regridder - Extrapolation methods

Source: https://context7.com/pangeo-data/xesmf/llms.txt

Demonstrates how to use `xe.Regridder` with different extrapolation methods like 'inverse_dist' and 'creep_fill' to handle cells outside the source grid domain.

```APIDOC
## `xe.Regridder` — Extrapolation methods

After weight generation, ESMF's extrapolation methods can fill target cells that fall outside the source grid domain using `extrap_method`.

```python
import numpy as np
import xarray as xr
import xesmf as xe

ds_in = xe.util.grid_global(20, 12)
ds_in["data"] = xe.data.wave_smooth(ds_in["lon"], ds_in["lat"])
ds_out = xe.util.grid_global(5, 4)

# Inverse-distance weighted extrapolation
regridder_idw = xe.Regridder(
    ds_in, ds_out, "bilinear",
    extrap_method="inverse_dist",
    extrap_dist_exponent=2.0,
    extrap_num_src_pnts=8,
)
dr_extrap = regridder_idw(ds_in["data"])

# Creep-fill extrapolation: iteratively fills unmapped cells from neighbors
regridder_creep = xe.Regridder(
    ds_in, ds_out, "bilinear",
    extrap_method="creep_fill",
    extrap_num_levels=4,   # number of fill iterations (required for creep_fill)
)
dr_creep = regridder_creep(ds_in["data"])
```
```

--------------------------------

### Create Regridder for LocStream output

Source: https://github.com/pangeo-data/xesmf/blob/master/doc/notebooks/Using_LocStream.ipynb

Initialize a Regridder to map data from a grid to a LocStream. Set `locstream_out=True`.

```python
regridder = xe.Regridder(airtemps, ds_locs, "bilinear", locstream_out=True)
```

--------------------------------

### Apply post-masking for regional grids

Source: https://context7.com/pangeo-data/xesmf/llms.txt

Shows how to use `post_mask_source='domain_edge'` with regional grids and `nearest_s2d` to avoid extrapolation issues at the boundaries.

```python
import xesmf as xe
ds_regional = xe.util.grid_2d(-30, 30, 1, -20, 20, 1)
ds_regional["data"] = xe.data.wave_smooth(ds_regional["lon"], ds_regional["lat"])
regridder_edge = xe.Regridder(
    ds_regional,
    ds_out, "nearest_s2d", post_mask_source="domain_edge"
)
dr_masked = regridder_edge(ds_regional["data"])
```

--------------------------------

### Inspect regridder object

Source: https://github.com/pangeo-data/xesmf/blob/master/doc/notebooks/Reuse_regridder.ipynb

Displays information about the created regridder object, including the algorithm, grid shapes, and periodicity.

```python
regridder
```

--------------------------------

### Create output grid

Source: https://github.com/pangeo-data/xesmf/blob/master/doc/notebooks/Reuse_regridder.ipynb

Generates a 2D output grid using xesmf.util.grid_2d with different longitude and latitude ranges and resolutions.

```python
ds_out = xe.util.grid_2d(-120, 120, 0.6, -60, 60, 0.4)
ds_out
```

--------------------------------

### xe.util.grid_2d — Create a regional 2D grid

Source: https://context7.com/pangeo-data/xesmf/llms.txt

Documentation for `xe.util.grid_2d` which creates regional 2D rectilinear grids with cell centers and bounds.

```APIDOC
## `xe.util.grid_2d` — Create a regional 2D grid

Creates an xarray Dataset describing a regional 2D rectilinear grid with cell centers and cell-corner bounds, ready for use as input/output grid specification.

```python
import xesmf as xe

# Regional grid: lon from -30 to 30 at 1° resolution, lat from -20 to 20 at 1°
ds = xe.util.grid_2d(-30, 30, 1.0, -20, 20, 1.0)
print(ds)
```
```

--------------------------------

### Initialize SpatialAverager

Source: https://github.com/pangeo-data/xesmf/blob/master/doc/notebooks/Spatial_Averaging.ipynb

Instantiate SpatialAverager with input data, geometries, and a dimension name for the output. Weights are computed and stored, with an option to reuse them if available.

```python
savg = xe.SpatialAverager(ds, regs.geometry, geom_dim_name="country")
savg
```

--------------------------------

### xe.util.cf_grid_2d

Source: https://context7.com/pangeo-data/xesmf/llms.txt

Creates a CF-compliant 2D grid Dataset with 1D coordinates and bounds attributes.

```APIDOC
## `xe.util.cf_grid_2d` — Create a CF-compliant 2D grid

Like `grid_2d` but returns a CF-compliant Dataset with 1D coordinates and `bounds` attributes understood by `cf-xarray`.

```python
import xesmf as xe

ds = xe.util.cf_grid_2d(-180, 180, 2.0, -90, 90, 2.0)
print(ds)
# Coordinates: lon(lon), lat(lat), lon_bounds(bound, lon), lat_bounds(bound, lat)
# lon.attrs['bounds'] == 'lon_bounds'
```
```

--------------------------------

### Reusing Pre-computed Regridding Weights

Source: https://context7.com/pangeo-data/xesmf/llms.txt

Explains how to save regridding weights to a NetCDF file and reload them for subsequent runs, significantly speeding up the process by avoiding recomputation. It also shows how to access the weights as a sparse DataArray and reshape them for inspection.

```python
import numpy as np
import xarray as xr
import xesmf as xe

ds = xr.tutorial.open_dataset("air_temperature")
ds_out = xr.Dataset({
    "lat": (["lat"], np.arange(16, 75, 1.0), {"units": "degrees_north"}),
    "lon": (["lon"], np.arange(200, 330, 1.5), {"units": "degrees_east"}),
})

# First run: compute and save weights
regridder = xe.Regridder(ds, ds_out, "bilinear", filename="weights_bilinear.nc")
regridder.to_netcdf("weights_bilinear.nc")   # also saves automatically if filename given

# Subsequent runs: load saved weights (very fast)
regridder_reuse = xe.Regridder(
    ds, ds_out, "bilinear",
    weights="weights_bilinear.nc",
    reuse_weights=True
)
dr_out = regridder_reuse(ds["air"])

# Weights are also accessible as a sparse DataArray
print(regridder.weights)        # xr.DataArray backed by sparse.COO (out_dim, in_dim)

# Reshape weights to 4D for inspection: (y_out, x_out, y_in, x_in)
w4d = regridder.w
print(w4d.dims)    # ('y_out', 'x_out', 'y_in', 'x_in')
```

--------------------------------

### Checking Saved Weights File Size

Source: https://github.com/pangeo-data/xesmf/blob/master/doc/notebooks/Reuse_regridder.ipynb

Use the `du` command to check the disk space occupied by the saved weights file. Due to sparsity, these files are usually small.

```bash
du -sh bilinear_400x600_300x400.nc
```

--------------------------------

### Inverse-distance weighted extrapolation

Source: https://context7.com/pangeo-data/xesmf/llms.txt

Demonstrates inverse-distance weighted extrapolation for filling cells outside the source grid domain. Requires specifying `extrap_method`, `extrap_dist_exponent`, and `extrap_num_src_pnts`.

```python
import numpy as np
import xarray as xr
import xesmf as xe

ds_in = xe.util.grid_global(20, 12)
ds_in["data"] = xe.data.wave_smooth(ds_in["lon"], ds_in["lat"])
ds_out = xe.util.grid_global(5, 4)

# Inverse-distance weighted extrapolation
regridder_idw = xe.Regridder(
    ds_in, ds_out, "bilinear",
    extrap_method="inverse_dist",
    extrap_dist_exponent=2.0,
    extrap_num_src_pnts=8,
)
dr_extrap = regridder_idw(ds_in["data"])
```

--------------------------------

### Apply source mask and regrid

Source: https://context7.com/pangeo-data/xesmf/llms.txt

Demonstrates adding a source mask to the input dataset and then performing regridding. The `unmapped_to_nan` option ensures cells outside the source domain become NaN.

```python
ds_in["mask"] = xr.where(ds_in["lat"] > -60, 1, 0).astype(int)

ds_out = xe.util.grid_global(10, 6)

# unmapped_to_nan=True: cells outside source domain become NaN instead of 0
regridder = xe.Regridder(ds_in, ds_out, "bilinear", unmapped_to_nan=True)
dr_out = regridder(ds_in["data"])
```

--------------------------------

### Create Regridder for LocStream to LocStream remapping

Source: https://github.com/pangeo-data/xesmf/blob/master/doc/notebooks/Using_LocStream.ipynb

Initialize a Regridder to map data from one LocStream to another. Set both `locstream_in=True` and `locstream_out=True`. Only nearest neighbor methods are available.

```python
regrid_l2l = xe.Regridder(
    ds_locs, ds_locs2, "nearest_s2d", locstream_in=True, locstream_out=True
)
```

--------------------------------

### Regridding with Output Chunking

Source: https://context7.com/pangeo-data/xesmf/llms.txt

Shows how to override spatial output chunk sizes during regridding. This is useful for managing memory when dealing with large output datasets.

```python
# Override spatial output chunk sizes
ds_spatially_chunked = ds.chunk({"time": 3, "lat": 10, "lon": 10})
ds_out_chunked = regridder(ds_spatially_chunked, output_chunks={\"lat\": 10, \"lon\": 10})
print(ds_out_chunked["air"].data)
# dask.array<...> chunksize=(3, 10, 10)
```

--------------------------------

### Create bilinear regridder

Source: https://github.com/pangeo-data/xesmf/blob/master/doc/notebooks/Reuse_regridder.ipynb

Creates a bilinear regridder object from the input to the output grid. This operation can be computationally expensive.

```python
%%time
regridder = xe.Regridder(ds_in, ds_out, 'bilinear')
```

--------------------------------

### Create synthetic global data

Source: https://github.com/pangeo-data/xesmf/blob/master/doc/notebooks/Spatial_Averaging.ipynb

Generates a synthetic global dataset with a 'field' variable using xesmf's utility functions for creating a grid and a smooth wave pattern.

```python
# Create synthetic global data
ds = xe.util.grid_global(2, 2)
ds = ds.assign(field=xe.data.wave_smooth(ds.lon, ds.lat))
ds
```

--------------------------------

### Create CF-compliant 2D grid with xesmf.util.cf_grid_2d

Source: https://context7.com/pangeo-data/xesmf/llms.txt

Use `cf_grid_2d` to create a CF-compliant Dataset for a 2D grid. It returns 1D coordinates and `bounds` attributes compatible with cf-xarray.

```python
import xesmf as xe

ds = xe.util.cf_grid_2d(-180, 180, 2.0, -90, 90, 2.0)
print(ds)
# Coordinates: lon(lon), lat(lat), lon_bounds(bound, lon), lat_bounds(bound, lat)
# lon.attrs['bounds'] == 'lon_bounds'
```

--------------------------------

### xesmf.util Module

Source: https://github.com/pangeo-data/xesmf/blob/master/doc/user_api.rst

Utility functions for XESMF, including functions for grid manipulation and file handling.

```APIDOC
## xesmf.util

### Description

This module contains utility functions that can be helpful when working with XESMF, such as creating grids and managing weights.

### Members

- `add_dims(ds, dims)`: Adds dimensions to a Dataset.
- `get_corners(ds, **kwargs)`: Computes the corners of grid cells.
- `load_weights(filename, **kwargs)`: Loads regridding weights from a file.
- `save_weights(weights, filename, **kwargs)`: Saves regridding weights to a file.
- `grid_2d(ds, **kwargs)`: Creates a 2D grid from a Dataset.
- `grid_3d(ds, **kwargs)`: Creates a 3D grid from a Dataset.

### Example Usage (Illustrative)

```python
import xesmf as xe
import xarray as xr

# Example of using a utility function (hypothetical)
# ds = xr.Dataset(...)
# weights = xe.util.load_weights('weights.nc')
```
```

--------------------------------

### Create Regridder for LocStream input

Source: https://github.com/pangeo-data/xesmf/blob/master/doc/notebooks/Using_LocStream.ipynb

Initialize a Regridder to map data from a LocStream back to a grid. Set `locstream_in=True`. Only 'nearest_s2d' and 'nearest_d2s' methods are available.

```python
regridder_back_s2d = xe.Regridder(
    airtemps_locs, airtemps, "nearest_s2d", locstream_in=True
)
```

--------------------------------

### Generate output mask from weights with xesmf.smm.gen_mask_from_weights

Source: https://context7.com/pangeo-data/xesmf/llms.txt

Create a binary mask indicating mapped output grid cells. This requires the regridder to be initialized with `unmapped_to_nan=True`. The mask helps identify valid output data.

```python
import xarray as xr
import xesmf as xe

ds_in = xe.util.grid_global(20, 12)
ds_in["data"] = xe.data.wave_smooth(ds_in["lon"], ds_in["lat"])
ds_out = xe.util.grid_global(5, 4)

reg = xe.Regridder(ds_in, ds_out, "bilinear", unmapped_to_nan=True)

# Generate mask: 1 = mapped, 0 = unmapped
mask = xe.smm.gen_mask_from_weights(reg.weights, *reg.shape_out)

# Wrap in a DataArray with proper coordinates
mask_da = xr.DataArray(mask, dims=reg.out_horiz_dims, coords=reg.out_coords.coords)
print(mask_da.shape)
print(mask_da.sum().values)
```

--------------------------------

### Verifying Regridding Results

Source: https://github.com/pangeo-data/xesmf/blob/master/doc/notebooks/Reuse_regridder.ipynb

Assert that the output from a regridded field using loaded weights is identical to the output from a freshly computed regridder.

```python
xr.testing.assert_identical(dr_out, dr_out2)  # they are equal
```

--------------------------------

### Saving Regridder Weights to NetCDF

Source: https://github.com/pangeo-data/xesmf/blob/master/doc/notebooks/Reuse_regridder.ipynb

Save the computed regridder weights to a NetCDF file for later reuse. A default filename is used if none is provided.

```python
fn = regridder.to_netcdf()
print(fn)
```

--------------------------------

### Import necessary libraries

Source: https://github.com/pangeo-data/xesmf/blob/master/doc/notebooks/Spatial_Averaging.ipynb

Imports essential libraries for data manipulation, plotting, and spatial operations, including xesmf, geopandas, shapely, and xarray. Sets display options for xarray and filters warnings.

```python
%matplotlib inline
import matplotlib.pyplot as plt
import geopandas as gpd
import pandas as pd
from shapely.geometry import Polygon, MultiPolygon
import numpy as np
import xarray as xr
import xesmf as xe
import warnings

warnings.filterwarnings("ignore")
xr.set_options(display_style='text')
```

--------------------------------

### Save and reload regridding weights with BaseRegridder.to_netcdf

Source: https://context7.com/pangeo-data/xesmf/llms.txt

Save regridding weights to a netCDF file for later reuse. This allows for faster subsequent regridding operations by loading pre-computed weights.

```python
import numpy as np
import xarray as xr
import xesmf as xe

ds = xr.tutorial.open_dataset("air_temperature")
ds_out = xr.Dataset({
    "lat": (["lat"], np.arange(16, 75, 1.0), {"units": "degrees_north"}),
    "lon": (["lon"], np.arange(200, 330, 1.5), {"units": "degrees_east"}),
})

regridder = xe.Regridder(ds, ds_out, "conservative")

# Save weights
saved_path = regridder.to_netcdf("conservative_weights.nc")
print(saved_path)

# Reload on future runs
fast_regridder = xe.Regridder(
    ds, ds_out, "conservative",
    weights="conservative_weights.nc",
    reuse_weights=True,
)
result = fast_regridder(ds["air"])
```

--------------------------------

### Verify Weight Normalization

Source: https://github.com/pangeo-data/xesmf/blob/master/doc/notebooks/Spatial_Averaging.ipynb

Sum the weights along the spatial dimensions ('y', 'x') for each country to confirm that the weights are normalized to 1, ensuring accurate averaging.

```python
w.sum(dim=["y", "x"]).values
```

--------------------------------

### BaseRegridder.to_netcdf

Source: https://context7.com/pangeo-data/xesmf/llms.txt

Saves the regridding weight matrix to a netCDF file for later reloading.

```APIDOC
## `BaseRegridder.to_netcdf` — Save weights to disk

Saves the current regridding weight matrix to a netCDF file in ESMF-compatible format. The file can be reloaded with the `weights=` argument on subsequent calls.

```python
import numpy as np
import xarray as xr
import xesmf as xe

ds = xr.tutorial.open_dataset("air_temperature")
ds_out = xr.Dataset({
    "lat": (["lat"], np.arange(16, 75, 1.0), {"units": "degrees_north"}),
    "lon": (["lon"], np.arange(200, 330, 1.5), {"units": "degrees_east"}),
})

regridder = xe.Regridder(ds, ds_out, "conservative")

# Save weights
saved_path = regridder.to_netcdf("conservative_weights.nc")
print(saved_path)  # 'conservative_weights.nc'

# Reload on future runs
fast_regridder = xe.Regridder(
    ds, ds_out, "conservative",
    weights="conservative_weights.nc",
    reuse_weights=True,
)
result = fast_regridder(ds["air"])
```
```

--------------------------------

### xe.Regridder - Grid-to-grid regridder with numpy arrays / dictionaries

Source: https://context7.com/pangeo-data/xesmf/llms.txt

Creates a regridder object for transforming data between grids when not using xarray. Grids can be specified as plain Python dictionaries of numpy arrays, and the regridder accepts and returns numpy arrays.

```APIDOC
## `xe.Regridder` with numpy arrays / dictionaries

When working without xarray, grids can be specified as plain Python dictionaries of numpy arrays. The regridder accepts numpy arrays as input data and returns numpy arrays. Both rectilinear (1D lon/lat) and curvilinear (2D lon/lat) grids are supported via the same interface.

### Method
```python
regridder = xe.Regridder(grid_in, grid_out, method, **kwargs)
```

### Parameters
- **grid_in**: dict or numpy.ndarray - Input grid specification. For dicts, keys like 'lon', 'lat', 'lon_b', 'lat_b' are expected.
- **grid_out**: dict or numpy.ndarray - Output grid specification. For dicts, keys like 'lon', 'lat', 'lon_b', 'lat_b' are expected.
- **method**: str - Interpolation algorithm (e.g., "bilinear", "conservative").

### Request Example
```python
import numpy as np
import xesmf as xe

# Rectilinear grid as dict (1D arrays)
data = np.arange(20, dtype=float).reshape(4, 5)
grid_in  = {"lon": np.linspace(0, 40, 5),  "lat": np.linspace(0, 20, 4)}
grid_out = {"lon": np.linspace(-20, 60, 51), "lat": np.linspace(-10, 30, 41)}

regridder = xe.Regridder(grid_in, grid_out, "bilinear")
data_out = regridder(data)
print(data_out.shape)  # (41, 51)

# Curvilinear grid with conservative regridding (needs bounds lon_b, lat_b)
lon, lat = np.meshgrid(np.linspace(-20, 20, 5), np.linspace(0, 30, 4))
lon += lat / 3;  lat += lon / 3
lon_b, lat_b = np.meshgrid(np.linspace(-25, 25, 6), np.linspace(-5, 35, 5))
lon_b += lat_b / 3;  lat_b += lon_b / 3

lon_out_b = np.linspace(-30, 40, 36)
lon_out   = 0.5 * (lon_out_b[1:] + lon_out_b[:-1])
lat_out_b = np.linspace(-20, 50, 36)
lat_out   = 0.5 * (lat_out_b[1:] + lat_out_b[:-1])

grid_in  = {"lon": lon,     "lat": lat,     "lon_b": lon_b,     "lat_b": lat_b}
grid_out = {"lon": lon_out, "lat": lat_out, "lon_b": lon_out_b, "lat_b": lat_out_b}

regridder = xe.Regridder(grid_in, grid_out, "conservative")
data_out = regridder(data)
print(data_out.shape)  # (35, 35)
```

### Response
#### Success Response (Regridder object)
- **Regridder object**: An instance of the Regridder class, ready to apply regridding to numpy arrays.

#### Response Example
```
(41, 51)
(35, 35)
```
```

--------------------------------

### Create Regridder using nearest_d2s

Source: https://github.com/pangeo-data/xesmf/blob/master/doc/notebooks/Using_LocStream.ipynb

Initialize a Regridder using the 'nearest_d2s' method for LocStream input. This method maps one destination grid point per LocStream point.

```python
regrid_back_d2s = xe.Regridder(
    airtemps_locs, airtemps, "nearest_d2s", locstream_in=True
)
```

--------------------------------

### Regrid with NaN handling using skipna

Source: https://context7.com/pangeo-data/xesmf/llms.txt

Illustrates regridding data containing NaN values by using the `skipna=True` option. The `na_thres` parameter controls the threshold for considering a cell as valid.

```python
# skipna: ignore NaN values in the input when computing interpolation
dr_with_nans = ds_in["data"].where(ds_in["lat"] > 0)   # NaN south of equator
regridder2 = xe.Regridder(ds_in, ds_out, "bilinear")
dr_skipna = regridder2(dr_with_nans, skipna=True, na_thres=0.5)
```

--------------------------------

### Generate spherical harmonic test field with xesmf.data.wave_smooth

Source: https://context7.com/pangeo-data/xesmf/llms.txt

Create a smooth 2D spherical harmonic test field ($Y_2^2$) for benchmarking regridding algorithms. This synthetic data can be used to test regridding accuracy.

```python
import xesmf as xe

ds = xe.util.grid_global(2, 2)
field = xe.data.wave_smooth(ds["lon"], ds["lat"])
print(field.min().values, field.max().values)

# Use as synthetic data for regridding benchmarks
ds["data"] = field
ds_out = xe.util.grid_global(1, 1)
regridder = xe.Regridder(ds, ds_out, "conservative")
ds_out["data"] = regridder(ds["data"])
```

--------------------------------

### Create and use a regridder with xarray datasets

Source: https://context7.com/pangeo-data/xesmf/llms.txt

Use `xe.Regridder` to create a regridder object for transforming data between grids. Supports bilinear, conservative, and nearest-neighbor methods. The regridder can be applied to xarray DataArrays or Datasets.

```python
import numpy as np
import xarray as xr
import xesmf as xe

# Load an xarray dataset with lat/lon coordinates
ds = xr.tutorial.open_dataset("air_temperature")

# Define the output grid
ds_out = xr.Dataset({
    "lat": (["lat"], np.arange(16, 75, 1.0), {"units": "degrees_north"}),
    "lon": (["lon"], np.arange(200, 330, 1.5), {"units": "degrees_east"}),
})

# Create regridder with bilinear method
regridder = xe.Regridder(ds, ds_out, "bilinear")
print(regridder)
# xESMF Regridder
# Regridding algorithm:       bilinear
# Weight filename:            bilinear_25x53_59x87.nc
# Input grid shape:           (25, 53)
# Output grid shape:          (59, 87)
# Periodic in longitude?      False

# Regrid a DataArray — broadcasts over all extra dims (time here)
dr_out = regridder(ds["air"], keep_attrs=True)
print(dr_out.shape)  # (2920, 59, 87)

# Regrid an entire Dataset at once
ds_out_data = regridder(ds, keep_attrs=True)

# Conservative regridding (requires grid corner / bounds info)
regridder_cons = xe.Regridder(ds, ds_out, "conservative")
dr_cons = regridder_cons(ds["air"])

# Nearest-neighbor regridding with unmapped cells set to NaN
regridder_nn = xe.Regridder(ds, ds_out, "nearest_s2d", unmapped_to_nan=True)
dr_nn = regridder_nn(ds["air"])
```

--------------------------------

### Applying Masks in Regridding

Source: https://context7.com/pangeo-data/xesmf/llms.txt

Illustrates how to use source and target masks with xesmf. It mentions the `unmapped_to_nan` option to set output cells outside the source domain to NaN and `post_mask_source='domain_edge'` to remove edge cells from contributing to interpolation, which is useful for nearest-neighbor methods on regional grids.

```python
import numpy as np
import xarray as xr
import xesmf as xe

ds_in = xe.util.grid_global(20, 12)
ds_in["data"] = xe.data.wave_smooth(ds_in["lon"], ds_in["lat"])

```

--------------------------------

### xe.data.wave_smooth

Source: https://context7.com/pangeo-data/xesmf/llms.txt

Generates a smooth 2D spherical harmonic test field, commonly used for benchmarking regridding algorithms.

```APIDOC
## `xe.data.wave_smooth` — Spherical harmonic test field

Generates a smooth 2D spherical harmonic test field $Y_2^2 = 2 + \cos^2(\theta)\cos(2\phi)$, commonly used to benchmark and validate regridding algorithms.

```python
import xesmf as xe

ds = xe.util.grid_global(2, 2)
field = xe.data.wave_smooth(ds["lon"], ds["lat"])
print(field.min().values, field.max().values)  # ~1.0, ~3.0

# Use as synthetic data for regridding benchmarks
ds["data"] = field
ds_out = xe.util.grid_global(1, 1)
regridder = xe.Regridder(ds, ds_out, "conservative")
ds_out["data"] = regridder(ds["data"])
```
```

--------------------------------

### Load and simplify country outlines

Source: https://github.com/pangeo-data/xesmf/blob/master/doc/notebooks/Spatial_Averaging.ipynb

Loads country boundary data from a URL using geopandas and selects specific countries. Simplifies the geometries to a specified tolerance to improve performance, noting that this may reduce precision.

```python
# Load some polygons from the internet
regs = gpd.read_file(
    "https://cdn.jsdelivr.net/npm/world-atlas@2/countries-10m.json"
)

# Select a few countries for the sake of the example
regs = regs.iloc[[5, 9, 37, 67, 98, 155]]

# Simplify the geometries to a 0.02 deg tolerance, which is 1/100 of our grid.
# The simpler the polygons, the faster the averaging, but we lose some precision.
regs["geometry"] = regs.simplify(tolerance=0.02, preserve_topology=True)
regs
```

--------------------------------

### Add time and level dimensions to input grid

Source: https://github.com/pangeo-data/xesmf/blob/master/doc/notebooks/Reuse_regridder.ipynb

Adds 'time' and 'lev' dimensions to the input dataset and creates a 'data4D' variable by combining time, level, and a 2D wave smooth field.

```python
ds_in.coords["time"] = np.arange(1, 11)
ds_in.coords["lev"] = np.arange(1, 51)
ds_in["data2D"] = xe.data.wave_smooth(ds_in["lon"], ds_in["lat"])
ds_in["data4D"] = ds_in["time"] * ds_in["lev"] * ds_in["data2D"]
ds_in
```

--------------------------------

### Plot gridded data

Source: https://github.com/pangeo-data/xesmf/blob/master/doc/notebooks/Using_LocStream.ipynb

Visualize the gridded data before remapping.

```python
airtemps["air"].isel(time=0).plot(vmin=230, vmax=300)
```

--------------------------------

### Plot reconstructed gridded data

Source: https://github.com/pangeo-data/xesmf/blob/master/doc/notebooks/Using_LocStream.ipynb

Visualize the data after remapping it back to a grid. Note that reconstruction may differ significantly due to undersampling.

```python
airtemps_gridded2["air"].isel(time=0).plot(vmin=230, vmax=300)
```

--------------------------------

### xe.Regridder - Grid-to-grid regridder with xarray

Source: https://context7.com/pangeo-data/xesmf/llms.txt

Creates a regridder object for transforming data between grids using xarray Datasets/DataArrays. The regridder is callable and applies to data with matching horizontal dimensions, automatically broadcasting over extra dimensions.

```APIDOC
## `xe.Regridder` - Grid-to-grid regridder

Creates a regridder object that computes and stores interpolation weights between two grids. Accepts xarray Datasets/DataArrays, plain dictionaries of numpy arrays, or DataArrays as input/output grid specifications. The `method` argument controls the interpolation algorithm. Once created, the regridder is callable and applies to any array with matching horizontal dimensions, broadcasting over extra dimensions like time and level automatically.

### Method
```python
regridder = xe.Regridder(ds_in, ds_out, method, **kwargs)
```

### Parameters
- **ds_in**: xarray.Dataset or xarray.DataArray or dict or numpy.ndarray - Input grid specification.
- **ds_out**: xarray.Dataset or xarray.DataArray or dict or numpy.ndarray - Output grid specification.
- **method**: str - Interpolation algorithm (e.g., "bilinear", "conservative", "nearest_s2d").
- **keep_attrs**: bool, optional - If True, preserve attributes from the input data.
- **unmapped_to_nan**: bool, optional - If True, unmapped cells in nearest-neighbor regridding are set to NaN.

### Request Example
```python
import numpy as np
import xarray as xr
import xesmf as xe

# Load an xarray dataset with lat/lon coordinates
ds = xr.tutorial.open_dataset("air_temperature")

# Define the output grid
ds_out = xr.Dataset({
    "lat": (["lat"], np.arange(16, 75, 1.0), {"units": "degrees_north"}),
    "lon": (["lon"], np.arange(200, 330, 1.5), {"units": "degrees_east"}),
})

# Create regridder with bilinear method
regridder = xe.Regridder(ds, ds_out, "bilinear")
print(regridder)

# Regrid a DataArray — broadcasts over all extra dims (time here)
dr_out = regridder(ds["air"], keep_attrs=True)
print(dr_out.shape)

# Regrid an entire Dataset at once
ds_out_data = regridder(ds, keep_attrs=True)

# Conservative regridding (requires grid corner / bounds info)
regridder_cons = xe.Regridder(ds, ds_out, "conservative")
dr_cons = regridder_cons(ds["air"])

# Nearest-neighbor regridding with unmapped cells set to NaN
regridder_nn = xe.Regridder(ds, ds_out, "nearest_s2d", unmapped_to_nan=True)
dr_nn = regridder_nn(ds["air"])
```

### Response
#### Success Response (Regridder object)
- **Regridder object**: An instance of the Regridder class, ready to apply regridding.

#### Response Example
```
xESMF Regridder
Regridding algorithm:       bilinear
Weight filename:            bilinear_25x53_59x87.nc
Input grid shape:           (25, 53)
Output grid shape:          (59, 87)
Periodic in longitude?      False
```
```

--------------------------------

### Creep-fill extrapolation

Source: https://context7.com/pangeo-data/xesmf/llms.txt

Shows creep-fill extrapolation, an iterative method to fill unmapped cells using neighbor values. Requires `extrap_method='creep_fill'` and `extrap_num_levels`.

```python
import numpy as np
import xarray as xr
import xesmf as xe

ds_in = xe.util.grid_global(20, 12)
ds_in["data"] = xe.data.wave_smooth(ds_in["lon"], ds_in["lat"])
ds_out = xe.util.grid_global(5, 4)

# Creep-fill extrapolation: iteratively fills unmapped cells from neighbors
regridder_creep = xe.Regridder(
    ds_in, ds_out, "bilinear",
    extrap_method="creep_fill",
    extrap_num_levels=4,   # number of fill iterations (required for creep_fill)
)
dr_creep = regridder_creep(ds_in["data"])
```

--------------------------------

### Check size of 4D data

Source: https://github.com/pangeo-data/xesmf/blob/master/doc/notebooks/Reuse_regridder.ipynb

Calculates and prints the size in gigabytes of the 'data4D' variable in the input dataset.

```python
ds_in["data4D"].nbytes / 1e9  # Byte -> GB
```

--------------------------------

### xe.smm.gen_mask_from_weights

Source: https://context7.com/pangeo-data/xesmf/llms.txt

Generates a binary mask identifying output grid cells that are mapped from input weights.

```APIDOC
## `xe.smm.gen_mask_from_weights` — Generate output mask from weights

Generates a binary 2D mask identifying which output grid cells are mapped (have non-NaN weights). Requires the regridder to have been created with `unmapped_to_nan=True`.

```python
import xarray as xr
import xesmf as xe

ds_in = xe.util.grid_global(20, 12)
ds_in["data"] = xe.data.wave_smooth(ds_in["lon"], ds_in["lat"])
ds_out = xe.util.grid_global(5, 4)

reg = xe.Regridder(ds_in, ds_out, "bilinear", unmapped_to_nan=True)

# Generate mask: 1 = mapped, 0 = unmapped
mask = xe.smm.gen_mask_from_weights(reg.weights, *reg.shape_out)

# Wrap in a DataArray with proper coordinates
mask_da = xr.DataArray(mask, dims=reg.out_horiz_dims, coords=reg.out_coords.coords)
print(mask_da.shape)       # (45, 72)
print(mask_da.sum().values)  # number of mapped output cells
```
```

--------------------------------

### Remap grid to LocStream

Source: https://github.com/pangeo-data/xesmf/blob/master/doc/notebooks/Using_LocStream.ipynb

Apply the Regridder to transform gridded data to the LocStream format.

```python
airtemps_locs = regridder(airtemps)
```

--------------------------------

### xesmf.data Module

Source: https://github.com/pangeo-data/xesmf/blob/master/doc/user_api.rst

Module for accessing and managing data related to grids and datasets within XESMF.

```APIDOC
## xesmf.data

### Description

This module provides access to data structures and potentially sample datasets used within XESMF. It might be used for internal data handling or providing example data for testing.

### Members

(Specific members are not detailed in the provided source, but typically would include functions or classes for data loading, manipulation, or access.)

### Example Usage (Hypothetical)

```python
# import xesmf.data
# data_info = xesmf.data.some_data_function()
```
```

--------------------------------

### Apply regridder to data

Source: https://github.com/pangeo-data/xesmf/blob/master/doc/notebooks/Reuse_regridder.ipynb

Applies the previously created regridder object to the 'data4D' variable. This operation is significantly faster than creating the regridder.

```python
%%time
dr_out = regridder(ds_in['data4D'])
```

--------------------------------

### Plot reconstructed gridded data with nearest_d2s

Source: https://github.com/pangeo-data/xesmf/blob/master/doc/notebooks/Using_LocStream.ipynb

Visualize the data after remapping it to a grid using the 'nearest_d2s' method.

```python
airtemps_gridded3["air"].isel(time=0).plot()
```

--------------------------------

### Accessing Regridder Weights

Source: https://github.com/pangeo-data/xesmf/blob/master/doc/notebooks/Reuse_regridder.ipynb

Access the computed weights matrix from an xESMF regridder object. This matrix is typically sparse.

```python
regridder.weights
```

--------------------------------

### Applying Regridding to Data

Source: https://github.com/pangeo-data/xesmf/blob/master/doc/notebooks/Reuse_regridder.ipynb

Apply the regridder to a DataArray. This operation is a fast matrix-vector multiplication once weights are loaded.

```python
dr_out2 = regridder2(ds_in['data4D'])
```

--------------------------------

### Remap LocStream to grid

Source: https://github.com/pangeo-data/xesmf/blob/master/doc/notebooks/Using_LocStream.ipynb

Apply the Regridder to transform LocStream data back to a gridded format.

```python
airtemps_gridded2 = regridder_back_s2d(airtemps_locs)
```