# Introduction

```{image} Areslog.png
:alt: AresGW logo
:align: center
:width: 60%
```

The ACME AresGW training session was organized by [ACME](https://www.acme-astro.eu/) on March 4, 2026. The speakers were [Alexandra Eleni Koloniari](https://www.linkedin.com/in/alexandra-eleni-koloniari-862705353/) and [Nikolaos Stergioulas](https://niksterg.github.io/niksterg/). The original training material is available in the [AresGW ACME development repository](https://gitlab.com/niksterg/acme-aresgw-dev).

The source repository uses [Git LFS](https://docs.gitlab.com/topics/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:

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

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

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

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

For newer cards such as NVIDIA 5090:

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

Before training, generate waveform arrays for data augmentation:

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

Then train a model with `train.py`:

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

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

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

```bash
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](https://ui.adsabs.harvard.edu/abs/2023PhRvD.108b4022N/abstract) and the original [AresGW code repository](https://github.com/vivinousi/gw-detection-deep-learning).