LALSimIMRNRHybSur3dq8.c File Reference

C code for NRHybSur3dq8 waveform model, an NR-hybrid surrogate model for aligned-spin BBH. More...

Prototypes
static bool	NRHybSur3dq8_IsSetup (void)
	Helper function to check if the NRHybSur3dq8 model has been initialized. More...
static void	NRHybSur3dq8_Init_LALDATA (void)
	Surrogate initialization. More...
int	NRHybSur3dq8_fitParams (gsl_vector *fit_params, const REAL8 q, const REAL8 chi1z, const REAL8 chi2z)
	Map from mass ratio and spins to surrogate fit parameters. More...
int	NRHybSur3dq8_core (gsl_vector **phi_22, EvaluatedDataPieces **evaluated_mode_dps, LIGOTimeGPS *epoch, const REAL8 deltaT, const REAL8 fMin, const REAL8 fRef, REAL8 q, const REAL8 Mtot_sec, REAL8 chi1z, REAL8 chi2z, LALValue *ModeArray, LALDict *LALparams)
	This is the core function of the NRHybSur3dq8 model. More...
INT4	XLALSimIMRNRHybSur3dq8Polarizations (REAL8TimeSeries **hplus, REAL8TimeSeries **hcross, REAL8 phiRef, REAL8 inclination, REAL8 deltaT, REAL8 m1, REAL8 m2, REAL8 distance, REAL8 fMin, REAL8 fRef, REAL8 chi1z, REAL8 chi2z, LALDict *LALparams)
	Reference: arxiv:1812.07865. More...
SphHarmTimeSeries *	XLALSimIMRNRHybSur3dq8Modes (REAL8 deltaT, REAL8 m1, REAL8 m2, REAL8 chi1z, REAL8 chi2z, REAL8 fMin, REAL8 fRef, REAL8 distance, LALDict *LALparams)
	Reference: arxiv:1812.07865. More...

Detailed Description

C code for NRHybSur3dq8 waveform model, an NR-hybrid surrogate model for aligned-spin BBH.

Author

Vijay Varma

The binary data file is available at https://dcc.ligo.org/LIGO-T1900034. Get the lalsuite-extra repo or put the data into a location in your LAL_DATA_PATH.

Paper: https://arxiv.org/abs/1812.07865

Parameter ranges:

q = [1, 10.1] and \(\chi_{1z}, \chi_{2z}\) = [-0.81, 0.81] or q = [1, 9.1] and \(\chi_{1z}, \chi_{2z}\) = [-0.91, 0.91]

modes: \( \ell \leq 4, m \geq 0 \), and (5,5), but not (4,1) or (4,0). m<0 modes are determined from the m \(\geq0\) modes.

\(M \geq 2.25 M_{\odot} \), for fstart=20Hz, for all modes.

Training parameter ranges:

q = [1, 8]

\(\chi_{1z}, \chi_{2z}\) = [-0.8, 0.8]

But extrapolates reasonably to the above mass ratios and spins.

Definition in file LALSimIMRNRHybSur3dq8.c.

Go to the source code of this file.

Variables
static NRHybSurData	__lalsim_NRHybSur3dq8_data
	Global surrogate data. More...

Function Documentation

NRHybSur3dq8_IsSetup()

static bool NRHybSur3dq8_IsSetup ( void  )

static

Helper function to check if the NRHybSur3dq8 model has been initialized.

Definition at line 95 of file LALSimIMRNRHybSur3dq8.c.

NRHybSur3dq8_Init_LALDATA()

static void NRHybSur3dq8_Init_LALDATA ( void  )

static

Surrogate initialization.

This needs to be called once, before __lalsim_NRHybSur3dq8_data is used. It finds the H5 data file with the NRHybSur3dq8 data and loads the surrogate. Can be called multiple times, will just return true if surrogate is already loaded.

Definition at line 111 of file LALSimIMRNRHybSur3dq8.c.

