README.md

Spherical Functions in Julia

Julia package for evaluating and transforming Wigner's 𝔇 matrices, and spin-weighted spherical harmonics (which includes the ordinary scalar spherical harmonics). Because both 𝔇 and the harmonics are most correctly considered functions on the rotation group $𝐒𝐎(3)$ — or more precisely, the spin group $𝐒𝐩𝐢𝐧(3)$ that covers it — these functions are evaluated directly in terms of quaternions. Concessions are also made for more standard forms of spherical coordinates and Euler angles.¹ Among other applications, those functions permit "synthesis" (evaluation of the spin-weighted spherical functions) of spin-weighted spherical harmonic coefficients on regular or distorted grids. This package also includes functions enabling efficient "analysis" (decomposition into mode coefficients) of functions evaluated on regular grids to high order and accuracy.

These quantities are computed using recursion relations, which makes it possible to compute to fairly high ℓ values. Unlike direct evaluation of individual elements, which will generally cause overflow or underflow beyond ℓ≈30 when using double precision, these recursion relations should be valid for far higher ℓ values. More precisely, when using this package, Inf values appear starting at ℓ=22 for Float16, ℓ=183 for Float32, and ℓ=1474 for Float64. BigFloat also works, and presumably will not overflow for any ℓ value that could reasonably fit into computer memory — though it is far slower. Also note that DoubleFloats will work, and achieve significantly greater accuracy but no greater ℓ range than Float64. The results are accurate to roughly ℓ times the precision of the input quaternion.

The conventions for this package inherited from — and are described in detail on — its predecessors found here and here.

Note that the goals of this package do not include some important use cases, including some that are common in fields such as CMB astronomy or lensing. Numerous other packages may be better suited to those use cases, including FastTransforms.jl, FastSphericalHarmonics.jl, WignerSymbols.jl, and WignerFamilies.jl. However, I need support only for relatively moderate values of ℓ, for quaternions (via Quaternionic.jl) and for higher-precision numbers — even at the cost of a very slight decrease in speed in some cases — which are what this package provides.

Installation

using Pkg
Pkg.add("SphericalFunctions")

References

The most important routine in this package is the computation of the 𝔇 matrices — or more specifically, of terms proportional to parts of the 𝔇 matrices. This mostly follows the treatment of Gumerov and Duraiswami (2014). To seed the recursions they present, we also need to calculate the associated Legendre functions. Currently, this is done using the "modified forward row method" of Holmes and Featherstone (2002). Note that this is apparently the source of overflow noted above. Two other (though more complicated) methods have appeared more recently in the literature, which could presumably extend these limits much further. Fukushima (2012) showed that using "X-numbers" (wherein the exponent is stored as a separate integer) in the core of the recursion could increase the range to ℓ≈2³². Xing et al. (2020) showed that Fukushima's results exhibited increased error for certain angles, whereas their Eqs. (12)—(14) could be used directly to obtain results with greater accuracy for those certain angles, and comparable accuracy for other angles.

It may be worthwhile simply passing X-numbers to these algorithms if higher orders are needed. (Though using BigFloat may achieve a similar objective, it would probably be far slower.) The actual recommendation of Fukushima is more sophisticated — just using X-numbers in the core calculation — but it looks like the simpler approach wouldn't be too much slower.

The other major functionality of this package is map2salm, which decomposes function values on regular grids into mode weights (coefficients). The approach used here is taken from Reinecke and Seljebotn, with weights based on Waldvogel's method.

---

¹ Euler angles are inadequate

Euler angles are quite generally a very poor choice for computing with rotations. (The only context in which they may be preferred is when analytically integrating some analytically known functions.) Almost universally, it is best to use quaternions when computing with rotations. All the computations done within this package use quaternions; the user interfaces involving Euler angles essentially convert to/from quaternions. While the calculations needed for those conversions would still need to be done if this package used Euler angles internally — meaning that this approach is as efficient as any — that work can be avoided entirely if you work with quaternions directly.