Metadata-Version: 2.5
Name: spharmgrid
Version: 0.1.0
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
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.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Requires-Python: >=3.12
Requires-Dist: ducc0>=0.39.0
Requires-Dist: numpy>=2.0.0
Requires-Dist: xarray>=2025.11.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.26; (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)
[![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/)
[![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.22546616-blue.svg)](https://doi.org/10.5281/zenodo.22546616)

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 pole-including Clenshaw–Curtis (CC) grids.

## Install

Install with either pip or uv:

```bash
pip install spharmgrid
```

```bash
uv add 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.

Dask-backed transforms execute lazily. DUCC uses four threads per transform. For the local Dask scheduler, spharmgrid sets `num_workers=max(1, os.cpu_count() // 4)` unless `num_workers` is configured.

For a standalone command-line installation:

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

For a project environment, install the CLI extra with either:

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

```bash
pip install "spharmgrid[cli]"
```

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

## 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](LICENSE).
