Module s2_wnoise_mod

module s2_wnoise_mod

        ! Uses
    use s2_types_mod
    use s2_error_mod
    use s2_distn_mod
    use s2_sky_mod
    use s2_pl_mod

        ! Types
    public type s2_wnoise

        ! Variables
    integer, public, parameter :: S2_WNOISE_TYPE_STD_CONST = 1
    integer, public, parameter :: S2_WNOISE_TYPE_STD_SKY = 2

        ! Interfaces
    public interface s2_wnoise_init

        ! Subroutines and functions
    private function s2_wnoise_init_const (std, nside, seed) result (wnoise)
    private function s2_wnoise_init_sky_file (filename_nobs, extension, sigma0, seed) result (wnoise)
    private function s2_wnoise_init_sky (nobs, sigma0, seed) result (wnoise)
    private function s2_wnoise_init_copy (orig) result (copy)
    public subroutine s2_wnoise_free (wnoise)
    private subroutine s2_wnoise_compute_std_sky (wnoise)
    public subroutine s2_wnoise_gen_sky (wnoise, seed_in)
    public subroutine s2_wnoise_conv (wnoise, beam)
    public subroutine s2_wnoise_compute_alm (wnoise, lmax, mmax)
    public subroutine s2_wnoise_map_convert (wnoise, pix_scheme)
    public subroutine s2_wnoise_downsample (wnoise, nside_down)
    public subroutine s2_wnoise_write_sky_file (wnoise, filename, comment)
    public subroutine s2_wnoise_write_nobs_file (wnoise, filename, comment)
    public subroutine s2_wnoise_write_std_file (wnoise, filename, comment)
    public function s2_wnoise_get_init (wnoise) result (init)
    public function s2_wnoise_get_nside (wnoise) result (nside)
    public function s2_wnoise_get_type (wnoise) result (type)
    public function s2_wnoise_get_sky (wnoise) result (sky)
    public function s2_wnoise_get_nobs (wnoise) result (nobs)
    public function s2_wnoise_get_sigma0 (wnoise) result (sigma0)
    public function s2_wnoise_get_std_const (wnoise) result (std_const)
    public function s2_wnoise_get_std_sky (wnoise) result (std_sky)
    public function s2_wnoise_get_beam_status (wnoise) result (beam_status)

end module 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.

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

Version: 0.1 August 2004

Description of Types

s2_wnoise

public type s2_wnoise
    private
    logical :: init = .false.
    integer :: seed
    integer :: nside = 0
    integer :: type = S2_WNOISE_TYPE_STD_CONST
    type (s2_sky) :: sky
    type (s2_sky) :: nobs
    type (s2_sky) :: std_sky
    real (kind=s2_sp) :: sigma0 = 0.0e0
    real (kind=s2_sp) :: std_const = 0.0e0
    logical :: beam_status = .false.
end type s2_wnoise

Description of Variables

S2_WNOISE_TYPE_STD_CONST

integer, public, parameter :: S2_WNOISE_TYPE_STD_CONST = 1

To specify constant noise std over the sky.

S2_WNOISE_TYPE_STD_SKY

integer, public, parameter :: S2_WNOISE_TYPE_STD_SKY = 2

To specify variable noise std over the sky.

Description of Interfaces

s2_wnoise_init

public interface s2_wnoise_init
    module procedure s2_wnoise_init_const
    module procedure s2_wnoise_init_sky_file
    module procedure s2_wnoise_init_sky
    module procedure s2_wnoise_init_copy
end interface s2_wnoise_init

Description of Subroutines and Functions

s2_wnoise_init_const

private function s2_wnoise_init_const (std, nside, seed) result (wnoise)
    real (kind=s2_sp), intent(in) :: std
    integer, intent(in) :: nside
    integer, intent(in) :: seed
    type (s2_wnoise) :: wnoise
    ! Calls: s2_error, s2_wnoise_gen_sky
end function s2_wnoise_init_const

Initialise wnoise with a constant std over the sky.

Variables:

std: Standard deviation of noise (constant over sky).
nside: Healpix resolution of sky.
seed: Seed for generating samples from uniform distribution.
wnoise: Wnoise object initialised.

Author: J. D. McEwen

Version: 0.1 August 2004

s2_wnoise_init_sky_file

