Computing the waveform
Once you have computed the orbital evolution, and selected the time steps on which you want to evaluate the waveform, you can do so with one of the functions documented below.
Precise definition of waveforms
The waveform returned by these functions is essentially the complex strain $h \colonequals h_+ - i\,h_\times$. However, this quantity decays as $1/r$, where $r$ is the radius at which the strain is measured. Therefore, as is conventional, the returned quantity is actually
\[H \colonequals \lim_{r\to\infty} h\, \frac{r}{M}\, \frac{c^2}{G},\]
where $M$ is the total mass of the two objects in the binary. Note that both $h$ and $H$ are dimensionless, but only $H$ is scale invariant.
Binaries are usually modeled in relativity as being isolated systems in otherwise empty asymptotically flat spacetimes — or even more specifically, in asymptotically Minkowski spacetimes. In this case, $r$ is just the asymptotic areal radius. The equivalent expression in an FLRW spacetime requires a simple reinterpretation of $M$ as the redshifted mass $M_z \colonequals M(1+z)$ and $r$ as the luminosity distance $d_L.$[1] Thus, to obtain the strain as it would be measured (in the asymptotic approximation) by an actual observer in an asymptotically flat universe or in our universe, we just need to invert the previous equation:
\[h \approx H\, \frac{M}{r}\, \frac{G}{c^2} \qquad \mathrm{or} \qquad h \approx H\, \frac{M_z}{d_L}\, \frac{G}{c^2}.\]
Furthermore, $H$ is a function of coordinates $(t, \theta, \phi)$. The dependence on $t$ will be discretely sampled at the times $t_i$ that are present in the inspiral arguments to the functions below. To handle the angular dependence, we provide the waveform decomposed as mode weights in a spin-weighted spherical-harmonic decomposition, so that the actual quantity returned will be
\[H_{\ell,m}(t_i) \colonequals \int H(t, \theta, \phi)\, {}_{-2}\bar{Y}_{\ell,m}(\theta, \phi)\, \sin\theta\, d\theta\, d\phi.\]
The output array is a two-dimensional complex array. The first dimension varies over $(\ell,m)$ values, with $m$ varying most rapidly — as in
[(ℓ,m) for ℓ ∈ ℓₘᵢₙ:ℓₘₐₓ for m ∈ -ℓ:ℓ]The second dimension of the array indexes the time.
See Example 2 on the "Units" page for a complete example of converting this package's output to standard units in our universe.
Evaluation of waveforms
PostNewtonian.coorbital_waveform — Functioncoorbital_waveform(inspiral; [ℓₘᵢₙ=2], [ℓₘₐₓ=8], [PNOrder])
coorbital_waveform(inspiral; [ell_min=2], [ell_max=8], [PNOrder])Evaluate the post-Newtonian waveform mode weights in the co-orbital frame for the given inspiral output by orbital_evolution.
See also inertial_waveform for the waveform in the inertial frame.
For a detailed description of the format and physical interpretation of the returned quantity, see the "Waveforms" section of the manual.
The PNOrder defaults to the one used to compute inspiral, but may be changed by passing the keyword argument.
If you need this waveform at a different set of times t′ than is currently present in inspiral.t, you should use the built-in interpolation capabilities of inspiral first, as in inspiral′ = inspiral(t′), rather than interpolating the results of this function. Or, perhaps better yet, you could select the times when calling orbital_evolution by using the saves_per_orbit or saveat keyword argument to that function. These approaches will be more accurate, faster, and require less memory than interpolating the result of this function. If using saves_per_orbit, you probably want to set it to at least 2ℓₘₐₓ, or preferably 4ℓₘₐₓ.
The mode weights are given starting at ℓₘᵢₙ (which must satisfy 0 ≤ ℓₘᵢₙ ≤ 2) and extending through ℓₘₐₓ. The waveform is returned as a 2-dimensional Array, in which the first index varies over the mode index from (ℓ, m) = (ℓₘᵢₙ, -ℓₘᵢₙ) to (ℓ, m) = (ℓₘₐₓ, ℓₘₐₓ), with m varying most rapidly, and the second index varying over the time steps.
In this function, the waveform is returned in the co-orbital frame — which is somewhat like the co-rotating frame. In particular, the modes of non-precessing systems vary slowly, over inspiral timescales; modes of precessing systems still vary on orbital timescales, though even this variation could be factored out.
PostNewtonian.inertial_waveform — Functioninertial_waveform(inspiral; [ℓₘᵢₙ=2], [ℓₘₐₓ=8], [PNOrder])
inertial_waveform(inspiral; [ell_min=2], [ell_max=8], [PNOrder])Evaluate the post-Newtonian waveform mode weights in the inertial frame for the given inspiral output by orbital_evolution.
The inertial frame is the one in which inertial observers are found, so this waveform is more like one that actual observers would detect. This function transforms the waveform from the co-orbital frame — which is the one in which PN expressions are provided.
See coorbital_waveform for details about the other arguments and returned quantity.
In-place evaluation of waveforms
This is likely to be an uncommon scenario, but if you happen to need to evaluate the waveform repeatedly on the same set (or at least same number) of time steps and same range of $\ell$ values, then you can pre-allocate the storage needed in this process, and re-use that storage. To do so, pre-allocate using either coorbital_waveform_computation_storage or inertial_waveform_computation_storage, and then pass the result as the first argument to either coorbital_waveform! or inertial_waveform!.
The h array returned by either coorbital_waveform! or inertial_waveform! is part of the pre-allocated storage. You need to use its values before you call either of those functions again, or those values will just be overwritten.
PostNewtonian.coorbital_waveform_computation_storage — Functioncoorbital_waveform_computation_storage(inspiral; [ℓₘᵢₙ=2], [ℓₘₐₓ=8], [PNOrder])
coorbital_waveform_computation_storage(inspiral; [ell_min=2], [ell_max=8], [PNOrder])Construct storage needed to compute waveforms in the co-orbital frame without allocations.
This returns the storage for the waveforms themselves and PNSystem used as temporary storage. The returned quantity can just be passed as the first argument to coorbital_waveform! without being unpacked.
The meaning of the arguments is the same as in coorbital_waveform.
PostNewtonian.inertial_waveform_computation_storage — Functioninertial_waveform_computation_storage(inspiral; [ℓₘᵢₙ=2], [ℓₘₐₓ=8], [PNOrder])
inertial_waveform_computation_storage(inspiral; [ell_min=2], [ell_max=8], [PNOrder])Construct storage needed to compute waveforms in the inertial frame without allocations.
This returns the storage for the waveforms themselves, storage used for computing the Wigner 𝔇 matrices, and for "in-place" multiplication. The returned quantity can just be passed as the first argument to inertial_waveform! without being unpacked.
The meaning of the arguments is the same as in inertial_waveform.
PostNewtonian.coorbital_waveform! — Functioncoorbital_waveform!(storage, inspiral; [ℓₘᵢₙ=2], [ℓₘₐₓ=8], [PNOrder])
coorbital_waveform!(storage, inspiral; [ell_min=2], [ell_max=8], [PNOrder])Evaluate the post-Newtonian waveform mode weights in the co-orbital frame for the given inspiral output by orbital_evolution, using pre-allocated storage.
The storage is assumed to be the object returned from coorbital_waveform_computation_storage. Other arguments are the same as in coorbital_waveform.
PostNewtonian.inertial_waveform! — Functioninertial_waveform!(storage, inspiral; [ℓₘᵢₙ=2], [ℓₘₐₓ=8], [PNOrder])
inertial_waveform!(storage, inspiral; [ell_min=2], [ell_max=8], [PNOrder])Evaluate the post-Newtonian waveform mode weights in the inertial frame for the given inspiral output by orbital_evolution, using pre-allocated storage.
The storage is assumed to be the object returned from inertial_waveform_computation_storage. Other arguments are the same as in inertial_waveform.
- 1Note that we use "luminosity distance" as it is understood in contemporary cosmology, which is unfortunately different from its meaning in older cosmology literature, and even some of the gravitational-wave astronomy literature from before 2015 or so.