$𝔇$ and $d$ matrices, and ${}_{s}Y_{ℓ,m}$ and $Y_{ℓ,m}$ functions

w(R)
w(R⃗)

Evaluate the function with mode weights w at the rotor R, or at each of a vector of rotors R⃗, $f(𝐑) = \sum_{ℓ,m} f_{ℓ,m}\, {}_sY_{ℓ,m}(𝐑)$. For spherical coordinates use R = from_spherical_coordinates(θ, ϕ).

This computes the harmonics on every call. For repeated evaluation build an sYlmCalculator once and use calc * w; for many rotors at once see sYlm_matrix and the transforms in the "Transformations" section. As for Y * w, the harmonics are computed in the floating-point type of the rotor, so a rotor of lower precision than the weights limits the precision of the result.

The entries of w with $ℓ < |s|$ belong to no harmonic, and are not read. Mode weights that hold no $ℓ ≥ |s|$ at all, such as an empty ModeWeights or weights whose $|s|$ exceeds their $ℓₘₐₓ$, describe the zero function, and evaluate to zero, although sYlm refuses such a spin weight; weights of that kind arise from ð applied to weights with $s = ℓₘₐₓ$, for example. An empty vector of rotors gives an empty vector of values.

𝔇 * w
calc * w

Rigidly rotate the mode weights w, giving the weights of $f′(𝐐) = f(𝐑^{-1} 𝐐)$ — the function actively rotated by the rotor whose Wigner matrices 𝔇 (a WignerSeries from D) or calc (a DCalculator) hold. Mode by mode,

\[f′_{ℓ,m′} = \sum_m 𝔇^{(ℓ)}_{m′,m}(𝐑)\, f_{ℓ,m},\]

with no complex conjugate: version 2's $𝔇$ was the conjugate of this one, so code ported from it must drop a conj rather than add one. The derivation is in the conventions section, under Rotation of mode weights.

The result is a new ModeWeights with the same spin weight and the same range of $ℓ$ as w — a rotation changes neither. 𝔇 must cover w's range, which is not the same as matching it: D has no ℓₘᵢₙ argument and always starts at $0$ (or $1/2$), while a ModeWeights usually starts at $|s|$. The blocks must be whole: a $𝔇$ built with any of the m′ₘₐₓ, m′ₘᵢₙ, mₘₐₓ or mₘᵢₙ restrictions cannot rotate anything, because every $m$ mixes into every $m′$, and is refused.

Real matrices from d are accepted, and are exactly the rotation by from_euler_angles(0, β, 0), for which $𝔇 = d$. The matrices are computed in the floating-point type of the rotor, as D says, and the result is of the promoted type of the matrices and the weights, so weights of higher precision than the rotor are rotated only to the rotor's precision; convert the rotor to the weights' type where their full precision is wanted.

The calculator form holds one $ℓ$ at a time instead of materializing every block, so it allocates only the result; mul! into an existing container allocates nothing at all. (The destination may also be a bare vector at least as long as the result, which then comes back as a ModeWeights over it.) The calculator must have been built from a single Rotor: one built from a vector of rotors, even of length one, is batched, and is refused. A calculator holds workspace, so it must not be used by two tasks at once; similar(calc) gives each task one of its own.

w′ = D(R, ℓₘₐₓ(w)) * ww′(Q) ≈ w(inv(R) * Q)          # the defining property

See also ModeWeights and HarmonicValues.

Y * w
calc * w

Evaluate the function with mode weights w at the rotor (or rotors) whose harmonics Y holds, $f(𝐑) = \sum_{ℓ,m} f_{ℓ,m}\, {}_sY_{ℓ,m}(𝐑)$. Y is a HarmonicValues from sYlm, or an sYlmCalculator. Real harmonics are refused, whether from an sλlmCalculator or in a HarmonicValues of real numbers: they are functions of $θ$ alone, without the phase $i^{2s}$ of ${}_sY_{ℓ,m}$, so they evaluate the function at no rotor.

The result is a scalar when the harmonics were computed for a single rotor, and a Vector of one value per rotor otherwise. Where Y holds a range of spin weights, the row of w's own spin weight is the one used, and the result is as above; weights of one spin weight paired against harmonics of another mean nothing, so a w whose spin weight is not among them is refused.

Y's range of $ℓ$ must cover that of w, from the larger of ℓₘᵢₙ(w) and $|s|$ up, which is not the same as matching it: sYlm takes an ℓₘᵢₙ, and the two need not agree. The entries of w with $ℓ < |s|$ belong to no harmonic and are not read, so a non-finite value there does not reach the result; weights that hold no $ℓ ≥ |s|$ at all evaluate to zero.

The harmonics are computed in the floating-point type of the rotor, and the result is of the promoted type of the harmonics and the weights, so weights of higher precision than the rotor are evaluated only to the rotor's precision; convert the rotor to the weights' type where their full precision is wanted.

This product does not conjugate anything, which is why it is * and not ⋅: ⋅ is LinearAlgebra.dot, which conjugates its first argument. It is the labelled form of the product that sYlm_matrix's docstring writes as f = Y * array_view(f̃), and unlike that product of plain arrays it checks the spin weight and the range of $ℓ$ of w.

The calculator form holds one $ℓ$ at a time rather than every harmonic at once. A calculator holds workspace, so it must not be used by two tasks at once; similar(calc) gives each task one of its own.

Y = sYlm(R, ℓₘₐₓ(w), spin(w); ℓₘᵢₙ=ℓₘᵢₙ(w))Y * w == w(R)

D(R, ℓₘₐₓ; m′ₘₐₓ=ℓₘₐₓ, m′ₘᵢₙ=-m′ₘₐₓ, mₘₐₓ=ℓₘₐₓ, mₘᵢₙ=-mₘₐₓ)
D(α, β, γ, ℓₘₐₓ; m′ₘₐₓ=ℓₘₐₓ, m′ₘᵢₙ=-m′ₘₐₓ, mₘₐₓ=ℓₘₐₓ, mₘᵢₙ=-mₘₐₓ)

Wigner's $𝔇^{(ℓ)}_{m',m}(R)$ matrices for all $ℓ ≤ ℓₘₐₓ$, for the single rotor R, or for the rotor from_euler_angles(α, β, γ) of the Euler angles $(α, β, γ)$.

