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