tdanalysis

Time-domain parameter estimation for gravitational-wave data, and the inspiral-ringdown consistency test built on it.

The likelihood is -½ δᵀ C⁻¹ δ evaluated on a chosen data segment, where C is a full noise covariance built from a detector autocorrelation function rather than from a diagonal-in-frequency PSD approximation. That is what makes short, gated or gappy segments tractable, which is the regime a ringdown analysis lives in.

This is release v1. It is pure Python, it installs from PyPI with no compiler, and it contains the parameter estimation core and the consistency test. The batched GPU sampling path (v2) and the ringdown spectroscopy likelihoods (v3) are separate, later releases of this same package.

Install

pip install tdanalysis

The wheel is py3-none-any. Python 3.11 or newer.

Optional extras:

Every one of these is imported inside a function at the point it is first needed, so the library imports and runs without any of them.

nrhjsurrogate declares requires-python >= 3.12, so the [nr] extra can only be resolved on 3.12 or newer even though the package itself supports 3.11. On an older interpreter pip fails with that as the reason, which is the intended behaviour: the alternative is a marker that installs nothing and leaves the backend quietly missing.

What is in here

• Parameter estimation. tdanalysis.likelihoods.single.pe.GWTransientTD for one detector, ...likelihoods.multi.pe.GWTransientTDMultiDetector for a coherent network. A bilby Likelihood, so it drops into a bilby sampler run.
• Inspiral-ringdown consistency test. tdanalysis.likelihoods.single.consistency_test.InspiralRingdownConsistencyTD and ...likelihoods.multi.consistency_test.IMRConsistencyMultiDetector, comparing an inspiral-derived and a ringdown-derived remnant, plus tdanalysis.likelihoods.comparison.discriminators.ChiSquaredRingdown.
• Quadratic forms and whiteners. tdanalysis.forms, selected with qform_method: Gohberg-Semencul (gs, O(N log N) via FFT), preconditioned CG (pcg), invLD, Llt and CD. gs_batched is the numpy batched chi-square that reduced_batch drives.
• Covariance and PSD handling. tdanalysis.covariance, including the band patching and taper conditioning the tests cover.
• Next-generation detectors. tdanalysis.detectors.xg: CE40, CE20, the triangular ET (ET1/ET2/ET3) and LIGO-India, with vendored noise curves and conditioned autocorrelations under tdanalysis/data/. Importing tdanalysis.detectors registers them with pycbc. Provenance for every vendored file is in tdanalysis/data/*/PROVENANCE.md.
• Waveform backends. LAL and pycbc approximants, plus the NRAASur action-angle surrogate (tdanalysis.waveforms.nraasur). All wrapped at the generator level, so peak finding, tapers, padding, the segment crop and the projection are the same code for every approximant. That is what makes parameters estimated with different models comparable.
• A CLI. tdanalysis --help, a config-driven run driver.

Not in v1: ringdown spectroscopy likelihoods and Kerr QNM templates (v3), the Kokkos GPU kernels and batched sampling (v2).

Worked example

tests/test_pe_smoke.py is the reference example as well as the release gate. It builds a real GWTransientTD with real LAL waveform generation, real conditioning and projection, and a real Gohberg-Semencul form from a real Cholesky factor, with nothing mocked. It carries no data-file dependency, so it runs anywhere the package installs.

Read it for the constructor arguments in context. The properties it pins are worth knowing about:

• the zero-noise truth is the maximum, and moving off it costs chi-square
• scalar and batched evaluation give the same number, so a posterior does not depend on the batch size
• batching is row-order independent, and a one-row batch matches the scalar call
• the likelihood survives a pickle round trip, which is what lets a bilby multiprocessing pool carry it

Tests

pip install tdanalysis
python -m pytest tests/ -q

Five files ship: the GWTransientTD gate above, plus PSD band patching, taper conditioning, whitening backend agreement and the XG autocorrelations.

Licence

PolyForm Noncommercial License 1.0.0, with two additional terms. See LICENSE for the text and NOTICE.md for what it means in practice, and for the contributors to this release.

This is deliberately not an open-source licence, because it restricts the field of use.

• Noncommercial use is free and needs no permission — research, teaching, and publishing results obtained with it. The licence grants that outright, including where the funding is industrial.
• Commercial use needs a written licence, which may carry a fee or a royalty: vbp5193@psu.edu.
• Training a model on this software is not permitted, commercial or not. Building a surrogate or emulator of the waveforms and posteriors it produces is ordinary research use and is fine; ingesting the source and documentation into a general-purpose code or language model is not.
• AI tools may be used on this software only with training and retention off. AI assistance as such is not prohibited; the configuration that would feed this code into a training corpus is.

Because those additional terms modify PolyForm, the metadata declares LicenseRef-PolyForm-Noncommercial-1.0.0-with-AI-terms rather than the bare PolyForm identifier.