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.
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 offline --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.
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:
- projects - containerized sub-tasks of aframe analysis that each produce artifacts
- libs - general-purpose functions (libraries) mean to support more than one project
- aframe -
law
wrappers for building complex pipelines of project tasks.
For more details, please see the respective README's.
If you are looking to contribute to Aframe
, please see our contribution guidelines