Waveform models¶

Waveform models give the prediction for a GW signal emitted by a coalescing binary as a function of the parameters of the source.

WF4Py provides Fourier domain waveform models. In particular, it provides a Python implementation for some selected state-of-the-art models, written following the original implementations in the LIGO Algorithm Library, LAL.

The WaveFormModel class¶

Waveforms in WF4Py are built as classes, initialised as follows

class WF4Py.waveform_models.WFclass_definition.WaveFormModel(objType, fcutPar, is_tidal=False, is_HigherModes=False, is_Precessing=False, is_eccentric=False)[source]¶

Abstract class to compute waveforms

Parameters

objType (str) – The kind of system the wf model is made for, can be 'BBH', 'BNS' or 'NSBH'.
fcutPar (float) – The cut frequency factor of the waveform. This can either be given in \(\rm Hz\), as for WF4Py.waveform_models.TaylorF2_RestrictedPN.TaylorF2_RestrictedPN, or as an adimensional frequency (Mf), as for the IMR models.
is_tidal (bool, optional) – Boolean specifying if the waveform includes tidal effects.
is_HigherModes (bool, optional) – Boolean specifying if the waveform includes the contribution of sub-dominant (higher-order) modes.
is_Precessing (bool, optional) – Boolean specifying if the waveform includes spin-precession effects.
is_eccentric (bool, optional) – Boolean specifying if the waveform includes orbital eccentricity.

Each waveform includes four fundamental methods, to compute, given the parameter of the source(s), the phase of the signal, \(\Phi (f)\), the amplitude of the signal, \(A (f)\), the time to coalescence as a function of the frequency, \(\tau^* (f)\), and the cut frequency.

abstract WaveFormModel.Phi(f, **kwargs)[source]¶

Compute the phase of the GW as a function of frequency, given the events parameters.

We compute here only the GW phase, not the full phase of the signal, which also includes the reference phase and the time of coalescence.

Parameters

f (numpy.ndarray) – Frequency grid on which the phase will be computed, in \(\rm Hz\).
kwargs (dict(numpy.ndarray, numpy.ndarray, ...)) – Dictionary with arrays containing the parameters of the events to compute the phase of, as in events.

Returns

GW phase for the chosen events evaluated on the frequency grid.

Return type

numpy.ndarray

abstract WaveFormModel.Ampl(f, **kwargs)[source]¶

Compute the amplitude of the GW as a function of frequency, given the events parameters.

Parameters

f (numpy.ndarray) – Frequency grid on which the phase will be computed, in \(\rm Hz\).
kwargs (dict(numpy.ndarray, numpy.ndarray, ...)) – Dictionary with arrays containing the parameters of the events to compute the amplitude of, as in events.

Returns

GW amplitude for the chosen events evaluated on the frequency grid.

Return type

numpy.ndarray

WaveFormModel.tau_star(f, **kwargs)[source]¶

Compute the time to coalescence (in seconds) as a function of frequency (in \(\rm Hz\)), given the events parameters.

Parameters

f (numpy.ndarray) – Frequency grid on which the time to coalescence will be computed, in \(\rm Hz\).
kwargs (dict(numpy.ndarray, numpy.ndarray, ...)) – Dictionary with arrays containing the parameters of the events to compute the time to coalescence of, as in events.

Returns

time to coalescence for the chosen events evaluated on the frequency grid, in seconds.

Return type

numpy.ndarray

Note

For WF4Py.waveform_models.WFclass_definition.NewtInspiral we use the \(\tau^* (f)\) expression in M. Maggiore – Gravitational Waves Vol. 1 eq. (4.21). For the other models instead we use the \(\tau^* (f)\) expression in arXiv:0907.0700 eq. (3.8b), valid up to 3.5 PN.

WaveFormModel.fcut(**kwargs)[source]¶

Compute the cut frequency of the waveform as a function of the events parameters, in \(\rm Hz\).

Parameters: kwargs (dict(numpy.ndarray, numpy.ndarray, ...)) – Dictionary with arrays containing the parameters of the events to compute the cut frequency of, as in events.
Returns: Cut frequency of the waveform for the chosen events, in \(\rm Hz\).
Return type: numpy.ndarray

Some models also have a method denoted as hphc to compute directly the \(\tilde{h}_+\) and \(\tilde{h}_{\times}\) polarisations of the gravitational wave, see below.

Waveform models¶

We here report and briefly describe the waveform models implemented in pure Python in WF4Py. We carefully checked that our Python implementation accurately reproduces the original LAL waveforms.

Leading order inspiral¶

