LALInference

Nov 25, 2017
4 minutes

What is LALInference?

LALInference is a Monte Carlo sampler specifically designed for performing parameter estimation on merging compact binaries 1. LALInference implements both nested sampling and Markov Chain Monte Carlo.

How can I use it?

Update 11/09/2021

There are great instructions for the default IGWN (international gravitational-wave observatory network) environments here. Additionally, lalinference is available through conda-forge

$ conda install -c conda-forge lalsuite

and there are instructions to compile from source on git.

Source an existing build

If you have no desire to modify the code and just want a stable installation, the fastest way to get going with LALInference is to source the official O2 build:

$ ~cbc/pe/lalinference_o2.sh

Note, this is only possible on LIGO clusters where such an installation exists.

Build your own

Alternatively, if you want to install your own version, the simplest way is to run this bash script (taken from Carl-Johan Haster):

$ install_lalinference_cbc_master_icc_new.sh

This will install LALSuite using JHBuild. You can then source this build by running:

$ ~/pe/master_new/lalinference_master_new.sh

Additional files

Configuration file

Injection file

  • If you want to inject a set of simulated binaries an injection file is required, e.g., injections.xml.
  • In order to use one of these files it is necessary to uncomment the injection-file option in your config.ini and point to your injection file.
  • These files are not human readable and contain ligolw tables.
  • A nice introduction into how to manipulate these tables using is here.
  • You can also edit these using glue.
  • The parameter names in here are not immediately obvious, a handy guide can be found here.

Run LALInference on your injections

  • Source your LALSuite installation using one of the commands above.
  • Run this command:
$ lalinference_pipe -r /RUN/DIR -p /usr1/albert.einstein/ -I /PATH/TO/injections.xml /PATH/TO/config.ini
  • After running this command you should find the files for running LALInference and then post-processing to produce posterior samples.
$ condor_submit_dag /RUN/DIR/multidag.dag

While LALinference is running you can poke around in /RUN/DIR. The convergence of the run can be tracked in .../log/.

Is it nearly done yet?

Progress Tracking

Nested sampling has a well defined termination criterion based on an estimate of the maximum error on the calculated evidence, dZ. We can use this termination criterion to get a qualitative estimate of how close a lalinference_nest job is to finishing. The default stopping criterion is dZ=0.1. At every iteration lalinference_nest writes various bits of information to a .err file, an example is shown below.

$ tail -n1 log/lalinference-47175999-0-.err
24398: accpt: 0.301 Nmcmc: 5000 sub_accpt: 0.252 slpy: 79.9% H: 14.09 nats logL:-7976.154 ->-7976.142 logZ: -7995.688 deltalogLmax: 26.66 dZ: 0.100 Zratio: 5.090

The three most immediately interesting of these are:

  • deltalogLmax - this can be considered as a proxy for the signal to noise ratio, deltalogL ~ SNR2 / 2.
  • dZ - see above.
  • Zratio - this is the log Bayes factor comparing the signal hypothesis to the noise hypothesis.

We can identify that this run has completed (dZ=0.1) and has a maximum SNR ~ 7 and it is e5 times more likely to contain a signal than it is to be a realisation of Gaussian noise. If you have many simulataneous lalinference_nest jobs going simultaneously inspecting each of the files individually is not practical. I wrote a script that summarises the current dZ for all lalinference jobs in a directory.

$ trackLAL.py /home/colm.talbot/TBS/injections/correct_5Gpc
/home/colm.talbot/TBS/injections/correct_5Gpc/lalinferencenest/IMRPhenomPv2pseudoFourPN/4s
1500 log files found.
1489 finished (dZ = 0.1).
2 nearly finished (0.1 < dZ < 1.0).
8 less nearly finished (1.0 < dZ < 10.0).
1 not nearly finished (dZ > 10.0), maximum dZ = 13.111.
-----------------------------------------------
293 posterior files generated.

This should only be taken as a very loose measure of how the jobs are progressing. The evolution of dZ is nonlinear and nonmontonic.

What does it give me?

Posterior Samples

The main output of Monte Carlo samplers is a set of samples from the prior space of the parameters. These are contained in a file called posterior_samples.dat. These files are not human readable, however, they can be converted into n-d posterior distributions by taking a n-d histogram. Fortunately, the default post-processing generates an accompanying webpage, posplots.html. Additionally, one can also access the hdf5 file generated by LALinference, this can be found in the posterior_samples directory. An example of how to read these files and perform some simple operations is displayed in this ipython notebook.

These instructions have been compiled predominantly from these two pages which provide far more detailed information.

Older -
Newer Constrained Priors in Bilby