Package: qnm
Welcome to qnmqnmis an open-source Python package for computing the Kerr
quasinormal mode frequencies, angular separation constants, and
spherical-spheroidal mixing coefficients. Theqnmpackage includes a
Leaver solver with theCook-Zalutskiy spectral
approachto 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-weightedspheroidalharmonics into spin-weighted spherical
harmonics.  Therefore you get the spherical-spheroidal decomposition
coefficients for free when solving for ω and A (see below for
details).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.InstallationPyPIqnmis available onPyPI:pipinstallqnmCondaqnmis available onconda-forge:condainstall-cconda-forgeqnmFrom sourcegitclonehttps://github.com/duetosymmetry/qnm.gitcdqnm
pythonsetup.pyinstallIf you do not have root permissions, replace the last step withpython setup.py install --user.  Instead of usingsetup.pymanually, you can also replace the last step withpip install .orpip install --user ..DependenciesAll of these can be installed through pip or conda.numpyscipynumbatqdm(just forqnm.download_data()progress)pathlib2(backport ofpathlibto pre-3.4 python)DocumentationAutomatically-generated API documentation is available onRead the Docs: qnm.UsageThe highest-level interface is viaqnm.cached.KerrSeqCache, which
loads cachedspin sequencesfrom 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:importqnmqnm.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 filesThen, useqnm.modes_cacheto load aqnm.spinsequence.KerrSpinSeqof interest. If the mode is not
available, it will try to compute it (see detailed documentation for
how to control that calculation).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 sequenceseqwithseq(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).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 filenotebooks/examples.ipynbin the source repo):importnumpyasnpimportmatplotlibasmplimportmatplotlib.pyplotasplts,l,m=(-2,2,2)mode_list=[(s,l,m,n)forninnp.arange(0,7)]modes={ind:qnm.modes_cache(*ind)forindinmode_list}plt.subplot(1,2,1)formode,seqinmodes.items():plt.plot(np.real(seq.omega),np.imag(seq.omega))plt.subplot(1,2,2)formode,seqinmodes.items():plt.plot(np.real(seq.A),np.imag(seq.A))Which results in the following figure (modulo formatting):s,l,n=(-2,2,0)mode_list=[(s,l,m,n)forminnp.arange(-l,l+1)]modes={ind:qnm.modes_cache(*ind)forindinmode_list}plt.subplot(1,2,1)formode,seqinmodes.items():plt.plot(np.real(seq.omega),np.imag(seq.omega))plt.subplot(1,2,2)formode,seqinmodes.items():plt.plot(np.real(seq.A),np.imag(seq.A))Which results in the following figure (modulo formatting):Precision and validationThe 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(which were computed with
arbitrary-precision arithmetic) can be used for validating the results
of this code.  See the comparison notebooknotebooks/Comparison-against-Cook-data.ipynbto see such a comparison, which can be modified to compare any of the
available modes.Spherical-spheroidal decompositionThe angular dependence of QNMs are naturally spin-weightedspheroidalharmonics.  The spheroidals are not actually a complete orthogonal
basis set.  Meanwhile spin-weightedsphericalharmonics 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
callingqnm.angular.ells, e.g.ells = qnm.angular.ells(s=-2, m=2, l_max=grav_220.l_max)ContributingContributions are welcome! There are at least two ways to contribute to this codebase:If you find a bug or want to suggest an enhancement, use theissue trackeron 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.If you will write or edit the python code, we use thefork and pull requestmodel.You are also allowed to make use of this code for other purposes, as detailed in theMIT license. For any type of contribution, please follow thecode of conduct.How to citeIf this package contributes to a project that leads to a publication,
please acknowledge this by citing theqnmarticle in JOSS.  The
following BibTeX entry is available in theqnm.__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;%%"
}CreditsThe code is developed and maintained byLeo C. Stein.