FastCSWT package documentation

Jason McEwen

The FastCSWT package provides functionality to perform a directional continuous wavelet transform on the sphere. The transform is based on the construction of the continuous spherical wavelet transform (CSWT) developed by Antoine and Vanderghynest 1999. A fast implementation of the CSWT (based on the fast spherical convolution developed by Wandelt and Gorski 2001) is also provided. The fast algorithm in the context of the CSWT, and as implemented in this package, is described in our paper:

J. D. McEwen, M. P. Hobson, D. J. Mortlock, and A. N. Lasenby. Fast directional continuous spherical wavelet transform algorithms. IEEE Trans. Sig. Proc., 55(2):520-529, 2007.

The library design is based on object-oriented principles and is implemented in Fortran 90. Generally one must instantiate a class object using the corresponding init routines. The instatiated object should be freed once it is no longer required with the corresponding free routine (this deallocates all memory associated with the object).

For further details see the README.txt file.

Installation

The FastCSWT package requires the S2, HEALPix, CFITSIO and FFTW 2.1.5 packages. Please note that all FastCSWT code is written in Fortran 90 and a suitable Fortran compiler will be required.

Compiling library

Before compiling you may 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 then the FastCSWT library may be compilied by running:

>> make lib

For details on how to use the FastCSWT library code see the documentation below .

Compiling utility programs

The FastCSWT utility programs may be compiled by running:

>> make prog

For details on how to use the FastCSWT utility programs see the documentation below .

Documentation

By default, the FastCSWT code ships with only this single documentation page. The remainder of the documentation is automatically generated from the source code using f90doc. Please ensure that you have f90doc installed in order to generate this documentation. Once f90doc is installed the documentation may be generated by running:

>> make docs

Cleaning up

To clean up your version of the FastCSWT code and return all code to its original state run:

>> make clean

To remove all documentation, except the front page (i.e. this file), run:

>> make cleandocs

Library classes

An overview of the classes that comprise the FastCSWT library is given here. Please click on the link for each class for detailed documentation.

cswt_tr_mod: Provides functionality to support and compute the directional spherical wavelet transform. In addition the mother wavelet, the dilation values and all wavelet parameters are stored herein. The resulting wavelet coefficients for each dilation are sampled on an ecp (equi-sampled) alpha-beta-gamma Euler angle grid. Functionality is also provided to convert the alpha-beta dimensions to Healpix sky representations and vice versa.

cswt_swav_mod: Provides functionality to support and manipulate a spherical wavelet. The spherical wavelet data structure includes the wavelet sky plus its parameters.

cswt_tmpl_mod: Contains definitions of template functions defined on both the sky and the plane used to initialise spherical wavelets. The functions defined on the plane are projected onto the sphere numerically, whereas those functions defined on the sphere have already been analytically projected from the plane.

cswt_error_mod: Functionality to handle errors that may occur in the FastCSWT library. Public FastCSWT error codes are defined, with corresponding private error comments and default halt execution status.

Utility programs

A number of generic programs based on the FastCSWT library have been written. Please click on the link for each program for detailed documentation.

cswt_analysis: Perform fast directional continuous spherical wavelet transform.

cswt_mask_apply: Apply an extended coefficient exclusion mask to wavelet coefficients.

cswt_mask_copy: Generate a coefficient exclusion mask defined in the ecp wavelet coefficient domain by simply converting a list of Healpix sky mask to the wavelet domain.

cswt_mask_gen: Generate an extended coefficient exclusion mask defined in the ecp wavelet coefficient domain from an original mask defined on the sky and the spherical wavelet transform of the original mask.

cswt_mask_invert: Invert a coefficient mask by converting ones to zeros, and zeros to ones.

cswt_mask_nonzero: Compute number of effective coefficients in an extended coefficient exclusion mask and write results to either the standard output or to a file.

cswt_mask_nonzero_weight: Compute the weighted number of effecitve coefficients in the extended coefficient mask. Weights for each pixel are given by the size of the pixel on the sky for the ECP wavelet coefficient domain.

cswt_plot_swav: Plot spherical wavelet for a range of dilations.

cswt_swav_azbandlim: Determine azimuthal band limit of wavelet.

cswt_tr2sky: Convert a spherical wavelet transform fits file (ecp sampled) to a sky Healpix fits file. Just the sky corresponding to a specified dilation and orientation index may be written, or skies corresponding to all dilations and orientations may be written.

cswt_tr_nsigma: Convert wavelet coefficients to nsigma values. The coefficient map for each dilation is considered; the mean for each dilation is subtracted, before dividing by the sigma value computed for that dilation. Note that the mean and sigma are only computed over the non-masked pixels.

Support

For support or to report any bugs please contact Jason McEwen.

Reference

If you use the code to produce published works please reference the download site http://www.jasonmcewen.org and our related paper:

J. D. McEwen, M. P. Hobson, D. J. Mortlock, and A. N. Lasenby. Fast directional continuous spherical wavelet transform algorithms. IEEE Trans. Sig. Proc., 55(2):520-529, 2007.

Version

Author: J. D. McEwen

Version: 1.0 - July 2008

Version History

Version 1.0
Initial public release.
Version 0.4
Bug in fft_real fast cswt routine (which exploits conjugate symmetry) fixed. Shifts were correct; data was simply copied out incorrectly.
Version 0.3
Functionality added to exploit conjugate symmetry of Tmmm matrix. FFTW routine used to do inverse Fourier transform. Reduces memory and computation time both by a factor of two!
Version 0.2
FastCSWT library completely redesigned and rewritten with an object oriented focus. Now based on the object oriented S2 library for handling functions defined on the sphere. Additional utility programs written. Code documentation also addded.
Version 0.1
First prototype design. Written while algorithms and code were developed.

License

FastCSWT package to provide functionality to perform a directional continuous wavelet transform on the sphere
Copyright (C) 2005 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.

Acknowledgements

JDM would like to thank Daniel Morlet for providing the code base for the implementation of Wandelt and Gorski's fast spherical convolution, as well as for useful discussions.

This documentation has been generated largely by f90doc, with some minor modifications.

Last modified: 1 July 2008