Extending GBGPU Waveforms

The base class gbgpu.gbgpu.InheritGBGPU can be inherited in order to build other waveforms in the model of FastGB. To do this, there are required methods that need to be added to the new waveform class. They are described in the Abstract Base Class gbgpu.gbgpu.InheritGBGPU. After the base class, waveform models that have already been extended beyond the base are described.

InheritGBGPU base class

class gbgpu.gbgpu.InheritGBGPU(orbits: Orbits = None, use_gpu=False)

Bases: GBGPU, ABC

Inherit this class to expand on GBGPU waveforms.

The required methods to be added are shown below.

classmethod prepare_additional_args(*args)

Prepare the arguments special to this class

This function must take in the extra args input into GBGPU.run_wave() and transform them as needed to input into the rest of the code. If using GPUs, this is where the parameters are copied to GPUs.

Parameters:

*args (tuple) – Any additional args to be dealt with.

Returns:

New args. In the rest of the code this is add_args.

Return type:

Tuple

classmethod special_get_N(amp, f0, T, *args, oversample=1)

Determine proper sampling rate in time domain for slow-part.

Parameters:

  • amp (double or 1D double np.ndarray) – Amplitude parameter.

  • f0 (double or 1D double np.ndarray) – Initial frequency of gravitational wave in Hz.

  • T (double) – Observation time in seconds.

  • *args (tuple) – Args input for beyond-GBGPU functionality.

  • oversample (int, optional) – Oversampling factor compared to the determined N value. Final N will be oversample * N. This is only used if N is not provided. Default is 1.

Returns:

Number of time-domain points recommended for each binary.

Return type:

1D int32 xp.ndarray

shift_frequency(fi, xi, *args)

Shift the evolution of the frequency in the slow part

Parameters:

  • fi (3D double xp.ndarray) – Instantaneous frequencies of the wave before applying third-body effect at each spacecraft as a function of time. The shape is (num binaries, 3 spacecraft, N).

  • xi (3D double xp.ndarray) – Time at each spacecraft. The shape is (num binaries, 3 spacecraft, N).

  • *args (tuple) – Args returned from prepare_additional_args().

Returns:

Updated frequencies with third-body effect.

Return type:

3D double xp.ndarray

add_to_argS(argS, f0, fdot, fddot, xi, *args)

Update argS in FastGB formalism for third-body effect

argS is an effective phase that goes into kdotP in the construction of the slow part of the waveform. kdotP is then included directly in the transfer function. See gbgpu.gbgpu.GBGPU._construct_slow_part() for the use of argS in the larger code.

Parameters:

  • argS (3D double xp.ndarray) – Special phase evaluation that goes into kdotP. Shape is (num binaries, 3 spacecraft, N).

  • f0 (1D double np.ndarray) – Initial frequency of gravitational wave in Hz.

  • fdot (1D double np.ndarray) – Initial time derivative of the frequency given as Hz/s.

  • fddot (1D double np.ndarray) – Initial second derivative with respect to time of the frequency given in Hz/s^2.

  • xi (3D double xp.ndarray) – Time at each spacecraft. The shape is (num binaries, 3 spacecraft, N).

  • T (double) – Observation time in seconds.

  • *args (tuple) – Args returned from prepare_additional_args().

Returns:

Updated argS with third-body effect

Return type:

3D double xp.ndarray

Third-body inclusion

gbgpu.gbgpu.GBGPU has been extended to include a third-body in long orbit around the inner binary. This waveform was first built in arXiv:1806.00500. It was more recently used and adapted into this code base for # TODO: add arxiv. Please cite both papers, as well as the base FastGB papers, if you use this waveform.

Third-body waveform

class gbgpu.thirdbody.GBGPUThirdBody(orbits: Orbits = None, use_gpu=False)

Bases: InheritGBGPU

Build the effect of a third body into Galactic binary waveforms.

The third-body components are originally by Travis Robson for the paper arXiv:1806.00500.

Parameters:

use_gpu (bool, optional) – If True, run on GPUs. Default is False.

Attributes:

property citation

Get citations for this class

prepare_additional_args(A2, varpi, e2, P2, T2)

Prepare the arguments special to this class

Parameters:

  • A2 (double or 1D double np.ndarray) – Special amplitude parameter related to the line-of-site velocity for the third body orbit as defined in the paper given in the description above.

  • varpi (double or 1D double np.ndarray) – Special angular frequency parameter related to the line-of-site velocity for the third body orbit as defined in the paper given in the description above.

  • e2 (double or 1D double np.ndarray) – Eccentricity of the third body orbit.

  • P2 (double or 1D double np.ndarray) – Period of the third body orbit in Years.

  • T2 (double or 1D double np.ndarray) – Time of pericenter passage of the third body in Years. This parameter is effectively a constant of integration.

