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 LeistedtThis 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
SO3 was developed by Martin Büttner, Jason McEwen, and Boris Leistedt at University College London (UCL).