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
2.18e+04|10:13:34|9.96e+02(AD)|t=56|n=1874|a=0.15|e=1.1e-02%|16.68ms/ev|maxl=71.70|ETF=0:38:52 2.18e+04|10:14:34|9.96e+02(AD)|t=56|n=1877|a=0.15|e=1.1e-02%|16.73ms/ev|maxl=71.70|ETF=0:38:03 2.19e+04|10:15:35|9.96e+02(AD)|t=56|n=1880|a=0.15|e=1.1e-02%|17.94ms/ev|maxl=71.70|ETF=0:39:50
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
parallel-tempering, and set the
thin_by_nact parameter. Note that,
thin_by_nact < 1, this will produce 1000 correlated samples.
The number of independent samples is
nsamples*thin_by_nact=200 in this
>>> bilby.run_sampler( likelihood, priors, sampler="bilby_mcmc", 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=4 is recommended. Choosing non-multiple values will reduce
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
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
You can modify either the
'gwA' proposal cycles
by removing a particular class of proposals. For example, to remove the
Adaptive Gaussian proposals used
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.
$ pip install nflows
nflows depends on
PyTorch. Please see the
documentation for help with installation.
sklean used by the Gaussian Mixture Model, see the
If these are not installed, but the proposals are used a warning message is printed and the proposals ignored.
Proposal Cycles: custom
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
>>> 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.