Welcome to pyRing’s documentation!

_images/pyRing_docs_image.svg

Introduction

pyRing is a python package for black hole (BH) ringdown analysis, model comparison and parameter estimation. The package is tailored to the analysis of the post-merger phase of Compact Binary Coalescence (CBC) Gravitational-wave (GW) signals using a native time-domain likelihood formulation. It is integrated with standard LIGO-Virgo-Kagra software and supports:

  • Ringdown analyses of interferometric or simulated GW data using a variety of ringdown waveform models. All of them are analytical templates, some of them are calibrated to Numerical Relativity (NR).

  • Parametrised tests of General Relativity (GR), by adding parametrised deviations to the spectrum frequencies and damping times.

  • Quasi-normal modes (QNM) spectrum predictions for emissions alternative to the Kerr solution.

The main usage features of the software have been internally reviewed for scientific usage from the LIGO-Virgo-Kagra (LVK) collaboration and the code is routinely used to produce catalogs of BH ringdown properties and tests of GR in the merger-ringdown regime by the LVK collaboration.

The software can be accessed on git.ligo.org.

Disclaimer: since the name pyring had already been taken on pypi (which is not case sensitive), the package has to be pip-installed or conda-installed with the name pyRingGW. However, for all internal purposes and functionalities, the name of the package is pyRing. For example, the help message can be accessed through pyRing --help.

Tutorials

Tutorial slides (both on the physics and inference methods behind the analysis) are available here. See also below for brief instructions on how to run tutorial examples.

Install and run

  • Installing from pip:

    $ pip install pyRingGW
    
  • Installing from conda:

    $ conda install -c conda-forge pyringgw
    
  • Installing the source code:

    In your ~/.bashrc add:

    $ export PYRING_PREFIX=/home/installation_directory/pyring
    

    where installation_directory is the directory where you will be placing the pyRing source code. This path is needed for advanced functionalities such as QNM interpolation or injection of NR data.

    $ git clone https://git.ligo.org/lscsoft/pyring.git
    $ cd pyring
    $ git lfs install
    $ git lfs pull
    $ pip install -r requirements.txt
    $ pip install .
    

    Add --user to the last command in case you don’t have administrator’s permissions (for example if you are installing on a cluster). Alternatives to the last command are python -m pip install . or python setup.py install

  • Running the code:

    The one-liner you are searching for is:

    $ pyRing --config-file config.ini
    
  • Examples:

    The config_files directory contains a variety of example files to analyse GW detections and injections (both ringdown templates and IMR injections). There is one example file for each waveform model supported, included all modifications to the Kerr hypothesis. The configuration files directory can either be found on the source code repository or under the path installation_path/pyRing/config_files. To discover your installation_path, type on the terminal:

    $ import pyRing
    $ pyRing.__file__
    

    that will output the path under which the package was built.

    A very fast example, to get you up to speed, can be launched by:

    $ pyRing --config-file installation_path/pyRing/config_files/Quickstart_configs/quick_gw150914_DS.ini
    

    This allows the beginner to obtain a quick and rough measurement of GW150914 ringdown spectrum in under 3 minutes on a laptop (using aggressive priors and very light sampler settings). Other similar examples are available inside the Quickstart_configs directory. These examples are mainly meant to give beginners a sense of the output of the code for various models.

    A fast analysis, with settings more reliable than the above, can be obtained by launching:

    $ pyRing --config-file repopath/pyRing/config_files/config_gw150914_local_data.ini
    

    This run still uses a simplified noise estimation and simplified sampler settings, but allows to obtain a decent measurement in ~20 minutes.

    Instead, a proper configuration file for the same run using production settings (hence obtaining publication-level results) can be launched by:

    $ pyRing --config-file repopath/pyRing/config_files/config_gw150914_production.ini
    

    Never forget that the sampler settings may need adjustment based on the problem you want to tackle. See the Usage section for further discussion.

  • Explore:

    The software supports a variety of analysis and injection options, all of which can be explored by running:

    $ pyRing --help
    
  • Requirements:

    The software is guaranteed to be compatible with 3.6=<python=<3.9.

References

Ringdown models

