| Name | spherical JSON |
| Version |
1.0.13
JSON |
| download |
| home_page | https://github.com/moble/spherical |
| Summary | Evaluate and transform D matrices, 3-j symbols, and (scalar or spin-weighted) spherical harmonics |
| upload_time | 2023-02-10 04:32:46 |
| maintainer | |
| docs_url | None |
| author | Michael Boyle |
| requires_python | >=3.8,<3.12 |
| license | MIT |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
[](https://github.com/moble/spherical/actions)
[](https://codecov.io/gh/moble/spherical)
[](https://spherical.readthedocs.io/en/main/?badge=main)
[](https://pypi.org/project/spherical/)
[](https://anaconda.org/conda-forge/spherical)
[](https://zenodo.org/badge/latestdoi/295054260)
# 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.<sup>[1](#1-euler-angles-are-awful)</sup>
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](http://moble.github.io/spherical/).
## 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](https://quaternionic.readthedocs.io/en/latest/#rotations),
including direct construction or conversion from rotation matrices, axis-angle
representation, Euler angles,<sup>[1](#euler-angles-are-awful)</sup> 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.
<br/>
---
###### <sup>1</sup> Euler angles are awful
Euler angles are pretty much
[the worst things ever](http://moble.github.io/spherical/#euler-angles)
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.
Raw data
{
"_id": null,
"home_page": "https://github.com/moble/spherical",
"name": "spherical",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<3.12",
"maintainer_email": "",
"keywords": "",
"author": "Michael Boyle",
"author_email": "michael.oliver.boyle@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/2d/da/c0bd63715117754988034500813651a2d9c6bd04a2bc0887a45bd10960e5/spherical-1.0.13.tar.gz",
"platform": null,
"description": "[](https://github.com/moble/spherical/actions)\n[](https://codecov.io/gh/moble/spherical)\n[](https://spherical.readthedocs.io/en/main/?badge=main)\n[](https://pypi.org/project/spherical/)\n[](https://anaconda.org/conda-forge/spherical)\n[](https://zenodo.org/badge/latestdoi/295054260)\n\n\n# Spherical Functions\n\nPython/numba package for evaluating and transforming Wigner's \ud835\udd07 matrices,\nWigner's 3-j symbols, and spin-weighted (and scalar) spherical harmonics.\nThese functions are evaluated directly in terms of quaternions, as well as in\nthe more standard forms of spherical coordinates and Euler\nangles.<sup>[1](#1-euler-angles-are-awful)</sup>\n\nThese quantities are computed using recursion relations, which makes it\npossible to compute to very high \u2113 values. Unlike direct evaluation of\nindividual elements, which will generally cause overflow or underflow beyond\n\u2113\u224830, these recursion relations should be accurate for \u2113 values beyond 1000.\n\nThe conventions for this package are described in detail on\n[this page](http://moble.github.io/spherical/).\n\n## Installation\n\nBecause this package is pure python code, installation is very simple. In\nparticular, with a reasonably modern installation, you can just run a command\nlike\n\n```bash\nconda install -c conda-forge spherical\n```\n\nor\n\n```bash\npython -m pip install spherical\n```\n\nEither of these will download and install the package.\n\n\n## Usage\n\n#### Functions of angles or rotations\n\nCurrently, due to the nature of recursions, this module does not allow\ncalculation of individual elements, but returns ranges of results. For\nexample, when computing Wigner's \ud835\udd07 matrix, all matrices up to a given \u2113 will be\nreturned; when evaluating a spin-weighted spherical harmonic, all harmonics up\nto a given \u2113 will be returned. Fortunately, this is usually what is required\nin any case.\n\nTo calculate Wigner's d or \ud835\udd07 matrix or spin-weighted spherical harmonics, first\nconstruct a `Wigner` object.\n\n```python\nimport quaternionic\nimport spherical\nell_max = 16 # Use the largest \u2113 value you expect to need\nwigner = spherical.Wigner(ell_max)\n```\n\nThis module takes input as quaternions. The `quaternionic` module has [various\nways of constructing\nquaternions](https://quaternionic.readthedocs.io/en/latest/#rotations),\nincluding direct construction or conversion from rotation matrices, axis-angle\nrepresentation, Euler angles,<sup>[1](#euler-angles-are-awful)</sup> or\nspherical coordinates, among others:\n\n```python\nR = quaternionic.array([1, 2, 3, 4]).normalized\nR = quaternionic.array.from_axis_angle(vec)\nR = quaternionic.array.from_euler_angles(alpha, beta, gamma)\nR = quaternionic.array.from_spherical_coordinates(theta, phi)\n```\n\nMode weights can be rotated as\n\n```python\nwigner.rotate(modes, R)\n```\n\nor evaluated as\n\n```python\nwigner.evaluate(modes, R)\n```\n\nWe can compute the \ud835\udd07 matrix as\n\n```python\nD = wigner.D(R)\n```\n\nwhich can be indexed as\n\n```python\nD[wigner.Dindex(ell, mp, m)]\n```\n\nor we can compute the spin-weighted spherical harmonics as\n\n```python\nY = wigner.sYlm(s, R)\n```\n\nwhich can be indexed as\n\n```python\nY[wigner.Yindex(ell, m)]\n```\n\nNote that, if relevant, it is probably more efficient to use the `rotate` and\n`evaluate` methods than to use `D` or `Y`.\n\n\n\n#### Clebsch-Gordan and 3-j symbols\n\nIt is possible to compute individual values of the 3-j or Clebsch-Gordan\nsymbols:\n\n```python\nw3j = spherical.Wigner3j(j_1, j_2, j_3, m_1, m_2, m_3)\ncg = spherical.clebsch_gordan(j_1, m_1, j_2, m_2, j_3, m_3)\n```\n\nHowever, when more than one element is needed (as is typically the case), it is\nmuch more efficient to compute a range of values:\n\n```python\ncalc3j = spherical.Wigner3jCalculator(j2_max, j3_max)\nw3j = calc3j.calculate(j2, j3, m2, m3)\n```\n\n\n## Acknowledgments\n\nI very much appreciate Barry Wardell's help in sorting out the relationships\nbetween my conventions and those of other people and software packages\n(especially Mathematica's crazy conventions).\n\nThis code is, of course, hosted on github. Because it is an open-source\nproject, the hosting is free, and all the wonderful features of github are\navailable, including free wiki space and web page hosting, pull requests, a\nnice interface to the git logs, etc.\n\nThe work of creating this code was supported in part by the Sherman Fairchild\nFoundation and by NSF Grants No. PHY-1306125 and AST-1333129.\n\n\n<br/>\n\n---\n\n###### <sup>1</sup> Euler angles are awful\n\nEuler angles are pretty much\n[the worst things ever](http://moble.github.io/spherical/#euler-angles)\nand it makes me feel bad even supporting them. Quaternions are\nfaster, more accurate, basically free of singularities, more\nintuitive, and generally easier to understand. You can work entirely\nwithout Euler angles (I certainly do). You absolutely never need\nthem. But if you're so old fashioned that you really can't give them\nup, they are fully supported.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Evaluate and transform D matrices, 3-j symbols, and (scalar or spin-weighted) spherical harmonics",
"version": "1.0.13",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "adf0839d8d9229b55e6e370ba9f13ed623525aac022c3376ed2f849909a51757",
"md5": "d5310acd7a69822d70503ad234e960f7",
"sha256": "a495b8ed7f10925f72e196fad49a1adf5f191a2756532f191c8505d465eb1880"
},
"downloads": -1,
"filename": "spherical-1.0.13-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d5310acd7a69822d70503ad234e960f7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<3.12",
"size": 54760,
"upload_time": "2023-02-10T04:32:43",
"upload_time_iso_8601": "2023-02-10T04:32:43.929332Z",
"url": "https://files.pythonhosted.org/packages/ad/f0/839d8d9229b55e6e370ba9f13ed623525aac022c3376ed2f849909a51757/spherical-1.0.13-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2ddac0bd63715117754988034500813651a2d9c6bd04a2bc0887a45bd10960e5",
"md5": "d0c28afe2468d89cfce8d0dd3bde2132",
"sha256": "a4363a3531c47b5f1ff8dd5498e8cbe34e5075036e0160a15c1289ce568e0c8c"
},
"downloads": -1,
"filename": "spherical-1.0.13.tar.gz",
"has_sig": false,
"md5_digest": "d0c28afe2468d89cfce8d0dd3bde2132",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<3.12",
"size": 63516,
"upload_time": "2023-02-10T04:32:46",
"upload_time_iso_8601": "2023-02-10T04:32:46.120512Z",
"url": "https://files.pythonhosted.org/packages/2d/da/c0bd63715117754988034500813651a2d9c6bd04a2bc0887a45bd10960e5/spherical-1.0.13.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-02-10 04:32:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "moble",
"github_project": "spherical",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "spherical"
}