private function s2_wnoise_init_sky_file (filename_nobs, extension, sigma0, seed) result (wnoise)
    character (len=*), intent(in) :: filename_nobs
    integer, intent(in) :: extension
    real (kind=s2_sp), intent(in) :: sigma0
    integer, intent(in) :: seed
    type (s2_wnoise) :: wnoise
    ! Calls: s2_error, s2_wnoise_compute_std_sky, s2_wnoise_gen_sky
end function s2_wnoise_init_sky_file

Initialise a wnoise with a std that varies over the sky. The std map is calculated from the `number of observations' field contained in the fits file read.

Notes:

The wnoise healpix sky resolution will be set to the resolution of the nobs field contained in the fits file. If a lower resolution is later required, then the map resolution map be downsampled using the routine s2_wnoise_downsample.

Variables:

filename_nobs: Name of fits file containing nobs field.
extension: Fits file extension specifying extension of nobs field in fits file.
sigma0: Noise parameter used to calculate std_sky from nobs field.
seed: Seed for generating samples from uniform distribution.
wnoise: Wnoise object initialised.

Author: J. D. McEwen

Version: 0.1 August 2004

s2_wnoise_init_sky

private function s2_wnoise_init_sky (nobs, sigma0, seed) result (wnoise)
    type (s2_sky), intent(in) :: nobs
    real (kind=s2_sp), intent(in) :: sigma0
    integer, intent(in) :: seed
    type (s2_wnoise) :: wnoise
    ! Calls: s2_error, s2_wnoise_compute_std_sky, s2_wnoise_gen_sky
end function s2_wnoise_init_sky

Initialise a wnoise with a std that varies over the sky. The std map is calculated from the `number of observations' field contained in the passed s2_sky object.

Notes:

The wnoise healpix sky resolution will be set to the resolution of the nobs field contained in the fits file. If a lower resolution is later required, then the map resolution map be downsampled using the routine s2_wnoise_downsample.

Variables:

nobs: Sky object containing nobs field.
sigma0: Noise parameter used to calculate std_sky from nobs field.
seed: Seed for generating samples from uniform distribution.
wnoise: Wnoise object initialised.

Author: J. D. McEwen

Version: 0.1 October 2005

s2_wnoise_init_copy

private function s2_wnoise_init_copy (orig) result (copy)
    type (s2_wnoise), intent(in) :: orig
    type (s2_wnoise) :: copy
    ! Calls: s2_error
end function s2_wnoise_init_copy

Initialise a wnoise object as a copy of an original wnoise object.

Variables:

orig: Original wnoise object to copy.
copy: Initialised wnoise object as a copy of orig.

Author: J. D. McEwen

Version: 0.1 August 2004

s2_wnoise_free

public subroutine s2_wnoise_free (wnoise)
    type (s2_wnoise), intent(inout) :: wnoise
    ! Calls: s2_error, s2_sky_free
end subroutine s2_wnoise_free

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

Variables:

wnoise: Wnoise object freed.

Author: J. D. McEwen

Version: 0.1 August 2004

s2_wnoise_compute_std_sky

private subroutine s2_wnoise_compute_std_sky (wnoise)
    type (s2_wnoise), intent(inout) :: wnoise
    ! Calls: s2_error, s2_sky_free, s2_sky_get_map
end subroutine s2_wnoise_compute_std_sky

Compute the std sky map from nobs field: std_map(ipix) = sigma0/sqrt(nobs(ipix))

Notes:

Object must be initialised before this routine is call. If to be called from init function then must set init status first.

Variables:

wnoise: Wnoise object to calculate std_sky of.

Author: J. D. McEwen

Version: 0.1 August 2004

s2_wnoise_gen_sky

public subroutine s2_wnoise_gen_sky (wnoise, seed_in)
    type (s2_wnoise), intent(inout) :: wnoise
    integer, optional, intent(in) :: seed_in
    ! Calls: s2_error, s2_sky_free
end subroutine s2_wnoise_gen_sky

Generate a realisation of the wnoise sky satisfying the noise properties specified by the attributes of the wnoise object.

Notes:

Object must be initialised before this routine is call. If to be called from init function then must set init status first.

Variables:

wnoise: Wnoise object to generate sky realisation for.
seed_in: Seed used to generate samples. If not present then the wnoise seed attribute is used.

Author: J. D. McEwen

Version: 0.1 August 2004

s2_wnoise_conv

