LALWaveforms

ALIGO_DESIGN

Canonical Advanced LIGO design interferometer.

This corresponds to the broadband, zero-detuned, high-power Advanced LIGO design configuration.

This is the default parameterization of InterferometerModel.

ALIGO_O4

Advanced LIGO O4 observing run configuration.

Currently identical to ALIGO_DESIGN.

DetectorCollection

A collection of Detectors.

DetectorCollection is a type alias representing any supported collection of detectors, including vectors, tuples, and named tuples. It is intended for methods that operate on multiple detectors while preserving the structure of the input when using functions such as map.

AbstractNoiseModel

Abstract supertype for detector noise models.

Subtypes of AbstractNoiseModel describe the statistical properties of detector noise and may be used to generate noise realizations or apply noise-related transformations.

AbstractPSD

Abstract supertype for one-sided strain noise power spectral density models.

An AbstractPSD is a callable object psd(f) that evaluates the one-sided strain noise power spectral density at frequency f (Hz), returning a value with units of strain²/Hz.

Concrete subtypes should implement scalar evaluation (psd)(f::Real).

together with:

• minimum_frequency(psd)
• maximum_frequency(psd)

to specify their domain of validity.

AbstractWaveformGenerator

Abstract type for gravitational-waveform generators parameterised by an Approximant.

Concrete subtypes are WaveformGenerator (time-domain) and FDWaveformGenerator (frequency-domain). They are callable: $\mathtt{gen}(\mathtt{src})$ returns a GWTimeSeries or GWFrequencySeries.

AnalyticPSD(func, fmin, fmax)

Analytic power spectral density model.

AnalyticPSD wraps a callable object together with the frequency interval over which the model is considered valid.

Evaluation outside the interval [fmin, fmax] throws a DomainError.

Fields

• func : Callable object evaluating the PSD.
• fmin : Minimum valid frequency (Hz).
• fmax : Maximum valid frequency (Hz).

AnalyticPSD(model::InterferometerModel; fmin=9, fmax=Inf)

Construct an analytic strain-noise PSD from an interferometer model.

Approximant

Enumeration of the waveform approximants implemented in LALSimulation that can be used with generate_td_waveform and generate_fd_waveform. Each member corresponds to the identically‑named entry in the C Approximant enum defined in LALSimInspiral.h.

Only approximants that are actually implemented in LALSimulation are included; historical placeholders (e.g. BCV, FrameFile) and models marked “Not implemented” in the official documentation have been omitted.

External documentation

The complete list of approximants and their descriptions can be found in the LALSimulation inspiral group of the LALSuite Doxygen pages.

Arm

Detector arm geometry.

An Arm describes the orientation and midpoint of an interferometer arm. The arm geometry is used to construct the detector response tensor from the detector location and orientation.

Fields

• altitude::Real: Altitude angle above the local horizontal (rad).
• azimuth::Real: Azimuth measured east of north (rad).
• midpoint::Real: Distance from the detector vertex to the arm midpoint (m).

CBCSource{T}

Compact binary coalescence source parameters.

Stores the intrinsic and extrinsic parameters describing a compact binary system. The type parameter $T$ is promoted from the supplied arguments.

Fields

• m1::T, m2::T: Component masses ($M_\odot$).
• distance::T: Luminosity distance (pc).
• inclination::T: Inclination angle of the orbital plane (rad).
• ϕref::T: Reference orbital phase at f_ref (rad).
• longAscNodes::T: Longitude of the ascending node (rad).
• S1x::T, S1y::T, S1z::T: Dimensionless spin vector of object 1.
• S2x::T, S2y::T, S2z::T: Dimensionless spin vector of object 2.
• eccentricity::T: Orbital eccentricity at f_ref.
• meanPerAno::T: Mean anomaly at $t = 0$ (rad), used when $\mathtt{eccentricity} > 0$.

Keyword constructor

CBCSource(m1, m2; distance=1Mpc, inclination=0, ϕref=0,
          longAscNodes=0, S1x=0, S1y=0, S1z=0,
          S2x=0, S2y=0, S2z=0, eccentricity=0, meanPerAno=0)

Returns a CBCSource with type $T$ promoted from all arguments.

CachedDetector

Selected redefined gravitational wave detectors, contained in the lalCachedDetectors array.

Detector

Gravitational-wave detector.

A Detector stores the geometry and location of a gravitational-wave detector. It contains the detector position on the Earth, the arm geometry(Arm), and the precomputed detector response tensor used for antenna pattern and strain projection calculations.

Fields

• name::String: Full detector name.
• prefix::String: Short detector identifier.
• longitude::Real: Geodetic longitude (rad).
• latitude::Real: Geodetic latitude (rad).
• elevation::Real: Elevation above the WGS-84 reference ellipsoid (m).
• location::NTuple{3, Real}: Earth-centered, Earth-fixed Cartesian coordinates (m).
• response::DetectorResponse: DetectorResponse tensor.
• xarm::Arm: Geometry of the X Arm.
• yarm::Arm: Geometry of the Y Arm.
• type::DetectorType: Detector operating mode (DetectorType).

DetectorFrequencyStrain

Frequency-domain gravitational-wave strain measured by a detector.

A DetectorFrequencyStrain represents the response of a single gravitational-wave detector to an incident gravitational wave in the frequency domain. The strain is obtained by projecting the plus and cross polarisations of a GWFrequencySeries onto the detector tensor using the detector's antenna response.

The stored strain is dimensionless and sampled on a uniform frequency grid.

Fields

• h̃::AbstractVector{Complex}: Measured detector strain.
• δf::Real: Frequency resolution.
• epoch::GPSTime: GPSTime of the first sample.
• detector::Detector: Detector at which the strain was evaluated.

DetectorResponse

Symmetric detector response tensor.

A DetectorResponse stores the symmetric rank-2 tensor describing the response of a gravitational-wave detector (Detector). The tensor encodes the detector geometry and is used to compute antenna pattern functions and project gravitational-wave polarisations onto the detector.

Fields

• xx::Real: xx component of the response tensor.
• xy::Real: xy component of the response tensor.
• xz::Real: xz component of the response tensor.
• yy::Real: yy component of the response tensor.
• yz::Real: yz component of the response tensor.
• zz::Real: zz component of the response tensor.

DetectorStrain

Time-domain gravitational-wave strain measured by a detector.

A DetectorStrain represents the response of a single gravitational-wave detector to an incident gravitational wave. The strain is obtained by projecting the plus and cross polarisations of a GWTimeSeries onto the detector tensor using the detector's antenna response.

The stored strain is dimensionless and sampled uniformly in time.

Fields

• h::AbstractVector{Real}: Measured detector strain.
• δt::Real: Sampling interval.
• epoch::GPSTime: GPSTime of the first sample.
• detector::Detector: Detector at which the strain was evaluated.

DetectorType

Enumeration of supported gravitational-wave detector configurations.

DetectorType specifies how a detector responds to an incident gravitational wave. The detector type determines how the detector response tensor is constructed from the detector geometry.

Values

• DifferentialIFO: Differential interferometer.
• XArmIFO: Single-arm interferometer using the x arm.
• YArmIFO: Single-arm interferometer using the y arm.
• CommonIFO: Common-mode interferometer.
• CylindricalBar: Cylindrical resonant-bar detector.

Duration

Stores the precise time interval between two GPSTime values, or a time shift to be applied to a GPSTime.

