Introduction

The SSHT code provides functionality to perform fast and exact spin spherical harmonic transforms based on the sampling theorem on the sphere derived in our paper: A novel sampling theorem on the sphere (ArXiv | DOI). In some applications, adjoint forward and inverse spherical harmonic transforms are also required (for example, when solving convex optimisation problems). We provide functionality to perform fast and exact adjoint transforms, based on the fast algorithms derived in our paper: Sparse image reconstruction on the sphere: implications of a new sampling theorem (ArXiv | DOI).

This documentation outlines the various harmonic transforms supported in SSHT, before describing installation details and documenting the C, Fortran and Matlab source code. Reference, version, and license information then follows. For an overview see the README.txt file.

Spin spherical harmonic transform routines

Routines are provided to compute forward and inverse transforms using our optimal sampling (the MW routines). An extension of our 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 optimal routines to perform spherical harmonic transforms using Gauss-Legendre quadrature (the GL routines), although these are slower than the MW routines.

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 set 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 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, a Matlab interface to the C implementation is provided.

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.

Compiling

Makefiles are provided to build the code. By default the C makefile will be assumed, unless the Fortran makefile_f90 is explicitly specified by passing the filename to make using the following command: 

 >> make -f makefile_f90

Hereafter we consider the C makefile, although the following commands also apply to the Fortran makefile (with the exception of the Matlab interface). Before compiling you will need to edit the makefile to specify your compiler and to link with the appropriate libraries.

Once you have set the makefile up for your system, SSHT may be compiled by running: 

 >> make all

This will build the library, test program and Matlab interface. If your system is configured to build all of these components then you are done. If you prefer to build only a subset of these components then read on.

You may alternatively build the individual components of SSHT. To build the library only run: 

 >> make lib

To build the test program run: 

 >> make test

To build the Matlab interface run (which will also build the library if it has not already been built): 

 >> make matlab

To build and install the python interface run: 

 >> pip install .

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.

Testing

Run the test program to verify your installation. A default test may be performed by running: 

 >> make runtest

If SSHT is installed correctly the test program should run and print test results to the terminal. The test program performs an inverse (spin) spherical harmonic transform of a random signal, followed by a forward transform. The error between the original and recovered spherical harmonic coefficients is computed and displayed. All errors should be of the order of numerical precision.

Alternatively, you may run the test program directly by running: 

 >> ./bin/c/ssht_test <bandlimit> <spin>

where <bandlimit> and <spin> are the harmonic band-limit and spin number, respectively, of your test.

To check the version and build numbers of your version run: 

 >> ./bin/c/ssht_about

Documentation

The SSHT code is self documenting. Although the package ships with source documentation, you may generate html source documentation by running: 

 >> make doc

Documentation is generated using doxygen, thus you must have doxygen installed on your system to generate the source documentation.

Cleaning up

To clean up your version of the SSHT code and remove all builds run: 

 >> make clean

To remove all source documentation run: 

 >> make cleandoc

Source code documentation

SSHT ships with source documentation that is generated by doxygen. Documentation is available here for the C and Fortran 90 implementations. The Matlab routines that interface with the C implementation are self documenting (documentation can be access through the help command in Matlab), as discussed below.

Matlab interface

Once the Matlab interface is built, you must have ssht/src/matlab in your path in order to run the Matlab functions. A number of Matlab functions and demos illustrating their use are provided.

Functions

