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
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.
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.
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.
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 the python interface run:
>> python setup.py build_ext --inplace
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>
the harmonic band-limit and spin number, respectively, of your test.
To check the version and build numbers of your version run:
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.
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.
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
Usage of the SSHT Matlab interface will most
frequently require only the functions to perform forward and inverse
spherical harmonic transforms (
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>
<function> is the function name.
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>
<demo> is the demo name.
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
Usage of the SSHT python interface will most
frequently require only the functions to perform forward and inverse
spherical harmonic transforms (
pyssht.inverse respectively). However, a number of
additional functions are also provided. A full list of python
functions are given here.
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.
We make the source code of the SSHT package available under the license described below.
SSHT can be downloaded from the following site:
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).
Release date: April 2017
- 1.1b1 (April 2017): Python interface added and support for C99 standard.
- 1.0b1 (31 October 2011): Public release of first beta.
- 0.2 (20 May 2011): Fast adjoint algorithms added.
- 0.1 (5 March 2011): First private release.
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 2 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, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.