Metadata-Version: 2.5
Name: tdanalysis
Version: 1.0.0
Summary: Time-domain parameter estimation and multi-segment consistency tests for gravitational-wave data
Project-URL: Homepage, https://github.com/vaishakp/tdanalysis
Author: Vaishak Prasad, Viviana Cáceres
Maintainer-email: Vaishak Prasad <vbp5193@psu.edu>
License-Expression: LicenseRef-PolyForm-Noncommercial-1.0.0-with-AI-terms
License-File: LICENSE
License-File: NOTICE.md
Keywords: consistency-test,gravitational-waves,parameter-estimation,time-domain
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.11
Requires-Dist: bilby-pipe
Requires-Dist: bilby<3,>=2.4
Requires-Dist: corner
Requires-Dist: dask
Requires-Dist: dynesty>=2.1
Requires-Dist: gwpy>=3.0
Requires-Dist: h5py
Requires-Dist: lalsuite>=7.20
Requires-Dist: matplotlib>=3.7
Requires-Dist: numba
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: pycbc>=2.3
Requires-Dist: scipy>=1.10
Requires-Dist: spectools
Requires-Dist: statsmodels
Requires-Dist: tqdm
Requires-Dist: waveformtools
Provides-Extra: all
Requires-Dist: nrhjsurrogate; extra == 'all'
Requires-Dist: threadpoolctl; extra == 'all'
Requires-Dist: vlconf; extra == 'all'
Provides-Extra: gpu-legacy
Requires-Dist: torch; extra == 'gpu-legacy'
Provides-Extra: nr
Requires-Dist: nrhjsurrogate; extra == 'nr'
Provides-Extra: pipeline
Requires-Dist: threadpoolctl; extra == 'pipeline'
Requires-Dist: vlconf; extra == 'pipeline'
Description-Content-Type: text/markdown

# 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

```bash
pip install tdanalysis
```

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

Optional extras:

| Extra | Pulls in | For |
|---|---|---|
| `tdanalysis[pipeline]` | `vlconf`, `threadpoolctl` | the `tdanalysis` config-driven CLI |
| `tdanalysis[nr]` | `nrhjsurrogate` | the NRAASur action-angle waveform backend |
| `tdanalysis[gpu-legacy]` | `torch` | non-numba backends of the legacy matrix multiplier |
| `tdanalysis[all]` | the first two | |

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

```bash
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.