This model includes only the leading order term in the inspiral.

class WF4Py.waveform_models.WFclass_definition.NewtInspiral(**kwargs)[source]¶

Leading order inspiral only waveform model.

Relevant references: M. Maggiore – Gravitational Waves Vol. 1, chapter 4.

Parameters: kwargs – Optional arguments to be passed to the parent class WaveFormModel.

TaylorF2¶

New in version 1.0.1: Added the possibility to terminate the waveform at the ISCO frequency of a remnant Kerr BH. Added the spin-induced quadrupole due to tidal effects.

This model includes contributions to the phase up to 3.5 order in the Post Newtonian, PN, expansion, and can thus be used to describe the inspiral. The amplitude is the same as in Newtonian approximation. Our implementation can include both the tidal terms at 5 and 6 PN (see arXiv:1402.5156) and a moderate eccentricity in the orbit \(e_0\lesssim 0.1\) up to 3 PN (see arXiv:1605.00304). There is no limitation in the parameters range, but, being an inspiral-only model, WF4Py.waveform_models.TaylorF2_RestrictedPN.TaylorF2_RestrictedPN is better suited for BNS systems.

class WF4Py.waveform_models.TaylorF2_RestrictedPN.TaylorF2_RestrictedPN(fHigh=None, is_tidal=False, use_3p5PN_SpinHO=False, phiref_vlso=False, is_eccentric=False, fRef_ecc=None, which_ISCO='Schw', use_QuadMonTid=False, **kwargs)[source]¶

TaylorF2 restricted PN waveform model, with coefficients up to 3.5 PN. The amplitude is thus the same as in Newtonian approximation, and the model is valid only in the inspiral.

This model can include both the contribution of tidal effects at 5 and 6 PN and the contribution of eccentricity up to 3 PN.

Relevant references:

[1] arXiv:0907.0700

[2] arXiv:1107.1267

[3] arXiv:1402.5156

[4] arXiv:1601.05588

[5] arXiv:1605.00304

Parameters

fHigh (float) –
The cut frequency factor of the waveform, in \(\rm Hz\). By default this is set to two times the Innermost Stable Circular Orbit, ISCO, frequency of a remnant Schwarzschild BH having a mass equal to the total mass of the binary, see WF4Py.WFutils.f_isco. Another useful value, whose coefficient is provided in WF4Py.WFutils.f_qK, is the limit of the quasi-Keplerian approximation, defined as in arXiv:2108.05861 (see also arXiv:1605.00304), which is more conservative than two times the Schwarzschild ISCO.
is_tidal (bool, optional) – Boolean specifying if the waveform has to include tidal effects.
use_3p5PN_SpinHO (bool, optional) – Boolean specifying if the waveform has to include the quadratic- and cubic-in-spin contributions at 3.5 PN, which are not included in LAL.
phiref_vlso (bool, optional) – Boolean specifying if the reference frequency of the waveform has to be set to the Last Stable Orbit, LSO, frequency.
is_eccentric (bool, optional) – Boolean specifying if the waveform has to include orbital eccentricity.
fRef_ecc (float, optional) – The reference frequency for the provided eccentricity, \(f_{e_{0}}\).
which_ISCO (str, optional) –
String specifying if the waveform has to be cut at two times the ISCO frequency of a remnant Schwarzschild (non-rotating) BH or of a Kerr BH, as in arXiv:2108.05861 (see in particular App. C), with the fits from arXiv:1605.01938. The Schwarzschild ISCO can be selected passing 'Schw', while the Kerr ISCO passing 'Kerr'. NOTE: the Kerr option pushes the validity of the model to the limit, and is not the default option.
use_QuadMonTid (bool, optional) – Boolean specifying if the waveform has to include the spin-induced quadrupole due to tidal effects, with the fits from arXiv:1608.02582.
kwargs – Optional arguments to be passed to the parent class WF4Py.waveform_models.WFclass_definition.WaveFormModel.

IMRPhenomD¶

This is a full inspiral–merger-ringdown model tuned with NR simulations, which can be used to simulate signals coming from BBH mergers, with non–precessing spins up to \(|\chi_z|\sim 0.85\) and mass ratios up to \(q = m_1/m_2 \sim 18\).

class WF4Py.waveform_models.IMRPhenomD.IMRPhenomD(**kwargs)[source]¶

IMRPhenomD waveform model.

Relevant references:

[1] arXiv:1508.07250

[2] arXiv:1508.07253

Parameters: kwargs – Optional arguments to be passed to the parent class WF4Py.waveform_models.WFclass_definition.WaveFormModel.

