Metadata-Version: 2.5
Name: spharmgrid
Version: 0.4.0
Summary: Spherical harmonic tools for filtering, regridding, and kinematics in atmospheric science with Xarray, JAX, 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>=2025.1.1
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.1; extra == 'cli'
Requires-Dist: zarr>=3.0.0; extra == 'cli'
Provides-Extra: dask
Requires-Dist: dask[array]>=2024.1.0; extra == 'dask'
Provides-Extra: jax
Requires-Dist: jax>=0.5.0; extra == 'jax'
Requires-Dist: s2fft==1.4.0; extra == 'jax'
Provides-Extra: torch
Requires-Dist: torch-harmonics==0.6.5; extra == 'torch'
Requires-Dist: torch>=2.13.0; extra == 'torch'
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 Python Version](https://img.shields.io/pypi/pyversions/spharmgrid)](https://pypi.org/project/spharmgrid/)
[![PyPI version](https://img.shields.io/pypi/v/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, JAX, and PyTorch.

**spharmgrid** (**sp**herical **harm**onic **grid**ding) implements spherical harmonic
filtering, regridding, differential operators, and atmospheric kinematics for global
Xarray fields, JAX arrays, and PyTorch tensors. It computes relative vorticity,
divergence, streamfunction, velocity potential, Helmholtz decomposition, and inverse
wind transforms. The Xarray API uses [DUCC](https://gitlab.mpcdf.mpg.de/mtr/ducc)
(`ducc0`) for spherical harmonic transforms; the optional JAX API uses
[S2FFT](https://github.com/astro-informatics/s2fft), and 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 extras are:

- `spharmgrid[dask]` — Dask-backed lazy execution;
- `spharmgrid[cf]` — optional `cf-xarray` coordinate discovery;
- `spharmgrid[cli]` — command-line NetCDF, Zarr, and GRIB I/O;
- `spharmgrid[jax]` — JAX arrays and S2FFT transforms;
- `spharmgrid[torch]` — PyTorch tensors and torch-harmonics transforms.

The `spharmgrid.jax` API requires JAX and S2FFT. See the
[JAX API documentation](https://spharmgrid.readthedocs.io/en/latest/jax.html) for
supported GL and CC/MWSS dimensions, x64 and dtype requirements, and examples. For CPU
use, `spharmgrid[jax]` installs JAX and S2FFT. For GPU or TPU use, install the
appropriate JAX accelerator build first by following the
[official JAX installation instructions](https://docs.jax.dev/en/latest/installation.html),
then install `spharmgrid[jax]`; spharmgrid does not bundle or select CUDA or TPU builds.
The JAX API currently requires JAX x64 mode and `float64` spatial inputs; it does not
enable x64 globally.

The `spharmgrid.torch` API can be installed with `spharmgrid[torch]`. 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")
```

For workflows with several spectral operations, analyze once and reuse the private
coefficient representation:

```python
spectral = field.sg.analyze()
large_scale = spectral.filter("T5-42").synthesize()
laplacian = spectral.laplacian().synthesize()
```

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 JAX workflows, configure JAX x64 mode before creating arrays and use
`spharmgrid.jax`:

```python
import jax

jax.config.update("jax_enable_x64", True)

import jax.numpy as jnp
import spharmgrid as sg
import spharmgrid.jax as sgj

grid = sg.gaussian_grid(64, 127)
field = jnp.ones((grid.nlat, grid.nlon))
filtered = sgj.filter(field, grid=grid, truncation="T42")
```

The last two array dimensions are latitude and longitude.

For differentiable PyTorch workflows, install `spharmgrid[torch]` and 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).
