Metadata-Version: 2.5
Name: spharmgrid
Version: 0.2.0
Summary: Spherical harmonic tools for filtering, regridding, and kinematics in atmospheric science with Xarray and PyTorch
Project-URL: Documentation, https://spharmgrid.readthedocs.io/
Project-URL: Repository, https://github.com/mwyau/spharmgrid
Project-URL: DOI, https://doi.org/10.5281/zenodo.22559210
Author-email: "Albert M. W. Yau" <albert@mwyau.com>
License-Expression: BSD-3-Clause
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Requires-Python: >=3.11
Requires-Dist: ducc0>=0.39.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: xarray>=2024.9.0
Provides-Extra: cf
Requires-Dist: cf-xarray>=0.10.4; extra == 'cf'
Provides-Extra: cli
Requires-Dist: cfgrib>=0.9.15; extra == 'cli'
Requires-Dist: eccodeslib>=2.48.0; (sys_platform != 'win32') and extra == 'cli'
Requires-Dist: h5netcdf[h5py]>=1.8.0; extra == 'cli'
Requires-Dist: zarr>=3.0.0; extra == 'cli'
Provides-Extra: dask
Requires-Dist: dask[array]>=2024.1.0; extra == 'dask'
Description-Content-Type: text/markdown

# spharmgrid

[![CI](https://github.com/mwyau/spharmgrid/actions/workflows/ci.yml/badge.svg)](https://github.com/mwyau/spharmgrid/actions/workflows/ci.yml)
[![Documentation Status](https://readthedocs.org/projects/spharmgrid/badge/?version=latest)](https://spharmgrid.readthedocs.io/en/latest/?badge=latest)
[![codecov](https://codecov.io/github/mwyau/spharmgrid/graph/badge.svg?token=5kDDQ8Ii0Z)](https://codecov.io/github/mwyau/spharmgrid)
[![PyPI version](https://img.shields.io/pypi/v/spharmgrid)](https://pypi.org/project/spharmgrid/)
[![PyPI Python Version](https://img.shields.io/pypi/pyversions/spharmgrid)](https://pypi.org/project/spharmgrid/)
[![Conda Version](https://img.shields.io/conda/vn/conda-forge/spharmgrid)](https://anaconda.org/channels/conda-forge/packages/spharmgrid/overview)
[![GitHub License](https://img.shields.io/github/license/mwyau/spharmgrid)](https://github.com/mwyau/spharmgrid/blob/main/LICENSE)
[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.22559210-blue.svg)](https://doi.org/10.5281/zenodo.22559210)

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

**spharmgrid** (**sp**herical **harm**onic **grid**ding) 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](https://gitlab.mpcdf.mpg.de/mtr/ducc) (`ducc0`) for spherical harmonic transforms; the optional PyTorch API uses [torch-harmonics](https://github.com/NVIDIA/torch-harmonics).

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

## Install

Install with either `pip`, `uv`, or `conda`:

```bash
pip install spharmgrid
```

```bash
uv add spharmgrid
```

```bash
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](https://spharmgrid.readthedocs.io/en/latest/torch.html)
for installation instructions.

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

For a standalone command-line installation:

```bash
uv tool install "spharmgrid[cli,dask]"
```

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

```bash
uv add "spharmgrid[cli,dask]"
```

```bash
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`:

```python
import xarray as xr
import spharmgrid

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

See the [Quick start](https://spharmgrid.readthedocs.io/en/latest/quickstart.html) for regridding, atmospheric wind diagnostics, direct-function equivalents, and further examples.

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

```python
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](https://spharmgrid.readthedocs.io/en/latest/torch.html) 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](https://spharmgrid.readthedocs.io/en/latest/cli.html) for installation and usage.

See the full [documentation](https://spharmgrid.readthedocs.io/) 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](https://doi.org/10.5281/zenodo.22559210). Citation metadata are also provided in [`CITATION.cff`](https://github.com/mwyau/spharmgrid/blob/main/CITATION.cff).

## References

See the documentation [References](https://spharmgrid.readthedocs.io/en/latest/references.html) for the scientific literature and software cited by spharmgrid.

## License

spharmgrid is distributed under the [BSD 3-Clause License](https://github.com/mwyau/spharmgrid/blob/main/LICENSE).
