[](https://github.com/moble/spherical_functions/actions)
[](https://pypi.org/project/spherical-functions/)
[](https://anaconda.org/conda-forge/spherical_functions)
[](https://github.com/moble/spherical_functions/blob/main/LICENSE)
[](https://zenodo.org/badge/latestdoi/25589782)
# Spherical Functions
| NOTE: This package will still be maintained, but *active* development has moved to the [`spherical`](https://github.com/moble/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 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>
The conventions for this package are described in detail on
[this page](http://moble.github.io/spherical_functions/).
## Dependencies
The only true requirements for this code are `python` and the python package
`numpy`, as well as my accompanying
[`quaternion`](https://github.com/moble/quaternion) package (installation of
which is shown below).
However, this package can automatically use
[`numba`](http://numba.pydata.org/), which uses [LLVM](http://llvm.org/) 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`](http://continuum.io/downloads), makes it trivial. Just install
the main `anaconda` package.
If you prefer the smaller download size of
[`miniconda`](http://conda.pydata.org/miniconda.html) (which comes with no
extras beyond python), you may also have to run this command:
```sh
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
```sh
conda install -c conda-forge spherical_functions
```
This should automatically download and install the package
[`quaternion`](https://github.com/moble/quaternion), on which this package
depends.
Alternatively, if you prefer to use `pip` (whether or not you use `conda`), you
can also do
```sh
python -m pip install spherical-functions
```
Finally, there's also the fully manual option of just downloading both code
repositories, changing to the code directory, and issuing
```sh
python -m pip install .
```
This should work regardless of the installation method, as long as you have a
compiler hanging around. However, this may be more likely to try to compile
the dependencies, including numpy and/or spinsfast, which can be much more
complicated.
## Usage
First, we show a very simple example of usage with Euler angles, though it
breaks my heart to do so:<sup>[1](#euler-angles-are-awful)</sup>
```python
>>> 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:
```python
>>> 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 𝔇<sup>(ℓ)</sup> 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):
```python
>>> 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:
```python
>>> 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](http://moble.github.io/spherical_functions/) (though the user need
not care about that). The `indices` variable is assumed to be a
two-dimensional array of integers, where the second dimension has size three,
representing the (ℓ, m', m) indices. This avoids certain somewhat slower
pure-python operations involving argument checking, reshaping, etc. The
`elements` variable must be a one-dimensional 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 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.
Finally, the code is automatically compiled, and the binaries hosted for
download by `conda` on [anaconda.org](https://anaconda.org/moble/spherical_functions).
This is also a free service for open-source projects like this one.
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_functions/#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_functions",
"name": "spherical-functions",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Michael Boyle",
"author_email": "mob22@cornell.edu",
"download_url": "https://files.pythonhosted.org/packages/cb/78/9ea3252a3c6d0e8df0af57d100d5caddf4b232d686dd1fba77c86668e152/spherical_functions-2022.4.5.tar.gz",
"platform": null,
"description": "[](https://github.com/moble/spherical_functions/actions)\n[](https://pypi.org/project/spherical-functions/)\n[](https://anaconda.org/conda-forge/spherical_functions)\n[](https://github.com/moble/spherical_functions/blob/main/LICENSE)\n[](https://zenodo.org/badge/latestdoi/25589782)\n\n\n# Spherical Functions\n\n| NOTE: This package will still be maintained, but *active* development has moved to the [`spherical`](https://github.com/moble/spherical) package. While this package works well for \u2113 (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 \u2113 times machine precision. \u2014Mike |\n| --- |\n\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\nThe conventions for this package are described in detail on\n[this page](http://moble.github.io/spherical_functions/).\n\n## Dependencies\n\nThe only true requirements for this code are `python` and the python package\n`numpy`, as well as my accompanying\n[`quaternion`](https://github.com/moble/quaternion) package (installation of\nwhich is shown below).\n\nHowever, this package can automatically use\n[`numba`](http://numba.pydata.org/), which uses [LLVM](http://llvm.org/) to\ncompile python code to machine code, accelerating most numerical functions by\nfactors of anywhere from 2 to 2000. It is *possible* to run the code without\n`numba`, but the most important functions are roughly 10 times slower without\nit.\n\nThe only drawback of `numba` is that it is nontrivial to install on its own.\nFortunately, the best python installer,\n[`anaconda`](http://continuum.io/downloads), makes it trivial. Just install\nthe main `anaconda` package.\n\nIf you prefer the smaller download size of\n[`miniconda`](http://conda.pydata.org/miniconda.html) (which comes with no\nextras beyond python), you may also have to run this command:\n\n```sh\nconda install pip numpy numba\n```\n\n\n## Installation\n\nAssuming you use `conda` to manage your python installation (like any sane\npython user), you can install this package simply as\n\n```sh\nconda install -c conda-forge spherical_functions\n```\n\nThis should automatically download and install the package\n[`quaternion`](https://github.com/moble/quaternion), on which this package\ndepends.\n\nAlternatively, if you prefer to use `pip` (whether or not you use `conda`), you\ncan also do\n\n```sh\npython -m pip install spherical-functions\n```\n\nFinally, there's also the fully manual option of just downloading both code\nrepositories, changing to the code directory, and issuing\n\n```sh\npython -m pip install .\n```\n\nThis should work regardless of the installation method, as long as you have a\ncompiler hanging around. However, this may be more likely to try to compile\nthe dependencies, including numpy and/or spinsfast, which can be much more\ncomplicated.\n\n\n## Usage\n\nFirst, we show a very simple example of usage with Euler angles, though it\nbreaks my heart to do so:<sup>[1](#euler-angles-are-awful)</sup>\n\n```python\n>>> import spherical_functions as sf\n>>> alpha, beta, gamma = 0.1, 0.2, 0.3\n>>> ell,mp,m = 3,2,1\n>>> sf.Wigner_D_element(alpha, beta, gamma, ell, mp, m)\n\n```\n\nOf course, it's always better to use unit quaternions to describe rotations:\n\n```python\n>>> import numpy as np\n>>> import quaternion\n>>> R = np.quaternion(1,2,3,4).normalized()\n>>> ell,mp,m = 3,2,1\n>>> sf.Wigner_D_element(R, ell, mp, m)\n\n```\n\nIf you need to calculate values of the \ud835\udd07<sup>(\u2113)</sup> matrix elements for many\nvalues of (\u2113, m', m), it is more efficient to do so all at once. The following\ncalculates all modes for \u2113 from 2 to 8 (inclusive):\n\n```python\n>>> indices = np.array([[ell,mp,m] for ell in range(2,9)\n... for mp in range(-ell, ell+1) for m in range(-ell, ell+1)])\n>>> sf.Wigner_D_element(R, indices)\n\n```\n\nFinally, if you really need to put the pedal to the metal, and are willing to\nguarantee that the input arguments are correct, you can use a special hidden\nform of the function:\n\n```python\n>>> sf._Wigner_D_element(R.a, R.b, indices, elements)\n\n```\n\nHere, `R.a` and `R.b` are the two complex parts of the quaternion defined on\n[this page](http://moble.github.io/spherical_functions/) (though the user need\nnot care about that). The `indices` variable is assumed to be a\ntwo-dimensional array of integers, where the second dimension has size three,\nrepresenting the (\u2113, m', m) indices. This avoids certain somewhat slower\npure-python operations involving argument checking, reshaping, etc. The\n`elements` variable must be a one-dimensional array of complex numbers (can be\nuninitialized), which will be replaced with the corresponding values on return.\nAgain, however, there is no input dimension checking here, so if you give bad\ninputs, behavior could range from silently wrong to exceptions to segmentation\nfaults. Caveat emptor.\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\nFinally, the code is automatically compiled, and the binaries hosted for\ndownload by `conda` on [anaconda.org](https://anaconda.org/moble/spherical_functions).\nThis is also a free service for open-source projects like this one.\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###### <sup>1</sup> Euler angles are awful\n\nEuler angles are pretty much\n[the worst things ever](http://moble.github.io/spherical_functions/#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": "Python/numba implementation of Wigner D Matrices, spin-weighted spherical harmonics, and associated functions",
"version": "2022.4.5",
"project_urls": {
"Homepage": "https://github.com/moble/spherical_functions"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "41266f436558b4491646181ede76e8518e97509fa16ea7c5f8224d3c170823e9",
"md5": "ba15b3c6eacc959adabc9aeff7d30747",
"sha256": "24fae7a7b02dc32bc9800747b85b7bcf94dbb6f859165ed76e253ed4154886b6"
},
"downloads": -1,
"filename": "spherical_functions-2022.4.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ba15b3c6eacc959adabc9aeff7d30747",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 381853,
"upload_time": "2024-04-29T21:23:55",
"upload_time_iso_8601": "2024-04-29T21:23:55.800937Z",
"url": "https://files.pythonhosted.org/packages/41/26/6f436558b4491646181ede76e8518e97509fa16ea7c5f8224d3c170823e9/spherical_functions-2022.4.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cb789ea3252a3c6d0e8df0af57d100d5caddf4b232d686dd1fba77c86668e152",
"md5": "6a3db7d3750e25611f71aefbf1e5e1a9",
"sha256": "a46d86ad450d3b9c29de5dab65432663894b745b1496b8d1cbd24e9b5cabb520"
},
"downloads": -1,
"filename": "spherical_functions-2022.4.5.tar.gz",
"has_sig": false,
"md5_digest": "6a3db7d3750e25611f71aefbf1e5e1a9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 373543,
"upload_time": "2024-04-29T21:23:57",
"upload_time_iso_8601": "2024-04-29T21:23:57.587924Z",
"url": "https://files.pythonhosted.org/packages/cb/78/9ea3252a3c6d0e8df0af57d100d5caddf4b232d686dd1fba77c86668e152/spherical_functions-2022.4.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-29 21:23:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "moble",
"github_project": "spherical_functions",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "spherical-functions"
}
JSON