FDWaveformGenerator{T} <: AbstractWaveformGenerator

Frequency-domain waveform generator.

Fields

• approximant::Approximant: Waveform approximant (Approximant).
• δf::T: Frequency resolution (Hz).
• f_min::T: Starting frequency (Hz).
• f_max::T: Maximum frequency (Hz). Zero means the maximum frequency is set internally.
• f_ref::T: Reference frequency (Hz). Zero means the reference frequency is set internally.

Keyword constructor

FDWaveformGenerator(approximant; δf=1/32, f_min=40.0, f_max=0.0, f_ref=0.0)

Returns an FDWaveformGenerator with type $T$ promoted from the keyword arguments. Calling $\mathtt{gen}(\mathtt{src})$ on a CBCSource dispatches to generate_fd_waveform.

GPSTime

Stores absolute GPS time to nanosecond precision. Converts to and from LIGOTimeGPS.

GWFrequencySeries

Frequency-domain gravitational-wave strain data.

A GWFrequencySeries stores the plus and cross polarisations, $h̃_+$ and $h̃_\times$, sampled on a uniform frequency grid.

Fields

• h̃₊::AbstractVector{Complex}: Samples of the plus polarisation.
• h̃ₓ::AbstractVector{Complex}: Samples of the cross polarisation.
• δf::Real: Frequency resolution in Hz.
• epoch::GPSTime: GPSTime of the first sample in seconds.

GWTimeSeries

Time-domain gravitational-wave strain data.

A GWTimeSeries stores the plus and cross polarisations, $h_+$ and $h_\times$, sampled on a uniform time grid.

Fields

• h₊::AbstractVector{Real}: Samples of the plus polarisation.
• hₓ::AbstractVector{Real}:Samples of the cross polarisation.
• δt::Real: Sampling interval in seconds.
• epoch::GPSTime: GPSTime of the first sample in seconds.

GaussianNoise

Stationary Gaussian detector noise characterized by a one-sided strain noise power spectral density.

A GaussianNoise model represents zero-mean stationary Gaussian noise whose frequency-domain power is described by the supplied AbstractPSD.

Fields

• psd::AbstractPSD: One-sided strain noise power spectral density.

InterferometerNoiseModel

Physical model of a dual-recycled Fabry-Pérot Michelson interferometer.

InterferometerNoiseModel collects the physical, optical, and thermal parameters required to evaluate the quantum and thermal strain noise of a gravitational-wave interferometer.

The model itself performs no calculations; it simply defines the detector configuration. Evaluation is handled by PreparedInterferometer, created via precompute.

Fields

Fundamental constants

• c : Speed of light (m/s).
• ħ : Reduced Planck constant (J⋅s).
• kᵦ : Boltzmann constant (J/K).

Interferometer geometry

• L : Arm length (m).
• M : Test mass mirror mass (kg).

Optical configuration

• P₀ : Input laser power (W).
• λ₀ : Laser wavelength (m).
• Tᵢ : Input test mass power transmittance.
• Tₚ : Power recycling mirror transmittance.
• Tₛ : Signal recycling mirror transmittance.
• Aₘ : Average arm cavity loss.
• Aₛ : Signal recycling cavity loss.
• η : Photodiode quantum efficiency.
• ϕ_d : Signal recycling cavity detuning (rad).
• ζ : Homodyne readout angle (rad).

Thermal model

• T_env : Temperature (K).
• fₛ : Suspension resonance frequency (Hz).
• Qₛ : Suspension quality factor.
• fₒ : Coating resonance frequency (Hz).
• Qₒ : Coating quality factor.

Absent: No FrDetector associated with this detector IFODiff: IFO in differential mode IFOXArm: IFO in one-armed mode (X arm) IFOYArm: IFO in one-armed mode (Y arm) IFOComm: IFO in common mode CylBar : Cylindrical bar

LinearInterpolation(x, y)

Construct a one-dimensional piecewise linear interpolant from the sample points (x, y).

The vectors x and y must have the same length, and x must be sorted in ascending order.

The returned object is callable:

interp = LinearInterpolation(x, y)
interp(125.0)

Queries outside the sampled interval throw a DomainError.

This was added because I wanted to avoid adding another dependency to the package, and this is a simple implementation of linear interpolation.

NoiseTimeSeries

Time-domain detector noise.

A NoiseTimeSeries represents a realization of detector noise sampled uniformly in time.

Fields

• n::AbstractVector{Real}: Noise samples.
• δt::Real: Sampling interval.
• epoch::GPSTime: GPSTime of the first sample.

PreparedInterferometer

Frequency-independent quantities derived from an InterferometerModel.

PreparedInterferometer stores all constants required for efficient evaluation of the interferometer strain noise. Expensive optical quantities are computed once by precompute and reused for every frequency evaluation.

You should rarely construct this type directly.

(model::PreparedInterferometer)(f)

Evaluate the total strain noise power spectral density.

QPlane

Time-frequency representation of a detector strain computed via the Q-transform.

A QPlane stores the energy spectrogram and the corresponding time and frequency grids. It subtypes AbstractMatrix so standard plotting and matrix operations work directly.

Fields

• energy::AbstractMatrix{Real}: Time-frequency energy matrix (time × frequency).
• time::Vector{Float64}: Time bin centres relative to epoch (s).
• frequency::Vector{Float64}: Frequency bin centres (Hz).
• Q::Int: Quality factor of the transform.
• sd::Int: Number of wavelet standard deviations.
• δt::Real: Original sampling interval (s).
• epoch::GPSTime: GPSTime of the first sample.
• detector::Detector: Detector at which the strain was measured.

SNRTimeSeries

Time series of matched-filter signal-to-noise ratio (SNR).

An SNRTimeSeries represents the matched-filter signal-to-noise ratio evaluated as a function of time for a single gravitational-wave detector. Each sample corresponds to the SNR obtained by correlating the detector strain with a template at the corresponding time offset.

Fields

• ρ::AbstractVector{Real}: Matched-filter signal-to-noise ratio.
• δt::Real: Sampling interval.
• epoch::GPSTime: GPSTime of the first sample.
• detector::Detector: Detector at which the SNR was evaluated.

SampledPSD

Interpolated power spectral density defined on a discrete frequency grid.

A SampledPSD stores the sampled frequencies, PSD values, and an interpolation object providing continuous evaluation over the sampled domain.

Extrapolation beyond the sampled frequency range is implementation defined by the interpolation object.

SampledPSD(
    strain::DetectorStrain;
    method=:welch,
    segmentlength=length(strain.h) ÷ 8,
    overlap=0.5,
    window=hanning,
    nfft=nextfastfft(segmentlength),
)

Estimate the noise spectrum of a detector strain time series (DetectorStrain).

The power spectral density (PSD) is estimated directly from the time-domain strain using either Welch's method or a standard periodogram. The resulting spectrum is returned as a SampledPSD, allowing it to be evaluated at arbitrary frequencies through piecewise linear interpolation.

By default, the PSD is estimated using Welch's method with eight segments, a 50% overlap between adjacent segments, and a Hann window. These defaults provide a good balance between frequency resolution and variance reduction for typical gravitational-wave detector data.

Arguments

• strain::DetectorStrain: Time-domain detector strain from which the spectrum is estimated.

Keyword Arguments

• method::Symbol = :welch: Spectral estimation method. Supported methods are :welch and :periodogram.

• segmentlength::Int = length(strain.h) ÷ 8: Number of samples in each segment when using Welch's method.

