Metadata-Version: 2.5
Name: spharmgrid
Version: 0.1.3
Summary: Spherical harmonic tools for filtering, regridding, and kinematics in atmospheric science with Xarray
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: Albert Yau
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.

**spharmgrid** (**sp**herical **harm**onic **grid**ding) implements spherical harmonic filtering, regridding, differential operators, and atmospheric kinematics for global Xarray fields. It computes relative vorticity, divergence, streamfunction, velocity potential, Helmholtz decomposition, and inverse wind transforms. [DUCC](https://gitlab.mpcdf.mpg.de/mtr/ducc) performs the numerical spherical harmonic transforms.

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.

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.

## 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).
