SSHT.jl: Fast and exact spin spherical harmonic transforms

This package is a Julia wrapper for the SSHT library. It calculates spin spherical harmonic transforms.

Most functions come in two versions, one that mutates its arguments and one that allocates its output.

Spin-weighted Spherical Harmonic transforms

The functions with dh in their names use the Driscoll & Healy quadrature points. With L = lmax+1 modes there are nphi * ntheta quadrature points on the sphere, with nphi = 2L-1 and ntheta = 2L. The points are equispaced in the angles theta (latitude) and phi (longitude), and they straddle (avoid) the poles.

SSHT.core_dh_inverse_sov! — Function

SSHT.core_dh_inverse_sov!(f::AbstractArray{Complex{Float64},2},
                          flm::AbstractVector{Complex{Float64}},
                          L::Integer,
                          spin::Integer,
                          verbosity::Integer=0)

Evaluate spin-weighted spherical harmonic coefficients flm with spin-weight spin. L = lmax+1 is the number of modes in flm.

The arrays flm and f must have the following sizes:

nphi = SSHT.sampling_dh_nphi(L)
ntheta = SSHT.sampling_dh_ntheta(L)
length(flm) == L^2
size(f) == (nphi, ntheta)

See the SSHT reference for details.

See also: SSHT.core_dh_inverse_sov, SSHT.core_dh_inverse_sov_real!, SSHT.core_dh_forward_sov!.

SSHT.core_dh_inverse_sov — Function

f = SSHT.core_dh_inverse_sov(flm::AbstractVector{Complex{Float64}},
                             L::Integer,
                             spin::Integer,
                             verbosity::Integer=0)
f::Array{Complex{Float64},2}

Evaluate spin-weighted spherical harmonic coefficients flm with spin-weight spin. L = lmax+1 is the number of modes in flm.

The array flm must have the length L^2. The result f will have the following size:

nphi = SSHT.sampling_dh_nphi(L)
ntheta = SSHT.sampling_dh_ntheta(L)
size(f) == (nphi, ntheta)

See the SSHT reference for details.

See also: SSHT.core_dh_inverse_sov!, SSHT.core_dh_inverse_sov_real, SSHT.core_dh_forward_sov.

SSHT.core_dh_inverse_sov_real! — Function

SSHT.core_dh_inverse_sov_real!(f::AbstractArray{Float64,2},
                               flm::AbstractVector{Complex{Float64}},
                               L::Integer,
                               spin::Integer,
                               verbosity::Integer=0)

Evaluate spin-weighted spherical harmonic coefficients flm with spin-weight spin. L = lmax+1 is the number of modes in flm. The result f is real-valued.

The arrays flm and f must have the following sizes:

nphi = SSHT.sampling_dh_nphi(L)
ntheta = SSHT.sampling_dh_ntheta(L)
length(flm) == L^2
size(f) == (nphi, ntheta)

See the SSHT reference for details.

See also: SSHT.core_dh_inverse_sov_real, SSHT.core_dh_inverse_sov!, SSHT.core_dh_forward_sov_real!.

SSHT.core_dh_inverse_sov_real — Function

f = SSHT.core_dh_inverse_sov_real(flm::AbstractVector{Complex{Float64}},
                                  L::Integer,
                                  spin::Integer,
                                  verbosity::Integer=0)
f::Array{Float64,2}

Evaluate spin-weighted spherical harmonic coefficients flm with spin-weight spin. L = lmax+1 is the number of modes in flm. The result f is real-valued.

The array flm must have the length L^2. The result f will have the following size:

nphi = SSHT.sampling_dh_nphi(L)
ntheta = SSHT.sampling_dh_ntheta(L)
size(f) == (nphi, ntheta)

See the SSHT reference for details.

See also: SSHT.core_dh_inverse_sov_real!, SSHT.core_dh_inverse_sov, SSHT.core_dh_forward_sov_real.

SSHT.core_dh_forward_sov! — Function

SSHT.core_dh_forward_sov!(flm::AbstractVector{Complex{Float64}},
                          f::AbstractArray{Complex{Float64},2},
                          L::Integer,
                          spin::Integer,
                          verbosity::Integer=0)

Calculate spin-weighted spherical harmonic coefficients with spin-weight spin flm from grid point values f. L = lmax+1 is the number of modes in flm.

The arrays flm and f must have the following sizes:

nphi = SSHT.sampling_dh_nphi(L)
ntheta = SSHT.sampling_dh_ntheta(L)
length(flm) == L^2
size(f) == (nphi, ntheta)

Use SSTH.sampling_elm2ind to access individual modes in the flm array.

See the SSHT reference for details.

See also: SSHT.core_dh_forward_sov, SSHT.core_dh_forward_sov_real!, SSHT.core_dh_inverse_sov!.

SSHT.core_dh_forward_sov — Function

flm = SSHT.core_dh_forward_sov(fl:AbstractVector{Complex{Float64}},
                               L::Integer,
                               spin::Integer,
                               verbosity::Integer=0)
flm::Vector{Complex{Float64}}

Calculate spin-weighted spherical harmonic coefficients flm with spin-weight spin from grid point values f. L = lmax+1 is the number of modes in flm.

The array flm will have length L^2. The input f must have the following size:

nphi = SSHT.sampling_dh_nphi(L)
ntheta = SSHT.sampling_dh_ntheta(L)
size(f) == (nphi, ntheta)

Use SSTH.sampling_elm2ind to access individual modes in the flm array.

See the SSHT reference for details.

See also: SSHT.core_dh_forward_sov!, SSHT.core_dh_forward_sov_real, SSHT.core_dh_inverse_sov.

SSHT.core_dh_forward_sov_real! — Function

SSHT.core_dh_forward_sov_real!(flm::AbstractVector{Complex{Float64}},
                               f::AbstractArray{Float64,2},
                               L::Integer,
                               spin::Integer,
                               verbosity::Integer=0)

Calculate spin-weighted spherical harmonic coefficients flm with spin-weight spin from real-valued grid point values f. L = lmax+1 is the number of modes in flm.

The arrays flm and f must have the following sizes:

nphi = SSHT.sampling_dh_nphi(L)
ntheta = SSHT.sampling_dh_ntheta(L)
length(flm) == L^2
size(f) == (nphi, ntheta)

Use SSTH.sampling_elm2ind to access individual modes in the flm array.

See the SSHT reference for details.

See also: SSHT.core_dh_forward_sov_real, SSHT.core_dh_forward_sov!, SSHT.core_dh_inverse_sov_real!.

SSHT.core_dh_forward_sov_real — Function

flm = SSHT.core_dh_inverse_sov_real(f::AbstractVector{Float64},
                                    L::Integer,
                                    spin::Integer,
                                    verbosity::Integer=0)
f::Array{Complex{Float64},2}

Calculate spin-weighted spherical harmonic coefficients flm with spin-weight spin from real-valued grid point values f. L = lmax+1 is the number of modes in flm.

The array flm must have the length L^2. The result f will have the following size:

nphi = SSHT.sampling_dh_nphi(L)
ntheta = SSHT.sampling_dh_ntheta(L)
size(f) == (nphi, ntheta)

Use SSTH.sampling_elm2ind to access individual modes in the flm array.

See the SSHT reference for details.

See also: SSHT.core_dh_forward_sov_real!, SSHT.core_dh_forward_sov, SSHT.core_dh_inverse_sov_real.

Derivatives ð (eth) and ð̄ (eth-bar)

See Wikipedia for the definition of these operators.

SSHT.eth! — Function

eth!(ðflm::AbstractVector, flm::AbstractVector, L::Integer, spin::Integer)

Calculate the ð (eth) derivative of the spin-weighted spherical harmonic coefficients flm with spin weight s. L = lmax+1 is the number of modes in flm. The result has spin weight s+1.

The arrays ðflm and flm must have length L^2.

See Wikipedia for a definition of the ð (eth) operator.

See also: SSHT.eth, SSHT.ethbar!, SSHT.core_dh_transform_sov!, SSHT.core_dh_inverse_sov!.

SSHT.eth — Function

ðflm = eth(flm::AbstractVector, L::Integer, spin::Integer)
ðflm::AbstractVector

Calculate the ð (eth) derivative of the spin-weighted spherical harmonic coefficients flm with spin weight s. L = lmax+1 is the number of modes in flm. The result has spin weight s+1.

The array flm must have length L^2. The result ðflm will also have length L^2.

See Wikipedia for a definition of the ð (eth) operator.

See also: SSHT.eth, SSHT.ethbar!, SSHT.core_dh_transform_sov!, SSHT.core_dh_inverse_sov!.

SSHT.ethbar! — Function

ethbar!(ð̄flm::AbstractVector, flm::AbstractVector, L::Integer, spin::Integer)