• overlap::Real = 0.5: Overlap between adjacent Welch segments. Values in the interval [0, 1) are interpreted as a fraction of the segment length, while integer values are interpreted as the number of overlapping samples.

• window = hann: Window function applied to the detector strain prior to spectral estimation. Supported window functions include hann, hamming, blackman, and tukey.

• nfft::Int = nextfastfft(segmentlength): Length of the FFT used during the spectral estimation.

Notes

The segmentlength and overlap keyword arguments are only applicable when method = :welch. Supplying either keyword with method = :periodogram will result in an ArgumentError.

SampledPSD(model, frequencies)

Sample the interferometer PSD on a frequency grid.

SampledPSD(type, filename)

Construct a sampled PSD (SampledPSD) from a two-column text file.

The input file must contain

frequency    value

where frequency is given in Hz.

WaveformGenerator{T} <: AbstractWaveformGenerator

Time-domain waveform generator.

Fields

• approximant::Approximant: Waveform approximant (Approximant).
• δt::T: Sampling interval (s).
• f_min::T: Starting frequency (Hz).
• f_ref::T: Reference frequency (Hz). Zero means the reference frequency is set internally.

Keyword constructor

WaveformGenerator(approximant; δt=1/16384, f_min=40.0, f_ref=0.0)

Returns a WaveformGenerator with type $T$ promoted from the keyword arguments. Calling $\mathtt{gen}(\mathtt{src})$ on a CBCSource dispatches to generate_td_waveform.

fft(strain)

Compute the discrete Fourier transform of a detector strain time series.

Arguments

• strain::DetectorStrain: The input detector strain (DetectorStrain).

Returns

Returns a DetectorFrequencyStrain.

ifft(strain)

Compute the inverse discrete Fourier transform of a detector strain.

Arguments

• strain::DetectorFrequencyStrain: The input detector strain in frequency domain (DetectorFrequencyStrain).

Returns

Returns a DetectorStrain.

blackman(strain)

Apply a Blackman window to a detector strain time series.

Windowing tapers the beginning and end of the time series to reduce spectral leakage in subsequent frequency-domain analyses, such as Fourier transforms and power spectral density estimation.

The Blackman window provides stronger suppression of spectral leakage than the Hann or Hamming windows, at the expense of a wider main lobe in the frequency domain.

Arguments

• strain::DetectorStrain: Input detector strain (DetectorStrain).

Returns

Returns a new DetectorStrain containing the windowed strain.

hamming(strain)

Apply a Hamming window to a detector strain time series.

Windowing tapers the beginning and end of the time series to reduce spectral leakage in subsequent frequency-domain analyses, such as Fourier transforms and power spectral density estimation.

The Hamming window smoothly tapers the signal while preserving slightly more amplitude near the ends than the Hann window.

Arguments

• strain::DetectorStrain: Input detector strain (DetectorStrain).

Returns

Returns a new DetectorStrain containing the windowed strain.

tukey(strain; α = 0.5)

Apply a Tukey window to a detector strain time series.

Windowing tapers the beginning and end of the time series to reduce spectral leakage in subsequent frequency-domain analyses, such as Fourier transforms and power spectral density estimation.

The Tukey window combines a flat central region with cosine tapers at both ends. The taper fraction is controlled by α, with α = 0 corresponding to a rectangular window and α = 1 corresponding to a Hann window.

Arguments

• strain::DetectorStrain: Input detector strain (DetectorStrain).
• α = 0.5 (kwarg): Fraction of the window occupied by the cosine tapers.

Returns

Returns a new DetectorStrain containing the windowed strain.

AdvVirgoPSD(; fmin=10.0, fmax=Inf)

Phenomenological fit to the Advanced Virgo design strain noise power spectral density.

This fit follows Eq. (6) of md2012 and reproduces the published Advanced Virgo sensitivity curve.

GEOHFPSD(; fmin=50.0, fmax=8000.0)

Phenomenological fit to the GEO600 High Frequency strain noise power spectral density.

The fit reproduces the published GEO-HF sensitivity between approximately 50 Hz and 8 kHz.

GEOPSD(; fmin=10.0, fmax=Inf)

Phenomenological fit to the GEO600 design strain noise power spectral density.

This model is adapted from the deprecated LALGEOPsd implementation in LALSuite.

KAGRAPSD(; fmin=10.0, fmax=Inf)

Phenomenological fit to the KAGRA design strain noise power spectral density.

This fit follows Eq. (5) of md2012 and reproduces the published KAGRA sensitivity curve.

TAMAPSD(; fmin=10.0, fmax=Inf)

Phenomenological fit to the TAMA300 design strain noise power spectral density.

This model is adapted from the deprecated LALTAMAPsd implementation in LALSuite.

VirgoPSD(; fmin=10.0, fmax=Inf)

Phenomenological fit to the Virgo design strain noise power spectral density.

This model is adapted from the deprecated LALVIRGOPsd implementation in LALSuite and is not derived from interferometer optical parameters.

_coating_noise(model, f)

Evaluate the mirror coating thermal strain noise power spectral density.

This phenomenological model follows the broadband approximation used in LALSuite, where the coating contribution scales as

Sₕ(f) ∝ f⁻¹.

Estimate PSD in narrow bands around each frequency.

_frequency_quantities(model, f)

Compute all frequency-dependent optical quantities used in the quantum noise model.

_periodogram_psd(
    strain;
    window,
    nfft,
)

Estimate the one-sided power spectral density of a detector strain using a standard periodogram.

This is an internal helper used by SampledPSD and shouldn't be used directly. The detector strain is windowed prior to estimating the power spectral density.

This uses periodogram from DSP.jl.

Arguments

• strain::DetectorStrain: Time-domain detector strain.

Keyword Arguments

• window: Window function applied to the strain.
• nfft::Int: FFT length used during spectral estimation.

Returns

Returns a tuple (frequency, psd) containing the sampled frequencies and the estimated power spectral density.

_project_noise(M, sζ, cζ)

Project a 2×2 quantum noise transfer matrix onto the homodyne readout quadrature.

_signal_response(D, κ, τ, sζ, cζ)

Compute the projected signal response appearing in the denominator of the quantum noise spectrum.

_suspension_noise(model, f)

Evaluate the suspension thermal strain noise power spectral density.

This phenomenological model follows the broadband approximation used in LALSuite, where the suspension contribution scales as

Sₕ(f) ∝ f⁻⁵

and is valid above the suspension resonance.

_transfer_matrix_C(p, fq)

Compute the C transfer matrix for quantum noise calculations.

_transfer_matrix_N(p, fq)

Compute the N transfer matrix for quantum noise calculations.

_transfer_matrix_P(p, fq)

Compute the P transfer matrix for quantum noise calculations.

_transfer_matrix_Q(p, fq)

Compute the Q transfer matrix for quantum noise calculations.

_transfer_vector_D(p, fq)

Compute the D transfer vector for quantum noise calculations.

_welch_psd(strain; segmentlength, overlap, window, nfft)

Estimate the one-sided power spectral density of a detector strain using Welch's method.

This is an internal helper used by SampledPSD and shouldn't be used directly. The detector strain is first windowed before the PSD is estimated using the specified segment length, overlap, and FFT length.

This uses welch_pgram from DSP.jl.

Arguments

• strain::DetectorStrain: Time-domain detector strain.

Keyword Arguments

