PNWaveform¶

Note

For post-Newtonian waveforms, use PostNewtonian.jl, which is far more complete, accurate, and flexible than this code.

class GWFrames.PNWaveform¶

Post-Newtonian waveform of a precessing binary black hole.

A PNWaveform is a Waveform computed by evolving the orbital dynamics and spins of a quasicircular binary in post-Newtonian (PN) theory, and then evaluating the PN expressions for the modes of \(h\). In addition to the data of a Waveform, it stores at each time step the two spin vectors chi1 and chi2, the orbital angular velocity Omega_orb, the precessional angular velocity Omega_prec, the orbital angular momentum L, and the orbital phase Phi_orb, which are returned by the methods of the same names. All of these vectors are expressed in the inertial basis. Methods also return their magnitudes (PNWaveform.Omega_orbMag, and so on) and their directions (PNWaveform.OmegaHat_orb, and so on).

A PNWaveform may be constructed in any of these ways:

PNWaveform(): An empty waveform.
PNWaveform(W): A copy of the PNWaveform W, including its history.
PNWaveform(Approximant, delta, chi1_i, chi2_i, Omega_orb_i, ...): The PN waveform of a binary with the given parameters, which are described below. The optional parameters Omega_orb_0, R_frame_i, MinStepsPerOrbit, PNWaveformModeOrder, and PNOrbitalEvolutionOrder follow, in that order.

The PN system is defined with respect to an inertial basis \((\hat{x}, \hat{y}, \hat{z})\), in which the spin vectors are given. A second basis \((\hat{X}, \hat{Y}, \hat{Z})\) is obtained by rotating the inertial basis by R_frame_i. At the initial time, black hole 1 lies on the positive \(X\) axis, black hole 2 lies on the negative \(X\) axis, and the orbital angular velocity points along the positive \(Z\) axis with magnitude Omega_orb_i. The orbital evolution is integrated forward in time from there until the PN equations stop making progress near merger (when the PN parameter \(v\) reaches 1, stops increasing, or requires very small time steps), and, if Omega_orb_0 is smaller than Omega_orb_i, also backward in time until the orbital frequency falls to Omega_orb_0. The time \(t = 0\) corresponds to the moment at which the orbital frequency is Omega_orb_i. The time steps are chosen by the adaptive integrator, so they are not uniform.

The parameters of the third constructor are these:

Approximantstr: The PN approximant used to evolve the orbital frequency: "TaylorT1", "TaylorT4", or "TaylorT5". Any other value raises an error.
deltafloat: The normalized mass difference \((M_1 - M_2) / (M_1 + M_2)\), which lies between -1 and 1 and is 0 for equal masses. The total mass \(M_1 + M_2\) is 1, so that all quantities are in units of the total mass.
chi1_i, chi2_iarray_like of float, shape (3,): The initial dimensionless spin vectors \(\vec{S}_1 / M_1^2\) and \(\vec{S}_2 / M_2^2\) of the two black holes, with components in the inertial basis.
Omega_orb_ifloat: The orbital angular frequency at \(t = 0\), in units of \(1/M\).
Omega_orb_0float, default -1.0: The orbital angular frequency at which the waveform begins. If it is smaller than Omega_orb_i, the system is also evolved backward in time to that frequency. A value that is not positive (the default), or that is not smaller than Omega_orb_i, makes the waveform begin at Omega_orb_i.
R_frame_iQuaternion, default Quaternion(1, 0, 0, 0): The rotor taking the inertial basis to the initial basis of the binary, as described above. The default places the binary in the standard position, with its orbital angular velocity along \(\hat{z}\).
MinStepsPerOrbitint, default 32: The minimum number of time steps per orbit. The step size of the integrator is limited to a fraction of the instantaneous orbital period, so that at least this many steps are taken in each orbit.
PNWaveformModeOrderfloat, default 3.5: The PN order at which the waveform modes are computed, a multiple of 0.5 from 0 to 3.5.
PNOrbitalEvolutionOrderfloat, default 4.0: The PN order at which the orbital evolution is computed, a multiple of 0.5 from 0 to 6.0.

Both PN orders are rounded down to a multiple of 0.5, and an order outside the stated range raises an error.

The waveform has modes with \(2 \leq \ell \leq 8\) and all values of \(m\). Its data type is \(h\), with the radius and the total mass scaled out. The modes are computed in the co-orbital frame, whose rotor at each time is stored as the waveform’s Waveform.Frame, so the waveform initially has frame type Coorbital; this frame is nearly, but not quite, corotating. To obtain the waveform in an inertial frame, apply Waveform.TransformToInertialFrame; to obtain it in the corotating frame, apply Waveform.TransformToInertialFrame and then Waveform.TransformToCorotatingFrame.

