This repository is a companion to Wagg et al. (2021), a paper investigating the Galactic population of LISA detectable BH and NS binaries. We discuss the expected detection rate, variations when using different underlying binary physics assumptions, prospects for identifying the sources of signals and matching them to electromagnetic counterparts.
This repository contains all of the code associated with with Wagg et al. (2021), both for the simulations so that you can reproduce the results, but also for the paper so that you can reproduce all of the plots. If you've come this far without reading the paper yet, I recommend that you go and take a look before trying to see what's going on in the code so it makes more sense.
If you have any questions about how to use any part of this repository please reach out via email at tomjwagg@gmail.com!
If you use any figures, code or results from this paper we ask that you please cite Wagg et al. (2021). For convenience, here is link to the ArXiv and ADS. Additionally, here is the bibtex entry:
@ARTICLE{Wagg+2021,
author = {{Wagg}, Tom and {Broekgaarden}, Floor S. and {de Mink}, Selma E. and {van Son}, Lieke A.~C. and {Frankel}, Neige and et al.},
title = "{Gravitational wave sources in our Galactic backyard: Predictions for BHBH, BHNS and NSNS binaries detectable with LISA}",
journal = {arXiv e-prints},
keywords = {Astrophysics - High Energy Astrophysical Phenomena},
year = 2021,
month = nov,
eid = {arXiv:2111.13704},
pages = {arXiv:2111.13704},
archivePrefix = {arXiv},
eprint = {2111.13704},
primaryClass = {astro-ph.HE},
adsurl = {https://ui.adsabs.harvard.edu/abs/2021arXiv211113704W},
adsnote = {Provided by the SAO/NASA Astrophysics Data System}
}
This code makes heavy use of LEGWORK, a Python package for determining the detectability of stellar-mass LISA sources that I wrote with Katie Breivik. It allows you evolve the orbits of binary sources, measure their strain and SNR as well as visualise the results.
We also use some more well known Python packages and list them below
numpyastropyscipyseabornh5pymatplotlibjupyteripython
You can install these packages using conda and create an environment for working with this code. Run the following to do so
conda create -n LISA_dcos numpy astropy scipy seaborn h5py matplotlib legwork jupyter ipython
conda activate LISA_dcosIf you don't have Anaconda then alternatively you can use pip to install everything by running
pip install numpy astropy scipy seaborn h5py matplotlib legwork jupyter ipythonAll data related to the predictions in the paper is stored here on Zenodo. You'll need to download all of this data for reproducing the figures and be sure to follow the instructions on Zenodo for placing the data in the right place. If you also want to run a new simulation then you'll need the data from Broekgaarden et al. (2021, in prep.) which you can download here, here and here for BHBHs, BHNSs and NSNSs respectively.
This repository is set up so that it is very easy not only to reproduce every result and figure in the paper but also adapt the work for future studies. With this in mind, let's split into two sections depending on whether you just want to visualise the results differently or whether you want to produce new results entirely.
Here's a quick guide on how you can reproduce any figure from the paper, as well as how to adapt those figures for your own use. First, clone the repository to your local machine to access all of the code. Next, for the majority of the figures in the paper you'll need to download the data by following the instructions on Zenodo. Once you've downloaded the data and put it in the right folder (simulation/data), you're ready to start making figures!
You're welcome to peruse the notebooks directly here on GitHub if you want to take a look at everything...but if you're looking for a particular figure then I recommend that you check the caption in the paper. There will be a small book symbol that links directly to the notebook that creates it. For example, let's consider Figure 9 and say you wanted to only include the NSNS panel instead over DCO type. In this case, you need to open this notebook, which is linked in Figure 9's caption, and edit the code to remove the loop over DCO types so that you plot only the NSNSs instead.
In this same way you can pick any figure and follow the link in the caption to find a related notebook that will explain how to make the figure with commented code that you can edit.
Please remember to cite Wagg et al. (2021) should you use any figure/adapted figure in any public setting (papers/talks etc.). Thanks!
Reproducing the results from the paper should be just as easy as reproducing figures and adapting the simulations should also be very possible. Here are the steps you need to go through to run your very own simulation
- Clone the repository to your machine
- Ensure you have the required dependencies installed
- Download the data from both this paper and Broekgaarden et al. (2021)
- (optional) Open
simulation/src/simulate_DCO_detections.pyand make and edits to the simulation that you want to - Run
simulate_DCO_detections.pyto run a simulation! Runpython simulate_DCO_detections.py -hto get usage instructions if you need them.
Let's consider an example just to make sure everything is clear. Let's say that you were interested in how the detectable BHNSs are affected by both reducing the kicks from CCSN and assuming optimistic CE scenario (combining models K and Q) for a 10-year LISA mission. In this case, you could run a new simulation to find out!! In order to just run a single Milky Way instance you would run the following (from the simulation/src directory)
python simulate_DCO_detections.py -i path/to/broekgaarden2021data/ccSNkick_30km_s/COMPASOutputCombined.h5 -o ../output/optimistic_plus_low_kicks.h5 -n 1 -t BHNS --opt-flag --extended-missionIn this line we've done a couple of things with the various command-line options:
- Set the input file to the correct data file from Broekgaarden et al. (2021)
- Set the output file to a sensible name in the output folder
- Only run a single MW instance
- Only run the simulation for BHNSs
- Turned on the optimistic CE flag
- Switched to an extended (10-year) LISA mission
And that is all you need to do to produce a simulation based on your new model!!
Of course, if you wanted to build up a proper statistical sample you'll need much more than a single Milky Way instance. For the paper, we ran 2500 Milky Way instances with 100,000 systems of each DCO type in each. You're welcome to edit the size of the Milky Way also within the simulation but we found that 100,000 provided a good number of detections to keep uncertainties low. You may also find that the simulation/slurm folder is useful for getting some of the setup for running these simulations on a computing cluster.
Want to use our Milky Way model in your work without coding it yourself? You're in luck, the simulate_mw() function in simulation/src/galaxy.py will do exactly this. If you're interested in exploring the galaxy model in more detail I recommend you check out the Galaxy Creation Station.
In case you're interested in using my colour schemes for the physics variations or formation channels:
- The colours used for each physics variation (as well as labels/descriptions) are contained in simulation/src/variations.py
- The colours for the formation channels are defined in the formation channels notebook which can be found in paper/figure_notebooks/formation_channels.ipynb
Not sure where to look? This map should help point you to the right folder!
detecting-DCOs-with-LISA
│
└── paper
│ │ This folder contains everything to do with the paper
│ │
│ │ `previous_BH_NS_studies.xlsx` has the comparison of previous studies with ours
│ └─── figure_notebooks
│ | | Jupyter notebooks that reproduce every figure in the paper
│ │
│ └─── figures
│ │ │ A collection of every figure used in the paper
│ │ └─── extra_figures
│ │ │ Some figures that didn't make it into the paper but that are still interesting!
│ │
│ └─── tex
│ │ All of the LaTeX files for the paper (split up by section)
│
│
└─── simulation
│
└─── data
│ │ This is the folder where most of the code assumes the data from Zenodo is stored
│ │
└─── postprocessing_notebooks
│ │ Jupyter notebooks that transform the direct simulation output into more usable formats
│ │
└─── output
│ │ Where the simulation puts all of its output on completion
│ │
└─── slurm
│ │ SLURM commands for running cluster jobs on the Harvard cluster
│ │
└─── src
│ Main simulation code