• segmentlength::Int: Number of samples in each Welch segment.
• overlap: Segment overlap specified either as a fraction of the segment length or as an integer number of samples.
• window: Window function applied to the strain.
• nfft::Int: FFT length used during spectral estimation.

Returns

Returns a tuple (frequency, psd) containing the sampled frequencies and the estimated power spectral density.

antenna_response(detector, α, δ, ψ, θ_GMST)

Compute the antenna pattern functions $F_+$ and $F_\times$ for a gravitational-wave detector. An implementation of the detector response formula in Anderson et al (2001).

Calculates the wave frame polarization vectors X and Y. Then the Detector response functions are obtained by:

F₊ = Xᵀ D X - Yᵀ D Y Fₓ = Xᵀ D Y + Yᵀ D X

Arguments

• detector::Detector: Detector.
• α: Right ascension (rad).
• δ: Declination (rad).
• ψ: Polarization angle (rad).
• θ_GMST: Greenwich mean sidereal time (rad).

Returns

A tuple (F₊, Fₓ) containing the plus and cross antenna pattern functions.

arrival_time_difference(det₁, det₂, α, δ, time)

Returns the difference in gravitational-wave arrival time between two detectors.

The returned value is positive when the wavefront reaches det₁ after det₂.

Arguments

• det₁::Detector: First Detector.
• det₂::Detector: Second Detector.
• α::Real: Source right ascension (radians).
• δ::Real: Source declination (radians).
• time::GPSTime: GPSTime at which to evaluate the source position.

Returns

Returns the arrival time difference in seconds.

bandpass(strain, f_low, f_high; order = 4)

Apply a zero-phase Butterworth band-pass filter to a detector strain time series.

Band-pass filtering suppresses low-frequency seismic noise and high-frequency instrumental noise while preserving the frequency band of interest.

Filtering is performed forwards and backwards to eliminate phase distortion.

Arguments

• strain::DetectorStrain: Input detector strain (DetectorStrain).
• f_low::Real: Lower cutoff frequency (Hz).
• f_high::Real: Upper cutoff frequency (Hz).
• order = 4 (kwarg): Butterworth filter order.

Returns

Returns a new DetectorStrain containing the filtered strain.

bandstop(strain, f_low, f_high; order = 4)

Apply a zero-phase Butterworth band-stop filter to a detector strain time series.

Band-stop filtering suppresses signals within a specified frequency band while preserving frequencies outside that band. It is commonly used to remove narrow- band instrumental noise, such as power-line interference.

Filtering is applied forward and backward using filtfilt, resulting in zero-phase filtering with no phase distortion.

Arguments

• strain::DetectorStrain: Input detector strain (DetectorStrain).
• f_low::Real: Lower cutoff frequency (Hz).
• f_high::Real: Upper cutoff frequency (Hz).
• order = 4 (kwarg): Butterworth filter order. Higher orders produce a steeper transition between the stopband and passbands.

Returns

Returns a new DetectorStrain containing the filtered strain.

check_lalsuite()

Verify that the required LALSuite shared libraries can be loaded.

This function checks that both liblal and liblalsimulation are available to Julia's dynamic linker. If either library cannot be loaded, an error is thrown with diagnostic information describing the missing dependency.

This check is performed automatically by waveform-generation routines, but may also be called directly to diagnose installation issues.

coalescence_time(snr)

Return the estimated coalescence time of a matched-filter signal.

The coalescence time is estimated as the time corresponding to the peak of the matched-filter signal-to-noise ratio.

Arguments

• snr::SNRTimeSeries: Matched-filter signal-to-noise ratio time series (SNRTimeSeries).

Returns

Returns the estimated coalescence time as a GPSTime.

coherence(a, b, psd_a, psd_b)

Compute the magnitude-squared coherence of two detector strains.

The coherence is defined as

\[\gamma^2(f) = \frac{|S_{xy}(f)|^2}{S_{xx}(f)\,S_{yy}(f)}\]

where $S_{xy}$ is the cross-spectral density and $S_{xx}$, $S_{yy}$ are the auto-spectral densities (power spectral densities).

When both strains come from the same detector, a single PSD can be passed instead of two.

The coherence is a real-valued quantity in the interval $[0, 1]$. A value of 1 indicates perfect linear correlation at frequency $f$, while a value of 0 indicates no correlation.

Arguments

• a::DetectorFrequencyStrain or DetectorStrain: First detector strain.
• b::DetectorFrequencyStrain or DetectorStrain: Second detector strain.
• psd_a::AbstractPSD: One-sided noise PSD for the first detector.
• psd_b::AbstractPSD: One-sided noise PSD for the second detector.

Returns

Returns a NamedTuple with fields frequency and coherence containing the sampled frequencies and the real-valued coherence.

coherence_whitened(a, b)

Compute the magnitude-squared coherence of two whitened detector strains.

The coherence is defined as

\[\gamma^2(f) = \frac{|S_{xy}(f)|^2}{S_{xx}(f)\,S_{yy}(f)}\]

where $S_{xy} = \tilde{a}^*\tilde{b}$ and $S_{xx} = |\tilde{a}|^2$, $S_{yy} = |\tilde{b}|^2$ are the cross- and auto-spectral densities of the whitened strains.

Arguments

• a::DetectorFrequencyStrain or DetectorStrain: First whitened detector strain.
• b::DetectorFrequencyStrain or DetectorStrain: Second whitened detector strain.

Returns

Returns a NamedTuple with fields frequency and coherence containing the sampled frequencies and the real-valued coherence.

Warning

This function assumes that both input strains have already been whitened. Passing unwhitened strains will produce incorrect results. Use coherence for unwhitened strains.

cross_spectral_density(a, b, psd_a, psd_b)

Compute the noise-weighted cross-spectral density of two detector strains.

The cross-spectral density is defined as

\[S_{xy}(f) = \frac{\tilde{a}^*(f)\tilde{b}(f)}{\sqrt{S_{n,a}(f)\,S_{n,b}(f)}}\]

where $\tilde{a}(f)$ and $\tilde{b}(f)$ are the Fourier transforms of the input strains and $S_{n,a}(f)$, $S_{n,b}(f)$ are the one-sided strain noise power spectral densities for each detector.

When both strains come from the same detector, a single PSD can be passed instead of two.

Arguments

• a::DetectorFrequencyStrain or DetectorStrain: First detector strain.
• b::DetectorFrequencyStrain or DetectorStrain: Second detector strain.
• psd_a::AbstractPSD: One-sided noise PSD for the first detector.
• psd_b::AbstractPSD: One-sided noise PSD for the second detector.

Returns

Returns a NamedTuple with fields frequency and csd containing the sampled frequencies and the complex cross-spectral density.

cross_spectral_density_whitened(a, b)

Compute the cross-spectral density of two whitened detector strains.

The cross-spectral density is defined as

\[S_{xy}(f) = \tilde{a}^*(f)\tilde{b}(f)\]

where $\tilde{a}(f)$ and $\tilde{b}(f)$ are the Fourier transforms of the whitened input strains.

Arguments

• a::DetectorFrequencyStrain or DetectorStrain: First whitened detector strain.
• b::DetectorFrequencyStrain or DetectorStrain: Second whitened detector strain.

Returns

Returns a NamedTuple with fields frequency and csd containing the sampled frequencies and the complex cross-spectral density.

Warning

This function assumes that both input strains have already been whitened. Passing unwhitened strains will produce incorrect results. Use cross_spectral_density for unwhitened strains.

