Development documentation · 0.2.3 30c2f8ba · Intro examples tested with 0.2.3 · Version details · Known limitations

Validated Algorithms#

Note

Who should read this page?

  • Researchers who want to verify the mathematical and physical validity of the methods.

  • Developers who need to know the numerical tolerances between GWexpy and external libraries (SciPy, LALSuite, etc.).

  • Users who need to check the data characteristics (stationarity, Gaussianity, etc.) assumed by each algorithm.

Important

Advanced validation/theory companion

This page intentionally stays under the user guide so readers can discover it from feature docs, but it is not an onboarding page. Treat it as the advanced/theory landing for audit-oriented reading across the API reference, theory notes, and targeted tutorials. For first-use guidance, start with Getting Started, Prerequisites and Conventions, or the linked tutorials for each method.

The algorithms listed on this page have public implementation tests, theory references, or audit records. Those evidence types are distinct and their scope is stated for each algorithm below.

Validation Criteria and Numerical Precision#

The algorithms listed on this page are assessed against the evidence recorded in their own sections.

  • Tolerance: Numerical tolerance is algorithm- and test-specific. The relevant test or audit entry states the comparison and acceptance condition where one is available.

  • Invariance: Scale-invariance checks apply only to algorithms whose evidence explicitly records such a check; they are not a package-wide guarantee.

Objective Evidence#

The summaries on this page are backed by the public evidence trail collected here.

The evidence table is intentionally column-dense so the audit trail stays on one page. On mobile, horizontal scrolling is expected and should align with the shared table CSS used across the docs.

Evidence type

Public source

What it shows

Audit scope

Validation summary

Which algorithms were reviewed and which numerical questions were checked

Consolidated findings

Per-algorithm sections

Cross-reviewed findings, severity, and agreement across independent audits

Fix history

Audit Trail

What changed after the review findings were merged and addressed

Field-specific physics review

k-space calculation

Physics and axis-consistency review for ScalarField FFT behavior

Source References#

Use the source keys below in the per-algorithm sections so the bibliography and source trail stay centralized on this page.

Key

Source

Used for

S1

Press et al., Numerical Recipes (3rd ed., 2007), §12.3.2

k-space calculation and FFT-axis interpretation

S2

Percival, D.B. & Walden, A.T., Spectral Analysis for Physical Applications (1993), Eq.(56)

Welch overlap / VIF correction

S3

Prerequisites and Conventions

Time-system assumptions and FFT-related conventions referenced by validation notes

S4

Numerical Stability

Adaptive stabilization guidance for whitening and related preprocessing paths

S5

Objective Evidence and the Audit Trail below

Repository-backed implementation evidence for transient FFT behavior and complex GLS / MCMC handling

Validated Algorithms Summary Table#

Algorithm

Primary API

API page

Evidence

Related tutorial

k-space calculation

ScalarField.fft_space()

Fields API / ScalarField

Objective Evidence

Field Intro

Transient FFT

TimeSeries.fft(mode="transient") / TimeSeries._fft_transient

Time Series API / TimeSeries

Objective Evidence

Signal Extraction

VIF correction

calculate_correlation_factor()

Spectral API / Spectral Estimation

Objective Evidence

Bootstrap Guide

Forecast timing

ArimaResult.forecast()

Time Series API / TimeSeries

Objective Evidence

Advanced ARIMA

MCMC / GLS likelihood

fit_series() / GeneralizedLeastSquares

Fitting API / gwexpy.fitting

Objective Evidence

Bootstrap Guide

Adaptive whitening

whiten() / WhiteningModel

Preprocessing API

Objective Evidence

ML Preprocessing Case Study

How to Read This Page#

Detailed Algorithm Basis and Assumptions#

1. k-space Calculation#

Target: gwexpy.fields.ScalarField.fft_space()

Angular wavenumber calculation follows the standard physics definition \(k = 2\pi / \lambda\).

Assumptions:

  • Spatial coordinates (\(x, y\)) must be Uniformly Spaced.

  • For non-uniform grids, a correct wavenumber axis cannot be obtained without prior interpolation.

Source reference: S1

Related tutorial

Related API

Related theory

2. Transient FFT (Amplitude Spectrum)#

Target: TimeSeries._fft_transient

Uses an amplitude-preserving convention rather than density, allowing direct reading of time-domain peak amplitudes.

Assumptions:

  • No window function is applied to the input signal (assumes Rectangular window).

  • For data with windows already applied, separate correction for coherent gain is required.

Source reference: S5

Related tutorial

Related API

Related theory

3. VIF (Variance Inflation Factor)#

Target: gwexpy.spectral.estimation.calculate_correlation_factor()

Corrects for the reduction in effective sample size caused by overlapping segments in spectral estimation methods like Welch’s.

Here, VIF is not meant as the regression-style Variance Inflation Factor used in multicollinearity diagnostics. In the codebase it is exposed as calculate_correlation_factor() because the API is describing the concrete operation: computing the overlap-induced correlation correction factor.

Assumptions:

  • The data must be Weakly Stationary.

  • VIF may under- or over-estimate variance if non-stationary glitches or step responses are present.

Source reference: S2

Related tutorial

Related API

Related theory

4. Forecast Timestamp (ARIMA)#

Target: gwexpy.timeseries.arima.ArimaResult.forecast()

Maintains GPS continuity according to LIGO conventions for future timestamp prediction.

A representative update rule is forecast_t0 = t0 + n_obs * dt, where

  • t0: start GPS time of the original series

  • n_obs: number of observed samples used for the fit

  • dt: sampling interval in seconds

This is the quantity mapping assumed when forecast timestamps are extended forward.

Assumptions:

  • The time system must be GPS Time (no leap seconds).

  • Using this in time systems with leap seconds (like UTC) will result in a 1-second offset in future predictions.

Source reference: S3

Related tutorial

Related API

Related theory

5. MCMC / GLS Likelihood#

Target: run_mcmc, GLS

For complex-valued residuals, the MCMC likelihood path assumes a Hermitian quadratic form r.conj() @ cov_inv @ r and then takes the real part. In practice, this means the API can accept complex residual vectors without silently dropping the imaginary component.

Assumptions:

  • cov_inv should be close to Hermitian positive-definite.

  • The implementation is intended for a circular-complex-Gaussian-style treatment of residuals rather than a naive “real-part only” model.

Source reference: S5

Related tutorial

Related API

Related theory

6. Adaptive Whitening#

Target: TimeSeriesMatrix.whiten_channels(eps="auto"), whiten_matrix(), gwexpy.signal.preprocessing.whiten(), WhiteningModel

Adaptive whitening uses an automatically chosen stabilization parameter so that PSD-based normalization remains well behaved in the presence of very small bins or local numerical underflow.

Assumptions:

  • The data are treated as locally quasi-stationary over the FFT segments used for whitening.

  • The adaptive eps path is intended to stabilize small denominators, not to compensate for a badly chosen whitening window or clearly non-stationary bursts.

Source reference: S4

Related tutorial

Related API

Related theory

Audit Trail#

The public audit trail is summarized on this page so readers do not need to follow developer-only or historical review artifacts. The validation summary table above records the reviewed algorithm families, while each per-algorithm section records the public-facing assumptions, implementation status, and related theory links.

Next to Read#