spharmgrid

Spherical harmonic tools for filtering, regridding, and kinematics in atmospheric science with Xarray and PyTorch.

spharmgrid (spherical harmonic gridding) implements spherical harmonic filtering, regridding, differential operators, and atmospheric kinematics for global Xarray fields and PyTorch tensors. It computes relative vorticity, divergence, streamfunction, velocity potential, Helmholtz decomposition, and inverse wind transforms. The Xarray/NumPy API uses DUCC (ducc0) for spherical harmonic transforms; the optional PyTorch API uses torch-harmonics.

Supported grids are full rectangular Gauss–Legendre (GL) and Clenshaw–Curtis (CC) grids.

Install

Install with either pip, uv, or conda:

pip install spharmgrid

uv add spharmgrid

conda install -c conda-forge spharmgrid

Optional groups are:

• spharmgrid[dask] — Dask-backed lazy execution;
• spharmgrid[cf] — optional cf-xarray coordinate discovery;
• spharmgrid[cli] — command-line NetCDF, Zarr, and GRIB I/O.

The spharmgrid.torch API requires PyTorch and torch-harmonics. See the PyTorch API documentation for installation instructions.

Install spharmgrid[cli,dask] to use the transforming CLI commands.

For a standalone command-line installation:

uv tool install "spharmgrid[cli,dask]"

For a project environment, install the CLI and Dask extras with either:

uv add "spharmgrid[cli,dask]"

pip install "spharmgrid[cli,dask]"

Quick start

Importing spharmgrid registers the .sg accessor on Xarray objects. This example applies a T6–42 spectral filter to a DataArray:

import xarray as xr
import spharmgrid

field = xr.open_dataarray("msl.nc")
filtered = field.sg.filter("T6-42")

See the Quick start for regridding, atmospheric wind diagnostics, direct-function equivalents, and further examples.

For differentiable PyTorch workflows, install PyTorch and torch-harmonics, then use spharmgrid.torch:

import torch
import spharmgrid as sg
import spharmgrid.torch as sgt

grid = sg.gaussian_grid(64, 128)
field = torch.randn(grid.nlat, grid.nlon)
filtered = sgt.filter(field, grid=grid, truncation="T42")

See the PyTorch API documentation for tensor dimensions, reusable torch.nn modules, device/autograd behavior, and PyTorch bandwidth limits.

Documentation

The optional CLI reads NetCDF, Zarr, and GRIB and writes NetCDF and Zarr. See the CLI documentation for installation and usage.

See the full documentation for grid requirements, coordinate handling, CF metadata, atmospheric kinematics, inverse transforms, zero-mode conventions, and command-line use.

Citation

If you use spharmgrid in research, please cite the software release DOI: 10.5281/zenodo.22559210. Citation metadata are also provided in CITATION.cff.

References

See the documentation References for the scientific literature and software cited by spharmgrid.

License

spharmgrid is distributed under the BSD 3-Clause License.