Module cswt_swav_mod

module cswt_swav_mod

        ! Uses
    use cswt_error_mod
    use s2_types_mod
    use s2_sky_mod

        ! Types
    public type cswt_swav

        ! Variables
    integer, public, parameter :: CSWT_SWAV_DEFAULT_PIX_SCHEME = S2_SKY_RING
    character (len=*), public, parameter :: CSWT_SWAV_DEFAULT_NAME = 'Not specified'
    integer, public, parameter :: CSWT_SWAV_DILATION_DIM = 2

        ! Interfaces
    public interface cswt_swav_init

        ! Subroutines and functions
    private function cswt_swav_init_fun (fun, nside, pix_scheme_in, lmax, mmax, param, name, dilation, alpha, beta, gamma, fun_type, norm_preserve) result (swav)
    private function cswt_swav_init_sky (sky, name, dilation, alpha, beta, gamma, norm_preserve) result (swav)
    private function cswt_swav_init_file (filename, name, dilation, alpha, beta, gamma, norm_preserve) result (swav)
    private function cswt_swav_init_copy (orig) result (copy)
    public subroutine cswt_swav_free (swav)
    public subroutine cswt_swav_dilate (swav, dilation, norm_preserve_in)
    public subroutine cswt_swav_rotate (swav, alpha, beta, gamma)
    public function cswt_swav_azimuthal_bl (swav, cutoff_prop) result (mmax_min)
    public subroutine cswt_swav_compute_alm (swav, lmax, mmax, message)
    public subroutine cswt_swav_write_map_file (swav, filename, comment)
    public function cswt_swav_get_init (swav) result (init)
    public function cswt_swav_get_sky (swav) result (sky)
    public subroutine cswt_swav_get_sky_alm (swav, alm)
    public function cswt_swav_get_map_status (swav) result (map_status)
    public function cswt_swav_get_alm_status (swav) result (alm_status)
    public function cswt_swav_get_nside (swav) result (nside)
    public function cswt_swav_get_pix_scheme (swav) result (pix_scheme)
    public function cswt_swav_get_name (swav) result (name)
    public function cswt_swav_get_admiss (swav) result (admiss)
    public function cswt_swav_get_admiss_perc (swav) result (admiss_perc)
    public function cswt_swav_get_dilation (swav) result (dilation)
    public function cswt_swav_get_alpha (swav) result (alpha)
    public function cswt_swav_get_beta (swav) result (beta)
    public function cswt_swav_get_gamma (swav) result (gamma)

end module cswt_swav_mod

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

Author: J. D. McEwen (mcewen@mrao.cam.ac.uk)

Version: 0.1 - November 2004

Description of Types

cswt_swav

public type cswt_swav
    private
    logical :: init = .false.
    type (s2_sky) :: sky
    character (len=S2_STRING_LEN) :: name = trim (CSWT_SWAV_DEFAULT_NAME)
    real (kind=s2_sp) :: admiss = 0.0e0
    real (kind=s2_sp), dimension (CSWT_SWAV_DILATION_DIM) :: dilation = (/ 1.0e0, 1.0e0 /)
    real (kind=s2_sp) :: alpha = 0.0e0
    real (kind=s2_sp) :: beta = 0.0e0
    real (kind=s2_sp) :: gamma = 0.0e0
end type cswt_swav

Description of Variables

CSWT_SWAV_DEFAULT_PIX_SCHEME

integer, public, parameter :: CSWT_SWAV_DEFAULT_PIX_SCHEME = S2_SKY_RING

Default healpix pixelisation scheme.

CSWT_SWAV_DEFAULT_NAME

character (len=*), public, parameter :: CSWT_SWAV_DEFAULT_NAME = 'Not specified'

Default wavelet name if not specified.

CSWT_SWAV_DILATION_DIM

integer, public, parameter :: CSWT_SWAV_DILATION_DIM = 2

Dimension of dilation.

Description of Interfaces

cswt_swav_init

public interface cswt_swav_init
    module procedure cswt_swav_init_fun
    module procedure cswt_swav_init_sky
    module procedure cswt_swav_init_file
    module procedure cswt_swav_init_copy
end interface cswt_swav_init

Description of Subroutines and Functions

cswt_swav_init_fun