Calculate the ð̄ (eth-bar) derivative of the spin-weighted spherical harmonic coefficients flm with spin weight s. L = lmax+1 is the number of modes in flm. The result has spin weight s-1.

The arrays ð̄flm and flm must have length L^2.

See Wikipedia for a definition of the ð̄ (eth-bar) operator.

See also: SSHT.ethbar, SSHT.eth!, SSHT.core_dh_transform_sov!, SSHT.core_dh_inverse_sov!.

SSHT.ethbar — Function

ð̄flm = ethbar(flm::AbstractVector, L::Integer, spin::Integer)
ð̄flm::AbstractVector

Calculate the ð̄ (eth) derivative of the spin-weighted spherical harmonic coefficients flm with spin weight s. L = lmax+1 is the number of modes in flm. The result has spin weight s-1.

The array flm must have length L^2. The result ð̄flm will also have length L^2.

See Wikipedia for a definition of the ð (eth) operator.

See also: SSHT.ethbar, SSHT.eth!, SSHT.core_dh_transform_sov!, SSHT.core_dh_inverse_sov!.

Helper functions

SSHT.sampling_dh_n — Function

n = sampling_dh_n(L::Integer)
n::Int

Total number of unique collocation points for L = lmax+1 modes that. (If the collocation scheme places points onto the poles, then not all collocation points are unique.)

See also: SSHT.sampling_dh_nphi, SSHT.sampling_dh_ntheta.

SSHT.sampling_dh_nphi — Function

nphi = sampling_dh_nphi(L::Integer)
nphi::Int

Number of collocation points in the phi direction for L = lmax+1 modes.

See also: SSHT.sampling_dh_n, SSHT.sampling_dh_ntheta.

SSHT.sampling_dh_ntheta — Function

ntheta = sampling_dh_ntheta(L::Integer)
ntheta::Int

Number of collocation points in the theta direction for L = lmax+1 modes.

See also: SSHT.sampling_dh_n, SSHT.sampling_dh_nphi.

SSHT.sampling_dh_p2phi — Function

phi = sampling_dh_p2phi(p::Integer, L::Integer)
phi::Float64

Calculate the phi coordinate for point p in the phi direction (1 ≤ p ≤ nphi).

See also: SSHT.sampling_dh_t2theta, SSHT.sampling_dh_nphi.

SSHT.sampling_dh_t2theta — Function

theta = sampling_dh_p2theta(t::Integer, L::Integer)
theta::Float64

Calculate the theta coordinate for point t in the theta direction (1 ≤ t ≤ ntheta).

See also: SSHT.sampling_dh_p2phi, SSHT.sampling_dh_ntheta.

SSHT.sampling_weight_dh — Function

w = sampling_weight_dh(theta_t::Real, L::Integer)
w::Float64

Calculate the sampling weight of a point with the given theta coordinate. This value is essentially sin(theta) * dtheta, possibly modified to achive higher accuracy depending on how the collocation points are spaced out in the theta direction.

Integrating a function over the sphere should be done as follows:

# Input: Choose `L` and array `f`
s = 0.0
nphi = SSHT.sampling_dh_nphi(L)
ntheta = SSHT.sampling_dh_ntheta(L)
for p in 1:nphi, t in 1:ntheta
    phi = SSHT.sampling_dh_p2phi(p, L)
    theta = SSHT.sampling_dh_t2theta(t, L)
    # dtheta = π / ntheta
    dtheta = SSHT.sampling_weight_dh(theta, L)
    dphi = 2π / nphi
    s += f[p, t] * dtheta * dphi
end
# Output: s

See also: SSHT.sampling_dh_nphi, SSHT.sampling_dh_ntheta, SSHT.sampling_dh_p2phi, SSHT.sampling_dh_t2theta.

SSHT.sampling_elm2ind — Function

ind = sampling_elm2ind(el::Integer, m::Integer)
ind::Int

Calculate the mode array index ind for a given mode l, m. For L = lmax+1 modes, there are L^2 modes in total.

See also: sampling_ind2elm.

SSHT.sampling_ind2elm — Function

l, m = sampling_ind2elm(ind::Integer)
l::Int
m::Int

Calculate the mode numbers l and m from a given mode array index ind. For L = lmax+1 modes, there are L^2 modes in total: 1 ≤ ind ≤ L^2.

This function needs to evaluate a square root internally. If possible, using sampling_elm2ind instead is slightly preferred.

See also: sampling_elm2ind.