buoy

buoy deploys trained Aframe and AMPLFI models on gravitational wave events, producing detection statistics and parameter estimation outputs.

• Aframe is a neural network that scans strain data and assigns a detection statistic at each time step. buoy runs it over a segment of data surrounding an event and reports the integrated detection statistic alongside the raw network output.
• AMPLFI is a normalizing flow that performs rapid Bayesian parameter estimation. Given a coalescence time (inferred from Aframe or provided directly), it generates posterior samples for intrinsic and extrinsic parameters and produces a sky localization map.

Model weights (~320 MB total) are downloaded automatically from HuggingFace on first use and cached locally.

Documentation: https://ml4gw.github.io/buoy/

Installation

pip install ml4gw-buoy

A virtual environment is recommended:

conda create -n buoy python=3.11
conda activate buoy
pip install ml4gw-buoy

Analyzing unreleased data

Open data (O1–O4a) is fetched automatically. For events from data not yet publicly released, frame-discovery dependencies are required. A pre-built container with those dependencies is available:

apptainer pull buoy.sif docker://ghcr.io/ml4gw/buoy/buoy:latest

Supported event types

When using a GPS time, buoy defaults to fetching data for H1, L1, and V1. Use --ifos to restrict the detector set.

Usage

Exactly one event source must be supplied: explicit event name(s) via --events, an observing run via --observing_runs, or a GPS window via --gps_start/--gps_end.

Single event

buoy --events GW150914 --outdir ./results

Multiple events

buoy --events '["GW190521", "GW190828_063405", "S200213t"]' --outdir ./results

All public events from an observing run

buoy --observing_runs '["O3a"]' --outdir ./results

All public events in a GPS time window

buoy --gps_start 1126051217 --gps_end 1137254417 --outdir ./results

GPS time event

buoy --events 1187008882.4 --outdir ./results --ifos '["H1", "L1"]'

Parallel processing

Use --max_workers to process multiple events concurrently. Data fetching for the next event overlaps with model inference for the current one:

buoy --observing_runs '["O3a"]' --outdir ./results --max_workers 4

Config file

All arguments can be stored in a YAML config file:

# config.yaml
events:
  - GW190521
  - GW190814
outdir: ./results
samples_per_event: 10000
device: cuda

buoy --config config.yaml

Output structure

<outdir>/
└── <event>/
    ├── data/
    │   ├── <event>.hdf5          # Raw strain data
    │   ├── aframe_outputs.hdf5     # Aframe times, detection statistics, integrated outputs
    │   ├── posterior_samples.dat # AMPLFI posterior samples
    │   ├── whitened_data.npy     # Whitened strain used for plotting
    │   └── amplfi_<HL|HLV>.fits  # Skymap in FITS format
    └── plots/
        ├── aframe_response.png   # Detection statistic vs. time with whitened strain
        ├── H1_qtransform.png     # Q-transform for H1
        ├── L1_qtransform.png     # Q-transform for L1
        ├── skymap_<HL|HLV>.png   # Mollweide sky localization map
        └── corner_plot_<HL|HLV>.png  # Corner plot of posterior samples

CLI reference

Default corner plot parameters: chirp_mass, mass_ratio, distance, mass_1, mass_2.