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

SSHT can also interface with ducc0 and use it as a backend for the forward, inverse and inverse adjoint transforms.

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:

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 contributors

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