Generalize time-domain waveform modes generation via lalsim

[prayush]

Generalize time-domain waveform modes generation via `lalsimulation``

Standard information about the request

This is a: new feature

This change affects: No existing code, this is a new feature

This change changes: CBC waveform modes generation

This change: has appropriate unit tests, follows style guidelines (See e.g. PEP8), has been proposed using the contribution guidelines

Motivation

There are many approximants implemented in lalsimulation that allow for generation of individual spherical harmonic modes of gravitational radiation. We want to interface them through the waveform.get_td_waveform_modes interface, which currently works for a small number of approximants.

Contents

• Added a function to generate waveform modes for many time-domain approximants available via lalsimulation.

• Added a function to generate lalsimulation approximant object from model name string.

Links to any issues or associated PRs

Testing performed

Additional notes

• The author of this pull request confirms they will adhere to the code of conduct

[ahnitz]

Thanks for adding this!

[ahnitz]

@prayush I think one thing to understand is the mode convention for the different approximants. We've had this experience before where things like XPHM or the NRSurrogates differ in what frame they defined the modes. The latter actually being easier to work with since could pretty easily apply initial inclination / phase and reconstruct the waveform post-facto even for a precessing signal. Is this standardized now, or is it still a free for all?

[prayush]

@prayush I think one thing to understand is the mode convention for the different approximants. We've had this experience before where things like XPHM or the NRSurrogates differ in what frame they defined the modes. The latter actually being easier to work with since could pretty easily apply initial inclination / phase and reconstruct the waveform post-facto even for a precessing signal. Is this standardized now, or is it still a free for all?

@ahnitz indeed many of those issues are now worked out. AFAIK the frame conventions for defining the initial binary spin conventions have been made consistent between all waveform approximants (or at least among the major ones). However the meaning of angle parameters, like coa_phase is definitely not consistent among all approximants.

One solution to this dilemma could be that this interface that I've added here require a prefix "LAL" to the approximant name, e.g. LALSEOBNRv4 or LALTaylorT1, which will make it explicit to the user that they are calling into lalsuite here, and we can also print a warning saying that the user needs to be responsible for understanding what they are getting back because it depends on lalsuite's conventions, which might change without notice.

If you think either of these are useful, let me know and I'll patch this PR accordingly. Overall though, this functionality will be very useful to have though.

[ahnitz]

@prayush I don't think it's needed to modify the names. The question about convention was more to do with how the modes are defined and extracted not the spin definition.

This has not been entirely consistent, especially between things like the NRSurrogates and the Phenom Models. The latter combined +- m modes together and handled the extraction frame differently (in the precessing case). This mean that in practice one couldn't recombine them with the ylms to project to a particular phase / inclination. For the NRSurrogates you could however.

So the real question is if the modes here can be recombined into the full waveform by only multiplying by the appropriate ylm term and summing? (e.g. can you directly feed them back to the sum_modes function and get back what you expect?

[prayush]

@ahnitz I believe the answer is yes. Here is some evidence in code:

import pycbc.waveform as wf

one_sim_params = {
    "mass1": 44.99800626045199,
    "mass2": 15.00199373954801,
    "spin1x": 0.0,
    "spin1y": 0.0,
    "spin1z": -4.73607340256702e-06,
    "spin2x": 0.0,
    "spin2y": 0.0,
    "spin2z": 0.666916884593987,
    "f_lower": 30.0,
    "distance": 1.0,
    "delta_t": 6.103515625e-05,
}
modes1 = wf.get_td_waveform_modes(
    approximant="SEOBNRv4PHM", coa_phase=coa_phase, **one_sim_params
)
modes2 = wf.get_td_waveform_modes(
    approximant="NRSur7dq4", coa_phase=coa_phase, **one_sim_params
)
modes3 = wf.get_td_waveform_modes(
    approximant="IMRPhenomTPHM", coa_phase=coa_phase, **one_sim_params
)

for ellem in [(2, 2), (3, 3), (4, 4)]:
    plt.figure(figsize=(12, 8))
    plt.plot(modes1[ellem][0].sample_times, modes1[ellem][0], label="SEOBNRv4P")
    plt.plot(modes2[ellem][0].sample_times, modes2[ellem][0], "--", label="NRSur7dq4")
    plt.plot(
        modes3[ellem][0].sample_times, modes3[ellem][0], "--", label="IMRPhenomTHM"
    )
    plt.xlim(xmax=0.05)
    plt.legend()
    plt.title(f"$\ell={ellem[0]}, m={ellem[1]}$")

which gives me the following figures:

[prayush]

In other words, whatever can be done with NRSur7dq4 (ie sum the modes up with appropriate ${}^{-2}Y_{lm}$) can be done with SEOBNRx and PhenomTHM. Note that this PR only adds time-domain approximants, and I am not yet adding Fourier domain ones since I have not tested them well enough yet.

[prayush]

Here's what you get if you run the above with $m \rightarrow -m$:

[prayush]

One question I have for you @ahnitz is for the NRSur approximants, currently we have a call into the surrogates' API directly, and not through lalsuite. Do you want to retain that (as this PR does)? Or do you prefer to have that redirected through lalsuite as well? I was inclined to add a couple of new approximants with LAL prefixed onto their names, i.e. LALNRSur7dq4 etc, and have those route through lalsuite, while retaining the call to surrogates' API for NRSur7dq4 etc. This would be backwards compatible, and just give us a route to test both interfaces -- which might be useful in the future in case the two interfaces begin to diverge (which is not impossible!).

[prayush]

@ahnitz gentle ping on this.

[ahnitz]

@prayush I think this is good to go as is.

@prayush I think it would be fine to add each path as a different approximant in a followup PR if that makes sense. The other thing that would be good in a followup is to add a unittest that exercises this interface.