diff --git a/bilby/bilby_mcmc/sampler.py b/bilby/bilby_mcmc/sampler.py
index 6cad693ae9c1879388141d99d49fc282a3e0487a..767e3a65085fb40235e9eebfe0002a9d83ad39a3 100644
--- a/bilby/bilby_mcmc/sampler.py
+++ b/bilby/bilby_mcmc/sampler.py
@@ -46,9 +46,6 @@ class Bilby_MCMC(MCMCSampler):
If true, resume from any existing check point files
exit_code: int
The code on which to raise if exiting
-
- Sampling Parameters
- -------------------
nsamples: int (1000)
The number of samples to draw
nensemble: int (1)
diff --git a/bilby/core/utils/conversion.py b/bilby/core/utils/conversion.py
index af8882991dc7be90b898c55f33e8823a920efc5b..978e34346039d2d7fafb1cc865349394cb25969e 100644
--- a/bilby/core/utils/conversion.py
+++ b/bilby/core/utils/conversion.py
@@ -42,7 +42,7 @@ def gps_time_to_gmst(gps_time):
Error accumulates at a rate of ~0.0001 radians/decade.
Parameters
- -------
+ ----------
gps_time: float
gps time
diff --git a/docs/bilby-mcmc-guide.txt b/docs/bilby-mcmc-guide.txt
new file mode 100644
index 0000000000000000000000000000000000000000..2a196db524e36c6f987a96e06f82dd4210f4d461
--- /dev/null
+++ b/docs/bilby-mcmc-guide.txt
@@ -0,0 +1,157 @@
+.. _bilby-mcmc-guide:
+
+================
+Bilby MCMC Guide
+================
+
+Bilby MCMC is a native sampler built directly in :code:`bilby` and described in
+`Ashton & Talbot (2021) <https://ui.adsabs.harvard.edu/abs/2021arXiv210608730A/abstract>`_.
+Here, we describe how to use it.
+
+
+Quickstart and output
+---------------------
+To use the :code:`bilby_mcmc` sampler, we call
+
+.. code-block:: python
+
+ >>> 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
+
+.. code-block:: console
+
+ 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.
+
+Configuration
+-------------
+
+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 at the end of this page for an exhaustive list.
+
+Here, we provide a code snippet to run :code:`bilby-mcmc` with
+parallel-tempering, and set the :code:`thin_by_nact` parameter. Note that,
+because :code:`thin_by_nact < 1`, this will produce 1000 correlated samples.
+The number of independent samples is :code:`nsamples*thin_by_nact=200` in this
+case.
+
+.. code-block:: python
+
+ >>> 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
+ )
+
+.. note::
+ If the ACT of your runs are consistently 1 with the above settings, you may
+ wish to decrease the number of internal steps :code:`L1steps`. The parameter
+ above has been tuned for typical gravitational-wave problems where the ACT
+ is usually several thousand.
+
+.. note::
+ You should choose `npool` to suit your computer and the number of parallel
+ chains. If you have 8 cores and use 8 temperatures, then :code:`npool=8`
+ or :code:`npool=4` is recommended. Choosing non-multiple values will reduce
+ the efficiency.
+
+Proposal Cycles: built-in
+--------------------------
+
+:code:`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 :code:`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.
+
+.. code-block:: console
+
+ 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
+:code:`bilby_mcmc` to analyse a CBC gravitational-wave signal, you can use
+:code:`proposal_cycle='gwA'` to select the proposal cycle described in Table 1
+of 2106.08730.
+
+.. note::
+ You can modify either the :code:`'default'` or :code:`'gwA'` proposal cycles
+ by removing a particular class of proposals. For example, to remove the
+ Adaptive Gaussian proposals used :code:`proposal_cycle='default_noAG'`. The
+ two-letter codes follow the conventions established in Ashton & Talbot (2021).
+
+.. note::
+ The Normalizing Flow, and Gaussian Mixture Model proposals require additional
+ software to be installed.
+
+ To install :code:`nflows`, run
+
+ .. code-block:: console
+
+ $ pip install nflows
+
+ Note: :code:`nflows` depends on :code:`PyTorch`. Please see `the
+ documentation <https://pytorch.org/>`_ for help with installation.
+
+ To install :code:`sklean` used by the Gaussian Mixture Model, see the
+ `installation instructions <https://scikit-learn.org/stable/install.html>`_.
+
+ If these are not installed, but the proposals are used a warning message is
+ printed and the proposals ignored.
+
+Proposal Cycles: custom
+-----------------------
+
+The :code:`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 :code:`run_sampler`.
+
+.. code-block:: python
+
+ >>> 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.
+
+Full API
+--------
+
+.. autoclass:: bilby.bilby_mcmc.sampler.Bilby_MCMC
diff --git a/docs/conf.py b/docs/conf.py
index 9c7aba43d7bbd861ca382eec3aeb09200292a341..8b130c4afd866e8ee71be443cbff6698c55d47dd 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -105,7 +105,7 @@ html_theme = 'sphinx_rtd_theme'
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
diff --git a/docs/index.txt b/docs/index.txt
index efdbda91f0adf10e31725228d88118eff7535723..2259e08b4bf12eb2fe4e25997cdac364a3746541 100644
--- a/docs/index.txt
+++ b/docs/index.txt
@@ -16,6 +16,7 @@ Welcome to bilby's documentation!
likelihood
samplers
dynesty-guide
+ bilby-mcmc-guide
bilby-output
compact-binary-coalescence-parameter-estimation
transient-gw-data
@@ -28,6 +29,7 @@ Welcome to bilby's documentation!
containers
faq
+
.. toctree::
:maxdepth: 1
:caption: Examples:
@@ -51,4 +53,4 @@ API:
core
gw
hyper
-
+ bilby_mcmc
diff --git a/docs/samplers.txt b/docs/samplers.txt
index 3da888fd2d4afc6895a8271fbd1ae1cf06116757..8e26550cb1c2d564d8c1c4ed3810890ed214cf98 100644
--- a/docs/samplers.txt
+++ b/docs/samplers.txt
@@ -66,6 +66,7 @@ Nested Samplers
MCMC samplers
-------------
+- bilby-mcmc :code:`bilby.bilby_mcmc.sampler.Bilby_MCMC`
- emcee :code:`bilby.core.sampler.emcee.Emcee`
- ptemcee :code:`bilby.core.sampler.ptemcee.Ptemcee`
- pymc3 :code:`bilby.core.sampler.pymc3.Pymc3`