Usage of the SSHT Matlab interface will most frequently require only the functions to perform forward and inverse spherical harmonic transforms (ssht_forward and ssht_inverse respectively). However, a number of additional functions are also provided. A full list of Matlab functions, with brief descriptions are given here: 


  ssht_c2s
  Convert cartesian to spherical coordinates

  ssht_dl
  Compute Wigner small-d functions

  ssht_dln
  Compute Wigner small-d functions for given n

  ssht_elm2ind
  Convert harmonic indices to vector index

  ssht_forward
  Compute forward spin spherical harmonic transform

  ssht_forward_adjoint
  Compute adjoint forward spin spherical harmonic transform

  ssht_ind2elm
  Convert vector index to harmonic indices

  ssht_inverse
  Compute inverse spin spherical harmonic transform

  ssht_inverse_adjoint
  Compute adjoint inverse spin spherical harmonic transform

  ssht_plot_harmonic
  Plot spherical harmonic coefficients

  ssht_plot_mollweide
  Plot function using Mollweide projection

  ssht_plot_sphere
  Plot function on sphere

  ssht_s2c
  Convert spherical to cartesian coordinates

  ssht_sampling
  Compute sample positions

To access the documentation for each function in Matlab, simply run: 

 >> help <function>

where <function> is the function name.

Demos

A number of demos are provided to illustrate the use of the Matlab interface. The demos start extremely simple and progressively become more complicated/flexible. 

  ssht_demo0
  Plot spherical harmonic functions on the sphere.

  ssht_demo1
  Simple demo to compute inverse and forward transform of complex
  scalar function, using simplest interface with default options.

  ssht_demo2
  Simple demo to compute inverse and forward transform of real scalar
  function, using simplest interface with default options.

  ssht_demo3
  Demo to compute inverse and forward transform of spin function,
  using standard interface with various options.

  ssht_demo4
  Demo to compute inverse and forward transform of spin function,
  using polar interface with various options.

  ssht_demo5
  Simulate a Gaussian cosmic microwave background (CMB).

  ssht_demo6
  Smooth Earth topography map by applying a Gaussian filter in
  harmonic space.

  ssht_demo7
  Integrate a band-limited function on the sphere using the
  symmetrised quadrature weights. 

  ssht_demo8
  Evaluate Wigner and spherical harmonic functions.

To access the documentation for each demo in Matlab, simply run: 

 >> help <demo>

where <demo> is the demo name.

Python interface

Once the python interface is built, you must have ssht/src/python in your python path in order to run the python functions. A number of python functions and demos illustrating their use are provided.

Functions

Usage of the SSHT python interface will most frequently require only the functions to perform forward and inverse spherical harmonic transforms (pyssht.forward and pyssht.inverse respectively). However, a number of additional functions are also provided. A full list of python functions are given here.

Demos

A number of demos are provided to illustrate the use of the python interface. The demos start extremely simple and progressively become more complicated/flexible. 

  pyssht_demo_0
  Plot spherical harmonic functions on the sphere.

  pyssht_demo_1
  Simple demo to compute inverse and forward transform of complex
  scalar function, using simplest interface with default options.

  pyssht_demo_2
  Simple demo to compute inverse and forward transform of real scalar
  function, using simplest interface with default options.

  pyssht_demo_3
  Demo to compute inverse and forward transform of spin function,
  using standard interface with various options.

  pyssht_demo_4
  Demo to compute inverse and forward transform of spin function,
  using polar interface with various options.

  pyssht_demo_5
  Smooth Earth topography map by applying a Gaussian filter in
  harmonic space.

  pyssht_demo_6
  Integrate a band-limited function on the sphere using the
  symmetrised quadrature weights.

  pyssht_demo_7
  Rotating an image on the sphere in harmonic space using the 
  Wigner matricies.

Download

We make the source code of the SSHT package available under the license described below.

SSHT can be downloaded from the following site:

Referencing

If you use SSHT for work that results in publication, please reference this site (http://www.jasonmcewen.org/) and 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).

Version

Version: 1.2b1
Release date: April 2018

Version history

License

SSHT package to perform spin spherical harmonic transforms
Copyright (C) 2011 Jason McEwen

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

About the authors

SSHT was initially written by Jason McEwen, based on collaborative work with Yves Wiaux, but significant contributions have since been made by Christopher Wallis, Martin Büttner, and Boris Leistedt.