GWSignal Interface

The GWSignal.py module acts as a wrapper around the gwsignal library. It is designed to avoid some of the stdout noise and slow import times associated with the base library while providing a clean interface for generating both time-domain waveforms and their harmonic decompositions.

Overview

This interface allows RIFT to leverage the wide array of waveform models available in the gwsignal ecosystem. It handles the conversion between RIFT’s internal parameter structures (ChooseWaveformParams) and the Python dictionaries required by the gwsignal generators.

Core Functions

Harmonic Decomposition

  • hlmoft(P, Lmax=2, ...): The core function for generating harmonic modes. It takes a parameter set P and returns a dictionary of LAL COMPLEX16TimeSeries objects for each $(l, m)$ mode up to Lmax.

    • It handles the necessary coordinate conversions (e.g., masses to solar masses).

    • It applies required tapering and phase shifts.

    • It can optionally adjust the waveform epoch based on the peak of the signal.

  • hlmoff(P, ...): A convenience wrapper around hlmoft that returns Fourier-transformed harmonic modes.

  • std_and_conj_hlmoff(P, ...): Returns both the Fourier-transformed modes and their complex conjugates.

Time-Domain Waveforms

  • hoft(P, ...): Generates a real-valued time-domain waveform. It handles the projection of the $h_+$ and $h_times$ polarizations onto a specific detector strain based on the sky location and orientation.

  • complex_hoft(P, ...): Generates a complex-valued time-domain waveform ($h_+ + i h_times$), which is useful for certain internal RIFT calculations.

Implementation Details

  • Coordinate Handling: The module carefully converts RIFT’s internal units to the units expected by gwsignal (e.g., using astropy.units).

  • Tapering: Since gwsignal output is often not tapered, the module manually applies a cosine taper to the start of the segments to avoid spectral leakage.

  • Epoch Alignment: The module supports an align_method='peak' option, which shifts the waveform epoch to coincide with the peak of the total power $sum |h_{lm}|^2$.

Backend options

With --use-gwsignal, ILE passes the complete dictionary supplied to --internal-waveform-extra-kwargs to the selected waveform generator. For example, the production SEOBNRv5PHM settings use:

--use-gwsignal --approx SEOBNRv5PHM \
--internal-waveform-extra-kwargs "{'antisymmetric_modes_hm': True, 'enable_antisymmetric_modes': True, 'lmax_nyquist': 1}"

No list of approved backend options is maintained in RIFT. Nested dictionaries, false values and zero values are preserved, and errors from the generator are allowed to propagate. A generator can still reject unsupported options or ignore them according to its own interface; RIFT does not validate a plugin’s option schema.

The explicit dictionary is kept separate from RIFT alignment and conditioning controls, including --internal-waveform-fd-L-frame. It takes precedence over --use-gwsignal-lmax-nyquist. Direct Python callers can use gwsignal_extra_kwargs={...} with hlmoft, hoft or complex_hoft for the same behavior. Legacy direct keyword arguments are forwarded too, except for known RIFT wrapper controls.

Masses, spins, sampling and other physical parameters must be set on ChooseWaveformParams. Backend options that override those translated fields raise ValueError to prevent disagreement with likelihood parameters or series metadata. condition may override the taper-derived backend conditioning value. RIFT’s own tapering and alignment of returned modes still apply. Plain nested dictionaries, lists and tuples are copied before generation; opaque backend objects are passed through unchanged.

--internal-waveform-extra-lalsuite-args targets the native LAL-dictionary route, not GWSignal. ILE rejects its combination with --use-gwsignal before loading detector data, including an explicitly supplied empty dictionary. Use --internal-waveform-extra-kwargs for GWSignal backend options. Direct GWSignal callers receive an error for a nonempty legacy extra_waveform_args payload; an explicitly namespaced backend option with that name remains allowed.

The same dictionary separation is preserved when pseudo-pipeline arguments are forwarded to calibration reweighting. --extra-waveform-kwargs in that executable is a wrapper-options dictionary; its gwsignal_extra_kwargs member holds explicit backend options. The pseudo-pipeline constructs this member from --internal-waveform-extra-kwargs when GWSignal is selected.

Asimov’s waveform dictionaries are quoted as shell arguments. BasicIteration preserves their nested list syntax and backslashes, and the ILE submit writer translates complete shell argument boundaries into HTCondor’s new argument syntax. Multiple dictionaries and quoted string values are supported. Literal line breaks inside an individual submit argument are rejected.