Tutorials

All of the following explanations expect that you use a linux command line. Whenever some names are subject to your choice, they are marked as [CHOICE]. If you encounter trouble, consider the remarks at the end of the page.

You usually employ parallel bilby on a computer cluster. This should have python and miniconda available. You might need to activate these, though, typing:

module load python

Later analysis steps might and should be performed on some local device, though. If miniconda is not yet installed there, you can get it the usual way. In any way, make sure it is updated to the most recent version by typing

conda update -n base -c defaults conda

It will save you a great amount of pain to use a dedicated python environment for your work with bilby. Create it with

conda create -n [YOUR_PBILBY_ENVIRONMENT] python=3.7

and hit y when asked if you want to proceed. Then activate it by typing

conda activate [YOUR_PBILBY_ENVIRONMENT]

Python packages are distributed through sometimes conflicting channels. To avoid conflicts, we make sure to use the very common channel conda-forge:

conda config --add channels conda-forge
conda config --set channel_priority strict

Then execute the following commands to install packages that the bilby-family requires:

conda install mpi4py
conda install ipython
conda install numpy
conda install scipy
conda install matplotlib

Whenever asked for confirmation to proceed, hit y.

If you want to work with the bilby family in its most recent version, simply use again

conda install bilby
conda install bilby_pipe
conda install parallel_bilby

parallel_bilby uses bilby_pipe to interact efficiently with bilby and your computer.

If however, you want to include the possibility to sample over Equations of State, you need to install from source as this allows us to include dedicated patches (see below). To do so, (make and) go to a convenient destination directory (cd [YOUR_DESTINATION]) and download the respective package:

git clone https://git.ligo.org/lscsoft/bilby.git
git clone https://git.ligo.org/lscsoft/bilby_pipe.git
git clone https://git.ligo.org/lscsoft/parallel_bilby.git

Patches to handle EoS are available in this zip-file. Copy it to the same directory as the bilby-family, using e.g. the scp-command, and hit unzip patches.zip. Allocate and apply the patches using these commands:

cd bilby
git apply ../patches/bilby/* 
pip install -r requirements.txt
pip install .
cd ../bilby_pipe
git apply ../patches/pipe/* 
pip install .
cd ../parallel_bilby
git apply ../patches/pbilby/
pip install .

Your computer should now be ready to handle Bayesian Inference problems in a gravitational wave context. Let us now get you prepared as well :)

It can happen that for some of the bilby-packages, pip install . raises an error, similar to this:

  ERROR: Failed building wheel for lscsoft-glue
Successfully built bilby-pipe
Failed to build ligo-segments python-ligo-lw lscsoft-glue

Note that it still claims bilby-pipe to be successfully built. This seems to be especially frequent when using Virtual Machines or Ubuntu for Windows. A possible solution is this:

sudo apt-get update
sudo apt-get install gcc

Then try again pip install .. You may also need to update pip by running pip install -U pip (with a capital U).

Essentially, pip install . is a convenient way to check dependencies and then execute the file setup.py in your current directory. This file specifies the routines to be installed. The patches now serve to change some of the files setup.py refers to before installation. As a basic sanity check, the patches contain some lines of the original code at time of writing to investigate whether the insertions will happen at the expexted lines. As all of the bilby family is still under development, there is a good chance this reference content is not matched and git apply will return

error:[file]: patch does not apply

You have two options two fix this: A) Ressort to that version for which the patches were written. This can be done by creating new branches of the code. To do so, execute:

cd  [YOUR_DESTINATION]/bilby
git checkout -b branch_1.2.1 1.2.1

cd  [YOUR_DESTINATION]/bilby_pipe
git checkout -b branch_1.0.7 1.0.7

cd  [YOUR_DESTINATION]/parallel_bilby
git checkout -b branch_1.1.0 1.1.0

You can then apply the patches as described above.

B) Fix the fix. If you feel comfortable doing so, you might also fix the patches. This will generally be advantageous as newer programme versions tend to be more efficient, but the patches might also cause some fringe behaviour. For safety, you might want to first do A in a dedicated conda environment. The patch files look something like this:

diff --git a/parallel_bilby/analysis.py b/parallel_bilby/analysis.py
[...]
--- a/parallel_bilby/analysis.py
+++ b/parallel_bilby/analysis.py
@@ -684,4 +686,6 @@ with MPIPool(
 
+        logger.info(f"Saving posterior samples to {outdir}/{label}_posterior_samples.dat")
+        result.save_posterior_samples()
         logger.info(f"Saving result to {outdir}/{label}_result.json")
         result.save_to_file(extension="json")
         print(f"Sampling time = {datetime.timedelta(seconds=result.sampling_time)}s")

Read this as: The content of file a in the 4 lines starting at line 684 and file b in the 6lines starting at line 686 should be

• exlusive to file b if the line begins with a +
• exclusive to file a if the line begins with a -
• shared if the line begins with a blank.

Since file a and b are identical, this will effectively result in the addition of the two lines indicated by the '+'. Because the omitted code section had already added two more lines, the linecount for b starts at 686, not 684. So probably all you need to do is to identify where in the updated version of the respective files a and b the insertions have to be made and change the corresponding start lines. The addition of with MPIPool( indicates the general context (in many other cases the superior function) in which the respective lines of code were called. As mentioned, though, this is subject to the extend of changes that have been made to the packages. If you find that this context is no longer present or that the patch causes other errors, you might prefer to ressort to option A.