Skip to content

Strain injection examples

After producing detector strain (e.g. with Waveforms and Detector projection), you often need to embed that strain into a longer segment aligned to a science run—typically starting from zeros or from a noise realization (noise generation can live in a separate package). This step is central to software injections, end-to-end mock challenges, and pipeline validation.

This page is examples only. Signatures, defaults, and raised exceptions for inject_strain / inject_strains_sequential are documented only under API → Injection.

API reference

Use API → Injection for the authoritative behavior description; examples below illustrate common patterns.

Example 1 — Inject one CBC into a zero-filled segment

import numpy as np
from gwpy.timeseries import TimeSeries

from gwmock_signal.waveform import pycbc_waveform_wrapper
from gwmock_signal.projection import project_polarizations_to_network
from gwmock_signal.injection import inject_strain

fs = 4096.0
duration = 8.0
t0 = 1_400_000_000.0
n = int(duration * fs)

target = TimeSeries(np.zeros(n), t0=t0, sample_rate=fs)

pol = pycbc_waveform_wrapper(
    tc=t0 + 2.0,
    sampling_frequency=fs,
    minimum_frequency=20.0,
    waveform_model="IMRPhenomD",
    mass1=30.0,
    mass2=25.0,
    spin1z=0.0,
    spin2z=0.0,
)
strains = project_polarizations_to_network(
    pol,
    ["H1"],
    right_ascension=1.0,
    declination=0.5,
    polarization_angle=0.2,
    earth_rotation=False,
)
h1 = strains["H1"]

out = inject_strain(target, h1)
assert out is not target  # immutability: new object (recommended contract)

Example 2 — Multiple injections in time order

from gwmock_signal.injection import inject_strains_sequential

# target: long segment; inj1, inj2: non-overlapping or overlapping GWpy series
out = inject_strains_sequential(target, [inj1, inj2], interpolate_if_offset=True)

Example 3 — Disable interpolation (strict grid)

If you know injections are exactly aligned to the target grid and want to avoid cubic resampling at boundaries:

out = inject_strain(target, h1, interpolate_if_offset=False)

Pitfalls

  • Units: Target and injection should use compatible strain units (typically dimensionless); mixed units should raise a clear error.
  • No overlap: If the injection lies entirely outside the target span, the API returns a copy of the target (same samples, new object).
  • Interpolation: Cubic interpolation can ring at edges; prefer aligned waveforms from the same sampling_frequency and GPS grid when possible.
  • Performance: Large segments are memory-bound; avoid unnecessary copies if the API documents mutability (default recommendation: return a new TimeSeries).

Scientific notes

  • Conventions follow common GWpy / LIGO injection practice: coherent addition of strain in the time domain on a fixed grid.
  • For colored noise backgrounds, build target as noise first, then inject; stationary Gaussian noise can be added in a separate noise-focused package.

See also