Waveform Module#

The complex waveform \(h = h_{+} - i h_{\times}\) is calculated as a sum of many harmonics,

(1)#\[\begin{align} h(t, r, \theta, \phi) = \frac{\mu}{r} \sum_{lm} H_{lm}(t) e^{i \Phi_{lm}(t)} {}_{-2} Y_{lm}(\theta, \phi) \end{align}\]
bhpwave.waveform.check_source_frame_parameters(a, x0, theta, phi, Phi_phi0)[source]#
bhpwave.waveform.check_ssb_frame_parameters(a, x0, qK, phiK, Phi_phi0)[source]#
class bhpwave.waveform.KerrCircularWaveform(trajectory_data=None, harmonic_data=None, num_threads=None)[source]#

Bases: object

Class that generates the gravitational waveform produced by an extreme-mass-ratio inspiral using the adiabatic approximation from black hole perturbation theory and the self-force formalism. By default, the waveform is generated in the solar system barycenter frame.

Waveform generation is limited to quasi-circular inspirals in Kerr spacetime, but the generator mirrors the generic parametrization used in other EMRI waveform generators (e.g., https://bhptoolkit.org/FastEMRIWaveforms/html/user/main.html)

Parameters:

  • trajectory_data (TrajectoryData or None, optional) – TrajectoryData class which holds interpolants of the relevant trajectory data

  • harmonic_data (HarmonicAmplitudes or None, optional) – HarmonicAmplitudes class which holds interpolants of the harmonic mode amplitudes

  • num_threads (int or None, optional) – Number of threads used to evaluate the waveform

select_modes(M, mu, a, r0, qS, phiS, qK, phiK, Phi_phi0, dt=10.0, T=1.0, **kwargs)[source]#

Selects the harmonic modes that are used for calculating the waveform

Parameters:

  • M (double) – mass (in solar masses) of the massive black hole

  • mu (double) – mass (in solar masses) of the (smaller) stellar-mass compact object

  • a (double) – dimensionless black hole spin

  • r0 (double) – initial orbital separation of the two objects

  • qS (double) – polar angle of the source’s sky location

  • phiS (double) – azimuthal angle of the source’s sky location

  • qK (double) – polar angle of the Kerr spin vector

  • phiK (double) – azimuthal angle of the Kerr spin vector

  • Phi_phi0 (double) – Initial azimuthal position of the small compact object

  • T (double, optional) – Duration of the waveform in years

Return type:

1d-array[tuples(doubles)]

__call__(M, mu, a, r0, dist, qS, phiS, qK, phiK, Phi_phi0, dt=10.0, T=1.0, **kwargs)[source]#

Calculate the complex gravitational wave strain

Parameters:

  • M (double) – mass (in solar masses) of the massive black hole

  • mu (double) – mass (in solar masses) of the (smaller) stellar-mass compact object

  • a (double) – dimensionless black hole spin

  • r0 (double) – initial orbital separation of the two objects

  • dist (double) – luminosity distance to the source in Gpc

  • qS (double) – polar angle of the source’s sky location

  • phiS (double) – azimuthal angle of the source’s sky location

  • qK (double) – polar angle of the Kerr spin vector

  • phiK (double) – azimuthal angle of the Kerr spin vector

  • Phi_phi0 (double) – Initial azimuthal position of the small compact object

  • dt (double, optional) – Spacing of time samples in seconds

  • T (double, optional) – Duration of the waveform in years

  • pad_output (bool, optional) – True returns the waveform for the full duration T years even if the system merges before T years has elasped

  • select_modes (list[tuple(double)] or ndarray[tuple(double)], optional) – A list of tuples \((l, m)\) that select which modes to include in the waveform calculation

  • return_list (bool, optional) – True returns the plus and cross polarizations of the waveform as separate ndarrays

  • include_negative_m (bool, optional) – True returns the sum of the positive and negative m-modes for each mode in select_modes

Return type:

1d-array[complex] or list[two 1d-arrays[double]]

harmonics(M, mu, a, r0, dist, qS, phiS, qK, phiK, Phi_phi0, dt=10.0, T=1.0, **kwargs)[source]#

Calculate the spin-weighted spherical harmonic modes of the gravitational wave strain

Parameters:

  • M (double) – mass (in solar masses) of the massive black hole

  • mu (double) – mass (in solar masses) of the (smaller) stellar-mass compact object

  • a (double) – dimensionless black hole spin

  • r0 (double) – initial orbital separation of the two objects

  • dist (double) – luminosity distance to the source in Gpc

  • qS (double) – polar angle of the source’s sky location

  • phiS (double) – azimuthal angle of the source’s sky location

  • qK (double) – polar angle of the Kerr spin vector

  • phiK (double) – azimuthal angle of the Kerr spin vector

  • Phi_phi0 (double) – Initial azimuthal position of the small compact object

  • dt (double, optional) – Spacing of time samples in seconds

  • T (double, optional) – Duration of the waveform in years

  • pad_output (bool, optional) – True returns the waveform for the full duration T years even if the system merges before T years has elasped

  • select_modes (list[tuple(double)] or ndarray[tuple(double)], optional) – A list of tuples \((l, m)\) that select which modes to include in the waveform calculation

  • return_list (bool, optional) – True returns the plus and cross polarizations of the waveform as separate ndarrays

  • include_negative_m (bool, optional) – True returns the sum of the positive and negative m-modes for each mode in select_modes

Return type:

2d-array[complex] or list[two 2d-arrays[double]]

harmonics_data(M, mu, a, r0, dist, qS, phiS, qK, phiK, Phi_phi0, dt=10.0, T=1.0, **kwargs)[source]#

Calculate the amplitudes and phases of the spin-weighted spherical harmonic \((l, m)\)-modes of the gravitational wave strain. The function returns mode data for both positive and negative m-modes. Given a list of modes \([(l_1, m_1), (l_2, m_2), \dots , (l_N, m_N)]\) the function returns data in the order \([(l_1, m_1), (l_1, -m_1), (l_2, m_2), (l_2, -m_2), \dots, (l_N, m_N), (l_N, -m_N)]\).

Parameters:

  • M (double) – mass (in solar masses) of the massive black hole

  • mu (double) – mass (in solar masses) of the (smaller) stellar-mass compact object

  • a (double) – dimensionless black hole spin

  • r0 (double) – initial orbital separation of the two objects

  • dist (double) – luminosity distance to the source in Gpc

  • qS (double) – polar angle of the source’s sky location

  • phiS (double) – azimuthal angle of the source’s sky location

  • qK (double) – polar angle of the Kerr spin vector

  • phiK (double) – azimuthal angle of the Kerr spin vector

  • Phi_phi0 (double) – Initial azimuthal position of the small compact object

  • dt (double, optional) – Spacing of time samples in seconds

  • T (double, optional) – Duration of the waveform in years

  • pad_output (bool, optional) – True returns the waveform for the full duration T years even if the system merges before T years has elasped

  • select_modes (list[tuple(double)] or ndarray[tuple(double)], optional) – A list of tuples \((l, m)\) that select which modes to include in the waveform calculation. Only positive m-modes are used.

  • return_list (bool, optional) – True returns the plus and cross polarizations of the waveform as separate ndarrays

Return type:

2d-array[complex] or list[two 2d-arrays[double]]

source_frame(M, mu, a, r0, theta, phi, Phi_phi0, dt=10.0, T=1.0, **kwargs)[source]#

Calculate the scaled gravitational wave strain \(r\times h/\mu\) in the source frame

Parameters:

  • M (double) – mass (in solar masses) of the massive black hole

  • mu (double) – mass (in solar masses) of the (smaller) stellar-mass compact object

  • a (double) – dimensionless black hole spin

  • r0 (double) – initial radial separation

  • theta (double) – polar angle of the observor with respect to the Kerr spin vector

  • phi (double) – azimuthal angle of the observor with respect to the Kerr spin vector

  • Phi_phi0 (double) – Initial azimuthal position of the small compact object

  • dt (double, optional) – Spacing of time samples in seconds. Default is 10 seconds.

  • T (double, optional) – Duration of the waveform in years. Default is 1 year.

  • pad_output (bool, optional) – True returns the waveform for the full duration T years even if the system merges before T years has elasped

  • select_modes (list[tuple(double)] or ndarray[tuple(double)], optional) – A list of tuples \((l, m)\) that select which modes to include in the waveform calculation

  • return_list (bool, optional) – True returns the plus and cross polarizations of the waveform as separate ndarrays

  • include_negative_m (bool, optional) – True returns the sum of the positive and negative m-modes for each mode in select_modes

Return type:

1d-array[complex] or list[two 1d-arrays[double]]

class bhpwave.waveform.KerrWaveform(trajectory_data=None, harmonic_data=None, num_threads=None)[source]#

Bases: KerrCircularWaveform

Class that generates the gravitational waveform produced by an extreme-mass-ratio inspiral using the adiabatic approximation from black hole perturbation theory and the self-force formalism. By default, the waveform is generated in the solar system barycenter frame.

Waveform generation is limited to quasi-circular inspirals in Kerr spacetime, but the generator mirrors the generic parametrization used in other EMRI waveform generators (e.g., https://bhptoolkit.org/FastEMRIWaveforms/html/user/main.html)

Parameters:

  • trajectory_data (TrajectoryData or None, optional) – a TrajectoryData class which holds interpolants of the relevant trajectory data

  • harmonic_data (HarmonicAmplitudes or None, optional) – a HarmonicAmplitudes class which holds interpolants of the harmonic mode amplitudes

  • num_threads (int or None, optional) – the number of threads used to evaluate the waveform

__call__(M, mu, a, p0, e0, x0, dist, qS, phiS, qK, phiK, Phi_phi0, Phi_r0, Phi_theta0, dt=10.0, T=1.0, **kwargs)[source]#

Calculate the gravitational wave strain

Parameters:

  • M (double) – mass (in solar masses) of the massive black hole

  • mu (double) – mass (in solar masses) of the (smaller) stellar-mass compact object

  • a (double) – dimensionless black hole spin

  • p0 (double) – initial semi-latus rectum

  • e0 (double) – initial orbital eccentricity

  • x0 (double) – intial cosine of the orbital inclination

  • dist (double) – luminosity distance to the source in Gpc

  • qS (double) – polar angle of the source’s sky location

  • phiS (double) – azimuthal angle of the source’s sky location

  • qK (double) – polar angle of the Kerr spin vector

  • phiK (double) – azimuthal angle of the Kerr spin vector

  • Phi_phi0 (double) – Initial azimuthal position of the small compact object

  • Phi_r0 (double) – Phase describing the initial radial position and velocity of the small compact object

  • Phi_theta0 (double) – Phase describing the initial polar position and velocity of the small compact object

  • dt (double, optional) – Spacing of time samples in seconds

  • T (double, optional) – Duration of the waveform in years

  • pad_output (bool, optional) – True returns the waveform for the full duration T years even if the system merges before T years has elasped

  • select_modes (list[tuple(double)] or ndarray[tuple(double)], optional) – A list of tuples \((l, m)\) that select which modes to include in the waveform calculation

  • return_list (bool, optional) – True returns the plus and cross polarizations of the waveform as separate ndarrays

  • include_negative_m (bool, optional) – True returns the sum of the positive and negative m-modes for each mode in select_modes

Return type:

1d-array[complex] or list[two 1d-arrays[double]]

harmonics(M, mu, a, p0, e0, x0, dist, qS, phiS, qK, phiK, Phi_phi0, Phi_r0, Phi_theta0, dt=10.0, T=1.0, **kwargs)[source]#

Calculate the spin-weighted spherical harmonic modes of the gravitational wave strain

Parameters:

  • M (double) – mass (in solar masses) of the massive black hole

  • mu (double) – mass (in solar masses) of the (smaller) stellar-mass compact object

  • a (double) – dimensionless black hole spin

  • p0 (double) – initial semi-latus rectum

  • e0 (double) – initial orbital eccentricity

  • x0 (double) – intial cosine of the orbital inclination

  • dist (double) – luminosity distance to the source in Gpc

  • qS (double) – polar angle of the source’s sky location

  • phiS (double) – azimuthal angle of the source’s sky location

  • qK (double) – polar angle of the Kerr spin vector

  • phiK (double) – azimuthal angle of the Kerr spin vector

  • Phi_phi0 (double) – Initial azimuthal position of the small compact object

  • Phi_r0 (double) – Phase describing the initial radial position and velocity of the small compact object

  • Phi_theta0 (double) – Phase describing the initial polar position and velocity of the small compact object

  • dt (double, optional) – Spacing of time samples in seconds

  • T (double, optional) – Duration of the waveform in years

  • pad_output (bool, optional) – True returns the waveform for the full duration T years even if the system merges before T years has elasped

  • select_modes (list[tuple(double)] or ndarray[tuple(double)], optional) – A list of tuples \((l, m)\) that select which modes to include in the waveform calculation

  • return_list (bool, optional) – True returns the plus and cross polarizations of the waveform as separate ndarrays

  • include_negative_m (bool, optional) – True returns the sum of the positive and negative m-modes for each mode in select_modes

Return type:

2d-array[complex] or list[two 2d-arrays[double]]

harmonics_data(M, mu, a, p0, e0, x0, dist, qS, phiS, qK, phiK, Phi_phi0, Phi_r0, Phi_theta0, dt=10.0, T=1.0, **kwargs)[source]#

Calculate the amplitudes and phases of the spin-weighted spherical harmonic (l, m)-modes of the gravitational wave strain. The function returns mode data for both positive and negative m-modes. Given a list of modes \([(l_1, m_1), (l_2, m_2), \dots , (l_N, m_N)]\) the function returns data in the order \([(l_1, m_1), (l_1, -m_1), (l_2, m_2), (l_2, -m_2), \dots, (l_N, m_N), (l_N, -m_N)]\).

Parameters:

  • M (double) – mass (in solar masses) of the massive black hole

  • mu (double) – mass (in solar masses) of the (smaller) stellar-mass compact object

  • a (double) – dimensionless black hole spin

  • p0 (double) – initial semi-latus rectum

  • e0 (double) – initial orbital eccentricity

  • x0 (double) – intial cosine of the orbital inclination

  • dist (double) – luminosity distance to the source in Gpc

  • qS (double) – polar angle of the source’s sky location

  • phiS (double) – azimuthal angle of the source’s sky location

  • qK (double) – polar angle of the Kerr spin vector

  • phiK (double) – azimuthal angle of the Kerr spin vector

  • Phi_phi0 (double) – Initial azimuthal position of the small compact object

  • Phi_r0 (double) – Phase describing the initial radial position and velocity of the small compact object

  • Phi_theta0 (double) – Phase describing the initial polar position and velocity of the small compact object

  • dt (double, optional) – Spacing of time samples in seconds

  • T (double, optional) – Duration of the waveform in years

  • pad_output (bool, optional) – True returns the waveform for the full duration T years even if the system merges before T years has elasped

  • select_modes (list[tuple(double)] or ndarray[tuple(double)], optional) – A list of tuples \((l, m)\) that select which modes to include in the waveform calculation. Only positive m-modes are used.

  • return_list (bool, optional) – True returns the plus and cross polarizations of the waveform as separate ndarrays

Return type:

2d-array[complex] or list[two 2d-arrays[double]]

select_modes(M, mu, a, r0, qS, phiS, qK, phiK, Phi_phi0, dt=10.0, T=1.0, **kwargs)#

Selects the harmonic modes that are used for calculating the waveform

Parameters:

  • M (double) – mass (in solar masses) of the massive black hole

  • mu (double) – mass (in solar masses) of the (smaller) stellar-mass compact object

  • a (double) – dimensionless black hole spin

  • r0 (double) – initial orbital separation of the two objects

  • qS (double) – polar angle of the source’s sky location

  • phiS (double) – azimuthal angle of the source’s sky location

  • qK (double) – polar angle of the Kerr spin vector

  • phiK (double) – azimuthal angle of the Kerr spin vector

  • Phi_phi0 (double) – Initial azimuthal position of the small compact object

  • T (double, optional) – Duration of the waveform in years

Return type:

1d-array[tuples(doubles)]

source_frame(M, mu, a, r0, theta, phi, Phi_phi0, dt=10.0, T=1.0, **kwargs)#

Calculate the scaled gravitational wave strain \(r\times h/\mu\) in the source frame

Parameters:

  • M (double) – mass (in solar masses) of the massive black hole

  • mu (double) – mass (in solar masses) of the (smaller) stellar-mass compact object

  • a (double) – dimensionless black hole spin

  • r0 (double) – initial radial separation

  • theta (double) – polar angle of the observor with respect to the Kerr spin vector

  • phi (double) – azimuthal angle of the observor with respect to the Kerr spin vector

  • Phi_phi0 (double) – Initial azimuthal position of the small compact object

  • dt (double, optional) – Spacing of time samples in seconds. Default is 10 seconds.

  • T (double, optional) – Duration of the waveform in years. Default is 1 year.

  • pad_output (bool, optional) – True returns the waveform for the full duration T years even if the system merges before T years has elasped

  • select_modes (list[tuple(double)] or ndarray[tuple(double)], optional) – A list of tuples \((l, m)\) that select which modes to include in the waveform calculation

  • return_list (bool, optional) – True returns the plus and cross polarizations of the waveform as separate ndarrays

  • include_negative_m (bool, optional) – True returns the sum of the positive and negative m-modes for each mode in select_modes

Return type:

1d-array[complex] or list[two 1d-arrays[double]]

class bhpwave.waveform.KerrCircularFrequencyWaveform(trajectory_data=None, harmonic_data=None, num_threads=None)[source]#

Bases: object

Class that generates the gravitational waveform produced by an extreme-mass-ratio inspiral in the frequency domain using the adiabatic approximation from black hole perturbation theory and the self-force formalism. By default, the waveform is generated in the solar system barycenter frame.

Waveform generation is limited to quasi-circular inspirals in Kerr spacetime, but the generator mirrors the generic parametrization used in other EMRI waveform generators (e.g., https://bhptoolkit.org/FastEMRIWaveforms/html/user/main.html)

Parameters:

  • trajectory_data (TrajectoryData or None, optional) – a TrajectoryData class which holds interpolants of the relevant trajectory data

  • harmonic_data (HarmonicAmplitudes or None, optional) – a HarmonicAmplitudes class which holds interpolants of the harmonic mode amplitudes

  • num_threads (int or None, optional) – the number of threads used to evaluate the waveform

select_modes(M, mu, a, r0, qS, phiS, qK, phiK, Phi_phi0, T=1.0, **kwargs)[source]#

Selects the harmonic modes that are used for calculating the waveform

Parameters:

  • M (double) – mass (in solar masses) of the massive black hole

  • mu (double) – mass (in solar masses) of the (smaller) stellar-mass compact object

  • a (double) – dimensionless black hole spin

  • r0 (double) – initial orbital separation of the two objects

  • qS (double) – polar angle of the source’s sky location

  • phiS (double) – azimuthal angle of the source’s sky location

  • qK (double) – polar angle of the Kerr spin vector

  • phiK (double) – azimuthal angle of the Kerr spin vector

  • Phi_phi0 (double) – Initial azimuthal position of the small compact object

  • T (double, optional) – Duration of the waveform in years

Return type:

1d-array[tuples(doubles)]

__call__(M, mu, a, r0, dist, qS, phiS, qK, phiK, Phi_phi0, dt=10.0, T=1.0, df=None, fmax=None, frequencies=None, **kwargs)[source]#

Calculate the Fourier transform of the plus and cross polarizations of the gravitational wave strain

Parameters:

  • M (double) – mass (in solar masses) of the massive black hole

  • mu (double) – mass (in solar masses) of the (smaller) stellar-mass compact object

  • a (double) – dimensionless black hole spin

  • r0 (double) – initial orbital separation of the two objects

  • dist (double) – luminosity distance to the source in Gpc

  • qS (double) – polar angle of the source’s sky location

  • phiS (double) – azimuthal angle of the source’s sky location

  • qK (double) – polar angle of the Kerr spin vector

  • phiK (double) – azimuthal angle of the Kerr spin vector

  • Phi_phi0 (double) – Initial azimuthal position of the small compact object

  • dt (double, optional) – Spacing of time samples for corresponding time-domain waveform in seconds. Default is 10. This option is only considered if df, fmax, and frequencies are None.

  • T (double, optional) – Duration of the observed waveform in years. Default is 1. If None, T is set to be 1/df.

  • df (double, optional) – Spacing of the frequency samples in Hertz. Default is None. If df is None, then one must specify values for frequencies or T.

  • fmax (double, optional) – Maximum sampled frequency in Hertz. Default is None. If fmax is None, then one must specify values for frequencies or dt.

  • frequencies (list[double] or ndarray[double], optional) – Array of frequency samples in Hertz. Default is None. This option overrides df and fmax.

  • pad_output (bool, optional) – True returns the waveform for the full duration T years even if the system merges before T years has elasped

  • select_modes (list[tuple(double)] or ndarray[tuple(double)], optional) – A list of tuples \((l, m)\) that select which modes to include in the waveform calculation

  • return_list (bool, optional) – True returns the plus and cross polarizations of the waveform as separate ndarrays

  • include_negative_m (bool, optional) – True returns the sum of the positive and negative m-modes for each mode in select_modes

  • eps (double, optional) – The tolerance to include modes that are subdominant to the power in the (2,2)-mode.

  • max_samples (double, optional) –

Return type:

list[two 1d-arrays[double]]

harmonics(M, mu, a, r0, dist, qS, phiS, qK, phiK, Phi_phi0, dt=10.0, T=1.0, df=None, fmax=None, frequencies=None, **kwargs)[source]#

Calculate the spin-weighted spherical harmonic \((l, m)\)-modes of the Fourier transform of the plus and cross polarizations of the gravitational wave strain

Parameters:

  • M (double) – mass (in solar masses) of the massive black hole

  • mu (double) – mass (in solar masses) of the (smaller) stellar-mass compact object

  • a (double) – dimensionless black hole spin

  • r0 (double) – initial orbital separation of the two objects

  • dist (double) – luminosity distance to the source in Gpc

  • qS (double) – polar angle of the source’s sky location

  • phiS (double) – azimuthal angle of the source’s sky location

  • qK (double) – polar angle of the Kerr spin vector

  • phiK (double) – azimuthal angle of the Kerr spin vector

  • Phi_phi0 (double) – Initial azimuthal position of the small compact object

  • dt (double, optional) – Spacing of time samples for corresponding time-domain waveform in seconds. Default is 10. This option is only considered if df, fmax, and frequencies are None.

  • T (double, optional) – Duration of the observed waveform in years. Default is 1. If None, T is set to be 1/df.

  • df (double, optional) – Spacing of the frequency samples in Hertz. Default is None. If df is None, then one must specify values for frequencies or T.

  • fmax (double, optional) – Maximum sampled frequency in Hertz. Default is None. If fmax is None, then one must specify values for frequencies or dt.

  • frequencies (list[double] or ndarray[double], optional) – Array of frequency samples in Hertz. Default is None. This option overrides df and fmax.

  • pad_output (bool, optional) – True returns the waveform for the full duration T years even if the system merges before T years has elasped

  • select_modes (list[tuple(double)] or ndarray[tuple(double)], optional) – A list of tuples \((l, m)\) that select which modes to include in the waveform calculation

  • return_list (bool, optional) – True returns the plus and cross polarizations of the waveform as separate ndarrays

  • include_negative_m (bool, optional) – True returns the sum of the positive and negative m-modes for each mode in select_modes

Return type:

list[two 2d-arrays[double]]

harmonics_data(M, mu, a, r0, dist, qS, phiS, qK, phiK, Phi_phi0, dt=10.0, T=1.0, df=None, fmax=None, frequencies=None, **kwargs)[source]#

Calculate the phases and amplitudes for the spin-weighted spherical harmonic \((l, m)\)-modes of the Fourier transform of the plus and cross polarizations of the gravitational wave strain. The function returns mode data for both positive and negative m-modes. Given a list of modes \([(l_1, m_1), (l_2, m_2), \dots , (l_N, m_N)]\) the function returns data in the order \([(l_1, m_1), (l_1, -m_1), (l_2, m_2), (l_2, -m_2), \dots, (l_N, m_N), (l_N, -m_N)]\).

Parameters:

  • M (double) – mass (in solar masses) of the massive black hole

  • mu (double) – mass (in solar masses) of the (smaller) stellar-mass compact object

  • a (double) – dimensionless black hole spin

  • r0 (double) – initial orbital separation of the two objects

  • dist (double) – luminosity distance to the source in Gpc

  • qS (double) – polar angle of the source’s sky location

  • phiS (double) – azimuthal angle of the source’s sky location

  • qK (double) – polar angle of the Kerr spin vector

  • phiK (double) – azimuthal angle of the Kerr spin vector

  • Phi_phi0 (double) – Initial azimuthal position of the small compact object

  • dt (double, optional) – Spacing of time samples for corresponding time-domain waveform in seconds. Default is 10. This option is only considered if df, fmax, and frequencies are None.

  • T (double, optional) – Duration of the observed waveform in years. Default is 1. If None, T is set to be 1/df.

  • df (double, optional) – Spacing of the frequency samples in Hertz. Default is None. If df is None, then one must specify values for frequencies or T.

  • fmax (double, optional) – Maximum sampled frequency in Hertz. Default is None. If fmax is None, then one must specify values for frequencies or dt.

  • frequencies (list[double] or ndarray[double], optional) – Array of frequency samples in Hertz. Default is None. This option overrides df and fmax.

  • pad_output (bool, optional) – True returns the waveform for the full duration T years even if the system merges before T years has elasped

  • select_modes (list[tuple(double)] or ndarray[tuple(double)], optional) – A list of tuples \((l, m)\) that select which modes to include in the waveform calculation

  • return_list (bool, optional) – True returns the plus and cross polarizations of the waveform as separate ndarrays

  • include_negative_m (bool, optional) – True returns the sum of the positive and negative m-modes for each mode in select_modes

Return type:

list[two 2d-arrays[double]]

source_frame(M, mu, a, r0, theta, phi, Phi_phi0, dt=10.0, T=1.0, df=None, fmax=None, frequencies=None, **kwargs)[source]#

Calculate the Fourier transform of the plus and cross polarizations of the scaled gravitational wave strain \(r\times h/\mu\) in the source frame

Parameters:

  • M (double) – mass (in solar masses) of the massive black hole

  • mu (double) – mass (in solar masses) of the (smaller) stellar-mass compact object

  • a (double) – dimensionless black hole spin

  • r0 (double) – initial radial separation

  • theta (double) – polar angle of the observor with respect to the Kerr spin vector

  • phi (double) – azimuthal angle of the observor with respect to the Kerr spin vector

  • Phi_phi0 (double) – Initial azimuthal position of the small compact object

  • dt (double, optional) – Spacing of time samples for corresponding time-domain waveform in seconds. Default is 10. If None, dt is set to be 1/(2 fmax).

  • T (double, optional) – Duration of the observed waveform in years. Default is 1. If None, T is set to be 1/df.

  • df (double, optional) – Spacing of the frequency samples in Hertz. Default is None. If df is None, then one must specify values for frequencies or T.

  • fmax (double, optional) – Maximum sampled frequency in Hertz. Default is None. If fmax is None, then one must specify values for frequencies or dt.

  • frequencies (list[double] or ndarray[double], optional) – Array of frequency samples in Hertz. Default is None. This option overrides df and fmax.

  • pad_output (bool, optional) – True returns the waveform for the full duration T years even if the system merges before T years has elasped

  • select_modes (list[tuple(double)] or ndarray[tuple(double)], optional) – A list of tuples \((l, m)\) that select which modes to include in the waveform calculation

  • return_list (bool, optional) – True returns the plus and cross polarizations of the waveform as separate ndarrays

Return type:

list[two 1d-arrays[double]]

bhpwave.waveform.sort_frequency_and_time_sampling_arguments(df, fmax, frequencies, dt, T)[source]#
class bhpwave.waveform.KerrFrequencyWaveform(trajectory_data=None, harmonic_data=None, num_threads=None)[source]#

Bases: KerrCircularFrequencyWaveform

Class that generates the gravitational waveform produced by an extreme-mass-ratio inspiral in the frequency domain using the adiabatic approximation from black hole perturbation theory and the self-force formalism. By default, the waveform is generated in the solar system barycenter frame.

Waveform generation is limited to quasi-circular inspirals in Kerr spacetime, but the generator mirrors the generic parametrization used in other EMRI waveform generators (e.g., https://bhptoolkit.org/FastEMRIWaveforms/html/user/main.html)

Parameters:

  • trajectory_data (TrajectoryData or None, optional) – a TrajectoryData class which holds interpolants of the relevant trajectory data

  • harmonic_data (HarmonicAmplitudes or None, optional) – a HarmonicAmplitudes class which holds interpolants of the harmonic mode amplitudes

  • num_threads (int or None, optional) – the number of threads used to evaluate the waveform

__call__(M, mu, a, p0, e0, x0, dist, qS, phiS, qK, phiK, Phi_phi0, Phi_r0, Phi_theta0, dt=10.0, T=1.0, df=None, fmax=None, frequencies=None, **kwargs)[source]#

Calculate the Fourier transform of the plus and cross polarizations of the gravitational wave strain

Parameters:

  • M (double) – mass (in solar masses) of the massive black hole

  • mu (double) – mass (in solar masses) of the (smaller) stellar-mass compact object

  • a (double) – dimensionless black hole spin

  • p0 (double) – initial semi-latus rectum

  • e0 (double) – initial orbital eccentricity

  • x0 (double) – intial cosine of the orbital inclination

  • dist (double) – luminosity distance to the source in Gpc

  • qS (double) – polar angle of the source’s sky location

  • phiS (double) – azimuthal angle of the source’s sky location

  • qK (double) – polar angle of the Kerr spin vector

  • phiK (double) – azimuthal angle of the Kerr spin vector

  • Phi_phi0 (double) – Initial azimuthal position of the small compact object

  • Phi_r0 (double) – Phase describing the initial radial position and velocity of the small compact object

  • Phi_theta0 (double) – Phase describing the initial polar position and velocity of the small compact object

  • dt (double, optional) – Spacing of time samples for corresponding time-domain waveform in seconds. Default is 10. If None, dt is set to be 1/(2 fmax).

  • T (double, optional) – Duration of the observed waveform in years. Default is 1. If None, T is set to be 1/df.

  • df (double, optional) – Spacing of the frequency samples in Hertz. Default is None. If df is None, then one must specify values for frequencies or T.

  • fmax (double, optional) – Maximum sampled frequency in Hertz. Default is None. If fmax is None, then one must specify values for frequencies or dt.

  • frequencies (list[double] or ndarray[double], optional) – Array of frequency samples in Hertz. Default is None. This option overrides df and fmax.

  • pad_output (bool, optional) – True returns the waveform for the full duration T years even if the system merges before T years has elasped

  • select_modes (list[tuple(double)] or ndarray[tuple(double)], optional) – A list of tuples \((l, m)\) that select which modes to include in the waveform calculation

  • return_list (bool, optional) – True returns the plus and cross polarizations of the waveform as separate ndarrays

  • include_negative_m (bool, optional) – True returns the sum of the positive and negative m-modes for each mode in select_modes

Return type:

list[two 1d-arrays[double]]

harmonics(M, mu, a, p0, e0, x0, dist, qS, phiS, qK, phiK, Phi_phi0, Phi_r0, Phi_theta0, dt=10.0, T=1.0, df=None, fmax=None, frequencies=None, **kwargs)[source]#

Calculate the spin-weighted spherical harmonic \((l, m)\)-modes of the Fourier transform of the plus and cross polarizations of the gravitational wave strain

Parameters:

  • M (double) – mass (in solar masses) of the massive black hole

  • mu (double) – mass (in solar masses) of the (smaller) stellar-mass compact object

  • a (double) – dimensionless black hole spin

  • p0 (double) – initial semi-latus rectum

  • e0 (double) – initial orbital eccentricity

  • x0 (double) – intial cosine of the orbital inclination

  • dist (double) – luminosity distance to the source in Gpc

  • qS (double) – polar angle of the source’s sky location

  • phiS (double) – azimuthal angle of the source’s sky location

  • qK (double) – polar angle of the Kerr spin vector

  • phiK (double) – azimuthal angle of the Kerr spin vector

  • Phi_phi0 (double) – Initial azimuthal position of the small compact object

  • Phi_r0 (double) – Phase describing the initial radial position and velocity of the small compact object

  • Phi_theta0 (double) – Phase describing the initial polar position and velocity of the small compact object

  • dt (double, optional) – Spacing of time samples for corresponding time-domain waveform in seconds. Default is 10. If None, dt is set to be 1/(2 fmax).

  • T (double, optional) – Duration of the observed waveform in years. Default is 1. If None, T is set to be 1/df.

  • df (double, optional) – Spacing of the frequency samples in Hertz. Default is None. If df is None, then one must specify values for frequencies or T.

  • fmax (double, optional) – Maximum sampled frequency in Hertz. Default is None. If fmax is None, then one must specify values for frequencies or dt.

  • frequencies (list[double] or ndarray[double], optional) – Array of frequency samples in Hertz. Default is None. This option overrides df and fmax.

  • pad_output (bool, optional) – True returns the waveform for the full duration T years even if the system merges before T years has elasped

  • select_modes (list[tuple(double)] or ndarray[tuple(double)], optional) – A list of tuples \((l, m)\) that select which modes to include in the waveform calculation

  • return_list (bool, optional) – True returns the plus and cross polarizations of the waveform as separate ndarrays

  • include_negative_m (bool, optional) – True returns the sum of the positive and negative m-modes for each mode in select_modes

Return type:

list[two 2d-arrays[double]]

harmonics_data(M, mu, a, p0, e0, x0, dist, qS, phiS, qK, phiK, Phi_phi0, Phi_r0, Phi_theta0, dt=10.0, T=1.0, df=None, fmax=None, frequencies=None, **kwargs)[source]#

Calculate the phases and amplitudes for spin-weighted spherical harmonic \((l, m)\)-modes of the Fourier transform of the plus and cross polarizations of the gravitational wave strain

Parameters:

  • M (double) – mass (in solar masses) of the massive black hole

  • mu (double) – mass (in solar masses) of the (smaller) stellar-mass compact object

  • a (double) – dimensionless black hole spin

  • p0 (double) – initial semi-latus rectum

  • e0 (double) – initial orbital eccentricity

  • x0 (double) – intial cosine of the orbital inclination

  • dist (double) – luminosity distance to the source in Gpc

  • qS (double) – polar angle of the source’s sky location

  • phiS (double) – azimuthal angle of the source’s sky location

  • qK (double) – polar angle of the Kerr spin vector

  • phiK (double) – azimuthal angle of the Kerr spin vector

  • Phi_phi0 (double) – Initial azimuthal position of the small compact object

  • Phi_r0 (double) – Phase describing the initial radial position and velocity of the small compact object

  • Phi_theta0 (double) – Phase describing the initial polar position and velocity of the small compact object

  • dt (double, optional) – Spacing of time samples for corresponding time-domain waveform in seconds. Default is 10. If None, dt is set to be 1/(2 fmax).

  • T (double, optional) – Duration of the observed waveform in years. Default is 1. If None, T is set to be 1/df.

  • df (double, optional) – Spacing of the frequency samples in Hertz. Default is None. If df is None, then one must specify values for frequencies or T.

  • fmax (double, optional) – Maximum sampled frequency in Hertz. Default is None. If fmax is None, then one must specify values for frequencies or dt.

  • frequencies (list[double] or ndarray[double], optional) – Array of frequency samples in Hertz. Default is None. This option overrides df and fmax.

  • pad_output (bool, optional) – True returns the waveform for the full duration T years even if the system merges before T years has elasped

  • select_modes (list[tuple(double)] or ndarray[tuple(double)], optional) – A list of tuples \((l, m)\) that select which modes to include in the waveform calculation

  • return_list (bool, optional) – True returns the plus and cross polarizations of the waveform as separate ndarrays

  • include_negative_m (bool, optional) – True returns the sum of the positive and negative m-modes for each mode in select_modes

Return type:

list[two 2d-arrays[double]]

select_modes(M, mu, a, r0, qS, phiS, qK, phiK, Phi_phi0, T=1.0, **kwargs)#

Selects the harmonic modes that are used for calculating the waveform

Parameters:

  • M (double) – mass (in solar masses) of the massive black hole

  • mu (double) – mass (in solar masses) of the (smaller) stellar-mass compact object

  • a (double) – dimensionless black hole spin

  • r0 (double) – initial orbital separation of the two objects

  • qS (double) – polar angle of the source’s sky location

  • phiS (double) – azimuthal angle of the source’s sky location

  • qK (double) – polar angle of the Kerr spin vector

  • phiK (double) – azimuthal angle of the Kerr spin vector

  • Phi_phi0 (double) – Initial azimuthal position of the small compact object

  • T (double, optional) – Duration of the waveform in years

Return type:

1d-array[tuples(doubles)]

source_frame(M, mu, a, r0, theta, phi, Phi_phi0, dt=10.0, T=1.0, df=None, fmax=None, frequencies=None, **kwargs)#

Calculate the Fourier transform of the plus and cross polarizations of the scaled gravitational wave strain \(r\times h/\mu\) in the source frame

Parameters:

  • M (double) – mass (in solar masses) of the massive black hole

  • mu (double) – mass (in solar masses) of the (smaller) stellar-mass compact object

  • a (double) – dimensionless black hole spin

  • r0 (double) – initial radial separation

  • theta (double) – polar angle of the observor with respect to the Kerr spin vector

  • phi (double) – azimuthal angle of the observor with respect to the Kerr spin vector

  • Phi_phi0 (double) – Initial azimuthal position of the small compact object

  • dt (double, optional) – Spacing of time samples for corresponding time-domain waveform in seconds. Default is 10. If None, dt is set to be 1/(2 fmax).

  • T (double, optional) – Duration of the observed waveform in years. Default is 1. If None, T is set to be 1/df.

  • df (double, optional) – Spacing of the frequency samples in Hertz. Default is None. If df is None, then one must specify values for frequencies or T.

  • fmax (double, optional) – Maximum sampled frequency in Hertz. Default is None. If fmax is None, then one must specify values for frequencies or dt.

  • frequencies (list[double] or ndarray[double], optional) – Array of frequency samples in Hertz. Default is None. This option overrides df and fmax.

  • pad_output (bool, optional) – True returns the waveform for the full duration T years even if the system merges before T years has elasped

  • select_modes (list[tuple(double)] or ndarray[tuple(double)], optional) – A list of tuples \((l, m)\) that select which modes to include in the waveform calculation

  • return_list (bool, optional) – True returns the plus and cross polarizations of the waveform as separate ndarrays

Return type:

list[two 1d-arrays[double]]

bhpwave.waveform.source_angles(qS, phiS, qK, phiK)[source]#

Calculate the sky location \((\theta, \phi)\) of the observor in the source frame using the sky location and orientation of the source in the SSB frame

Parameters:

  • qS (double) – polar angle of the source’s sky location

  • phiS (double) – azimuthal angle of the source’s sky location

  • qK (double) – polar angle of the Kerr spin vector

  • phiK (double) – azimuthal angle of the Kerr spin vector

Return type:

tuple(double, double)

bhpwave.waveform.polarization(qS, phiS, qK, phiK)[source]#

Calculate the rotation of polarization angle \(e^{i\psi}\) due to transforming from the plus and cross polarizations in the source frame to the plus and cross polarization in the SSB frame.

Parameters:

  • qS (double) – polar angle of the source’s sky location

  • phiS (double) – azimuthal angle of the source’s sky location

  • qK (double) – polar angle of the Kerr spin vector

  • phiK (double) – azimuthal angle of the Kerr spin vector

Return type:

complex

bhpwave.waveform.solar_mass_to_seconds(mass)[source]#

Converts units of solar mass in \(G=c=1\) convention to units of seconds in the MKS convention

Parameters:

mass (double) – mass in units of solar masses

Return type:

double

bhpwave.waveform.seconds_to_solar_mass(time)[source]#

Converts units of seconds in the MKS convention to units of solar mass in \(G=c=1\) convention

Parameters:

time (double) – time in units of seconds

Return type:

double

bhpwave.waveform.solar_mass_to_meters(mass)[source]#

Converts units of solar mass in \(G=c=1\) convention to units of meters in the MKS convention

Parameters:

mass (double) – mass in units of solar masses

Return type:

double

bhpwave.waveform.solar_mass_to_parsecs(mass)[source]#

Converts units of solar mass in \(G=c=1\) convention to units of parsecs in the MKS convention

Parameters:

mass (double) – mass in units of solar masses

Return type:

double

bhpwave.waveform.parsecs_to_solar_mass(length)[source]#

Converts units of parsecs in the MKS convention to units of solar mass in \(G=c=1\) convention

Parameters:

length (double) – length in units of solar masses

Return type:

double

bhpwave.waveform.seconds_to_years(time)[source]#

Converts units of seconds to units of sidereal years

Parameters:

time (double) – time in seconds

Return type:

double

bhpwave.waveform.years_to_seconds(time)[source]#

Converts units of sidereal years to units of seconds

Parameters:

time (double) – time in sidereal years

Return type:

double

bhpwave.waveform.scaled_amplitude(mu, dist)[source]#

Gives the overall scaling of the waveform amplitude \(\mu/D_L\) for a binary with small mass \(\mu\) and an observer at distance \(D_L\)

Parameters:

  • mu (double) – mass of the small body in solar masses

  • dist (double) – distance between the binary and observor in Gpc

Return type:

double

bhpwave.waveform.frequencies(dt, T)[source]#

Frequency sampling of the frequency-domain gravitational wave signal for a given time step and signal duration

Parameters:

  • dt (double) – time step in seconds

  • T (double) – signal duration in years

Return type:

array[double]