# Differentiable and accelerated spherical transforms#

`S2FFT`

is a Python package for computing Fourier transforms on the sphere and rotation
group (Price & McEwen 2023) using JAX and PyTorch.
It leverages autodiff to provide differentiable transforms, which are also
deployable on modern hardware accelerators (e.g. GPUs and TPUs).

More specifically, `S2FFT`

provides support for spin spherical harmonic and Wigner
transforms (for both real and complex signals), with support for adjoint transformations
where needed, and comes with different optimisations (precompute or not) that one
may select depending on available resources and desired angular resolution \(L\).

Important

HEALPix long JIT compile time fixed for CPU! Fix for GPU coming soon.

Tip

As of version 1.0.2 `S2FFT`

also provides PyTorch implementations of underlying
precompute transforms. In future releases this support will be extended to our
on-the-fly algorithms.

Tip

As of version 1.1.0 `S2FFT`

also provides JAX support for existing C/C++ packages,
specifically `HEALPix`

and `SSHT`

. This works by wrapping python bindings with custom
JAX frontends. Note that currently this C/C++ to JAX interoperability is currently
limited to CPU.

## Algorithms ⚡#

`S2FFT`

leverages new algorithmic structures that can he highly parallelised and
distributed, and so map very well onto the architecture of hardware accelerators (i.e.
GPUs and TPUs). In particular, these algorithms are based on new Wigner-d recursions
that are stable to high angular resolution \(L\). The diagram below illustrates the
recursions (for further details see Price & McEwen 2023).

With this recursion to hand, the spherical harmonic coefficients of an isolatitudinally sampled map may be computed as a two step process. First, a 1D Fourier transform over longitude, for each latitudinal ring. Second, a projection onto the real polar-d functions. One may precompute and store all real polar-d functions for extreme acceleration, however this comes with an equally extreme memory overhead, which is infeasible at L ~ 1024. Alternatively, the real polar-d functions may calculated recursively, computing only a portion of the projection at a time, hence incurring negligible memory overhead at the cost of slightly slower execution. The diagram below illustrates the separable spherical harmonic transform.

Note

For algorithmic reasons JIT compilation of HEALPix transforms can become slow at high bandlimits, due to XLA unfolding of loops which currently cannot be avoided. After compiling HEALPix transforms should execute with the efficiency outlined in the associated paper, therefore this additional time overhead need only be incurred once. We are aware of this issue and are working to fix it. A fix for CPU execution has now been implemented (see example notebook). Fix for GPU execution is coming soon.

## Sampling 🌍#

The structure of the algorithms implemented in `S2FFT`

can support any isolattitude sampling scheme. A number of sampling schemes are currently supported.

The equiangular sampling schemes of McEwen & Wiaux (2012), Driscoll & Healy (1995), and Gauss-Legendre (1986) are supported, which exhibit associated sampling theorems and so harmonic transforms can be computed to machine precision. Note that the McEwen & Wiaux sampling theorem reduces the Nyquist rate on the sphere by a factor of two compared to the Driscoll & Healy approach, halving the number of spherical samples required.

The popular HEALPix sampling scheme (Gorski et al. 2005) is also supported. The HEALPix sampling does not exhibit a sampling theorem and so the corresponding harmonic transforms do not achieve machine precision but exhibit some error. However, the HEALPix sampling provides pixels of equal areas, which has many practical advantages.

## Contributors ✨#

Thanks goes to these wonderful people (emoji key):

## Attribution 📚#

Should this code be used in any way, we kindly request that the following article is referenced. A BibTeX entry for this reference may look like:

```
@article{price:s2fft,
author = "Matthew A. Price and Jason D. McEwen",
title = "Differentiable and accelerated spherical harmonic and Wigner transforms",
journal = "Journal of Computational Physics, submitted",
year = "2023",
eprint = "arXiv:2311.14670"
}
```

You might also like to consider citing our related papers on which this code builds:

```
@article{mcewen:fssht,
author = "Jason D. McEwen and Yves Wiaux",
title = "A novel sampling theorem on the sphere",
journal = "IEEE Trans. Sig. Proc.",
year = "2011",
volume = "59",
number = "12",
pages = "5876--5887",
eprint = "arXiv:1110.6298",
doi = "10.1109/TSP.2011.2166394"
}
```

```
@article{mcewen:so3,
author = "Jason D. McEwen and Martin B{\"u}ttner and Boris ~Leistedt and Hiranya V. Peiris and Yves Wiaux",
title = "A novel sampling theorem on the rotation group",
journal = "IEEE Sig. Proc. Let.",
year = "2015",
volume = "22",
number = "12",
pages = "2425--2429",
eprint = "arXiv:1508.03101",
doi = "10.1109/LSP.2015.2490676"
}
```

## License 📝#

We provide this code under an MIT open-source licence with the hope that it will be of use to a wider community.

Copyright 2023 Matthew Price, Jason McEwen and contributors.

`S2FFT`

is free software made available under the MIT License. For details see
the LICENSE file.