Introduction

The SO3 code provides functionality to perform fast and exact Wigner transforms based on the sampling theorem on the rotation group derived in McEwen et al (2015).

This documentation outlines the various harmonic transforms supported in SO3, before describing installation details and documenting the C, and Matlab source code. Reference, version, and license information then follows.

Installation

The SO3 package contains a C implementations and a Matlab interface to the C implementation.

Dependencies

SO3 requires the FFTW and the SSHT package. Obviously suitable C compilers will be required to build the implementation. Both C and Matlab mex compilers will be required to build the Matlab interface to the C implementation.

Compiling

A makefile is provided to build the code. 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, SO3 may be compiled by running:

 >> make all

This will build the library, unit tests, 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 SO3. To build the library only run:

 >> make lib

To build the unit tests run:

 >> make unittest

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

Testing

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

 >> make runtest

If SO3 is installed correctly the test program should run and print test results to the terminal. The test program performs an inverse Wigner transform of a random signal, followed by a forward transform. The error between the original and recovered Wigner 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/so3_test <L> <N> <L0>

where <L> and <N> are the harmonic and orientational band-limit, respectively, and <L0> is the lower harmonic band-limit of your test.

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

 >> ./bin/c/so3_about 

Documentation

The SO3 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 SO3 code and remove all builds run:

 >> make clean

To remove all source documentation run:

 >> make cleandoc

Source code documentation

SO3 ships with source documentation that is generated by doxygen. Documentation is available here for the C implementation. 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 so3/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 SO3 Matlab interface will most frequently require only the functions to perform forward and inverse Wigner transforms (so3_forward and so3_inverse respectively). However, a number of additional functions are also provided. A full list of Matlab functions, with brief descriptions are given here:


  so3_elmn2ind
  Convert harmonic indices to vector index

  so3_forward
  Compute forward Wigner transform

  so3_forward_direct
  Compute forward Wigner transform using direct method

  so3_ind2elmn
  Convert vector index to harmonic indices

  so3_inverse
  Compute inverse Wigner transform

  so3_inverse_direct
  Compute inverse Wigner transform using direct method

  so3_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:

  so3_demo_error_timing
  Create timing and error plots of round-trip transform.

  so3_demo_plot_wigner
  Use SO3 to plot Wigner functions on SO(3).

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

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

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

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

  so3_demo_compact_storage
  Demo to compute inverse and forward transform of complex
  scalar function, using compact storage.

  so3_demo_storage_order
  Demo to compute inverse and forward transform of complex
  function, storing the flmn for n = -N+1 first.

  so3_demo_lower_band_limit
  Demo to compute inverse and forward transform of complex
  function, using a non-zero lower harmonic band-limit - i.e. only
  harmonic coefficients with L greater than or equal to some L0
  are non-zero.

  so3_demo_even_n
  Demo to compute inverse and forward transform of complex
  function, using only harmonic coefficients with even n.

  so3_demo_symmetric_sampling
  Demo to compute inverse and forward transform of complex
  function, using a symmetrically sampled signal.

  so3_demo_covariance
  This demo runs a series of forward transforms from random coefficients
  and compares the transformed signal's covariance with the theoretical
  prediction.
  

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

 >> help <demo>

where <demo> is the demo name.

Download

We make the source code of the SO3 package available under the license described below. It can be downloaded from the following site:

Referencing

If you use SO3 for work that results in publication, please reference this site (http://www.jasonmcewen.org/) and our related academic paper:

A novel sampling theorem on the rotation group. J. D. McEwen, M. Büttner, B. Leistedt, H. V. Peiris, Y. Wiaux

License

SO3 package to perform Wigner transforms
Copyright (C) 2014-2015 Martin Büttner, Jason McEwen, and Boris Leistedt

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.

About the authors

SO3 was developed by Martin Büttner, Jason McEwen, and Boris Leistedt at University College London (UCL).