## 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 the python interface run:

>> python setup.py build_ext --inplace

#### 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

- 1.2b1 (April 2018): Support for linking with C++.
- 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.

## License

SSHT package to perform spin spherical harmonic transforms

Copyright (C) 2011 Jason McEwenThis 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.

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