Public Documentation

Collection of routines for working with coordinates on the sphere.

Calculates the bearing angle ($α$), defined as the angle between the meridian (at the first coordinate) and the great circle connecting the first coordinate to the second. Angles are measured eastward of north and will be in the range $[-π,π]$. See also bearing2.

α = bearing(θ₁, ϕ₁, θ₂, ϕ₂)

Points on the sphere are given as coordinate pairs $(θ₁,ϕ₁)$ and $(θ₂,ϕ₂)$ where $θ$ is the colatitude angle from the North Pole and $ϕ$ is the azimuthal angle, both in radians.

Examples

julia> bearing(π/2, 0.0, π/4, π/4)
0.6154797086703873

α = bearing(r₁, r₂)

Points on the sphere are given as unit vectors $r₁$ and $r₂$.

Examples

julia> bearing([1.0, 0.0, 0.0], [0.5, 0.5, sqrt(2)/2])
0.6154797086703873

Calculates the north/east vector components of the bearing angle (i.e. $δn = \cos(α), δe = \sin(α)$), defined as the angle between the meridian (at the first coordinate) and the great circle connecting the first coordinate to the second. See also bearing.

(δn, δe) = bearing2(θ₁, ϕ₁, θ₂, ϕ₂)

Points on the sphere are given as coordinate pairs $(θ₁,ϕ₁)$ and $(θ₂,ϕ₂)$ where $θ$ is the colatitude angle from the North Pole and $ϕ$ is the azimuthal angle, both in radians.

Examples

julia> bearing2(π/2, 0.0, π/4, π/4)
(0.8164965809277261, 0.5773502691896257)

(δn, δe) = bearing2(r₁, r₂)

Points on the sphere are given as unit vectors $r₁$ and $r₂$.

Examples

julia> bearing2([1.0, 0.0, 0.0], [0.5, 0.5, sqrt(2)/2])
(0.816496580927726, 0.5773502691896257)

Calculates the cosine of the inner angle ($z$) between unit vectors pointing from the center of the sphere to two points on its surface.

z = cosdistance(θ₁, ϕ₁, θ₂, ϕ₂)

Points on the sphere are given as coordinate pairs $(θ₁,ϕ₁)$ and $(θ₂,ϕ₂)$ where $θ$ is the colatitude angle from the North Pole and $ϕ$ is the azimuthal angle, both in radians.

Examples

julia> cosdistance(π/2, 0.0, π/4, π/4)
0.5

z = cosdistance(r₁, r₂)

Points on the sphere are given as unit vectors $r₁$ and $r₂$.

Examples

julia> cosdistance([1.,0.,0.], [0.5,0.5,sqrt(2)/2])
0.5

Calculates the inner angle ($σ$) between unit vectors pointing from the center of the sphere to two points on its surface.

σ = distance(θ₁, ϕ₁, θ₂, ϕ₂)

Points on the sphere are given as coordinate pairs $(θ₁,ϕ₁)$ and $(θ₂,ϕ₂)$ where $θ$ is the colatitude angle from the North Pole and $ϕ$ is the azimuthal angle, both in radians.

Examples

julia> distance(π/2, 0.0, π/4, π/4)
1.0471975511965979

σ = distance(r₁, r₂)

Points on the sphere are given as unit vectors $r₁$ and $r₂$.

Examples

julia> distance([1.,0.,0.], [0.5,0.5,sqrt(2)/2])
1.0471975511965979

Calculates a position on the sphere a given distance ($σ$, in radians) and relative bearing angle ($α$, in radians) away from a given point (measuring the eastward-of-north orientation of the great circle connecting the source and destination points with respect to the merdian passing through the source).

(θ′, ϕ′) = reckon(θ, ϕ, σ, α)

The point on the sphere is given by the colatitude-azimuth pair $(θ, ϕ)$, both given in radians.

julia> reckon(0.0, 0.0, π/2, 0.0)
(1.5707963267948966, 3.141592653589793)

julia> reckon(0.0, π/2, π/2, 0.0)
(1.5707963267948966, 4.71238898038469)

r′ = reckon(r::AbstractVector, σ, α)

The point on the sphere is given as a unit vector $r$.

julia> reckon([0.0, 0.0, 1.0], π/2, 0.0)
3-element SVector{3, Float64} with indices SOneTo(3):
 -1.0
  0.0
  6.123233995736766e-17

