Evaluate and transform D matrices, 3-j symbols, and (scalar or spin-weighted) spherical harmonics
Project description
Spherical Functions
Python/numba package for evaluating and transforming Wigner's 𝔇 matrices, Wigner's 3-j symbols, and spin-weighted (and scalar) spherical harmonics. These functions are evaluated directly in terms of quaternions, as well as in the more standard forms of spherical coordinates and Euler angles.1
These quantities are computed using recursion relations, which makes it possible to compute to very high ℓ values. Unlike direct evaluation of individual elements, which will generally cause overflow or underflow beyond ℓ≈30, these recursion relations should be accurate for ℓ values beyond 1000.
The conventions for this package are described in detail on this page.
Installation
Because this package is pure python code, installation is very simple. In particular, with a reasonably modern installation, you can just run a command like
conda install -c conda-forge spherical
or
python -m pip install spherical
Either of these will download and install the package.
Usage
Functions of angles or rotations
Currently, due to the nature of recursions, this module does not allow calculation of individual elements, but returns ranges of results. For example, when computing Wigner's 𝔇 matrix, all matrices up to a given ℓ will be returned; when evaluating a spin-weighted spherical harmonic, all harmonics up to a given ℓ will be returned. Fortunately, this is usually what is required in any case.
To calculate Wigner's d or 𝔇 matrix or spin-weighted spherical harmonics, first
construct a Wigner
object.
import quaternionic
import spherical
ell_max = 16 # Use the largest ℓ value you expect to need
wigner = spherical.Wigner(ell_max)
This module takes input as quaternions. The quaternionic
module has various
ways of constructing
quaternions,
including direct construction or conversion from rotation matrices, axis-angle
representation, Euler angles,1 or
spherical coordinates, among others:
R = quaternionic.array([1, 2, 3, 4]).normalized
R = quaternionic.array.from_axis_angle(vec)
R = quaternionic.array.from_euler_angles(alpha, beta, gamma)
R = quaternionic.array.from_spherical_coordinates(theta, phi)
Mode weights can be rotated as
wigner.rotate(modes, R)
or evaluated as
wigner.evaluate(modes, R)
We can compute the 𝔇 matrix as
D = wigner.D(R)
which can be indexed as
D[wigner.Dindex(ell, mp, m)]
or we can compute the spin-weighted spherical harmonics as
Y = wigner.sYlm(s, R)
which can be indexed as
Y[wigner.Yindex(ell, m)]
Note that, if relevant, it is probably more efficient to use the rotate
and
evaluate
methods than to use D
or Y
.
Clebsch-Gordan and 3-j symbols
It is possible to compute individual values of the 3-j or Clebsch-Gordan symbols:
w3j = spherical.Wigner3j(j_1, j_2, j_3, m_1, m_2, m_3)
cg = spherical.clebsch_gordan(j_1, m_1, j_2, m_2, j_3, m_3)
However, when more than one element is needed (as is typically the case), it is much more efficient to compute a range of values:
calc3j = spherical.Wigner3jCalculator(j2_max, j3_max)
w3j = calc3j.calculate(j2, j3, m2, m3)
Acknowledgments
I very much appreciate Barry Wardell's help in sorting out the relationships between my conventions and those of other people and software packages (especially Mathematica's crazy conventions).
This code is, of course, hosted on github. Because it is an open-source project, the hosting is free, and all the wonderful features of github are available, including free wiki space and web page hosting, pull requests, a nice interface to the git logs, etc.
The work of creating this code was supported in part by the Sherman Fairchild Foundation and by NSF Grants No. PHY-1306125 and AST-1333129.
1 Euler angles are awful
Euler angles are pretty much the worst things ever and it makes me feel bad even supporting them. Quaternions are faster, more accurate, basically free of singularities, more intuitive, and generally easier to understand. You can work entirely without Euler angles (I certainly do). You absolutely never need them. But if you're so old fashioned that you really can't give them up, they are fully supported.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file spherical-1.0.14.tar.gz
.
File metadata
- Download URL: spherical-1.0.14.tar.gz
- Upload date:
- Size: 82.6 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: python-httpx/0.25.2
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | a9de448a02c84734cd8829ebeca5fe0ade1f6bd249fb081e2cfc1f528499ff2f |
|
MD5 | e4636e22f5d99dfc7cae21c661131aed |
|
BLAKE2b-256 | 8418b9d5d0318b45500817918999c16e0729f878e991f1c54d6cb5424866ed17 |
File details
Details for the file spherical-1.0.14-py3-none-any.whl
.
File metadata
- Download URL: spherical-1.0.14-py3-none-any.whl
- Upload date:
- Size: 55.6 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: python-httpx/0.25.2
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 31c008e574d56c6c6ca0e4e415a9b203334616a938633d046c680359de43e409 |
|
MD5 | 14621cd9465cd8b50df2bf59f839c57e |
|
BLAKE2b-256 | ff799426f1b2555104553e5344c4846f81c3db24d5a96af6b17cf9cdfbe556ea |