[](https://github.com/duetosymmetry/qnm)
[](https://badge.fury.io/py/qnm)
[](https://anaconda.org/conda-forge/qnm)
[](https://zenodo.org/record/2593978)
[](https://joss.theoj.org/papers/85532a74baaa67a24518de1365f1bcf5)
[](https://arxiv.org/abs/1908.10377)
[](http://ascl.net/1910.022)
[](https://github.com/duetosymmetry/qnm/blob/master/LICENSE)
[](https://travis-ci.org/duetosymmetry/qnm)
[](https://qnm.readthedocs.io/en/latest/?badge=latest)
# Welcome to qnm
`qnm` is an open-source Python package for computing the Kerr
quasinormal mode frequencies, angular separation constants, and
spherical-spheroidal mixing coefficients. The `qnm` package includes a
Leaver solver with the [Cook-Zalutskiy spectral
approach](https://arxiv.org/abs/1410.7698) to the angular sector, and
a caching mechanism to avoid repeating calculations.
With this python package, you can compute the QNMs labeled by
different (s,l,m,n), at a desired dimensionless spin parameter 0≤a<1.
The angular sector is treated as a spectral decomposition of
spin-weighted *spheroidal* harmonics into spin-weighted spherical
harmonics. Therefore you get the spherical-spheroidal decomposition
coefficients for free when solving for ω and A ([see below for
details](#spherical-spheroidal-decomposition)).
We have precomputed a large cache of low-lying modes (s=-2 and s=-1,
all l<8, all n<7). These can be automatically installed with a single
function call, and interpolated for good initial guesses for
root-finding at some value of a.
## Installation
### PyPI
_**qnm**_ is available on [PyPI](https://pypi.org/project/qnm/):
```shell
pip install qnm
```
### Conda
_**qnm**_ is available on [conda-forge](https://anaconda.org/conda-forge/qnm):
```shell
conda install -c conda-forge qnm
```
### From source
```shell
git clone https://github.com/duetosymmetry/qnm.git
cd qnm
python setup.py install
```
If you do not have root permissions, replace the last step with
`python setup.py install --user`. Instead of using `setup.py`
manually, you can also replace the last step with `pip install .` or
`pip install --user .`.
## Dependencies
All of these can be installed through pip or conda.
* [numpy](https://docs.scipy.org/doc/numpy/user/install.html)
* [scipy](https://www.scipy.org/install.html)
* [numba](http://numba.pydata.org/numba-doc/latest/user/installing.html)
* [tqdm](https://tqdm.github.io) (just for `qnm.download_data()` progress)
* [pathlib2](https://pypi.org/project/pathlib2/) (backport of
`pathlib` to pre-3.4 python)
## Documentation
Automatically-generated API documentation is available on [Read the Docs: qnm](https://qnm.readthedocs.io/).
## Usage
The highest-level interface is via `qnm.cached.KerrSeqCache`, which
loads cached *spin sequences* from disk. A spin sequence is just a mode
labeled by (s,l,m,n), with the spin a ranging from a=0 to some
maximum, e.g. 0.9995. A large number of low-lying spin sequences have
been precomputed and are available online. The first time you use the
package, download the precomputed sequences:
```python
import qnm
qnm.download_data() # Only need to do this once
# Trying to fetch https://duetosymmetry.com/files/qnm/data.tar.bz2
# Trying to decompress file /<something>/qnm/data.tar.bz2
# Data directory /<something>/qnm/data contains 860 pickle files
```
Then, use `qnm.modes_cache` to load a
`qnm.spinsequence.KerrSpinSeq` of interest. If the mode is not
available, it will try to compute it (see detailed documentation for
how to control that calculation).
```python
grav_220 = qnm.modes_cache(s=-2,l=2,m=2,n=0)
omega, A, C = grav_220(a=0.68)
print(omega)
# (0.5239751042900845-0.08151262363119974j)
```
Calling a spin sequence `seq` with `seq(a)` will return the complex
quasinormal mode frequency omega, the complex angular separation
constant A, and a vector C of coefficients for decomposing the
associated spin-weighted spheroidal harmonics as a sum of
spin-weighted spherical harmonics ([see below for
details](#spherical-spheroidal-decomposition)).
Visual inspections of modes are very useful to check if the solver is
behaving well. This is easily accomplished with matplotlib. Here are
some partial examples (for the full examples, see the file
[`notebooks/examples.ipynb`](notebooks/examples.ipynb) in the source repo):
```python
import numpy as np
import matplotlib as mpl
import matplotlib.pyplot as plt
s, l, m = (-2, 2, 2)
mode_list = [(s, l, m, n) for n in np.arange(0,7)]
modes = { ind : qnm.modes_cache(*ind) for ind in mode_list }
plt.subplot(1, 2, 1)
for mode, seq in modes.items():
plt.plot(np.real(seq.omega),np.imag(seq.omega))
plt.subplot(1, 2, 2)
for mode, seq in modes.items():
plt.plot(np.real(seq.A),np.imag(seq.A))
```
Which results in the following figure (modulo formatting):
```python
s, l, n = (-2, 2, 0)
mode_list = [(s, l, m, n) for m in np.arange(-l,l+1)]
modes = { ind : qnm.modes_cache(*ind) for ind in mode_list }
plt.subplot(1, 2, 1)
for mode, seq in modes.items():
plt.plot(np.real(seq.omega),np.imag(seq.omega))
plt.subplot(1, 2, 2)
for mode, seq in modes.items():
plt.plot(np.real(seq.A),np.imag(seq.A))
```
Which results in the following figure (modulo formatting):
## Precision and validation
The default tolerances for continued fractions, `cf_tol`, is 1e-10, and
for complex root-polishing, `tol`, is DBL_EPSILON≅1.5e-8. These can
be changed at runtime so you can re-polish the cached values to higher
precision.
[Greg Cook's precomputed data
tables](https://zenodo.org/record/2650358) (which were computed with
arbitrary-precision arithmetic) can be used for validating the results
of this code. See the comparison notebook
[`notebooks/Comparison-against-Cook-data.ipynb`](notebooks/Comparison-against-Cook-data.ipynb)
to see such a comparison, which can be modified to compare any of the
available modes.
## Spherical-spheroidal decomposition
The angular dependence of QNMs are naturally spin-weighted *spheroidal*
harmonics. The spheroidals are not actually a complete orthogonal
basis set. Meanwhile spin-weighted *spherical* harmonics are complete
and orthonormal, and are used much more commonly. Therefore you
typically want to express a spheroidal (on the left hand side) in
terms of sphericals (on the right hand side),
Here ℓmin=max(|m|,|s|) and ℓmax can be chosen at run time. The C
coefficients are returned as a complex ndarray, with the zeroth
element corresponding to ℓmin.
To avoid indexing errors, you can get the ndarray of ℓ values by
calling `qnm.angular.ells`, e.g.
```
ells = qnm.angular.ells(s=-2, m=2, l_max=grav_220.l_max)
```
## Contributing
Contributions are welcome! There are at least two ways to contribute to this codebase:
1. If you find a bug or want to suggest an enhancement, use the [issue tracker](https://github.com/duetosymmetry/qnm/issues) on GitHub. It's a good idea to look through past issues, too, to see if anybody has run into the same problem or made the same suggestion before.
2. If you will write or edit the python code, we use the [fork and pull request](https://help.github.com/articles/creating-a-pull-request-from-a-fork/) model.
You are also allowed to make use of this code for other purposes, as detailed in the [MIT license](LICENSE). For any type of contribution, please follow the [code of conduct](CODE_OF_CONDUCT.md).
## How to cite
If this package contributes to a project that leads to a publication,
please acknowledge this by citing the `qnm` article in JOSS. The
following BibTeX entry is available in the `qnm.__bibtex__` string:
```
@article{Stein:2019mop,
author = "Stein, Leo C.",
title = "{qnm: A Python package for calculating Kerr quasinormal
modes, separation constants, and spherical-spheroidal
mixing coefficients}",
journal = "J. Open Source Softw.",
volume = "4",
year = "2019",
number = "42",
pages = "1683",
doi = "10.21105/joss.01683",
eprint = "1908.10377",
archivePrefix = "arXiv",
primaryClass = "gr-qc",
SLACcitation = "%%CITATION = ARXIV:1908.10377;%%"
}
```
## Credits
The code is developed and maintained by [Leo C. Stein](https://duetosymmetry.com).
Raw data
{
"_id": null,
"home_page": "https://github.com/duetosymmetry/qnm/",
"name": "qnm",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "black holes quasinormal modes physics scientific computing numerical methods",
"author": "Leo C. Stein",
"author_email": "leo.stein@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/71/53/6a1e24671d0f2af6a70054c74f364cbf33e88a7db1e3f82e490a103be87b/qnm-0.4.3.tar.gz",
"platform": "",
"description": "[](https://github.com/duetosymmetry/qnm)\n[](https://badge.fury.io/py/qnm)\n[](https://anaconda.org/conda-forge/qnm)\n[](https://zenodo.org/record/2593978)\n[](https://joss.theoj.org/papers/85532a74baaa67a24518de1365f1bcf5)\n[](https://arxiv.org/abs/1908.10377)\n[](http://ascl.net/1910.022)\n[](https://github.com/duetosymmetry/qnm/blob/master/LICENSE)\n[](https://travis-ci.org/duetosymmetry/qnm)\n[](https://qnm.readthedocs.io/en/latest/?badge=latest)\n\n\n# Welcome to qnm\n`qnm` is an open-source Python package for computing the Kerr\nquasinormal mode frequencies, angular separation constants, and\nspherical-spheroidal mixing coefficients. The `qnm` package includes a\nLeaver solver with the [Cook-Zalutskiy spectral\napproach](https://arxiv.org/abs/1410.7698) to the angular sector, and\na caching mechanism to avoid repeating calculations.\n\nWith this python package, you can compute the QNMs labeled by\ndifferent (s,l,m,n), at a desired dimensionless spin parameter 0\u2264a<1.\nThe angular sector is treated as a spectral decomposition of\nspin-weighted *spheroidal* harmonics into spin-weighted spherical\nharmonics. Therefore you get the spherical-spheroidal decomposition\ncoefficients for free when solving for \u03c9 and A ([see below for\ndetails](#spherical-spheroidal-decomposition)).\n\nWe have precomputed a large cache of low-lying modes (s=-2 and s=-1,\nall l<8, all n<7). These can be automatically installed with a single\nfunction call, and interpolated for good initial guesses for\nroot-finding at some value of a.\n\n## Installation\n\n### PyPI\n_**qnm**_ is available on [PyPI](https://pypi.org/project/qnm/):\n\n```shell\npip install qnm\n```\n\n### Conda\n_**qnm**_ is available on [conda-forge](https://anaconda.org/conda-forge/qnm):\n\n```shell\nconda install -c conda-forge qnm\n```\n\n### From source\n\n```shell\ngit clone https://github.com/duetosymmetry/qnm.git\ncd qnm\npython setup.py install\n```\n\nIf you do not have root permissions, replace the last step with\n`python setup.py install --user`. Instead of using `setup.py`\nmanually, you can also replace the last step with `pip install .` or\n`pip install --user .`.\n\n## Dependencies\nAll of these can be installed through pip or conda.\n* [numpy](https://docs.scipy.org/doc/numpy/user/install.html)\n* [scipy](https://www.scipy.org/install.html)\n* [numba](http://numba.pydata.org/numba-doc/latest/user/installing.html)\n* [tqdm](https://tqdm.github.io) (just for `qnm.download_data()` progress)\n* [pathlib2](https://pypi.org/project/pathlib2/) (backport of\n `pathlib` to pre-3.4 python)\n\n## Documentation\n\nAutomatically-generated API documentation is available on [Read the Docs: qnm](https://qnm.readthedocs.io/).\n\n\n## Usage\n\nThe highest-level interface is via `qnm.cached.KerrSeqCache`, which\nloads cached *spin sequences* from disk. A spin sequence is just a mode\nlabeled by (s,l,m,n), with the spin a ranging from a=0 to some\nmaximum, e.g. 0.9995. A large number of low-lying spin sequences have\nbeen precomputed and are available online. The first time you use the\npackage, download the precomputed sequences:\n\n```python\nimport qnm\n\nqnm.download_data() # Only need to do this once\n# Trying to fetch https://duetosymmetry.com/files/qnm/data.tar.bz2\n# Trying to decompress file /<something>/qnm/data.tar.bz2\n# Data directory /<something>/qnm/data contains 860 pickle files\n```\n\nThen, use `qnm.modes_cache` to load a\n`qnm.spinsequence.KerrSpinSeq` of interest. If the mode is not\navailable, it will try to compute it (see detailed documentation for\nhow to control that calculation).\n\n```python\ngrav_220 = qnm.modes_cache(s=-2,l=2,m=2,n=0)\nomega, A, C = grav_220(a=0.68)\nprint(omega)\n# (0.5239751042900845-0.08151262363119974j)\n```\n\nCalling a spin sequence `seq` with `seq(a)` will return the complex\nquasinormal mode frequency omega, the complex angular separation\nconstant A, and a vector C of coefficients for decomposing the\nassociated spin-weighted spheroidal harmonics as a sum of\nspin-weighted spherical harmonics ([see below for\ndetails](#spherical-spheroidal-decomposition)).\n\nVisual inspections of modes are very useful to check if the solver is\nbehaving well. This is easily accomplished with matplotlib. Here are\nsome partial examples (for the full examples, see the file\n[`notebooks/examples.ipynb`](notebooks/examples.ipynb) in the source repo):\n\n```python\nimport numpy as np\nimport matplotlib as mpl\nimport matplotlib.pyplot as plt\n\ns, l, m = (-2, 2, 2)\nmode_list = [(s, l, m, n) for n in np.arange(0,7)]\nmodes = { ind : qnm.modes_cache(*ind) for ind in mode_list }\n\nplt.subplot(1, 2, 1)\nfor mode, seq in modes.items():\n plt.plot(np.real(seq.omega),np.imag(seq.omega))\n\nplt.subplot(1, 2, 2)\nfor mode, seq in modes.items():\n plt.plot(np.real(seq.A),np.imag(seq.A))\n```\n\nWhich results in the following figure (modulo formatting):\n\n\n\n```python\ns, l, n = (-2, 2, 0)\nmode_list = [(s, l, m, n) for m in np.arange(-l,l+1)]\nmodes = { ind : qnm.modes_cache(*ind) for ind in mode_list }\n\nplt.subplot(1, 2, 1)\nfor mode, seq in modes.items():\n plt.plot(np.real(seq.omega),np.imag(seq.omega))\n\nplt.subplot(1, 2, 2)\nfor mode, seq in modes.items():\n plt.plot(np.real(seq.A),np.imag(seq.A))\n```\n\nWhich results in the following figure (modulo formatting):\n\n\n\n## Precision and validation\n\nThe default tolerances for continued fractions, `cf_tol`, is 1e-10, and\nfor complex root-polishing, `tol`, is DBL_EPSILON\u22451.5e-8. These can\nbe changed at runtime so you can re-polish the cached values to higher\nprecision.\n\n[Greg Cook's precomputed data\ntables](https://zenodo.org/record/2650358) (which were computed with\narbitrary-precision arithmetic) can be used for validating the results\nof this code. See the comparison notebook\n[`notebooks/Comparison-against-Cook-data.ipynb`](notebooks/Comparison-against-Cook-data.ipynb)\nto see such a comparison, which can be modified to compare any of the\navailable modes.\n\n## Spherical-spheroidal decomposition\n\nThe angular dependence of QNMs are naturally spin-weighted *spheroidal*\nharmonics. The spheroidals are not actually a complete orthogonal\nbasis set. Meanwhile spin-weighted *spherical* harmonics are complete\nand orthonormal, and are used much more commonly. Therefore you\ntypically want to express a spheroidal (on the left hand side) in\nterms of sphericals (on the right hand side),\n\n\n\nHere \u2113min=max(|m|,|s|) and \u2113max can be chosen at run time. The C\ncoefficients are returned as a complex ndarray, with the zeroth\nelement corresponding to \u2113min.\nTo avoid indexing errors, you can get the ndarray of \u2113 values by\ncalling `qnm.angular.ells`, e.g.\n\n```\nells = qnm.angular.ells(s=-2, m=2, l_max=grav_220.l_max)\n```\n\n## Contributing\nContributions are welcome! There are at least two ways to contribute to this codebase:\n\n1. If you find a bug or want to suggest an enhancement, use the [issue tracker](https://github.com/duetosymmetry/qnm/issues) on GitHub. It's a good idea to look through past issues, too, to see if anybody has run into the same problem or made the same suggestion before.\n2. If you will write or edit the python code, we use the [fork and pull request](https://help.github.com/articles/creating-a-pull-request-from-a-fork/) model.\n\nYou are also allowed to make use of this code for other purposes, as detailed in the [MIT license](LICENSE). For any type of contribution, please follow the [code of conduct](CODE_OF_CONDUCT.md).\n\n## How to cite\nIf this package contributes to a project that leads to a publication,\nplease acknowledge this by citing the `qnm` article in JOSS. The\nfollowing BibTeX entry is available in the `qnm.__bibtex__` string:\n```\n@article{Stein:2019mop,\n author = \"Stein, Leo C.\",\n title = \"{qnm: A Python package for calculating Kerr quasinormal\n modes, separation constants, and spherical-spheroidal\n mixing coefficients}\",\n journal = \"J. Open Source Softw.\",\n volume = \"4\",\n year = \"2019\",\n number = \"42\",\n pages = \"1683\",\n doi = \"10.21105/joss.01683\",\n eprint = \"1908.10377\",\n archivePrefix = \"arXiv\",\n primaryClass = \"gr-qc\",\n SLACcitation = \"%%CITATION = ARXIV:1908.10377;%%\"\n}\n```\n\n## Credits\nThe code is developed and maintained by [Leo C. Stein](https://duetosymmetry.com).\n\n\n",
"bugtrack_url": null,
"license": "",
"summary": "Package for computing Kerr quasinormal mode frequencies, separation constants, and spherical-spheroidal mixing coefficients",
"version": "0.4.3",
"project_urls": {
"Bug Tracker": "https://github.com/duetosymmetry/qnm/issues",
"Documentation": "https://qnm.readthedocs.io/",
"Homepage": "https://github.com/duetosymmetry/qnm/",
"Source Code": "https://github.com/duetosymmetry/qnm"
},
"split_keywords": [
"black",
"holes",
"quasinormal",
"modes",
"physics",
"scientific",
"computing",
"numerical",
"methods"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6b5d03b89b152275440853078a701b1ac7e4fddf9a9a267b24f48caff786e709",
"md5": "868f9c989779c9d32785aa9c3594f0d8",
"sha256": "9f7f83b773b1a7f15d78e5d7dc428fbdf1c6a6fd8d5554b5cdb04f217c73ab3d"
},
"downloads": -1,
"filename": "qnm-0.4.3-py2-none-any.whl",
"has_sig": false,
"md5_digest": "868f9c989779c9d32785aa9c3594f0d8",
"packagetype": "bdist_wheel",
"python_version": "py2",
"requires_python": null,
"size": 95051,
"upload_time": "2019-12-22T22:37:16",
"upload_time_iso_8601": "2019-12-22T22:37:16.721860Z",
"url": "https://files.pythonhosted.org/packages/6b/5d/03b89b152275440853078a701b1ac7e4fddf9a9a267b24f48caff786e709/qnm-0.4.3-py2-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "71536a1e24671d0f2af6a70054c74f364cbf33e88a7db1e3f82e490a103be87b",
"md5": "16faa2ea9ed2185773d4739a5bffc990",
"sha256": "6fd017c2acb25b1ba3a4c00fe8a70a5f0fe90e0cf7d407e45842e5b33f8cf47b"
},
"downloads": -1,
"filename": "qnm-0.4.3.tar.gz",
"has_sig": false,
"md5_digest": "16faa2ea9ed2185773d4739a5bffc990",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 94329,
"upload_time": "2019-12-22T22:37:18",
"upload_time_iso_8601": "2019-12-22T22:37:18.755433Z",
"url": "https://files.pythonhosted.org/packages/71/53/6a1e24671d0f2af6a70054c74f364cbf33e88a7db1e3f82e490a103be87b/qnm-0.4.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2019-12-22 22:37:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "duetosymmetry",
"github_project": "qnm",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "numpy",
"specs": []
},
{
"name": "scipy",
"specs": []
},
{
"name": "numba",
"specs": []
},
{
"name": "tqdm",
"specs": []
},
{
"name": "pathlib2",
"specs": []
}
],
"lcname": "qnm"
}
JSON
