Sampling

Given a Likelihood and Priors, we run parameter estimation using the run_sampler function. This is the core interface which you should use to setup a sampler and switch between different samplers easily.

This can be accessed via bilby.run_sampler or bilby.core.sampler.run_sampler.

Switching between samplers

bilby can use a large number (and growing) of off-the-shelf samplers. Given your likelihood and prior, it is trivial to switch between samplers by changing the argument sampler given to run_sampler.

Note

By default, only the dynesty sampler is a requirement when installing bilby; therefore, other samplers may not be installed on your system. You can try to use them, if they aren’t installed a help message will print out. See installing samplers for help with installation.

Different samplers take different arguments to control their behaviour. To handle this, we allow the user to pass arbitrary keyword arguments into run_sampler. To document what keyword arguments are available, below we give the API for each sampler. In each of these, there is an “Other Parameters” section which contains information on all the available keyword arguments that sampler takes. For example, to use the dynesty sampler with 250 live points, you would use

>>> bilby.core.run_sampler(likelihood, priors, sampler='dynesty', nlive=250)

Note

For some parameters, we map a variety of similar arguments together. E.g., nlive=250 is equivalent to npoints. The full list of these is given in the API information below.

Below, we give the detailed API for the samplers. Remember, this API is not recommended for direct use by the user, rather it should be accessed via the run_sampler.

Nested Samplers

  • Dynesty: bilby.core.sampler.dynesty.Dynesty

  • Nestle bilby.core.sampler.nestle.Nestle

  • CPNest bilby.core.sampler.cpnest.Cpnest

  • PyMultiNest bilby.core.sampler.pymultinest.Pymultinest

  • PyPolyChord bilby.core.sampler.polychord.PyPolyChord

  • UltraNest bilby.core.sampler.ultranest.Ultranest

  • DNest4 bilby.core.sampler.dnest4.DNest4

  • Nessai bilby.core.sampler.nessai.Nessai

MCMC samplers

  • bilby-mcmc bilby.bilby_mcmc.sampler.Bilby_MCMC

  • emcee bilby.core.sampler.emcee.Emcee

  • ptemcee bilby.core.sampler.ptemcee.Ptemcee

  • pymc bilby.core.sampler.pymc.Pymc

  • zeus bilby.core.sampler.zeus.Zeus

Listing available samplers

A list of available samplers can be produced using bilby.core.sampler.get_implemented_samplers(). This will list native bilby samplers and any samplers available via a plugin. If a plugin provides a sampler that is also implemented in bilby, the bilby implementation will be labeled with the prfix bilby. to distinguish it from the plugin version. See `sampler plugins`_ for more details.

Installing samplers

pip-installable samplers

Most samplers can be installed using pip (see exceptions below). E.g., to install the emcee

$ pip install emcee

If you installed bilby from source, then all the samplers can be installed using

$ pip install -r sampler_requirements.txt

where the file sampler_requirements.txt can be found in the at the top-level of the repository (Note: if you installed from pip, you can simply download that file and use the command above).

Installing PyPolyChord

If you want to use the PyPolyChord sampler, you first need the PolyChord library to be installed to work properly. An image of PolyChord can be found on github. Clone the following repository onto your system. Navigate to the folder you want to install PolyChord in and run:

$ git clone https://github.com/PolyChord/PolyChordLite.git

Then navigate into the PolyChord directory and install PolyChord/PyPolyChord with

$ make pypolychord MPI=
$ python setup.py install --user

Add a number after MPI= to compile with MPI. Leave it like it is if you don’t wish to compile with MPI.

Installing pymultinest

If you want to use the pymultinest sampler, you first need the MultiNest library to be installed to work properly. The full instructions can be found here: https://johannesbuchner.github.io/PyMultiNest/install.html. Here is a shortened version:

First, install the dependencies (for Ubuntu/Linux):

$ sudo apt-get install python-{scipy,numpy,matplotlib,progressbar} ipython libblas{3,-dev} liblapack{3,-dev} libatlas{3-base,-dev} cmake build-essential git gfortran

For Mac, the advice in the instructions are “If you google for “MultiNest Mac OSX” or “PyMultiNest Mac OSX” you will find installation instructions”.

The following will place a directory MultiNest in your $HOME directory, if you want to place it somewhere, adjust the instructions as such.

$ git clone https://github.com/JohannesBuchner/MultiNest $HOME
$ cd $HOME/MultiNest/build
$ cmake ..
$ make

Finally, add the libraries to you path. Add this to the .bashrc file ( replacing the path where appropriate)

$ export LD_LIBRARY_PATH=$HOME/MultiNest/lib:

(you’ll need to re-source your .bashrc after this, i.e. run bash).

Adding new samplers to bilby

We actively encourage the addition of new samplers to bilby. To help enable this, we have base classes which can be subclassed. Below we provide the API for reference, note that the NestedSampler and MCMCSampler inherit from the Sampler class.