create_alm*

This routine generates scalar (and tensor) $a_{\ell m}$ for a temperature (and polarisation) power spectrum read from an input FITS file. The $a_{\ell m}$ are gaussian distributed with a zero mean, and their amplitude is multiplied with the $\ell$-space window function of a gaussian beam characterized by its FWHM or an arbitrary circular beam and a pixel window read from an external file.

Location in HEALPix directory tree: src/f90/mod/alm_tools.F90 

FORMAT

call create_alm*( nsmax, nlmax, nmmax, polar, filename, rng_handle, fwhm_arcmin, alm_TGC, header[, windowfile, units, beam_file] )

Arguments appearing in italic are optional.

ARGUMENTS

name & dimensionality	kind	in/out	description
nsmax	I4B	IN	$N_{\mathrm{side}}$ of the map to be synthetized from the $a_{\ell m}$ created by this routine.
nlmax	I4B	IN	maximum $\ell$ value to be considered (MAX= $4N_{\mathrm{side}}$ if windowfile is provided).
nmmax	I4B	IN	maximum $m$ value for the $a_{\ell m}$.
polar	I4B	IN	if set to 0, only Temperature (scalar) $a_{\ell m}$ are generated using TT spectrum. If set to 1, 'conventional' polarization is added, based on EE, BB and TE spectra. If set to 2, and if the relevant information is in filename, polarization is generated assuming non-zero correlation of Curl (B) modes with Temperature (T) and Gradient (E) modes (TB and EB cross-spectra). Note that the synfast facility calls create_alm* with polar=0 or polar=1
filename(LEN=filenamelen)	CHR	IN	name of FITS file containing power spectra in the order TT, [EE, BB, TE, [TB, EB]] (terms in brackets are optional, see polar)
rng_handle	planck_rng	INOUT	structure containing information necessary to continue a random sequence initiated previously with the subroutine rand_init. Consecutive calls to create_alm* can be made after a single invocation to rand_init.
fwhm_arcmin	SP/ DP	IN	FWHM size of the gaussian beam in arcminutes.
alm_TGC(1:p,0:nlmax,0:nmmax)	SPC/ DPC	OUT	complex $a_{\ell m}$ values generated from the power spectrum in the FITS file. The first index here runs form 1:1 for temperature only, and 1:3 for polarisation. In the latter case, 1=T, 2=E, 3=B.

name & dimensionality	kind	in/out	description
header(LEN=80),dimension(60)	CHR	OUT	part of header which will be included in the FITS-file containing the map synthesised from the $a_{\ell m}$ which create_alm generates.
windowfile(LEN=filenamelen)	CHR	IN	full filename specification of the FITS file with the pixel window function (defined for $\ell\le4 N_{\mathrm{side}}$)
units(LEN=80),dimension(1:)	CHR	OUT	physical units of the created $a_{\ell m}$ (square-root of the input power spectrum units).
beam_file(LEN=filenamelen)	CHR	IN	name of the file containing the (non necessarily gaussian) window function $B_\ell$ of a circular beam. If present, it will override the argument fwhm_arcmin.

EXAMPLE:

use alm_tools, only: create_alm
use rngmod, only: rand_init, planck_rng
type(planck_rng) :: rng_handle

call rand_init(rng_handle, -1)
call create_alm(64, 128, 128, 1, 'cl.fits', rng_handle, 5.0, alm_TGC, &
& header, 'data/pixel_window_n0064.fits')

Creates scalar and tensor $a_{\ell m}$ from the power spectrum given in the file `cl.fits'. The map to be created from these $a_{\ell m}$ is assumed to have $N_{\mathrm{side}}=64$. $C_\ell$s from the power spectrum are used up to an $\ell$ value of 128. Corresponding $a_{\ell m}$ values up to l=128 and m=128 are created as gaussian distributed complex numbers. Their are drawn from a sequence of pseudo-random numbers initiated with a seed of -1. The produced $a_{\ell m}$ are convolved with a gaussian beam of FWHM 5 arcminutes and a pixel window read from 'data/pixel_window_n0064.fits'. It is assumed that after the return from this routine, a map is generated from the created $a_{\ell m}$. For this purpose, header is updated with FITS format information describing the origin and history of these $a_{\ell m}$.

MODULES & ROUTINES

This section lists the modules and routines used by create_alm*.

alm_tools

module, containing:

pow2alm_units

routine to convert from power spectrum units to $a_{\ell m}$ units

generate_beam

routine to generate beam window function

pixel_window

routine to read in pixel window function

utilities

module, containing:

die_alloc

routine that prints an error message if there is not enough space for allocation of variables.

fitstools

module, containing:

fits2cl

routine to read a FITS file containing a power spectrum.

read_dbintab

routine to read a FITS-binary file containing the pixel window functions.

head_fits

module, containing:

add_card

routine to add a keyword to a FITS header.

get_card

routine to read a keyword value from FITS header.

merge_headers

routine to merge two FITS headers.

rngmod

module, containing:

rand_gauss

function which returns a gaussian distributed random number.

RELATED ROUTINES

This section lists the routines related to create_alm*

rand_init

subroutine to initiate a random number sequence.

synfast

executable using create_alm* to synthesize CMB maps from a given power spectrum.

alm2map

Routine to transform a set of $a_{\ell m}$ created by create_alm* to a HEALPix map.

alms2fits, dump_alms

Routines to save a set of $a_{\ell m}$ in a FITS file.