Introduction

Introduction#

AresGW logo

The ACME AresGW training session was organized by ACME on March 4, 2026. The speakers were Alexandra Eleni Koloniari and Nikolaos Stergioulas. The original training material is available in the AresGW ACME development repository.

The source repository uses Git LFS for data files larger than 100 MB. Enable Git LFS before cloning it if you want to run the data-generation, training, or real-trigger analysis workflows with the full data files.

The notebooks in this section include generated-data inspection, foreground/background trigger inspection, trigger-statistic evaluation, and a real LVK O3a trigger example. Several notebooks expect files produced by the commands below, including data7200/*.hdf, data7200/*.npy, and results/*.hdf.

Generate Training Data#

The source repository includes an introductory notebook on public LIGO-Virgo-KAGRA data, adapted from PyCBC tutorials. To generate training data, create the data-generation environment from the source repository:

conda env create -f environments/generatedata.yml
conda activate generatedata

Then run generate_data.py inside the generatedata directory. The default workflow can download an 82-day O3a noise file of about 90 GB, so the repository also provides a shorter real_noise_file-subset-360000-10h.hdf file and segments.csv for a lighter training-session setup:

cd generatedata

./generate_data.py --output-injection-file injections.hdf \
  --output-foreground-file foreground.hdf \
  --output-background-file background.hdf \
  --real-noise-path real_noise_file-subset-360000-10h.hdf \
  --seed 42 --start-offset 0 --duration 7200 --verbose --force

For separate training, validation, and test sets, use generate_all_sets.py:

python generate_all_sets.py --output-dir data7200 \
  --output-injection-file injections.hdf \
  --output-foreground-file foreground.hdf \
  --output-background-file background.hdf \
  --real-noise-path real_noise_file-subset-360000-10h.hdf \
  --start-offset --seed 42 --duration 7200 --verbose --force

After generating the data products, use the data-inspection notebooks in this section to inspect the real-noise file, injection file, and foreground/background training files.

Train AresGW#

AresGW is written in PyTorch and is intended to run on a GPU. For common NVIDIA GPUs such as 3070 or 4080:

conda env create -f environments/aresgw.yaml
conda activate aresgw

For newer cards such as NVIDIA 5090:

conda env create -f environments/aresgw5090.yaml
conda activate aresgw5090

Before training, generate waveform arrays for data augmentation:

python generate_waveforms_npy.py \
  --hdf-filename generatedata/data7200/background_train.hdf \
  --data-dir generatedata/data7200

Then train a model with train.py:

python3 train.py --data-dir generatedata/data7200 \
  --output-dir runs/new-run --train-device cuda:0 \
  --slice-dur 6.25 --slice-stride 1.4 --learning-rate 0.0045 \
  --lr-milestones 5,10 --gamma 0.5 --epochs 14 \
  --warmup-epochs 2 --p-augment 0.4 --batch-size 32 \
  --snr-schedule 4:12.5-100,2:8.5-100,2:1-8.5,2:1-12.5

The trained model weights are written to the output directory, for example runs/new-run/weights.pt.

Test And Evaluate#

Run the trained model on foreground and background test data:

python3 test.py --weights runs/new-run/weights.pt \
  generatedata/data7200/foreground_test.hdf \
  results/test_fgevents.hdf --test-device cuda:0

python3 test.py --weights runs/new-run/weights.pt \
  generatedata/data7200/background_test.hdf \
  results/test_bgevents.hdf --test-device cuda:0

Evaluate the trigger statistics with evaluate.py:

python evaluate.py \
  --injection-file generatedata/data7200/injections_test.hdf \
  --foreground-files generatedata/data7200/foreground_test.hdf \
  --foreground-events results/test_fgevents.hdf \
  --background-events results/test_bgevents.hdf \
  --output-file results/test_eval_output.hdf \
  --verbose --force

Generate a sensitive-distance plot:

python3 sensitivity_plot.py \
  --files results/test_eval_output.hdf \
  --output results/test_eval_output_plot.png \
  --no-tex --force

The trigger-evaluation notebook in this section follows the same workflow interactively. It expects the results/test_fgevents.hdf, results/test_bgevents.hdf, and results/test_eval_output.hdf products created by the test and evaluation commands above.

Real LVK Data Example#

The notebook in this section analyzes triggers obtained with AresGW model 1 for the second month of the O3a observing period using the L1 and H1 detectors.

Note

The companion trigger file AresGW-model1-O3a-data-m2.hdf is stored with Git LFS in the source repository. If the file appears as a small text pointer rather than an HDF5 file, install Git LFS and fetch the LFS data from the source repository before running the notebook.

Citation#

Results produced with this code can be referred to as AresGW model 1, citing Koloniari et al. 2024 and the original AresGW code repository.

Contents