IMRPhenomD_NRTidalv2¶

This is a full inspiral-merger-ringdown model tuned with NR simulations, which extends the IMRPhenomD model to include tidal effects, and can thus be used to accurately describe signals coming from BNS mergers. The validity has been assessed for masses between \(1\,{\rm M}_{\odot}\) and \(3\,{\rm M}_{\odot}\), spins up to \(|\chi_z|\sim 0.6\) and tidal deformabilities up to \(\Lambda_i\sim 5000\).

class WF4Py.waveform_models.IMRPhenomD_NRTidalv2.IMRPhenomD_NRTidalv2(**kwargs)[source]¶

IMRPhenomD_NRTidal waveform model.

Relevant references:

[1] arXiv:1508.07250

[2] arXiv:1508.07253

[3] arXiv:1905.06011

Parameters: kwargs – Optional arguments to be passed to the parent class WF4Py.waveform_models.WFclass_definition.WaveFormModel.

The model includes a Planck taper filter to terminate the waveform after merger, we thus the cut frequency slightly before the end of the filter.

IMRPhenomHM¶

This is a full inspiral–merger-ringdown model tuned with NR simulations, which takes into account not only the \((2,2)\) quadrupole of the signal, but also the sub–dominant multipoles \((l,m) = (2,1),\, (3,2),\, (3,3),\, (4,3)\), and \((4,4)\), that can be particularly relevant to better describe the signal coming from BBH systems. The calibration range is the same of the IMRPhenomD model.

class WF4Py.waveform_models.IMRPhenomHM.IMRPhenomHM(**kwargs)[source]¶

IMRPhenomHM waveform model.

Relevant references:

Parameters: kwargs – Optional arguments to be passed to the parent class WF4Py.waveform_models.WFclass_definition.WaveFormModel.

To avoid for loops and recomputing coefficients (given that in this case the amplitude cannot be computed separately from the phase), this model features a WF4Py.waveform_models.IMRPhenomHM.IMRPhenomHM.hphc method, to compute directly \(\tilde{h}_+\) and \(\tilde{h}_{\times}\)

IMRPhenomHM.hphc(f, **kwargs)[source]¶

Compute the plus and cross polarisations of the GW as a function of frequency, given the events parameters, avoiding for loops over the modes.

Parameters

f (numpy.ndarray) – Frequency grid on which the phase will be computed, in \(\rm Hz\).
kwargs (dict(numpy.ndarray, numpy.ndarray, ...)) – Dictionary with arrays containing the parameters of the events to compute the phase of, as in events.

Returns

Plus and cross polarisations of the GW for the chosen events evaluated on the frequency grid.

Return type

tuple(numpy.ndarray, numpy.ndarray)

Also, in this case the WF4Py.waveform_models.IMRPhenomHM.IMRPhenomHM.Phi and WF4Py.waveform_models.IMRPhenomHM.IMRPhenomHM.Ampl methods return dictionaries containing the phases and amplitudes of the various modes, respectively. The dictionaries have keys '21', '22', '32', '33', '43' and '44'.

IMRPhenomHM.Phi(f, **kwargs)[source]¶

Compute the phase of the GW as a function of frequency, given the events parameters.

Parameters

f (numpy.ndarray) – Frequency grid on which the phase will be computed, in \(\rm Hz\).
kwargs (dict(numpy.ndarray, numpy.ndarray, ...)) – Dictionary with arrays containing the parameters of the events to compute the phase of, as in events.

Returns

GW phases of the various modes for the chosen events evaluated on the frequency grid.

Return type

dict(numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray)

IMRPhenomHM.Ampl(f, **kwargs)[source]¶

Compute the amplitude of the GW as a function of frequency, given the events parameters.

Parameters

f (numpy.ndarray) – Frequency grid on which the phase will be computed, in \(\rm Hz\).
kwargs (dict(numpy.ndarray, numpy.ndarray, ...)) – Dictionary with arrays containing the parameters of the events to compute the amplitude of, as in events.

Returns

GW amplitudes of the various modes for the chosen events evaluated on the frequency grid.

Return type

dict(numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray)

To combine the various modes and obtain the full amplitude and phase from these outputs, it is possible to use the function

WF4Py.WFutils.Add_Higher_Modes(Ampl, Phi, iota, phi=0.0)[source]¶

Compute the total signal from a collection of different modes.

Parameters