demean(strain)

Remove the mean (DC offset) from a detector strain time series.

Demeaning subtracts the arithmetic mean of the strain samples, centering the time series around zero.

Arguments

• strain::DetectorStrain: Input detector strain (DetectorStrain).

Returns

Returns a new DetectorStrain with the mean removed.

detrend(strain; method=:linear|:constant)

Removes a trend from a detector strain time series, either constant (mean) or linearly changing over time.

Detrending is often used to remove low-frequency noise or drift from the data.

Arguments

• strain::DetectorStrain: Input detector strain (DetectorStrain).
• method::Symbol: Detrending method, either :linear (default) or :constant.

Returns

Returns a new DetectorStrain. For constant detrending, removes the mean. Same as demean. For linear detrending, finds and subtracts the best fitting linear trend.

generate_fd_waveform(approximant, m₁, m₂; kwargs...)

Generate a frequency-domain gravitational waveform for a compact binary coalescence using a LALSuite waveform model.

The returned GWFrequencySeries contains the plus and cross polarisations, $h̃_+$ and $h̃_\times$, sampled at a uniform frequency spacing.

All inputs must be specified in SI units:

• masses in kilograms,
• distance in metres,
• frequencies in hertz,
• angles in radians.

Arguments

• approximant::Approximant: The waveform model to use, chosen from the Approximant enum. Only approximants that are actually implemented in LALSimulation will produce a waveform. The full enum includes many historical placeholder values; using one that is not implemented will result in an error.

• m₁::Real: Mass of the first compact object (kg).

• m₂::Real: Mass of the second compact object (kg).

Keyword Arguments

Spin parameters

Dimensionless spin components in the source frame.

• S₁x, S₁y, S₁z = 0.0
• S₂x, S₂y, S₂z = 0.0

Source geometry

• distance = 1e6 * 3.085677581491367e16: Luminosity distance to the source (1 Mpc).

• inclination = 0.0: Inclination angle between the orbital angular momentum and the line of sight.

• ϕref = 0.0: Orbital phase at the reference frequency f_ref.

• longAscNodes = 0.0: Longitude of the ascending node, defined as $\Omega - \pi/2$.

Orbital parameters

• eccentricity = 0.0: Orbital eccentricity at the reference epoch.

• meanPerAno = 0.0: Mean anomaly at the reference epoch (rad).

Sampling and frequency settings

• δf = 1 / 16384: Frequency resolution (Hz).

• f_min = 40.0: Starting gravitational-wave frequency (Hz).

• f_max = 0.0: Ending gravitational-wave frequency (Hz). A value of 0 uses the default maximum frequency chosen by the waveform model.

• f_ref = 0.0: Reference gravitational-wave frequency (Hz). A value of 0 uses the default reference frequency chosen by the waveform model.

Advanced

• LALparams = C_NULL: Pointer to a LAL dictionary containing additional waveform configuration parameters.

Returns

A GWFrequencySeries containing the plus and cross polarisations, $h̃_+$ and $h̃_\times$, sampled at a uniform frequency spacing.

generate_td_waveform(approximant, m₁, m₂; kwargs...)

Generate a time-domain gravitational waveform for a compact binary coalescence using a LALSuite waveform model.

The returned GWTimeSeries contains the plus and cross polarisations, $h_+$ and $h_\times$, sampled at a uniform cadence.

All inputs must be specified in SI units:

• masses in kilograms,
• distance in metres,
• frequencies in hertz,
• angles in radians.

Arguments

• approximant::Approximant: The waveform model to use, chosen from the Approximant enum. Only approximants that are actually implemented in LALSimulation will produce a waveform. The full enum includes many historical placeholder values; using one that is not implemented will result in an error.

• m₁::Real: Mass of the first compact object (kg).

• m₂::Real: Mass of the second compact object (kg).

Keyword Arguments

Spin parameters

Dimensionless spin components in the source frame.

• S₁x, S₁y, S₁z = 0.0
• S₂x, S₂y, S₂z = 0.0

Source geometry

• distance = 1e6 * 3.085677581491367e16: Luminosity distance to the source (1 Mpc).

• inclination = 0.0: Inclination angle between the orbital angular momentum and the line of sight.

• ϕref = 0.0: Orbital phase at the reference frequency f_ref.

• longAscNodes = 0.0: Longitude of the ascending node, defined as $\Omega - \pi/2$.

Orbital parameters

• eccentricity = 0.0: Orbital eccentricity at the reference epoch.

• meanPerAno = 0.0: Mean anomaly at the reference epoch (rad).

Sampling and frequency settings

• δt = 1 / 16384: Sampling interval (s).

• f_min = 40.0: Starting gravitational-wave frequency (Hz).

• f_ref = 0.0: Reference gravitational-wave frequency (Hz). A value of 0 uses the default reference frequency chosen by the waveform model.

Advanced

• LALparams = C_NULL: Pointer to a LAL dictionary containing additional waveform configuration parameters.

Returns

A GWTimeSeries containing the plus and cross polarisations, $h_+$ and $h_\times$, sampled at a uniform cadence.

greenwich_sidereal_time(time, equation_of_equinoxes = 0.0)

Returns the Greenwich Sidereal Time (GST) corresponding to a specified GPS time.

By default (equation_of_equinoxes = 0.0), this calculates the Greenwich Mean Sidereal Time. Apparent sidereal time is computed by providing the equation of the equinoxes.

This is a direct wrapper around LALSuite's XLALGreenwichSiderealTime.

Arguments

• time::GPSTime: The absolute GPSTime to evaluate.
• equation_of_equinoxes::Float64: (Optional) The equation of the equinoxes, strictly in seconds of time. Defaults to 0.0.

Returns

Returns the sidereal time in radians as a Float64, measured from the Julian epoch (J2000). Note: The result is NOT modulo 2π.

hann(strain)

Apply a Hann window to a detector strain time series.

Windowing tapers the beginning and end of the time series to reduce spectral leakage in subsequent frequency-domain analyses, such as Fourier transforms and power spectral density estimation.

The Hann window smoothly reduces the signal amplitude to zero at both ends of the time series.

Arguments

• strain::DetectorStrain: Input detector strain (DetectorStrain).

Returns

Returns a new DetectorStrain containing the windowed strain.

highpass(strain, f_low; order = 4)

Apply a zero-phase Butterworth high-pass filter to a detector strain time series.

High-pass filtering suppresses low-frequency seismic noise while preserving the frequency band of interest.

Filtering is performed forwards and backwards to eliminate phase distortion.

Arguments

• strain::DetectorStrain: Input detector strain (DetectorStrain).
• f_low::Real: Lower cutoff frequency (Hz).
• order = 4 (kwarg): Butterworth filter order.

Returns

Returns a new DetectorStrain containing the filtered strain.

inject(signal, noise)

Add a gravitational-wave signal to a noise realisation.

Superimposes two detector strains, or injects a signal into a noise background described by NoiseTimeSeries.

Arguments

• signal::DetectorStrain: Gravitational-wave signal (DetectorStrain).
• noise::DetectorStrain or NoiseTimeSeries: Noise realisation, either as a DetectorStrain or a NoiseTimeSeries sampled at the same rate.

Returns

A DetectorStrain containing $\mathtt{signal} + \mathtt{noise}$.

inner(a, b, psd)

Compute the noise-weighted inner product of two detector strains.

