Python/numba implementation of Wigner D Matrices, spinweighted spherical harmonics, and associated functions
Project description
Spherical Functions
NOTE: This package will still be maintained, but active development has moved to the spherical package. While this package works well for ℓ (aka ell, L, j, or J) values up to around 25, errors start to build rapidly and turn into NaNs around 30. The spherical package can readily handle values up to at least 1000, with accuracy close to ℓ times machine precision. —Mike 

Python/numba package for evaluating and transforming Wigner's 𝔇 matrices, Wigner's 3j symbols, and spinweighted (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}
The conventions for this package are described in detail on this page.
Dependencies
The only true requirements for this code are python
and the python package
numpy
, as well as my accompanying
quaternion
package (installation of
which is shown below).
However, this package can automatically use
numba
, which uses LLVM to
compile python code to machine code, accelerating most numerical functions by
factors of anywhere from 2 to 2000. It is possible to run the code without
numba
, but the most important functions are roughly 10 times slower without
it.
The only drawback of numba
is that it is nontrivial to install on its own.
Fortunately, the best python installer,
anaconda
, makes it trivial. Just install
the main anaconda
package.
If you prefer the smaller download size of
miniconda
(which comes with no
extras beyond python), you'll also have to run this command:
conda install pip numpy numba
Installation
Assuming you use conda
to manage your python installation (like any sane
python user), you can install this package simply as
conda install c condaforge spherical_functions
This should automatically download and install the package
quaternion
, on which this package
depends.
Alternatively, if you prefer to use pip
(whether or not you use conda
), you
can also do
pip install git+git://github.com/moble/quaternion pip install git+git://github.com/moble/spherical_functions
Or, if you refuse to use conda
, you might want to install inside your home
directory without root privileges. (Anaconda does this by default anyway.)
This is done by adding user
to the above commands:
pip install user git+git://github.com/moble/quaternion pip install user git+git://github.com/moble/spherical_functions
Finally, there's also the fully manual option of just downloading both code repositories, changing to the code directory, and issuing
python setup.py install
This should work regardless of the installation method, as long as you have a compiler hanging around.
Usage
First, we show a very simple example of usage with Euler angles, though it breaks my heart to do so:^{1}
>>> import spherical_functions as sf >>> alpha, beta, gamma = 0.1, 0.2, 0.3 >>> ell,mp,m = 3,2,1 >>> sf.Wigner_D_element(alpha, beta, gamma, ell, mp, m)
Of course, it's always better to use unit quaternions to describe rotations:
>>> import numpy as np >>> import quaternion >>> R = np.quaternion(1,2,3,4).normalized() >>> ell,mp,m = 3,2,1 >>> sf.Wigner_D_element(R, ell, mp, m)
If you need to calculate values of the 𝔇^{(ℓ)} matrix elements for many values of (ℓ, m', m), it is more efficient to do so all at once. The following calculates all modes for ℓ from 2 to 8 (inclusive):
>>> indices = np.array([[ell,mp,m] for ell in range(2,9) ... for mp in range(ell, ell+1) for m in range(ell, ell+1)]) >>> sf.Wigner_D_element(R, indices)
Finally, if you really need to put the pedal to the metal, and are willing to guarantee that the input arguments are correct, you can use a special hidden form of the function:
>>> sf._Wigner_D_element(R.a, R.b, indices, elements)
Here, R.a
and R.b
are the two complex parts of the quaternion defined on
this page (though the user need
not care about that). The indices
variable is assumed to be a
twodimensional array of integers, where the second dimension has size three,
representing the (ℓ, m', m) indices. This avoids certain somewhat slower
purepython operations involving argument checking, reshaping, etc. The
elements
variable must be a onedimensional array of complex numbers (can be
uninitialized), which will be replaced with the corresponding values on return.
Again, however, there is no input dimension checking here, so if you give bad
inputs, behavior could range from silently wrong to exceptions to segmentation
faults. Caveat emptor.
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 opensource 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.
Every change in this code is auomatically tested on TravisCI. This is a free service (for opensource projects like this one), which integrates beautifully with github, detecting each commit and automatically rerunning the tests. The code is downloaded and installed fresh each time, and then tested, on python 2.7, 3.4, and 3.5. This ensures that no change I make to the code breaks either installation or any of the features that I have written tests for.
Finally, the code is automatically compiled, and the binaries hosted for
download by conda
on anaconda.org.
This is also a free service for opensource projects like this one.
The work of creating this code was supported in part by the Sherman Fairchild Foundation and by NSF Grants No. PHY1306125 and AST1333129.
 ###### ^{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
Hashes for sphericalfunctions2022.4.1.tar.gz
Algorithm  Hash digest  

SHA256  0dda9641bac21c747c1e1419489b2d1a9eb7c7db3e46c3059b6a1f050478ab61 

MD5  6f87e85695c659031c28e6a7b4a48b71 

BLAKE2256  c821223be6514d5b962c0ce4f14f04162c4c07cb94cfb88f786733fc33001519 
Hashes for spherical_functions2022.4.1py3noneany.whl
Algorithm  Hash digest  

SHA256  5363f2647b990400b8f9ab426cab29ecfcd5834a03c65ca98487fb96b11eda02 

MD5  70e3893620eecbae9f6dfc98c55ecf85 

BLAKE2256  180966ecf0c606642a831246a23ebe69ebe200704dc75bf320651f70776b8fb4 