pespace.waveform.interface_lalsim

Interface to LALSimulation.

Note the time-frequency correspondence, t(f), for frequency domain waveforms is approximated by the PN expansion. If phenomenological waveforms are used, tiwave is recommended for waveform generation.

Functions

get_PN_d_phase(parameters, frequency_samples)

Calculate time-frequency correspondence t(f) using Post-Newtonian phase coefficients.

Classes

WaveformLALSimulationInterface(domain, ...)

Interface class to get waveform strains from lalsimulation.
class pespace.waveform.interface_lalsim.WaveformLALSimulationInterface(domain, approximant, sampling_interval, reference_frequency, minimum_frequency, maximum_frequency, skip_invalid_params=True, parameter_conversion=None, **waveform_parameters)[source]

Bases: object

Interface class to get waveform strains from lalsimulation.

The two polarizations are stacked in waveform_container to optimize memory access when computing detector responses. While this layout may result in low performance when two polarizations are accessed independently.

The frequency-domain waveform generated by lalsimulation has the length of \(2^n + 1\), which benefits performance of ifft. However, in our case, the waveform is mainly used to compute the detector response in frequency-domain, not used to get time-domain waveform through ifft. Therefore, to reduce samples need to be computed for response, we only ratain the concerned range, use minimum_frequency and maximum_frequency to truncate the frequency series given by lalsimulation.

Since lalsimulation does not provide a direct interface to obtain t(f) for each waveform approximant, we simply use the phase Post-Newtonian coefficients to derive \(t(f)=d\phi/df\), and use \(f_\mathrm{ISCO}=1/(6^{3/2}\pi M)\) as the truncation. For frequency above \(f_\mathrm{ISCO}\), we set t(f)=0 adopting the convention that the binary merge around t=0. If waveform model of IMRPhenomD or IMRPhenomX is used, tiwave is recommended.

Parameters:

  • domain (str)

  • approximant (str)

  • sampling_interval (float)

  • reference_frequency (float)

  • minimum_frequency (float)

  • maximum_frequency (float)

  • skip_invalid_params (bool)

  • parameter_conversion (Callable | None)

  • waveform_parameters (dict[str, Any])

__init__(domain, approximant, sampling_interval, reference_frequency, minimum_frequency, maximum_frequency, skip_invalid_params=True, parameter_conversion=None, **waveform_parameters)[source]

Initialize the LALSimulation waveform interface.

Parameters:

  • domain (str) – Waveform domain, either ‘td’ for time domain or ‘fd’ for frequency domain.

  • approximant (str) – Name of the waveform approximant (e.g., ‘IMRPhenomXAS’, ‘SEOBNRv4’).

  • sampling_interval (float) – Sampling interval. If domain is ‘td’, this is dt in seconds. If domain is ‘fd’, this is df in Hz.

  • reference_frequency (float) – Reference frequency in Hz for the waveform generation.

  • minimum_frequency (float) – Minimum frequency in Hz for the waveform.

  • maximum_frequency (float) – Maximum frequency in Hz for the waveform.

  • skip_invalid_params (bool, optional) – If True, skip parameter sets that cause LALSimulation errors. If False, raise the error. Default is True.

  • parameter_conversion (Callable or None, optional) – Function to convert input parameters before passing to LALSimulation. If None, uses default identity conversion. Default is None.

  • **waveform_parameters (dict[str, Any]) – Additional waveform flags passed to LALSimulation.

Raises:

ValueError – If domain is not ‘td’ or ‘fd’.

Notes

The waveform_container structure differs between time and frequency domains:

  • Time domain: dict with ‘data’ (Nx2 array) and ‘t0’ (epoch) keys

  • Frequency domain: Taichi struct field with ‘plus’, ‘cross’, and ‘tf’ components

_default_parameter_conversion(input_params)[source]

Default parameter conversion (identity function).

Parameters:

input_params (dict[str, float]) – Input parameter dictionary.

Returns:

Same as input_params (no conversion applied).

Return type:

dict[str, float]

_update_waveform_td(parameters)[source]

Update time-domain waveform with new parameters.

Parameters:

parameters (dict[str, float]) – Dictionary of waveform parameters.

Raises:

RuntimeError – If LALSimulation encounters an error and skip_invalid_params is False.

_update_waveform_fd(parameters)[source]

Update frequency-domain waveform with new parameters.

Parameters:

parameters (dict[str, float]) – Dictionary of waveform parameters.

Raises:

RuntimeError – If LALSimulation encounters an error and skip_invalid_params is False.

pespace.waveform.interface_lalsim.get_PN_d_phase(parameters, frequency_samples)[source]

Calculate time-frequency correspondence t(f) using Post-Newtonian phase coefficients.

This function computes \(t(f) = -\frac{1}{2\pi}\frac{d\phi}{df}\) using Post-Newtonian expansion coefficients.

Parameters:

  • parameters (dict[str, float]) –

    Dictionary containing binary parameters:

    • mass_1, mass_2: Component masses in solar masses

    • spin_1z, spin_2z: Dimensionless spin components along orbital angular momentum

  • frequency_samples (NDArray) – Array of frequency values in Hz at which to compute t(f).

Returns:

Time-frequency correspondence t(f) in seconds. For frequencies above fISCO, returns 0 (adopting the convention that merger occurs at t=0).

Return type:

NDArray

Notes

The calculation uses the TaylorF2 phase approximation with PN coefficients from phi_0 through phi_8. The innermost stable circular orbit (ISCO) frequency is used as a cutoff: \(f_\mathrm{ISCO}=1/(6^{3/2}\pi M)\). For frequencies f<f_ISCO, the time is computed from the PN phase derivative with a time shift applied so that t(f_ISCO) = 0.

References