pyRing supports most of the analytical ringdown models available in the literature:

  • Damped Sinusoids model

    This is the simplest model available, consisting of a superposition of damped sinusoid . It supports up to all five polarisations (the ones independent in a L-shaped GW detector, see this reference) allowed for a metric theory of gravity, employing the conventions:

    \[\begin{split}\begin{aligned} h_s &= \sum_{j} A^s_j \cdot cos(\omega^s_j t+\phi^s_j) \cdot e^{-(t-t^0_j)/\tau^s_j} \, ,\\ h_{v_x} - i h_{v_y} &= \sum_{j} A^v_j \cdot e^{i( \omega^v_j t+\phi^v_j)} \cdot e^{-(t-t^0_j)/\tau^v_j} \, ,\\ h_{+} - i h_{\times} &= \sum_{j} A^t_j \cdot e^{i( \omega^t_j t+\phi^t_j)} \cdot e^{-(t-t^0_j)/\tau^t_j} \, . \end{aligned}\end{split}\]

    Where, for each mode, the complex amplitudes and complex frequencies \(A_j, \phi_j, \omega_j, \tau_j\) are left free to vary and \(t^0_j\) is the start time.

  • Kerr model

    \[h_+ + i h_{\times} = \frac{M_f}{D_L} \sum_{\ell=2}^{\infty} \sum_{m=-\ell}^{+\ell} \sum_{n=0}^{\infty}\, \, (h^{+}_{\ell m n} + h^{-}_{\ell m n})\]

    with:

    \[\begin{split}\begin{aligned} h^{+}_{\ell m n} &= \mathcal{A}^{+}_{\ell m n} \, S_{\ell m n}( \iota, \varphi) \, e^{i[(t-t_{\ell m n})\tilde{\omega}_{\ell m n}+\phi^{+}_{\ell m n}]} \\ h^{-}_{\ell m n} &= \mathcal{A}^{-}_{\ell m n} \, S_{\ell -m n}(\iota, \varphi) \, e^{-i[(t-t_{\ell m n})\tilde{\omega}^*_{\ell m n}-\phi^{-}_{\ell m n}]} \end{aligned}\end{split}\]

    where \(\tilde{\omega}_{\ell m n} = {\omega}_{\ell m n} + i/{\tau_{\ell m n}}\) is the complex ringdown frequency (a * denotes complex conjugation), expressed as a function of the remnant BH mass \(M_f\) and spin \(a_f\), \(\tilde{\omega}_{\ell m n} = \tilde{\omega}_{\ell m n}(M_f, a_f)\). The amplitudes \(\mathcal{A}^{+/-}_{\ell m n}\) and phases \(\phi^{+/-}_{\ell m n}\) characterise the excitation of each mode. In the case where the progenitors binary has spins aligned with the orbital angular momentum, reflection symmetry implies (see e.g. Blanchet’s review): \(\tilde{A}^{-} = (-1)^l \cdot {\tilde{A}^{+}}^*\), halving the number of free parameters per mode (* denotes complex conjugation, and we grouped the \(\mathcal{A}, \phi\) parameters in a complex amplitude). The inclination of the BH final spin relative to the observer’s line of sight is denoted by \(\iota\), while \(\varphi\) corresponds to the azimuthal angle of the line of sight in the BH frame. \(S_{\ell m n}\) are the spin-weighted spheroidal harmonics and \(t_{\ell m n}=t_0\) is a reference start time. In writing these equations, we follow the conventions of Lim et al. (see their Section III), accoding to which \(m>0\) indices denote co-rotating modes, while counter-rotating modes are labeled by \(m<0\). Counter-rotating modes are hardly excited in the post-merger phase for the binaries observed by LIGO-Virgo-Kagra. For a discussion about the possible relevance of counter-rotating modes see Refs. [1], [2]. For applications of this model to numerical relativity simulations, see e.g. 2110.03116, 2302.03050.

    This model additionally supports:

    • Tail terms, see arxiv:2302.03050 and references therein.

    • Quadratic modes, see arxiv:2208.07374 and references therein.

    • Parametric deviations from GR QNM predictions:

      Parametrised deviations to QNM frequencies and damping times as predicted by GR can be added in the form:

      \[\begin{split}\begin{aligned} \omega_{lmn} &= \omega^{GR}_{lmn} \cdot (1+\delta\omega_{lmn})\, ,\\ \tau_{lmn} &= \tau^{GR}_{lmn} \cdot (1+\delta\tau_{lmn})\, .\\ \end{aligned}\end{split}\]

      and extracted from the data. See the GWTC-2 testing GR catalog for additional details on the method.

    • QNM spectrum induced by the area quantisation:

      The ringdown model from Foit and Kleban, assuming a modification of the ringdown spectrum induced by the area quantisation hypothesis is also implemented. The quantisation is parametrised by a new parameter \(\alpha\), determining the new QNM spectrum, labeled by an index \(N\):

      \[\begin{split}\begin{aligned} \omega_N &= \omega_N(M_f, a_f, \alpha)\, ,\\ \tau_N &= \tau_N(M_f, a_f, \alpha)\, .\\ \end{aligned}\end{split}\]

      For details of the implementation, the application of the model to current observations and to simulated data, see this reference. A more realistic model of this scenario, considering the echoes generated from such a modification, was presented in this reference. For an extended discussion, see Agullo et al..

    • ParSpec deviations:

      The software also supports perturbative deviations within the Parametrized ringdown spin expansion coefficients formalism, introduced in this reference. The formalism first considers a perturbative expansion of the QNM spectrum in powers of the remnant spin, adding deviation parameters at each given order in spin, in the form:

      \[\begin{split}\begin{aligned} \omega_K &= \frac{1}{M} \, \sum_{j=0}^{N_{max}} \, \chi^j \, \omega^{(j)}_K \, (1+\gamma \, \delta \omega_K^{(j)})\, ,\\ \tau_K &= M \, \sum_{j=0}^{N_{max}} \, \chi^j \, \tau^{(j)}_K \, (1+\gamma \, \delta \tau_K^{(j)}) \, . \end{aligned}\end{split}\]

      where each mode is labeled by \(K\), \(\omega^{(j)}_K, \tau^{(j)}_K\) are the GR spin-expansion coefficients and \(\delta \omega_K^{(j)}\) are the beyond-GR coefficients, to be inferred from the data. The beyond GR coupling is controlled by the parameter:

      \[\gamma = \frac{\alpha \,(1+z)^p}{M_f^p}\]

      expressed as a function of a theory-dependent coupling \(\alpha\), with \(p\) representing its mass dimension.

      Such a formalism encompasses large classes of modified theories of gravity. Depending on the theory considered, in certain cases it allowed to place the most stringent constraints to date on some of these alternative theories. Details of the implementation and the application to observational data were presented here.

    • Eistein-scalar-Gauss-Bonnet corrections:

      Coming soon…

    • Kerr-Newman charges:

      Coming soon…

    Note: at the moment, for the Kerr multipolar model, the modes are supposed to start all at the same time. This implicitly assumes that all the modes are already excited when the analysis is start.

  • Multi-modal ringdown non-spinning (MMRDNS) model

    This model, introduced in this reference is an improvement of the Kerr model in the case where the remnant black hole is generated by the quasi-circular coalescence of two non-spinning progenitor black holes. It models the most dominant modes (up to \(\ell=5\)) for the parameter space considered, assumes the conjugate symmetry discussed above and does not keep into account counter-rotating modes. The amplitudes and phases are tuned to BBH numerical simulations and are expressed as a function of the progenitors parameters:

    \[\begin{split}\begin{aligned} \mathcal{A}_{lmn} &= \mathcal{A}_{lmn}(\eta)\, ,\\ \phi_{lmn} &= \phi_{lmn}(\eta)\, .\\ \end{aligned}\end{split}\]

    where \(\eta\) is the symmetric mass ratio of the progenitors binary. The model describes only the late ringdown and was calibrated at \(10 M_f\) after the peak of \(\psi^{NR}_{22}\). For low-SNR events it can be extrapolated to earlier times, but its accuracy should be explicitly checked. See also this reference for a discussion of the start time and an application of the model to ringdown parameter estimation.

  • Multi-modal ringdown non-precessing (MMRDNP) model

    This model, introduced in this reference, is an improvement to MMRDNS to the case of spinning, non-precessing, progenitors. It employs a spherical decomposition, keeping into account mode mixing between different spheroidal modes. It models the most dominant modes (up to \(\ell=4\)) for the parameter space considered, assumes the conjugate symmetry discussed above and does not keep into account counter-rotating modes. The complex amplitudes are now expressed as:

    \[\begin{split}\begin{aligned} \mathcal{A}_{lm} &= \mathcal{A}_{lm}(\eta, \chi_s, \chi_a)\, ,\\ \phi_{lm} &= \phi_{lm}(\eta, \chi_s, \chi_a)\, .\\ \end{aligned}\end{split}\]

    where \(\eta\) is the symmetric mass ratio of the progenitors binary, \(\chi_s\) is a symmetric spin combination of the progenitors binary, and \(\chi_a\) is a anti-symmetric spin combination of the progenitors binary. The model describes only the late ringdown and was calibrated at \(20 M_f\) after the peak of \(h_{22}\). For low-SNR events it can be extrapolated to earlier times, but its accuracy should be explicitly checked.

  • Kamaretsos-Hannam-Husa-Sathyaprakash (KHS) multi-modal model

    This model, introduced in [1] and [2] is similar to MMRDNP, but uses a different fit of the amplitudes. Phases have not been tuned to numerical relativity and are set to zero by default. It models the most dominant modes (up to \(\ell=4\)) for the parameter space considered, assumes the conjugate symmetry discussed above and does not keep into account counter-rotating modes.

  • Tidal Effective One Body post-merger (TEOBPM) model

    The TEOBPM model, introduced in Damour and Nagar, arXiv:1406.0401, accurately describes the whole post-merger phase (from the peak of \(h_{22}\) onwards) for spinning, non-precessing binaries. The amplitudes and phases are calibrated to full numerical simulation, and the waveform is constructed through a spherical decomposition of the most dominant modes (up to \(\ell=5\)) with a resummation strategy keeping into account nonlinearities and overtones contributions through a phenomenological description of time-dependent amplitudes.

    \[\begin{split}\begin{aligned} \mathcal{A}_{lm} &= \mathcal{A}_{lm}(t; m_1, m_2 \chi_1, \chi_2)\, ,\\ \phi_{lm} &= \phi_{lm}(t; m_1, m_2, \chi_1, \chi_2)\, .\\ \end{aligned}\end{split}\]

    Since the model starts at the peak of the emission, in this case also the time-delays between the peak of the different modes are crucially kept into account. Further details on the model can be found in references [1] and [2].

    This model also forms the basis for the ringdown of IMRPhenomTPHM, arXiv:2105.05872. An implementation of the model in C is available here. A systematic characterisation of the model, and its application to higher-modes searches on GWTC-3 data can be found in Gennari et al., arXiv:2312.12515.