Examples

>>> import GWFrames
>>> W = GWFrames.PNWaveform("TaylorT4", 0.0, [0.0, 0.0, 0.9],
...                          [0.0, 0.0, 0.9], 0.01)

classmethod __new__(*args, **kwargs)¶

PNWaveform is a subclass of Waveform, so all of the methods of Waveform apply to it as well. The methods below return the quantities of the post-Newtonian orbital evolution.

Spins¶

PNWaveform.chi1() → ndarray¶

PNWaveform.chi1(iTime: int) → ndarray

Return the spin vector of black hole 1.

The dimensionless spin vector \(\vec{S}_1 / M_1^2\) is given in the inertial basis.

Parameters:: iTime (int, optional) – Index of the time step. If omitted, the vectors at all times are returned.
Returns:: ndarray of float, shape (3,) or (N, 3) – The spin vector at the given time step, or at each of the N time steps.

PNWaveform.chi2() → ndarray¶

PNWaveform.chi2(iTime: int) → ndarray

Return the spin vector of black hole 2.

The dimensionless spin vector \(\vec{S}_2 / M_2^2\) is given in the inertial basis.

Parameters:: iTime (int, optional) – Index of the time step. If omitted, the vectors at all times are returned.
Returns:: ndarray of float, shape (3,) or (N, 3) – The spin vector at the given time step, or at each of the N time steps.

PNWaveform.chi1Mag(iTime: int) → float¶

Return the magnitude of the spin of black hole 1.

Parameters:: iTime (int) – Index of the time step.
Returns:: float – The magnitude of PNWaveform.chi1 at the given time step.

PNWaveform.chi2Mag(iTime: int) → float¶

Return the magnitude of the spin of black hole 2.

Parameters:: iTime (int) – Index of the time step.
Returns:: float – The magnitude of PNWaveform.chi2 at the given time step.

PNWaveform.chiHat1() → ndarray¶

PNWaveform.chiHat1(iTime: int) → ndarray

Return the direction of the spin of black hole 1.

The result is PNWaveform.chi1 divided by its magnitude, so it is undefined (NaN) when the spin is zero.

Parameters:: iTime (int, optional) – Index of the time step. If omitted, the directions at all times are returned.
Returns:: ndarray of float, shape (3,) or (N, 3) – The unit vector at the given time step, or at each of the N time steps.

PNWaveform.chiHat2() → ndarray¶

PNWaveform.chiHat2(iTime: int) → ndarray

Return the direction of the spin of black hole 2.

The result is PNWaveform.chi2 divided by its magnitude, so it is undefined (NaN) when the spin is zero.

Parameters:: iTime (int, optional) – Index of the time step. If omitted, the directions at all times are returned.
Returns:: ndarray of float, shape (3,) or (N, 3) – The unit vector at the given time step, or at each of the N time steps.

Orbital and precessional motion¶

PNWaveform.Omega_orb() → ndarray¶

PNWaveform.Omega_orb(iTime: int) → ndarray

Return the orbital angular-velocity vector.

The orbital angular velocity is \(v^3 \hat{\ell}\), where \(v\) is the PN parameter and \(\hat{\ell}\) is the direction normal to the orbital plane. It is given in the inertial basis, in units of \(1/M\).

Parameters:: iTime (int, optional) – Index of the time step. If omitted, the vectors at all times are returned.
Returns:: ndarray of float, shape (3,) or (N, 3) – The orbital angular velocity at the given time step, or at each of the N time steps.

PNWaveform.Omega_orbMag() → ndarray¶

PNWaveform.Omega_orbMag(iTime: int) → float

Return the magnitude of the orbital angular velocity.

Parameters:: iTime (int, optional) – Index of the time step. If omitted, the magnitudes at all times are returned.
Returns:: float or ndarray of float, shape (N,) – The magnitude of PNWaveform.Omega_orb at the given time step, or at each of the N time steps.

PNWaveform.OmegaHat_orb() → ndarray¶

PNWaveform.OmegaHat_orb(iTime: int) → ndarray

Return the direction of the orbital angular velocity.

Parameters:: iTime (int, optional) – Index of the time step. If omitted, the directions at all times are returned.
Returns:: ndarray of float, shape (3,) or (N, 3) – The unit vector along PNWaveform.Omega_orb at the given time step, or at each of the N time steps.

PNWaveform.Omega_prec() → ndarray¶

PNWaveform.Omega_prec(iTime: int) → ndarray

Return the precessional angular-velocity vector.

The precessional angular velocity is the angular velocity of the co-orbital frame minus the orbital angular velocity, so that it describes the motion of the orbital plane. It is given in the inertial basis, in units of \(1/M\).

