xtorch-harmonics

Spherical harmonic filtering for xarray data, built on NVIDIA's torch-harmonics.

Installation

Can be installed from source. Clone this repository, then:

pip install -e ".[dev]"

Usage

roundtrip_filter transforms gridded data to spherical harmonic space and back, enabling spectral filtering and smoothing. It works with both xr.DataArray and xr.Dataset, and supports Dask arrays for lazy/parallel computation.

import xarray as xr
from xtorch_harmonics import roundtrip_filter

ds = xr.open_dataset("my_data.nc")

# Basic roundtrip filter
filtered = roundtrip_filter(ds, lat_dim="lat", lon_dim="lon")

# Keep only half the spherical harmonic modes
smoothed = roundtrip_filter(ds, lat_dim="lat", lon_dim="lon", fraction_modes_kept=0.5)

Grid types

The forward_grid and inverse_grid parameters control the quadrature scheme:

• "equiangular" — equally spaced latitudes
• "legendre-gauss" (default) — Gauss-Legendre quadrature points
• "lobatto" — Gauss-Lobatto quadrature points

Testing

pytest tests/

History

This small package was split out from the now-archived fv3net repository on March 30th, 2026. The original code can be found here. Future maintenance will occur in this repository.