pyseobnr.generate_waveform.GenerateWaveform

class pyseobnr.generate_waveform.GenerateWaveform(parameters)[source]

Bases: object

Class for generating modes, time-domain polarizations and frequency-domain polarizations following LAL conventions.

Initialize the class with the given parameters.

parameters is a dictionary whose keys are defined as follows:

Parameters:

mass1 (float) – Mass of companion 1, in solar masses - Required
mass2 (float) – Mass of companion 2, in solar masses - Required
spin1x (float) – x-component of dimensionless spin of companion 1 - Default: 0
spin1y (float) – y-component of dimensionless spin of companion 1 - Default: 0
spin1z (float) – z-component of dimensionless spin of companion 1 - Default: 0
spin2x (float) – x-component of dimensionless spin of companion 2 - Default: 0
spin2y (float) – y-component of dimensionless spin of companion 2 - Default: 0
spin2z (float) – z-component of dimensionless spin of companion 2 - Default: 0
eccentricity (float) – Keplerian eccentricity of the orbit - Default: 0
rel_anomaly (float) – Relativistic anomaly - Default: 0
distance (float) – Distance to the source, in Mpc - Default: 100 Mpc
inclination (float) – Inclination of the source, in radians - Default: 0
phi_ref (float) – Orbital phase at the reference frequency, in radians - Default: 0
f22_start (float) – Starting waveform generation frequency, in Hz - Default: 20 Hz
f_ref (float) – The reference frequency, in Hz - Default: f22_start
deltaT (float) – Time spacing, in seconds - Default: 1/2048 seconds
f_max (float) – Maximum frequency, in Hz - Default: 1024 Hz
deltaF (float) – Frequency spacing, in Hz - Default: 0.125
ModeArray (list)
mode_array (list) – Mode content (only positive must be specified, e.g [(2,2),(2,1)]). Defaults to None (all modes, see notes below).
domega_dict (dict) – The non-GR fractional deviation to the frequencies for each mode.
dA_dict (dict) – The non-GR fractional deviation to the merger amplitudes for each mode.
dw_dict (dict) – The non-GR fractional deviation to the merger frequencies.
dtau_dict (dict) – The non-GR fractional deviation to the damping times for each mode. Values should be \(> -1\).
dTpeak (float) – The non-GR additive deviation to the amplitude’s peak time.
da6 (float) – The non-GR additive deviation to the a6 calibration parameter.
ddSO (float) – The non-GR additive deviation to the dSO calibration parameter.
deltaT_sampling (bool) – If set to True, throws an error if the the attachment time induced by negative values of the deviation dTpeak is beyond the last point calculated from the dynamics. In those cases, the attachment time is set to be the last point of the dynamics. Setting the parameter to True prevents having incorrect posteriors when sampling over dTpeak, as those parameters would be rejected. Needs to be set to True if dTpeak is non-zero. Defaults to False.
omega_prec_deviation (bool) – If True (default), the fractional deviations to the J-frame QNM frequencies are included into the precession rate computation (Eq. 13 in arXiv:2301.06558 ).
initial_conditions (str) – Possible values are adiabatic (default) and postadiabatic. Used only for approximant="SEOBNRv5PHM" and postadiabatic is False.
initial_conditions_postadiabatic_type (str) – Possible values are analytic (default) and numeric. Used together with initial_conditions.
postadiabatic (bool) – Defaults to True.
postadiabatic_type (str) – Either analytic (default) or numeric. Used only when postadiabatic is True.
tol_PA (float) – Tolerance for the root finding routine in case postadiabatic_type="numeric" is used. Defaults to 1e-11.
lmax (int) – If specified, will add all the modes compatible with the approximant up to \(\ell =\) lmax. If provided together with mode_array, the two parameters should be set consistently. See the notes for details.
enable_antisymmetric_modes (bool) – when True will enable the handling of the anti-symmetric modes. Available only for the precessing approximant SEOBNRv5PHM.
list[tuple[int – Select the modes for which the anti-symmetric processing is active.
antisymmetric_modes (int]]) – Select the modes for which the anti-symmetric processing is active.
antisymmetric_modes_hm (bool) – if set to True, will enable the higher modes (3,3) and (4,4) for the anti-symmetric modes corrections. Overrides antisymmetric_modes.
approximant (str) –
- SEOBNRv5HM (default)
- SEOBNRv5PHM
- SEOBNRv5EHM
rtol_ode (float) – Relative tolerance of the ODE integrators. Defaults to 1e-11.
atol_ode (float) – Absolute tolerance of the ODE integrators. Defaults to 1e-12.
gwsignal_environment (bool) – if set and evaluates to True, indicates that the code is being run through GWSignal or environment requiring compliance with LVK reviews. Defaults to False.
convention_coprecessing_phase22_set_to_0_at_reference_frequency (bool) – if set and evaluates to True, indicates that we are using the convention where the phase of the 2,2 mode at reference frequency is set to 0.
convention_t0_set_to_0_at_coprecessing_amplitude22_peak (bool) – if set and evaluates to True, indicates that we are using the convention where the 0 of the time array is set to when the amplitude of the 2,2 mode is at its peak.