NRHybSur3dq8_fitParams()

int NRHybSur3dq8_fitParams	(	gsl_vector *	fit_params,
		const REAL8	q,
		const REAL8	chi1z,
		const REAL8	chi2z
	)

Map from mass ratio and spins to surrogate fit parameters.

The fit parameters are \([log_e(q), \hat{\chi}, \chi_a]\). \(\hat{\chi}\) is defined in Eq.(46) of arxiv:1812.07865. \(\chi_a = (\chi_{1z} - \chi_{2z})/2 \). These are described in Sec.VI.C.3 of arxiv:1812.07865.

Parameters

fit_params	Output: mapped fit parameters.
q	Mass ratio m1 / m2 >= 1.
chi1z	Dimless spin of heavier BH.
chi2z	Dimless spin of lighter BH.

Definition at line 155 of file LALSimIMRNRHybSur3dq8.c.

NRHybSur3dq8_core()

int NRHybSur3dq8_core	(	gsl_vector **	phi_22,
		EvaluatedDataPieces **	evaluated_mode_dps,
		LIGOTimeGPS *	epoch,
		const REAL8	deltaT,
		const REAL8	fMin,
		const REAL8	fRef,
		REAL8	q,
		const REAL8	Mtot_sec,
		REAL8	chi1z,
		REAL8	chi2z,
		LALValue *	ModeArray,
		LALDict *	LALparams
	)

This is the core function of the NRHybSur3dq8 model.

It evaluates all required waveform modes. For each mode, it evaluates each waveform data piece. The different data pieces are described in Sec.VI.B of arxiv:1812.07865. For the (2,2) mode the data pieces are the amplitude and phase. Note that we model the phase residual but add back the 0PN term at evaluation time. For all other modes the data pieces are the real and imaginary parts of the strain in the coorbital frame.

The reference point is the time at which the (2,2) mode frequency equals fRef. If fRef=0, sets fRef=fMin. We set the orbital phase to 0 at the reference point. The orbital phase is obtained as \(\phi_{22}/2\), so this leaves a pi ambiguity. But the surrogate data is already aligned such that the heavier BH is on the +ve x-axis at t=-1000M. See Sec.VI.A.4 of arxiv:1812.07865. This resolves the pi ambiguity. This means that after the realignment, the orbital phase at reference frequency fRef is 0, or Bh1 is on the +ve x-axis. Note that this is alignment is done using only waveform quantities, so this doesn't necessarily correspond to the (gauge dependent) NR Bh trajectories. The modes are returned in this frame, which agrees with the LAL convention. When combining the modes to get the polarizations, the Ylms should be evaluated at (inclination, pi/2 - phiRef), following the LAL convention.

Only uses data at (2,2) mode frequencies >= fMin. This determines the start time. The start time, along with the step size deltaT, is used to determine the output_times. Uses cubic spline interpolation to interpolate from the surrogate's time array to output_times.

NOTE: If mass ratio q<1, the labels of the two BHs are swapped internally.

Returned values:

phi_22: contains the phase of the (2,2) mode. This is always evaluated as this is required for other modes as well to transform from coorbital frame to inertial frame.

evaluated_mode_dps: Contains all other data pieces. This is a list of size num_modes_incl, the number of modes to include. For each mode this contains the amplitude, and real and imaginary parts of the coorbital frame strain. For the (2,2) mode only the amplitude is required. For all other modes only the coorbital frame strain is required. So, we evaluate only the required data pieces of each mode. The amplitude and coorbital frame strain is in units of rh/M and needs to be rescaled to physical units.

epoch: Initial time value, w.r.t. the peak (t=0 at the peak) of the total waveform amplitude, as defined in Eq.38 of arxiv:1812.07865.

Parameters

