Wigner's $𝔇$ and $d$ matrices

D_matrices(R, ℓₘₐₓ)
D_matrices(α, β, γ, ℓₘₐₓ)

Compute Wigner's 𝔇 matrices $\mathfrak{D}^{(\ell)}_{m',m}(\beta)$ for all $\ell \leq \ell_\mathrm{max}$.

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

This function only appropriate when you need to evaluate the matrices 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 D_prep, and then call D_matrices! with the result instead.

D_matrices!(D_storage, R)
D_matrices!(D_storage, α, β, γ)
D_matrices!(D, R, ℓₘₐₓ)
D_matrices!(D, α, β, γ, ℓₘₐₓ)

Compute Wigner's 𝔇 matrices $\mathfrak{D}^{(\ell)}_{m',m}(\beta)$ for all $\ell \leq \ell_\mathrm{max}$.

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

[
    𝔇ˡₘₚ,ₘ(R)
    for ℓ ∈ 0:ℓₘₐₓ
    for mp ∈ -ℓ:ℓ
    for m ∈ -ℓ:ℓ
]

When the first argument is D, it will be modified, so it must be at least as large as that array. When the first argument is D_storage, it should be the quantity returned by D_prep, and the result will be written into the D 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 D or D_storage arguments must have types compatible with the type of R or α, β, γ.

The α, β, γ arguments are Euler angles as described in the documentation of Quaternionic.from_euler_angles.

See also D_matrices for a simpler function call when you only need to evaluate the matrices for a single value of R or α, β, γ.

Examples

using Quaternionic, SphericalFunctions
ℓₘₐₓ = 8
T = Float64
R = Rotor{T}(1, 2, 3, 4)  # Will be normalized automatically
D_storage = D_prep(ℓₘₐₓ, T)
D = D_matrices!(D_storage, R)

D_prep(ℓₘₐₓ, [T=Float64])

Construct storage space and pre-compute recursion coefficients to compute Wigner's $\mathfrak{D}$ matrix in place.

This returns the D_storage arguments needed by D_matrices!.

D_iterator(D, ℓₘₐₓ, [ℓₘᵢₙ])

Construct an Iterator that returns sub-matrices of D, each of which consists of elements $(ℓ,-ℓ,-ℓ)$ through $(ℓ,ℓ,ℓ)$, for $ℓ$ from ℓₘᵢₙ through ℓₘₐₓ. By default, ℓₘᵢₙ is 0.

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

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

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

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

d_matrices(β, ℓₘₐₓ)
d_matrices(expiβ, ℓₘₐₓ)

Compute Wigner's $d^{(\ell)}$ matrices with elements $d^{(\ell)}_{m',m}(\beta)$ for all $\ell \leq \ell_\mathrm{max}$. The $d$ matrices are sometimes called the "reduced" Wigner matrices, in contrast to the full $\mathfrak{D}$ matrices.

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

This function only appropriate when you need to evaluate the matrices for a single value of β or expiβ because it allocates large arrays and performs many calculations that could be reused. If you need to evaluate the matrices for many values of β or expiβ, you should pre-allocate the storage with d_prep, and then call d_matrices! with the result instead.

d_matrices!(d_storage, β)
d_matrices!(d_storage, expiβ)
d_matrices!(d, β, ℓₘₐₓ)
d_matrices!(d, expiβ, ℓₘₐₓ)

Compute Wigner's $d^{(\ell)}$ matrices with elements $d^{(\ell)}_{m',m}(\beta)$ for all $\ell \leq \ell_\mathrm{max}$. The $d$ matrices are sometimes called the "reduced" Wigner matrices, in contrast to the full $\mathfrak{D}$ matrices.

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

[
    dˡₘₚ,ₘ(β)
    for ℓ ∈ 0:ℓₘₐₓ
    for mp ∈ -ℓ:ℓ
    for m ∈ -ℓ:ℓ
]

When the first argument is d, it will be modified, so it must be at least as large as that array. When the first argument is d_storage, it should be the quantity returned by d_prep, and the result will be written into the d 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.

See also d_matrices for a simpler function call when you only need to evaluate the matrices for a single value of β or expiβ.

Examples

using SphericalFunctions
ℓₘₐₓ = 8
T = Float64
β = T(1)/8
d_storage = d_prep(ℓₘₐₓ, T)
d = d_matrices!(d_storage, β)

d_prep(ℓₘₐₓ, [T=Float64])

Construct space and pre-compute recursion coefficients to compute Wigner's $d$ matrix in place.

This returns the d_storage arguments needed by d_matrices!.

d_iterator(d, ℓₘₐₓ, [ℓₘᵢₙ])

Construct an Iterator that returns sub-matrices of d, each of which consists of elements $(ℓ,-ℓ,-ℓ)$ through $(ℓ,ℓ,ℓ)$, for $ℓ$ from ℓₘᵢₙ through ℓₘₐₓ. By default, ℓₘᵢₙ is 0.

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

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

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

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