If $\tilde{a}(f)$ and $\tilde{b}(f)$ denote the Fourier transforms of the input strains and $S_n(f)$ is the one-sided strain noise power spectral density, the inner product is

\[(a|b) = 4\,\mathrm{Re} \int_0^\infty \frac{\tilde{a}^*(f)\tilde{b}(f)}{S_n(f)} \,df\]

For already whitened strains, use inner_whitened instead.

Arguments

• a::DetectorFrequencyStrain or DetectorStrain: First detector strain (DetectorFrequencyStrain or DetectorStrain).
• b::DetectorFrequencyStrain or DetectorStrain: Second detector strain (DetectorFrequencyStrain or DetectorStrain).
• psd::AbstractPSD: One-sided strain noise power spectral density (AbstractPSD).

Returns

Returns the noise-weighted inner product of the two detector strains.

inner_whitened(a, b)

Compute the inner product of two whitened detector strains.

This function computes the standard Euclidean inner product between two whitened strains in the frequency domain. If $a_w(f)$ and $b_w(f)$ denote the whitened strains, the inner product is

\[(a_w|b_w) = 4 \, \mathrm{Re} \int_0^\infty \tilde{a}_w^*(f)\tilde{b}_w(f) \, df.\]

This is equivalent to the standard noise-weighted inner product applied to the corresponding unwhitened strains. For non-whitened strains, use inner instead.

Arguments

• a::DetectorFrequencyStrain or DetectorStrain: First whitened detector strain (DetectorFrequencyStrain or DetectorStrain).
• b::DetectorFrequencyStrain or DetectorStrain: Second whitened detector strain (DetectorFrequencyStrain or DetectorStrain).

Returns

Returns the inner product of the two whitened detector strains.

Warning

This function assumes that both input strains have already been whitened. Passing unwhitened strains will produce incorrect results. Use inner to compute the noise-weighted inner product of unwhitened detector strains.

lowpass(strain, f_high; order = 4)

Apply a zero-phase Butterworth low-pass filter to a detector strain time series.

Low-pass filtering suppresses high-frequency instrumental noise while preserving the frequency band of interest.

Filtering is performed forwards and backwards to eliminate phase distortion.

Arguments

• strain::DetectorStrain: Input detector strain (DetectorStrain).
• f_high::Real: Upper cutoff frequency (Hz).
• order = 4 (kwarg): Butterworth filter order.

Returns

Returns a new DetectorStrain containing the filtered strain.

match(a, b, psd)

Compute the maximised match between two detector strains.

The match is the noise-weighted overlap maximised over both a relative phase shift and a relative time offset,

\[\mathcal{M}(a, b) = \max_{\Delta t, \phi} \frac{(a \,|\, b(\Delta t, \phi))}{\|a\| \, \|b\|}.\]

The phase maximisation is handled analytically by computing the complex correlation time series

\[z(\Delta t) = 4 \int_0^\infty \frac{\tilde{a}^*(f) \, \tilde{b}(f)}{S_n(f)} \, e^{2\pi i f \Delta t} \, df\]

and taking $|z(\Delta t)|$. The time maximisation selects the peak of $|z(\Delta t)|$ across all integer sample shifts.

Arguments

• a::DetectorFrequencyStrain or DetectorStrain: First detector strain (DetectorFrequencyStrain or DetectorStrain).
• b::DetectorFrequencyStrain or DetectorStrain: Second detector strain (DetectorFrequencyStrain or DetectorStrain).
• psd::AbstractPSD: One-sided strain noise power spectral density (AbstractPSD).

Returns

Returns the maximised match, a scalar in $[0, 1]$.

matched_filter(data, template, psd)

Compute the matched-filter signal-to-noise ratio (SNR) time series.

The matched filter computes the signal-to-noise ratio as a function of time by correlating the detector data with a template weighted by the inverse of the detector noise power spectral density. In the frequency domain, the matched-filter output is

\[z(t) = 4\mathcal{F}^{-1} \left[ \frac{\tilde{d}^*(f)\tilde{h}(f)}{S_n(f)} \right]\]

where $\tilde{d}(f)$ and $\tilde{h}(f)$ are the Fourier transforms of the detector data and template, respectively, and $S_n(f)$ is the one-sided strain noise power spectral density. The returned signal-to-noise ratio is obtained by normalizing the matched-filter output by the noise-weighted norm of the template,

\[\rho(t) = \frac{z(t)}{\sqrt{(h|h)}}\]

Arguments

• data::DetectorFrequencyStrain or DetectorStrain: Detector data (DetectorFrequencyStrain or DetectorStrain).
• template::DetectorFrequencyStrain or DetectorStrain: Template detector strain (DetectorFrequencyStrain or DetectorStrain).
• psd::AbstractPSD: One-sided strain noise power spectral density (AbstractPSD).

Returns

Returns an SNRTimeSeries containing the matched-filter signal-to-noise ratio as a function of time.

mismatch(a, b, psd)

Compute the noise-weighted mismatch of two detector strains.

The mismatch is defined as one minus the noise-weighted overlap of the two strains,

\[\mathcal{M}(a, b) = 1 - \mathcal{O}(a, b).\]

A mismatch of zero indicates identical strains, while larger values indicate increasing dissimilarity.

Arguments

• a::DetectorFrequencyStrain or DetectorStrain: First detector strain (DetectorFrequencyStrain or DetectorStrain).
• b::DetectorFrequencyStrain or DetectorStrain: Second detector strain (DetectorFrequencyStrain or DetectorStrain).
• psd::AbstractPSD: One-sided strain noise power spectral density (AbstractPSD).

Returns

Returns the noise-weighted mismatch of the two detector strains.

mismatch_whitened(a, b)

Compute the mismatch of two whitened detector strains.

The mismatch is defined as one minus the overlap of the two whitened strains,

\[\mathcal{M}(a_w, b_w) = 1 - \mathcal{O}(a_w, b_w).\]

This is equivalent to the noise-weighted mismatch of the corresponding unwhitened detector strains.

Arguments

• a::DetectorFrequencyStrain or DetectorStrain: First whitened detector strain (DetectorFrequencyStrain or DetectorStrain).
• b::DetectorFrequencyStrain or DetectorStrain: Second whitened detector strain (DetectorFrequencyStrain or DetectorStrain).

Returns

Returns the mismatch of the two whitened detector strains.

Warning

This function assumes that both input strains have already been whitened. Passing unwhitened strains will produce incorrect results. Use mismatch to compute the noise-weighted mismatch of unwhitened detector strains.

noise(model, n, δt; epoch=GPSTime(0))

Generate a realization of detector noise.

Currently, noise is generated as a stationary Gaussian random process whose frequency-domain power is determined by the supplied noise model.

Arguments

• model::AbstractNoiseModel: Noise model.
• n::Integer: Number of samples.
• δt::Real: Sampling interval.

Keyword Arguments

• epoch::GPSTime=GPSTime(0): GPSTime of the first sample.

Returns

Returns a NoiseTimeSeries containing the generated detector noise.

norm(strain, psd)

Compute the noise-weighted norm of a detector strain.

The noise-weighted norm is defined as the square root of the noise-weighted inner product of the strain with itself,

\[\abs(h) = \sqrt{(h|h)}.\]

Arguments

• strain::DetectorFrequencyStrain or DetectorStrain: Detector strain (DetectorFrequencyStrain or DetectorStrain).
• psd::AbstractPSD: One-sided strain noise power spectral density (AbstractPSD).