A script showing how to handle all available models can be found in pyring/scripts/Waveform_utils/plot_waveform.py.

Usage

  • Code input/output:

    The adopted configuration and the progress of the run are shown on the screen if the option screen-output=1 is added inside the [input] section of the configuration file. Otherwise, the output from pyRing is stored in the example_outdir/stderr_pyRing.txt, example_outdir/stdout_pyRing.txt files, while the progress of the sampler is stored inside the Nested_sample/cpnest.log file. Data and PSD diagnostic plots are produced at the beginning of the run and can be found in the example_outdir/Noise directory. All paths in the configuration files are relative to the path stored in the PYRING_PREFIX.

    At the end of the run, the posterior and evidence files can be found in the example_outdir/Nested_sampler directory under posterior.dat and Evidence.txt. Results on all parameters are displayed in the example_outdir/Plots directory. If the pesummary option is activated (see the help message for details), a PESummary metafile containing all the necessary information to reproduce the run, together with the complete run output, will be produced. Also, an html page displaying parameters posteriors will be created under: example_outdir/Plots/pesummary_postproc/home.html.

  • Sampler convergence:

    For details on the sampler used, CPNest, see CPNest documentation.

    Standard templates with a small number of parameters (e.g. a single damped sinusoid or a single Kerr mode) can be safely employed with the sampler settings documented in the repopath/pyRing/config_files/config_gw150914_production.ini example.

    When assuming many Kerr modes (e.g. more than two overtones), care must be taken in assessing the sampler’s convergence. To produce publication level results in these cases, we suggest checking that more conservative sampler settings such as nlive=8192, maxmcmc=8192 do not change the obtained results. We also suggest combining at least four parallel chains.

