Bilby MCMC Guide

Bilby MCMC is a native sampler built directly in bilby and described in Ashton & Talbot (2021). Here, we describe how to use it. For detailed API information see the API section.

Quickstart and output

To use the bilby_mcmc sampler, we call

>>> bilby.run_sampler(likelihood, priors, sampler="bilby_mcmc", nsamples=1000)

This will run the MCMC sampler until 1000 independent samples are drawn from the posterior. As the sampler is running, it will print output like this


From left to right, this gives the number of iterations, the time-elapsed, the number of burn-in iterations, the current estimate of the autocorrelation time (ACT), the current estimate of the number of samples, the overall acceptance fraction, the efficiency, the time per likelihood evaluation, the maximum likelihood seen to far, and the estimated time to finish. Note that the estimates of the time to finish and number of samples are dependent on the ACT. If this increases, the corresponding time to finish will increase. Generally, once the number of independent samples is greater than 50, the ACT is reasonably stable.


We now describe the configuration of the sampler. First, we will present a detailed look at some commonly-used parameters. But, please refer to the full API for an exhaustive list.

Here, we provide a code snippet to run bilby-mcmc with parallel-tempering, and set the thin_by_nact parameter. Note that, because thin_by_nact < 1, this will produce 1000 correlated samples. The number of independent samples is nsamples*thin_by_nact=200 in this case.

>>> bilby.run_sampler(
    nsamples=1000,  # This is the number of raw samples
    thin_by_nact=0.2,  # This sets the thinning factor
    ntemps=8,  # The number of parallel-tempered chains
    npool=1,  # The multiprocessing cores to use
    L1steps=100,  # The number of internal steps to take for each iteration
    proposal_cycle='default',  # Use the standard (non-GW) proposal cycle
    printdt=60,  # Print a progress update every 60s
    check_point_delta_t=1800,  # Checkpoint and create progress plots every 30m


If the ACT of your runs are consistently 1 with the above settings, you may wish to decrease the number of internal steps L1steps. The parameter above has been tuned for typical gravitational-wave problems where the ACT is usually several thousand.


You should choose npool to suit your computer and the number of parallel chains. If you have 8 cores and use 8 temperatures, then npool=8 or npool=4 is recommended. Choosing non-multiple values will reduce the efficiency.

Proposal Cycles: built-in

bilby_mcmc offers a flexible interface to define a proposal cycle. This can be passed in to the sampler via the proposal_cycle keyword argument.

Using the default proposal cycle: If proposal_cycle='default', a default non-gravitational-wave specific proposal cycle will be used which consists of a mixture of the standard, adaptive, and learning proposals. This proposal cycle is general-purpose and can be used on a variety of problems.

To evaluate the effectiveness of proposals, at the checkpoint stage we print a summary of the proposal cycles for the zero-temperature primary sampler. This provides the acceptance ratio for each proposal, the number of times it has been used, and the training status for the learning proposals.

14:14 bilby INFO    : Zero-temperature proposals:
14:14 bilby INFO    : AdaptiveGaussianProposal(acceptance_ratio:0.23,n:7e+04,scale:0.018,)
14:14 bilby INFO    : DifferentialEvolutionProposal(acceptance_ratio:0.21,n:6.6e+04,)
14:14 bilby INFO    : UniformProposal(acceptance_ratio:0,n:2.7e+02,)
14:14 bilby INFO    : KDEProposal(acceptance_ratio:0.42,n:6.9e+04,trained:1,)
14:14 bilby INFO    : GMMProposal(acceptance_ratio:0.73,n:6.9e+04,trained:1,)
14:14 bilby INFO    : NormalizingFlowProposal(acceptance_ratio:0.38,n:6.9e+04,trained:1,)

Using the default gravitational-wave proposal cycle: If you are using bilby_mcmc to analyse a CBC gravitational-wave signal, you can use proposal_cycle='gwA' to select the proposal cycle described in Table 1 of 2106.08730.


You can modify either the 'default' or 'gwA' proposal cycles by removing a particular class of proposals. For example, to remove the Adaptive Gaussian proposals used proposal_cycle='default_noAG'. The two-letter codes follow the conventions established in Ashton & Talbot (2021).


The Normalizing Flow, and Gaussian Mixture Model proposals require additional software to be installed.

To install nflows, run

$ pip install nflows

Note: nflows depends on PyTorch. Please see the documentation for help with installation.

To install sklean used by the Gaussian Mixture Model, see the installation instructions.

If these are not installed, but the proposals are used a warning message is printed and the proposals ignored.

Proposal Cycles: custom

The proposal_cycle can also be provided directly. For example, here we create a list of proposals then use these to initialize a the cycle directly. Note that the prior here is the prior as passed in to run_sampler.

>>> from bilby.bilby_mcmc.proposals import ProposalCycle, AdaptiveGaussianProposal, PriorProposal
>>> proposal_cycle_list = []
>>> proposal_cycle_list.append(AdaptiveGaussianProposal(priors, weight=2))
>>> proposal_cycle_list.append(PriorProposal(priors, weight=1))
>>> proposal_cycle = ProposalCycle(proposal_cycle_list)

New proposals can also be created by subclassing existing proposals.