phi_22	Output: phase of (2,2) mode.
evaluated_mode_dps	Output: All other data pieces.
epoch	Output: Initial time value, where t=0 is at the peak of the total waveform amplitude.
deltaT	Sampling interval (s).
fMin	Start GW frequency (Hz).
fRef	Reference GW frequency (Hz).
q	Mass ratio m1/m2.
Mtot_sec	Total mass in geometric units (s).
chi1z	Dimensionless spin of Bh1.
chi2z	Dimensionless spin of Bh2.
ModeArray	Container for (ell, m) modes to generate.
LALparams	Dict with extra parameters

Definition at line 230 of file LALSimIMRNRHybSur3dq8.c.

XLALSimIMRNRHybSur3dq8Polarizations()

INT4 XLALSimIMRNRHybSur3dq8Polarizations	(	REAL8TimeSeries **	hplus,
		REAL8TimeSeries **	hcross,
		REAL8	phiRef,
		REAL8	inclination,
		REAL8	deltaT,
		REAL8	m1,
		REAL8	m2,
		REAL8	distance,
		REAL8	fMin,
		REAL8	fRef,
		REAL8	chi1z,
		REAL8	chi2z,
		LALDict *	LALparams
	)

Reference: arxiv:1812.07865.

Evaluates the NRHybSur3dq8 surrogate model and combines different modes to obtain the plus and cross polarizations.

Returns the plus and cross polarizations of NRHybSur3dq8 waveform model.

The reference point is the time at which the (2,2) mode frequency equals fRef. If fRef=0, sets fRef=fMin. We set the orbital phase to 0 at the reference point. The orbital phase is obtained as \(\phi_{22}/2\), so this leaves a pi ambiguity. But the surrogate data is already aligned such that the heavier BH is on the +ve x-axis at t=-1000M. See Sec.VI.A.4 of arxiv:1812.07865. This resolves the pi ambiguity. This means that after the realignment, the orbital phase at reference frequency fRef is 0, or Bh1 is on the +ve x-axis. Note that this is alignment is done using only waveform quantities, so this doesn't necessarily correspond to the (gauge dependent) NR Bh trajectories. The polarizations of the waveform are returned in the sky of this frame at (inclination, pi/2 - phiRef). This agrees with the LAL convention.

Only uses data at (2,2) mode frequencies >= fMin. This determines the start time. The start time, along with the step size deltaT, is used to determine the output_times. Uses cubic spline interpolation to interpolate from the surrogate's time array to output_times.

By default, uses all available modes of the surrogate, that is \( \ell \leq 4, m \geq 0 \), and (5,5), but not (4,1) or (4,0). For m>0 modes, the contribution from the m<0 counterparts is automatically added.

If a custom ModeArray is given, only those modes are used. Note that it only looks for m>=0 modes in ModeArray, and will ignore m<0 modes even if present. The m<0 modes automatically get added.

This surrogate model is trained on the following range. q <= 8, |chi_1|, |chi_2| <= 0.8 If you want a guarantee of accuracy you should stick to the above ranges.

We allow extrapolation to the following ranges, but with a warning: q = [1, 10.1] and \(\chi_{1z}, \chi_{2z}\) = [-0.81, 0.81] or q = [1, 9.1] and \(\chi_{1z}, \chi_{2z}\) = [-0.91, 0.91] We expect the model to be reasonable when extrapolated to these ranges.

Beyond the above ranges, we raise an error. If you want to extrapolate beyond these limits you can specify unlimited_extrapolation = 1 in your dictParams as follows:

USE AT YOUR OWN RISK!!

lal.DictInsertUINT4Value(dictParams, "unlimited_extrapolation", 1)

Parameters

hplus	Output: \(h_+\) polarization.
hcross	Output: \(h_{\times}\) polarization.
phiRef	azimuthal angle for Ylms
inclination	Inclination angle.
deltaT	Sampling interval (s).
m1	Mass of Bh1 (kg).
m2	Mass of Bh2 (kg).
distance	Distance of source (m).
fMin	Start GW frequency (Hz).
fRef	Reference GW frequency (Hz).
chi1z	Dimensionless spin of Bh1.
chi2z	Dimensionless spin of Bh2.
LALparams	Dict with extra parameters

