New waveforms interface

Description

Incorporates the new waveforms interface.

Support calling C and python waveform models from C and python clients.

The standard functions XLALSimInspiralChooseFD(TD)Waveform and XLALSimInspiralChooseFD(TD)Modes remain backwards compatible.

New C functions have been added XLALSimInspiralGenerateFD(TD)Waveform(Modes) which replicate the old ones and support a more flexible input of the parameters. Equivalent functions exist for the python interface.

The LALSuite build system has been modified to support embedded python.

See here for a brief introduction on the new waveforms interface.

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

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

Review chaired by @vijay.varma and @sascha.husa. Review wiki, review repo The review statement for the first stage of reviews is here.

lalsimulation/lib/LALSimInspiral.c

@@ -359,7 +359,21 @@ const LALSimInspiralGenerator *lalSimInspiralGeneratorTemplates[NumApproximants]
     [ExternalPython] = &lalPythonGeneratorTemplate,
 };
 
-
+/**
+ * @addtogroup LALSimInspiral_c
+ * @brief General routines for generating binary inspiral waveforms.
+ *
+ * @{
+ */
+ 
+ /**
+  * @name New Interface Generator Routines
+  * @{
+  */
+  
+  /**
+   * Destroy LALSimInspiralGenerator object.
+   */
 void XLALDestroySimInspiralGenerator(LALSimInspiralGenerator *generator)
 {
     if (generator) {
@@ -376,7 +390,11 @@ void XLALDestroySimInspiralGenerator(LALSimInspiralGenerator *generator)
     return;
 }
 
-
+/**
+ * Create LALSimInspiralGenerator object.
+ * The LALDict can be None for all the C approximants. For external python model, the LALDict must contain the file and class object where the `generate_waveform` methods are defined. FIXME: add example.
+ * Activating the option `condition` in the LALDict will generate the waveform with adequate conditioning for (inverse)Fourier transform.
+ */
 LALSimInspiralGenerator *XLALCreateSimInspiralGenerator(const LALSimInspiralGenerator *generator, LALDict *params)
 {
     LALSimInspiralGenerator *new;
@@ -400,7 +418,11 @@ LALSimInspiralGenerator *XLALCreateSimInspiralGenerator(const LALSimInspiralGene
     return new;
 }
 
-
+/**
+ * Returns LALSimInspiralGenerator object from approximant.
+ * The LALDict can be None for all the C approximants. For external python model, the LALDict must contain the file and class object where the `generate_waveform` methods are defined. FIXME: add example.
+ * Activating the option `condition` in the LALDict will generate the waveform with adequate conditioning for (inverse)Fourier transform.
+ */
 LALSimInspiralGenerator *XLALSimInspiralChooseGenerator(Approximant approx, LALDict *params)
 {
     const LALSimInspiralGenerator *template = lalSimInspiralGeneratorTemplates[approx];
@@ -408,15 +430,30 @@ LALSimInspiralGenerator *XLALSimInspiralChooseGenerator(Approximant approx, LALD
     return XLALCreateSimInspiralGenerator(template, params);
 }
 
-
-/* warning: returns a shallow pointer */
+/**
+ * Return approximant name from generator object
+ *
+ */
 const char *XLALSimInspiralGeneratorName(LALSimInspiralGenerator *generator)
 {
     XLAL_CHECK_NULL(generator, XLAL_EFAULT);
     return generator->name;
 }
 
+ /** @} */
 
+/**
+ * @name New Interface Waveform Routines
+ * @{
+ */
+ 
+/**
+ * Returns time-domain polarizations for a specific approximant.
+ * Equivalent to XLALSimInspiralChooseTDWaveform(). Equivalent to XLALSimInspiralTD() if the option `condition` is activated in the LALDict.
+ * The waveform arguments are inserted into the LALDict. The generator carries the info about the approximant and potentially extra data which could be recycled by the model to speed-up calculation.  
+ *
+ * The parameters in the LALDict must be in SI units.
+ */
 int XLALSimInspiralGenerateTDWaveform(
     REAL8TimeSeries **hplus,
     REAL8TimeSeries **hcross,
@@ -433,7 +470,13 @@ int XLALSimInspiralGenerateTDWaveform(
     XLAL_ERROR(XLAL_EINVAL, "generator does not provide a method to generate time-domain waveforms");
 }
 
-
+/**
+ * Compute time-domain modes for a specific approximant.
+ * Equivalent to XLALSimInspiralChooseTDModes(). The only difference is that the SphHarmSeries object needs to be passed as an argument to the function. The actual returned value is an integer which indicates success or error in the waveform evaluation (see https://lscsoft.docs.ligo.org/lalsuite/lal/group___x_l_a_l_error__h.html).
+ * The waveform arguments are inserted into the LALDict. The generator carries the info about the approximant and potentially extra data which could be recycled by the model to speed-up calculation.  
+ *
+ * The parameters in the LALDict must be in SI units.
+ */
 int XLALSimInspiralGenerateTDModes(
     SphHarmTimeSeries **hlm,
     LALDict *params,
@@ -449,6 +492,13 @@ int XLALSimInspiralGenerateTDModes(
     XLAL_ERROR(XLAL_EINVAL, "generator does not provide a method to generate time-domain modes");
 }
 
+/**
+ * Returns frequency-domain polarizations for a specific approximant.
+ * Equivalent to XLALSimInspiralChooseFDWaveform(). Equivalent to XLALSimInspiralFD() if the option `condition` is activated in the LALDict.
+ * The waveform arguments are inserted into the LALDict. The generator carries the info about the approximant and potentially extra data which could be recycled by the model to speed-up calculation.  
+ *
+ * The parameters in the LALDict must be in SI units.
+ */
 int XLALSimInspiralGenerateFDWaveform(
     COMPLEX16FrequencySeries **hplus,
     COMPLEX16FrequencySeries **hcross,
@@ -464,6 +514,13 @@ int XLALSimInspiralGenerateFDWaveform(
     XLAL_ERROR(XLAL_EINVAL, "generator does not provide a method to generate frequency-domain waveforms");
 }
 
+/**
+ * Compute frequency-domain modes for a specific approximant. 
+ * Equivalent to XLALSimInspiralChooseFDModes. The only difference is that the SphHarmSeries object needs to be passed as an argument to the function. The actual returned value is an integer which indicates success or error in the waveform evaluation (see https://lscsoft.docs.ligo.org/lalsuite/lal/group___x_l_a_l_error__h.html).
+ * The waveform arguments are inserted into the LALDict. The generator carries the info about the approximant and potentially extra data which could be recycled by the model to speed-up calculation.  
+ *
+ * The parameters in the LALDict must be in SI units.
+ */
 int XLALSimInspiralGenerateFDModes(
     SphHarmFrequencySeries **hlm,
     LALDict *params,
@@ -479,6 +536,16 @@ int XLALSimInspiralGenerateFDModes(
     XLAL_ERROR(XLAL_EINVAL, "generator does not provide a method to generate frequency-domain modes");
 }
 
+/** @} */
+
+/**
+* @name New Interface parse parameters Routines
+* @{
+*/
+
+/**
+ * Insert all the input arguments needed by XALSimInspiralChooseTDWaveform() into a laldictionary.
+ */
 void XLALSimInspiralParseDictionaryToChooseTDWaveform(
     REAL8 *m1,                             /**< [out] mass of companion 1 (kg) */
     REAL8 *m2,                             /**< [out] mass of companion 2 (kg) */
@@ -497,7 +564,7 @@ void XLALSimInspiralParseDictionaryToChooseTDWaveform(
     REAL8 *deltaT,                         /**< [out] sampling interval (s) */
     REAL8 *f_min,                          /**< [out] starting GW frequency (Hz) */
     REAL8 *f_ref,                          /**< [out] reference frequency (Hz) */
-    LALDict *params                        /**< Input lal dictionary with ChooseTDwaveform parameters */
+    LALDict *params                        /**< Input lal dictionary with waveform (and optional) parameters **/
 )
 {
     *m1 = XLALSimInspiralWaveformParamsLookupMass1(params);
@@ -521,22 +588,25 @@ void XLALSimInspiralParseDictionaryToChooseTDWaveform(
     return;
 }
 
+/**
+ * Insert all the input arguments needed by XLALSimInspiralChooseTDModes() into a laldictionary.
+ */
 void XLALSimInspiralParseDictionaryToChooseTDModes(
-    REAL8 *phiRef,
-    REAL8 *deltaT,
-    REAL8 *m1,
-    REAL8 *m2,
-    REAL8 *S1x,
-    REAL8 *S1y,
-    REAL8 *S1z,
-    REAL8 *S2x,
-    REAL8 *S2y,
-    REAL8 *S2z,
-    REAL8 *f_min,
-    REAL8 *f_ref,
-    REAL8 *distance,
-	INT4 *lmax,
-    LALDict *params
+    REAL8 *phiRef,                         /**< [out] reference orbital phase (rad) */
+    REAL8 *deltaT,                         /**< [out] sampling interval (s) */
+    REAL8 *m1,                             /**< [out] mass of companion 1 (kg) */
+    REAL8 *m2,                             /**< [out] mass of companion 2 (kg) */
+    REAL8 *S1x,                            /**< [out] x-component of the dimensionless spin of object 1 */
+    REAL8 *S1y,                            /**< [out] y-component of the dimensionless spin of object 1 */
+    REAL8 *S1z,                            /**< [out] z-component of the dimensionless spin of object 1 */
+    REAL8 *S2x,                            /**< [out] x-component of the dimensionless spin of object 2 */
+    REAL8 *S2y,                            /**< [out] y-component of the dimensionless spin of object 2 */
+    REAL8 *S2z,                            /**< [out] z-component of the dimensionless spin of object 2 */
+    REAL8 *f_min,                          /**< [out] starting GW frequency (Hz) */
+    REAL8 *f_ref,                          /**< [out] reference frequency (Hz) */
+    REAL8 *distance,                       /**< [out] distance of source (m) */
+    INT4 *lmax,                            /**< [out] generate all modes with l <= lmax */
+    LALDict *params                        /**< Input lal dictionary with waveform (and optional) parameters **/
 )
 {
     *phiRef = XLALSimInspiralWaveformParamsLookupRefPhase(params);
@@ -558,6 +628,9 @@ void XLALSimInspiralParseDictionaryToChooseTDModes(
     return;
 }
 
+/**
+ * Insert all the input arguments needed by XLALSimInspiralChooseFDWaveform() into a laldictionary.
+ */
 void XLALSimInspiralParseDictionaryToChooseFDWaveform(
     REAL8 *m1,                             /**< [out] mass of companion 1 (kg) */
     REAL8 *m2,                             /**< [out] mass of companion 2 (kg) */
@@ -577,7 +650,7 @@ void XLALSimInspiralParseDictionaryToChooseFDWaveform(
     REAL8 *f_min,                          /**< [out] starting GW frequency (Hz) */
     REAL8 *f_max,                          /**< [out] ending GW frequency (Hz) */
     REAL8 *f_ref,                          /**< [out] reference frequency (Hz) */
-    LALDict *params                        /**< Input lal dictionary with ChooseTDwaveform parameters **/
+    LALDict *params                        /**< Input lal dictionary with waveform (and optional) parameters **/
 )
 {
 
@@ -603,23 +676,26 @@ void XLALSimInspiralParseDictionaryToChooseFDWaveform(
     return;
 }
 
+/**
+ * Insert all the input arguments needed by XLALSimInspiralChooseFDModes() into a laldictionary.
+ */
 void XLALSimInspiralParseDictionaryToChooseFDModes(
-    REAL8 *m1,
-    REAL8 *m2,
-    REAL8 *S1x,
-    REAL8 *S1y,
-    REAL8 *S1z,
-    REAL8 *S2x,
-    REAL8 *S2y,
-    REAL8 *S2z,
-    REAL8 *deltaF,
-    REAL8 *f_min,
-    REAL8 *f_max,
-    REAL8 *f_ref,
-    REAL8 *phiRef,
-    REAL8 *distance,
-    REAL8 *inclination,
-    LALDict *params
+    REAL8 *m1,                                   /**< [out] mass of companion 1 (kg) */
+    REAL8 *m2,                                   /**< [out] mass of companion 2 (kg) */
+    REAL8 *S1x,                                  /**< [out] x-component of the dimensionless spin of object 1 */
+    REAL8 *S1y,                                  /**< [out] y-component of the dimensionless spin of object 1 */
+    REAL8 *S1z,                                  /**< [out] z-component of the dimensionless spin of object 1 */
+    REAL8 *S2x,                                  /**< [out] x-component of the dimensionless spin of object 2 */
+    REAL8 *S2y,                                  /**< [out] y-component of the dimensionless spin of object 2 */
+    REAL8 *S2z,                                  /**< [out] z-component of the dimensionless spin of object 2 */
+    REAL8 *deltaF,                               /**< [out] sampling interval (s) */
+    REAL8 *f_min,                                /**< [out] starting GW frequency (Hz) */
+    REAL8 *f_max,                                /**< [out] ending GW frequency (Hz) */
+    REAL8 *f_ref,                                /**< [out] reference GW frequency (Hz) */
+    REAL8 *phiRef,                               /**< [out] reference phase (rad) */
+    REAL8 *distance,                             /**< [out] distance of source (m) */
+    REAL8 *inclination,                          /**< [out] inclination of source (rad) */
+    LALDict *params                              /**< Input lal dictionary with waveform (and optional) parameters **/
 )
 {
     *m1 = XLALSimInspiralWaveformParamsLookupMass1(params);
@@ -643,12 +719,9 @@ void XLALSimInspiralParseDictionaryToChooseFDModes(
 
 
 
-/**
- * @addtogroup LALSimInspiral_c
- * @brief General routines for generating binary inspiral waveforms.
- *
- * @{
- */
+
+ 
+ /** @} */
 
 /**
  * @name General Waveform Switching Generation Routines