AbstractPixelization

The supertype of various pixelization formats.

struct ArbitraryPixelization <: AbstractPixelization

An arbitrary pixelization format (i.e. one without any implied structure) where pixel centers are given as a vector of unit vectors.

struct HealpixPixelization <: AbstractPixelization

A HEALPix pixelization of a particular resolution ($N_\mathrm{side}$). May optionally also describe a subset of the sphere, containing an explicit list of pixels to subset.

struct RADecPixelization <: AbstractPixelization

An equidistant cylindrical projection described in terms of a square grid of pixels by their right ascension (RA) and declination (Dec) coordinates (in degrees).

Exports a given instance of AbstractPixelization to a "simple" data type representation suitable for export to disk.

See also parse_pixelization.

export_pixelization(pix::ArbitraryPixelization)

Returns a 3×N matrix that describes the given set of arbitrary pixel centers, pix. See also parse_pixelization.

export_pixelization(pix::HealpixPixelization)

Returns a Dict{String} appropriate for serializing to disk that describes the given HEALPix pixelization, pix. See also parse_pixelization.

export_pixelization(pix::RADecPixelization)

Returns a Dict{String} appropriate for serializing to disk that describes the given RA/Dec pixelization, pix. See also parse_pixelization.

Parses a number of recognizable pixelization specifications, returning a subtype of CMB.AbstractPixelization.

See also export_pixelization.

parse_pixelization(pixelspec::AbstractDict{String})

Attempts to parse an AbstractDict containing a pixelization description. The dictionary is expected to contain a field "type" which specifies the pixelization scheme name, which is used to dispatch for further format-specific processing.

parse_pixelization(pixelspec::AbstractMatrix)
parse_pixelization(pixelspec::AbstractVector{SVector{3,<:Any}}})

Interprets a collection of unit 3-vectors as a set of arbitrary pixels on the sphere, returning an instance of ArbitraryPixelization. The input may be either a vector of SVector{3} unit vectors or a 3×N matrix where each column is interpreted as a single unit vector.

parse_pixelization(::Val{:healpix}, pixelspec::AbstractDict{String,<:Any})

Parses a dictionary describing a HEALPix pixelization, returning an instance of HealpixPixelization.

pixelspec is must conform to the following format to be parsed:

Dict("type" => "healpix",
     "nside" => #= Nside value =#,
     "pixels" => #= vector of HEALPix pixel indices, or if not provided implied to be a
                    full-sky grid spanning pixels `0:nside2npix(nside)-1` =#
    )

parse_pixelization(::Val{:radec}, pixelspec::AbstractDict{String})

Parses a dictionary describing an equidistance cylindrical projection given in terms of right ascension (RA) and declination (Dec) coordinates, returning an instance of RADecPixelization.

pixelspec is must conform to the following format to be parsed:

Dict("type" => "radec",
     "ra" => #= vector of uniformly-spaced pixel centers along the RA axis, in degrees =#,
     "dec" => #= vector of uniformly-spaced pixel centers along the Dec axis, in degrees =#,
     "order" => #= either "row" or "col" for row/column-major unravelling =#,
    )

pointing(pix::AbstractPixelization)

Returns a Vector of SVector{3} unit-vectors pointing to the centers of the pixels described by pix.

R, metadata = read_obsmat(filename::String; keywords...)

Read a sparse observing matrix R and the corresponding metadata metadata from filename. The metadata data will include the following fields:

• fields: a description of the Stokes fields for which the observing matrix applies — e.g. the value "QU" signals that R is the block matrix [R_QQ R_QU; R_UQ R_UU].
• pixels_right: a description of the "right-hand side" pixelization format of the observing matrix — i.e. the pixelization of a map vector $v$ for which the matrix-vector multiplication $R v$ is defined.
• pixels_left: a description of the "left-hand side" pixelication format of the observing matrix — i.e. the pixelization of a map vector $w$ which results from the matrix-vector multiplication $w = R v$.

The metadata fields are loaded from datasets named by keyword arguments of the same name. Any keyword set to nothing indicates that the corresponding data should not be loaded. The data types are format- and situation-specific. It is not an error for the named dataset to not exist, and if the dataset does not exist, the field of the metadata named tuple will be filled with the value missing.

The observing matrix dataset within the data file is given by the keyword name and defaults to "R". It is an error for the named dataset to not exist (if not nothing).