Parameters:: iTime (int, optional) – Index of the time step. If omitted, the vectors at all times are returned.
Returns:: ndarray of float, shape (3,) or (N, 3) – The precessional angular velocity at the given time step, or at each of the N time steps.

PNWaveform.Omega_precMag() → ndarray¶

PNWaveform.Omega_precMag(iTime: int) → float

Return the magnitude of the precessional angular velocity.

Parameters:: iTime (int, optional) – Index of the time step. If omitted, the magnitudes at all times are returned.
Returns:: float or ndarray of float, shape (N,) – The magnitude of PNWaveform.Omega_prec at the given time step, or at each of the N time steps.

PNWaveform.OmegaHat_prec() → ndarray¶

PNWaveform.OmegaHat_prec(iTime: int) → ndarray

Return the direction of the precessional angular velocity.

The result is undefined (NaN) wherever the precessional angular velocity is zero, as it is for a nonprecessing system.

Parameters:: iTime (int, optional) – Index of the time step. If omitted, the directions at all times are returned.
Returns:: ndarray of float, shape (3,) or (N, 3) – The unit vector along PNWaveform.Omega_prec at the given time step, or at each of the N time steps.

PNWaveform.Omega_tot() → ndarray¶

PNWaveform.Omega_tot(iTime: int) → ndarray

Return the total angular-velocity vector of the binary.

The total angular velocity is the sum of PNWaveform.Omega_orb and PNWaveform.Omega_prec, which is the angular velocity of the co-orbital frame. It is given in the inertial basis, in units of \(1/M\).

Parameters:: iTime (int, optional) – Index of the time step. If omitted, the vectors at all times are returned.
Returns:: ndarray of float, shape (3,) or (N, 3) – The total angular velocity at the given time step, or at each of the N time steps.

PNWaveform.Omega_totMag() → ndarray¶

PNWaveform.Omega_totMag(iTime: int) → float

Return the magnitude of the total angular velocity.

Parameters:: iTime (int, optional) – Index of the time step. If omitted, the magnitudes at all times are returned.
Returns:: float or ndarray of float, shape (N,) – The magnitude of PNWaveform.Omega_tot at the given time step, or at each of the N time steps.

PNWaveform.OmegaHat_tot() → ndarray¶

PNWaveform.OmegaHat_tot(iTime: int) → ndarray

Return the direction of the total angular velocity.

Parameters:: iTime (int, optional) – Index of the time step. If omitted, the directions at all times are returned.
Returns:: ndarray of float, shape (3,) or (N, 3) – The unit vector along PNWaveform.Omega_tot at the given time step, or at each of the N time steps.

PNWaveform.Phi_orb() → ndarray¶

PNWaveform.Phi_orb(iTime: int) → float

Return the orbital phase.

The orbital phase is the integral of the orbital angular frequency, and is zero at \(t = 0\), where the orbital frequency is Omega_orb_i.

Parameters:: iTime (int, optional) – Index of the time step. If omitted, the phases at all times are returned.
Returns:: float or ndarray of float, shape (N,) – The orbital phase at the given time step, or at each of the N time steps.

Angular momentum¶

PNWaveform.L() → ndarray¶

PNWaveform.L(iTime: int) → ndarray

Return the orbital angular-momentum vector.

The orbital angular momentum is computed from its PN expression, at the PN order of the orbital evolution, and is given in the inertial basis in units of \(M^2\). Its leading term is \(M^2 \nu \hat{\ell} / v\), where \(\nu\) is the symmetric mass ratio; the spin-orbit terms make it deviate slightly from the direction \(\hat{\ell}\) of the orbital angular velocity.

Parameters:: iTime (int, optional) – Index of the time step. If omitted, the vectors at all times are returned.
Returns:: ndarray of float, shape (3,) or (N, 3) – The orbital angular momentum at the given time step, or at each of the N time steps.

PNWaveform.LMag() → ndarray¶

PNWaveform.LMag(iTime: int) → float

Return the magnitude of the orbital angular momentum.

Parameters:: iTime (int, optional) – Index of the time step. If omitted, the magnitudes at all times are returned.
Returns:: float or ndarray of float, shape (N,) – The magnitude of PNWaveform.L at the given time step, or at each of the N time steps.

PNWaveform.LHat() → ndarray¶

PNWaveform.LHat(iTime: int) → ndarray

Return the direction of the orbital angular momentum.

Parameters:: iTime (int, optional) – Index of the time step. If omitted, the directions at all times are returned.
Returns:: ndarray of float, shape (3,) or (N, 3) – The unit vector along PNWaveform.L at the given time step, or at each of the N time steps.