Skip to content
Back to search

torch-harmonics-skills

SkillWorks with Claude CodeGitHub

Index of project-local Claude Code skills for torch-harmonics. Use this to discover which skills are available for this codebase. Individual skills live in the .skills/ directory at the project root.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/NVIDIA/torch-harmonics with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/NVIDIA/torch-harmonics'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/nvidia--torch-harmonics/badge.svg)](/listings/nvidia--torch-harmonics)

HTML

<a href="/listings/nvidia--torch-harmonics"><img src="/api/listings/nvidia--torch-harmonics/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prebuilt wheels

Prebuilt Linux wheels with compiled CUDA extensions are available on [pypi.nvidia.com](https://pypi.nvidia.com). Pick the package matching your CUDA toolkit version:

| CUDA | Package | Supported PyTorch | Install command | |------|---------|-------------------|-----------------| | 12.6 | `torch-harmonics-cu126` | 2.9.1 | `pip install torch-harmonics-cu126 --extra-index-url https://pypi.nvidia.com` | | 12.8 | `torch-harmonics-cu128` | 2.9.1 | `pip install torch-harmonics-cu128 --extra-index-url https://pypi.nvidia.com` | | 12.9 | `torch-harmonics-cu129` | 2.9.1 | `pip install torch-harmonics-cu129 --extra-index-url https://pypi.nvidia.com` | | 13.0 | `torch-harmonics-cu130` | 2.9.1 | `pip install torch-harmonics-cu130 --extra-index-url https://pypi.nvidia.com` | | 13.2 | `torch-harmonics-cu132` | 2.12.0 | `pip install torch-harmonics-cu132 --extra-index-url https://pypi.nvidia.com` |

If you don't need a specific CUDA version, use the rolling alias for the latest CUDA build:

pip install torch-harmonics-cuda-latest --extra-index-url https://pypi.nvidia.com

For a CPU-only build, install the `torch-harmonics` package from [PyPI](#pypi).

> **Tip:** Run `nvidia-smi` to check your driver's CUDA version.

**Older PyTorch or CUDA** (PyTorch before 2.9, CUDA before 12.6) have no prebuilt wheels. Use the [Docker container](#building-from-source), which brings a matching PyTorch and CUDA, or build torch-harmonics from source against your installed PyTorch, adding `--no-deps` so that pip does not replace it with a newer one (`pip install --no-build-isolation --no-deps .`). These combinations are not tested.

PyPI

The vanilla `torch-harmonics` package on [PyPI](https://pypi.org/project/torch_harmonics/) ships a CPU-only prebuilt wheel. This version is built for the newest PyTorch release. For GPU support, use the NVIDIA PyPI packages above.

pip install torch-harmonics

Building from source

If your OS, PyTorch or CUDA toolkit version is not covered by the available wheels, we recomment building torch-harmonics from the GitHub repository. Use `--no-build-isolation` so that custom CPU and CUDA kernels compile against your existing torch installation:

git clone git@github.com:NVIDIA/torch-harmonics.git
cd torch-harmonics
pip install --no-build-isolation -e .

If CUDA devices are not detected automatically (e.g. inside a container), set the `TORCH_HARMONICS_BUILD_CUDA_EXTENSION` flag. Set `TORCH_CUDA_ARCH_LIST` to only the architectures you need to reduce compilation time:

export TORCH_HARMONICS_BUILD_CUDA_EXTENSION=1
export TORCH_CUDA_ARCH_LIST="8.0 8.6 9.0a 10.0a+PTX"
pip install --no-build-isolation -e .

> **Tip:** Use the `a` suffix (e.g. `9.0a`, `10.0a`) instead of plain `9.0` or `10.0` to enable architecture-specific tensor core instructions (e.g. `wgmma` on Hopper). Some layers such as DISCO benefit significantly from this. The trade-off is that the resulting binary is only compatible with the exact GPU generation it was compiled for.

:warning: Custom CUDA extensions require architectures >= 7.0.

Alternatively, build a Docker container:

git clone git@github.com:NVIDIA/torch-harmonics.git
cd torch-harmonics
docker build . -t torch_harmonics
docker run --gpus all -it --rm --ipc=host --ulimit memlock=-1 --ulimit stack=67108864 torch_harmonics

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 18 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. ---
  2. name: torch-harmonics-skills
  3. description: >
  4. Index of project-local Claude Code skills for torch-harmonics. Use this to
  5. discover which skills are available for this codebase. Individual skills live
  6. in the .skills/ directory at the project root.
  7. ---
  8. # torch-harmonics skills
  9. Project-local skills live in `.skills/<skill-name>/SKILL.md`.
  10. ## Available skills
  11. | Skill | Trigger | Description |
  12. |-------|---------|-------------|
  13. | [test-writing](.skills/test-writing/SKILL.md) | Writing or extending tests (serial or distributed), tolerance values, comparing tensors, gradient testing, autocast in tests | Guide for writing numerical tests following torch-harmonics conventions |
  14. | [disco-kernel-dev](.skills/disco-kernel-dev/SKILL.md) | Adding/optimizing/debugging DISCO kernels, wiring dispatch layers, bf16/fp16 autocast, distributed a2a, test coverage | Expert guide for DISCO convolution kernel development |
README.md · README · 507 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <!--
  2. SPDX-FileCopyrightText: Copyright (c) 2022 The torch-harmonics Authors. All rights reserved.
  3. SPDX-License-Identifier: BSD-3-Clause
  4. Redistribution and use in source and binary forms, with or without
  5. modification, are permitted provided that the following conditions are met:
  6. 1. Redistributions of source code must retain the above copyright notice, this
  7. list of conditions and the following disclaimer.
  8. 2. Redistributions in binary form must reproduce the above copyright notice,
  9. this list of conditions and the following disclaimer in the documentation
  10. and/or other materials provided with the distribution.
  11. 3. Neither the name of the copyright holder nor the names of its
  12. contributors may be used to endorse or promote products derived from
  13. this software without specific prior written permission.
  14. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  15. AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16. IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  17. DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
  18. FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19. DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
  20. SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
  21. CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  22. OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  23. OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  24. -->
  25. <!-- <div align="center">
  26. <img src="https://raw.githubusercontent.com/NVIDIA/torch-harmonics/main/images/logo/logo.png" width="568">
  27. <br>
  28. <a href="https://github.com/NVIDIA/torch-harmonics/actions/workflows/tests.yml"><img src="https://github.com/NVIDIA/torch-harmonics/actions/workflows/tests.yml/badge.svg"></a>
  29. <a href="https://pypi.org/project/torch_harmonics/"><img src="https://img.shields.io/pypi/v/torch_harmonics"></a>
  30. </div> -->
  31. <!--
  32. [![pypi](https://img.shields.io/pypi/v/torch_harmonics)](https://pypi.org/project/torch_harmonics/)
  33. -->
  34. <!-- # spherical harmonic transforms -->
  35. # torch-harmonics
  36. [**Overview**](#overview) | [**Installation**](#installation) | [**More information**](#more-about-torch-harmonics) | [**Getting started**](#getting-started) | [**Contributors**](#contributors) | [**Cite us**](#cite-us) | [**References**](#references)
  37. [![tests](https://github.com/NVIDIA/torch-harmonics/actions/workflows/tests.yml/badge.svg)](https://github.com/NVIDIA/torch-harmonics/actions/workflows/tests.yml)
  38. [![coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/NVIDIA/torch-harmonics/coverage-data/badge.json&cacheSeconds=3600)](https://github.com/NVIDIA/torch-harmonics/tree/coverage-data)
  39. [![pypi](https://img.shields.io/pypi/v/torch_harmonics)](https://pypi.org/project/torch_harmonics/)
  40. [![conda-forge](https://img.shields.io/conda/vn/conda-forge/torch-harmonics)](https://anaconda.org/conda-forge/torch-harmonics)
  41. [![downloads](https://static.pepy.tech/badge/torch-harmonics/month)](https://pepy.tech/projects/torch-harmonics)
  42. [![docs](https://img.shields.io/badge/docs-latest-blue)](https://nvidia.github.io/torch-harmonics/)
  43. [![license](https://img.shields.io/github/license/NVIDIA/torch-harmonics)](LICENSE.txt)
  44. [![arXiv](https://img.shields.io/badge/arXiv-2609.39737-b31b1b.svg)](https://arxiv.org/abs/2609.39737)
  45. ## Overview
  46. torch-harmonics implements differentiable signal processing on the sphere. This includes differentiable implementations of the spherical harmonic transforms, vector spherical harmonic transforms and discrete-continuous convolutions on the sphere. The package was originally implemented to enable Spherical Fourier Neural Operators (SFNO) [1]. A description of the library as a whole is given in [7].
  47. <div align="center">
  48. <img src="https://raw.githubusercontent.com/NVIDIA/torch-harmonics/main/images/overview.png" width="760">
  49. </div>
  50. The SHT algorithm uses quadrature rules to compute the projection onto the associated Legendre polynomials and FFTs for the projection onto the harmonic basis. This algorithm tends to outperform others with better asymptotic scaling for most practical purposes [2].
  51. torch-harmonics uses PyTorch primitives to implement these operations, making it fully differentiable. Moreover, the quadrature can be distributed onto multiple ranks making it spatially distributed.
  52. torch-harmonics has been used to implement a variety of differentiable PDE solvers which generated the animations below. Moreover, it has enabled the development of Spherical Fourier Neural Operators [1].
  53. <div align="center">
  54. <table border="0" cellspacing="0" cellpadding="0">
  55. <tr>
  56. <td><img src="https://media.githubusercontent.com/media/NVIDIA/torch-harmonics/main/images/sfno.gif" width="240"></td>
  57. <td><img src="https://media.githubusercontent.com/media/NVIDIA/torch-harmonics/main/images/zonal_jet.gif" width="240"></td>
  58. <td><img src="https://media.githubusercontent.com/media/NVIDIA/torch-harmonics/main/images/allen-cahn.gif" width="240"></td>
  59. </tr>
  60. <!-- <tr>
  61. <td style="text-align:center; border-style : hidden!important;">Shallow Water Eqns.</td>
  62. <td style="text-align:center; border-style : hidden!important;">Ginzburg-Landau Eqn.</td>
  63. <td style="text-align:center; border-style : hidden!important;">Allen-Cahn Eqn.</td>
  64. </tr> -->
  65. </table>
  66. </div>
  67. ## Installation
  68. ### Prebuilt wheels
  69. Prebuilt Linux wheels with compiled CUDA extensions are available on [pypi.nvidia.com](https://pypi.nvidia.com). Pick the package matching your CUDA toolkit version:
  70. | CUDA | Package | Supported PyTorch | Install command |
  71. |------|---------|-------------------|-----------------|
  72. | 12.6 | `torch-harmonics-cu126` | 2.9.1 | `pip install torch-harmonics-cu126 --extra-index-url https://pypi.nvidia.com` |
  73. | 12.8 | `torch-harmonics-cu128` | 2.9.1 | `pip install torch-harmonics-cu128 --extra-index-url https://pypi.nvidia.com` |
  74. | 12.9 | `torch-harmonics-cu129` | 2.9.1 | `pip install torch-harmonics-cu129 --extra-index-url https://pypi.nvidia.com` |
  75. | 13.0 | `torch-harmonics-cu130` | 2.9.1 | `pip install torch-harmonics-cu130 --extra-index-url https://pypi.nvidia.com` |
  76. | 13.2 | `torch-harmonics-cu132` | 2.12.0 | `pip install torch-harmonics-cu132 --extra-index-url https://pypi.nvidia.com` |
  77. If you don't need a specific CUDA version, use the rolling alias for the latest CUDA build:
  78. ```bash
  79. pip install torch-harmonics-cuda-latest --extra-index-url https://pypi.nvidia.com
  80. ```
  81. For a CPU-only build, install the `torch-harmonics` package from [PyPI](#pypi).
  82. > **Tip:** Run `nvidia-smi` to check your driver's CUDA version.
  83. > **Note:** `torch.compile` of the vector SHTs (`RealVectorSHT`, `InverseRealVectorSHT`) can give wrong results in float32 on PyTorch before 2.13. With PyTorch 2.12 (NGC 26.04) on H100, the compiled `InverseRealVectorSHT` was off by up to 1e7 ULPs and differed between runs; it is exact with PyTorch 2.13 (NGC 26.06) on the same GPU. Eager mode is not affected. If you compile models that contain vector SHTs, use PyTorch 2.13 or newer.
  84. **Older PyTorch or CUDA** (PyTorch before 2.9, CUDA before 12.6) have no prebuilt wheels. Use the [Docker container](#building-from-source), which brings a matching PyTorch and CUDA, or build torch-harmonics from source against your installed PyTorch, adding `--no-deps` so that pip does not replace it with a newer one (`pip install --no-build-isolation --no-deps .`). These combinations are not tested.
  85. ### PyPI
  86. The vanilla `torch-harmonics` package on [PyPI](https://pypi.org/project/torch_harmonics/) ships a CPU-only prebuilt wheel. This version is built for the newest PyTorch release. For GPU support, use the NVIDIA PyPI packages above.
  87. ```bash
  88. pip install torch-harmonics
  89. ```
  90. ### Building from source
  91. If your OS, PyTorch or CUDA toolkit version is not covered by the available wheels, we recomment building torch-harmonics from the GitHub repository. Use `--no-build-isolation` so that custom CPU and CUDA kernels compile against your existing torch installation:
  92. ```bash
  93. git clone git@github.com:NVIDIA/torch-harmonics.git
  94. cd torch-harmonics
  95. pip install --no-build-isolation -e .
  96. ```
  97. If CUDA devices are not detected automatically (e.g. inside a container), set the `TORCH_HARMONICS_BUILD_CUDA_EXTENSION` flag. Set `TORCH_CUDA_ARCH_LIST` to only the architectures you need to reduce compilation time. The example below needs CUDA 12.9 or newer; with CUDA 12.8 drop `10.3a`, and before 12.8 also drop `10.0a` and `12.0+PTX`, which those compilers do not support:
  98. ```bash
  99. export TORCH_HARMONICS_BUILD_CUDA_EXTENSION=1
  100. export TORCH_CUDA_ARCH_LIST="8.0 8.6 9.0a 10.0a 10.3a 12.0+PTX"
  101. pip install --no-build-isolation -e .
  102. ```
  103. > **Tip:** Use the `a` suffix (e.g. `9.0a`, `10.0a`) instead of plain `9.0` or `10.0` to enable architecture-specific tensor core instructions (e.g. `wgmma` on Hopper). Some layers such as DISCO benefit significantly from this. The trade-off is that the resulting binary is only compatible with the exact GPU it was compiled for, and this includes `+PTX` on an `a` target: `10.0a` runs on GB200/B200 (10.0) but not on GB300/B300 (10.3), which needs `10.3a`.
  104. :warning: Custom CUDA extensions require architectures >= 7.0.
  105. Alternatively, build a Docker container:
  106. ```bash
  107. git clone git@github.com:NVIDIA/torch-harmonics.git
  108. cd torch-harmonics
  109. docker build . -t torch_harmonics
  110. docker run --gpus all -it --rm --ipc=host --ulimit memlock=-1 --ulimit stack=67108864 torch_harmonics
  111. ```
  112. ## More about torch-harmonics
  113. ### Spherical harmonics
  114. The [spherical harmonics](https://en.wikipedia.org/wiki/Spherical_harmonics) are special functions defined on the two-dimensional sphere $S^2$ (embedded in three dimensions). They form an orthonormal basis of the space of square-integrable functions defined on the sphere $L^2(S^2)$ and are comparable to the harmonic functions defined on a circle/torus. The spherical harmonics are defined as
  115. $$
  116. Y_l^m(\theta, \lambda) = \sqrt{\frac{(2l + 1)}{4 \pi} \frac{(l - m)!}{(l + m)!}} P_l^m(\cos \theta) \exp(im\lambda),
  117. $$
  118. where $\theta$ and $\lambda$ are colatitude and longitude respectively, and $P_l^m$ the normalized, [associated Legendre polynomials](https://en.wikipedia.org/wiki/Associated_Legendre_polynomials).
  119. <div align="center">
  120. <img src="https://media.githubusercontent.com/media/NVIDIA/torch-harmonics/main/images/spherical_harmonics.gif" width="432">
  121. <br>
  122. Spherical harmonics up to degree 5
  123. </div>
  124. ### Spherical harmonic transform
  125. The spherical harmonic transform (SHT)
  126. $$
  127. f_l^m = \int_{S^2} \overline{Y_{l}^{m}}(\theta, \lambda) f(\theta, \lambda) \mathrm{d} \mu(\theta, \lambda)
  128. $$
  129. realizes the projection of a signal $f(\theta, \lambda)$ on $S^2$ onto the spherical harmonics basis. The SHT generalizes the Fourier transform on the sphere. Conversely, a truncated series expansion of a function $f$ can be written in terms of spherical harmonics as
  130. $$
  131. f (\theta, \lambda) = \sum_{m=-M}^{M} \exp(im\lambda) \sum_{l=|m|}^{M} \hat f_l^m P_l^m (\cos \theta),
  132. $$
  133. where $\hat{f}_l^m$, are the expansion coefficients associated to the mode $m$, $n$.
  134. The implementation of the SHT follows the algorithm as presented in [2]. A direct spherical harmonic transform can be accomplished by a Fourier transform
  135. $$
  136. \hat f^m(\theta) = \frac{1}{2 \pi} \int_{0}^{2\pi} f(\theta, \lambda) \exp(-im\lambda) \mathrm{d} \lambda
  137. $$
  138. in longitude and a Legendre transform
  139. $$
  140. \hat f_l^m = \frac{1}{2} \int^{\pi}_0 \hat f^{m} (\theta) P_l^m (\cos \theta) \sin \theta \mathrm{d} \theta
  141. $$
  142. in latitude.
  143. ### Discrete Legendre transform
  144. The second integral, which computed the projection onto the Legendre polynomials is realized with quadrature. On the Gaussian grid, we use Gaussian quadrature in the $\cos \theta$ domain. The integral
  145. $$
  146. \hat f_l^m = \frac{1}{2} \int_{-1}^1 \hat{f}^m(\arccos x) P_l^m (x) \mathrm{d} x
  147. $$
  148. is obtained with the substitution $x = \cos \theta$ and then approximated by the sum
  149. $$
  150. \hat f_l^m = \sum_{j=1}^{N_\theta} \hat{f}^m(\arccos x_j) P_l^m(x_j) w_j.
  151. $$
  152. Here, $x_j \in [-1,1]$ are the quadrature nodes with the respective quadrature weights $w_j$.
  153. ### Discrete-continuous convolutions on the sphere
  154. torch-harmonics now provides local discrete-continuous (DISCO) convolutions as outlined in [5] on the sphere. These are use in local neural operators [2] to generalize convolutions to structured and unstructured meshes on the sphere.
  155. ### Spherical (neighborhood) attention
  156. torch-harmonics introduces spherical attention mechanisms which correctly generalize the attention mechanism to the sphere. The use of quadrature rules makes the resulting operations approximately equivariant and equivariant in the continuous limit. Moreover, neighborhood attention is correctly generalized onto the sphere by using the geodesic distance to determine the size of the neighborhood.
  157. ## Getting started
  158. The main functionality of `torch_harmonics` is provided in the form of `torch.nn.Modules` for composability. A minimum example is given by:
  159. ```python
  160. import torch
  161. import torch_harmonics as th
  162. device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
  163. nlat = 512
  164. nlon = 2*nlat
  165. batch_size = 32
  166. signal = torch.randn(batch_size, nlat, nlon, device=device)
  167. # transform data on an equiangular grid
  168. grid = th.EquiangularGrid(nlat=nlat, nlon=nlon)
  169. sht = th.RealSHT(grid).to(device)
  170. coeffs = sht(signal)
  171. ```
  172. ### Grids
  173. Every layer takes a grid descriptor rather than a resolution and a grid name.
  174. The descriptor holds both, along with everything that follows from where the
  175. nodes sit: the quadrature weights, the node spacing localized operators take
  176. their default cutoff from, and the degree an SHT can be truncated to without
  177. losing orthogonality. Each grid type has its own class, e.g.
  178. `th.EquiangularGrid(nlat=..., nlon=...)` or `th.HealpixGrid(nside=...)`.
  179. Alternatively, `th.as_grid` builds a grid from its name, e.g.
  180. `th.as_grid("equiangular", nlat=..., nlon=...)`, which is convenient when the
  181. grid type comes from a configuration file.
  182. The supported grids differ in where they place their nodes, which the figure
  183. below shows at coarse resolution, both on the sphere and in longitude-latitude
  184. coordinates:
  185. <div align="center">
  186. <img src="https://raw.githubusercontent.com/NVIDIA/torch-harmonics/main/images/grids.png" width="100%">
  187. </div>
  188. - **Equiangular**: rings equally spaced in latitude, including both poles, with Clenshaw-Curtis quadrature. This is the familiar latitude-longitude grid used for most reanalysis and climate data.
  189. - **Fejér-1**: pole-excluding rings with Fejér quadrature. Its direct-analysis default is `(nlat + 1) // 2`; folded analysis supports higher bandlimits within its recovery bounds.
  190. - **Legendre-Gauss**: rings at the roots of the Legendre polynomial in $\cos\theta$, excluding the poles. Gaussian quadrature is exact up to the highest polynomial degree for a given number of rings, so this grid supports the highest SHT bandlimit per ring.
  191. - **Lobatto**: Gauss-Lobatto nodes, i.e. Legendre-Gauss-like rings that include both poles.
  192. - **Trapezoidal**: rings equally spaced in $\cos\theta$ with the trapezoidal rule, which places them densely near the equator and sparsely near the poles. Its quadrature converges only algebraically, so it is suited for quadrature and localized operators but not for an SHT at a high bandlimit.
  193. - **HEALPix** [8]: `12 * nside**2` pixels of equal area on `4 * nside - 1` rings of constant latitude. The rings have different lengths, so a field is stored as a flat tensor of shape `(..., npix)` in RING order. HEALPix supports the scalar and vector SHTs, spectral convolutions, resampling, random fields, attention, DISCO convolutions and quadrature. Its SHT synthesis is exact, while its analysis is approximate: about 1e-2 relative error at the default `lmax = 2 * nside`, or about 1e-6 with `RealSHT(grid, iter=3)`. Of the distributed layers, the SHTs, `DistributedSpectralConvS2`, `DistributedResampleS2`, `DistributedNeighborhoodAttentionS2`, the distributed DISCO convolutions and `DistributedQuadratureS2` accept HEALPix, decomposed along latitude only (see below).
  194. | grid type | class | field shape | accepted by |
  195. | ------------------ | ------------------------------------------ | -------------- | -------------------------------------------------------- |
  196. | `"equiangular"` | `th.EquiangularGrid(nlat=..., nlon=...)` | `(nlat, nlon)` | every layer |
  197. | `"fejer1"` | `th.Fejer1Grid(nlat=..., nlon=...)` | `(nlat, nlon)` | every layer |
  198. | `"legendre-gauss"` | `th.LegendreGaussGrid(nlat=..., nlon=...)` | `(nlat, nlon)` | every layer |
  199. | `"lobatto"` | `th.LobattoGrid(nlat=..., nlon=...)` | `(nlat, nlon)` | every layer |
  200. | `"trapezoidal"` | `th.TrapezoidalGrid(nlat=..., nlon=...)` | `(nlat, nlon)` | every layer |
  201. | `"healpix"` | `th.HealpixGrid(nside=...)` | `(npix,)` | `RealSHT`, `InverseRealSHT`, `RealVectorSHT`, `InverseRealVectorSHT`, `SpectralConvS2`, `ResampleS2`, `AttentionS2`, `NeighborhoodAttentionS2`, `DiscreteContinuousConvS2`, `DiscreteContinuousConvTransposeS2`, `QuadratureS2`, `GaussianRandomFieldS2`; distributed: the four SHTs, `DistributedSpectralConvS2`, `DistributedResampleS2`, `DistributedNeighborhoodAttentionS2`, `DistributedDiscreteContinuousConvS2`, `DistributedDiscreteContinuousConvTransposeS2` and `DistributedQuadratureS2`, polar ranks only |
  202. Equiangular and Fejér-1 grids use native quadrature at the default SHT
  203. truncation. Explicitly higher `lmax` bounds can use folded scalar and vector
  204. analysis, provided the latitude bound fits the grid and `mmax` excludes the
  205. even-longitude Nyquist order. See the [grid guide](docs/guide/grids.md) for
  206. the precise limits and memory costs.
  207. Layers that map between two grids take `grid_in` and `grid_out`, which need not
  208. be of the same type -- attention can decode from HEALPix onto a latitude-longitude
  209. grid, for instance:
  210. ```python
  211. hp = th.HealpixGrid(nside=16) # 3072 equal-area pixels
  212. ll = th.EquiangularGrid(nlat=33, nlon=64)
  213. attn = th.NeighborhoodAttentionS2(grid_in=hp, grid_out=hp, in_channels=32, num_heads=4)
  214. decode = th.AttentionS2(grid_in=hp, grid_out=ll, in_channels=32, num_heads=4)
  215. x = torch.randn(2, 32, hp.npoints) # a HEALPix field is flat: (..., npix)
  216. h = attn(x) # self-attention: (2, 32, 3072)
  217. q = torch.randn(2, 32, 33, 64) # queries live on the output grid,
  218. y = decode(q, key=h, value=h) # keys and values on the input grid
  219. ```
  220. Volumetric fields on balls, shells or the space outside a sphere use a radial grid
  221. together with any of the grids above. `th.SphericalProductGrid(angular, radial)` samples
  222. the same angular grid at every radius, and a field on it is laid out
  223. `(..., nr, *angular.shape)`. Every layer accepts a product grid and acts on each shell
  224. alike, treating the radius as a batch axis. `th.QuadratureVolume` integrates over the
  225. volume:
  226. ```python
  227. shells = th.LegendreGaussRadialGrid(nr=8, r_inner=1.0, r_outer=2.0)
  228. grid = th.SphericalProductGrid(th.EquiangularGrid(nlat=33, nlon=64), shells) # grid.shape == (8, 33, 64)
  229. conv = th.DiscreteContinuousConvS2(grid_in=grid, grid_out=grid, in_channels=4, out_channels=8, kernel_shape=3)
  230. x = torch.randn(2, 4, *grid.shape) # (batch, channels, nr, nlat, nlon)
  231. y = conv(x) # every shell convolved alike: (2, 8, 8, 33, 64)
  232. volume = th.QuadratureVolume(grid)(torch.ones(grid.shape)) # 4/3 pi (2^3 - 1^3)
  233. ```
  234. The distributed layers take the *global* grid and derive each rank's shard from
  235. it. Passing a resolution where a descriptor belongs raises a `TypeError` naming
  236. the replacement, and a layer that does not support a grid yet refuses it at
  237. construction.
  238. A HEALPix grid decomposes along latitude only: each polar rank holds a contiguous
  239. band of rings with about the same number of pixels, which in RING order is a
  240. contiguous slice of the flat pixel axis, so a local field is `(..., npix_local)`.
  241. The rings differ in length, so there is no global `nlon` to split, and a process
  242. grid with more than one azimuth rank is rejected with a `NotImplementedError` at
  243. construction. Of the distributed layers, `DistributedRealSHT`,
  244. `DistributedInverseRealSHT`, `DistributedRealVectorSHT`,
  245. `DistributedInverseRealVectorSHT`, `DistributedSpectralConvS2`,
  246. `DistributedResampleS2`, `DistributedNeighborhoodAttentionS2`,
  247. `DistributedDiscreteContinuousConvS2`, `DistributedDiscreteContinuousConvTransposeS2`
  248. and `DistributedQuadratureS2` accept HEALPix. See [Grids](https://nvidia.github.io/torch-harmonics/api/utilities.html#grids)
  249. for the full descriptor API, and the [grid descriptors notebook](./notebooks/grid_descriptors.ipynb) for a walkthrough.
  250. ### Distributed and further reading
  251. To enable scalable model-parallelism, `torch-harmonics` implements distributed variants of the SHT and the other layers in `torch_harmonics.distributed`. See the [distributed guide](docs/guide/distributed.md) for the process grid, how fields are split across ranks, and the HEALPix restrictions.
  252. Detailed usage of torch-harmonics, alongside helpful analysis provided in a series of notebooks:
  253. 1. [Getting started](./notebooks/getting_started.ipynb)
  254. 2. [Quadrature](./notebooks/quadrature.ipynb)
  255. 3. [Visualizing the spherical harmonics](./notebooks/plot_spherical_harmonics.ipynb)
  256. 4. [Spectral fitting vs. SHT](./notebooks/gradient_analysis.ipynb)
  257. 5. [Conditioning of the Gramian](./notebooks/conditioning_sht.ipynb)
  258. 6. [Solving the Helmholtz equation](./notebooks/helmholtz.ipynb)
  259. 7. [Solving the shallow water equations](./notebooks/shallow_water_equations.ipynb)
  260. 8. [Training Spherical Fourier Neural Operators (SFNO)](./notebooks/train_spherical_neural_operator.ipynb)
  261. 9. [Resampling signals on the sphere](./notebooks/resample_sphere.ipynb)
  262. 10. [Grid descriptors](./notebooks/grid_descriptors.ipynb)
  263. 11. [Computing partial derivatives with the SHT](./notebooks/partial_derivatives.ipynb)
  264. ## Benchmarks
  265. The `benchmarks/` directory contains a performance benchmark suite covering SHT, DISCO
  266. convolution, and spherical attention across resolutions, dtypes, and channel counts.
  267. ```bash
  268. # run full suite on current GPU
  269. python benchmarks/run.py
  270. # filter by name or tag
  271. python benchmarks/run.py --name disco
  272. python benchmarks/run.py --tags attention neighborhood
  273. # save a baseline, then compare after a change
  274. python benchmarks/run.py --save-csv before.csv
  275. python benchmarks/run.py --reference-csv before.csv
  276. ```
  277. See [CONTRIBUTING.md](CONTRIBUTING.md#running-benchmarks) for the full workflow expected
  278. in performance-related PRs.
  279. ## Examples and reproducibility
  280. The `examples` folder contains training scripts for three distinct tasks:
  281. * [solution of the shallow water equations on the rotating sphere](./examples/shallow_water_equations/train.py)
  282. * [depth estimation on the sphere](./examples/depth/train.py)
  283. * [semantic segmentation on the sphere](./examples/segmentation/train.py)
  284. Results from the papers can generally be reproduced by running `python train.py`. In the case of some older results the number of epochs and learning-rate may need to be adjusted by passing the corresponding command line argument.
  285. ## Remarks on automatic mixed precision (AMP) support
  286. Note that torch-harmonics uses Fourier transforms from `torch.fft` which in turn uses kernels from the optimized `cuFFT` library. This library supports fourier transforms of `float32` and `float64` (i.e. `single` and `double` precision) tensors for all input sizes. For `float16` (i.e. `half` precision) and `bfloat16` inputs however, the dimensions which are transformed are restricted to powers of two. Since data is converted to one of these reduced precision floating point formats when `torch.autocast` is used, torch-harmonics will issue an error when the input shapes are not powers of two. For these cases, we recommend disabling autocast for the harmonics transform specifically:
  287. ```python
  288. import torch
  289. import torch_harmonics as th
  290. sht = th.RealSHT(th.EquiangularGrid(nlat=512, nlon=1024)).cuda()
  291. with torch.autocast(device_type="cuda", enabled = True):
  292. # do some AMP converted math here
  293. x = some_math(x)
  294. # convert tensor to float32
  295. x = x.to(torch.float32)
  296. # now disable autocast specifically for the transform,
  297. # making sure that the tensors are not converted
  298. # back to reduced precision internally
  299. with torch.autocast(device_type="cuda", enabled = False):
  300. xt = sht(x)
  301. # continue operating on the transformed tensor
  302. xt = some_more_math(xt)
  303. ```
  304. Depending on the problem, it might be beneficial to upcast data to `float64` instead of `float32` precision for numerical stability.
  305. ## Contributors
  306. [Boris Bonev](https://bonevbs.github.io) (bbonev@nvidia.com), [Thorsten Kurth](https://github.com/azrael417) (tkurth@nvidia.com), [Max Rietmann](https://github.com/rietmann-nv), [Mauro Bisson](https://scholar.google.com/citations?hl=en&user=f0JE-0gAAAAJ), [Andrea Paris](https://github.com/apaaris), [Alberto Carpentieri](https://github.com/albertocarpentieri), [Massimiliano Fatica](https://scholar.google.com/citations?user=Deaq4uUAAAAJ&hl=en), [Nikola Kovachki](https://kovachki.github.io), [Jean Kossaifi](http://jeankossaifi.com), [Christian Hundt](https://github.com/gravitino)
  307. ## Cite us
  308. If you use `torch-harmonics` in your work, please cite the paper describing the library [7]:
  309. ```bibtex
  310. @misc{kurth2026library,
  311. title={A library for differentiable signal processing and machine learning on the sphere},
  312. author={Thorsten Kurth and Max Rietmann and Mauro Bisson and Andrea Paris and Alberto Carpentieri and Jean Kossaifi and Anima Anandkumar and Christian Hundt and Boris Bonev},
  313. year={2026},
  314. eprint={2609.39737},
  315. archivePrefix={arXiv},
  316. primaryClass={cs.LG},
  317. url={https://arxiv.org/abs/2609.39737}
  318. }
  319. ```
  320. If you use the spherical neural operators or spherical attention, please also cite the papers introducing them: Spherical Fourier Neural Operators [1], localized neural operators with discrete-continuous convolutions [2], and attention on the sphere [6]:
  321. ```bibtex
  322. @misc{bonev2023spherical,
  323. title={Spherical Fourier Neural Operators: Learning Stable Dynamics on the Sphere},
  324. author={Boris Bonev and Thorsten Kurth and Christian Hundt and Jaideep Pathak and Maximilian Baust and Karthik Kashinath and Anima Anandkumar},
  325. year={2023},
  326. eprint={2306.03838},
  327. archivePrefix={arXiv},
  328. primaryClass={cs.LG}
  329. }
  330. @misc{liuschiaffini2024neural,
  331. title={Neural Operators with Localized Integral and Differential Kernels},
  332. author={Miguel Liu-Schiaffini and Julius Berner and Boris Bonev and Thorsten Kurth and Kamyar Azizzadenesheli and Anima Anandkumar},
  333. year={2024},
  334. eprint={2402.16845},
  335. archivePrefix={arXiv},
  336. primaryClass={cs.LG}
  337. }
  338. @misc{bonev2025attention,
  339. title={Attention on the Sphere},
  340. author={Boris Bonev and Max Rietmann and Andrea Paris and Alberto Carpentieri and Thorsten Kurth},
  341. year={2025},
  342. eprint={2505.11157},
  343. archivePrefix={arXiv},
  344. primaryClass={cs.LG}
  345. }
  346. ```
  347. ## References
  348. <a id="1">[1]</a>
  349. Bonev B., Kurth T., Hundt C., Pathak, J., Baust M., Kashinath K., Anandkumar A.;
  350. Spherical Fourier Neural Operators: Learning Stable Dynamics on the Sphere;
  351. International Conference on Machine Learning, 2023. [arxiv link](https://arxiv.org/abs/2306.03838)
  352. <a id="2">[2]</a>
  353. Liu-Schiaffini M., Berner J., Bonev B., Kurth T., Azizzadenesheli K., Anandkumar A.;
  354. Neural Operators with Localized Integral and Differential Kernels;
  355. International Conference on Machine Learning, 2024. [arxiv link](https://arxiv.org/abs/2402.16845)
  356. <a id="3">[3]</a>
  357. Schaeffer N.;
  358. Efficient spherical harmonic transforms aimed at pseudospectral numerical simulations;
  359. G3: Geochemistry, Geophysics, Geosystems, 2013.
  360. <a id="4">[4]</a>
  361. Wang B., Wang L., Xie Z.;
  362. Accurate calculation of spherical and vector spherical harmonic expansions via spectral element grids;
  363. Adv Comput Math, 2018.
  364. <a id="5">[5]</a>
  365. Ocampo, Price, McEwen, Scalable and equivariant spherical CNNs by discrete-continuous (DISCO) convolutions, ICLR (2023), arXiv:2209.13603
  366. <a id="6">[6]</a>
  367. Bonev B., Rietmann M., Paris A., Carpentieri A., Kurth T.; Attention on the Sphere; [arxiv link](https://arxiv.org/abs/2505.11157)
  368. <a id="7">[7]</a>
  369. Kurth T., Rietmann M., Bisson M., Paris A., Carpentieri A., Kossaifi J., Anandkumar A., Hundt C., Bonev B.;
  370. A library for differentiable signal processing and machine learning on the sphere;
  371. arXiv preprint, 2026. [arxiv link](https://arxiv.org/abs/2609.39737)
  372. <a id="8">[8]</a>
  373. Gorski K. M., Hivon E., Banday A. J., Wandelt B. D., Hansen F. K., Reinecke M., Bartelmann M.;
  374. HEALPix: A Framework for High-Resolution Discretization and Fast Analysis of Data Distributed on the Sphere;
  375. The Astrophysical Journal, 622:759-771, 2005.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.