# graviflows

`graviflows` provides tools to model and evaluate gravitational-wave detection probabilities with normalizing flows.

## What this package can do

- Build and train normalizing flows for GW parameter distributions.
- Load trained flow checkpoints and evaluate detection probabilities.
- Generate found-event samples via rejection sampling with GWTC4-like proposal distributions.
- Evaluate pdet for batches of events from dictionaries or pandas DataFrames.

## Quick Start: pdet emulator

Small end-to-end example using the pre-trained O4 flow:

```python
import numpy as np
from graviflows.pdet import pdetO4

# 1) Load the pre-trained O4 model.
emulator_path = "models/pdet/PDetO4a/PDetO4a.npz"
pdet_emulator_O4 = pdetO4.PDet_O4.from_saved(emulator_path)

# 2) Prepare source parameters with expected column names.
n = 2
params = {
    "m1_source": np.array([35.0, 20.0]),
    "m2_source": np.array([30.0, 15.0]),
    "redshift": np.array([0.2, 0.1]),
    "a1": np.array([0.2, 0.1]),
    "a2": np.array([0.3, 0.2]),
    "right_ascension": np.array([1.0, 2.0]),
    "sin_declination": np.array([0.1, -0.2]),
    "polarization": np.array([0.5, 0.3]),
    "cos_inclination": np.array([0.4, -0.1]),
    "cos_tilt1": np.array([0.2, -0.3]),
    "cos_tilt2": np.array([0.0, 0.5]),
    "phi1": np.array([1.2, 0.8]),
    "phi2": np.array([2.2, 1.8]),
}

# 3) Evaluate detection probability for each fake event.
p_det = pdet_emulator_O4.pdet(params)
print(p_det)         # shape: (n,)
print(p_det.min(), p_det.max())
```

> [!IMPORTANT]
> The code is compiled on first execution and will therefore seemingly take a long time to compute. Subsequent usage will be much faster.

## Contents

```{toctree}
:maxdepth: 2

usage
api
```