# kerrgeodesic_gw
A [SageMath](https://www.sagemath.org/) package to compute gravitational radiation from material orbiting a Kerr black hole
This package makes use of SageMath functionalities developed through the [SageManifolds](https://sagemanifolds.obspm.fr/) project and is part of the [Black Hole Perturbation Toolkit](https://bhptoolkit.org/).
## Installation
### Requirements
This package requires the Python-based free mathematics software system [SageMath](https://www.sagemath.org/) (at least version 9.3).
For versions of SageMath lower than 9.3, only version 0.3.2 of the package will work.
*NB:* the version of SageMath shipped with Ubuntu 20.04 is only 9.0; instead of
the Ubuntu package `sagemath`, install then the most recent binary for Ubuntu 20.04
from [SageMath download page](https://www.sagemath.org/download-linux.html).
### Simple installation from PyPI
It suffices to run
sage -pip install kerrgeodesic_gw
to have the package ready to use in SageMath.
See however *install from source* below if you want to build a
local version of the documentation or modify the source files (development).
*NB1 (Ubuntu users):* if you have installed SageMath as the system package `sagemath` (e.g. via `apt-get install`), the installation is system wide and does not allow to use `-pip install` at the user level. Install instead SageMath from the most recent binary tar ball for Ubuntu
from [SageMath download page](https://www.sagemath.org/download-linux.html).
*NB2:* on the [CoCalc](https://cocalc.com) cloud computing platform, you need
to add the option `--user`, i.e. open a terminal and run
sage -pip install --user kerrgeodesic_gw
Here is the [kerrgeodesic_gw page](https://pypi.org/project/kerrgeodesic-gw/) on PyPI (the Python Package Index).
### Install from source
Download the source from the git repository:
git clone https://github.com/BlackHolePerturbationToolkit/kerrgeodesic_gw.git
This creates a directory `kerrgeodesic_gw`.
Run
sage -pip install --upgrade --no-index -v kerrgeodesic_gw
to install the package in SageMath.
A shortcut of the above command is provided by the `Makefile` distributed with the package:
cd kerrgeodesic_gw
make install
*NB:* on [CoCalc](https://cocalc.com), you need to add the option `--user`, i.e. open a terminal and run
git clone https://github.com/BlackHolePerturbationToolkit/kerrgeodesic_gw.git
sage -pip install --user --upgrade --no-index -v kerrgeodesic_gw
#### Install for development
If you plan to edit the package source, you should add the option `-e` to the pip install, i.e. run
sage -pip install --upgrade --no-index -v -e kerrgeodesic_gw
or equivalently
cd kerrgeodesic_gw
make develop
## Usage
Once the package is installed, you can use it in SageMath, like for instance:
sage: from kerrgeodesic_gw import spin_weighted_spherical_harmonic
sage: theta, phi = var('theta phi')
sage: spin_weighted_spherical_harmonic(-2, 2, 1, theta, phi)
1/4*(sqrt(5)*cos(theta) + sqrt(5))*e^(I*phi)*sin(theta)/sqrt(pi)
## Usage in a virtual Python environment (no SageMath installation required)
Download the source from the git repository:
git clone https://github.com/BlackHolePerturbationToolkit/kerrgeodesic_gw.git
This creates a directory `kerrgeodesic_gw`.
Create and activate a virtual environment:
python3 -m venv venv_kerrgeodesic_gw
. venv_kerrgeodesic_gw/bin/activate
Install the package in the virtual environment:
pip install -e .[passagemath]
This automatically installs the modularized parts of the Sage library that are
needed by the package.
Start Python:
python3
Import and use the package:
>>> from sage.all__sagemath_symbolics import *
>>> from sage.all__sagemath_plot import *
>>> from kerrgeodesic_gw import spin_weighted_spherical_harmonic
>>> theta, phi = var('theta phi')
>>> spin_weighted_spherical_harmonic(-2, 2, 1, theta, phi)
1/4*(sqrt(5)*cos(theta) + sqrt(5))*e^(I*phi)*sin(theta)/sqrt(pi)
## Tests
This package is configured for tests written in the documentation strings of the source files, also known as *doctests*.
You may then test the install by running, from the root of the package tree
(i.e. the directory kerrgeodesic_gw created by the `git clone`),
sage -t kerrgeodesic_gw
You should then get the message `All tests passed!`
Alternatively, you can run (from the same directory)
make test
## Documentation
The package documentation can be generated using SageMath's [Sphinx](https://www.sphinx-doc.org/) installation:
cd docs
sage -sh -c "make html"
A shorthand of the above is
make doc
The html reference manual is then at
kerrgeodesic_gw/docs/build/html/index.html
For the LaTeX documentation, use
make doc-pdf
The pdf reference manual is then
kerrgeodesic_gw/docs/build/latex/kerrgeodesic_gw.pdf
### Online documentation
- [Reference manual](https://sagemanifolds.obspm.fr/kerrgeodesic_gw/reference/)
([PDF](https://sagemanifolds.obspm.fr/kerrgeodesic_gw/kerrgeodesic_gw.pdf))
- [Article describing the formulas implemented in the package](https://doi.org/10.1051/0004-6361/201935406) *(open access)*
- Demo notebooks:
- [Spin-weighted spheroidal harmonics](https://nbviewer.jupyter.org/github/BlackHolePerturbationToolkit/kerrgeodesic_gw/blob/master/Notebooks/basic_kerrgeodesic_gw.ipynb) [](https://mybinder.org/v2/gh/BlackHolePerturbationToolkit/kerrgeodesic_gw/master?filepath=Notebooks/basic_kerrgeodesic_gw.ipynb)
- [Timelike and null geodesics in Kerr spacetime](https://nbviewer.jupyter.org/github/BlackHolePerturbationToolkit/kerrgeodesic_gw/blob/master/Notebooks/Kerr_geodesics.ipynb) [](https://mybinder.org/v2/gh/BlackHolePerturbationToolkit/kerrgeodesic_gw/master?filepath=Notebooks/Kerr_geodesics.ipynb)
- [Gravitational waves from circular orbits around a Kerr black hole](https://nbviewer.jupyter.org/github/BlackHolePerturbationToolkit/kerrgeodesic_gw/blob/master/Notebooks/grav_waves_circular.ipynb) [](https://mybinder.org/v2/gh/BlackHolePerturbationToolkit/kerrgeodesic_gw/master?filepath=Notebooks/grav_waves_circular.ipynb)
- [More on gravitational waves from circular orbits](https://nbviewer.jupyter.org/github/BlackHolePerturbationToolkit/kerrgeodesic_gw/blob/master/Notebooks/gw_single_particle.ipynb) [](https://mybinder.org/v2/gh/BlackHolePerturbationToolkit/kerrgeodesic_gw/master?filepath=Notebooks/gw_single_particle.ipynb)
- For the tensor calculus functionalities of the
[KerrBH](https://sagemanifolds.obspm.fr/kerrgeodesic_gw/reference/kerr_spacetime.html)
class provided by the package, see these examples:
[Kerr 1](https://nbviewer.jupyter.org/github/sagemanifolds/SageManifolds/blob/master/Notebooks/SM_Kerr.ipynb),
[Kerr 2](https://nbviewer.jupyter.org/github/sagemanifolds/SageManifolds/blob/master/Notebooks/SM_Kerr_Killing_tensor.ipynb),
[Kerr 3](https://nbviewer.jupyter.org/github/sagemanifolds/SageManifolds/blob/master/Worksheets/v1.3/SM_Simon-Mars_Kerr.ipynb),
and more generally [SageManifolds documentation](https://sagemanifolds.obspm.fr/documentation.html).
## Authors
- Eric Gourgoulhon
- Alexandre Le Tiec
- Frederic Vincent
- Niels Warburton
**Reference:** E. Gourgoulhon, A. Le Tiec, F. H. Vincent & N. Warburton: *Gravitational waves from bodies orbiting the Galactic center black hole and their detectability by LISA*, [A&A **627**, A92 (2019)](https://doi.org/10.1051/0004-6361/201935406) (preprint: [arXiv:1903.02049](https://arxiv.org/abs/1903.02049))
Raw data
{
"_id": null,
"home_page": "https://github.com/BlackHolePerturbationToolkit/kerrgeodesic_gw",
"name": "kerrgeodesic-gw",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "SageMath",
"author": "Eric Gourgoulhon, Alexandre Le Tiec, Frederic Vincent, Niels Warburton",
"author_email": "eric.gourgoulhon@obspm.fr",
"download_url": "https://files.pythonhosted.org/packages/c2/61/edc5c8b260769b85e660128aca5ea7feb09f458b9c993cbf88978125bdc1/kerrgeodesic_gw-0.5.tar.gz",
"platform": null,
"description": "# kerrgeodesic_gw\n\nA [SageMath](https://www.sagemath.org/) package to compute gravitational radiation from material orbiting a Kerr black hole\n\nThis package makes use of SageMath functionalities developed through the [SageManifolds](https://sagemanifolds.obspm.fr/) project and is part of the [Black Hole Perturbation Toolkit](https://bhptoolkit.org/).\n\n## Installation\n\n### Requirements\n\nThis package requires the Python-based free mathematics software system [SageMath](https://www.sagemath.org/) (at least version 9.3).\nFor versions of SageMath lower than 9.3, only version 0.3.2 of the package will work.\n\n*NB:* the version of SageMath shipped with Ubuntu 20.04 is only 9.0; instead of\nthe Ubuntu package `sagemath`, install then the most recent binary for Ubuntu 20.04\nfrom [SageMath download page](https://www.sagemath.org/download-linux.html).\n\n### Simple installation from PyPI\n\nIt suffices to run\n\n sage -pip install kerrgeodesic_gw\n\nto have the package ready to use in SageMath.\nSee however *install from source* below if you want to build a\nlocal version of the documentation or modify the source files (development).\n\n*NB1 (Ubuntu users):* if you have installed SageMath as the system package `sagemath` (e.g. via `apt-get install`), the installation is system wide and does not allow to use `-pip install` at the user level. Install instead SageMath from the most recent binary tar ball for Ubuntu\nfrom [SageMath download page](https://www.sagemath.org/download-linux.html).\n\n*NB2:* on the [CoCalc](https://cocalc.com) cloud computing platform, you need\nto add the option `--user`, i.e. open a terminal and run\n\n sage -pip install --user kerrgeodesic_gw\n\n\nHere is the [kerrgeodesic_gw page](https://pypi.org/project/kerrgeodesic-gw/) on PyPI (the Python Package Index).\n\n### Install from source\n\nDownload the source from the git repository:\n\n git clone https://github.com/BlackHolePerturbationToolkit/kerrgeodesic_gw.git\n\nThis creates a directory `kerrgeodesic_gw`.\n\nRun\n\n sage -pip install --upgrade --no-index -v kerrgeodesic_gw\n\nto install the package in SageMath.\nA shortcut of the above command is provided by the `Makefile` distributed with the package:\n\n cd kerrgeodesic_gw\n make install\n\n*NB:* on [CoCalc](https://cocalc.com), you need to add the option `--user`, i.e. open a terminal and run\n\n git clone https://github.com/BlackHolePerturbationToolkit/kerrgeodesic_gw.git\n sage -pip install --user --upgrade --no-index -v kerrgeodesic_gw\n\n#### Install for development\n\nIf you plan to edit the package source, you should add the option `-e` to the pip install, i.e. run\n\n sage -pip install --upgrade --no-index -v -e kerrgeodesic_gw\n\nor equivalently\n\n cd kerrgeodesic_gw\n make develop\n\n## Usage\n\nOnce the package is installed, you can use it in SageMath, like for instance:\n\n sage: from kerrgeodesic_gw import spin_weighted_spherical_harmonic\n sage: theta, phi = var('theta phi')\n sage: spin_weighted_spherical_harmonic(-2, 2, 1, theta, phi)\n 1/4*(sqrt(5)*cos(theta) + sqrt(5))*e^(I*phi)*sin(theta)/sqrt(pi)\n\n\n## Usage in a virtual Python environment (no SageMath installation required)\n\nDownload the source from the git repository:\n\n git clone https://github.com/BlackHolePerturbationToolkit/kerrgeodesic_gw.git\n\nThis creates a directory `kerrgeodesic_gw`.\n\nCreate and activate a virtual environment:\n\n python3 -m venv venv_kerrgeodesic_gw\n . venv_kerrgeodesic_gw/bin/activate\n\nInstall the package in the virtual environment:\n\n pip install -e .[passagemath]\n\nThis automatically installs the modularized parts of the Sage library that are\nneeded by the package.\n\nStart Python:\n\n python3\n\nImport and use the package:\n\n >>> from sage.all__sagemath_symbolics import *\n >>> from sage.all__sagemath_plot import *\n >>> from kerrgeodesic_gw import spin_weighted_spherical_harmonic\n >>> theta, phi = var('theta phi')\n >>> spin_weighted_spherical_harmonic(-2, 2, 1, theta, phi)\n 1/4*(sqrt(5)*cos(theta) + sqrt(5))*e^(I*phi)*sin(theta)/sqrt(pi)\n\n\n## Tests\n\nThis package is configured for tests written in the documentation strings of the source files, also known as *doctests*.\nYou may then test the install by running, from the root of the package tree\n(i.e. the directory kerrgeodesic_gw created by the `git clone`),\n\n sage -t kerrgeodesic_gw\n\nYou should then get the message `All tests passed!`\n\nAlternatively, you can run (from the same directory)\n\n make test\n\n\n## Documentation\n\nThe package documentation can be generated using SageMath's [Sphinx](https://www.sphinx-doc.org/) installation:\n\n cd docs\n sage -sh -c \"make html\"\n\nA shorthand of the above is\n\n make doc\n\nThe html reference manual is then at\n\n kerrgeodesic_gw/docs/build/html/index.html\n\nFor the LaTeX documentation, use\n\n make doc-pdf\n\nThe pdf reference manual is then\n\n kerrgeodesic_gw/docs/build/latex/kerrgeodesic_gw.pdf\n\n### Online documentation\n\n- [Reference manual](https://sagemanifolds.obspm.fr/kerrgeodesic_gw/reference/)\n ([PDF](https://sagemanifolds.obspm.fr/kerrgeodesic_gw/kerrgeodesic_gw.pdf))\n- [Article describing the formulas implemented in the package](https://doi.org/10.1051/0004-6361/201935406) *(open access)*\n- Demo notebooks:\n\n - [Spin-weighted spheroidal harmonics](https://nbviewer.jupyter.org/github/BlackHolePerturbationToolkit/kerrgeodesic_gw/blob/master/Notebooks/basic_kerrgeodesic_gw.ipynb) [](https://mybinder.org/v2/gh/BlackHolePerturbationToolkit/kerrgeodesic_gw/master?filepath=Notebooks/basic_kerrgeodesic_gw.ipynb)\n - [Timelike and null geodesics in Kerr spacetime](https://nbviewer.jupyter.org/github/BlackHolePerturbationToolkit/kerrgeodesic_gw/blob/master/Notebooks/Kerr_geodesics.ipynb) [](https://mybinder.org/v2/gh/BlackHolePerturbationToolkit/kerrgeodesic_gw/master?filepath=Notebooks/Kerr_geodesics.ipynb)\n - [Gravitational waves from circular orbits around a Kerr black hole](https://nbviewer.jupyter.org/github/BlackHolePerturbationToolkit/kerrgeodesic_gw/blob/master/Notebooks/grav_waves_circular.ipynb) [](https://mybinder.org/v2/gh/BlackHolePerturbationToolkit/kerrgeodesic_gw/master?filepath=Notebooks/grav_waves_circular.ipynb)\n - [More on gravitational waves from circular orbits](https://nbviewer.jupyter.org/github/BlackHolePerturbationToolkit/kerrgeodesic_gw/blob/master/Notebooks/gw_single_particle.ipynb) [](https://mybinder.org/v2/gh/BlackHolePerturbationToolkit/kerrgeodesic_gw/master?filepath=Notebooks/gw_single_particle.ipynb)\n\n- For the tensor calculus functionalities of the\n [KerrBH](https://sagemanifolds.obspm.fr/kerrgeodesic_gw/reference/kerr_spacetime.html)\n class provided by the package, see these examples:\n [Kerr 1](https://nbviewer.jupyter.org/github/sagemanifolds/SageManifolds/blob/master/Notebooks/SM_Kerr.ipynb),\n [Kerr 2](https://nbviewer.jupyter.org/github/sagemanifolds/SageManifolds/blob/master/Notebooks/SM_Kerr_Killing_tensor.ipynb),\n [Kerr 3](https://nbviewer.jupyter.org/github/sagemanifolds/SageManifolds/blob/master/Worksheets/v1.3/SM_Simon-Mars_Kerr.ipynb),\n and more generally [SageManifolds documentation](https://sagemanifolds.obspm.fr/documentation.html).\n\n\n## Authors\n\n- Eric Gourgoulhon\n- Alexandre Le Tiec\n- Frederic Vincent\n- Niels Warburton\n\n**Reference:** E. Gourgoulhon, A. Le Tiec, F. H. Vincent & N. Warburton: *Gravitational waves from bodies orbiting the Galactic center black hole and their detectability by LISA*, [A&A **627**, A92 (2019)](https://doi.org/10.1051/0004-6361/201935406) (preprint: [arXiv:1903.02049](https://arxiv.org/abs/1903.02049))\n",
"bugtrack_url": null,
"license": "GPLv2+",
"summary": "Gravitational radiation from material orbiting a Kerr black hole",
"version": "0.5",
"project_urls": {
"Homepage": "https://github.com/BlackHolePerturbationToolkit/kerrgeodesic_gw"
},
"split_keywords": [
"sagemath"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d201ee04b51bd132b4711b49640a9abf441de7fca7008bb82d4b267eb4ff522a",
"md5": "375d2cedd937f89e502a12f6c5475702",
"sha256": "12c36bb42a4244b17677236a00b23a33e93b2f89c43af5592d9291afa942b0b1"
},
"downloads": -1,
"filename": "kerrgeodesic_gw-0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "375d2cedd937f89e502a12f6c5475702",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 746707,
"upload_time": "2024-11-19T17:48:05",
"upload_time_iso_8601": "2024-11-19T17:48:05.244022Z",
"url": "https://files.pythonhosted.org/packages/d2/01/ee04b51bd132b4711b49640a9abf441de7fca7008bb82d4b267eb4ff522a/kerrgeodesic_gw-0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c261edc5c8b260769b85e660128aca5ea7feb09f458b9c993cbf88978125bdc1",
"md5": "8a9a541df9e1f6f321ca742dfbbdcef3",
"sha256": "8307675229afbf61b7cdae3dc380a3620d6213b367e90f0f7e99d817c5f17b68"
},
"downloads": -1,
"filename": "kerrgeodesic_gw-0.5.tar.gz",
"has_sig": false,
"md5_digest": "8a9a541df9e1f6f321ca742dfbbdcef3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 730552,
"upload_time": "2024-11-19T17:48:14",
"upload_time_iso_8601": "2024-11-19T17:48:14.447358Z",
"url": "https://files.pythonhosted.org/packages/c2/61/edc5c8b260769b85e660128aca5ea7feb09f458b9c993cbf88978125bdc1/kerrgeodesic_gw-0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-19 17:48:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "BlackHolePerturbationToolkit",
"github_project": "kerrgeodesic_gw",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"tox": true,
"lcname": "kerrgeodesic-gw"
}
JSON
