Analysing your first gravitational wave candidate with asimov

Set Up Your Python Environment

We recommend using conda (a package and environment manager) to isolate your asimov installation. If you don't have conda installed yet, download miniconda (a lightweight version of Anaconda).

Create a new conda environment:

conda create -n gw-analysis python=3.11
conda activate gw-analysis

Install the IGWN Software Stack

The International Gravitational-Wave Network (IGWN) provides a curated conda environment with all the gravitational wave analysis tools pre-configured:

# Add the IGWN conda channel
conda config --add channels conda-forge
conda config --add channels igwn

# Install the IGWN environment
conda install -c conda-forge -c igwn igwn-software

This installs:

• All required gravitational wave analysis tools
• The necessary data analysis libraries
• Git and other utilities

Install Asimov and the Pipeline Plugins

Install asimov itself, plus the three pipeline plugins this tutorial uses: asimov-gwdata (fetches strain data), bayeswave (PSD estimation), and bilby (parameter estimation).

# Via pip
pip install asimov asimov-gwdata bilby_pipe bilby

# Or via conda
conda install -c conda-forge bilby bayeswave asimov-gwdata

The bayeswave package is currently only available via conda-forge.

Configure Git

Asimov uses git to track your project. Configure it globally if you haven't already:

git config --global user.email "you@example.com"
git config --global user.name "Your Name"

Replace the email and name with your own values.

Check Your HTCondor Installation

This tutorial assumes HTCondor (a job scheduler) is already installed and running on your system. Test it:

which condor_q
condor_q

Verify Your Complete Setup

Make sure everything is installed correctly:

asimov --version

You should see asimov's version number printed (0.7.1 or later).

Create Project Directory

First, create a directory for your project, move into it, and initialize an asimov project:

mkdir gw150914-tutorial
cd gw150914-tutorial
asimov init "GW150914 Analysis Tutorial"

This sets up the project's directory structure and a blank, git-tracked ledger.

Apply the Project-Wide Defaults

Asimov ships pipelines with a minimal set of default settings. A blueprint with the settings normally used for LVK production analyses is maintained in the asimov data repository—apply the resource-allocation defaults and the prior defaults:

asimov apply -f https://git.ligo.org/asimov/data/-/raw/main/defaults/production-pe.yaml
asimov apply -f https://git.ligo.org/asimov/data/-/raw/main/defaults/production-pe-priors.yaml

Add the Event

Add GW150914 to the project by applying its event blueprint, which is also maintained in the data repository:

asimov apply -f https://git.ligo.org/asimov/data/-/raw/main/events/gwtc-2-1/GW150914_095045.yaml

Define the Workflow

The standard workflow for a gravitational-wave analysis has three stages: fetch data (gwdata), estimate the noise PSD (bayeswave), then run parameter estimation (bilby), with each stage declaring the previous one as a dependency via needs. Save the following as workflow.yaml:

kind: analysis
name: get-data
pipeline: gwdata
file length: 4096
download:
  - frames
scheduler:
  accounting group: ligo.dev.o4.cbc.pe.bilby
  request memory: 1024
  request post memory: 16384
---
kind: analysis
name: generate-psd
pipeline: bayeswave
comment: Bayeswave on-source PSD estimation process
needs:
  - get-data
---
kind: analysis
name: bilby-IMRPhenomXPHM-cosmo
pipeline: bilby
waveform:
  approximant: IMRPhenomXPHM
comment: PE job using IMRPhenomXPHM and bilby
needs:
  - generate-psd

Then apply the workflow to the event you added above, using its full name:

asimov apply -f workflow.yaml -e GW150914_095045

Review Your Project Layout

Your new project has a carefully organized structure:

gw150914-tutorial/
├── .asimov/                    # Asimov's internal directory
│   └── ledger.yml             # The project database (git-tracked)
├── checkouts/                  # Working directories for each analysis
│   └── GW150914_095045/       # Event directory
│       ├── get-data/          # gwdata download job
│       ├── generate-psd/      # Bayeswave on-source PSD job
│       └── bilby-IMRPhenomXPHM-cosmo/  # Bilby parameter estimation job
├── results/                    # Where results will be stored
├── working/                    # HTCondor job submission files
└── README.md                   # Project information

Check Your Analysis Status

To see the current status of your analyses, run:

asimov report status

You should see something like:

GW150914_095045
  Analyses
  - get-data[gwdata]                      ready
  - generate-psd[bayeswave]               waiting (needs get-data)
  - bilby-IMRPhenomXPHM-cosmo[bilby]      waiting (needs generate-psd)

Build Configuration Files

Asimov works out which stages of the workflow are ready to run and produces the configuration needed to submit them to the scheduler. Since only get-data has no unmet dependencies, this is the stage that gets built first:

asimov manage build

Submit Jobs to the Scheduler

Now submit the first analysis to HTCondor:

asimov manage submit

One-time Status Check

For a quick status check:

asimov monitor

This checks the job status once and shows you what's happening, similar to asimov report status.

Continuous Monitoring (Recommended)

You probably don't want to check on these jobs by hand. Asimov can automate the process instead: checking the status of each analysis, and building and submitting the next stage automatically once its dependencies complete.

asimov start

This starts a background monitoring process, and stops once everything is done, or you can stop it yourself with:

asimov stop

Automatic Post-Processing

Asimov automatically:

• Runs post-processing with PESummary to generate summary statistics and plots
• Moves results to the results/ directory
• Generates comprehensive HTML reports with visualization of the posterior distributions
• Marks analyses as complete

Examine Your Results

You can then examine the results:

ls results/GW150914_095045/

This directory contains all your output files, plots, and reports.

Install Minicondor

HTCondor provides pre-built installers. Visit htcondor.readthedocs.io and follow the installation guide for your operating system.

On Linux (Ubuntu/Debian):

# Add HTCondor repository
wget -qO - https://research.cs.wisc.edu/htcondor/yum/HTCondor/repo.key | sudo apt-key add -
echo "deb [arch=amd64] https://research.cs.wisc.edu/htcondor/yum/HTCondor/ubuntu focal main" | \
  sudo tee /etc/apt/sources.list.d/htcondor.list

# Install minicondor
sudo apt-get update
sudo apt-get install minicondor

On macOS:

# Using Homebrew
brew tap htcondor/htcondor
brew install htcondor

For other systems, follow the official installation guide.

Configure Minicondor

After installation, start the HTCondor daemon:

# Start the HTCondor daemon
sudo /etc/init.d/condor start

# Or on systems using systemd
sudo systemctl start condor

For personal workstations, limit resource usage by editing /etc/condor/condor_config.d/personal.conf:

NUM_SLOTS = 1
NUM_SLOTS_TYPE_1 = 1

This ensures only one job runs at a time on your machine.

Verify Installation

Test that HTCondor is working:

condor_q          # List jobs (should be empty)
condor_status     # Show available slots

Now you can follow the main tutorial above!