API
AbstractMCMC defines an interface for sampling Markov chains.
Model
AbstractMCMC.AbstractModel
— TypeAbstractModel
An AbstractModel
represents a generic model type that can be used to perform inference.
AbstractMCMC.LogDensityModel
— TypeLogDensityModel <: AbstractMCMC.AbstractModel
Wrapper around something that implements the LogDensityProblem.jl interface.
Note that this does not implement the LogDensityProblems.jl interface itself, but it simply useful for indicating to the sample
and other AbstractMCMC
methods that the wrapped object implements the LogDensityProblems.jl interface.
Fields
logdensity
: The object that implements the LogDensityProblems.jl interface.
Sampler
AbstractMCMC.AbstractSampler
— TypeAbstractSampler
The AbstractSampler
type is intended to be inherited from when implementing a custom sampler. Any persistent state information should be saved in a subtype of AbstractSampler
.
When defining a new sampler, you should also overload the function transition_type
, which tells the sample
function what type of parameter it should expect to receive.
Sampling a single chain
StatsBase.sample
— Methodsample(
+API · AbstractMCMC
+
+
+
+
+
+API
AbstractMCMC defines an interface for sampling Markov chains.
Model
AbstractMCMC.AbstractModel
— TypeAbstractModel
An AbstractModel
represents a generic model type that can be used to perform inference.
sourceAbstractMCMC.LogDensityModel
— TypeLogDensityModel <: AbstractMCMC.AbstractModel
Wrapper around something that implements the LogDensityProblem.jl interface.
Note that this does not implement the LogDensityProblems.jl interface itself, but it simply useful for indicating to the sample
and other AbstractMCMC
methods that the wrapped object implements the LogDensityProblems.jl interface.
Fields
logdensity
: The object that implements the LogDensityProblems.jl interface.
sourceSampler
AbstractMCMC.AbstractSampler
— TypeAbstractSampler
The AbstractSampler
type is intended to be inherited from when implementing a custom sampler. Any persistent state information should be saved in a subtype of AbstractSampler
.
When defining a new sampler, you should also overload the function transition_type
, which tells the sample
function what type of parameter it should expect to receive.
sourceSampling a single chain
StatsBase.sample
— Methodsample(
rng::Random.AbatractRNG=Random.default_rng(),
model::AbstractModel,
sampler::AbstractSampler,
@@ -150,3 +608,4 @@
while ...
transition, state = AbstractMCMC.step(rng, model, sampler, state)
end
Settings
This document was generated with Documenter.jl version 1.8.0 on Friday 29 November 2024. Using Julia version 1.11.1.
+
diff --git a/previews/PR151/design/index.html b/previews/PR151/design/index.html
index 82082b2..e5ad1ef 100644
--- a/previews/PR151/design/index.html
+++ b/previews/PR151/design/index.html
@@ -1,5 +1,463 @@
-Design · AbstractMCMC Design
This page explains the default implementations and design choices of AbstractMCMC. It is not intended for users but for developers that want to implement the AbstractMCMC interface for Markov chain Monte Carlo sampling. The user-facing API is explained in API.
Overview
AbstractMCMC provides a default implementation of the user-facing interface described in API. You can completely neglect these and define your own implementation of the interface. However, as described below, in most use cases the default implementation allows you to obtain support of parallel sampling, progress logging, callbacks, iterators, and transducers for free by just defining the sampling step of your inference algorithm, drastically reducing the amount of code you have to write. In general, the docstrings of the functions described below might be helpful if you intend to make use of the default implementations.
Basic structure
The simplified structure for regular sampling (the actual implementation contains some additional error checks and support for progress logging and callbacks) is
StatsBase.sample(
+Design · AbstractMCMC
+
+
+
+
+
+Design
This page explains the default implementations and design choices of AbstractMCMC. It is not intended for users but for developers that want to implement the AbstractMCMC interface for Markov chain Monte Carlo sampling. The user-facing API is explained in API.
Overview
AbstractMCMC provides a default implementation of the user-facing interface described in API. You can completely neglect these and define your own implementation of the interface. However, as described below, in most use cases the default implementation allows you to obtain support of parallel sampling, progress logging, callbacks, iterators, and transducers for free by just defining the sampling step of your inference algorithm, drastically reducing the amount of code you have to write. In general, the docstrings of the functions described below might be helpful if you intend to make use of the default implementations.
Basic structure
The simplified structure for regular sampling (the actual implementation contains some additional error checks and support for progress logging and callbacks) is
StatsBase.sample(
rng::Random.AbstractRNG,
model::AbstractMCMC.AbstractModel,
sampler::AbstractMCMC.AbstractSampler,
@@ -25,3 +483,4 @@
return AbstractMCMC.bundle_samples(samples, model, sampler, state, chain_type; kwargs...)
end
All other default implementations make use of the same structure and in particular call the same methods.
Sampling step
The only method for which no default implementation is provided (and hence which downstream packages have to implement) is AbstractMCMC.step
. It defines the sampling step of the inference method.
AbstractMCMC.step
— Functionstep(rng, model, sampler[, state; kwargs...])
Return a 2-tuple of the next sample and the next state of the MCMC sampler
for model
.
Samples describe the results of a single step of the sampler
. As an example, a sample might include a vector of parameters sampled from a prior distribution.
When sampling using sample
, every step
call after the first has access to the current state
of the sampler.
sourceIf one also has some special handling of the warmup-stage of sampling, then this can be specified by overloading
AbstractMCMC.step_warmup
— Functionstep_warmup(rng, model, sampler[, state; kwargs...])
Return a 2-tuple of the next sample and the next state of the MCMC sampler
for model
.
When sampling using sample
, this takes the place of AbstractMCMC.step
in the first num_warmup
number of iterations, as specified by the num_warmup
keyword to sample
. This is useful if the sampler has an initial "warmup"-stage that is different from the standard iteration.
By default, this simply calls AbstractMCMC.step
.
sourcewhich will be used for the first num_warmup
iterations, as specified as a keyword argument to AbstractMCMC.sample
. Note that this is optional; by default it simply calls AbstractMCMC.step
from above.
Collecting samples
Note This section does not apply to the iterator and transducer interface.
After the initial sample is obtained, the default implementations for regular and parallel sampling (not for the iterator and the transducer since it is not needed there) create a container for all samples (the initial one and all subsequent samples) using AbstractMCMC.samples
.
AbstractMCMC.samples
— Functionsamples(sample, model, sampler[, N; kwargs...])
Generate a container for the samples of the MCMC sampler
for the model
, whose first sample is sample
.
The method can be called with and without a predefined number N
of samples.
sourceIn each step, the sample is saved in the container by AbstractMCMC.save!!
. The notation !!
follows the convention of the package BangBang.jl which is used in the default implementation of AbstractMCMC.save!!
. It indicates that the sample is pushed to the container but a "widening" fallback is used if the container type does not allow to save the sample. Therefore AbstractMCMC.save!!
always has to return the container.
AbstractMCMC.save!!
— Functionsave!!(samples, sample, iteration, model, sampler[, N; kwargs...])
Save the sample
of the MCMC sampler
at the current iteration
in the container of samples
.
The function can be called with and without a predefined number N
of samples. By default, AbstractMCMC uses push!!
from the Julia package BangBang to append to the container, and widen its type if needed.
sourceFor most use cases the default implementation of AbstractMCMC.samples
and AbstractMCMC.save!!
should work out of the box and hence need not to be overloaded in downstream code.
Creating chains
Note This section does not apply to the iterator and transducer interface.
At the end of the sampling procedure for regular and paralle sampling we transform the collection of samples to the desired output type by calling AbstractMCMC.bundle_samples
.
AbstractMCMC.bundle_samples
— Functionbundle_samples(samples, model, sampler, state, chain_type[; kwargs...])
Bundle all samples
that were sampled from the model
with the given sampler
in a chain.
The final state
of the sampler
can be included in the chain. The type of the chain can be specified with the chain_type
argument.
By default, this method returns samples
.
sourceThe default implementation should be fine in most use cases, but downstream packages could, e.g., save the final state of the sampler as well if they overload AbstractMCMC.bundle_samples
.
Settings
This document was generated with Documenter.jl version 1.8.0 on Friday 29 November 2024. Using Julia version 1.11.1.
+
diff --git a/previews/PR151/index.html b/previews/PR151/index.html
index fa6bdbb..1bf487d 100644
--- a/previews/PR151/index.html
+++ b/previews/PR151/index.html
@@ -1,2 +1,461 @@
-Home · AbstractMCMC AbstractMCMC.jl
Abstract types and interfaces for Markov chain Monte Carlo methods.
AbstractMCMC defines an interface for sampling and combining Markov chains. It comes with a default sampling algorithm that provides support of progress bars, parallel sampling (multithreaded and multicore), and user-provided callbacks out of the box. Typically developers only have to define the sampling step of their inference method in an iterator-like fashion to make use of this functionality. Additionally, the package defines an iterator and a transducer for sampling Markov chains based on the interface.
Settings
This document was generated with Documenter.jl version 1.8.0 on Friday 29 November 2024. Using Julia version 1.11.1.
+Home · AbstractMCMC
+
+
+
+
+
+AbstractMCMC.jl
Abstract types and interfaces for Markov chain Monte Carlo methods.
AbstractMCMC defines an interface for sampling and combining Markov chains. It comes with a default sampling algorithm that provides support of progress bars, parallel sampling (multithreaded and multicore), and user-provided callbacks out of the box. Typically developers only have to define the sampling step of their inference method in an iterator-like fashion to make use of this functionality. Additionally, the package defines an iterator and a transducer for sampling Markov chains based on the interface.
Settings
This document was generated with Documenter.jl version 1.8.0 on Friday 29 November 2024. Using Julia version 1.11.1.
+