Package: kerrgeodesic-gw
kerrgeodesic_gwASageMathpackage to compute gravitational radiation from material orbiting a Kerr black holeThis package makes use of SageMath functionalities developed through theSageManifoldsproject and is part of theBlack Hole Perturbation Toolkit.InstallationRequirementsThis package requires the Python-based free mathematics software systemSageMath(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 packagesagemath, install then the most recent binary for Ubuntu 20.04
fromSageMath download page.Simple installation from PyPIIt suffices to runsage -pip install kerrgeodesic_gwto have the package ready to use in SageMath.
See howeverinstall from sourcebelow 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 packagesagemath(e.g. viaapt-get install), the installation is system wide and does not allow to use-pip installat the user level. Install instead SageMath from the most recent binary tar ball for Ubuntu
fromSageMath download page.NB2:on theCoCalccloud computing platform, you need
to add the option--user, i.e. open a terminal and runsage -pip install --user kerrgeodesic_gwHere is thekerrgeodesic_gw pageon PyPI (the Python Package Index).Install from sourceDownload the source from the git repository:git clone https://github.com/BlackHolePerturbationToolkit/kerrgeodesic_gw.gitThis creates a directorykerrgeodesic_gw.Runsage -pip install --upgrade --no-index -v kerrgeodesic_gwto install the package in SageMath.
A shortcut of the above command is provided by theMakefiledistributed with the package:cd kerrgeodesic_gw
make installNB:onCoCalc, you need to add the option--user, i.e. open a terminal and rungit clone https://github.com/BlackHolePerturbationToolkit/kerrgeodesic_gw.git
sage -pip install --user --upgrade --no-index -v kerrgeodesic_gwInstall for developmentIf you plan to edit the package source, you should add the option-eto the pip install, i.e. runsage -pip install --upgrade --no-index -v -e kerrgeodesic_gwor equivalentlycd kerrgeodesic_gw
make developUsageOnce 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)TestsThis package is configured for tests written in the documentation strings of the source files, also known asdoctests.
You may then test the install by running, from the root of the package tree
(i.e. the directory kerrgeodesic_gw created by thegit clone),sage -t kerrgeodesic_gwYou should then get the messageAll tests passed!Alternatively, you can run (from the same directory)make testDocumentationThe package documentation can be generated using SageMath'sSphinxinstallation:cd docs
sage -sh -c "make html"A shorthand of the above ismake docThe html reference manual is then atkerrgeodesic_gw/docs/build/html/index.htmlFor the LaTeX documentation, usemake doc-pdfThe pdf reference manual is thenkerrgeodesic_gw/docs/build/latex/kerrgeodesic_gw.pdfOnline documentationReference manual(PDF)Article describing the formulas implemented in the package(open access)Demo notebooks:Spin-weighted spheroidal harmonicsTimelike and null geodesics in Kerr spacetimeGravitational waves from circular orbits around a Kerr black holeMore on gravitational waves from circular orbitsFor the tensor calculus functionalities of theKerrBHclass provided by the package, see these examples:Kerr 1,Kerr 2,Kerr 3,
and more generallySageManifolds documentation.AuthorsEric GourgoulhonAlexandre Le TiecFrederic VincentNiels WarburtonReference: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&A627, A92 (2019)(preprint:arXiv:1903.02049)