Returns:

(A2, varpi, e2, n2, T2) adjusted for GPU usage if necessary.

(\(n_2=\frac{2\pi}{P_2}\) is the angular frequency of the orbit.)

Return type:

Tuple

special_get_N(amp, f0, T, A2, varpi, e2, P2, T2, oversample=1)

Determine proper sampling rate in time domain for slow-part.

Parameters:

  • amp (double or 1D double np.ndarray) – Amplitude parameter.

  • f0 (double or 1D double np.ndarray) – Initial frequency of gravitational wave in Hz.

  • T (double) – Observation time in seconds.

  • A2 (double or 1D double np.ndarray) – Special amplitude parameter related to the line-of-site velocity for the third body orbit as defined in the paper given in the description above. (Not needed in this function)

  • varpi (double or 1D double np.ndarray) – Special angular frequency parameter related to the line-of-site velocity for the third body orbit as defined in the paper given in the description above. (Not needed in this function)

  • e2 (double or 1D double np.ndarray) – Eccentricity of the third body orbit. (Not needed in this function)

  • P2 (double or 1D double np.ndarray) – Period of the third body orbit in Years.

  • T2 (double or 1D double np.ndarray) – Time of pericenter passage of the third body in Years. This parameter is effectively a constant of integration. (Not needed in this function)

Returns:

Number of time-domain points recommended for each binary.

Return type:

1D int32 xp.ndarray

Raises:

AssertionError – Shapes of inputs are wrong.

shift_frequency(fi, xi, A2, varpi, e2, n2, T2)

Shift the evolution of the frequency in the slow part

Parameters:

  • fi (3D double xp.ndarray) – Instantaneous frequencies of the wave before applying third-body effect at each spacecraft as a function of time. The shape is (num binaries, 3 spacecraft, N).

  • xi (3D double xp.ndarray) – Time at each spacecraft. The shape is (num binaries, 3 spacecraft, N).

  • A2 (1D double np.ndarray) – Special amplitude parameter related to the line-of-site velocity for the third body orbit as defined in the paper given in the description above.

  • varpi (1D double np.ndarray) – Special angular frequency parameter related to the line-of-site velocity for the third body orbit as defined in the paper given in the description above.

  • e2 (1D double np.ndarray) – Eccentricity of the third body orbit.

  • n2 (1D double np.ndarray) – Angular frequency of the third body orbit in per seconds.

  • T2 (1D double np.ndarray) – Time of pericenter passage of the third body in seconds. This parameter is effectively a constant of integration.

Returns:

Updated frequencies with third-body effect.

Return type:

3D double xp.ndarray

add_to_argS(argS, f0, fdot, fddot, xi, A2, varpi, e2, n2, T2)

Update argS in FastGB formalism for third-body effect

argS is an effective phase that goes into kdotP in the construction of the slow part of the waveform. kdotP is then included directly in the transfer function. See gbgpu.gbgpu.GBGPU._construct_slow_part() for the use of argS in the larger code.

Parameters:

  • argS (3D double xp.ndarray) – Special phase evaluation that goes into kdotP. Shape is (num binaries, 3 spacecraft, N).

  • f0 (1D double np.ndarray) – Initial frequency of gravitational wave in Hz.

  • fdot (1D double np.ndarray) – Initial time derivative of the frequency given as Hz/s.

  • fddot (1D double np.ndarray) – Initial second derivative with respect to time of the frequency given in Hz/s^2.

  • xi (3D double xp.ndarray) – Time at each spacecraft. The shape is (num binaries, 3 spacecraft, N).

  • T (double) – Observation time in seconds.

  • A2 (1D double np.ndarray) – Special amplitude parameter related to the line-of-site velocity for the third body orbit as defined in the paper given in the description above.

  • varpi (1D double np.ndarray) – Special angular frequency parameter related to the line-of-site velocity for the third body orbit as defined in the paper given in the description above.

  • e2 (1D double np.ndarray) – Eccentricity of the third body orbit.

  • n2 (1D double np.ndarray) – Angular frequency of the third body orbit in per seconds.

  • T2 (1D double np.ndarray) – Time of pericenter passage of the third body in seconds. This parameter is effectively a constant of integration.

Returns:

Updated argS with third-body effect