Returns

Returns the noise-weighted norm of the detector strain.

norm_whitened(strain)

Compute the norm of a whitened detector strain.

The norm is defined as the square root of the inner product of the whitened strain with itself,

\[\abs(h_w) = \sqrt{(h_w|h_w)}.\]

This is equivalent to the noise-weighted norm of the corresponding unwhitened detector strain.

Arguments

• strain::DetectorFrequencyStrain or DetectorStrain: Whitened detector strain (DetectorFrequencyStrain or DetectorStrain).

Returns

Returns the norm of the whitened detector strain.

Warning

This function assumes that the input strain has already been whitened. Passing an unwhitened strain will produce incorrect results. Use norm to compute the noise-weighted norm of an unwhitened detector strain.

optimal_snr(strain, psd)

Compute the optimal signal-to-noise ratio (SNR) of a detector strain.

The optimal SNR is defined as the noise-weighted norm of the detector strain,

\[\rho_\mathrm{opt} = \sqrt{(h|h)}\]

Arguments

• strain::DetectorFrequencyStrain or DetectorStrain: Detector strain (DetectorFrequencyStrain or DetectorStrain).
• psd::AbstractPSD: One-sided strain noise power spectral density (AbstractPSD).

Returns

Returns the optimal signal-to-noise ratio.

optimal_snr_whitened(strain)

Compute the optimal signal-to-noise ratio (SNR) of a whitened detector strain.

The optimal SNR is defined as the norm of the whitened detector strain,

\[\rho_\mathrm{opt} = \sqrt{(h_w|h_w)}\]

This is equivalent to the optimal signal-to-noise ratio of the corresponding unwhitened detector strain.

Arguments

• strain::DetectorFrequencyStrain or DetectorStrain: Whitened detector strain (DetectorFrequencyStrain or DetectorStrain).

Returns

Returns the optimal signal-to-noise ratio.

Warning

This function assumes that the input strain has already been whitened. Passing an unwhitened strain will produce incorrect results. Use optimal_snr to compute the optimal signal-to-noise ratio of an unwhitened detector strain.

overlap(a, b, psd)

Compute the noise-weighted overlap of two detector strains.

The overlap is defined as the noise-weighted inner product of the two strains, normalized by their noise-weighted norms,

\[\mathcal{O}(a, b) = \frac{(a|b)}{\sqrt{(a|a)(b|b)}}.\]

Arguments

• a::DetectorFrequencyStrain or DetectorStrain: First detector strain (DetectorFrequencyStrain or DetectorStrain).
• b::DetectorFrequencyStrain or DetectorStrain: Second detector strain (DetectorFrequencyStrain or DetectorStrain).
• psd::AbstractPSD: One-sided strain noise power spectral density (AbstractPSD).

Returns

Returns the noise-weighted overlap of the two detector strains.

overlap_whitened(a, b)

Compute the overlap of two whitened detector strains.

The overlap is defined as the inner product of the two whitened strains, normalized by their norms,

\[\mathcal{O}(a_w, b_w) = \frac{(a_w|b_w)}{\sqrt{(a_w|a_w)(b_w|b_w)}}.\]

This is equivalent to the noise-weighted overlap of the corresponding unwhitened detector strains.

Arguments

• a::DetectorFrequencyStrain or DetectorStrain: First whitened detector strain (DetectorFrequencyStrain or DetectorStrain).
• b::DetectorFrequencyStrain or DetectorStrain: Second whitened detector strain (DetectorFrequencyStrain or DetectorStrain).

Returns

Returns the overlap of the two whitened detector strains.

Warning

This function assumes that both input strains have already been whitened. Passing unwhitened strains will produce incorrect results. Use overlap to compute the noise-weighted overlap of unwhitened detector strains.

peak_snr(snr)

Return the peak matched-filter signal-to-noise ratio.

Arguments

• snr::SNRTimeSeries: Matched-filter signal-to-noise ratio time series (SNRTimeSeries).

Returns

Returns the maximum signal-to-noise ratio in the time series.

precompute(model::InterferometerModel)

Precompute all frequency-independent quantities required for efficient evaluation of the interferometer quantum and thermal noise models.

The returned PreparedInterferometer is a lightweight, immutable object that can be evaluated repeatedly with negligible overhead.

project(detector, waveform, α, δ, ψ)

Project a gravitational-wave signal onto a detector.

Computes the strain measured by a Detector or a collection of detectors for a gravitational wave incident from the specified sky location and polarisation. The projection uses the detector antenna pattern functions evaluated at the Greenwich mean sidereal time corresponding to the waveform epoch.

This method is defined for both GWTimeSeries and GWFrequencySeries.

Arguments

• detector::Detector or detectors: Detector or collection of detectors receiving the signal.
• waveform: Gravitational-wave plus and cross polarisations stored as a GWTimeSeries or GWFrequencySeries.
• α::Real: Right ascension of the source (rad).
• δ::Real: Declination of the source (rad).
• ψ::Real: Polarization angle (rad).

Returns

Returns a detector strain with the same sampling as the input waveform. Time-domain waveforms return a DetectorStrain, while frequency-domain waveforms return a DetectorFrequencyStrain.

qtransform(strain; Q=8, frequency_range=(20, 500), sd=3, frange=:log)

Compute the Q-transform of a detector strain time series.

The Q-transform decomposes the strain into a time-frequency representation using constant-Q Morlet wavelets (Gabor atoms). The resulting energy spectrogram is normalised by the noise power spectral density so that white noise produces uniform energy ≈ 1.

Arguments

• strain::DetectorStrain: Time-domain detector strain.

Keyword Arguments

• Q::Int = 8: Quality factor. Higher Q gives better frequency resolution at the cost of time resolution. Typical values: 4–64.
• frequency_range::Tuple{Real,Real} = (20, 500): Frequency band (Hz) over which to compute the transform.
• sd::Int = 3: Number of standard deviations for the Morlet wavelet envelope. Controls the time-frequency tiling.
• frange::Symbol = :log: Frequency grid spacing. :log for logarithmic (standard for burst searches), :linear for linear.

Returns

Returns a QPlane containing the time-frequency energy spectrogram and the corresponding time and frequency grids.

Notes

The transform slides a Morlet wavelet (Gaussian-enveloped cosine) across the strain at each frequency. The window length is n_w = Q * fs / (π * f) and the hop size is n_w / (2 * sd). The energy at each time-frequency tile is |⟨h, ψ⟩|², normalised by the PSD estimate in a band f ± f/(2Q) so that white noise produces unit expectation.

The time resolution varies across frequency as Δt = Q / (π f), so low-frequency tiles are wider in time than high-frequency tiles.

quantum_noise(model, f)

Evaluate the quantum strain noise power spectral density at frequency f.

shift!(strain, Δt)

In-place time-shift of a detector strain by $\Delta t$.

Modifies the input strain in place in the frequency domain. For time-domain strains, the Fourier transform is computed internally and a new DetectorStrain is returned (allocation is unavoidable for the time-domain case).

Arguments

• strain::DetectorFrequencyStrain or DetectorStrain: Detector strain (DetectorFrequencyStrain or DetectorStrain).
• Δt::Real: Time shift in seconds.

Returns

The modified strain with the time shift applied.

shift(strain, Δt)

Time-shift a detector strain by $\Delta t$.

The shift is applied in the frequency domain via a phase rotation,

