Aframe

Detecting compact binary mergers from gravitational wave strain data using neural networks, with an emphasis on

• Efficiency - making effective use of accelerated hardware like GPUs in order to minimize time-to-solution
• Scale - validating hypotheses on large volumes of data to obtain high-confidence estimates of model performance
• Flexibility - modularizing functionality to expose various levels of abstraction and make implementing new ideas simple
• Physics first - taking advantage of the rich priors available in GW physics to build robust models and evaluate them accoring to meaningful metrics
• Multi-messenger astronomy - making algorithmic decisions and optimizations that allow for extremely low-latency alerts

For algorithm details and performance estimates on the LVK O3 observing run, please see "A machine-learning pipeline for real-time detection of gravitational waves from compact binary coalescences". Please also cite this paper if you use Aframe software in your work.

Getting Started

Note: this repository is a WIP. Please open up an issue if you encounter bugs, quirks, or any undesired behavior

Note: Running Aframe out-of-the-box requires access to an enterprise-grade GPU(s) (e.g. P100, V100, T4, A[30,40,100], etc.). There are several nodes on the LIGO Data Grid which meet these requirements.

Please see the ml4gw quickstart for help on setting up your environment on the LIGO Data Grid (LDG) and for configuring access to Weights and Biases, and the Nautilus hypercluster. This quickstart includes a Makefile and instructions for setting up all of the necessary software, environment variables, and credentials required to run Aframe.

Once setup, create a fork of this repository, and clone it.

Note: Ensure that you have added a github ssh key to your account

git clone git@github.com:albert-einstein/aframev2.git

Export the AFRAME_REPO environment variable in your ~/.bash_profile to point to the location where you cloned the repository. Be sure to also source ~/.bash_profile.

Aframe utilizes git submodules. Make sure to initialize and update those

git submodule update --init

When pulling changes from this repository, it's recommended to use the --recurse-submodules flag to pull any updates from the submodules as well.

Next, in the root of the repository, install the base aframe poetry environment.

poetry install

This environment is used to launch luigi/law tasks and pipelines (See this README for more information), and also contains other helpful command line utilities for building project container images, and initializing directories with configuration files for various analyses.

Set the AFRAME_CONTAINER_ROOT environment variable where the image files will be stored. We recommend something like ~/aframe/images.

echo export AFRAME_CONTAINER_ROOT=~/aframe/images/ >> ~/.bash_profile
mkdir -p $AFRAME_CONTAINER_ROOT

Aframe uses Condor for parallelizing tasks across the LDG cluster. Set the LIGO_USERNAME and LIGO_GROUP environment variables for use with Condor

echo export LIGO_USERNAME=<your albert.einstein username> >> ~/.bash_profile
echo export LIGO_GROUP=ligo.dev.o4.cbc.allsky.aframe >> ~/.bash_profile

You can now build each of the project apptainer container images. This might take ~ 10 minutes, so grab a coffee!

poetry run build-containers 

These images are containerized environments for running Aframe tasks in isolation, and thus are necessary to build. For more information on what is happening under the hood, please see the projects README. Once complete, you are all setup!

The default Aframe experiment is the sandbox pipeline found under aframe/pipelines/sandbox. You can intialize a run directory with default configuration files using the aframe-init command line utility

poetry run aframe-init sandbox --directory ~/aframe/runs/my-first-run/

This will create configuration files and a bash executable to launch the pipeline. Feel free to edit the configuration files! Launch the pipeline via

bash ~/aframe/runs/my-first-run/run.sh

Please see the instructions in the sandbox README for more details.

Repository structure

The code here is structured like a monorepo, with applications siloed off into isolated environments to keep dependencies lightweight, but built on top of a shared set of libraries to keep the code modular and consistent. Briefly, the repository consists of three main sub-directories:

1. projects - containerized sub-tasks of aframe analysis that each produce artifacts
2. libs - general-purpose functions (libraries) mean to support more than one project
3. aframe - law wrappers for building complex pipelines of project tasks.

For more details, please see the respective README's.

Contributing

If you are looking to contribute to Aframe, please see our contribution guidelines