Note

The default modes are (2, 2), (2, 1), (3, 3), (3, 2), (4, 4) and (4, 3). In particular (5, 5) is not included and should be explicitly set through ModeArray.

All GR deviations default to 0. For the dictionaries domega_dict, dA_dict, dw_dict, dtau_dict, keys are the modes l,m as a string, for \(\ell > 0\). For a description of the non-GR deviation parameters, see Section II of [Pompili2025].

If lmax is set, it will activate all the supported modes for the selected approximant up until \(\ell =\) lmax. If specified together with mode_array, then the selected modes from lmax should be the same as the ones provides in mode_array, otherwise a ValueError exception is raised. For instance, lmax=3 and mode_array=[(2, 2), (3, 2)] will create inconsistencies for the selection of the modes (2, 1) and (3, 3).

Setting conventions different from the default ones is not necessarily supported by all approximants.

__init__(parameters)[source]

Initialize the class with the given parameters.

parameters is a dictionary whose keys are defined as follows:

Parameters:

mass1 (float) – Mass of companion 1, in solar masses - Required
mass2 (float) – Mass of companion 2, in solar masses - Required
spin1x (float) – x-component of dimensionless spin of companion 1 - Default: 0
spin1y (float) – y-component of dimensionless spin of companion 1 - Default: 0
spin1z (float) – z-component of dimensionless spin of companion 1 - Default: 0
spin2x (float) – x-component of dimensionless spin of companion 2 - Default: 0
spin2y (float) – y-component of dimensionless spin of companion 2 - Default: 0
spin2z (float) – z-component of dimensionless spin of companion 2 - Default: 0
eccentricity (float) – Keplerian eccentricity of the orbit - Default: 0
rel_anomaly (float) – Relativistic anomaly - Default: 0
distance (float) – Distance to the source, in Mpc - Default: 100 Mpc
inclination (float) – Inclination of the source, in radians - Default: 0
phi_ref (float) – Orbital phase at the reference frequency, in radians - Default: 0
f22_start (float) – Starting waveform generation frequency, in Hz - Default: 20 Hz
f_ref (float) – The reference frequency, in Hz - Default: f22_start
deltaT (float) – Time spacing, in seconds - Default: 1/2048 seconds
f_max (float) – Maximum frequency, in Hz - Default: 1024 Hz
deltaF (float) – Frequency spacing, in Hz - Default: 0.125
ModeArray (list)
mode_array (list) – Mode content (only positive must be specified, e.g [(2,2),(2,1)]). Defaults to None (all modes, see notes below).
domega_dict (dict) – The non-GR fractional deviation to the frequencies for each mode.
dA_dict (dict) – The non-GR fractional deviation to the merger amplitudes for each mode.
dw_dict (dict) – The non-GR fractional deviation to the merger frequencies.
dtau_dict (dict) – The non-GR fractional deviation to the damping times for each mode. Values should be \(> -1\).
dTpeak (float) – The non-GR additive deviation to the amplitude’s peak time.
da6 (float) – The non-GR additive deviation to the a6 calibration parameter.
ddSO (float) – The non-GR additive deviation to the dSO calibration parameter.
deltaT_sampling (bool) – If set to True, throws an error if the the attachment time induced by negative values of the deviation dTpeak is beyond the last point calculated from the dynamics. In those cases, the attachment time is set to be the last point of the dynamics. Setting the parameter to True prevents having incorrect posteriors when sampling over dTpeak, as those parameters would be rejected. Needs to be set to True if dTpeak is non-zero. Defaults to False.
omega_prec_deviation (bool) –
If True (default), the fractional deviations to the J-frame QNM frequencies are included into the precession rate computation (Eq. 13 in arXiv:2301.06558 ).
initial_conditions (str) – Possible values are adiabatic (default) and postadiabatic. Used only for approximant="SEOBNRv5PHM" and postadiabatic is False.
initial_conditions_postadiabatic_type (str) – Possible values are analytic (default) and numeric. Used together with initial_conditions.
postadiabatic (bool) – Defaults to True.
postadiabatic_type (str) – Either analytic (default) or numeric. Used only when postadiabatic is True.
tol_PA (float) – Tolerance for the root finding routine in case postadiabatic_type="numeric" is used. Defaults to 1e-11.
lmax (int) – If specified, will add all the modes compatible with the approximant up to \(\ell =\) lmax. If provided together with mode_array, the two parameters should be set consistently. See the notes for details.
enable_antisymmetric_modes (bool) – when True will enable the handling of the anti-symmetric modes. Available only for the precessing approximant SEOBNRv5PHM.
list[tuple[int – Select the modes for which the anti-symmetric processing is active.
antisymmetric_modes (int]]) – Select the modes for which the anti-symmetric processing is active.
antisymmetric_modes_hm (bool) – if set to True, will enable the higher modes (3,3) and (4,4) for the anti-symmetric modes corrections. Overrides antisymmetric_modes.
approximant (str) –
- SEOBNRv5HM (default)
- SEOBNRv5PHM
- SEOBNRv5EHM
rtol_ode (float) – Relative tolerance of the ODE integrators. Defaults to 1e-11.
atol_ode (float) – Absolute tolerance of the ODE integrators. Defaults to 1e-12.
gwsignal_environment (bool) – if set and evaluates to True, indicates that the code is being run through GWSignal or environment requiring compliance with LVK reviews. Defaults to False.
convention_coprecessing_phase22_set_to_0_at_reference_frequency (bool) – if set and evaluates to True, indicates that we are using the convention where the phase of the 2,2 mode at reference frequency is set to 0.
convention_t0_set_to_0_at_coprecessing_amplitude22_peak (bool) – if set and evaluates to True, indicates that we are using the convention where the 0 of the time array is set to when the amplitude of the 2,2 mode is at its peak.

