ml4gw-buoy 0.5.0

Deploy Aframe and AMPLFI models over open data

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.

---

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

Format	Example	Source
GWTC catalog event	GW150914	GWOSC
GraceDB event	G363842	GraceDB (requires LIGO credentials)
GraceDB superevent	S200213t	GraceDB (requires LIGO credentials)
GPS time	1187008882.4	User-supplied

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

---

Usage

Single event

buoy --events GW150914 --outdir ./results

Multiple events

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

GPS time event

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

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

Argument	Default	Description
--events	(required)	Event name(s) or GPS time(s) to analyze
--outdir	(required)	Directory to write results
--samples_per_event	20000	Number of AMPLFI posterior samples
--nside	64	HEALPix resolution for the skymap
--min_samples_per_pix	5	Minimum samples per pixel for distance ansatz
--use_distance	true	Include distance in the 3D skymap
--aframe_weights	HuggingFace	Path to Aframe TorchScript weights (.pt)
--amplfi_hl_weights	HuggingFace	Path to AMPLFI HL checkpoint (.ckpt)
--amplfi_hlv_weights	HuggingFace	Path to AMPLFI HLV checkpoint (.ckpt)
--aframe_config	HuggingFace	Path to config of Aframe model config (.yaml)
--amplfi_hl_config	HuggingFace	Path to config of AMPLFI HL model config (.yaml)
--amplfi_hlv_config	HuggingFace	Path to config of AMPLFI HLV model config (.yaml)
--aframe_revision	default branch	HuggingFace revision for Aframe weights
--amplfi_revision	default branch	HuggingFace revision for AMPLFI weights
--use_true_tc_for_amplfi	false	Use catalog/GraceDB time instead of Aframe-inferred time
--ifos	["H1","L1","V1"]	Detectors to use for GPS time events
--device	auto	cpu or cuda
--seed	None	Random seed for AMPLFI reproducibility
--verbose	false	Enable DEBUG-level logging
--run_aframe	true	Run Aframe inference; if false, load saved outputs
--run_amplfi	true	Run AMPLFI inference; if false, skip PE
--generate_plots	true	Generate output plots
--force	false	Reprocess events even if outputs already exist
--corner_parameters	see below	Parameters to include in the corner plot
--to_html	false	Generate an HTML summary page
--config	—	Path to a YAML config file

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