See also: write_obsmat

Extended help

Backends

The HDF5.jl storage backend is always loaded with CMB.jl and is considered the native storage format. See write_obsmat for writing a native HDF5 file to disk.

Importing observing matrices from the following additional data formats is supported via Requires.jl, which requires the user to first load the extra backend of choice.

• JLD and JLD2-flavored HDF5 files with JLD.jl (v0.12+) and JLD2.jl, respectively.
• MATLAB v5, v6, v7, and v7.3 save files with MAT.jl (v0.10+).
• scipy.sparse CSC and CSR matrices saved to HDF5 files with h5sparse. This case is supported without needing to load any extra packages.

The pixelization descriptions are imported as data format specific types. For instance, all formats support loading strings and simple numerical scalars or arrays. Additionally, JLD and JLD2 formats can load named datasets as arbitrary Julia types, MATLAB structs are deserialized as Dicts, and named HDF5 groups are read as (nested) Dicts.

read_obsmat(file::FileIO.File{format"HDF5"};
            mmap::Union{Bool,Val{true},Val{false}} = READ_OBSMAT_MMAP[],
            keywords...)

Reads an observing matrix and pixelization descriptors from an HDF5 file. The native format as written by write_obsmat as well as h5sparse-formatted data structures are supported.

With HDF5 files in the native format, the additional keyword mmap argument controls whether the observing matrix arrays are loaded via memory-mapping or not. If memory-mapped on Unix systems, the MADV_WILLNEED advice will be applied to the arrays. Additionally, on Linux systems, the memory mapping includes the MAP_POPULATE flag to pre-fault the data pages into active RAM. The default behavior is controlled by the global Ref READ_OBSMAT_MMAP.

read_obsmat(file::FileIO.File{format"JLD"}; keywords...)

Reads an observing matrix and pixelization descriptors from a JLD-formatted HDF5 file. This function is conditionally included via Requires.jl and requires the user to import JLD or using JLD first.

read_obsmat(file::FileIO.File{format"JLD2"}; keywords...)

Reads an observing matrix and pixelization descriptors from a JLD2-formatted HDF5 file. This function is conditionally included via Requires.jl and requires the user to import JLD2 or using JLD2 first.

read_obsmat(file::FileIO.File{format"MAT"}; keywords...)

Reads an observing matrix and pixelization descriptors from a MATLAB save file in v5, v6, v7, or v7.3 format. This function is conditionally included via Requires.jl and requires the user to import MAT or using MAT first.

READ_OBSMAT_MMAP = Ref{Bool}(true)

Controls the default memory mapping behavior of read_obsmat. Defaults to true.

READ_OBSMAT_MMAP_FLAGS = Ref{UnixMmap.MmapFlags}(MAP_SHARED)

Controls the flags passed to mmap when read_obsmat memory maps the observing matrix arrays. Defaults to MAP_SHARED on all systems, with Linux also including MAP_POPULATE by default.

write_obsmat(filename::String, obsmat::SparseMatrixCSC;
             obsmat_name::String = "R",
             fields = missing, fields_name::String = "fields",
             pixels_right = missing, pixels_right_name::String = "pixels_right",
             pixels_left  = missing, pixels_left_name::String  = "pixels_left")

Write an observing matrix obsmat to the HDF5 file filename. If the file exists, it will be overwritten completely (to ensure proper data alignment required for memory mapping), otherwise it will be created.

Additional metadata — pixelization descriptions pixels_right and pixels_left and an annotation of the Stokes field the observing matrix applies to fields — may also be provided; for a missing value, the description will not be written to disk.

The HDF5 dataset and group names of the observing matrix and metadata can be changed from their defaults by setting the associated *_name keywords which effect.

See also: read_obsmat

@enum Convention IAUConv HealpixConv

An enumeration to specify the two types of polarization conventions used to describe Stokes Q/U coordinate systems.

@bitflag Field TT QT UT TQ QQ UQ TU QU UU NO_FIELD=0

A bitfield for identifying combinations of Stokes fields. There are 9 subblocks, named as the Cartesian product of elements T, Q, and U:

TT  TQ  TU
QT  QQ  QU
UT  UQ  UU

const TPol = QT | UT | TQ | TU

An alias for the temperature-cross-polarization Stokes field combinations.

const Pol  = QQ | UQ | QU | UU

An alias for the polarization-only sub-blocks Stokes field combinations.