spherical
Evaluate and transform D matrices, 3-j symbols, and (scalar or spin-weighted) spherical harmonics
Science Score: 54.0%
This score indicates how likely this project is to be science-related based on various indicators:
-
✓CITATION.cff file
Found CITATION.cff file -
✓codemeta.json file
Found codemeta.json file -
✓.zenodo.json file
Found .zenodo.json file -
○DOI references
-
✓Academic publication links
Links to: zenodo.org -
○Committers with academic emails
-
○Institutional organization owner
-
○JOSS paper metadata
-
○Scientific vocabulary similarity
Low similarity (15.1%) to scientific vocabulary
Repository
Evaluate and transform D matrices, 3-j symbols, and (scalar or spin-weighted) spherical harmonics
Basic Info
- Host: GitHub
- Owner: moble
- License: mit
- Language: Python
- Default Branch: main
- Size: 754 KB
Statistics
- Stars: 54
- Watchers: 3
- Forks: 3
- Open Issues: 6
- Releases: 23
Metadata Files
README.md
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
bash
conda install -c conda-forge spherical
or
bash
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.
python
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:
python
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
python
wigner.rotate(modes, R)
or evaluated as
python
wigner.evaluate(modes, R)
We can compute the 𝔇 matrix as
python
D = wigner.D(R)
which can be indexed as
python
D[wigner.Dindex(ell, mp, m)]
or we can compute the spin-weighted spherical harmonics as
python
Y = wigner.sYlm(s, R)
which can be indexed as
python
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:
python
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:
python
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.
Owner
- Name: Mike Boyle
- Login: moble
- Kind: user
- Location: Ithaca, NY
- Company: Cornell University
- Website: black-holes.org
- Repositories: 76
- Profile: https://github.com/moble
Citation (CITATION.cff)
cff-version: 1.2.0
message: "If you use this software, please cite it as below."
authors:
- family-names: Boyle
given-names: Michael
orcid: https://orcid.org/0000-0002-5075-5116
title: "The spherical package"
license: MIT
doi: 10.5281/zenodo.4045222
version: 1.0.16
date-released: 2025-03-27
GitHub Events
Total
- Create event: 5
- Release event: 1
- Issues event: 1
- Watch event: 5
- Delete event: 1
- Issue comment event: 1
- Push event: 5
- Pull request event: 4
- Fork event: 1
Last Year
- Create event: 5
- Release event: 1
- Issues event: 1
- Watch event: 5
- Delete event: 1
- Issue comment event: 1
- Push event: 5
- Pull request event: 4
- Fork event: 1
Committers
Last synced: 10 months ago
Top Committers
| Name | Commits | |
|---|---|---|
| Michael Boyle | m****e@g****m | 68 |
| github-actions | g****s@g****m | 23 |
Committer Domains (Top 20 + Academic)
Issues and Pull Requests
Last synced: 7 months ago
All Time
- Total issues: 6
- Total pull requests: 17
- Average time to close issues: 10 days
- Average time to close pull requests: about 4 hours
- Total issue authors: 6
- Total pull request authors: 2
- Average comments per issue: 1.0
- Average comments per pull request: 0.47
- Merged pull requests: 14
- Bot issues: 0
- Bot pull requests: 3
Past Year
- Issues: 1
- Pull requests: 3
- Average time to close issues: N/A
- Average time to close pull requests: N/A
- Issue authors: 1
- Pull request authors: 1
- Average comments per issue: 1.0
- Average comments per pull request: 0.0
- Merged pull requests: 0
- Bot issues: 0
- Bot pull requests: 3
Top Authors
Issue Authors
- xmikel2907 (1)
- ryanlevy (1)
- Editst (1)
- duetosymmetry (1)
- nilsvu (1)
- brunocuevas (1)
Pull Request Authors
- moble (14)
- dependabot[bot] (4)
Top Labels
Issue Labels
Pull Request Labels
Packages
- Total packages: 3
-
Total downloads:
- pypi 5,922 last-month
-
Total dependent packages: 3
(may contain duplicates) -
Total dependent repositories: 5
(may contain duplicates) - Total versions: 40
- Total maintainers: 3
pypi.org: spherical
Evaluate and transform D matrices, 3-j symbols, and (scalar or spin-weighted) spherical harmonics
- Homepage: https://github.com/moble/spherical
- Documentation: https://spherical.readthedocs.io/
- License: The MIT License (MIT) Copyright (c) 2023 Mike Boyle Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
Latest release: 1.0.16
published 12 months ago
Rankings
Maintainers (1)
spack.io: py-spherical
Evaluate and transform D matrices, 3-j symbols, and (scalar or spin- weighted) spherical harmonics
- Homepage: https://github.com/moble/spherical
- License: []
-
Latest release: 1.0.10
published almost 4 years ago
Rankings
conda-forge.org: spherical
This package provides efficient, accurate, and numerically stable code to compute various spherical functions and related quantities. The code is written in pure python, but is automatically compiled with numba for greater efficiency.
- Homepage: https://github.com/moble/spherical
- License: MIT
-
Latest release: 1.0.11
published about 4 years ago
Rankings
Dependencies
- ipykernel ^5.3.4 develop
- ipython <7.17 develop
- line_profiler ^3.0.2 develop
- pytest ^7.0 develop
- pytest-cov >=2.10.1 develop
- scipy ^1.0 develop
- sympy ^1.6.2 develop
- black >=22.1
- mkdocs >=1.1.2
- mktheapidocs >=0.2
- numba >=0.55
- numpy ^1.19
- pymdown-extensions ^8
- python >=3.8,<3.11
- quaternionic ^1.0
- spinsfast >=104.2020.8
- actions/checkout v3 composite
- actions/create-release latest composite
- actions/setup-python v4 composite
- codecov/codecov-action v3 composite