The result is a WignerSeries, indexed by $ℓ$ and then naturally by $(m', m)$: D(R, ℓₘₐₓ)[ℓ][m′, m]. Each block is a WignerMatrix; Matrix (or collect) gives the ordinary $(2ℓ+1)×(2ℓ+1)$ Matrix with rows and columns in order of increasing $m'$ and $m$. The keyword arguments restrict the block of each matrix that is computed, and may also be spelled mp_max, mp_min, m_max and m_min. The convention is $𝔇^{(ℓ)}_{m',m}(𝐑_{α,β,γ}) = e^{-im'α}\, d^{(ℓ)}_{m',m}(β)\, e^{-imγ}$; see the "Conventions" section of the documentation.

ℓₘₐₓ may be a half-integer, as a Rational with denominator 2 or a HalfOddInteger, as may the keyword limits; then $ℓ$ runs over $1/2, 3/2, …, ℓₘₐₓ$ rather than $0, 1, …, ℓₘₐₓ$. The container types are the same either way, and D(R, ℓₘₐₓ)[ℓ][m′, m] reads the same.

This function allocates all of its output on every call, and takes a single rotor. To evaluate the matrices for many rotors, or to avoid holding every $ℓ$ at once, use a DCalculator instead, which allocates once, computes one $ℓ$ at a time, and takes a vector of rotors as a batch.

See also d and sYlm.

d(β, ℓₘₐₓ; m′ₘₐₓ=ℓₘₐₓ, m′ₘᵢₙ=-m′ₘₐₓ, mₘₐₓ=ℓₘₐₓ, mₘᵢₙ=-mₘₐₓ)

Wigner's real $d^{(ℓ)}_{m′,m}(β)$ matrices for all $ℓ ≤ ℓₘₐₓ$, for the single angle β, which may also be given as the phase $e^{iβ}$ or as a Rotor or other Quaternion. The result is indexed as d(β, ℓₘₐₓ)[ℓ][m′, m]. See D for details, including the keyword arguments and their ASCII spellings; this function is the real, $β$-only analogue.

A Rotor contributes the $β ∈ [0, π]$ of its canonical Euler decomposition, as described under dCalculator, so d(R, ℓₘₐₓ) equals d(β, ℓₘₐₓ) for the angle $β$ used to build R only when $β ∈ [0, π]$.

ℓₘₐₓ may be a half-integer, as a Rational with denominator 2 or a HalfOddInteger. Half-integer $d$ has period $4π$ in $β$, so an angle or a Rotor determines it unambiguously, but a bare phase $e^{iβ}$ determines it only up to the sign $(-1)^{2ℓ}$ (the branch $β ∈ (-π, π]$ is used).

sYlm(R, ℓₘₐₓ, s; ℓₘᵢₙ=abs(s))
sYlm(θ, ϕ, ℓₘₐₓ, s; ℓₘᵢₙ=abs(s))
sYlm(R⃗, ℓₘₐₓ, s; ℓₘᵢₙ=abs(s))

The spin-weighted spherical harmonics ${}_sY_{ℓ,m}(R)$ for all $ℓₘᵢₙ ≤ ℓ ≤ ℓₘₐₓ$ and $-ℓ ≤ m ≤ ℓ$, as a HarmonicValues: indexed first by $ℓ$ and then naturally, so that sYlm(R, ℓₘₐₓ, s)[ℓ][m] is one value. With ℓₘᵢₙ below abs(s) the entries for $ℓ < |s|$ are zero. The keyword may also be given as ell_min. The computation is done in the rotor's own floating-point type, and the result is Complex of it; to compute in another type, convert the rotor.

The first argument may be a single rotor or a vector of them, and s may be a single spin weight or an ascending unit range such as -2:2, which between them give a block four shapes:

A vector of rotors gives the batched shapes whatever its length, even one. For a range, ℓₘᵢₙ defaults to the smallest $|s|$ in it, which is 0 (or 1/2) whenever the range straddles zero, so rows below their own $|s|$ are zero.

Underneath, the values are held in one array whose last axis is the modes in the canonical ordering [ₛYₗₘ for ℓ ∈ ℓₘᵢₙ:ℓₘₐₓ for m ∈ -ℓ:ℓ] (see Yindex), and whose leading axes are the rotors and spin weights. array_view hands that array back, which is the form a product with mode weights takes; sYlm_matrix is the direct name for it, for callers who want the bare array.

A single rotor may instead be given by the spherical coordinates of its point: sYlm(θ, ϕ, ℓₘₐₓ, s) is sYlm(from_spherical_coordinates(θ, ϕ), ℓₘₐₓ, s). For repeated evaluation use an sYlmCalculator, which allocates once, and give it each new rotor with set_R!. The convention is ${}_sY_{ℓ,m} = (-1)^s \sqrt{(2ℓ+1)/4π}\, \overline{𝔇^{(ℓ)}_{m,-s}}$; see the "Conventions" section of the documentation.

Half-integer indices

ℓₘₐₓ and s may be half-integers, passed as Rationals with denominator 2 or as HalfOddIntegers — as in sYlm(R, 7//2, 1//2), or sYlm(R, 7//2, -3//2:3//2) — in which case every $ℓ$ and $m$ is a half-odd-integer, and so is ℓₘᵢₙ, which may be as small as 1//2. The indices in one call must all be of one kind, integers or half-odd-integers; a call that mixes them, such as sYlm(R, 7//2, 1), is refused with an ArgumentError. For half-integer s the prefactor $(-1)^s$ is $i^{2s} = \pm i$, so the values include that phase and are not real multiples of $\overline{𝔇}$; the choice of branch is explained under sYlmCalculator.

Ylm(R, ℓₘₐₓ; ℓₘᵢₙ=0)
Ylm(θ, ϕ, ℓₘₐₓ; ℓₘᵢₙ=0)
Ylm(R⃗, ℓₘₐₓ; ℓₘᵢₙ=0)

The ordinary scalar spherical harmonics $Y_{ℓ,m}(R)$ for all $ℓₘᵢₙ ≤ ℓ ≤ ℓₘₐₓ$, as a HarmonicValues indexed by $ℓ$ and then by $m$: Ylm(R, ℓₘₐₓ)[ℓ][m]. The keyword may also be given as ell_min.

These are the spin-weight-zero case of the spin-weighted harmonics; this function is exactly sYlm(R, ℓₘₐₓ, 0; ℓₘᵢₙ), and everything sYlm says applies here too — including that a vector of rotors gives blocks indexed [iᵣ, m], and that Ylm(θ, ϕ, ℓₘₐₓ) is Ylm(from_spherical_coordinates(θ, ϕ), ℓₘₐₓ). See YlmCalculator for repeated evaluation.

The $ℓ$ arguments must be integers. Half-integer $ℓ$ goes with half-integer spin weight, so there is no half-integer analogue of this function, and a half-integer index is refused with an ArgumentError that says so; see sYlm for half-integer spin weights.

sYlm_matrix(R⃗, ℓₘₐₓ, s; ℓₘᵢₙ=abs(s))

The dense matrix of spin-weighted spherical harmonics ${}_sY_{ℓ,m}(R_i)$, with rows indexed by the rotors in R⃗ and columns by the modes $(ℓ, m)$ in the canonical ordering [(ℓ, m) for ℓ ∈ ℓₘᵢₙ:ℓₘₐₓ for m ∈ -ℓ:ℓ] (see Yindex). Row i equals sYlm(R⃗[i], ℓₘₐₓ, s; ℓₘᵢₙ). The keyword may also be given as ell_min. The computation is done in the rotors' own floating-point type; to compute in another type, convert them.

Multiplying this matrix by the array of mode weights synthesizes the corresponding spin-weighted function at the rotors, as Y * array_view(f̃), provided the weights are stored from the same ℓₘᵢₙ; the labelled sYlm(R⃗, ℓₘₐₓ, s) * f̃ does the same, and checks the labels. The (pseudo)inverse of the matrix performs the analysis. It is computed with all rotors batched, which is the efficient path; for $ℓₘₐₓ ≳ 64$ the matrix becomes large and the transforms in the "Transformations" section of the documentation should be preferred.

The argument s may also be a range of spin weights (ascending, and with step size 1). The result is then three-dimensional, indexed [rotor, spin, mode], and is a stack of the matrices above rather than one of them. The spin index is an ordinary 1-based position, and ℓₘᵢₙ defaults to the smallest $|s|$ in the range, which is 0 (or 1/2) for a range that straddles zero. Y[:, i, :] is the synthesis matrix of spin weight s[i] for weights stored from that same ℓₘᵢₙ. Weights that start at their own $|s[i]|$, as those the transforms return do, need that ℓₘᵢₙ passed explicitly; the labelled sYlm(R⃗, ℓₘₐₓ, s) * w picks the right spin row and $ℓ$ range itself.

The indices may be half-integers, passed as Rationals with denominator 2 or as HalfOddIntegers, on the terms described under sYlm: all of one kind, with ℓₘᵢₙ defaulting to the smallest $|s|$ and the values including the phase $i^{2s}$. The columns are then indexed by half-odd $(ℓ, m)$ in the same canonical ordering, and Yindex locates them as before.

DCalculator(R, ℓₘₐₓ; m′ₘₐₓ=ℓₘₐₓ, m′ₘᵢₙ=-m′ₘₐₓ, mₘₐₓ=ℓₘₐₓ, mₘᵢₙ=-mₘₐₓ)
DCalculator(α, β, γ, ℓₘₐₓ; m′ₘₐₓ=ℓₘₐₓ, m′ₘᵢₙ=-m′ₘₐₓ, mₘₐₓ=ℓₘₐₓ, mₘᵢₙ=-mₘₐₓ)

Calculator for Wigner's $𝔇^{(ℓ)}_{m′,m}(R)$ matrices, for $ℓ ≤ ℓₘₐₓ$, with elements of type Complex{RT}. The keyword arguments restrict the block of each matrix that is computed and returned; they may also be spelled mp_max, mp_min, m_max and m_min. Restricting either the rows $m′$ or the columns $m$ to a narrow band also narrows the recurrence itself, which at each $ℓ$ costs in proportion to the narrower of the two ranges.

The rotor is given at construction, so that the calculator is usable the moment it exists, and so that the element type is the rotor's own: a Rotor{Float32} gives a Float32 calculator, and floattype(calc) reports it. There is no argument to override that — to compute in another type, convert the rotor, which is the honest way to say that those are the values to be treated as exact. Give R as an AbstractVector of rotors to get a calculator that handles all Nᵣ = length(R) of them at once — which is substantially faster per rotor, for the reason described under Reusing the workspace. Later rotors are supplied with set_R!. A single rotor may instead be given by its Euler angles: DCalculator(α, β, γ, ℓₘₐₓ) is DCalculator(from_euler_angles(α, β, γ), ℓₘₐₓ).

The calculator is iterable, yielding one $ℓ$ at a time:

calc = DCalculator(R, ℓₘₐₓ)for (ℓ, 𝔇ˡ) ∈ calc    # 𝔇ˡ[m′, m] with m′, m ∈ -ℓ:ℓend

For a calculator built from a vector of rotors — of any length, even one — each block is indexed as [iᵣ, m′, m] instead. The block is a view into the calculator's storage and is overwritten by the next step, so copy it if it must survive (the copy keeps the natural indices), or collect it to get an ordinary 1-based Array: a Matrix, or a three-dimensional Array for a block with a rotor index. collect(calc) copies every block, so it is safe. To sweep part of the range, or to take the values of $ℓ$ in some other order, loop over recurrence! yourself.

A calculator is a mutable workspace, which every step and every setter overwrites, so one calculator must not be used by two tasks at once; similar(calc) gives each task a calculator of its own, holding the same rotor data.

The convention is $𝔇^{(ℓ)}_{m′,m}(𝐑_{α,β,γ}) = e^{-im′α}\, d^{(ℓ)}_{m′,m}(β)\, e^{-imγ}$; see the "Conventions" section of the documentation.

Half-integer indices

DCalculator(R, 7//2) — a Rational ℓₘₐₓ with denominator 2, or a HalfOddInteger — gives a calculator for half-integer $ℓ, m′, m$. All four keyword limits must then be half-integers too, in either spelling; recurrence! accepts only half-integer ℓ and returns a WignerMatrix (or a WignerMatrixBatch when built from a vector) whose indices are half-odd-integers; it is indexed the same way. The double cover is respected exactly: $𝔇(-R) = -𝔇(R)$.

See also D for a simpler interface when the matrices for only one rotor are needed, dCalculator for the real $d$ matrices, and recurrence!.

dCalculator(β, ℓₘₐₓ; m′ₘₐₓ=ℓₘₐₓ, m′ₘᵢₙ=-m′ₘₐₓ, mₘₐₓ=ℓₘₐₓ, mₘᵢₙ=-mₘₐₓ)

Calculator for Wigner's real $d^{(ℓ)}_{m′,m}(β)$ matrices, for $ℓ ≤ ℓₘₐₓ$, with elements of the angle's own floating-point type. The first argument may be the angle $β$, the phase $e^{iβ}$, or a Rotor or other Quaternion, or an AbstractVector of Nᵣ of any one of those; later values are supplied with set_β!. Otherwise this behaves exactly like DCalculator — including iteration, the ASCII spellings of the keywords, and half-integer $ℓ$ for a Rational or HalfOddInteger ℓₘₐₓ.

A Rotor contributes the $β ∈ [0, π]$ of its canonical Euler decomposition. If the rotor was built from a $β$ outside that range, that $β$ is folded into its $α$ and $γ$, which a $d$ matrix does not see, so d of such a rotor equals d of its angle only for $β ∈ [0, π]$; this is consistent with D of the same rotor.

Half-integer $d$ has period $4π$ in $β$, so an angle or a Rotor determines it unambiguously, while a bare phase $e^{iβ}$ determines it only up to the double-cover sign $(-1)^{2ℓ}$; the branch $β ∈ (-π, π]$ is used in that case.

See also d.

HCalculator(β, ℓₘₐₓ; m′ₘₐₓ=ℓₘₐₓ)

Engine for the Gumerov–Duraiswami recurrences, computing the $H$ wedge (see HWedge) for one value of $ℓ$ at a time, for Nᵣ rotors simultaneously.

The parameters of the type HCalculator{IT, RT, ST} are as follows:

• IT is the index type, Int or HalfOddInteger.
• RT is the real type the calculator works in.
• ST is the storage type of the $H$ wedge.

The $H$ matrix depends on the rotor only through $β$, so the calculator stores one phase $e^{iβ}$ per rotor. The first argument supplies them: an angle $β$, a phase $e^{iβ}$, a Rotor or Quaternion, or an AbstractVector of any one of those — and it is the vector case that makes the calculator handle Nᵣ = length(β) rotors at once. A Rotor contributes the $β ∈ [0, π]$ of its canonical Euler decomposition; if the rotor was built from a $β$ outside that range, that $β$ is folded into its $α$ and $γ$, which this calculator does not see. Later values are supplied by set_β!. The wedge is stored for $|m′| ≤ m′ₘₐₓ$ and $m ≥ |m′|$; every other element of the $H$ matrix is obtained by symmetry through wedge_value. The keyword may also be spelled mp_max.

The element type is the rotor data's own: an angle given as a Float32 gives a Float32 calculator, and there is no argument to override that. To compute in another type, convert the data — HCalculator(Double64(β), ℓₘₐₓ) — which says what is meant, that these are the values to treat as exact. floattype(calc) reports the type in use.

This is the low-level calculator of $H$ shared by DCalculator, dCalculator, and the spin-weighted spherical harmonics; most users will want one of those instead.

Usage

calc = HCalculator(rotors, ℓₘₐₓ)for ℓ ∈ 0:ℓₘₐₓ    recurrence!(calc, ℓ)            # advance to the next ℓ (cheap when sequential)    H = calc.Hˡ                     # HWedge for the current ℓ; H[iᵣ, m′, m] for m ≥ |m′|end

Unlike DCalculator and the other calculators built on it, this one is not iterable: its wedge is one mutable object handed back by identity, rather than a view that copy can preserve. The wedge belongs to the calculator, so its ℓ must not be reassigned; copy(calc.Hˡ) gives an independent wedge that survives the next step.

Requesting an $ℓ$ smaller than the current one restarts the recurrence from $ℓ_{min}$; jumping forward advances through the intermediate values. Nothing is allocated after construction.

A calculator is a mutable workspace, which every step and every setter overwrites, so one calculator must not be used by two tasks at once; similar(calc) gives each task a calculator of its own.

Half-integer indices

Passing a Rational ℓₘₐₓ with denominator 2 — HCalculator(β, 7//2) — or a HalfOddInteger gives a calculator for half-integer $ℓ, m′, m$. Then m′ₘₐₓ must also be a half-integer, in either spelling, and recurrence!(calc, ℓ) accepts only half-integer ℓ. The recurrence is the same one: the $m'=0$ axis is run at the integer order $j = ℓ - 1/2$, the rows $m' = ±1/2$ are seeded from it by a Clebsch–Gordan step, and the $m'$ ladder then proceeds unchanged (see the notes on the $H$ recursion). Note that the $H$ matrix is then symmetric only up to the sign $σ = \mathrm{sgn}(m)\,\mathrm{sgn}(m')$ (see transpose_sign), which wedge_value applies for you.

Because half-integer $d$ has period $4π$ in $β$, a rotor or an angle $β$ determines it unambiguously, but a bare phase $e^{iβ}$ determines $β$ only modulo $2π$ and hence $d$ only up to the double-cover sign $(-1)^{2ℓ}$; the branch $β ∈ (-π, π]$ is used.

sYlmCalculator(R, ℓₘₐₓ, s)
sYlmCalculator(θ, ϕ, ℓₘₐₓ, s)

Calculator for the spin-weighted spherical harmonics ${}_sY_{ℓ,m}$ for all $ℓ ≤ ℓₘₐₓ$, with elements of Complex of the rotor's own element type. The spin weight s is either a single value or an ascending unit range of them, such as -2:2; the calculator serves exactly those, and works out for itself how much of the underlying recurrence they need.

The rotor is given at construction, so that the calculator is usable the moment it exists, and so that the element type is the rotor's own: a Rotor{Float32} gives a Float32 calculator, and floattype(calc) reports it. There is no argument to override that — to compute in another type, convert the rotor. Give R as an AbstractVector of rotors to get a calculator that handles all Nᵣ = length(R) of them at once. Later rotors are supplied with set_R!. A single rotor may instead be given by the spherical coordinates of its point: sYlmCalculator(θ, ϕ, ℓₘₐₓ, s) is sYlmCalculator(from_spherical_coordinates(θ, ϕ), ℓₘₐₓ, s).

Only one $ℓ$ is held at a time, and iteration is how to step through them:

calc = sYlmCalculator(R, ℓₘₐₓ, 2)for (ℓ, ₛYₗ) ∈ calc    # ₛYₗ[m] is available for m ∈ -ℓ:ℓendcalc = sYlmCalculator(R, ℓₘₐₓ, -2:2)for (ℓ, ₛYₗ) ∈ calc    # ₛYₗ[s, m] is available for s ∈ -2:2 and m ∈ -ℓ:ℓend

For a calculator built from a vector of rotors or angles — of any length, even one — each block gains a leading rotor index, so it is read as ₛYₗ[iᵣ, m] or ₛYₗ[iᵣ, s, m]. The same block is what recurrence! returns when the calculator is stepped by hand, and ₛYₗ[s, :] picks out the row of one spin weight of a calculator built for several. Each block is a view into the calculator's storage, overwritten by the next step; copy it if it must survive (keeping the natural indices), or collect it to get an ordinary 1-based array. Wherever $ℓ < |s|$ the values are zero.

spins reports the range of spin weights served, and spin the single value when there is only one. Lengthening the range costs storage and arithmetic in proportion to its length, but it is the largest $|s|$ alone that decides the size of the underlying Wigner $H$ wedge: sYlmCalculator(R, ℓₘₐₓ, 2) and sYlmCalculator(R, ℓₘₐₓ, -2:2) run precisely the same recurrence, and differ only in how much of it is read out.

Instead of rotors, the angle $θ$ (or a vector of Nᵣ angles) may be given, at construction or through set_θ!. This evaluates the harmonics at $(θ, ϕ=0)$, which is what the ring-based transforms need — though the values are still stored as complex numbers, and a calculator that will only ever be used that way is better built as an sλlmCalculator, which stores them as reals.

A calculator is a mutable workspace, which every step and every setter overwrites, so one calculator must not be used by two tasks at once; similar(calc) gives each task a calculator of its own, holding the same rotor data.

The harmonics are defined by

\[{}_sY_{ℓ,m}(𝐑) = (-1)^s \sqrt{\frac{2ℓ+1}{4π}}\, \overline{𝔇^{(ℓ)}_{m,-s}(𝐑)},\]

so that they are functions on the rotation group, and the harmonics at the spherical coordinates $(θ, ϕ)$ are those at R = from_spherical_coordinates(θ, ϕ). See the "Conventions" section of the documentation.

Half-integer indices

ℓₘₐₓ and the spin weights may all be half-integers, passed as Rationals with denominator 2 or as HalfOddIntegers, in which case $ℓ$, $m$ and $s$ are all half-integers. A range is written the same way, as -3//2:3//2. The prefactor $(-1)^s$ is then $\pm i$; the principal branch $(-1)^s ≡ e^{iπs} = i^{2s}$ settled in the "Conventions" section is used, so the harmonics are not real multiples of $\overline{𝔇}$, and ${}_sY_{ℓ,m}(θ, 0)$ is therefore not real (see sλlmCalculator, which divides that constant phase out). The blocks are the same containers as for integer indices — a DegreeBlock or DegreeBlockBatch for one spin weight, and a SpinMatrix or SpinMatrixBatch for several — indexed exactly as described above. The flat interfaces sYlm and sYlm_matrix accept the same types, and lay the values out in the canonical mode-weight ordering of Yindex, which holds for half-odd indices exactly as it does for integers.

See also sYlm and sYlm_matrix for simpler interfaces, and DCalculator.

YlmCalculator(R, ℓₘₐₓ)
YlmCalculator(θ, ϕ, ℓₘₐₓ)

Calculator for the ordinary scalar spherical harmonics $Y_{ℓ,m}$, for $ℓ ≤ ℓₘₐₓ$.

This is exactly sYlmCalculator(R, ℓₘₐₓ, 0), or sYlmCalculator(θ, ϕ, ℓₘₐₓ, 0), and returns an sYlmCalculator rather than a type of its own — there is nothing about spin weight zero to specialize. Everything sYlmCalculator documents applies, so blocks are indexed Yₗ[m] (or Yₗ[iᵣ, m] for a collection of rotors), and it iterates as for (ℓ, Yₗ) ∈ calc.

$ℓₘₐₓ$ must be an integer: a half-integer $ℓ$ goes with a half-integer spin weight, so spin weight zero has no half-integer analogue, and a half-integer ℓₘₐₓ is refused with an ArgumentError that says so. See sYlmCalculator for those.

sλlmCalculator(θ, ℓₘₐₓ, s)
slambdalmCalculator(θ, ℓₘₐₓ, s)

Calculator for the real functions

\[{}_sλ_{ℓ,m}(θ) = \begin{cases} {}_sY_{ℓ,m}(θ, 0), & s ∈ ℤ, \\ {}_sY_{ℓ,m}(θ, 0) \big/ i^{2s}, & s ∈ ℤ + \tfrac{1}{2}, \end{cases}\]

for all $ℓ ≤ ℓₘₐₓ$, with elements of the angle's own real type. The first argument is the angle $θ$, or an AbstractVector of Nᵣ of them; later values are supplied with set_θ!. Otherwise this behaves exactly like sYlmCalculator — the same blocks, the same iteration, the same half-integer types — but stores real numbers rather than complex ones, and allocates no phase tables at all. slambdalmCalculator is an ASCII alias of the same constructor.

Both are real. For an integer spin weight the prefactor $(-1)^s$ in the definition of ${}_sY_{ℓ,m}$ is $\pm 1$, so ${}_sY_{ℓ,m}(θ, 0)$ is already real, and ${}_sλ_{ℓ,m}$ is just the harmonic evaluated at $ϕ = 0$, exactly as the literature writes it. For a half-odd spin weight that prefactor is $i^{2s} = \pm i$, so ${}_sY_{ℓ,m}(θ, 0)$ is imaginary rather than real, and dividing that constant phase out is what leaves a real function behind. (Dividing by $i^{2s}$ in both cases would give the wrong sign for odd integer $s$, where $i^{2s} = -1$.) The values are bit-for-bit those of an sYlmCalculator at the same angles: the real part for an integer spin weight, and $±$ the imaginary part for a half-odd one.

A Rotor is not accepted, here or through set_R!: a rotor specifies the angles $α$ and $γ$, whose phases a real calculator cannot represent. Use an sYlmCalculator for that.

See also dCalculator, which stands in the same relation to DCalculator.

HarmonicCalculator{IT, RT, NT, ST, S, B, FT, L}

Calculator producing the spin-weighted spherical harmonics ${}_sY_{ℓ,m}$ (when NT is Complex{RT}) or the real ${}_sλ_{ℓ,m}$ (when NT is RT), for Nᵣ points at a time, one $ℓ$ at a time. Use the constructors sYlmCalculator and sλlmCalculator.

• IT is the index type, Int or HalfOddInteger.
• RT is the real type the calculator works in.
• NT is the number type of the harmonics, Complex{RT} or RT.
• ST is the storage type of the $H$ wedge.
• S is the type of the spin weights served: the index type for one spin weight, or a UnitRange of it for a range of them.
• B is true exactly when the calculator was built from a vector of rotor data, and is what isbatched reads.
• FT is the real type in which the recurrence runs, which is RT itself unless RT holds derivatives, as a dual number does.
• L is Nothing, unless the calculator lifts the blocks of a calculator of the values of its rotors into blocks that hold derivatives, when it is the type of the data for that.

Internally this holds an HCalculator, which runs the recurrence that both subtypes use, and the tables Z₊ and Z₋ of the powers of the rotors' phases, in the same form as the calculators of Wigner's matrices, plus a buffer backing the block for the current $ℓ$. The tables are empty for the real subtype, which is the whole of the saving: the $H$ recurrence is real, and it is only the $e^{-i(mα - sγ)}$ factor that ever made the result complex.

Because S and B decide the shape of the block, the type of the block is known at compile time, and a loop over the blocks is inferrable.

recurrence!(calc, R, ℓ)
recurrence!(calc, ℓ)

Compute the quantities for index $ℓ$ in the calculator calc, and return the block holding them.

In the first form, the rotor data R is stored in the calculator first. For a calculator with Nᵣ rotors, R is an AbstractVector of length Nᵣ; for Nᵣ = 1 a single element is also accepted. The elements may be Rotors or Quaternions, or — for quantities that depend only on $β$, such as $d$ and $H$ — the angle $β$ or the phase $e^{iβ}$.

In the second form, the rotor data from the previous call is reused. Successive calls with $ℓ, ℓ+1, ℓ+2, …$ are the cheap path: each costs $O(N_r ℓ^2)$. Requesting a smaller $ℓ$ than the current one restarts the recurrence from $ℓ_{min}$, so a loop that reads two neighboring $ℓ$ together pays that restart at every step.

This is the only way to read a calculator by hand — the calculators are not indexed — and it is what iterating one calls for each $ℓ$:

for ℓ ∈ 2:ℓₘₐₓ    𝔇ˡ = recurrence!(calc, ℓ)    # 𝔇ˡ[m′, m] for m′, m ∈ -ℓ:ℓend

What comes back depends on the calculator, and in every case it is indexed by the natural ranges rather than from 1:

For a calculator built from a vector of rotor data — of any length, even one — each of the others gains a leading rotor index, so that the first is [iᵣ, m′, m]; an HWedge has that index even for a single rotor, where it is 1. One spin weight of a block that holds several is ₛYₗ[s, :].

ℓ must be an index of the calculator's own kind — an Int for a calculator built with integer indices, and a half-odd-integer, as a HalfOddInteger or a Rational{Int} with denominator 2, for one built with half-integer indices — and must lie between ℓₘᵢₙ(calc) and ℓₘₐₓ(calc); anything else is refused with an ArgumentError. An index that is not of the calculator's kind, including an integer of another type such as an Int8 and a floating-point number such as 2.0, is refused with a message that says how to write it, as it is by every function that takes an index.

The rotor data given this way must be of the calculator's own floating-point type, exactly as for set_R!, set_β! and set_θ!, and anything else is refused rather than converted. A phase given as a Complex number must have unit modulus (to within rounding), and is used as given.

set_R!(calc, R)

Replace the rotor data of calc with the rotor R, and return calc. Any results the calculator was holding are discarded, so the next step of the recurrence starts from $ℓ_{min}$ again.

R must be a Rotor, or an AbstractVector of exactly as many rotors as the calculator handles, which is required when the calculator was built from a vector of rotors; a vector of one rotor is accepted by a calculator built from a single one. A Quaternion may also stand in for a rotor, as the rotation of its normalization; a QuatVec is refused, as not_a_rotor explains. The reason we must accept Quaternions is that some automatic-differentiation packages require the tangent of a type to have the same type; the tangent to the space of Rotors is not a Rotor, but a Quaternion, so we must accept Quaternions to begin with. The number of rotors is fixed at construction and cannot be changed here; for a different number of rotors, build another calculator.

This applies to DCalculator and sYlmCalculator, both of which need the whole rotor. The real $d$ matrices and the $H$ wedge depend on $β$ alone, so their calculators take set_β! instead, and the $(θ, ϕ=0)$ evaluation of the harmonics takes set_θ!; an angle given to set_R! is refused with a message naming it.

The new rotor's floating-point type must be the one the calculator already works in, which was fixed by the rotor it was built from. A mismatch is an error rather than a silent conversion — narrowing a BigFloat rotor into a Float64 calculator would throw away precision that nobody chose to throw away — so convert whichever side you meant, or build a calculator from data of the type you want. floattype(calc) reports the type in use.

Everything is checked before anything is replaced, so data that are refused leave the calculator exactly as it was, including whatever it had computed.

calc = DCalculator(first(rotors), ℓₘₐₓ)for R ∈ rotors    set_R!(calc, R)    for (ℓ, 𝔇ˡ) ∈ calc        # ...    endend

set_β!(calc, β)
set_beta!(calc, β)

Replace the rotor data of calc with the angle β, and return calc. Any results the calculator was holding are discarded. set_beta! is an ASCII alias of the same function.

β may be given as the angle itself, as the phase $e^{iβ}$, or as a Rotor or other Quaternion, of which only the $β$ Euler angle is kept — the $d$ matrices and the $H$ wedge depend on nothing else. A Rotor contributes the $β ∈ [0, π]$ of its canonical Euler decomposition; if the rotor was built from a $β$ outside that range, that $β$ is folded into its $α$ and $γ$, which are discarded here. For a calculator built from a vector, pass an AbstractVector of exactly as many of any one of those forms; a vector of one is accepted by a calculator built from a single value.

This applies to dCalculator and HCalculator. Wigner's $𝔇$ matrices and the spin-weighted harmonics need the whole rotor, so their calculators take set_R! instead.

As for set_R!, the new value's floating-point type must match the calculator's, and data that are refused leave the calculator as it was. An angle that is infinite or NaN has no phase, and a phase whose modulus is not 1 is not one; both are refused with a DomainError.

Half-integer $d$ has period $4π$ in $β$, so an angle or a rotor determines it unambiguously, while a bare phase determines it only up to the double-cover sign $(-1)^{2ℓ}$; the branch $β ∈ (-π, π]$ is used in that case.

set_θ!(calc, θ)
set_theta!(calc, θ)

Replace the rotor data of the sYlmCalculator or sλlmCalculator calc with the angle θ, meaning the point $(θ, ϕ = 0)$, and return calc. Any results the calculator was holding are discarded. set_theta! is an ASCII alias of the same function.

For an sYlmCalculator the values are then ${}_sY_{ℓ,m}(θ, 0)$, stored as complex numbers. For an integer spin weight these are the real functions ${}_sλ_{ℓ,m}(θ)$ that the ring-based transforms are built on, with zero imaginary part; for a half-odd one they are $i^{2s}$ times ${}_sλ_{ℓ,m}(θ)$, and so imaginary. An sλlmCalculator gives ${}_sλ_{ℓ,m}(θ)$ directly, as real numbers. For a calculator built from a vector, pass an AbstractVector of exactly as many angles; a vector of one is accepted by a calculator built from a single angle.

As for set_R!, the angle's floating-point type must match the calculator's, and data that are refused leave the calculator as it was. An angle that is infinite or NaN is refused with a DomainError, and a rotor with an ArgumentError that names the setter for rotors.

For a general point on the sphere use set_R! with from_spherical_coordinates(θ, ϕ).

array_view(w)

The contents of w as an ordinary 1-based array, aliasing its storage (returning a view) rather than copying it.

The containers in this package are deliberately not AbstractArrays, because their natural indices may be half-odd-integers; this is the explicit route from one of them to the plain numbers, with the $ℓ$, $m′$, $m$ and $s$ labels dropped and every axis starting at

1. For a ModeWeights or the result of sYlm it is the flat array in the

canonical mode ordering of Yindex, which is what the transforms take:

Y = sYlm(R, ℓₘₐₓ, s)array_view(Y)[Yindex(ℓ, m, ℓₘᵢₙ)]      # one mode of the flat array

An ordinary 1-based array is returned unchanged, so a function can accept either a labelled container or a bare array without asking which it was given. An array with other axes, such as an OffsetArray, is refused with an ArgumentError, because the result is indexed from 1.

For a calculator's blocks, the blocks of D and d, and the results of copy, similar, and relabel, the result is a contiguous StridedArray, which is the second reason to want it: BLAS needs a unit stride down the first axis and a constant stride between columns — not contiguity — so a block can go straight to mul!, lu!, norm, and the rest with no copy at all:

𝔇₃ = array_view(𝔇₁[ℓ]) * array_view(𝔇₂[ℓ])

The array_view of a block that a calculator returns is moreover linearly indexed, so that sum, broadcasting, and copyto! run over it as fast as over an Array, and a batch can be reshaped to a matrix of Nᵣ times as many rows for BLAS without a copy.

A single rotor's slice of a batched block has a leading stride of Nᵣ, so BLAS cannot take it; mul! then falls back to the generic implementation, which is slower but correct. The answer is never wrong, only sometimes slow.

See also relabel, which is the return leg.

relabel(w, A)

A container with the natural indices of w and the data of the plain array A, which must have the shape of w.

This is the return leg of a trip through linear algebra, so that a result comes back labelled rather than as a bare array:

𝔇₃ = relabel(𝔇₁[ℓ], array_view(𝔇₁[ℓ]) * array_view(𝔇₂[ℓ]))

A is used as storage, not copied, exactly as the container constructors do.

The labels are those of w, whatever A holds. For a ModeWeights that includes the spin weight, so the result of a spin-changing operator matrix applied to array_view(w), such as ð(s, ℓₘᵢₙ, ℓₘₐₓ) * array_view(w), is labelled correctly only by ModeWeights(A, s + 1, ℓₘᵢₙ, ℓₘₐₓ); the operator itself, ð * w, gives the labelled result directly.

See also array_view.

AbstractBlock{IT, NT, ST}

Abstract supertype of the blocks, the containers that hold the values of one $ℓ$, indexed by their natural indices $m′$, $m$ and $s$ rather than by position. There are six: WignerMatrix, indexed w[m′, m], WignerMatrixBatch, w[iᵣ, m′, m], DegreeBlock, v[m], DegreeBlockBatch, v[iᵣ, m], SpinMatrix, b[s, m], and SpinMatrixBatch, b[iᵣ, s, m].

• IT is the index type, Int or HalfOddInteger, which is the type of $ℓ$ and of every natural index.
• NT is the number type, such as ComplexF64 for a block of $𝔇$ or Float64 for one of $d$.
• ST is the type of the storage, parent(w), which is one-dimensional and 1-based (see below).

A block's storage is one-dimensional, and element k of the block, in the order of Array(w) (the column-major order of its axes), is entry k of the storage; entries beyond length(w) are not read. The constructors take a 1-based array of any shape with at least length(w) entries and use it in its linear order: the storage is vec of that array, which shares its memory, and an array of exactly the block's shape is the block. A calculator's blocks are the leading entries of the calculator's one buffer, so parent(w) of such a block is that buffer. The blocks of D and d are consecutive parts of one vector, which holds them all, so parent(w) of each is a view of its own part. array_view(w) is the block's entries of the storage, reshaped to the block's shape, without a copy: contiguous for a calculator's block, for the blocks of D and d, and for the results of copy, similar, and relabel. A slice of a batch, w[iᵣ] or b[iᵣ], and the row b[s, :] of a SpinMatrix, are views of an arithmetic progression of the storage, with the step Nᵣ or the number of spin weights. The one exception is the slice b[:, s, :] of a SpinMatrixBatch, whose elements are not one such progression: its storage is a strided matrix view of exactly its shape, and its array_view is that matrix.

These types are not AbstractArrays, because half-integer indices cannot satisfy that interface: axes must be integer ranges there, and -3//2:3//2 is not one. Consequently linear algebra (*, ', \, lu) does not apply to them; array_view gives the numbers as an ordinary 1-based array, and relabel puts the labels back.

Methods

Every block has parent(w), the storage; ℓ(w), the degree; ℓₘᵢₙ(w), the smallest degree of the index type, 0 or 1//2; eltype(w), the number type; ishalfinteger; and summary and show. Each block defines its own indexing, since the natural indices differ from one to the next, and all six share an array-like interface as well:

• axes(w) are the ranges of the natural indices, one per axis, with 1:Nᵣ for the rotor axis of a batch, and size(w), length(w) and ndims(w) describe the block, whose storage may be larger, as a calculator's buffer is;
• the limits are read with m′ₘₐₓ, m′ₘᵢₙ, mₘₐₓ, mₘᵢₙ, sₘₐₓ and sₘᵢₙ, for the axes a block has, and isbatched says whether it has a rotor axis;
• checkbounds(Bool, w, inds...) tests natural indices;
• Array(w) and collect(w) copy the block into an ordinary 1-based array, as do Matrix(w) for a two-axis block and Vector(v) for a DegreeBlock;
• copy(w) and similar(w) keep the labels, and iteration visits the elements in the order of Array(w);
• ==, isequal, hash and ≈ compare the labels — the kind of block, $ℓ$ and the axes — as well as the numbers, so the same numbers under different labels are not equal;
• broadcasting gives an ordinary 1-based Array, and a broadcast that combines blocks, or writes into one with .=, requires their labels to agree, since it pairs the elements by position.

Note that there is deliberately no linear indexing (w[i]), for the reason given above.

WignerMatrix{IT, NT, ST} <: AbstractBlock{IT, NT, ST}
WignerMatrix(parent, ℓ; m′ₘₐₓ=ℓ, m′ₘᵢₙ=-m′ₘₐₓ, mₘₐₓ=ℓ, mₘᵢₙ=-mₘₐₓ)

General concrete subtype of AbstractBlock for Wigner rotation matrices, which can include D-matrices (when NT is complex) or d-matrices (when NT is real).

• IT is the index type, Int or HalfOddInteger.
• NT is the number type of the elements.
• ST is the type of the storage, an AbstractVector{NT} (see AbstractBlock).

The block holds some or all of the Wigner matrix for a specific $ℓ$, as a rectangular array whose first dimension corresponds to the m′ index and whose second corresponds to the m index; how it is stored is described under AbstractBlock. The allowed ranges of m′ and m are governed by the fields m′ₘₐₓ, m′ₘᵢₙ, mₘₐₓ, and mₘᵢₙ, which must satisfy

\[\begin{aligned} -ℓₘₐₓ &≤ m′ₘᵢₙ ≤ -ℓₘᵢₙ ≤ ℓₘᵢₙ ≤ m′ₘₐₓ ≤ ℓₘₐₓ, \\ -ℓₘₐₓ &≤ mₘᵢₙ ≤ -ℓₘᵢₙ ≤ ℓₘᵢₙ ≤ mₘₐₓ ≤ ℓₘₐₓ, \end{aligned}\]

where ℓₘᵢₙ is either 0 or 1//2 depending on whether IT is an integer or half-integer type. Both rows ±ℓₘᵢₙ must be included because the recurrence seeds the half-integer ladder from the pair of rows m′ = ±1/2; for integers this reduces to the familiar m′ₘᵢₙ ≤ 0 ≤ m′ₘₐₓ.

The constructor wraps parent without copying it. parent is a 1-based array of any shape with at least (m′ₘₐₓ-m′ₘᵢₙ+1) × (mₘₐₓ-mₘᵢₙ+1) entries, read in its linear order, so that a matrix of exactly that size is the block. ℓ and the limits must all be integers of type Int, or all half-odd-integers, each a HalfOddInteger or a Rational{Int} with denominator 2; the limits default to the whole block, and each lower limit defaults to minus the corresponding upper one. The keywords may also be spelled mp_max, mp_min, m_max, and m_min; where both spellings of one are given, the Unicode one is used.

WignerMatrixBatch{IT, NT, ST} <: AbstractBlock{IT, NT, ST}
WignerMatrixBatch(parent, ℓ; m′ₘₐₓ=ℓ, m′ₘᵢₙ=-m′ₘₐₓ, mₘₐₓ=ℓ, mₘᵢₙ=-mₘₐₓ)

Nᵣ Wigner matrices of one $ℓ$, stored together and indexed as w[iᵣ, m′, m]. This is what recurrence! returns for a calculator built from a vector of rotor data, of any length, for either kind of index.

• IT is the index type, Int or HalfOddInteger.
• NT is the number type of the elements.
• ST is the type of the storage, an AbstractVector{NT} (see AbstractBlock).

The elements are ordered [iᵣ, m′, m], exactly as in the calculator. The constructor takes a 1-based array of any shape, whose first extent is Nᵣ and which has at least as many entries as the block, read in its linear order, so that an array of exactly the block's shape is the block; it takes the indices and the limits, with their ASCII spellings, exactly as WignerMatrix does, and under the same rules. w[iᵣ] gives the WignerMatrix view of one rotor's matrix, which is then indexed naturally as w[iᵣ][m′, m].

See also WignerMatrix and WignerSeries.

DegreeBlock{IT, NT, ST}

One harmonic degree's worth of values, indexed naturally by the order $m$: v[m] for $mₘᵢₙ ≤ m ≤ mₘₐₓ$. This is the 1-dimensional sibling of WignerMatrix.

• IT is the index type, Int or HalfOddInteger.
• NT is the number type of the elements.
• ST is the type of the storage, an AbstractVector{NT} (see AbstractBlock).

The name is deliberately neutral, because the same shape serves three things: a block of spin-weighted harmonics at one $ℓ$, from sYlm or sYlmCalculator's ₛYₗ[s, :]; one $ℓ$'s worth of mode weights, from ModeWeights's w[ℓ, :]; and one spin weight's row of a SpinMatrix, from b[s, :]. All three are values at a fixed degree indexed by order, whatever they mean.

The elements are in order of increasing $m$. The constructor

DegreeBlock(parent, ℓ; mₘₐₓ=ℓ, mₘᵢₙ=-mₘₐₓ)

wraps parent without copying it. parent is a 1-based array of any shape with at least mₘₐₓ-mₘᵢₙ+1 entries, read in its linear order, so that a vector of exactly that length is the block. The limits must satisfy -ℓ ≤ mₘᵢₙ ≤ mₘₐₓ ≤ ℓ; unlike the limits of a WignerMatrix, these need not bracket zero, because no recurrence fills the block. ℓ and the limits must all be integers of type Int, or all half-odd-integers, each a HalfOddInteger or a Rational{Int} with denominator 2. The keywords may also be spelled m_max and m_min.

See also DegreeBlockBatch.

DegreeBlockBatch{IT, NT, ST}

Nᵣ rows of values of a single $ℓ$, stored together and indexed as v[iᵣ, m]. This is the 1-dimensional sibling of WignerMatrixBatch, and is what a batched sYlmCalculator built for one spin weight yields, for either kind of index. v[iᵣ] gives the DegreeBlock view of one rotor's row.

• IT is the index type, Int or HalfOddInteger.
• NT is the number type of the elements.
• ST is the type of the storage, an AbstractVector{NT}, or an AbstractMatrix{NT} for the slice b[:, s, :] of a SpinMatrixBatch (see AbstractBlock).

The elements are ordered [iᵣ, m]. The constructor, DegreeBlockBatch(parent, ℓ; mₘₐₓ=ℓ, mₘᵢₙ=-mₘₐₓ), takes a 1-based array of any shape, whose first extent is Nᵣ and which has at least as many entries as the block, read in its linear order, so that a matrix of exactly the block's shape is the block; it takes the indices and the limits exactly as DegreeBlock does, and under the same rules.

SpinMatrix{IT, NT, ST}

The values of a single $ℓ$ for a range of spin weights, indexed naturally by $(s, m)$: b[s, m] for $sₘᵢₙ ≤ s ≤ sₘₐₓ$ and $mₘᵢₙ ≤ m ≤ mₘₐₓ$, and b[s, :] for one whole row as a DegreeBlock. This is what an sYlmCalculator built for a range of spin weights yields for each $ℓ$.

• IT is the index type, Int or HalfOddInteger.
• NT is the number type of the elements.
• ST is the type of the storage, an AbstractVector{NT} (see AbstractBlock).

The elements are ordered [s, m]. The constructor

SpinMatrix(parent, ℓ; sₘₐₓ, sₘᵢₙ, mₘₐₓ=ℓ, mₘᵢₙ=-mₘₐₓ)

wraps parent without copying it. parent is a 1-based array of any shape with at least as many entries as the block, read in its linear order, so that a matrix of exactly the block's shape is the block. The spin limits are required, and the keywords may also be spelled s_max, s_min, m_max, and m_min. ℓ and every limit must all be integers of type Int, or all half-odd-integers, each a HalfOddInteger or a Rational{Int} with denominator 2. The $m$ axis obeys the rule of DegreeBlock, -ℓ ≤ mₘᵢₙ ≤ mₘₐₓ ≤ ℓ.

The spin axis, spins(b), is under none of the restrictions a WignerMatrix places on its $m′$: it is whatever range of spin weights was asked for, so it may lie wholly on one side of zero, and it may reach beyond $ℓ$ — the harmonics with $|s| > ℓ$ simply vanish, and a calculator stores them as zeros. It must only be in order, sₘᵢₙ ≤ sₘₐₓ.

See also SpinMatrixBatch and DegreeBlock.

SpinMatrixBatch{IT, NT, ST}

Nᵣ SpinMatrix blocks of one $ℓ$, stored together and indexed as b[iᵣ, s, m]. This is what a batched sYlmCalculator yields when it was built for a range of spin weights. b[iᵣ] gives the SpinMatrix view of one rotor's block, which is then indexed naturally as b[iᵣ][s, m].

• IT is the index type, Int or HalfOddInteger.
• NT is the number type of the elements.
• ST is the type of the storage, an AbstractVector{NT} (see AbstractBlock).

The elements are ordered [iᵣ, s, m], exactly as in the calculator. The constructor, SpinMatrixBatch(parent, ℓ; sₘₐₓ, sₘᵢₙ, mₘₐₓ=ℓ, mₘᵢₙ=-mₘₐₓ), takes a 1-based array of any shape, whose first extent is Nᵣ and which has at least as many entries as the block, read in its linear order, so that an array of exactly the block's shape is the block; it takes the indices and the limits exactly as SpinMatrix does, and under the same rules.

See also SpinMatrix and DegreeBlockBatch.

AbstractDegreeSeries{IT}

Supertype of the series of blocks indexed by the degree $ℓ$: WignerSeries, the blocks of a Wigner matrix, and HarmonicValues, the values of the spin-weighted spherical harmonics.

• IT is the index type, Int or HalfOddInteger.

A series s holds one block for each $ℓ$ from ℓₘᵢₙ(s) to ℓₘₐₓ(s), and s[ℓ] is the block of degree $ℓ$; for a half-integer series ℓ may be written as a HalfOddInteger or as a Rational{Int} with denominator 2, and for an integer series it is an Int. Like a calculator, a series iterates as ℓ => block pairs, so eltype(s) is that pair type; keys(s) is the range of $ℓ$, and length(s) counts the blocks. first(s) and last(s) are the first and last blocks, as indexing gives them, and so are first(s, n) and last(s, n), which give vectors of the first or last n blocks, and only(s), the one block of a series that has only one. ishalfinteger says which kind of index the series takes.

A series is not an AbstractVector: $ℓ$ may be a half-odd-integer, and the axes of an AbstractVector must be integer ranges.

WignerSeries{IT, VT}
WignerSeries(blocks, ℓₘᵢₙ, ℓₘₐₓ)

The blocks of a Wigner matrix for every $ℓ$ from ℓₘᵢₙ to ℓₘₐₓ, indexed by $ℓ$: s[ℓ] is the block of degree ℓ, and s[ℓ][m′, m] an element of it. For a half-integer series ℓ may be written as a HalfOddInteger or as a Rational{Int} with denominator 2, and for an integer series it is an Int.

• IT is the index type, Int or HalfOddInteger.
• VT is the type of the vector of blocks.

This is what D and d return, for either kind of index. Like a calculator, it iterates as ℓ => block pairs, so that for (ℓ, 𝔇ˡ) ∈ D(R, ℓₘₐₓ) reads exactly as the same loop over a DCalculator; keys is the range of $ℓ$, values gives the blocks alone, and length counts them. first and last give the first and last blocks, as indexing does, and so do first(s, n) and last(s, n), which give vectors of the first or last n blocks, and only(s), the one block of a series that has only one.

Two series are ==, isequal or ≈ when they have the same range of $ℓ$ and their blocks are, block by block; ≈ applies its tolerances to each block separately.

The constructor takes a 1-based vector of blocks without copying it, and requires block i to have $ℓ = ℓₘᵢₙ + i - 1$, with the index type of the bounds. The bounds must both be integers of type Int, or both half-odd-integers, each a HalfOddInteger or a Rational{Int} with denominator 2.

See also WignerMatrix and WignerMatrixBatch.

HarmonicValues

The values of the spin-weighted spherical harmonics ${}_sY_{ℓ,m}$ at one or more rotors, indexed first by $ℓ$ and then naturally within the block:

The parameters of HarmonicValues{T, IT, S, A} are as follows:

• T is the number type.
• IT is the index type, Int or HalfOddInteger.
• S is the type of the spin weights: IT for one, or a range of IT for several.
• A is the type of the storage, an array of T.

This is what sYlm returns. The blocks are DegreeBlock, DegreeBlockBatch, SpinMatrix and SpinMatrixBatch respectively, and are views into the storage rather than copies, so writing through one writes into Y.

array_view gives the flat storage: a Vector of modes, or an array whose last axis is the modes in the canonical ordering (see Yindex) and whose leading axes are the rotors and spin weights. That is the form a product with mode weights takes, and sYlm_matrix is the direct name for it.

spins(Y) is the range of spin weights served, spin(Y) the single value when there is only one, Nᵣ(Y) the number of rotors, isbatched(Y) whether there is a rotor axis, and ℓₘᵢₙ(Y)/ℓₘₐₓ(Y) the range of $ℓ$.

Y[ℓ] and Y[ℓ, :] both give the block of degree $ℓ$, the second as w[ℓ, :] gives the block of a ModeWeights w; for a half-integer Y, ℓ may be written as a HalfOddInteger or as a Rational{Int} with denominator 2, and for an integer Y it is an Int. first(Y) and last(Y) are the first and last blocks, as indexing gives them, and so are first(Y, n), last(Y, n) and only(Y), as for a WignerSeries. Iterating gives ℓ => block pairs, as a calculator does, so eltype(Y) is that pair type; the number type is eltype(array_view(Y)). length(Y) counts the blocks, and keys(Y) is the range of $ℓ$.

HarmonicValues(data, s, ℓₘᵢₙ, ℓₘₐₓ, Nᵣ) wraps existing storage of one of those four shapes without copying it. Its labels must describe the storage: the rank must be that of one of the shapes, the spin axis as long as the range s, the leading axis Nᵣ long (Nᵣ = 1 without it), and the mode axis Ysize(ℓₘᵢₙ, ℓₘₐₓ) long. The indices must all be integers of type Int, or all half-odd-integers, each a HalfOddInteger or a Rational{Int} with denominator 2.

copy, similar and relabel keep the labels. As for a ModeWeights, two HarmonicValues are equal, or approximately equal, only when their labels agree as well as their numbers, while ==, isequal and ≈ against a plain array compare the numbers of array_view(Y); hash is therefore that of the numbers alone. Broadcasting reads the numbers of array_view(Y) and gives a plain array, and Y .= x writes into the storage; a broadcast that combines two HarmonicValues, or writes one into another, requires their labels to agree, since it pairs the numbers by position.

See also ModeWeights, which shares this layout but holds the weights of a function rather than the values of the harmonics.

WignerCalculator{IT, RT, NT, ST, B, FT, L}

Calculator producing Wigner's $𝔇$ matrices (when NT is Complex{RT}) or $d$ matrices (when NT is RT) for Nᵣ rotors at a time, one $ℓ$ at a time. Use the constructors DCalculator and dCalculator. The type parameters are as follows:

• IT is the index type, Int or HalfOddInteger.
• RT is the real type of the rotor data, and of the elements.
• NT is the number type of the matrix elements, Complex{RT} or RT.
• ST is the storage type of the $H$ wedge.
• B is true exactly when the calculator was built from a vector of rotor data, of any length, and is what isbatched reads.
• FT is the real type in which the recurrence runs, which is RT itself unless RT holds derivatives, as a dual number does.
• L is Nothing, unless the calculator lifts the blocks of a calculator of the values of its rotors into blocks that hold derivatives, when it is the type of the data for that.

Internally this holds an HCalculator, which does the actual recurrence, and the tables of the powers of the rotors' phases, in the same form as the calculators of the harmonics, plus a buffer into which the requested block of the matrix is written for the current $ℓ$; that block is what recurrence! returns, as a WignerMatrix indexed naturally by [m′, m], or a WignerMatrixBatch indexed by [iᵣ, m′, m] when the calculator was built from a vector of rotor data.

A calculator whose rotor data hold derivatives, such as dual numbers, runs the recurrence on the values of those data, in FT, and gives each block its derivatives from the angular-momentum operators (for $d$, from the one about the $y$ axis), as described in src/derivatives/kernels.jl; the recurrence itself is never differentiated.

Because B is a type parameter, the type of the block is known at compile time, and a loop over the blocks is inferrable.

HWedge{IT, RT, ST}
HWedge(RT, Nᵣ, ℓₘₐₓ, m′ₘₐₓ=ℓₘₐₓ)

A compact, real-valued workspace holding the $Hˡ$ matrix of one $ℓ$ for Nᵣ rotors at once.

• IT is the index type, Int or HalfOddInteger.
• RT is the real type of the elements.
• ST is the type of the flat storage, a vector of RT.

The $Hˡ$ matrix is critical to efficient and stable computation of the Wigner $D$ and $d$ matrices — in fact, it essentially is the $d$ matrix with signs adjusted to avoid numerical problems with alternating signs. This gives it additional symmetries that reduce the amount of data that needs to be stored to about 1/4 of the total $d$ size.

The purpose of an HWedge is to provide a workspace for the Wigner recurrences that is efficient, both in terms of the size of memory used, and the implications for vectorization. Specifically, the data is stored as strictly Real values, in contiguous storage. Indexing is performed efficiently via precomputed row offsets. Once the full recurrence is done, the data can be used directly — computing phases and symmetry on the fly — or copied into a full explicit matrix with the appropriate phases.

The recurrences require $m$ in the full range from 0 (or 1/2) to $ℓ$, but $m'$ only needs the rows $|m'| ≤ m'_{\mathrm{max}}$, which must include the axis $m'=0$ for integer indices and both rows $m' = ±1/2$ for half-integer ones. The range of $m'$ is always symmetric, so m′ₘᵢₙ(H) is -m′ₘₐₓ(H), and only enough storage for those rows is allocated. Specifically, an HWedge stores elements in a vector as if they were components of the Hˡ matrix:

[    Hˡ[m′, m]    for m′ ∈ max(-ℓ, -m′ₘₐₓ):min(ℓ, m′ₘₐₓ)    for m ∈ abs(m′):ℓ]

However, for further efficiency when vectorizing over multiple rotors, the data is stored as a 1-dimensional vector, though it can be indexed as if it were a three-dimensional array, with the first dimension indexing Nᵣ different rotors, and the second dimension indexing m′, and the third dimension indexing m. Thus, this object can be indexed as Hˡ[iᵣ, m′, m] to get the Hˡ value for rotor index iᵣ, and matrix element (m′, m). Accordingly ndims(Hˡ) is 3 and axes(Hˡ) and size(Hˡ, d) describe those three indices, while length(Hˡ) and size(Hˡ) describe the flat storage, which is what linear indexing Hˡ[i] runs over. Only the elements with $m ≥ |m'|$ are stored; the others are read through wedge_value, which applies the symmetries of $H$.

Because of this complicated layout, the constructor is fairly restrictive, but will do all the allocation needed. ℓₘₐₓ and m′ₘₐₓ may be integers, or half-integers given as Rationals with denominator 2 or as HalfOddIntegers, as for the other index arguments. To avoid multiple allocations, it is advisable to first construct an instance with the maximum ℓ value that will be needed, and then change the ℓ field as needed to compute different orders. That is, if H isa HWedge, then H.ℓ = new_ell can be used to change the current order being computed; this lays out the storage for the new order without computing anything. The constructor starts out with the smallest ℓ value possible (0 or 1/2), which is the natural choice for recurrence. The wedge an HCalculator returns is that calculator's own workspace, so its ℓ should not be reassigned; copy(Hˡ) gives an independent wedge holding the same numbers, which survives the calculator's next step.

wedge_value(H::HWedge, iᵣ, m′, m)

Value of $H_{m′,m}$ for rotor iᵣ, for any $|m′|, |m| ≤ ℓ$ (at least one of them $≤ m′ₘₐₓ$), read from the stored wedge through wedge_source, which applies the symmetry sign $σ$ of half-integer indices. This is the way to read an element of $H$ that the wedge does not store, and the only correct one for half-integer indices, where transposing the stored elements by hand gets the sign of half of them wrong.

m′ and m must be of the wedge's own kind: Ints for an integer wedge, and half-odd-integers — HalfOddIntegers, or Rational{Int}s with denominator 2 such as 1//2 — for a half-integer one. An index of the other kind is refused with an ArgumentError rather than floored onto a neighboring element, and so is an integer of another type, such as an Int8, as it is by every function that takes an index. An element that the wedge cannot supply is a BoundsError or, when both $|m′|$ and $|m|$ exceed m′ₘₐₓ(H), an ArgumentError.

w[iᵣ]

The WignerMatrix of rotor iᵣ in a WignerMatrixBatch, as a view; index it naturally as w[iᵣ][m′, m].

b[s, :]

The row of one spin weight of a SpinMatrix, as a DegreeBlock view; it is then indexed naturally as b[s, :][m]. The notation follows ModeWeights's w[ℓ, :], so that a loop over spin weights reads the same in both places.

b[:, s, :]

The rows of one spin weight of a SpinMatrixBatch, over every rotor, as a DegreeBlockBatch view; it is then indexed naturally as b[:, s, :][iᵣ, m]. The notation follows SpinMatrix's b[s, :].

b[iᵣ]

The SpinMatrix of rotor iᵣ in a SpinMatrixBatch, as a view; index it naturally as b[iᵣ][s, m].

w[ℓ, m]

The mode weight of $(ℓ, m)$ in the ModeWeights w. For a w with half-integer indices, ℓ and m may be passed as Rational{Int}s with denominator 2 — w[3//2, 1//2] — or as HalfOddIntegers, either way for each; for a w with integer indices they must be Ints. An index of another kind or type is refused with an ArgumentError that says why, as the constructors refuse one.

w[ℓ, :]

A view of the mode weights of the ModeWeights w for the given $ℓ$, indexed by m ∈ -ℓ:ℓ. This is a DegreeBlock for either kind of index; where the indices are half-odd-integers they may be passed either as Rationals or as HalfOddIntegers. Writing through the view writes into w.

similar(w::AbstractBlock, [T=eltype(w)])

A new block of the same kind as w, with the same ℓ and the same natural axes (and so, for a batch, the same Nᵣ), over uninitialized storage of element type T. The storage is a Vector of exactly length(w) entries, even when parent(w) is a calculator's buffer or a view.

similar(calc)
similar(calc, R)

A second calculator of exactly the type of calc — the same limits, number of rotors and element type — with storage of its own and nothing computed. With one argument it holds a copy of the rotor data of calc, so that stepping it gives the values calc would give; with two it holds the rotor data R instead, which must describe the same number of rotors, in the same floating-point type. This applies to every calculator: DCalculator, dCalculator, HCalculator, sYlmCalculator and sλlmCalculator.

Unlike similar of an array, this does copy the rotor data, because a calculator without rotor data is not representable, and the rotor data cannot be recovered from what a calculator stores. The second argument is rotor data rather than an element type; to compute in another type, build a calculator from rotor data of that type.

A calculator is a mutable workspace, which every step and every setter overwrites, so one calculator must not be used by two tasks at once. similar is the way to give each task a calculator of its own; the two share nothing that either one changes.

fill!(w::HCalculator, v)

Fill every internal buffer of w (both axes, the wedge, and the table of recurrence coefficients) with the value v, and mark the axis data as invalid. The stored rotor data — the phases e^{iβ} and, on the half-integer path, the half angles — is deliberately left alone, so that recurrence!(w, ℓ) still has everything it needs, and so is the constant table of square roots that the constructor builds, which the recurrence reads but never writes. Useful for testing that no uninitialized storage is ever read: everything the recurrence is responsible for writing is poisoned, while everything the rotor data consists of is preserved.

fill!(c::WignerCalculator, v)

Fill the axis, wedge and output buffers of c with the value v and mark the current results as invalid. The stored rotor data — e^{iβ}, the half angles, the phase powers Z₊ and Z₋ — is deliberately not touched, so recurrence!(c, ℓ) still has everything it needs, exactly as for HCalculator. Useful for testing that no uninitialized storage is ever read: everything the recurrence is responsible for writing is poisoned, while everything set_rotors! is responsible for writing is left alone.

fill!(c::sYlmCalculator, v)

Fill the axis, wedge and output buffers of c with the value v and mark the current results as invalid. The stored rotor data — e^{iβ}, the half angles, the phase powers Z₊, Z₋, and the flag recording whether rotors or bare angles were given — is deliberately not touched, so recurrence!(c, ℓ) still has everything it needs, exactly as for HCalculator. Useful for testing that no uninitialized storage is ever read.

collect(calc)

Every $ℓ$ of a calculator, as an ordinary 1-based Vector of ℓ => block pairs, with each block copied.

The copies are the point: the blocks a calculator yields are views into storage that the next step overwrites, so a collect that did not copy would hand back length(calc) aliases of one buffer, all holding the last $ℓ$. Each copy keeps its natural $(m′, m)$ indices, and generic functions that store what they are handed — map, first(calc, n), Iterators.take — do not copy, so use this or copy the block inside the loop.

Note that the result is indexed from 1, while D and d return containers indexed by $ℓ$; collect(calc)[i] is the pair whose first element is the $ℓ$.

values(calc) iterates over the blocks alone, as values of a WignerSeries does. Those blocks are the same views that iteration over calc yields, and collect(values(calc)) copies each of them for the same reason.

Matrix(w::WignerMatrix)

Materialize the block of the Wigner matrix represented by w as an ordinary Matrix. The rows and columns are in order of increasing m′ and m, so that the element w[m′, m] is at [Int(m′-m′ₘᵢₙ)+1, Int(m-mₘᵢₙ)+1].

ℓ(x)
ell(x)

The value of $ℓ$ that x currently holds: the degree of a block (WignerMatrix, DegreeBlock, HWedge, …), or of the block most recently computed by a calculator. For a calculator on which recurrence! has not been called since it was built, or since its data were last replaced (by set_R!, set_β!, set_θ! or fill!), this is ℓₘᵢₙ(x) - 1.

ℓₘᵢₙ(x)
ell_min(x)

The smallest $ℓ$ that x holds or can hold.

For a block or a calculator, this is the smallest degree of the index type: 0 for integer indices and 1//2 for half-integer ones. For a ModeWeights, a HarmonicValues, a WignerSeries, or a transform, it is the smallest $ℓ$ stored, which may be larger, such as the $|s|$ of the weights that an analysis returns.

ℓₘₐₓ(x)
ell_max(x)

The largest $ℓ$ that x can hold — the value its storage was sized for.

m′ₘₐₓ(x)
mp_max(x)

The largest $m'$ in the block x holds or returns. For a calculator this is the keyword argument of the same name, which restricts the rows that are computed.

m′ₘᵢₙ(x)
mp_min(x)

The smallest $m'$ in the block x holds or returns. Note that both $±ℓₘᵢₙ$ must lie in m′ₘᵢₙ(x):m′ₘₐₓ(x), because the recurrence seeds the half-integer ladder from the pair of rows $m' = ±1/2$; for integer indices that reduces to the familiar m′ₘᵢₙ ≤ 0 ≤ m′ₘₐₓ.

The blocks with a single $m$ axis, DegreeBlock, SpinMatrix and their batches, have no $m'$, and this and m′ₘₐₓ refuse them with an explanation.

mₘₐₓ(x)
m_max(x)

The largest $m$ in the block x holds or returns.

mₘᵢₙ(x)
m_min(x)

The smallest $m$ in the block x holds or returns. For a WignerMatrix, a WignerMatrixBatch or a calculator, the range must bracket $±ℓₘᵢₙ$, as for m′ₘᵢₙ, because the recurrence computes those blocks. The blocks that no recurrence fills, DegreeBlock, SpinMatrix and their batches, require only -ℓ ≤ mₘᵢₙ(x) ≤ mₘₐₓ(x) ≤ ℓ.

spins(c)

The spin weights an sYlmCalculator serves, as a range. A calculator built for a single spin weight reports the one-element range containing it, so that this accessor answers in the same currency whichever way the calculator was built; spin gives the value itself, and has no method for a calculator built for several.

For a SpinMatrix or a SpinMatrixBatch, which is what such a calculator yields when it serves several spin weights, this is the range of spin weights the block holds, sₘᵢₙ(b):sₘₐₓ(b). For a HarmonicValues it is the range of spin weights the values were computed for, again a one-element range when there is only one.

sₘₐₓ(x)
s_max(x)

The largest $s$ in the block x holds. Unlike m′ₘₐₓ, this is under no obligation to bracket zero or to stay within $±ℓ$: a block of spin-weighted harmonics may hold any consecutive run of spin weights, and those with $|s| > ℓ$ are zero.

sₘᵢₙ(x)
s_min(x)

The smallest $s$ in the block x holds; see sₘₐₓ.

spin(w)

The spin weight of a ModeWeights vector, of an SSHT transform, or of an sYlmCalculator built for a single one. A calculator built for a range of spin weights has no single value to report, so it has no method here; ask it for spins instead, which answers for either kind.

A function of spin weight $s$ has $R_z f = s f$, and is expanded in the harmonics ${}_{s}Y_{ℓ,m}$ with $ℓ ≥ |s|$. The spin weight is kept alongside the numbers because nothing about the numbers themselves reveals it.

julia> using SphericalFunctionsjulia> spin(ModeWeights(zeros(ComplexF64, 21), -2))-2julia> spin(SSHT(1, 4))1

See also modes, ModeWeights, SSHT, and spins.

Nᵣ(x)
Nr(x)

The number of rotors x handles at once. A calculator built from a vector of rotor data evaluates the whole batch in one pass, and its blocks have a leading rotor index, 𝔇ˡ[iᵣ, m′, m], even when the vector has only one element; isbatched says which kind a calculator is, since Nᵣ == 1 does not.

floattype(x)
floattype(T)

The floating-point type in which x, or anything of type T, is computed. For a calculator or a transform, this is the type it works in, and its results are that type, or Complex of it. For rotor data — a Rotor or other Quaternion, an angle β::Real, a phase e^{iβ}::Complex, or an AbstractVector of any one of those — it is the type in which a calculator built from that data works: the float of the data's component type, so that a Rotor{Float32} gives a Float32 calculator, a Rotor{Double64} a Double64 one, and the angle 3 a Float64 one. As with eltype, the method for a value is that for its type.

The type of the rotor data is the only thing that decides the type in which a calculator works. There is no way to set it independently of the data: to compute in some other type, convert the data — which is also the honest way to say it, since the type of the data is the claim being made about the points. The methods that replace a calculator's data — set_R!, set_β!, set_θ! — require the new data to agree with what this reports. A Quaternion counts as a rotor here; we always divide out by the norm, and accept Quaternion for compatibility with various automatic-differentiation packages.

The rotor data must therefore commit to a type to go on: data whose component type is abstract, such as a Complex{Real} or a Vector{Rotor{Real}}, or a vector whose element type is abstract or a Union, is refused with an ArgumentError rather than guessed at, as is a QuatVec, which does not denote a rotation (see not_a_rotor).

nmodes(𝒯)

Number of mode weights the transform 𝒯 works with, Ysize(abs(s), ℓₘₐₓ).

npixels(𝒯)

Number of sample points (function values) the transform 𝒯 works with.

ishalfinteger(w)

Whether the natural indices of w are half-odd-integers (true) or integers (false). This is a property of the index type — half-odd-integer indices are represented as HalfOddIntegers — so it is known at compile time.

isbatched(c)

Whether the calculator c was built for a batch of rotors (true, when it was built from a vector of rotor data, of any length) or for a single one (false). Like ishalfinteger, this is a property of the type rather than of the data, so it is known at compile time — which is what lets the block that recurrence! returns have a single, inferrable type rather than a union of the batched and unbatched ones. For a HarmonicValues it says whether the storage has a rotor axis, which again it has exactly when the values were computed for a vector of rotors. For a block it says whether the block has a leading rotor axis: it is true for a WignerMatrixBatch, a DegreeBlockBatch and a SpinMatrixBatch, which is what a batched calculator returns, and false for the other blocks.