Return type:

3D double xp.ndarray

get_u(l, e)

Invert Kepler’s Equation to get eccentric anomaly

Invert Kepler’s equation (\(l = u - e \sin{u}\)) using Mikkola’s method (1987) referenced in Tessmer & Gopakumar 2007.

Parameters:

  • l (1D double xp.ndarray) – Mean anomaly in radians.

  • e (1D double xp.ndarray) – Eccentricity.

Returns:

Eccentric anomaly

Return type:

3D double xp.ndarray

get_phi(t, T, e, n)

Get phi value for Line-of-sight velocity

See arXiv:1806.00500.

Parameters:

  • t (3D double xp.ndarray) – Time values to evaluate \(\bar{\phi}\).

  • T (1D double xp.ndarray) – Time of periastron passage (T2) in seconds.

  • e (1D double xp.ndarray) – Eccentricity.

  • n (1D double xp.ndarray) – Angular frequency of third-body orbit (n2) in per seconds.

Returns:

Phi values for line-of-sight velocities.

Return type:

3D double xp.ndarray

get_vLOS(t, A2, varpi, e2, n2, T2)

Calculate the line-of-site velocity

See equation 13 in arXiv:1806.00500.

Parameters:

  • t (3D double xp.ndarray) – Time values to evaluate \(\bar{\phi}\).

  • A2 (1D double np.ndarray) – Special amplitude parameter related to the line-of-site velocity for the third body orbit as defined in the paper given in the description above.

  • varpi (1D double np.ndarray) – Special angular frequency parameter related to the line-of-site velocity for the third body orbit as defined in the paper given in the description above.

  • e2 (1D double np.ndarray) – Eccentricity of the third body orbit.

  • n2 (1D double np.ndarray) – Angular frequency of the third body orbit in per seconds.

  • T2 (1D double np.ndarray) – Time of pericenter passage of the third body in seconds. This parameter is effectively a constant of integration.

Returns:

LOS velocity.

Return type:

3D double xp.ndarray

parab_step_ET(f0, fdot, fddot, A2, varpi, e2, n2, T2, t0, t0_old)

Determine phase difference caused by third-body

Takes a step in the integration of the orbit. In this setup, the calculations can all be done in parallel because we are just inverted Kepler’s equation rather than integrating an ODE where a serial operation is required. TODO: Check this again. Was checked in past.

Parameters:

  • f0 (1D double np.ndarray) – Initial frequency of gravitational wave in Hz.

  • fdot (1D double np.ndarray) – Initial time derivative of the frequency given as Hz/s.

  • fddot (1D double np.ndarray) – Initial second derivative with respect to time of the frequency given in Hz/s^2.

  • A2 (1D double np.ndarray) – Special amplitude parameter related to the line-of-site velocity for the third body orbit as defined in the paper given in the description above.

  • varpi (1D double np.ndarray) – Special angular frequency parameter related to the line-of-site velocity for the third body orbit as defined in the paper given in the description above.

  • e2 (1D double np.ndarray) – Eccentricity of the third body orbit.

  • n2 (1D double np.ndarray) – Angular frequency of the third body orbit in per seconds.

  • T2 (1D double np.ndarray) – Time of pericenter passage of the third body in seconds. This parameter is effectively a constant of integration.

  • t0 (3D double xp.ndarray) – Time values at end of step. Shape is (num binaries, 3 spacecraft, N - 1).

  • t0_old (3D double xp.ndarray) – Time values at start of step. Shape is (num binaries, 3 spacecraft, N - 1).

Returns:

Phase shifts due to third-body effect.

Return type:

3D double xp.ndarray

get_aLOS(A2, varpi, e2, P2, T2, t, eps=1e-09)

Get line-of-sight acceleration

Use central difference with LOS velocity to get LOS acceleration.

Parameters:

  • A2 (1D double np.ndarray) – Special amplitude parameter related to the line-of-site velocity for the third body orbit as defined in the paper given in the description above.

  • varpi (1D double np.ndarray) – Special angular frequency parameter related to the line-of-site velocity for the third body orbit as defined in the paper given in the description above.

  • e2 (1D double np.ndarray) – Eccentricity of the third body orbit.

  • n2 (1D double np.ndarray) – Angular frequency of the third body orbit in per seconds.

  • T2 (1D double np.ndarray) – Time of pericenter passage of the third body in seconds. This parameter is effectively a constant of integration.

  • t (3D double xp.ndarray) – Time values to evaluate. Shape is (num binaries, 3 spacecraft, N).

Returns:

LOS acceleration

Return type:

3D double xp.ndarray

get_f_derivatives(f0, fdot, fddot, A2, varpi, e2, P2, T2, t=None, eps=50000.0)

Get instantaneous frequency derivatives in third-body waveform

Computes the instantaneous frequency and frequency derivatives by calculating the effect of the third-body over the course of the orbit.

Central difference is used for both first and second derivatives.

Parameters:

  • f0 (1D double np.ndarray) – Initial frequency of gravitational wave in Hz.

  • fdot (1D double np.ndarray) – Initial time derivative of the frequency given as Hz/s.

  • fddot (1D double np.ndarray) – Initial second derivative with respect to time of the frequency given in Hz/s^2.

  • A2 (1D double np.ndarray) – Special amplitude parameter related to the line-of-site velocity for the third body orbit as defined in the paper given in the description above.

  • varpi (1D double np.ndarray) – Special angular frequency parameter related to the line-of-site velocity for the third body orbit as defined in the paper given in the description above.

  • e2 (1D double np.ndarray) – Eccentricity of the third body orbit.

  • n2 (1D double np.ndarray) – Angular frequency of the third body orbit in per seconds.

  • T2 (1D double np.ndarray) – Time of pericenter passage of the third body in seconds. This parameter is effectively a constant of integration.

  • t (3D double xp.ndarray, optional) – Time values for derivative calculation. Shape is (num binaries, anything, 3). The 3 here represents the times for each derivative computation. The derivatives are to be calucated at index 1. The step before (after) the time of the derivative (for central differencing) is at index 0 (1). In other words, the final dimension of t should be [t_deriv - eps, t_deriv, t_deriv + eps]. Default is None. If None, will fill [t_deriv - eps, t_deriv, t_deriv + eps] with t_deriv = 0.0 and eps will be the kwarg value.

  • eps (double) – Step size for central differencing. Only used if t is not provided.

Returns:

Phase shifts due to third-body effect.

Return type:

3D double xp.ndarray

Third-body utility functions

gbgpu.thirdbody.third_body_factors(M, mc, P2, e2, iota, Omega2, omega2, phi2, lam, beta, third_mass_unit='Mjup', third_period_unit='yrs')

Get A2,varpi,T2 from third-body parameters

Get all the third-body factors that go into the waveform computation: A2, varpi, and T2.

Parameters:

  • M (double or double np.ndarray) – Total mass of inner Galactic binary in Solar Masses.

  • mc (double or double np.ndarray) – Mass of third body in units of third_mass_unit kwarg.

  • P2 (double or double np.ndarray) – Orbital period of third body in units of third_period_unit kwarg.

  • e2 (double or double np.ndarray) – Orbital eccentricity of third body.

  • iota (double or double np.ndarray) – Orbital inclination of third body in radians. This orbital inclination is one of the three euler angles describing the rotation of the third-body orbital frame to ecliptic frame.

  • Omega2 (double or double np.ndarray) –

    The other two of three euler angles describing the third-body orbital frame rotation from the ecliptic frame. See the Figure 1 in arXiv:1806.00500.

  • omega2 (double or double np.ndarray) –

    The other two of three euler angles describing the third-body orbital frame rotation from the ecliptic frame. See the Figure 1 in arXiv:1806.00500.

  • phi2 (double or double np.ndarray) – Orbital phase in radians.

  • lam (double or double np.ndarray) – Ecliptic longitude in radians.

  • beta (double or double np.ndarray) – Ecliptic latitude in radians.

  • third_mass_unit (str, optional) – Mass unit for third-body mass. Options are "Mjup" for Jupiter Masses or "MSUN” for Solar Masses. Default is "Mjup".

  • third_period_unit (str, optional) – Time unit for third-body period. Options are "sec" for seconds or "yrs” for years. Default is "yrs".

Returns:

(A2, varpi, T2) associated with the input parameters.

Return type:

Tuple

gbgpu.thirdbody.get_T2(P2, e2, phi2, third_period_unit='yrs')

Get T2 from third-body parameters

Parameters:

  • P2 (double or double np.ndarray) – Orbital period of third body in units of third_period_unit kwarg.

  • e2 (double or double np.ndarray) – Orbital eccentricity of third body.

  • phi2 (double or double np.ndarray) – Orbital phase in radians.

  • third_period_unit (str, optional) – Time unit for third-body period. Options are "sec" for seconds or "yrs” for years. Default is "yrs".

Returns:

T2 associated with the input parameters.

Return type:

double xp.ndarray