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.

```
```` >> make lib`

For details on how to use the s2 library code see the documentation
below.
The s2 utility programs may be compiled by running:

```
````>> make prog`

For details on how to use the s2 utility programs see the documentation
below.
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`

```
````>> make clean`

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

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

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

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 1.1

Various updates. - Version 1.0

Initial public release. - Version 0.2

Name changed to s2. Additional functionality added. - Version 0.1

Original SPH version.

s2 package to provide object oriented functionality for functions on the sphere

Copyright (C) 2008 Jason McEwenThis 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