dingo.gw.waveform_generator package

Submodules

dingo.gw.waveform_generator.frame_utils module

These functions are used for transforming between J and L0 frames.

dingo.gw.waveform_generator.frame_utils.convert_J_to_L0_frame(hlm_J, p, wfg, spin_conversion_phase=None)

dingo.gw.waveform_generator.frame_utils.get_JL0_euler_angles(p, wfg, spin_conversion_phase=None)

dingo.gw.waveform_generator.frame_utils.rotate_y(angle, vx, vy, vz)

dingo.gw.waveform_generator.frame_utils.rotate_z(angle, vx, vy, vz)

dingo.gw.waveform_generator.waveform_generator module

class dingo.gw.waveform_generator.waveform_generator.NewInterfaceWaveformGenerator(**kwargs)

Bases: WaveformGenerator

Generate polarizations using GWSignal routines in the specified domain for a single GW coalescence given a set of waveform parameters.

Parameters:

• approximant (str) – Waveform “approximant” string understood by lalsimulation This is defines which waveform model is used.

• domain (Domain) – Domain object that specifies on which physical domain the waveform polarizations will be generated, e.g. Fourier domain, time domain.

• f_ref (float) – Reference frequency for the waveforms

• f_start (float) – Starting frequency for waveform generation. This is optional, and if not included, the starting frequency will be set to f_min. This exists so that EOB waveforms can be generated starting from a lower frequency than f_min.

• mode_list (List[Tuple]) – A list of waveform (ell, m) modes to include when generating the polarizations.

• spin_conversion_phase (float = None) – Value for phiRef when computing cartesian spins from bilby spins via bilby_to_lalsimulation_spins. The common convention is to use the value of the phase parameter here, which is also used in the spherical harmonics when combining the different modes. If spin_conversion_phase = None, this default behavior is adapted. For dingo, this convention for the phase parameter makes it impossible to treat the phase as an extrinsic parameter, since we can only account for the change of phase in the spherical harmonics when changing the phase (in order to also change the cartesian spins – specifically, to rotate the spins by phase in the sx-sy plane – one would need to recompute the modes, which is expensive). By setting spin_conversion_phase != None, we impose the convention to always use phase = spin_conversion_phase when computing the cartesian spins.

property domain

generate_FD_modes_LO(parameters)

Generate FD modes in the L0 frame.

Parameters:

parameters (dict) – Dictionary of parameters for the waveform. For details see see self.generate_hplus_hcross.

Returns:

• hlm_fd (dict) – Dictionary with (l,m) as keys and the corresponding FD modes in lal format as values.

• iota (float)

generate_FD_waveform(parameters_gwsignal: Dict) → Dict[str, ndarray]

Generate Fourier domain GW polarizations (h_plus, h_cross).

Parameters:

parameters_lal – A tuple of parameters for the lalsimulation waveform generator

Returns:

A dictionary of generated waveform polarizations

Return type:

pol_dict

generate_TD_modes_L0(parameters)

Generate TD modes in the L0 frame.

Parameters:

parameters (dict) – Dictionary of parameters for the waveform. For details see see self.generate_hplus_hcross.

Returns:

• hlm_td (dict) – Dictionary with (l,m) as keys and the corresponding TD modes in lal format as values.

• iota (float)

generate_TD_modes_L0_conditioned_extra_time(parameters)

