Tutorials

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
===== Installation of the Bilby Framework=====
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 [[https://engineeringfordatascience.com/posts/install_miniconda_from_the_command_line/|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

==== Basic Packages ====
It will save you a great amount of pain to use a dedicated python [[https://docs.conda.io/projects/conda/en/latest/user-guide/concepts/environments.html|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 [[https://docs.conda.io/projects/conda/en/latest/user-guide/concepts/channels.html#what-is-a-conda-channel|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%%''.

==== The Bilby Family ====
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

====EoS Patches====
Patches to handle EoS are available in {{:patches.zip|this zip-file}}.
Copy it to the same directory as the bilby-family, using e.g. the ''scp''-[[https://linuxhandbook.com/scp-command/|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 %%:)%%

===Trouble Shooting===
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 [[https://www.atlassian.com/git/tutorials/using-branches/git-checkout|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.
Page Tools
