## Description

The **SSHT** code provides functionality to perform fast and exact
spin spherical harmonic transforms based on the sampling theorem on the
sphere derived in
McEwen & Wiaux (2011).

In some applications adjoint forward and inverse spherical harmonic transforms are also required (for example, when solving convex optimisation problems). Functionality is also provided to perform fast and exact adjoint transforms, based on the fast algorithms derived in McEwen et al. (2013).

This documentation outlines the various harmonic transforms
supported in **SSHT**, before describing installation details and
documenting the source code. Reference, author and license information is also given. The code itself is hosted on GitHub.

#### Spin spherical harmonic transforms supported

Routines are provided to compute forward and inverse transforms using the efficient sampling theorem of McEwen & Wiaux (2011) (the MW routines). An extension of the sampling theorem to a sub-optimal but diametrically symmetric sampling, which is important for certain applications, is also provided (the MWSS routines). For the MW and MWSS routines we also provide fast algorithms to perform adjoint forward and inverse transforms.

We also provide routines to compute spherical harmonic transforms for a number of alternative sampling scheme. Efficient routines to perform spherical harmonic transforms using Gauss-Legendre quadrature are inlucded (the GL routines), although these are slower than the MW routines, and not stable to such high band-limmits. Finally, we provide routines to perform transforms based on the quadrature of Driscoll & Healy (the DH routines). Note that we do NOT implement the fast Driscoll & Healy algorithms (which may be found in s2kit) but simply apply the quadrature rule to implement a simple algorithm based on a separation of variables, hence these routines are slower still.

All of these transforms correspond to sampling theorems on the sphere, with exact forward and inverse transforms for band-limited signals. In practice reconstruction accuracy is limited by machine precision. For all of the algorithms we find maximum reconstruction errors are of the order 10^(-10) or considerably smaller. Please see our paper for a discussion of the various algorithms implemented in the SSHT package and for a comparison of their performance.

## Installation

The **SSHT** package contains both **C** and **Fortran 90**
core implementations. The C version is recommended since it is faster
(due to more efficient memory addressing) and, in addition to the MW
routines, it also contains the MWSS, GL and DH routines described above. Furthermore, fast adjoint algorithms
are provided in the C implementation only. The Fortran version
contains the core MW routines and additional development and testing
routines. Furthermore, **Python** and **Matlab** interfaces to the C implementation
are provided.

Source code is hosted on GitHub.

#### Dependencies

**SSHT** requires only the FFTW package. Obviously suitable C and
Fortran 90 compilers will be required to build the respective
implementations. Both C and Matlab mex compilers will be required
to build the Matlab interface to the C implementation. The python interface requires numpy and, in addition, the demos require matplotlib.

#### Python installation

The python package, **pyssht**, is available on pypi and can be installed with:

pip install pyssht

The python package is backed by scikit-build and CMake. It will install a local version of FFTW and will compile its own version of the C package.

#### C installation

The C package can be installed with CMake and conan.

Both can be installed using pip:

pip install conan cmake

Then **SSHT** can be compiled with:

git clone https://github.com/astro-informatics/ssht.git mkdir ssht/build && cd ssht/build cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr/local -Dconan_deps=True .. make make install

The above will also download FFTW, if necessary.

#### Matlab installation

The Matlab interface requires the C version to be installed.

It can be built using make by configuring appropriate compilers and dependencies, and then running:

make matlab

#### Fortran installation

The Fortran version can be built using make by configuring appropriate compilers and dependencies, and then running:

make -f makefile_f90

Note that we recommend the use of the Python, Matlab or C version over Fortran (nevertheless, the Fortran version is provided for posterity).

## Source code documentation

**SSHT** code is self documented. Source code documentation for each language is available here:

- Python source documentation (usage for the python package is given in the package docstring)
- C source documentation
- Matlab source documentation (usage for the matlab package is available through matlab help documentation)
- Fortran source documentation

## Referencing

If you use **SSHT** for work that results in
publication, please reference https://github.com/astro-informatics/ssht/
and cite our related academic paper:

J. D. McEwen and Y. Wiaux, A novel sampling theorem on the sphere, IEEE Trans. Sig. Proc., 59(12):5876-5887, 2011 (ArXiv | DOI).

If you make use of our fast adjoint algorithms, then please also cite:

J. D. McEwen, G. Puy, J.-Ph. Thiran, P. Vandergheynst, D. Van De Ville and Y. Wiaux, Sparse image reconstruction on the sphere: implications of a new sampling theorem, IEEE Trans. Image Proc., 22(6):2275-2285, 2013 (ArXiv | DOI).

## License

SSHT: spin spherical harmonic transforms

Copyright (C) 2011 Jason McEwen and contributorsThis program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details (LICENSE.txt).

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.

## Authors

**SSHT** was initially written by Jason McEwen but significant contributors have since been made by a number of others.