s2 package documentation

Jason McEwen

The s2 library contains functionality to support functions defined on the sky and was developed primarily for astrophysical applications. More generally, however, any arbitrary function defined on the sphere may be represented. Both real space map and harmonic space spherical harmonic representations are supported.

Basic sky representations have been extended to simulate full sky noise distributions and Gaussian cosmic microwave background realisations. Support for the representation and convolution of beams is also provided.

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

A HEALPix spherical pixelisation scheme is adopted, although this may be extended in the future to support other spherical pixelisations. The spherical harmonic transforms applied are all based on the routines provided by HEALPix.

For further details see the README.txt file.


The s2 package requires the HEALPix and CFITSIO packages. Please note that all s2 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 s2 library may be compilied by running:
>> make lib
For details on how to use the s2 library code see the documentation below.

Compiling utility programs

The s2 utility programs may be compiled by running:

>> make prog
For details on how to use the s2 utility programs see the documentation


By default, the s2 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 s2 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 s2 library is given here. Please click on the link for each class for detailed documentation.

s2_sky_mod: Provides functionality to support and manipulate a function defined on the sky(/sphere). Support is provided to representing the sky in both real (map) space and in harmonic (alm) space, and also to convert between the two representations. One may also scale, dilate, rotate, downsample and add functions defined on the sky. The sky pixelisation used is currently based on HEALPix.

s2_ylm_mod: Provides functionality to compute spherical harmonic functions.

s2_dl_mod: Functionality to compute specified plane of the Wigner dl functions. (Provided by D. J. Mortlock.)

s2_pl_mod: Provides functionality to support and manipulate a pl power spectrum.

s2_cmb_mod: Provides functionality to create a Gaussian simuated CMB map. The map is realised from Gaussain alms that satisfy the specified CMB power spectrum.

s2_wnoise_mod: Provides functionality to support white noise realisations on the sky. Noise may either be constructed from a uniform standard devaition constant over the sky or from a standard deviation map that varies over the sky depending on the number of observations at a particular position on the sky.

s2_distn_mod: Functionality to sample from uniform and Gaussian distributions.

s2_vect_mod: Provide functionality to support and rotate vectors in R^3, represented in either cartesian or spherical coordinates.

s2_types_mod: Definition of intrinsic types and constants used in the s2 library.

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

Utility programs

Utility programs based on the s2 library are listed here. More s2 programs may appear here in the future as their need becomes apparent. Please click on the link for each program for detailed documentation.

s2_alm2map: Read a HEALPix alm fits file, compute map and then write the map to a HEALPix map fits file.

s2_alm2sky: Read a HEALPix alm fits file and write the read map to a full s2_sky fits file. Compute map if requested.

s2_cl2ascii: Read a fits cl file and write out an ascii file (spectrum may be scaled to dls depending on dl_status flag).

s2_dlwrite: Write out Wigner d function values for theta=pi/2.

s2_gcmb: Generate a Gaussian CMB realisation from an input power spectrum.

s2_gcmbcoad: Generate co-added Gaussian CMB and noise realisations. Realisations are simulated for each WMAP channel by convolving with the approriate beam function and adding appropriate noise for the specific receiver. The signals from each receiver are combined to give a coadded map, using the processing pipeline specified by Komatsu et al. (2003).

s2_grf2: Simulate two Gaussian random fields (GRFs) on the sky that satisfy individual and cross power spectra. -- NOT TESTED

s2_map2alm: Read a HEALPix map fits file and write the read map to a HEALPix fits alm file.

s2_map2sky: Read a HEALPix map fits file and write the read map to a full s2_sky fits file.

s2_nmask: Generate noisy masks and computed harmonic space noise covariance matrix (not yet outputted) from a binary mask.

s2_nonzero: Count the number of non-zero values in a map. Two techniques are used. One assumes the map is binary and sums the values. The other counts the number of values above a threshold. The results are printed to the screen.

s2_plplot: Read a fit pl file and plot the values to and output postscript file.

s2_sky2alm: Read a HEALPix map fits file and write the read map to a full s2_sky fits file.

s2_sky2cl: Read a map from a fits file, compute the alms of the map and then the cl spectrum. Write the computed cl spectrum values to the standard output.

s2_sky2fsht: Read a HEALPix pixelised sky file (map or sky format) and extra an ecp (equispaced) sampled theta-phi array over the sphere for the grid used for the Fast Spherical Harmonic Transform.

s2_sky2map: Read a full s2_sky file and write the map to a HEALPix fits file.

s2_sky2plplot: Read a full fits s2_sky file and compute and plot the cl spectrum (dilate sky also if required).

s2_skyadd: Add or subtract two maps of the sky.

s2_skydown: Downsample a sky.

s2_skyerror: Compute error between two sky maps.

s2_skymask: Apply a mask (containing only ones and zeros) to a sky. The output map is the product of the mask and sky maps. If the display status is set then masked pixels of the output map are overwritten with a magic number that appears grey when plotted. Output maps producted with the display option set should only be used for display purposes, and not for any subsequent analysis.

s2_skymultiply: Multiply sky by constant scale.

s2_skyoffset: Add a constant offset to a sky.

s2_skyorder: Change the pixelisation ordering scheme of a sky.

s2_skyprod: Take the product of two maps of the sky.

s2_skyrms: Compute RMS value of sky map.

s2_skyrot: Rotate a sky.

s2_skythres: Threshold sky.

s2_skyup: Up-sample a sky.

s2_ylm: Compute spherical harmonic function on full sky.


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


The s2 package was written originally for the development of fast continuous wavelet transform algorithms on the sphere but has since evolved to provide much additional functionality. If you use the code to produce published works please reference the download site http://www.jasonmcewen.org/codes.html 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.


Author: J. D. McEwen

Version: 1.1

Version History


s2 package to provide object oriented functionality for functions on the sphere
Copyright (C) 2008 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.


JDM would like to thank Daniel Mortlock for useful discussions on the design of the library and also for providing the routines that compute dl matrices.

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

Last modified: 1 July 2008