Ampl (dict(numpy.ndarray, numpy.ndarray, ...)) – Dictionary containing the amplitudes for each mode computed on a grid of frequencies. The keys are expected to be stings made up of \(l\) and \(m\), e.g. for \((2,2)\) –> key= '22'.
Phi (dict(numpy.ndarray, numpy.ndarray, ...)) – Dictionary containing the phases for each mode computed on a grid of frequencies.
iota (numpy.ndarray or float) – The inclination angle(s) of the system(s) with respect to orbital angular momentum, \(\iota\), in \(\rm rad\).
phi (numpy.ndarray or float) – The second angular direction of the spherical coordinate system.

Returns

Plus and cross polarisations of the GW for the chosen events evaluated on the frequency grid.

Return type

tuple(numpy.ndarray, numpy.ndarray)

IMRPhenomNSBH¶

This is a full inspiral–merger-ringdown model tuned with NR simulations, which can describe the signal coming from the merger of a NS and a BH, with mass ratios up to \(q = m_1/m_2 \sim 100\), also taking into account tidal effects and the impact of the possible tidal disruption of the NS.

class WF4Py.waveform_models.IMRPhenomNSBH.IMRPhenomNSBH(verbose=True, returnMergerType=False, **kwargs)[source]¶

IMRPhenomNSBH waveform model

The inputs labelled as 1 refer to the BH (e.g. 'chi1z') and with 2 to the NS (e.g. 'Lambda2')

Relevant references:

Parameters

verbose (bool, optional) – Boolean specifying if the code has to print additional details during execution.
returnMergerType (bool, optional) – Boolean specifying if the kind of merger (disruptive or non disruptive) has to be returned. This is determined in the amplitude calculation.
kwargs – Optional arguments to be passed to the parent class WF4Py.waveform_models.WFclass_definition.WaveFormModel.

Note

In LAL, to compute the parameter \(\xi_{\rm tide}\) in arXiv:1509.00512 eq. (8), the roots are extracted. In Python this would break the possibility to vectorise so, to circumvent the issue, we compute a grid of \(\xi_{\rm tide}\) as a function of the compactness, mass ratio and BH spin, and then use a 3D interpolator. The first time the code runs, if this interpolator is not already present, it will be computed. The base resolution of the grid is 200 points per parameter, that we find sufficient to reproduce the LAL implementation with good precision, given the smooth behaviour of the function, but this can be raised if needed. In this case, it is necessary to change the name of the file assigned to self.path_xiTide_tab and the res input passed to the function that loads the grid.

IMRPhenomNSBH._make_xiTide_interpolator(res=200)[source]¶

Load the table of the parameter \(\xi_{\rm tide}\) if present or computes it if not, and builds the needed 3-D interpolator.

Parameters: res (int, optional) – Resolution of the grid in compactness, mass ratio and spin.

IMRPhenomXAS¶

This is a full inspiral–merger-ringdown model tuned with NR simulations, which can be used to simulate signals coming from BBH mergers, with non–precessing spins up to \(|\chi_z|\sim 0.9\) and mass ratios \(q = m_1/m_2\) from 1 to 1000, among the last to be released.

class WF4Py.waveform_models.IMRPhenomXAS.IMRPhenomXAS(InsPhaseVersion=104, IntPhaseVersion=105, IntAmpVersion=104, **kwargs)[source]¶

IMRPhenomXAS waveform model.

Relevant references: arXiv:2001.11412

Parameters

InsPhaseVersion (int, optional) –
Int specifying the inspiral phase model to use
- 104 (default): Canonical TaylorF2 at 3.5PN (including cubic-in-spin and quadratic-in-spin corrections) with 4 pseudo-PN coefficients;
- 105: Canonical TaylorF2 at 3.5PN (including cubic-in-spin and quadratic-in-spin corrections) with 5 pseudo-PN coefficients;
- 114: Extended TaylorF2 (including cubic-in-spin, quadratic-in-spin corrections, 4PN and 4.5PN orbital corrections) with 4 pseudo-PN coefficients;
- 115: Extended TaylorF2 (including cubic-in-spin, quadratic-in-spin corrections, 4PN and 4.5PN orbital corrections) with 5 pseudo-PN coefficients
IntPhaseVersion (int, optional) –
Int specifying the intermediate phase model to use
- 104: 4th order polynomial;
- 105 (default): 5th order polynomial.
IntAmpVersion (int, optional) –
Int specifying the intermediate amplitude model to use
- 104 (default): 4th order polynomial, less accurate in calibration but more stable extrapolation;
- 105: 5th order polynomial, more accurate in calibration but less stable extrapolation.
kwargs – Optional arguments to be passed to the parent class WF4Py.waveform_models.WFclass_definition.WaveFormModel.