${}_{s}Y_{\ell,m}$ functions

The spin-weighted spherical harmonics are an important set of functions defined on the rotation group $𝐒𝐎(3)$, or more generally, the spin group $𝐒𝐩𝐢𝐧(3)$ that covers it. They are eigenfunctions of the left- and right-Lie derivatives, and are particularly useful in describing the angular dependence of polarized fields, like the electromagnetic field and gravitational-wave field. Originally introduced by Newman and Penrose [7], they are essentially components of Wigner's $\frak{D}$ matrices:

\[{}_{s}Y_{\ell,m}(\mathbf{R}) = (-1)^s \sqrt{\frac{2\ell+1}{4\pi}} \, \frak{D}^{(\ell)}_{m, -s}(\mathbf{R}).\]

As such, they can be computed using the same $H$ recursion algorithm as the Wigner $\frak{D}^{(\ell)}_{m, -s}$ matrices. But because not all values of $s \in -\ell:\ell$ are used, we can be much more efficient in both storage and computation time.

The user interface is very similar to the one for Wigner's $𝔇$ and $d$ matrices:

using Quaternionic
using SphericalFunctions

R = randn(RotorF64)
ℓₘₐₓ = 8
s = -2
Y = sYlm_values(R, ℓₘₐₓ, s)

Again, the results can take up a lot of memory, so for maximum efficiency when calling this function repeatedly with different R values, it is best to pre-allocate the necessary memory with the sYlm_prep function, and the pass that in as an argument to sYlm_values!:

Y_storage = sYlm_prep(ℓₘₐₓ, s)
Y = sYlm_values!(Y_storage, R, s)

(Beware that, as noted in the documentation for sYlm_values!, the output Y is just a reference to part of the Y_storage object, so you should not reuse Y_storage until you have copied or otherwise finished using Y.)

The output Y is a single vector of Complex numbers with the same base type as R. The ordering of the elements is described in the documentation for sYlm_values!. It is also possible to efficiently view slices of this vector as a series of individual vectors using a sYlm_iterator:

for (ℓ, Yˡ) in zip(0:ℓₘₐₓ, sYlm_iterator(Y, ℓₘₐₓ))
    # Do something with the matrix Yˡ[ℓ+m′+1, ℓ+m+1]
end

Docstrings

SphericalFunctions.sYlm_values — Function

sYlm_values(R, ℓₘₐₓ, spin)
sYlm_values(θ, ϕ, ℓₘₐₓ, spin)

Compute values of the spin-weighted spherical harmonic ${}_{s}Y_{\ell, m}(R)$ for all $\ell \leq \ell_\mathrm{max}$.

See sYlm_values! for details about the input and output values.

This function only appropriate when you need to evaluate the ${}_{s}Y_{\ell, m}$ for a single value of R or θ, ϕ because it allocates large arrays and performs many calculations that could be reused. If you need to evaluate the matrices for many values of R or θ, ϕ, you should pre-allocate the storage with sYlm_prep, and then call sYlm_values! with the result instead.

source

SphericalFunctions.sYlm_values! — Function

sYlm_values!(sYlm_storage, R, spin)
sYlm_values!(sYlm_storage, θ, ϕ, spin)
sYlm_values!(sYlm, R, ℓₘₐₓ, spin)
sYlm_values!(sYlm, θ, ϕ, ℓₘₐₓ, spin)

Compute values of the spin-weighted spherical harmonic ${}_{s}Y_{\ell, m}(R)$ for all $\ell \leq \ell_\mathrm{max}$.

The spherical harmonics of spin weight $s$ are related to Wigner's $\mathfrak{D}$ matrix as

\[\begin{aligned} {}_{s}Y_{\ell, m}(R) &= (-1)^s \sqrt{\frac{2\ell+1}{4\pi}} \mathfrak{D}^{(\ell)}_{m, -s}(R) \\ &= (-1)^s \sqrt{\frac{2\ell+1}{4\pi}} \bar{\mathfrak{D}}^{(\ell)}_{-s, m}(\bar{R}). \end{aligned}\]