public subroutine s2_wnoise_conv (wnoise, beam)
    type (s2_wnoise), intent(inout) :: wnoise
    type (s2_pl), intent(in) :: beam
    ! Calls: s2_error, s2_sky_conv
end subroutine s2_wnoise_conv

Apply a beam by convolving it with the wnoise sky.

Variables:

wnoise: Wnoise object containing sky to apply beam to.
beam: Beam to apply.

Author: J. D. McEwen

Version: 0.1 May 2005

s2_wnoise_compute_alm

public subroutine s2_wnoise_compute_alm (wnoise, lmax, mmax)
    type (s2_wnoise), intent(inout) :: wnoise
    integer, intent(in) :: lmax
    integer, intent(in) :: mmax
    ! Calls: s2_error, s2_sky_compute_alm
end subroutine s2_wnoise_compute_alm

Compute the alms of the wnoise sky at the lmax and mmax specified.

Variables:

wnoise: Wnoise object to compute alms of sky.
lmax: Healpix spherical harmonic lmax.
mmax: Healpix spherical harmonic mmax.

Author: J. D. McEwen

Version: 0.1 May 2005

s2_wnoise_map_convert

public subroutine s2_wnoise_map_convert (wnoise, pix_scheme)
    type (s2_wnoise), intent(inout) :: wnoise
    integer, intent(in) :: pix_scheme
    ! Calls: s2_error, s2_sky_map_convert
end subroutine s2_wnoise_map_convert

Convert a wnoise sky map to the specified pixelisation scheme.

Variables:

wnoise: Wnoise object to convert sky of.
pix_scheme: Pixelisation scheme to conver to sky map to.

Author: J. D. McEwen

Version: 0.1 August 2004

s2_wnoise_downsample

public subroutine s2_wnoise_downsample (wnoise, nside_down)
    type (s2_wnoise), intent(inout) :: wnoise
    integer, intent(in) :: nside_down
    ! Calls: s2_sky_downsample, s2_wnoise_compute_std_sky, s2_wnoise_gen_sky
end subroutine s2_wnoise_downsample

Downsample wnoise sky map to the specified nside_down.

Notes:

Actually generate a new wnoise realisation at the lower resolution (based on the new std map).

Variables:

wnoise: Wnoise containing sky to downsample.
nside_down: New Healpix nside to downsample to.

Author: J. D. McEwen

Version: 0.1 August 2004

s2_wnoise_write_sky_file

public subroutine s2_wnoise_write_sky_file (wnoise, filename, comment)
    type (s2_wnoise), intent(in) :: wnoise
    character (len=*), intent(in) :: filename
    character (len=*), optional, intent(in) :: comment
    ! Calls: s2_error, s2_sky_write_map_file
end subroutine s2_wnoise_write_sky_file

Write the wnoise sky to an output fits file.

Variables:

wnoise: Wnoise object to write sky of.
filename: Output fits filename.
[comment]: Optional comment to be appended to the fits file header.

Author: J. D. McEwen

Version: 0.1 August 2004

s2_wnoise_write_nobs_file

public subroutine s2_wnoise_write_nobs_file (wnoise, filename, comment)
    type (s2_wnoise), intent(in) :: wnoise
    character (len=*), intent(in) :: filename
    character (len=*), optional, intent(in) :: comment
    ! Calls: s2_error, s2_sky_write_map_file
end subroutine s2_wnoise_write_nobs_file

Write the wnoise nobs file, providing the wnoise type is S2_WNOISE_TYPE_STD_SKY (i.e. the noise std varies over the full sky).

Variables:

wnoise: Wnoise object to write nobs field of.
filename: Output fits filename.
[comment]: Optional comment to be appended to the fits file header.

Author: J. D. McEwen

Version: 0.1 August 2004

s2_wnoise_write_std_file

public subroutine s2_wnoise_write_std_file (wnoise, filename, comment)
    type (s2_wnoise), intent(in) :: wnoise
    character (len=*), intent(in) :: filename
    character (len=*), optional, intent(in) :: comment
    ! Calls: s2_error, s2_sky_write_map_file
end subroutine s2_wnoise_write_std_file

Write the wnoise std file, providing the wnoise type is S2_WNOISE_TYPE_STD_SKY (i.e. the noise std varies over the full sky).

Variables:

wnoise: Wnoise object to write std_sky of.
filename: Output fits filename.
[comment]: Optional comment to be appended to the fits file header.