Definition at line 477 of file LALSimIMRNRHybSur3dq8.c.

XLALSimIMRNRHybSur3dq8Modes()

SphHarmTimeSeries* XLALSimIMRNRHybSur3dq8Modes	(	REAL8	deltaT,
		REAL8	m1,
		REAL8	m2,
		REAL8	chi1z,
		REAL8	chi2z,
		REAL8	fMin,
		REAL8	fRef,
		REAL8	distance,
		LALDict *	LALparams
	)

Reference: arxiv:1812.07865.

Evaluates the NRHybSur3dq8 surrogate model and returns all required modes.

Returns the spin-weighted spherical harmonic modes of NRHybSur3dq8 waveform model.

The reference point is the time at which the (2,2) mode frequency equals fRef. If fRef=0, sets fRef=fMin. We set the orbital phase to 0 at the reference point. The orbital phase is obtained as \(\phi_{22}/2\), so this leaves a pi ambiguity. But the surrogate data is already aligned such that the heavier BH is on the +ve x-axis at t=-1000M. See Sec.VI.A.4 of arxiv:1812.07865. This resolves the pi ambiguity. This means that after the realignment, the orbital phase at reference frequency fRef is 0, or Bh1 is on the +ve x-axis. Note that this is alignment is done using only waveform quantities, so this doesn't necessarily correspond to the (gauge dependent) NR Bh trajectories. The modes are returned in this frame, which agrees with the LAL convention. When combining the modes to get the polarizations, the Ylms should be evaluated at (inclination, pi/2 - phiRef), following the LAL convention.

Only uses data at (2,2) mode frequencies >= fMin. This determines the start time. The start time, along with the step size deltaT, is used to determine the output_times. Uses cubic spline interpolation to interpolate from the surrogate's time array to output_times.

By default, returns all available modes of the surrogate, that is \( \ell \leq 4, m \geq 0 \), and (5,5), but not (4,1) or (4,0).

If a custom ModeArray is given, only those modes are used. Note that it only looks for m>=0 modes in ModeArray, and will ignore m<0 modes even if present.

This surrogate model is trained on the following range. q <= 8, |chi_1|, |chi_2| <= 0.8 If you want a guarantee of accuracy you should stick to the above ranges.

We allow extrapolation to the following ranges, but with a warning: q = [1, 10.1] and \(\chi_{1z}, \chi_{2z}\) = [-0.81, 0.81] or q = [1, 9.1] and \(\chi_{1z}, \chi_{2z}\) = [-0.91, 0.91] We expect the model to be reasonable when extrapolated to these ranges.

Beyond the above ranges, we raise an error. If you want to extrapolate beyond these limits you can specify unlimited_extrapolation = 1 in your dictParams as follows:

USE AT YOUR OWN RISK!!

lal.DictInsertUINT4Value(dictParams, "unlimited_extrapolation", 1)

Parameters

deltaT	Sampling interval (s).
m1	Mass of Bh1 (kg).
m2	Mass of Bh2 (kg).
chi1z	Dimensionless spin of Bh1.
chi2z	Dimensionless spin of Bh2.
fMin	Start GW frequency (Hz).
fRef	Reference GW frequency (Hz).
distance	Distance of source (m).
LALparams	Dict with extra parameters

Definition at line 731 of file LALSimIMRNRHybSur3dq8.c.

Variable Documentation

__lalsim_NRHybSur3dq8_data

NRHybSurData __lalsim_NRHybSur3dq8_data

static

Global surrogate data.

This data will be loaded at most once. Any executable which calls NRHybSur3dq8_Init_LALDATA directly or by calling any XLAL NRHybSur3dq8 function will have a memory leak according to valgrind, because we never free this memory.

Definition at line 86 of file LALSimIMRNRHybSur3dq8.c.