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/LALSimInspiralGeneratorLegacy.c

@@ -1216,7 +1216,7 @@ static int XLALSimInspiralChooseTDWaveform_legacy(
 
     case IMRPhenomXO4a:
     	 		polariz = 0;
-    			ret = XLALSimInspiralTDFromFD(hplus, hcross, m1, m2, S1x, S1y, S1z, S2x, S2y, S2z, distance, inclination, phiRef, longAscNodes, eccentricity, meanPerAno, deltaT, f_min, f_ref, LALparams, approximant);
+    			ret = XLALSimInspiralTDFromFD(hplus, hcross, m1, m2, S1x, S1y, S1z, S2x, S2y, S2z, distance, inclination, phiRef, longAscNodes, eccentricity, meanPerAno, deltaT, f_min, f_ref, params, approximant);
     			break;
 
     default:
@@ -2404,24 +2404,25 @@ static int XLALSimInspiralChooseFDWaveform_legacy(
         break;
         
     case IMRPhenomXO4a:
-
-        if (LALparams == NULL){
-            LALparams_aux = XLALCreateDict();
+    {
+        LALDict *params_aux;
+        if (params == NULL){
+            params_aux = XLALCreateDict();
         }
         else{
-            LALparams_aux = XLALDictDuplicate(LALparams);
+            params_aux = XLALDictDuplicate(params);
         }
 
         /* XO4 uses previous version of XHM */
-        XLALSimInspiralWaveformParamsInsertPhenomXHMReleaseVersion(LALparams_aux, 122019);
+        XLALSimInspiralWaveformParamsInsertPhenomXHMReleaseVersion(params_aux, 122019);
 
     		/* Waveform-specific sanity checks */
-    		if( !XLALSimInspiralWaveformParamsFrameAxisIsDefault(LALparams_aux) )
+    		if( !XLALSimInspiralWaveformParamsFrameAxisIsDefault(params_aux) )
     		{
     			/* Default is LAL_SIM_INSPIRAL_FRAME_AXIS_ORBITAL_L : z-axis along direction of orbital angular momentum. */
     			XLAL_ERROR(XLAL_EINVAL, "Non-default LALSimInspiralFrameAxis provided, but this approximant does not use that flag.");
     		}
-    		if(!XLALSimInspiralWaveformParamsModesChoiceIsDefault(LALparams_aux))
+    		if(!XLALSimInspiralWaveformParamsModesChoiceIsDefault(params_aux))
     		{
     			/* Default is (2,2) or l=2 modes. */
     			XLAL_ERROR(XLAL_EINVAL, "Non-default LALSimInspiralModesChoice provided, but this approximant does not use that flag.");
@@ -2442,32 +2443,32 @@ static int XLALSimInspiralChooseFDWaveform_legacy(
     		*/
 
         /* Toggle on PNR angles */
-        if(!XLALDictContains(LALparams_aux, "PNRUseTunedAngles")){
-            XLALSimInspiralWaveformParamsInsertPhenomXPNRUseTunedAngles(LALparams_aux, 1);
+        if(!XLALDictContains(params_aux, "PNRUseTunedAngles")){
+            XLALSimInspiralWaveformParamsInsertPhenomXPNRUseTunedAngles(params_aux, 1);
         }
 
         /* Toggle on tuned coprecessing strain */
-        if(!XLALDictContains(LALparams_aux, "PNRUseTunedCoprec")){
-            XLALSimInspiralWaveformParamsInsertPhenomXPNRUseTunedCoprec(LALparams_aux, 1);
+        if(!XLALDictContains(params_aux, "PNRUseTunedCoprec")){
+            XLALSimInspiralWaveformParamsInsertPhenomXPNRUseTunedCoprec(params_aux, 1);
         }
-        if(!XLALDictContains(LALparams_aux, "PNRForceXHMAlignment")){
-            XLALSimInspiralWaveformParamsInsertPhenomXPNRForceXHMAlignment(LALparams_aux, 0);
+        if(!XLALDictContains(params_aux, "PNRForceXHMAlignment")){
+            XLALSimInspiralWaveformParamsInsertPhenomXPNRForceXHMAlignment(params_aux, 0);
         }
 
         /* Toggle on antisymmetric contributions */
-        if(!XLALDictContains(LALparams_aux, "AntisymmetricWaveform")){
-            XLALSimInspiralWaveformParamsInsertPhenomXAntisymmetricWaveform(LALparams_aux, 1);
+        if(!XLALDictContains(params_aux, "AntisymmetricWaveform")){
+            XLALSimInspiralWaveformParamsInsertPhenomXAntisymmetricWaveform(params_aux, 1);
         }
 
-        if(XLALSimInspiralWaveformParamsLookupPhenomXAntisymmetricWaveform(LALparams_aux))
+        if(XLALSimInspiralWaveformParamsLookupPhenomXAntisymmetricWaveform(params_aux))
         {
-            if(!XLALSimInspiralWaveformParamsLookupPhenomXPNRUseTunedAngles(LALparams_aux))
+            if(!XLALSimInspiralWaveformParamsLookupPhenomXPNRUseTunedAngles(params_aux))
             {
                 XLAL_ERROR(XLAL_EFUNC,"Error: Antisymmetric waveform generation not supported without PNR angles, please turn on PNR angles to produce waveform with asymmetries in the (2,2) and (2,-2) modes \n");
             }
         }
 
-    		usemodes = XLALSimInspiralWaveformParamsLookupPhenomXPHMUseModes(LALparams_aux);
+    		usemodes = XLALSimInspiralWaveformParamsLookupPhenomXPHMUseModes(params_aux);
 
     		if(usemodes == 0){
     			ret = XLALSimIMRPhenomXPHM(
@@ -2476,7 +2477,7 @@ static int XLALSimInspiralChooseFDWaveform_legacy(
     				S1x, S1y, S1z,
     				S2x, S2y, S2z,
     				distance, inclination,
-    				phiRef, f_min, f_max, deltaF, f_ref, LALparams_aux
+    				phiRef, f_min, f_max, deltaF, f_ref, params_aux
     			);
     		}
     		else{
@@ -2486,11 +2487,11 @@ static int XLALSimInspiralChooseFDWaveform_legacy(
     				S1x, S1y, S1z,
     				S2x, S2y, S2z,
     				distance, inclination,
-    				phiRef, f_min, f_max, deltaF, f_ref, LALparams_aux
+    				phiRef, f_min, f_max, deltaF, f_ref, params_aux
     			);
     		}
 
-        XLALDestroyDict(LALparams_aux);
+        XLALDestroyDict(params_aux);
 
 
     		if (ret == XLAL_FAILURE)
@@ -2499,7 +2500,7 @@ static int XLALSimInspiralChooseFDWaveform_legacy(
     		}
 
     		break;
-
+    }
     default:
         XLALPrintError("FD version of approximant not implemented in lalsimulation\n");
         XLAL_ERROR(XLAL_EINVAL);
@@ -3118,57 +3119,57 @@ static SphHarmFrequencySeries *XLALSimInspiralChooseFDModes_legacy(
         break;
 
     case IMRPhenomXO4a:
-        if (LALparams == NULL){
-            LALparams_aux = XLALCreateDict();
+        if (params == NULL){
+            params_aux = XLALCreateDict();
         }
         else{
-            LALparams_aux = XLALDictDuplicate(LALparams);
+            params_aux = XLALDictDuplicate(params);
         }
 
         /* XO4 uses previous version of XHM */
-        XLALSimInspiralWaveformParamsInsertPhenomXHMReleaseVersion(LALparams_aux, 122019);
+        XLALSimInspiralWaveformParamsInsertPhenomXHMReleaseVersion(params_aux, 122019);
 
   			/* Waveform-specific sanity checks */
-  			if( !XLALSimInspiralWaveformParamsFlagsAreDefault(LALparams_aux) )
+  			if( !XLALSimInspiralWaveformParamsFlagsAreDefault(params_aux) )
   					XLAL_ERROR_NULL(XLAL_EINVAL, "Non-default flags given, but this approximant does not support this case.");
   			if( !checkTidesZero(lambda1, lambda2) )
   					XLAL_ERROR_NULL(XLAL_EINVAL, "Non-zero tidal parameters were given, but this is approximant doe not have tidal corrections.");
 
         /* Toggle on PNR angles */
-        if(!XLALDictContains(LALparams_aux, "PNRUseTunedAngles")){
-            XLALSimInspiralWaveformParamsInsertPhenomXPNRUseTunedAngles(LALparams_aux, 1);
+        if(!XLALDictContains(params_aux, "PNRUseTunedAngles")){
+            XLALSimInspiralWaveformParamsInsertPhenomXPNRUseTunedAngles(params_aux, 1);
         }
 
         /* Toggle on tuned coprecessing strain */
-        if(!XLALDictContains(LALparams_aux, "PNRUseTunedCoprec")){
-            XLALSimInspiralWaveformParamsInsertPhenomXPNRUseTunedCoprec(LALparams_aux, 1);
+        if(!XLALDictContains(params_aux, "PNRUseTunedCoprec")){
+            XLALSimInspiralWaveformParamsInsertPhenomXPNRUseTunedCoprec(params_aux, 1);
         }
 
         /* Ensure that 33 tuning is set to preferred value */
-        if(!XLALDictContains(LALparams_aux, "PNRUseTunedCoprec33")){
-            XLALSimInspiralWaveformParamsInsertPhenomXPNRUseTunedCoprec33(LALparams_aux, 0);
+        if(!XLALDictContains(params_aux, "PNRUseTunedCoprec33")){
+            XLALSimInspiralWaveformParamsInsertPhenomXPNRUseTunedCoprec33(params_aux, 0);
         }
-        if(!XLALDictContains(LALparams_aux, "PNRForceXHMAlignment")){
-            XLALSimInspiralWaveformParamsInsertPhenomXPNRForceXHMAlignment(LALparams_aux, 0);
+        if(!XLALDictContains(params_aux, "PNRForceXHMAlignment")){
+            XLALSimInspiralWaveformParamsInsertPhenomXPNRForceXHMAlignment(params_aux, 0);
         }
 
         /* Toggle on antisymmetric contributions */
-        if(!XLALDictContains(LALparams_aux, "AntisymmetricWaveform")){
-            XLALSimInspiralWaveformParamsInsertPhenomXAntisymmetricWaveform(LALparams_aux, 1);
+        if(!XLALDictContains(params_aux, "AntisymmetricWaveform")){
+            XLALSimInspiralWaveformParamsInsertPhenomXAntisymmetricWaveform(params_aux, 1);
         }
 
-        if(XLALSimInspiralWaveformParamsLookupPhenomXAntisymmetricWaveform(LALparams_aux))
+        if(XLALSimInspiralWaveformParamsLookupPhenomXAntisymmetricWaveform(params_aux))
         {
-            if(!XLALSimInspiralWaveformParamsLookupPhenomXPNRUseTunedAngles(LALparams_aux))
+            if(!XLALSimInspiralWaveformParamsLookupPhenomXPNRUseTunedAngles(params_aux))
             {
                 XLAL_ERROR_NULL(XLAL_EFUNC,"Error: Antisymmetric waveform generation not supported without PNR angles, please turn on PNR angles to produce waveform with asymmetries in the (2,2) and (2,-2) modes \n");
             }
         }
 
 	      /* Compute individual modes in the J-frame from IMRPhenomXPHM */
-        XLALSimIMRPhenomXPHMModes(&hlms, m1, m2, S1x, S1y, S1z,	S2x, S2y, S2z, deltaF, f_min, f_max, f_ref, phiRef, distance, inclination, LALparams_aux);
+        XLALSimIMRPhenomXPHMModes(&hlms, m1, m2, S1x, S1y, S1z,	S2x, S2y, S2z, deltaF, f_min, f_max, f_ref, phiRef, distance, inclination, params_aux);
 
-        XLALDestroyDict(LALparams_aux);
+        XLALDestroyDict(params_aux);
 
         break;