Author: J. D. McEwen

Version: 0.1 August 2004

s2_wnoise_get_init

public function s2_wnoise_get_init (wnoise) result (init)
    type (s2_wnoise), intent(in) :: wnoise
    logical :: init
end function s2_wnoise_get_init

Get init variable from the passed wnoise object.

Variables:

wnoise: Wnoise object to get the variable of.
init: Object init variable returned.

Author: J. D. McEwen

Version: 0.1 August 2004

s2_wnoise_get_nside

public function s2_wnoise_get_nside (wnoise) result (nside)
    type (s2_wnoise), intent(in) :: wnoise
    integer :: nside
    ! Calls: s2_error
end function s2_wnoise_get_nside

Get nside variable from the passed wnoise object.

Variables:

wnoise: Wnoise object to get the variable of.
nside: Object nside variable returned.

Author: J. D. McEwen

Version: 0.1 August 2004

s2_wnoise_get_type

public function s2_wnoise_get_type (wnoise) result (type)
    type (s2_wnoise), intent(in) :: wnoise
    integer :: type
    ! Calls: s2_error
end function s2_wnoise_get_type

Get type variable from the passed wnoise object.

Variables:

wnoise: Wnoise object to get the variable of.
type: Object type variable returned.

Author: J. D. McEwen

Version: 0.1 August 2004

s2_wnoise_get_sky

public function s2_wnoise_get_sky (wnoise) result (sky)
    type (s2_wnoise), intent(in) :: wnoise
    type (s2_sky) :: sky
    ! Calls: s2_error
end function s2_wnoise_get_sky

Get sky variable from the passed wnoise object.

Notes:

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

Variables:

wnoise: Wnoise object to get the variable of.
sky: Object sky variable returned.

Author: J. D. McEwen

Version: 0.1 August 2004

s2_wnoise_get_nobs

public function s2_wnoise_get_nobs (wnoise) result (nobs)
    type (s2_wnoise), intent(in) :: wnoise
    type (s2_sky) :: nobs
    ! Calls: s2_error
end function s2_wnoise_get_nobs

Get nobs variable from the passed wnoise object.

Notes:

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

Variables:

wnoise: Wnoise object to get the variable of.
nobs: Object nobs variable returned.

Author: J. D. McEwen

Version: 0.1 August 2004

s2_wnoise_get_sigma0

public function s2_wnoise_get_sigma0 (wnoise) result (sigma0)
    type (s2_wnoise), intent(in) :: wnoise
    real (kind=s2_sp) :: sigma0
    ! Calls: s2_error
end function s2_wnoise_get_sigma0

Get sigma0 variable from the passed wnoise object.

Variables:

wnoise: Wnoise object to get the variable of.
sigma0: Object sigma0 variable returned.

Author: J. D. McEwen

Version: 0.1 August 2004

s2_wnoise_get_std_const

public function s2_wnoise_get_std_const (wnoise) result (std_const)
    type (s2_wnoise), intent(in) :: wnoise
    real (kind=s2_sp) :: std_const
    ! Calls: s2_error
end function s2_wnoise_get_std_const

Get std_const variable from the passed wnoise object.

Variables:

wnoise: Wnoise object to get the variable of.
std_const: Object std_const variable returned.

Author: J. D. McEwen

Version: 0.1 August 2004

s2_wnoise_get_std_sky

public function s2_wnoise_get_std_sky (wnoise) result (std_sky)
    type (s2_wnoise), intent(in) :: wnoise
    type (s2_sky) :: std_sky
    ! Calls: s2_error
end function s2_wnoise_get_std_sky

Get std_sky variable from the passed wnoise object.

Notes:

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

Variables:

wnoise: Wnoise object to get the variable of.
std_sky: Object std_sky variable returned.

Author: J. D. McEwen

Version: 0.1 August 2004

s2_wnoise_get_beam_status

public function s2_wnoise_get_beam_status (wnoise) result (beam_status)
    type (s2_wnoise), intent(in) :: wnoise
    logical :: beam_status
    ! Calls: s2_error
end function s2_wnoise_get_beam_status

Get beam_status variable from the passed wnoise object.

Variables:

wnoise: Wnoise object to get the variable of.
beam_status: Object beam_status variable returned.

Author: J. D. McEwen

Version: 0.1 May 2005