Enable f_min=0 for NRSur in XLALSimInspiralTD

Description

This enables f_min=0 for NRSur7dq4/q2 through SimInspiralTD. No changes to the surrogate code itself.

f_min=0 means return the full length of the surrogate, which is -4300M (-4500M) for NRSur7dq4 (NRSur7dq2). Setting f_min=20Hz (for say M~60 MSun) will mean the early part of the surrogate would get discarded. With this change, one can use f_min=0, but set fStart=20Hz in the likelihood integral itself. This way, at least some of the higher mode content above 20Hz can be captured.

ChooseTDWaveform already allowed f_min=0, but SimInspiralTD did not. Now, models that are listed as allowing f_min=0 (currently only NRSur7dq4/q2, in XLALSimInspiralGetAllowZeroMinFreqFromApproximant) will call ChooseTDWaveform from within SimInspiralTD, independent of what f_min is passed.

Furthermore, the previous default behaviour of SimInspiralTD was to reduce f_min before evaluating the model. Now, models that allow f_min=0, do not reduce f_min, independent of what f_min is passed. This behaviour is now documented as well, and one has to explicitly add new models to the list of models in XLALSimInspiralGetAllowZeroMinFreqFromApproximant for this behaviour to take effect.

Example:

Working with this test example,

import lal
import lalsimulation as lalsim
approxTag = lalsim.GetApproximantFromString('NRSur7dq4')
f_ref = 20
f_min = 0
q = 1
M = 60
hp, hc = lalsim.SimInspiralTD(M*lal.MSUN_SI*q/(1.+q), M*lal.MSUN_SI/(1.+q),
        0., 0., 0., 0., 0., 0., 1.0e6 * lal.PC_SI, 0., 0., 0., 0., 0.,
        1./4096, f_min, f_ref, lal.CreateDict(), approxTag)

Before this change, this is what SimInspiralTD did for f_min=0:

XLAL Error - XLALParsePassBandParamStruc (/home/conda/feedstock_root/build_artifacts/lal-split_1642171255063/work/lib/tdfilter/ButterworthTimeSeries.c:574): Invalid argument
XLAL Error - XLALButterworthREAL8TimeSeries (/home/conda/feedstock_root/build_artifacts/lal-split_1642171255063/work/lib/tdfilter/ButterworthTimeSeries_source.c:52): Invalid argument
XLAL Error - XLALHighPassREAL8TimeSeries (/home/conda/feedstock_root/build_artifacts/lal-split_1642171255063/work/lib/tdfilter/ButterworthTimeSeries_source.c:186): Internal function call failed: Invalid argument
XLAL Error - XLALParsePassBandParamStruc (/home/conda/feedstock_root/build_artifacts/lal-split_1642171255063/work/lib/tdfilter/ButterworthTimeSeries.c:574): Invalid argument
XLAL Error - XLALButterworthREAL8TimeSeries (/home/conda/feedstock_root/build_artifacts/lal-split_1642171255063/work/lib/tdfilter/ButterworthTimeSeries_source.c:52): Invalid argument
XLAL Error - XLALHighPassREAL8TimeSeries (/home/conda/feedstock_root/build_artifacts/lal-split_1642171255063/work/lib/tdfilter/ButterworthTimeSeries_source.c:186): Internal function call failed: Invalid argument
Traceback (most recent call last):
  File "test.py", line 22, in <module>
    1./4096, f_min, f_ref, lal.CreateDict(), approxTag)
RuntimeError: Internal function call failed: Invalid argument

And if I use f_min=20:

XLAL Error - XLALSimInspiralPrecessingNRSurPolarizations (/home/conda/feedstock_root/build_artifacts/lalsimulation-split_1642168446269/work/lib/LALSimIMRPrecessingNRSur.c:2295): fMin should be 0 or >= 17.36990539 for this configuration, got 16.39382138
XLAL Error - XLALSimInspiralPrecessingNRSurPolarizations (/home/conda/feedstock_root/build_artifacts/lalsimulation-split_1642168446269/work/lib/LALSimIMRPrecessingNRSur.c:2295): Input domain error
XLAL Error - XLALSimInspiralTDFromTD (/home/conda/feedstock_root/build_artifacts/lalsimulation-split_1642168446269/work/lib/LALSimInspiral.c:2533): Internal function call failed: Input domain error
XLAL Error - XLALSimInspiralTD (/home/conda/feedstock_root/build_artifacts/lalsimulation-split_1642168446269/work/lib/LALSimInspiral.c:2780): Internal function call failed: Input domain error
Traceback (most recent call last):
  File "test.py", line 22, in <module>
    1./4096, f_min, f_ref, lal.CreateDict(), approxTag)
RuntimeError: Internal function call failed: Input domain error

Notice that the f_min passed to the surrogate is 16.39, not 20. This is the expected behaviour for SimInspiralTD, but it means that the surrogate cannot be used for M=60 MSun for f_min=20 Hz through this interface.

With this change, both of the above cases produce a waveform. The full surrogate is returned for f_min=0, and f_min=20Hz is directly passed to the surrogate code so it has no issues for M=60 MSun.

API Changes and Justification

Backwards Compatible Changes

• This change does not modify any class/function/struct/type definitions in a public C header file or any Python class/function definitions
• This change adds new classes/functions/structs/types to a public C header file or Python module.
• Adds a new struct tagAllowZeroMinFreq and a new function XLALSimInspiralGetAllowZeroMinFreqFromApproximant to lalsimulation/lib/LALSimInspiral.h.

Backwards Incompatible Changes

• This change modifies an existing class/function/struct/type definition in a public C header file or Python module
• This change removes an existing class/function/struct/type from a public C header file or Python module

If any of the Backwards Incompatible check boxes are ticked please provide a justification why this change is necessary and why it needs to be done in a backwards incompatible way.

Review Status

The model is already reviewed: https://git.ligo.org/waveforms/reviews/nrsur7dq4, but these changes should be approved by the review chair (@harald.pfeiffer). Some new tests (to make sure flow=0 does the right thing for SimInspiralTD, and that this MR does not impact ChooseTDWaveform for NRSur7dq4/q2, or SimInspiraTD for PhenomXPHM/PhenomTPHM/SEOBNRv4PHM) have been added here.