Generate TD modes in the L0 frame applying a conditioning routine which mimics the behaviour of the standard LALSimulation conditioning (https://lscsoft.docs.ligo.org/lalsuite/lalsimulation/_l_a_l_sim_inspiral_generator_conditioning_8c.html#ac78b5fcdabf8922a3ac479da20185c85)

Essentially, a new starting frequency is computed to have some extra cycles that will be tapered. Some extra buffer time is also added to ensure that the waveform at the requested starting frequency is not modified, while still having a tapered timeseries suited for clean FFT.

Parameters:

parameters (dict) – Dictionary of parameters for the waveform. For details see self.generate_hplus_hcross.

Returns:

• hlm_td (dict) – Dictionary with (l,m) as keys and the corresponding TD modes in lal format as values.

• iota (float)

generate_TD_waveform(parameters_gwsignal: Dict) → Dict[str, ndarray]

Generate time domain GW polarizations (h_plus, h_cross)

Parameters:

parameters_gwsignal – A dict of parameters for the gwsignal waveform generator

Returns:

A dictionary of generated waveform polarizations

Return type:

pol_dict

generate_hplus_hcross_m(parameters: Dict[str, float]) → Dict[tuple, Dict[str, ndarray]]

Generate GW polarizations (h_plus, h_cross), separated into contributions from the different modes. This method is identical to self.generate_hplus_hcross, except that it generates the individual contributions of the modes to the polarizations and sorts these according to their transformation behavior (see below), instead of returning the overall sum.

This is useful in order to treat the phase as an extrinsic parameter. Instead of {“h_plus”: hp, “h_cross”: hc}, this method returns a dict in the form of {m: {“h_plus”: hp_m, “h_cross”: hc_m} for m in [-l_max,…,0,…,l_max]}. Each key m contains the contribution to the polarization that transforms according to exp(-1j * m * phase) under phase transformations (due to the spherical harmonics).

Note:

• pol_m[m] contains contributions of the m modes and and the -m modes. This is because the frequency domain (FD) modes have a positive frequency part which transforms as exp(-1j * m * phase), while the negative frequency part transforms as exp(+1j * m * phase). Typically, one of these dominates [e.g., the (2,2) mode is dominated by the negative frequency part and the (-2,2) mode is dominated by the positive frequency part] such that the sum of (l,|m|) and (l,-|m|) modes transforms approximately as exp(1j * |m| * phase), which is e.g. used for phase marginalization in bilby/lalinference. However, this is not exact. In this method we account for this effect, such that each contribution pol_m[m] transforms exactly as exp(-1j * m * phase).

• Phase shifts contribute in two ways: Firstly via the spherical harmonics, which we account for with the exp(-1j * m * phase) transformation. Secondly, the phase determines how the PE spins transform to cartesian spins, by rotating (sx,sy) by phase. This is not accounted for in this function. Instead, the phase for computing the cartesian spins is fixed to self.spin_conversion_phase (if not None). This effectively changes the PE parameters {phi_jl, phi_12} to parameters {phi_jl_prime, phi_12_prime}. For parameter estimation, a postprocessing operation can be applied to account for this, {phi_jl_prime, phi_12_prime} -> {phi_jl, phi_12}. See also documentation of __init__ method for more information on self.spin_conversion_phase.

Differences to self.generate_hplus_hcross: - We don’t catch errors yet TODO - We don’t apply transforms yet TODO

Parameters:

parameters (dict) – Dictionary of parameters for the waveform. For details see see self.generate_hplus_hcross.

Returns:

pol_m – Dictionary with contributions to h_plus and h_cross, sorted by their transformation behaviour under phase shifts: {m: {“h_plus”: hp_m, “h_cross”: hc_m} for m in [-l_max,…,0,…,l_max]} Each contribution h_m transforms as exp(-1j * m * phase) under phase shifts (for fixed self.spin_conversion_phase, see above).

Return type:

dict

dingo.gw.waveform_generator.waveform_generator.SEOBNRv4PHM_maximum_starting_frequency(total_mass: float, fudge: float = 0.99) → float

Given a total mass return the largest possible starting frequency allowed for SEOBNRv4PHM and similar effective-one-body models.

The intended use for this function is at the stage of designing a data set: after choosing a mass prior one can use it to figure out which prior samples would run into an issue when generating an EOB waveform, and tweak the parameters to reduce the number of failing configurations.

Parameters:

• total_mass – Total mass in units of solar masses

• fudge – A fudge factor

Returns:

The largest possible starting frequency in Hz

Return type:

f_max_Hz

class dingo.gw.waveform_generator.waveform_generator.WaveformGenerator(approximant: str, domain: Domain, f_ref: float, f_start: float | None = None, mode_list: List[Tuple] | None = None, transform=None, spin_conversion_phase=None, **kwargs)

Bases: object

Generate polarizations using LALSimulation routines in the specified domain for a single GW coalescence given a set of waveform parameters.

Parameters:

• approximant (str) – Waveform “approximant” string understood by lalsimulation This is defines which waveform model is used.

• domain (Domain) – Domain object that specifies on which physical domain the waveform polarizations will be generated, e.g. Fourier domain, time domain.

• f_ref (float) – Reference frequency for the waveforms

• f_start (float) – Starting frequency for waveform generation. This is optional, and if not included, the starting frequency will be set to f_min. This exists so that EOB waveforms can be generated starting from a lower frequency than f_min.

• mode_list (List[Tuple]) – A list of waveform (ell, m) modes to include when generating the polarizations.

• spin_conversion_phase (float = None) – Value for phiRef when computing cartesian spins from bilby spins via bilby_to_lalsimulation_spins. The common convention is to use the value of the phase parameter here, which is also used in the spherical harmonics when combining the different modes. If spin_conversion_phase = None, this default behavior is adapted. For dingo, this convention for the phase parameter makes it impossible to treat the phase as an extrinsic parameter, since we can only account for the change of phase in the spherical harmonics when changing the phase (in order to also change the cartesian spins – specifically, to rotate the spins by phase in the sx-sy plane – one would need to recompute the modes, which is expensive). By setting spin_conversion_phase != None, we impose the convention to always use phase = spin_conversion_phase when computing the cartesian spins.

property domain

property full_domain

generate_FD_modes_LO(parameters)

Generate FD modes in the L0 frame.

Parameters:

parameters (dict) – Dictionary of parameters for the waveform. For details see see self.generate_hplus_hcross.

Returns:

• hlm_fd (dict) – Dictionary with (l,m) as keys and the corresponding FD modes in lal format as values.

• iota (float)

generate_FD_waveform(parameters_lal: Tuple, target_function: Callable) → Dict[str, ndarray]

Generate Fourier domain GW polarizations (h_plus, h_cross).

Parameters:

• parameters_lal – A tuple of parameters for the lalsimulation waveform generator

• target_function – Lalsimulation function for waveform generation.

Returns:

A dictionary of generated waveform polarizations

Return type:

pol_dict

generate_TD_modes_L0(parameters)

Generate TD modes in the L0 frame.

Parameters:

parameters (dict) – Dictionary of parameters for the waveform. For details see see self.generate_hplus_hcross.

Returns:

• hlm_td (dict) – Dictionary with (l,m) as keys and the corresponding TD modes in lal format as values.

• iota (float)

generate_TD_waveform(parameters_lal: Tuple) → Dict[str, ndarray]

Generate time domain GW polarizations (h_plus, h_cross)

Parameters:

parameters_lal – A tuple of parameters for the lalsimulation waveform generator

Returns:

A dictionary of generated waveform polarizations

Return type:

pol_dict

generate_hplus_hcross(parameters: Dict[str, float], catch_waveform_errors=True) → Dict[str, ndarray]

Generate GW polarizations (h_plus, h_cross).

If the generation of the lalsimulation waveform fails with an “Input domain error”, we return NaN polarizations.

Use the domain, approximant, and mode_list specified in the constructor along with the waveform parameters to generate the waveform polarizations.

Parameters:

• parameters (Dict[str, float]) –

  A dictionary of parameter names and scalar values. The parameter dictionary must include the following keys. For masses, spins, and distance there are multiple options.

  Mass: (mass_1, mass_2) or a pair of quantities from

  ((chirp_mass, total_mass), (mass_ratio, symmetric_mass_ratio))

  Spin:

  (a_1, a_2, tilt_1, tilt_2, phi_12, phi_jl) if precessing binary or (chi_1, chi_2) if the binary has aligned spins

  Reference frequency: f_ref at which spin vectors are defined Extrinsic:

  Distance: one of (luminosity_distance, redshift, comoving_distance) Inclination: theta_jn Reference phase: phase Geocentric time: geocent_time (GPS time)

  The following parameters are not required:

  Sky location: ra, dec, Polarization angle: psi

  Units:

  Masses should be given in units of solar masses. Distance should be given in megaparsecs (Mpc). Frequencies should be given in Hz and time in seconds. Spins should be dimensionless. Angles should be in radians.

• catch_waveform_errors (bool) – Whether to catch lalsimulation errors

Returns:

A dictionary of generated waveform polarizations

Return type:

wf_dict

generate_hplus_hcross_m(parameters: Dict[str, float]) → Dict[tuple, Dict[str, ndarray]]

Generate GW polarizations (h_plus, h_cross), separated into contributions from the different modes. This method is identical to self.generate_hplus_hcross, except that it generates the individual contributions of the modes to the polarizations and sorts these according to their transformation behavior (see below), instead of returning the overall sum.

This is useful in order to treat the phase as an extrinsic parameter. Instead of {“h_plus”: hp, “h_cross”: hc}, this method returns a dict in the form of {m: {“h_plus”: hp_m, “h_cross”: hc_m} for m in [-l_max,…,0,…,l_max]}. Each key m contains the contribution to the polarization that transforms according to exp(-1j * m * phase) under phase transformations (due to the spherical harmonics).

Note:

• pol_m[m] contains contributions of the m modes and and the -m modes. This is because the frequency domain (FD) modes have a positive frequency part which transforms as exp(-1j * m * phase), while the negative frequency part transforms as exp(+1j * m * phase). Typically, one of these dominates [e.g., the (2,2) mode is dominated by the negative frequency part and the (-2,2) mode is dominated by the positive frequency part] such that the sum of (l,|m|) and (l,-|m|) modes transforms approximately as exp(1j * |m| * phase), which is e.g. used for phase marginalization in bilby/lalinference. However, this is not exact. In this method we account for this effect, such that each contribution pol_m[m] transforms exactly as exp(-1j * m * phase).

• Phase shifts contribute in two ways: Firstly via the spherical harmonics, which we account for with the exp(-1j * m * phase) transformation. Secondly, the phase determines how the PE spins transform to cartesian spins, by rotating (sx,sy) by phase. This is not accounted for in this function. Instead, the phase for computing the cartesian spins is fixed to self.spin_conversion_phase (if not None). This effectively changes the PE parameters {phi_jl, phi_12} to parameters {phi_jl_prime, phi_12_prime}. For parameter estimation, a postprocessing operation can be applied to account for this, {phi_jl_prime, phi_12_prime} -> {phi_jl, phi_12}. See also documentation of __init__ method for more information on self.spin_conversion_phase.

Differences to self.generate_hplus_hcross: - We don’t catch errors yet TODO - We don’t apply transforms yet TODO

Parameters:

parameters (dict) – Dictionary of parameters for the waveform. For details see see self.generate_hplus_hcross.

Returns:

pol_m – Dictionary with contributions to h_plus and h_cross, sorted by their transformation behaviour under phase shifts: {m: {“h_plus”: hp_m, “h_cross”: hc_m} for m in [-l_max,…,0,…,l_max]} Each contribution h_m transforms as exp(-1j * m * phase) under phase shifts (for fixed self.spin_conversion_phase, see above).

Return type:

dict

setup_mode_array(mode_list: List[Tuple]) → Dict

Define a mode array to select waveform modes to include in the polarizations from a list of modes.

Parameters:

mode_list (a list of (ell, m) modes)

Returns:

A lal parameter dictionary

Return type:

lal_params

property spin_conversion_phase

dingo.gw.waveform_generator.waveform_generator.generate_waveforms_parallel(waveform_generator: WaveformGenerator, parameter_samples: DataFrame, pool: Pool | None = None) → Dict[str, ndarray]

Generate a waveform dataset, optionally in parallel.

Parameters:

• waveform_generator (WaveformGenerator) – A WaveformGenerator instance

• parameter_samples (pd.DataFrame) – Intrinsic parameter samples

• pool (multiprocessing.Pool) – Optional pool of workers for parallel generation

Returns:

A dictionary of all generated polarizations stacked together

Return type:

polarizations

dingo.gw.waveform_generator.waveform_generator.generate_waveforms_task_func(args: Tuple, waveform_generator: WaveformGenerator) → Dict[str, ndarray]

Picklable wrapper function for parallel waveform generation.

Parameters:

• args – A tuple of (index, pandas.core.series.Series)

• waveform_generator – A WaveformGenerator instance

Return type:

The generated waveform polarization dictionary

dingo.gw.waveform_generator.waveform_generator.sum_contributions_m(x_m, phase_shift=0.0)

Sum the contributions over m-components, optionally introducing a phase shift.

dingo.gw.waveform_generator.wfg_utils module

dingo.gw.waveform_generator.wfg_utils.get_polarizations_from_fd_modes_m(hlm_fd, iota, phase)

dingo.gw.waveform_generator.wfg_utils.get_starting_frequency_for_SEOBRNRv5_conditioning(parameters)

Compute starting frequency needed for having 3 extra cycles for tapering the TD modes. It returns the needed quantities to apply the standard LALSimulation conditioning routines to the TD modes.

Parameters:

parameters (dict) – Dictionary of parameters suited for GWSignal (obtained with NewInterfaceWaveformGenerator._convert_parameters)

Returns:

• f_min (float) – Waveform starting frequency

• f_start (float) – New waveform starting frequency

• extra_time (float) – Extra time to take care of situations where the frequency is close to merger

• original_f_min (float) – Initial waveform starting frequency

• f_isco (float) – ISCO frequency

dingo.gw.waveform_generator.wfg_utils.get_tapering_window_for_complex_time_series(h, tapering_flag: int = 1)

Get window for tapering of a complex time series from the lal backend. This is done by tapering the time series with lal, and dividing tapered output by untapered input. lal does not support tapering of complex time series objects, so as a workaround we taper only the real part of the array and extract the window based on this.

Parameters:

• h – complex lal time series object

• tapering_flag (int = 1) –

  Flag for tapering. See e.g. lines 2773-2777 in

  https://lscsoft.docs.ligo.org/lalsuite/lalsimulation/ _l_a_l_sim_inspiral_waveform_taper_8c_source.html#l00222

  tapering_flag = 1 corresponds to LAL_SIM_INSPIRAL_TAPER_START

Returns:

window – Array of length h.data.length, with the window used for tapering.

Return type:

np.ndarray

dingo.gw.waveform_generator.wfg_utils.linked_list_modes_to_dict_modes(hlm_ll)

Convert linked list of modes into dictionary with keys (l,m).

dingo.gw.waveform_generator.wfg_utils.taper_td_modes_for_SEOBRNRv5_extra_time(h, extra_time, f_min, original_f_min, f_isco)

Apply standard tapering procedure mimicking LALSimulation routine (https://lscsoft.docs.ligo.org/lalsuite/lalsimulation/_l_a_l_sim_inspiral_generator_conditioning_8c.html#ac78b5fcdabf8922a3ac479da20185c85)

Parameters:

• h – complex gwpy TimeSeries object

• extra_time (float) – Extra time to take care of situations where the frequency is close to merger

• f_min (float) – Starting frequency employed in waveform generation

• original_f_min (float) – Initial starting frequency requested by the user

• f_isco – ISCO frequency

Returns:

complex lal timeseries object

Return type:

h_return

dingo.gw.waveform_generator.wfg_utils.taper_td_modes_in_place(hlm_td, tapering_flag: int = 1)

Taper the time domain modes in place.

Parameters:

• hlm_td (dict) – Dictionary with (l,m) keys and the complex lal time series objects for the corresponding modes.

• tapering_flag (int = 1) –

  Flag for tapering. See e.g. lines 2773-2777 in

  https://lscsoft.docs.ligo.org/lalsuite/lalsimulation/ _l_a_l_sim_inspiral_waveform_taper_8c_source.html#l00222

  tapering_flag = 1 corresponds to LAL_SIM_INSPIRAL_TAPER_START

dingo.gw.waveform_generator.wfg_utils.td_modes_to_fd_modes(hlm_td, domain)

Transform dict of td modes to dict of fd modes via FFT. The td modes are expected to be tapered.

Parameters:

• hlm_td (dict) – Dictionary with (l,m) keys and the complex lal time series objects for the corresponding tapered modes.

• domain (dingo.gw.domains.UniformFrequencyDomain) – Target domain after FFT.

Returns:

hlm_fd – Dictionary with (l,m) keys and numpy arrays with the corresponding modes as values.

Return type:

dict

Module contents