private function cswt_swav_init_fun (fun, nside, pix_scheme_in, lmax, mmax, param, name, dilation, alpha, beta, gamma, fun_type, norm_preserve) result (swav)
    interface fun
        function fun (x, phi, param) result (val)
            real (kind=s2_sp), intent(in) :: x
            real (kind=s2_sp), intent(in) :: phi
            real (kind=s2_sp), optional, intent(in), dimension (:) :: param
            real (kind=s2_sp) :: val
        end function fun
    end interface fun
    integer, intent(in) :: nside
    integer, optional, intent(in) :: pix_scheme_in
    integer, optional, intent(in) :: lmax
    integer, optional, intent(in) :: mmax
    real (kind=s2_sp), optional, intent(in), dimension (:) :: param
    character (len=*), optional, intent(in) :: name
    real (kind=s2_sp), optional, intent(in), dimension (CSWT_SWAV_DILATION_DIM) :: dilation
    real (kind=s2_sp), optional, intent(in) :: alpha
    real (kind=s2_sp), optional, intent(in) :: beta
    real (kind=s2_sp), optional, intent(in) :: gamma
    integer, optional, intent(in) :: fun_type
    logical, optional, intent(in) :: norm_preserve
    type (cswt_swav) :: swav
    ! Calls: cswt_error, cswt_swav_dilate, cswt_swav_rotate
end function cswt_swav_init_fun

Initialise a swav (spherical wavelet) from a template function defined either on the sphere or plane.

Variables:

fun: Function `pointer' to a function defined on either the sphere or the plane.
fun_type_in: Integer specifing the function type (whether function defined directly on sphere or whether defined on plane and to be numericall projected onto the sphere.
nside: Healpix sky resolution.
[pix_scheme_in]: Pixelisation scheme to create sky in (if not specified then CSWT_SWAV_DEFAULT_PIX_SCHEME is used).
[lmax]: Alm maximum l.
[mmax]: Alm maximum m.
[param]: Parameter array specifying analytic parameters for the function to be evaluated.
[name]: String specifying name of wavelet.
[dilation]: Dilation to scale template by.
[alpha]: Alpha Euler rotation angle applied to rotate the funciton defined on the sphere.
[beta]: Beta Euler rotation angle applied to rotate the funciton defined on the sphere.
[gamma]: Gamma Euler rotation angle applied to rotate the funciton defined on the sphere.
[norm_preserve]: Logical to specify whether or not a norm preserving dilation is to be performed.
swav: Initialised swav.

Author: J. D. McEwen

Version: 0.1 - November 2004

cswt_swav_init_sky

private function cswt_swav_init_sky (sky, name, dilation, alpha, beta, gamma, norm_preserve) result (swav)
    type (s2_sky), intent(in) :: sky
    character (len=*), optional, intent(in) :: name
    real (kind=s2_sp), optional, intent(in), dimension (CSWT_SWAV_DILATION_DIM) :: dilation
    real (kind=s2_sp), optional, intent(in) :: alpha
    real (kind=s2_sp), optional, intent(in) :: beta
    real (kind=s2_sp), optional, intent(in) :: gamma
    logical, optional, intent(in) :: norm_preserve
    type (cswt_swav) :: swav
    ! Calls: cswt_error, cswt_swav_dilate, cswt_swav_rotate
end function cswt_swav_init_sky

Initialise a swav (spherical wavelet) from a predefined sky.

Variables:

sky: Function defined on the sky(/sphere) to initialise the spherical wavelet.
[name]: String specifying name of wavelet.
[dilation]: Dilation to scale template by.
[alpha]: Alpha Euler rotation angle applied to rotate the funciton defined on the sphere.
[beta]: Beta Euler rotation angle applied to rotate the funciton defined on the sphere.
[gamma]: Gamma Euler rotation angle applied to rotate the funciton defined on the sphere.
[norm_preserve]: Logical to specify whether or not a norm preserving dilation is to be performed.
swav: Initialised swav.

Author: J. D. McEwen

Version: 0.1 - November 2004

cswt_swav_init_file

private function cswt_swav_init_file (filename, name, dilation, alpha, beta, gamma, norm_preserve) result (swav)
    character (len=*), intent(in) :: filename
    character (len=*), optional, intent(in) :: name
    real (kind=s2_sp), optional, intent(in), dimension (CSWT_SWAV_DILATION_DIM) :: dilation
    real (kind=s2_sp), optional, intent(in) :: alpha
    real (kind=s2_sp), optional, intent(in) :: beta
    real (kind=s2_sp), optional, intent(in) :: gamma
    logical, optional, intent(in) :: norm_preserve
    type (cswt_swav) :: swav
    ! Calls: cswt_error, s2_sky_free
end function cswt_swav_init_file

Initialise a swav (spherical wavelet) from a sky read from an input file.

Variables:

filename: Name of input file containing the function defined on the sky that is used to initialise the spherical wavelet.
[name]: String specifying name of wavelet.
[dilation]: Dilation to scale template by.
[alpha]: Alpha Euler rotation angle applied to rotate the funciton defined on the sphere.
[beta]: Beta Euler rotation angle applied to rotate the funciton defined on the sphere.
[gamma]: Gamma Euler rotation angle applied to rotate the funciton defined on the sphere.
[norm_preserve]: Logical to specify whether or not a norm preserving dilation is to be performed.
swav: Initialised swav.

Author: J. D. McEwen

Version: 0.1 - November 2004

cswt_swav_init_copy

private function cswt_swav_init_copy (orig) result (copy)
    type (cswt_swav), intent(in) :: orig
    type (cswt_swav) :: copy
    ! Calls: cswt_error
end function cswt_swav_init_copy

Initialise a new swav (spherical wavelet) as a copy of another swav.

Variables:

orig: The original swav to copy.
copy: The initialised swav copied from the original.

Author: J. D. McEwen

Version: 0.1 - November 2004

cswt_swav_free

public subroutine cswt_swav_free (swav)
    type (cswt_swav), intent(inout) :: swav
    ! Calls: cswt_error, s2_sky_free
end subroutine cswt_swav_free

Free all data associated with an initialised swav and reset all other attributes.

Variables:

swav: The swacv to be freed.

Author: J. D. McEwen

Version: 0.1 - November 2004

cswt_swav_dilate

public subroutine cswt_swav_dilate (swav, dilation, norm_preserve_in)
    type (cswt_swav), intent(inout) :: swav
    real (kind=s2_sp), intent(in), dimension (CSWT_SWAV_DILATION_DIM) :: dilation
    logical, optional, intent(in) :: norm_preserve_in
    ! Calls: cswt_error, s2_sky_dilate
end subroutine cswt_swav_dilate

Dilate the spherical wavelet and update the dilation parameter. Only a mother wavelet with dilation of one may be dilated (otherwise a different dilation would have to be performed to give the correct final dilation).

Notes:

If dilation value is set to one then no dilation performed and routine simply exists. This is useful for the case where only the wavelet alms are defined and not the map. Then routine may be called as normal but nothing will happen so easy to generalise parent code.

Variables:

swav: Spherical wavelet dilated.
dilation: Dilation value.
[norm_preserve_in]: Logical to specify whether or not a norm preserving dilation is to be performed.

Author: J. D. McEwen

Version: 0.1 - November 2004

cswt_swav_rotate

public subroutine cswt_swav_rotate (swav, alpha, beta, gamma)
    type (cswt_swav), intent(inout) :: swav
    real (kind=s2_sp), intent(in) :: alpha
    real (kind=s2_sp), intent(in) :: beta
    real (kind=s2_sp), intent(in) :: gamma
    ! Calls: cswt_error, s2_sky_rotate
end subroutine cswt_swav_rotate

Rotate a spherical wavelet. Only an originally non-rotated wavelet may be rotated (otherwise a different rotation would have to be performed to give the correct final rotation).

Variables:

swav: Spherical wavelet rotated.
alpha: Alpha Euler rotation angle applied to rotate the funciton defined on the sphere.
beta: Beta Euler rotation angle applied to rotate the funciton defined on the sphere.
gamma: Gamma Euler rotation angle applied to rotate the funciton defined on the sphere.

Author: J. D. McEwen

Version: 0.1 - November 2004

cswt_swav_azimuthal_bl

public function cswt_swav_azimuthal_bl (swav, cutoff_prop) result (mmax_min)
    type (cswt_swav), intent(inout) :: swav
    real (kind=s2_sp), optional, intent(in) :: cutoff_prop
    integer :: mmax_min
    ! Calls: cswt_error
end function cswt_swav_azimuthal_bl

Find azimuthal band limit of wavelet. Finds lowest m' value such that cutoff_prop*100 percent of the cm power is contained in the alms with m index below m'.

Notes:

Only successful if alms for the sky are already computed. Cannot mmax may not be defined.

Variables

swav: Sky to find azimuthal band limit for.
[cutoff_prop]: Cutoff proportion to use when finding azimuthal band limit. If not specified default value is used.
mmax_min: The azimuthal band limit found.

Author: J. D. McEwen

Version: 0.1 May 2005

cswt_swav_compute_alm

public subroutine cswt_swav_compute_alm (swav, lmax, mmax, message)
    type (cswt_swav), intent(inout) :: swav
    integer, intent(in) :: lmax
    integer, intent(in) :: mmax
    logical, optional, intent(in) :: message
    ! Calls: cswt_error, s2_sky_compute_alm
end subroutine cswt_swav_compute_alm

Compute the spherical wavelet sky alms.

Variables:

swav: Spherical wavelet to compute alms of.
lmax: Spherical harmonic lmax to compute alms up to.
mmax: Spherical harmoinc mmax to compute alms up to.

Author: J. D. McEwen

Version: 0.1 - November 2004

cswt_swav_write_map_file

public subroutine cswt_swav_write_map_file (swav, filename, comment)
    type (cswt_swav), intent(in) :: swav
    character (len=*), intent(in) :: filename
    character (len=*), optional, intent(in) :: comment
    ! Calls: cswt_error, s2_sky_write_map_file
end subroutine cswt_swav_write_map_file

Write the spherical wavelet sky to an output file.

Variables:

swav: Spherical wavelet containing sky to write to file.
filename: Name of the output fits file.
[comment]: Optional additional comment to be added to the fits file header.

Author: J. D. McEwen

Version: 0.1 - November 2004

cswt_swav_get_init

public function cswt_swav_get_init (swav) result (init)
    type (cswt_swav), intent(in) :: swav
    logical :: init
end function cswt_swav_get_init

Get init variable from the passed swav.

Variables:

swav: Spherical wavelet object to get copy of variable of.
init: Copy of object init variable extracted.

Author: J. D. McEwen

Version: 0.1 - November 2004

cswt_swav_get_sky

public function cswt_swav_get_sky (swav) result (sky)
    type (cswt_swav), intent(in) :: swav
    type (s2_sky) :: sky
    ! Calls: cswt_error
end function cswt_swav_get_sky

Get sky variable from the passed swav.

Notes:

Initialises a new sky as a copy of the swav sky.
The returned sky is subsequently independed of the sky stored herein and should be freed by the calling routine at some point.

Variables:

swav: Spherical wavelet object to get copy of variable of.
sky: Copy of sky extracted.

Author: J. D. McEwen

Version: 0.1 - November 2004

cswt_swav_get_sky_alm

public subroutine cswt_swav_get_sky_alm (swav, alm)
    type (cswt_swav), intent(in) :: swav
    complex (kind=s2_spc), intent(out), dimension (:,:) :: alm
    ! Calls: cswt_error, s2_sky_get_alm
end subroutine cswt_swav_get_sky_alm

Get alm of the swav sky.

Variables:

swav: pherical wavelet object to get copy of variable of.
alm(:,:): Object alm variable returned. Space must already be allocated.

Author: J. D. McEwen

Version: 0.1 July 2005

cswt_swav_get_map_status

public function cswt_swav_get_map_status (swav) result (map_status)
    type (cswt_swav), intent(in) :: swav
    logical :: map_status
    ! Calls: cswt_error
end function cswt_swav_get_map_status

Get map_status of the sky of the passed swav. Note that the map status is stored within the wavelet sky object.

Variables:

swav: Spherical wavelet object to get map_status of.
map_status: Map status of the wavelet sky.

Author: J. D. McEwen

Version: 0.1 - April 2005

cswt_swav_get_alm_status

public function cswt_swav_get_alm_status (swav) result (alm_status)
    type (cswt_swav), intent(in) :: swav
    logical :: alm_status
    ! Calls: cswt_error
end function cswt_swav_get_alm_status

Get alm_status of the sky of the passed swav. Note that the alm status is stored within the wavelet sky object.

Variables:

swav: Spherical wavelet object to get alm_status of.
alm_status: Alm status of the wavelet sky.

Author: J. D. McEwen

Version: 0.1 - April 2005

cswt_swav_get_nside

public function cswt_swav_get_nside (swav) result (nside)
    type (cswt_swav), intent(in) :: swav
    integer :: nside
    ! Calls: cswt_error
end function cswt_swav_get_nside

Get nside of the sky of the passed swav. Note that the alm status is stored within the wavelet sky object.

Variables:

swav: Spherical wavelet object to get nside of.
nside: Nside of the wavelet sky.

Author: J. D. McEwen

Version: 0.1 - April 2005

cswt_swav_get_pix_scheme

public function cswt_swav_get_pix_scheme (swav) result (pix_scheme)
    type (cswt_swav), intent(in) :: swav
    integer :: pix_scheme
    ! Calls: cswt_error
end function cswt_swav_get_pix_scheme

Get pix_scheme of the sky of the passed swav. Note that the alm status is stored within the wavelet sky object.

Variables:

swav: Spherical wavelet object to get pix_scheme of.
pix_scheme: Pix_scheme of the wavelet sky.

Author: J. D. McEwen

Version: 0.1 - April 2005

cswt_swav_get_name

public function cswt_swav_get_name (swav) result (name)
    type (cswt_swav), intent(in) :: swav
    character (len=S2_STRING_LEN) :: name
    ! Calls: cswt_error
end function cswt_swav_get_name

Get name variable from the passed swav.

Variables:

swav: Spherical wavelet object to get copy of variable of.
name: Copy of object name variable extracted.

Author: J. D. McEwen

Version: 0.1 - November 2004

cswt_swav_get_admiss

public function cswt_swav_get_admiss (swav) result (admiss)
    type (cswt_swav), intent(in) :: swav
    real (kind=s2_sp) :: admiss
    ! Calls: cswt_error
end function cswt_swav_get_admiss

Get normalised numerical admissibility of the passed swav.

Variables:

swav: Spherical wavelet object to get copy of variable of.
admiss: Copy of object admiss varaible extracted.

Author: J. D. McEwen

Version: 0.1 - November 2004

cswt_swav_get_admiss_perc

public function cswt_swav_get_admiss_perc (swav) result (admiss_perc)
    type (cswt_swav), intent(in) :: swav
    real (kind=s2_sp) :: admiss_perc
    ! Calls: cswt_error
end function cswt_swav_get_admiss_perc

Get admissibility percentage of the passed swav.

Notes:

Only the normalised admissibility value is stored as a spherical wavelet attribute. The admissibility percentage is calculated from this when required.

Variables:

swav: Spherical wavelet to calculate admissibility percentage of.
admiss_perc: Admissibility percentage calculated.

Author: J. D. McEwen

Version: 0.1 - November 2004

cswt_swav_get_dilation

public function cswt_swav_get_dilation (swav) result (dilation)
    type (cswt_swav), intent(in) :: swav
    real (kind=s2_sp), dimension (CSWT_SWAV_DILATION_DIM) :: dilation
    ! Calls: cswt_error
end function cswt_swav_get_dilation

Get dilation variable from the passed swav.

Variables:

swav: Spherical wavelet object to get copy of variable of.
dilation: Copy of object dilation variable extracted.

Author: J. D. McEwen

Version: 0.1 - November 2004

cswt_swav_get_alpha

public function cswt_swav_get_alpha (swav) result (alpha)
    type (cswt_swav), intent(in) :: swav
    real (kind=s2_sp) :: alpha
    ! Calls: cswt_error
end function cswt_swav_get_alpha

Get alpha Euler angle from the passed swav.

Variables:

swav: Spherical wavelet object to get copy of variable of.
alpha: Copy of object alpha Euler angle variable extracted.

Author: J. D. McEwen

Version: 0.1 - November 2004

cswt_swav_get_beta

public function cswt_swav_get_beta (swav) result (beta)
    type (cswt_swav), intent(in) :: swav
    real (kind=s2_sp) :: beta
    ! Calls: cswt_error
end function cswt_swav_get_beta

Get beta Euler angle from the passed swav.

Variables:

swav: Spherical wavelet object to get copy of variable of.
beta: Copy of object beta Euler angle variable extracted.

Author: J. D. McEwen

Version: 0.1 - November 2004

cswt_swav_get_gamma

public function cswt_swav_get_gamma (swav) result (gamma)
    type (cswt_swav), intent(in) :: swav
    real (kind=s2_sp) :: gamma
    ! Calls: cswt_error
end function cswt_swav_get_gamma

Get gamma Euler angle from the passed swav.

Variables:

swav: Spherical wavelet object to get copy of variable of.
gamma: Copy of object gamma Euler angle variable extracted.

Author: J. D. McEwen

Version: 0.1 - November 2004