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.

Native Samplers

bilby includes several samplers by default:

• bilby-mcmc bilby.bilby_mcmc.sampler.Bilby_MCMC

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

• emcee bilby.core.sampler.emcee.Emcee

External Samplers

In addition to the samplers listed above, bilby supports a wide range of external samplers provided by various plugins.

If your favourite sampler is missing, please open a PR to add it to the list.

MCMC Samplers

• kombine: https://github.com/bilby-dev/kombine-bilby

• numypyro: https://github.com/ColmTalbot/bilby-numpyro

• PTMCMCSampler: https://github.com/bilby-dev/ptmcmsampler-bilby

• ptemcee: https://github.com/bilby-dev/ptemcee-bilby

• pymc: https://github.com/bilby-dev/pymc-bilby

• zeus: https://github.com/bilby-dev/zeus-bilby

Nested Samplers

• cpnest: https://github.com/bilby-dev/cpnest-bilby

• dnest4: https://github.com/bilby-dev/dnest4-bilby

• nestle: https://github.com/bilby-dev/nestle-bilby

• nessai: https://github.com/bilby-dev/nessai-bilby

• pymultinest: https://github.com/bilby-dev/pymultinest-bilby

• pypolychord: https://github.com/bilby-dev/pypolychord-bilby

• ultranest: https://github.com/bilby-dev/ultranest-bilby

Sequential Monte Carlo Samplers

• aspire: https://github.com/mj-will/aspire-bilby

• pocomc: https://github.com/mj-will/pocomc-bilby

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 prefix bilby. to distinguish it from the plugin version. See `sampler plugins`_ for more details.

Installing samplers

Native samplers are installed by default when installing bilby. External samplers require you to install the corresponding plugin.

Most plugins can be installed from pip or conda. For example:

Conda

Once the plugin is installed, the sampler can be by specfiying, for example, sampler="nestle".

Warning

Some external samplers are only available via conda or directly from source. See the installation instructions in the corresponding sampler plugin for more details.

Adding new samplers to bilby

We actively encourage the addition of new samplers to bilby. We now recommended adding support for new samplers via the sampler plugins interface. For more details, and a template, see `sampler plugins`_.

If you have a bilby sampler plugin that you would like to be listed here, please let us know!

Migrating to sampler plugins

The interface for some samplers are being moved from bilby to external sampler plugins. This does not change how the samplers are used for most users, you still specify sampler='sampler name' in run_sampler, however, an additional dependency must be installed before using a sampler.

Note

Samplers that are scheduled to be moved will print a warning when using them.

For example, the nessai sampler interface has been moved to a plugin. In order for a user to continue using this sampler, they must install the nessai-bilby plugin which is available via PyPI and conda. Once this package is installed, the new interface will automatically be used instead of the native bilby interface.

Warning

Some samplers may require additional installation steps.

For more details about how sampler plugins, including a list of available sampler plugins, see `sampler plugins`_.