Contributing

If you have a request for an additional feature, spot any mistake or find any problem with using the code, please open an issue. If you are part of the LVK collaboration, this can be done through the issue tracker, otherwise, please send an email to our Service Desk address (contact+lscsoft-pyring-10295-issue-@support.ligo.org) to open an issue.

To develop the code, we follow a standard {create a branch-apply your edits-submit a merge request} workflow. If you wish to contribute directly to its development, please follow the steps described below:

  1. Make sure to start from the latest version of the branch you are looking at, so please pull before planning any changes to the code;

  2. Create your own branch (if you have permissions below developer, please fork the code and then keep following these instructions), where you can apply all your improvements and modifications to the code;

  3. Please check thoroughly your changes. Specifically check that, after applying them, you are still able to install and run the code without occurring in any errors. Test it by running a couple of quick examples (e.g. config_gw150914_local_data.ini, config_damped_sinusoids_inj_gaussian_noise.ini).

  4. Create a merge request to master and assign it to either Gregorio (gregorio.carullo@ligo.org) or Danny (danny.laghi@ligo.org);

Someone will have a look at your edits and eventually merge them. Thanks for taking time to contribute to the code, your help is greatly appreciated!

For additional questions, feedback and suggestions feel free to reach by email to gregorio.carullo@ligo.org or, if you are part of the LVK collaboration, directly through chat.ligo.org on the pyRing channel.

Indices and tables