In all cases, the result is returned in a 1-dimensional array ordered as

[
    ₛYₗₘ(R)
    for ℓ ∈ 0:ℓₘₐₓ
    for m ∈ -ℓ:ℓ
]

When the first argument is Y, it will be modified, so it must be at least as large as that array. When the first argument is sYlm_storage, it should be the quantity returned by sYlm_prep, and the result will be written into the Y field of that tuple. Both of these options — especially the latter — reduce the number of allocations needed on each call to the corresponding functions, which should increase the speed significantly. Note that the Y or sYlm_storage arguments must have types compatible with the type of R or θ, ϕ.

Warn

When using the sYlm_storage argument (which is recommended), the returned quantity sYlm will be an alias of sYlm_storage[1]. If you want to retain that data after the next call to sYlm_values!, you should copy it with copy(sYlm).

The θ, ϕ arguments are spherical coordinates as described in the documentation of Quaternionic.from_spherical_coordinates.

See also sYlm_values for a simpler function call when you only need to evaluate the ${}_{s}Y_{\ell, m}$ for a single value of R or θ, ϕ.

Examples

using Quaternionic, SphericalFunctions
spin = -2
ℓₘₐₓ = 8
T = Float64
R = Rotor{T}(1, 2, 3, 4)  # Will be normalized automatically
sYlm_storage = sYlm_prep(ℓₘₐₓ, spin, T)
sYlm = sYlm_values!(sYlm_storage, R, spin)

source

SphericalFunctions.sYlm_prep — Function

sYlm_prep(ℓₘₐₓ, sₘₐₓ, [T=Float64, [ℓₘᵢₙ=0]])

Construct storage space and pre-compute recursion coefficients to compute spin-weighted spherical-harmonic values ${}_{s}Y_{\ell, m}$ in place.

This returns the sYlm_storage arguments needed by sYlm_values!.

Note that the result of this function can be passed to sYlm_values!, even if the value of spin passed to that function is smaller (in absolute value) than the sₘₐₓ passed to this function. That is, the sYlm_storage returned by this function can be used to compute ${}_{s}Y_{\ell, m}$ values for numerous values of the spin.

source

SphericalFunctions.sYlm_iterator — Type

sYlm_iterator(Y, ℓₘₐₓ, [ℓₘᵢₙ, [iₘᵢₙ]])

Construct an Iterator that returns sub-vectors of Y, each of which consists of elements $(ℓ,-ℓ)$ through $(ℓ,ℓ)$, for $ℓ$ from ℓₘᵢₙ through ℓₘₐₓ.

Note that the returned objects are views into the original Y data — meaning that you may alter their values.

Because the result is a vector restricted to a particular $ℓ$ value, you can index the $(ℓ, m)$ element as [ℓ+m+1]. For example, you might use this as something like

for (ℓ, Yˡ) in zip(ℓₘᵢₙ:ℓₘₐₓ, sYlm_iterator(Y, ℓₘₐₓ))
    for m in -ℓ:ℓ
        Yˡ[ℓ+m+1] = <...>
    end
end

By default, Y is assumed to contain all possible values, beginning with (0,0). However, if ℓₘᵢₙ is not 0, this can be ambiguous: do we mean that Y really starts with the (0,0) element and we are just asking to begin the iteration higher? Or do we mean that Y doesn't even contain data for lower ℓ values? We can resolve this using iₘᵢₙ, which gives the index of ℓₘᵢₙ in Y. By default, we assume the first case, and set iₘᵢₙ=Ysize(ℓₘᵢₙ-1)+1. However, if Y doesn't contain data below ℓₘᵢₙ, we could use iₘᵢₙ=1 to indicate the index in Y at which to find $(ℓₘᵢₙ,-ℓₘᵢₙ)$.

Also note that no bounds checking is done, either at instantiation time or during iteration. You are responsible for ensuring that the size of Y and the values of ℓₘₐₓ, ℓₘᵢₙ, and iₘᵢₙ make sense.

source