Note

The default modes are (2, 2), (2, 1), (3, 3), (3, 2), (4, 4) and (4, 3). In particular (5, 5) is not included and should be explicitly set through ModeArray.

All GR deviations default to 0. For the dictionaries domega_dict, dA_dict, dw_dict, dtau_dict, keys are the modes l,m as a string, for \(\ell > 0\). For a description of the non-GR deviation parameters, see Section II of [Pompili2025].

If lmax is set, it will activate all the supported modes for the selected approximant up until \(\ell =\) lmax. If specified together with mode_array, then the selected modes from lmax should be the same as the ones provides in mode_array, otherwise a ValueError exception is raised. For instance, lmax=3 and mode_array=[(2, 2), (3, 2)] will create inconsistencies for the selection of the modes (2, 1) and (3, 3).

Setting conventions different from the default ones is not necessarily supported by all approximants.

Methods

`__init__`(parameters)	Initialize the class with the given `parameters`.
`generate_fd_polarizations`()	Generate Fourier-domain polarizations, returned as LAL COMPLEX16FrequencySeries
`generate_td_modes`()	Generate dictionary of positive and negative m modes in physical units.
`generate_td_polarizations`()	Generate time-domain polarizations, returned as LAL REAL8TimeSeries.
`generate_td_polarizations_conditioned_1`()	Generate time-domain polarizations, with tappering at the beginning of the waveform, returned as LAL REAL8TimeSeries.
`generate_td_polarizations_conditioned_2`()	Generate conditioned time-domain polarizations as in SimInspiralTDfromTD routine.

Attributes

model

generate_fd_polarizations()[source]

Generate Fourier-domain polarizations, returned as LAL COMPLEX16FrequencySeries

Routine similar to LAL SimInspiralFD.

This routine assumes that f_max is the Nyquist frequency of the time-domain waveform, so that deltaT = 0.5 / f_max. If deltaF is set to 0 then this routine computes a deltaF that is small enough to represent the Fourier transform of the time-domain waveform while ensuring the length of the time-domain signal if a power of 2.

If deltaF is specified but f_max / deltaF is not a power of 2, then f_max is increased so that f_max / deltaF is the next power of 2. (If the user wishes to discard the extra high frequency content, this must be done separately.)

Warning

The user should take care to ensure that deltaF is sufficiently small to contain the full signal (time series duration = 1 / deltaF). If the provided deltaF is too large the signal will be abruptly truncated.

Similarly, if the provided f_max is less than the ringdown frequency the underlying waveform generator may raise an error. If not, the frequency domain signal will be aliased in the frequency domain.

generate_td_modes()[source]: Generate dictionary of positive and negative m modes in physical units.

generate_td_polarizations()[source]: Generate time-domain polarizations, returned as LAL REAL8TimeSeries.

generate_td_polarizations_conditioned_1()[source]: Generate time-domain polarizations, with tappering at the beginning of the waveform, returned as LAL REAL8TimeSeries.

generate_td_polarizations_conditioned_2()[source]: Generate conditioned time-domain polarizations as in SimInspiralTDfromTD routine.