\[\tilde{h}(f) \rightarrow \tilde{h}(f) \, e^{-2\pi i f \Delta t}.\]

Negative $\Delta t$ shifts the signal backward in time.

Arguments

• strain::DetectorFrequencyStrain or DetectorStrain: Detector strain (DetectorFrequencyStrain or DetectorStrain).
• Δt::Real: Time shift in seconds.

Returns

Returns a new DetectorFrequencyStrain or DetectorStrain with the strain shifted by $\Delta t$.

simulate(detector, generator, source, α, δ, ψ, psd)

Simulate a complete gravitational-wave observation.

Chains waveform generation, detector projection, and additive Gaussian noise injection in a single call.

Arguments

• detector::Detector or DetectorCollection: Receiving detector(s) (Detector or DetectorCollection).
• generator: Waveform generator (e.g. WaveformGenerator or FDWaveformGenerator).
• src::CBCSource: Compact binary source parameters (CBCSource).
• α::Real: Right ascension of the source (rad).
• δ::Real: Declination of the source (rad).
• ψ::Real: Polarisation angle (rad).
• psd::AbstractPSD: One-sided strain noise power spectral density (AbstractPSD).

Returns

A DetectorStrain containing the simulated observation.

snr(data, template, psd)

Compute the matched-filter signal-to-noise ratio (SNR).

The matched-filter SNR is defined as the noise-weighted inner product of the detector data with a template, normalized by the noise-weighted norm of the template,

\[\rho = \frac{(d|h)}{\sqrt{(h|h)}}\]

Arguments

• data::DetectorFrequencyStrain or DetectorStrain: Detector data (DetectorFrequencyStrain or DetectorStrain).
• template::DetectorFrequencyStrain or DetectorStrain: Template detector strain (DetectorFrequencyStrain or DetectorStrain).
• psd::AbstractPSD: One-sided strain noise power spectral density (AbstractPSD).

Returns

Returns the matched-filter signal-to-noise ratio.

snr_whitened(data, template)

Compute the matched-filter signal-to-noise ratio (SNR) of whitened detector strains.

The matched-filter SNR is defined as the inner product of the whitened detector data with a whitened template, normalized by the norm of the template,

\[\rho = \frac{(d_w|h_w)}{\sqrt{(h_w|h_w)}}\]

This is equivalent to the matched-filter SNR of the corresponding unwhitened detector strains.

Arguments

• data::DetectorFrequencyStrain or DetectorStrain: Whitened detector data (DetectorFrequencyStrain or DetectorStrain).
• template::DetectorFrequencyStrain or DetectorStrain: Whitened template detector strain (DetectorFrequencyStrain or DetectorStrain).

Returns

Returns the matched-filter signal-to-noise ratio.

Warning

This function assumes that both input strains have already been whitened. Passing unwhitened strains will produce incorrect results. Use snr to compute the matched-filter signal-to-noise ratio of unwhitened detector strains.

source_direction

Returns the Earth-fixed unit vector pointing from the geocenter toward a source at right ascension α and declination δ evaluated at the given GPS time.

Arguments

• α::Real: The right ascension of the source in radians.
• δ::Real: The declination of the source in radians.
• time::GPSTime: GPSTime at which to evaluate the source direction.

Returns

Returns a tuple (x, y, z) representing the unit vector in the Earth-fixed frame.

strain_asd(model, f)

Evaluate the amplitude spectral density of the interferometer strain noise.

strain_noise(model, f)

Evaluate the total interferometer strain noise power spectral density at frequency f.

The total strain noise is the sum of the quantum and thermal noise contributions,

\[Sₕ(f) = Sₕᵠ(f) + Sₕᵗʰ(f).\]

thermal_noise(model, f)

Evaluate the total thermal strain noise power spectral density.

The total thermal noise is the sum of the suspension and mirror coating thermal contributions,

Sₕ(f) = Sₕˢᵘˢᵖ(f) + Sₕᶜᵒᵃᵗ(f).

time_delay(detector, α, δ, time)
time_delay(detectors, α, δ, time)

Returns the gravitational-wave arrival time at a detector relative to the Earth's center. For a collection of detectors, returns a collection of Float64s with the same structure as the input.

A positive value indicates that the wavefront reaches the detector after reaching the geocenter.

This is the Earth-center special case of arrival_time_difference.

Arguments

• detector::Detector or detectors: A single Detector or a collection of detectors.
• α::Real: Source right ascension in radians.
• δ::Real: Source declination in radians.
• time::GPSTime: The absolute GPSTime at which to evaluate.

Returns

Returns the gravitational-wave arrival time delay relative to the Earth's center.

When a single detector is provided, returns the arrival time delay in seconds.

When a collection of detectors is provided, the result has the same container type as the input, with each detector replaced by its corresponding arrival time delay.

unwhiten(strain, psd)

Reverse the whitening transformation on a detector strain.

The input strain is multiplied by the amplitude spectral density (ASD) corresponding to the supplied noise model, recovering the original unwhitened strain. If $\tilde{h}_\mathrm{w}(f)$ denotes the whitened strain and $S_n(f)$ the one-sided power spectral density, the unwhitened strain is

\[\tilde{h}(f) = \tilde{h}_\mathrm{w}(f) \, \sqrt{S_n(f)}.\]

Arguments

• strain::DetectorFrequencyStrain or DetectorStrain: Whitened detector strain in frequency or time domain (DetectorFrequencyStrain or DetectorStrain).
• psd::AbstractPSD: One-sided strain noise power spectral density (AbstractPSD).

Returns

Returns a new DetectorFrequencyStrain or DetectorStrain containing the unwhitened strain.

whiten(strain, psd)

Whiten a detector strain in the frequency or time domain.

The input strain is divided by the amplitude spectral density (ASD) corresponding to the supplied noise model. If $\tilde{h}(f)$ denotes the Fourier transform of the strain and $S_n(f)$ the one-sided power spectral density, the whitened strain is

\[\tilde{h}_\mathrm{w}(f) = \frac{\tilde{h}(f)}{\sqrt{S_n(f)}}.\]

Arguments

• strain::DetectorFrequencyStrain or DetectorStrain: Detector strain in frequency or time domain (DetectorFrequencyStrain or DetectorStrain).
• psd::AbstractPSD: One-sided strain noise power spectral density (AbstractPSD).

Returns

Returns a new DetectorFrequencyStrain or DetectorStrain containing the whitened strain.

write_psd(filename, psd, frequencies)

Sample a PSD on the supplied frequency grid and write a two-column text file containing

frequency    PSD

Plot the strain noise of an interferometer model.

Plot a PSD or ASD.

Plot a prepared interferometer model.

Plot the amplitude (or power) spectrum of a frequency-domain strain.

Keyword Arguments

• asd::Bool = true: If true plot the amplitude spectral density (√S); if false plot the power spectral density (S).

Plot a detector strain time series.

Plot a noise time series.

qplane(qp; norm=:log)

Plot a Q-transform spectrogram as a heatmap.

Keyword Arguments

• norm::Symbol = :log: Colour-scale normalisation. :log for log₁₀ (standard for GW burst analysis), :linear for linear, :dB for decibels (10 log₁₀).

Plot a matched-filter signal-to-noise ratio time series.

Plot a sampled power spectral density.

The sampled PSD is shown as discrete markers together with the piecewise linear interpolation used to evaluate the spectrum between sampled frequencies.