From b67742e57756b796997b7a1734433c5a46f0daf9 Mon Sep 17 00:00:00 2001 From: "Documenter.jl" Date: Fri, 21 Feb 2025 01:05:42 +0000 Subject: [PATCH] build based on bc71a07 --- previews/PR393/.documenter-siteinfo.json | 2 +- previews/PR393/api/index.html | 8 ++++---- previews/PR393/index.html | 4 ++-- previews/PR393/search_index.js | 2 +- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/previews/PR393/.documenter-siteinfo.json b/previews/PR393/.documenter-siteinfo.json index 66d3ccb9..42b56047 100644 --- a/previews/PR393/.documenter-siteinfo.json +++ b/previews/PR393/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.11.3","generation_timestamp":"2025-02-19T23:22:19","documenter_version":"1.8.1"}} \ No newline at end of file +{"documenter":{"julia_version":"1.11.3","generation_timestamp":"2025-02-21T01:05:31","documenter_version":"1.8.1"}} \ No newline at end of file diff --git a/previews/PR393/api/index.html b/previews/PR393/api/index.html index 4e0c17da..38ae622b 100644 --- a/previews/PR393/api/index.html +++ b/previews/PR393/api/index.html @@ -458,7 +458,7 @@ -
GitHub

AdvancedHMC.jl

Documentation for AdvancedHMC.jl

Types

AdvancedHMC.ClassicNoUTurn — Type
struct ClassicNoUTurn{F<:AbstractFloat} <: AdvancedHMC.DynamicTerminationCriterion

Classic No-U-Turn criterion as described in Eq. (9) in [1].

Informally, this will terminate the trajectory expansion if continuing the simulation either forwards or backwards in time will decrease the distance between the left-most and right-most positions.

Fields

  • max_depth::Int64

  • Δ_max::AbstractFloat

References

  1. Hoffman, M. D., & Gelman, A. (2014). The No-U-Turn Sampler: adaptively setting path lengths in Hamiltonian Monte Carlo. Journal of Machine Learning Research, 15(1), 1593-1623. (arXiv)
source
AdvancedHMC.HMCSampler — Type
HMCSampler

An AbstractMCMC.AbstractSampler for kernels in AdvancedHMC.jl.

Fields

Notes

Note that all the fields have the prefix initial_ to indicate that these will not necessarily correspond to the kernel, metric, and adaptor after sampling.

To access the updated fields, use the resulting HMCState.

source
AdvancedHMC.HMC — Type
HMC(ϵ::Real, n_leapfrog::Int)

Hamiltonian Monte Carlo sampler with static trajectory.

Fields

  • n_leapfrog: Number of leapfrog steps.

  • integrator: Choice of integrator, specified either using a Symbol or AbstractIntegrator

  • metric: Choice of initial metric; Symbol means it is automatically initialised. The metric type will be preserved during automatic initialisation and adaption.

source
AdvancedHMC.NUTS — Type
NUTS(δ::Real; max_depth::Int=10, Δ_max::Real=1000, integrator = :leapfrog, metric = :diagonal)

No-U-Turn Sampler (NUTS) sampler.

Fields

  • δ: Target acceptance rate for dual averaging.

  • max_depth: Maximum doubling tree depth.

  • Δ_max: Maximum divergence during doubling tree.

  • integrator: Choice of integrator, specified either using a Symbol or AbstractIntegrator

  • metric: Choice of initial metric; Symbol means it is automatically initialised. The metric type will be preserved during automatic initialisation and adaption.

source
AdvancedHMC.HMCDA — Type
HMCDA(δ::Real, λ::Real, integrator = :leapfrog, metric = :diagonal)

Hamiltonian Monte Carlo sampler with Dual Averaging algorithm.

Fields

  • δ: Target acceptance rate for dual averaging.

  • λ: Target leapfrog length.

  • integrator: Choice of integrator, specified either using a Symbol or AbstractIntegrator

  • metric: Choice of initial metric; Symbol means it is automatically initialised. The metric type will be preserved during automatic initialisation and adaption.

Notes

For more information, please view the following paper (arXiv link):

  • Hoffman, Matthew D., and Andrew Gelman. "The No-U-turn sampler: adaptively setting path lengths in Hamiltonian Monte Carlo." Journal of Machine Learning Research 15, no. 1 (2014): 1593-1623.
source

Functions

StatsBase.sample — Function
sample([rng], a::AbstractArray, [wv::AbstractWeights])

Select a single random element of a. Sampling probabilities are proportional to the weights given in wv, if provided.

Optionally specify a random number generator rng as the first argument (defaults to Random.default_rng()).

source
sample([rng], a, [wv::AbstractWeights], n::Integer; replace=true, ordered=false)

Select a random, optionally weighted sample of size n from an array a using a polyalgorithm. Sampling probabilities are proportional to the weights given in wv, if provided. replace dictates whether sampling is performed with replacement. ordered dictates whether an ordered sample (also called a sequential sample, i.e. a sample where items appear in the same order as in a) should be taken.

Optionally specify a random number generator rng as the first argument (defaults to Random.default_rng()).

source
sample([rng], a, [wv::AbstractWeights], dims::Dims; replace=true, ordered=false)

Select a random, optionally weighted sample from an array a specifying the dimensions dims of the output array. Sampling probabilities are proportional to the weights given in wv, if provided. replace dictates whether sampling is performed with replacement. ordered dictates whether an ordered sample (also called a sequential sample, i.e. a sample where items appear in the same order as in a) should be taken.

Optionally specify a random number generator rng as the first argument (defaults to Random.default_rng()).

source
sample([rng], wv::AbstractWeights)

Select a single random integer in 1:length(wv) with probabilities proportional to the weights given in wv.

Optionally specify a random number generator rng as the first argument (defaults to Random.default_rng()).

source
sample(
+
GitHub
AdvancedHMC.jl
Documentation for AdvancedHMC.jl
Types
AdvancedHMC.ClassicNoUTurn — Type
struct ClassicNoUTurn{F<:AbstractFloat} <: AdvancedHMC.DynamicTerminationCriterion
Classic No-U-Turn criterion as described in Eq. (9) in [1].
Informally, this will terminate the trajectory expansion if continuing the simulation either forwards or backwards in time will decrease the distance between the left-most and right-most positions.
Fields
  • max_depth::Int64
  • Δ_max::AbstractFloat
References
  1. Hoffman, M. D., & Gelman, A. (2014). The No-U-Turn Sampler: adaptively setting path lengths in Hamiltonian Monte Carlo. Journal of Machine Learning Research, 15(1), 1593-1623. (arXiv)
source
AdvancedHMC.HMCSampler — Type
HMCSampler
An AbstractMCMC.AbstractSampler for kernels in AdvancedHMC.jl.
Fields
Notes
Note that all the fields have the prefix initial_ to indicate that these will not necessarily correspond to the kernel, metric, and adaptor after sampling.
To access the updated fields, use the resulting HMCState.
source
AdvancedHMC.HMC — Type
HMC(ϵ::Real, n_leapfrog::Int)
Hamiltonian Monte Carlo sampler with static trajectory.
Fields
  • n_leapfrog: Number of leapfrog steps.
  • integrator: Choice of integrator, specified either using a Symbol or AbstractIntegrator
  • metric: Choice of initial metric;  Symbol means it is automatically initialised. The metric type will be preserved during automatic initialisation and adaption.
source
AdvancedHMC.NUTS — Type
NUTS(δ::Real; max_depth::Int=10, Δ_max::Real=1000, integrator = :leapfrog, metric = :diagonal)
No-U-Turn Sampler (NUTS) sampler.
Fields
  • δ: Target acceptance rate for dual averaging.
  • max_depth: Maximum doubling tree depth.
  • Δ_max: Maximum divergence during doubling tree.
  • integrator: Choice of integrator, specified either using a Symbol or AbstractIntegrator
  • metric: Choice of initial metric;  Symbol means it is automatically initialised. The metric type will be preserved during automatic initialisation and adaption.
source
AdvancedHMC.HMCDA — Type
HMCDA(δ::Real, λ::Real, integrator = :leapfrog, metric = :diagonal)
Hamiltonian Monte Carlo sampler with Dual Averaging algorithm.
Fields
  • δ: Target acceptance rate for dual averaging.
  • λ: Target leapfrog length.
  • integrator: Choice of integrator, specified either using a Symbol or AbstractIntegrator
  • metric: Choice of initial metric;  Symbol means it is automatically initialised. The metric type will be preserved during automatic initialisation and adaption.
Notes
For more information, please view the following paper (arXiv link):
  • Hoffman, Matthew D., and Andrew Gelman. "The No-U-turn sampler: adaptively setting path lengths in Hamiltonian Monte Carlo." Journal of Machine Learning Research 15, no. 1 (2014): 1593-1623.
source
Functions
StatsBase.sample — Function
sample([rng], a::AbstractArray, [wv::AbstractWeights])
Select a single random element of a. Sampling probabilities are proportional to the weights given in wv, if provided.
Optionally specify a random number generator rng as the first argument (defaults to Random.default_rng()).
source
sample([rng], a, [wv::AbstractWeights], n::Integer; replace=true, ordered=false)
Select a random, optionally weighted sample of size n from an array a using a polyalgorithm. Sampling probabilities are proportional to the weights given in wv, if provided. replace dictates whether sampling is performed with replacement. ordered dictates whether an ordered sample (also called a sequential sample, i.e. a sample where items appear in the same order as in a) should be taken.
Optionally specify a random number generator rng as the first argument (defaults to Random.default_rng()).
source
sample([rng], a, [wv::AbstractWeights], dims::Dims; replace=true, ordered=false)
Select a random, optionally weighted sample from an array a specifying the dimensions dims of the output array. Sampling probabilities are proportional to the weights given in wv, if provided. replace dictates whether sampling is performed with replacement. ordered dictates whether an ordered sample (also called a sequential sample, i.e. a sample where items appear in the same order as in a) should be taken.
Optionally specify a random number generator rng as the first argument (defaults to Random.default_rng()).
source
sample([rng], wv::AbstractWeights)
Select a single random integer in 1:length(wv) with probabilities proportional to the weights given in wv.
Optionally specify a random number generator rng as the first argument (defaults to Random.default_rng()).
source
sample(
     rng::Random.AbatractRNG=Random.default_rng(),
     model::AbstractModel,
     sampler::AbstractSampler,
@@ -497,6 +497,6 @@
     drop_warmup::Bool=false,
     verbose::Bool=true,
     progress::Bool=false
-)
Sample n_samples samples using the proposal κ under Hamiltonian h.
  • The randomness is controlled by rng. 
    • If rng is not provided, GLOBAL_RNG will be used.
  • The initial point is given by θ.
  • The adaptor is set by adaptor, for which the default is no adaptation.
    • It will perform n_adapts steps of adaptation, for which the default is the minimum of 1_000 and 10% of n_samples
  • drop_warmup controls to drop the samples during adaptation phase or not
  • verbose controls the verbosity
  • progress controls whether to show the progress meter or not
source
More types
AdvancedHMC.AbstractIntegrator — Type
abstract type AbstractIntegrator
Represents an integrator used to simulate the Hamiltonian system.
Implementation
A AbstractIntegrator is expected to have the following implementations:
  • stat(@ref)
  • nom_step_size(@ref)
  • step_size(@ref)
source
AdvancedHMC.ClassicNoUTurn — Type
struct ClassicNoUTurn{F<:AbstractFloat} <: AdvancedHMC.DynamicTerminationCriterion
Classic No-U-Turn criterion as described in Eq. (9) in [1].
Informally, this will terminate the trajectory expansion if continuing the simulation either forwards or backwards in time will decrease the distance between the left-most and right-most positions.
Fields
  • max_depth::Int64
  • Δ_max::AbstractFloat
References
  1. Hoffman, M. D., & Gelman, A. (2014). The No-U-Turn Sampler: adaptively setting path lengths in Hamiltonian Monte Carlo. Journal of Machine Learning Research, 15(1), 1593-1623. (arXiv)
source
AdvancedHMC.FixedIntegrationTime — Type
struct FixedIntegrationTime{F<:AbstractFloat} <: AdvancedHMC.StaticTerminationCriterion
Standard HMC implementation with a fixed integration time.
Fields
  • λ::AbstractFloat: Total length of the trajectory, i.e. take floor(λ / integrator_step_size) number of leapfrog steps.
References
  1. Neal, R. M. (2011). MCMC using Hamiltonian dynamics. Handbook of Markov chain Monte Carlo, 2(11), 2. (arXiv) 
source
AdvancedHMC.FixedNSteps — Type
struct FixedNSteps <: AdvancedHMC.StaticTerminationCriterion
Static HMC with a fixed number of leapfrog steps.
Fields
  • L::Int64: Number of steps to simulate, i.e. length of trajectory will be L + 1.
References
  1. Neal, R. M. (2011). MCMC using Hamiltonian dynamics. Handbook of Markov chain Monte Carlo, 2(11), 2. (arXiv)
source
AdvancedHMC.GeneralisedNoUTurn — Type
struct GeneralisedNoUTurn{F<:AbstractFloat} <: AdvancedHMC.DynamicTerminationCriterion
Generalised No-U-Turn criterion as described in Section A.4.2 in [1].
Fields
  • max_depth::Int64
  • Δ_max::AbstractFloat
References
  1. Betancourt, M. (2017). A Conceptual Introduction to Hamiltonian Monte Carlo. arXiv preprint arXiv:1701.02434.
source
AdvancedHMC.GeneralizedLeapfrog — Type
struct GeneralizedLeapfrog{T<:(Union{AbstractVector{var"#s17"}, var"#s17"} where var"#s17"<:AbstractFloat)} <: AdvancedHMC.AbstractLeapfrog{T<:(Union{AbstractVector{var"#s17"}, var"#s17"} where var"#s17"<:AbstractFloat)}
Generalized leapfrog integrator with fixed step size ϵ.
Fields
  • ϵ::Union{AbstractVector{var"#s17"}, var"#s17"} where var"#s17"<:AbstractFloat: Step size.
  • n::Int64
References
  1. Girolami, Mark, and Ben Calderhead. "Riemann manifold Langevin and Hamiltonian Monte Carlo methods." Journal of the Royal Statistical Society Series B: Statistical Methodology 73, no. 2 (2011): 123-214.
source
AdvancedHMC.HMC — Type
HMC(ϵ::Real, n_leapfrog::Int)
Hamiltonian Monte Carlo sampler with static trajectory.
Fields
  • n_leapfrog: Number of leapfrog steps.
  • integrator: Choice of integrator, specified either using a Symbol or AbstractIntegrator
  • metric: Choice of initial metric;  Symbol means it is automatically initialised. The metric type will be preserved during automatic initialisation and adaption.
source
AdvancedHMC.HMCDA — Type
HMCDA(δ::Real, λ::Real, integrator = :leapfrog, metric = :diagonal)
Hamiltonian Monte Carlo sampler with Dual Averaging algorithm.
Fields
  • δ: Target acceptance rate for dual averaging.
  • λ: Target leapfrog length.
  • integrator: Choice of integrator, specified either using a Symbol or AbstractIntegrator
  • metric: Choice of initial metric;  Symbol means it is automatically initialised. The metric type will be preserved during automatic initialisation and adaption.
Notes
For more information, please view the following paper (arXiv link):
  • Hoffman, Matthew D., and Andrew Gelman. "The No-U-turn sampler: adaptively setting path lengths in Hamiltonian Monte Carlo." Journal of Machine Learning Research 15, no. 1 (2014): 1593-1623.
source
AdvancedHMC.HMCProgressCallback — Type
HMCProgressCallback
A callback to be used with AbstractMCMC.jl's interface, replicating the logging behavior of the non-AbstractMCMC sample.
Fields
  • pm: Progress meter from ProgressMeters.jl.
  • progress: Specifies whether or not to use display a progress bar.
  • verbose: If progress is not specified and this is true some information will be logged upon completion of adaptation.
  • num_divergent_transitions: Number of divergent transitions fo far.
  • num_divergent_transitions_during_adaption
source
AdvancedHMC.HMCSampler — Type
HMCSampler
An AbstractMCMC.AbstractSampler for kernels in AdvancedHMC.jl.
Fields
Notes
Note that all the fields have the prefix initial_ to indicate that these will not necessarily correspond to the kernel, metric, and adaptor after sampling.
To access the updated fields, use the resulting HMCState.
source
AdvancedHMC.JitteredLeapfrog — Type
struct JitteredLeapfrog{FT<:AbstractFloat, T<:Union{AbstractArray{FT<:AbstractFloat, 1}, FT<:AbstractFloat}} <: AdvancedHMC.AbstractLeapfrog{T<:Union{AbstractArray{FT<:AbstractFloat, 1}, FT<:AbstractFloat}}
Leapfrog integrator with randomly "jittered" step size ϵ for every trajectory.
Fields
  • ϵ0::Union{AbstractVector{FT}, FT} where FT<:AbstractFloat: Nominal (non-jittered) step size.
  • jitter::AbstractFloat: The proportion of the nominal step size ϵ0 that may be added or subtracted.
  • ϵ::Union{AbstractVector{FT}, FT} where FT<:AbstractFloat: Current (jittered) step size.
Description
This is the same as LeapFrog(@ref) but with a "jittered" step size. This means  that at the beginning of each trajectory we sample a step size ϵ by adding or  subtracting from the nominal/base step size ϵ0 some random proportion of ϵ0,  with the proportion specified by jitter, i.e. ϵ = ϵ0 - jitter * ϵ0 * rand(). p Jittering might help alleviate issues related to poor interactions with a fixed step size:
  • In regions with high "curvature" the current choice of step size might mean over-shoot  leading to almost all steps being rejected. Randomly sampling the step size at the  beginning of the trajectories can therefore increase the probability of escaping such high-curvature regions.
  • Exact periodicity of the simulated trajectories might occur, i.e. you might be so unlucky as to simulate the trajectory forwards in time L ϵ and ending up at the same point (which results in non-ergodicity; see Section 3.2 in [1]). If momentum is refreshed before each trajectory, then this should not happen exactly but it can still be an issue in practice. Randomly choosing the step-size ϵ might help alleviate such problems.
References
  1. Neal, R. M. (2011). MCMC using Hamiltonian dynamics. Handbook of Markov chain Monte Carlo, 2(11), 2. (arXiv)
source
AdvancedHMC.Leapfrog — Type
struct Leapfrog{T<:(Union{AbstractVector{var"#s26"}, var"#s26"} where var"#s26"<:AbstractFloat)} <: AdvancedHMC.AbstractLeapfrog{T<:(Union{AbstractVector{var"#s26"}, var"#s26"} where var"#s26"<:AbstractFloat)}
Leapfrog integrator with fixed step size ϵ.
Fields
  • ϵ::Union{AbstractVector{var"#s26"}, var"#s26"} where var"#s26"<:AbstractFloat: Step size.
source
AdvancedHMC.MultinomialTS — Method
struct MultinomialTS{F<:AbstractFloat} <: AdvancedHMC.AbstractTrajectorySampler
Multinomial sampler for a trajectory consisting only a leaf node.
  • tree weight is the (unnormalised) energy of the leaf.
source
AdvancedHMC.MultinomialTS — Method
struct MultinomialTS{F<:AbstractFloat} <: AdvancedHMC.AbstractTrajectorySampler
Multinomial sampler for the starting single leaf tree. (Log) weights for leaf nodes are their (unnormalised) Hamiltonian energies.
Ref: https://github.com/stan-dev/stan/blob/develop/src/stan/mcmc/hmc/nuts/base_nuts.hpp#L226
source
AdvancedHMC.MultinomialTS — Type
struct MultinomialTS{F<:AbstractFloat} <: AdvancedHMC.AbstractTrajectorySampler
Multinomial trajectory sampler carried during the building of the tree. It contains the weight of the tree, defined as the total probabilities of the leaves.
Fields
  • zcand::AdvancedHMC.PhasePoint: Sampled candidate PhasePoint.
  • ℓw::AbstractFloat: Total energy for the given tree, i.e. the sum of energies of all leaves.
source
AdvancedHMC.NUTS — Type
NUTS(δ::Real; max_depth::Int=10, Δ_max::Real=1000, integrator = :leapfrog, metric = :diagonal)
No-U-Turn Sampler (NUTS) sampler.
Fields
  • δ: Target acceptance rate for dual averaging.
  • max_depth: Maximum doubling tree depth.
  • Δ_max: Maximum divergence during doubling tree.
  • integrator: Choice of integrator, specified either using a Symbol or AbstractIntegrator
  • metric: Choice of initial metric;  Symbol means it is automatically initialised. The metric type will be preserved during automatic initialisation and adaption.
source
AdvancedHMC.PartialMomentumRefreshment — Type
struct PartialMomentumRefreshment{F<:AbstractFloat} <: AdvancedHMC.AbstractMomentumRefreshment
Partial momentum refreshment with refresh rate α.
Fields
  • α::AbstractFloat
See equation (5.19) [1]
r' = α⋅r + sqrt(1-α²)⋅G
where r is the momentum and G is a Gaussian random variable.
References
  1. Neal, Radford M. "MCMC using Hamiltonian dynamics." Handbook of markov chain monte carlo 2.11 (2011): 2.
source
AdvancedHMC.SliceTS — Method
struct SliceTS{F<:AbstractFloat} <: AdvancedHMC.AbstractTrajectorySampler
Slice sampler for the starting single leaf tree. Slice variable is initialized.
source
AdvancedHMC.SliceTS — Method
struct SliceTS{F<:AbstractFloat} <: AdvancedHMC.AbstractTrajectorySampler
Create a slice sampler for a single leaf tree:
  • the slice variable is copied from the passed-in sampler s and
  • the number of acceptable candicates is computed by comparing the slice variable against the current energy.
source
AdvancedHMC.SliceTS — Type
struct SliceTS{F<:AbstractFloat} <: AdvancedHMC.AbstractTrajectorySampler
Trajectory slice sampler carried during the building of the tree. It contains the slice variable and the number of acceptable condidates in the tree.
Fields
  • zcand::AdvancedHMC.PhasePoint: Sampled candidate PhasePoint.
  • ℓu::AbstractFloat: Slice variable in log-space.
  • n::Int64: Number of acceptable candidates, i.e. those with probability larger than slice variable u.
source
AdvancedHMC.TemperedLeapfrog — Type
struct TemperedLeapfrog{FT<:AbstractFloat, T<:Union{AbstractArray{FT<:AbstractFloat, 1}, FT<:AbstractFloat}} <: AdvancedHMC.AbstractLeapfrog{T<:Union{AbstractArray{FT<:AbstractFloat, 1}, FT<:AbstractFloat}}
Tempered leapfrog integrator with fixed step size ϵ and "temperature" α.
Fields
  • ϵ::Union{AbstractVector{FT}, FT} where FT<:AbstractFloat: Step size.
  • α::AbstractFloat: Temperature parameter.
Description
Tempering can potentially allow greater exploration of the posterior, e.g.  in a multi-modal posterior jumps between the modes can be more likely to occur.
source
AdvancedHMC.Termination — Type
Termination
Termination reasons
  • dynamic: due to stoping criteria
  • numerical: due to large energy deviation from starting (possibly numerical errors)
source
AdvancedHMC.Trajectory — Type
struct Trajectory{TS<:AdvancedHMC.AbstractTrajectorySampler, I<:AdvancedHMC.AbstractIntegrator, TC<:AdvancedHMC.AbstractTerminationCriterion}
Numerically simulated Hamiltonian trajectories.
source
AdvancedHMC.Transition — Type
struct Transition{P<:AdvancedHMC.PhasePoint, NT<:NamedTuple}
A transition that contains the phase point and other statistics of the transition.
Fields
  • z::AdvancedHMC.PhasePoint: Phase-point for the transition.
  • stat::NamedTuple: Statistics related to the transition, e.g. energy.
source
AdvancedHMC.Adaptation.NesterovDualAveraging — Type
An implementation of the Nesterov dual averaging algorithm to tune step size.
References
Hoffman, M. D., & Gelman, A. (2014). The No-U-Turn Sampler: adaptively setting path lengths in Hamiltonian Monte Carlo. Journal of Machine Learning Research, 15(1), 1593-1623. Nesterov, Y. (2009). Primal-dual subgradient methods for convex problems. Mathematical programming, 120(1), 221-259.
source

+)

Sample n_samples samples using the proposal κ under Hamiltonian h.

  • The randomness is controlled by rng.
    • If rng is not provided, the default random number generator (Random.default_rng()) will be used.
  • The initial point is given by θ.
  • The adaptor is set by adaptor, for which the default is no adaptation.
    • It will perform n_adapts steps of adaptation, for which the default is the minimum of 1_000 and 10% of n_samples
  • drop_warmup controls to drop the samples during adaptation phase or not
  • verbose controls the verbosity
  • progress controls whether to show the progress meter or not
source

More types

AdvancedHMC.AbstractIntegrator — Type
abstract type AbstractIntegrator

Represents an integrator used to simulate the Hamiltonian system.

Implementation

A AbstractIntegrator is expected to have the following implementations:

  • stat(@ref)
  • nom_step_size(@ref)
  • step_size(@ref)
source
AdvancedHMC.ClassicNoUTurn — Type
struct ClassicNoUTurn{F<:AbstractFloat} <: AdvancedHMC.DynamicTerminationCriterion

Classic No-U-Turn criterion as described in Eq. (9) in [1].

Informally, this will terminate the trajectory expansion if continuing the simulation either forwards or backwards in time will decrease the distance between the left-most and right-most positions.

Fields

  • max_depth::Int64

  • Δ_max::AbstractFloat

References

  1. Hoffman, M. D., & Gelman, A. (2014). The No-U-Turn Sampler: adaptively setting path lengths in Hamiltonian Monte Carlo. Journal of Machine Learning Research, 15(1), 1593-1623. (arXiv)
source
AdvancedHMC.FixedIntegrationTime — Type
struct FixedIntegrationTime{F<:AbstractFloat} <: AdvancedHMC.StaticTerminationCriterion

Standard HMC implementation with a fixed integration time.

Fields

  • λ::AbstractFloat: Total length of the trajectory, i.e. take floor(λ / integrator_step_size) number of leapfrog steps.

References

  1. Neal, R. M. (2011). MCMC using Hamiltonian dynamics. Handbook of Markov chain Monte Carlo, 2(11), 2. (arXiv)
source
AdvancedHMC.FixedNSteps — Type
struct FixedNSteps <: AdvancedHMC.StaticTerminationCriterion

Static HMC with a fixed number of leapfrog steps.

Fields

  • L::Int64: Number of steps to simulate, i.e. length of trajectory will be L + 1.

References

  1. Neal, R. M. (2011). MCMC using Hamiltonian dynamics. Handbook of Markov chain Monte Carlo, 2(11), 2. (arXiv)
source
AdvancedHMC.GeneralisedNoUTurn — Type
struct GeneralisedNoUTurn{F<:AbstractFloat} <: AdvancedHMC.DynamicTerminationCriterion

Generalised No-U-Turn criterion as described in Section A.4.2 in [1].

Fields

  • max_depth::Int64

  • Δ_max::AbstractFloat

References

  1. Betancourt, M. (2017). A Conceptual Introduction to Hamiltonian Monte Carlo. arXiv preprint arXiv:1701.02434.
source
AdvancedHMC.GeneralizedLeapfrog — Type
struct GeneralizedLeapfrog{T<:(Union{AbstractVector{var"#s17"}, var"#s17"} where var"#s17"<:AbstractFloat)} <: AdvancedHMC.AbstractLeapfrog{T<:(Union{AbstractVector{var"#s17"}, var"#s17"} where var"#s17"<:AbstractFloat)}

Generalized leapfrog integrator with fixed step size ϵ.

Fields

  • ϵ::Union{AbstractVector{var"#s17"}, var"#s17"} where var"#s17"<:AbstractFloat: Step size.

  • n::Int64

References

  1. Girolami, Mark, and Ben Calderhead. "Riemann manifold Langevin and Hamiltonian Monte Carlo methods." Journal of the Royal Statistical Society Series B: Statistical Methodology 73, no. 2 (2011): 123-214.
source
AdvancedHMC.HMC — Type
HMC(ϵ::Real, n_leapfrog::Int)

Hamiltonian Monte Carlo sampler with static trajectory.

Fields

  • n_leapfrog: Number of leapfrog steps.

  • integrator: Choice of integrator, specified either using a Symbol or AbstractIntegrator

  • metric: Choice of initial metric; Symbol means it is automatically initialised. The metric type will be preserved during automatic initialisation and adaption.

source
AdvancedHMC.HMCDA — Type
HMCDA(δ::Real, λ::Real, integrator = :leapfrog, metric = :diagonal)

Hamiltonian Monte Carlo sampler with Dual Averaging algorithm.

Fields

  • δ: Target acceptance rate for dual averaging.

  • λ: Target leapfrog length.

  • integrator: Choice of integrator, specified either using a Symbol or AbstractIntegrator

  • metric: Choice of initial metric; Symbol means it is automatically initialised. The metric type will be preserved during automatic initialisation and adaption.

Notes

For more information, please view the following paper (arXiv link):

  • Hoffman, Matthew D., and Andrew Gelman. "The No-U-turn sampler: adaptively setting path lengths in Hamiltonian Monte Carlo." Journal of Machine Learning Research 15, no. 1 (2014): 1593-1623.
source
AdvancedHMC.HMCProgressCallback — Type
HMCProgressCallback

A callback to be used with AbstractMCMC.jl's interface, replicating the logging behavior of the non-AbstractMCMC sample.

Fields

  • pm: Progress meter from ProgressMeters.jl, or nothing.

  • verbose: If pm === nothing and this is true some information will be logged upon completion of adaptation.

  • num_divergent_transitions: Number of divergent transitions.

  • num_divergent_transitions_during_adaption

source
AdvancedHMC.HMCSampler — Type
HMCSampler

An AbstractMCMC.AbstractSampler for kernels in AdvancedHMC.jl.

Fields

Notes

Note that all the fields have the prefix initial_ to indicate that these will not necessarily correspond to the kernel, metric, and adaptor after sampling.

To access the updated fields, use the resulting HMCState.

source
AdvancedHMC.JitteredLeapfrog — Type
struct JitteredLeapfrog{FT<:AbstractFloat, T<:Union{AbstractArray{FT<:AbstractFloat, 1}, FT<:AbstractFloat}} <: AdvancedHMC.AbstractLeapfrog{T<:Union{AbstractArray{FT<:AbstractFloat, 1}, FT<:AbstractFloat}}

Leapfrog integrator with randomly "jittered" step size ϵ for every trajectory.

Fields

  • ϵ0::Union{AbstractVector{FT}, FT} where FT<:AbstractFloat: Nominal (non-jittered) step size.

  • jitter::AbstractFloat: The proportion of the nominal step size ϵ0 that may be added or subtracted.

  • ϵ::Union{AbstractVector{FT}, FT} where FT<:AbstractFloat: Current (jittered) step size.

Description

This is the same as LeapFrog(@ref) but with a "jittered" step size. This means that at the beginning of each trajectory we sample a step size ϵ by adding or subtracting from the nominal/base step size ϵ0 some random proportion of ϵ0, with the proportion specified by jitter, i.e. ϵ = ϵ0 - jitter * ϵ0 * rand(). p Jittering might help alleviate issues related to poor interactions with a fixed step size:

  • In regions with high "curvature" the current choice of step size might mean over-shoot leading to almost all steps being rejected. Randomly sampling the step size at the beginning of the trajectories can therefore increase the probability of escaping such high-curvature regions.
  • Exact periodicity of the simulated trajectories might occur, i.e. you might be so unlucky as to simulate the trajectory forwards in time L ϵ and ending up at the same point (which results in non-ergodicity; see Section 3.2 in [1]). If momentum is refreshed before each trajectory, then this should not happen exactly but it can still be an issue in practice. Randomly choosing the step-size ϵ might help alleviate such problems.

References

  1. Neal, R. M. (2011). MCMC using Hamiltonian dynamics. Handbook of Markov chain Monte Carlo, 2(11), 2. (arXiv)
source
AdvancedHMC.Leapfrog — Type
struct Leapfrog{T<:(Union{AbstractVector{var"#s26"}, var"#s26"} where var"#s26"<:AbstractFloat)} <: AdvancedHMC.AbstractLeapfrog{T<:(Union{AbstractVector{var"#s26"}, var"#s26"} where var"#s26"<:AbstractFloat)}

Leapfrog integrator with fixed step size ϵ.

Fields

  • ϵ::Union{AbstractVector{var"#s26"}, var"#s26"} where var"#s26"<:AbstractFloat: Step size.
source
AdvancedHMC.MultinomialTS — Method
struct MultinomialTS{F<:AbstractFloat} <: AdvancedHMC.AbstractTrajectorySampler

Multinomial sampler for a trajectory consisting only a leaf node.

  • tree weight is the (unnormalised) energy of the leaf.
source
AdvancedHMC.MultinomialTS — Method
struct MultinomialTS{F<:AbstractFloat} <: AdvancedHMC.AbstractTrajectorySampler

Multinomial sampler for the starting single leaf tree. (Log) weights for leaf nodes are their (unnormalised) Hamiltonian energies.

Ref: https://github.com/stan-dev/stan/blob/develop/src/stan/mcmc/hmc/nuts/base_nuts.hpp#L226

source
AdvancedHMC.MultinomialTS — Type
struct MultinomialTS{F<:AbstractFloat} <: AdvancedHMC.AbstractTrajectorySampler

Multinomial trajectory sampler carried during the building of the tree. It contains the weight of the tree, defined as the total probabilities of the leaves.

Fields

  • zcand::AdvancedHMC.PhasePoint: Sampled candidate PhasePoint.

  • ℓw::AbstractFloat: Total energy for the given tree, i.e. the sum of energies of all leaves.

source
AdvancedHMC.NUTS — Type
NUTS(δ::Real; max_depth::Int=10, Δ_max::Real=1000, integrator = :leapfrog, metric = :diagonal)

No-U-Turn Sampler (NUTS) sampler.

Fields

  • δ: Target acceptance rate for dual averaging.

  • max_depth: Maximum doubling tree depth.

  • Δ_max: Maximum divergence during doubling tree.

  • integrator: Choice of integrator, specified either using a Symbol or AbstractIntegrator

  • metric: Choice of initial metric; Symbol means it is automatically initialised. The metric type will be preserved during automatic initialisation and adaption.

source
AdvancedHMC.PartialMomentumRefreshment — Type
struct PartialMomentumRefreshment{F<:AbstractFloat} <: AdvancedHMC.AbstractMomentumRefreshment

Partial momentum refreshment with refresh rate α.

Fields

  • α::AbstractFloat

See equation (5.19) [1]

r' = α⋅r + sqrt(1-α²)⋅G

where r is the momentum and G is a Gaussian random variable.

References

  1. Neal, Radford M. "MCMC using Hamiltonian dynamics." Handbook of markov chain monte carlo 2.11 (2011): 2.
source
AdvancedHMC.SliceTS — Method
struct SliceTS{F<:AbstractFloat} <: AdvancedHMC.AbstractTrajectorySampler

Slice sampler for the starting single leaf tree. Slice variable is initialized.

source
AdvancedHMC.SliceTS — Method
struct SliceTS{F<:AbstractFloat} <: AdvancedHMC.AbstractTrajectorySampler

Create a slice sampler for a single leaf tree:

  • the slice variable is copied from the passed-in sampler s and
  • the number of acceptable candicates is computed by comparing the slice variable against the current energy.
source
AdvancedHMC.SliceTS — Type
struct SliceTS{F<:AbstractFloat} <: AdvancedHMC.AbstractTrajectorySampler

Trajectory slice sampler carried during the building of the tree. It contains the slice variable and the number of acceptable condidates in the tree.

Fields

  • zcand::AdvancedHMC.PhasePoint: Sampled candidate PhasePoint.

  • ℓu::AbstractFloat: Slice variable in log-space.

  • n::Int64: Number of acceptable candidates, i.e. those with probability larger than slice variable u.

source
AdvancedHMC.TemperedLeapfrog — Type
struct TemperedLeapfrog{FT<:AbstractFloat, T<:Union{AbstractArray{FT<:AbstractFloat, 1}, FT<:AbstractFloat}} <: AdvancedHMC.AbstractLeapfrog{T<:Union{AbstractArray{FT<:AbstractFloat, 1}, FT<:AbstractFloat}}

Tempered leapfrog integrator with fixed step size ϵ and "temperature" α.

Fields

  • ϵ::Union{AbstractVector{FT}, FT} where FT<:AbstractFloat: Step size.

  • α::AbstractFloat: Temperature parameter.

Description

Tempering can potentially allow greater exploration of the posterior, e.g. in a multi-modal posterior jumps between the modes can be more likely to occur.

source
AdvancedHMC.Termination — Type
Termination

Termination reasons

  • dynamic: due to stoping criteria
  • numerical: due to large energy deviation from starting (possibly numerical errors)
source
AdvancedHMC.Trajectory — Type
struct Trajectory{TS<:AdvancedHMC.AbstractTrajectorySampler, I<:AdvancedHMC.AbstractIntegrator, TC<:AdvancedHMC.AbstractTerminationCriterion}

Numerically simulated Hamiltonian trajectories.

source
AdvancedHMC.Transition — Type
struct Transition{P<:AdvancedHMC.PhasePoint, NT<:NamedTuple}

A transition that contains the phase point and other statistics of the transition.

Fields

  • z::AdvancedHMC.PhasePoint: Phase-point for the transition.

  • stat::NamedTuple: Statistics related to the transition, e.g. energy.

source
AdvancedHMC.Adaptation.NesterovDualAveraging — Type

An implementation of the Nesterov dual averaging algorithm to tune step size.

References

Hoffman, M. D., & Gelman, A. (2014). The No-U-Turn Sampler: adaptively setting path lengths in Hamiltonian Monte Carlo. Journal of Machine Learning Research, 15(1), 1593-1623. Nesterov, Y. (2009). Primal-dual subgradient methods for convex problems. Mathematical programming, 120(1), 221-259.

source
diff --git a/previews/PR393/index.html b/previews/PR393/index.html index a4d0939c..6c90a6bd 100644 --- a/previews/PR393/index.html +++ b/previews/PR393/index.html @@ -576,7 +576,7 @@ drop_warmup=false, verbose::Bool=true, progress::Bool=false, -)

Draw n_samples samples using the kernel κ under the Hamiltonian system h

Note that the function signature of the sample function exported by AdvancedHMC.jl differs from the sample function used by Turing.jl. We refer to the documentation of Turing.jl for more details on the latter.

Citing AdvancedHMC.jl

If you use AdvancedHMC.jl for your own research, please consider citing the following publication:

Kai Xu, Hong Ge, Will Tebbutt, Mohamed Tarek, Martin Trapp, Zoubin Ghahramani: "AdvancedHMC.jl: A robust, modular and efficient implementation of advanced HMC algorithms.", Symposium on Advances in Approximate Bayesian Inference, 2020. (abs, pdf)

with the following BibTeX entry:

@inproceedings{xu2020advancedhmc,
+)

Draw n_samples samples using the kernel κ under the Hamiltonian system h

Note that the function signature of the sample function exported by AdvancedHMC.jl differs from the sample function used by Turing.jl. We refer to the documentation of Turing.jl for more details on the latter.

Citing AdvancedHMC.jl

If you use AdvancedHMC.jl for your own research, please consider citing the following publication:

Kai Xu, Hong Ge, Will Tebbutt, Mohamed Tarek, Martin Trapp, Zoubin Ghahramani: "AdvancedHMC.jl: A robust, modular and efficient implementation of advanced HMC algorithms.", Symposium on Advances in Approximate Bayesian Inference, 2020. (abs, pdf)

with the following BibTeX entry:

@inproceedings{xu2020advancedhmc,
   title={AdvancedHMC. jl: A robust, modular and efficient implementation of advanced HMC algorithms},
   author={Xu, Kai and Ge, Hong and Tebbutt, Will and Tarek, Mohamed and Trapp, Martin and Ghahramani, Zoubin},
   booktitle={Symposium on Advances in Approximate Bayesian Inference},
@@ -590,4 +590,4 @@
   pages={1682--1690},
   year={2018},
   organization={PMLR}
-}

References

  1. Neal, R. M. (2011). MCMC using Hamiltonian dynamics. Handbook of Markov chain Monte Carlo, 2(11), 2. (arXiv)

  2. Betancourt, M. (2017). A Conceptual Introduction to Hamiltonian Monte Carlo. arXiv preprint arXiv:1701.02434.

  3. Girolami, M., & Calderhead, B. (2011). Riemann manifold Langevin and Hamiltonian Monte Carlo methods. Journal of the Royal Statistical Society: Series B (Statistical Methodology), 73(2), 123-214. (arXiv)

  4. Betancourt, M. J., Byrne, S., & Girolami, M. (2014). Optimizing the integrator step size for Hamiltonian Monte Carlo. arXiv preprint arXiv:1411.6669.

  5. Betancourt, M. (2016). Identifying the optimal integration time in Hamiltonian Monte Carlo. arXiv preprint arXiv:1601.00225.

  6. Hoffman, M. D., & Gelman, A. (2014). The No-U-Turn Sampler: adaptively setting path lengths in Hamiltonian Monte Carlo. Journal of Machine Learning Research, 15(1), 1593-1623. (arXiv)

Footnotes

+}

References

  1. Neal, R. M. (2011). MCMC using Hamiltonian dynamics. Handbook of Markov chain Monte Carlo, 2(11), 2. (arXiv)

  2. Betancourt, M. (2017). A Conceptual Introduction to Hamiltonian Monte Carlo. arXiv preprint arXiv:1701.02434.

  3. Girolami, M., & Calderhead, B. (2011). Riemann manifold Langevin and Hamiltonian Monte Carlo methods. Journal of the Royal Statistical Society: Series B (Statistical Methodology), 73(2), 123-214. (arXiv)

  4. Betancourt, M. J., Byrne, S., & Girolami, M. (2014). Optimizing the integrator step size for Hamiltonian Monte Carlo. arXiv preprint arXiv:1411.6669.

  5. Betancourt, M. (2016). Identifying the optimal integration time in Hamiltonian Monte Carlo. arXiv preprint arXiv:1601.00225.

  6. Hoffman, M. D., & Gelman, A. (2014). The No-U-Turn Sampler: adaptively setting path lengths in Hamiltonian Monte Carlo. Journal of Machine Learning Research, 15(1), 1593-1623. (arXiv)

Footnotes

diff --git a/previews/PR393/search_index.js b/previews/PR393/search_index.js index 6acb6a19..f0eff37e 100644 --- a/previews/PR393/search_index.js +++ b/previews/PR393/search_index.js @@ -1,3 +1,3 @@ var documenterSearchIndex = {"docs": -[{"location":"api/#AdvancedHMC.jl","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"","category":"section"},{"location":"api/","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"Documentation for AdvancedHMC.jl","category":"page"},{"location":"api/","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"","category":"page"},{"location":"api/#Types","page":"AdvancedHMC.jl","title":"Types","text":"","category":"section"},{"location":"api/","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"ClassicNoUTurn\nHMCSampler\nHMC\nNUTS\nHMCDA","category":"page"},{"location":"api/#AdvancedHMC.ClassicNoUTurn","page":"AdvancedHMC.jl","title":"AdvancedHMC.ClassicNoUTurn","text":"struct ClassicNoUTurn{F<:AbstractFloat} <: AdvancedHMC.DynamicTerminationCriterion\n\nClassic No-U-Turn criterion as described in Eq. (9) in [1].\n\nInformally, this will terminate the trajectory expansion if continuing the simulation either forwards or backwards in time will decrease the distance between the left-most and right-most positions.\n\nFields\n\nmax_depth::Int64\nΔ_max::AbstractFloat\n\nReferences\n\nHoffman, M. D., & Gelman, A. (2014). The No-U-Turn Sampler: adaptively setting path lengths in Hamiltonian Monte Carlo. Journal of Machine Learning Research, 15(1), 1593-1623. (arXiv)\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.HMCSampler","page":"AdvancedHMC.jl","title":"AdvancedHMC.HMCSampler","text":"HMCSampler\n\nAn AbstractMCMC.AbstractSampler for kernels in AdvancedHMC.jl.\n\nFields\n\nκ: AbstractMCMCKernel.\nmetric: Choice of initial metric AbstractMetric. The metric type will be preserved during adaption.\nadaptor: AdvancedHMC.Adaptation.AbstractAdaptor.\n\nNotes\n\nNote that all the fields have the prefix initial_ to indicate that these will not necessarily correspond to the kernel, metric, and adaptor after sampling.\n\nTo access the updated fields, use the resulting HMCState.\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.HMC","page":"AdvancedHMC.jl","title":"AdvancedHMC.HMC","text":"HMC(ϵ::Real, n_leapfrog::Int)\n\nHamiltonian Monte Carlo sampler with static trajectory.\n\nFields\n\nn_leapfrog: Number of leapfrog steps.\nintegrator: Choice of integrator, specified either using a Symbol or AbstractIntegrator\nmetric: Choice of initial metric; Symbol means it is automatically initialised. The metric type will be preserved during automatic initialisation and adaption.\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.NUTS","page":"AdvancedHMC.jl","title":"AdvancedHMC.NUTS","text":"NUTS(δ::Real; max_depth::Int=10, Δ_max::Real=1000, integrator = :leapfrog, metric = :diagonal)\n\nNo-U-Turn Sampler (NUTS) sampler.\n\nFields\n\nδ: Target acceptance rate for dual averaging.\nmax_depth: Maximum doubling tree depth.\nΔ_max: Maximum divergence during doubling tree.\nintegrator: Choice of integrator, specified either using a Symbol or AbstractIntegrator\nmetric: Choice of initial metric; Symbol means it is automatically initialised. The metric type will be preserved during automatic initialisation and adaption.\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.HMCDA","page":"AdvancedHMC.jl","title":"AdvancedHMC.HMCDA","text":"HMCDA(δ::Real, λ::Real, integrator = :leapfrog, metric = :diagonal)\n\nHamiltonian Monte Carlo sampler with Dual Averaging algorithm.\n\nFields\n\nδ: Target acceptance rate for dual averaging.\nλ: Target leapfrog length.\nintegrator: Choice of integrator, specified either using a Symbol or AbstractIntegrator\nmetric: Choice of initial metric; Symbol means it is automatically initialised. The metric type will be preserved during automatic initialisation and adaption.\n\nNotes\n\nFor more information, please view the following paper (arXiv link):\n\nHoffman, Matthew D., and Andrew Gelman. \"The No-U-turn sampler: adaptively setting path lengths in Hamiltonian Monte Carlo.\" Journal of Machine Learning Research 15, no. 1 (2014): 1593-1623.\n\n\n\n\n\n","category":"type"},{"location":"api/#Functions","page":"AdvancedHMC.jl","title":"Functions","text":"","category":"section"},{"location":"api/","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"sample","category":"page"},{"location":"api/#StatsBase.sample","page":"AdvancedHMC.jl","title":"StatsBase.sample","text":"sample([rng], a::AbstractArray, [wv::AbstractWeights])\n\nSelect a single random element of a. Sampling probabilities are proportional to the weights given in wv, if provided.\n\nOptionally specify a random number generator rng as the first argument (defaults to Random.default_rng()).\n\n\n\n\n\nsample([rng], a, [wv::AbstractWeights], n::Integer; replace=true, ordered=false)\n\nSelect a random, optionally weighted sample of size n from an array a using a polyalgorithm. Sampling probabilities are proportional to the weights given in wv, if provided. replace dictates whether sampling is performed with replacement. ordered dictates whether an ordered sample (also called a sequential sample, i.e. a sample where items appear in the same order as in a) should be taken.\n\nOptionally specify a random number generator rng as the first argument (defaults to Random.default_rng()).\n\n\n\n\n\nsample([rng], a, [wv::AbstractWeights], dims::Dims; replace=true, ordered=false)\n\nSelect a random, optionally weighted sample from an array a specifying the dimensions dims of the output array. Sampling probabilities are proportional to the weights given in wv, if provided. replace dictates whether sampling is performed with replacement. ordered dictates whether an ordered sample (also called a sequential sample, i.e. a sample where items appear in the same order as in a) should be taken.\n\nOptionally specify a random number generator rng as the first argument (defaults to Random.default_rng()).\n\n\n\n\n\nsample([rng], wv::AbstractWeights)\n\nSelect a single random integer in 1:length(wv) with probabilities proportional to the weights given in wv.\n\nOptionally specify a random number generator rng as the first argument (defaults to Random.default_rng()).\n\n\n\n\n\nsample(\n rng::Random.AbatractRNG=Random.default_rng(),\n model::AbstractModel,\n sampler::AbstractSampler,\n N_or_isdone;\n kwargs...,\n)\n\nSample from the model with the Markov chain Monte Carlo sampler and return the samples.\n\nIf N_or_isdone is an Integer, exactly N_or_isdone samples are returned.\n\nOtherwise, sampling is performed until a convergence criterion N_or_isdone returns true. The convergence criterion has to be a function with the signature\n\nisdone(rng, model, sampler, samples, state, iteration; kwargs...)\n\nwhere state and iteration are the current state and iteration of the sampler, respectively. It should return true when sampling should end, and false otherwise.\n\nKeyword arguments\n\nSee https://turinglang.org/AbstractMCMC.jl/dev/api/#Common-keyword-arguments for common keyword arguments.\n\n\n\n\n\nsample(\n rng::Random.AbstractRNG=Random.default_rng(),\n model::AbstractModel,\n sampler::AbstractSampler,\n parallel::AbstractMCMCEnsemble,\n N::Integer,\n nchains::Integer;\n kwargs...,\n)\n\nSample nchains Monte Carlo Markov chains from the model with the sampler in parallel using the parallel algorithm, and combine them into a single chain.\n\nKeyword arguments\n\nSee https://turinglang.org/AbstractMCMC.jl/dev/api/#Common-keyword-arguments for common keyword arguments.\n\n\n\n\n\nsample(\n rng::Random.AbstractRNG=Random.default_rng(),\n logdensity,\n sampler::AbstractSampler,\n N_or_isdone;\n kwargs...,\n)\n\nWrap the logdensity function in a LogDensityModel, and call sample with the resulting model instead of logdensity.\n\nThe logdensity function has to support the LogDensityProblems.jl interface.\n\n\n\n\n\nsample(\n rng::Random.AbstractRNG=Random.default_rng(),\n logdensity,\n sampler::AbstractSampler,\n parallel::AbstractMCMCEnsemble,\n N::Integer,\n nchains::Integer;\n kwargs...,\n)\n\nWrap the logdensity function in a LogDensityModel, and call sample with the resulting model instead of logdensity.\n\nThe logdensity function has to support the LogDensityProblems.jl interface.\n\n\n\n\n\nsample(\n rng::AbstractRNG,\n h::Hamiltonian,\n κ::AbstractMCMCKernel,\n θ::AbstractVecOrMat{T},\n n_samples::Int,\n adaptor::AbstractAdaptor=NoAdaptation(),\n n_adapts::Int=min(div(n_samples, 10), 1_000);\n drop_warmup::Bool=false,\n verbose::Bool=true,\n progress::Bool=false\n)\n\nSample n_samples samples using the proposal κ under Hamiltonian h.\n\nThe randomness is controlled by rng. \nIf rng is not provided, GLOBAL_RNG will be used.\nThe initial point is given by θ.\nThe adaptor is set by adaptor, for which the default is no adaptation.\nIt will perform n_adapts steps of adaptation, for which the default is the minimum of 1_000 and 10% of n_samples\ndrop_warmup controls to drop the samples during adaptation phase or not\nverbose controls the verbosity\nprogress controls whether to show the progress meter or not\n\n\n\n\n\n","category":"function"},{"location":"api/#More-types","page":"AdvancedHMC.jl","title":"More types","text":"","category":"section"},{"location":"api/","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"Modules = [AdvancedHMC, AdvancedHMC.Adaptation]\nOrder = [:type]","category":"page"},{"location":"api/#AdvancedHMC.AbstractIntegrator-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.AbstractIntegrator","text":"abstract type AbstractIntegrator\n\nRepresents an integrator used to simulate the Hamiltonian system.\n\nImplementation\n\nA AbstractIntegrator is expected to have the following implementations:\n\nstat(@ref)\nnom_step_size(@ref)\nstep_size(@ref)\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.AbstractMCMCKernel-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.AbstractMCMCKernel","text":"abstract type AbstractMCMCKernel\n\nAbstract type for HMC kernels. \n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.AbstractMetric-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.AbstractMetric","text":"abstract type AbstractMetric\n\nAbstract type for preconditioning metrics. \n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.AbstractTerminationCriterion-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.AbstractTerminationCriterion","text":"abstract type AbstractTerminationCriterion\n\nAbstract type for termination criteria for Hamiltonian trajectories, e.g. no-U-turn and fixed number of leapfrog integration steps. \n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.AbstractTrajectorySampler-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.AbstractTrajectorySampler","text":"How to sample a phase-point from the simulated trajectory.\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.BinaryTree-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.BinaryTree","text":"A full binary tree trajectory with only necessary leaves and information stored.\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.ClassicNoUTurn-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.ClassicNoUTurn","text":"struct ClassicNoUTurn{F<:AbstractFloat} <: AdvancedHMC.DynamicTerminationCriterion\n\nClassic No-U-Turn criterion as described in Eq. (9) in [1].\n\nInformally, this will terminate the trajectory expansion if continuing the simulation either forwards or backwards in time will decrease the distance between the left-most and right-most positions.\n\nFields\n\nmax_depth::Int64\nΔ_max::AbstractFloat\n\nReferences\n\nHoffman, M. D., & Gelman, A. (2014). The No-U-Turn Sampler: adaptively setting path lengths in Hamiltonian Monte Carlo. Journal of Machine Learning Research, 15(1), 1593-1623. (arXiv)\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.DynamicTerminationCriterion-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.DynamicTerminationCriterion","text":"abstract type DynamicTerminationCriterion <: AdvancedHMC.AbstractTerminationCriterion\n\nAbstract type for dynamic Hamiltonian trajectory termination criteria. \n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.EndPointTS-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.EndPointTS","text":"Samples the end-point of the trajectory.\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.FixedIntegrationTime-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.FixedIntegrationTime","text":"struct FixedIntegrationTime{F<:AbstractFloat} <: AdvancedHMC.StaticTerminationCriterion\n\nStandard HMC implementation with a fixed integration time.\n\nFields\n\nλ::AbstractFloat: Total length of the trajectory, i.e. take floor(λ / integrator_step_size) number of leapfrog steps.\n\nReferences\n\nNeal, R. M. (2011). MCMC using Hamiltonian dynamics. Handbook of Markov chain Monte Carlo, 2(11), 2. (arXiv) \n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.FixedNSteps-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.FixedNSteps","text":"struct FixedNSteps <: AdvancedHMC.StaticTerminationCriterion\n\nStatic HMC with a fixed number of leapfrog steps.\n\nFields\n\nL::Int64: Number of steps to simulate, i.e. length of trajectory will be L + 1.\n\nReferences\n\nNeal, R. M. (2011). MCMC using Hamiltonian dynamics. Handbook of Markov chain Monte Carlo, 2(11), 2. (arXiv)\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.FullMomentumRefreshment-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.FullMomentumRefreshment","text":"Completly resample new momentum.\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.GeneralisedNoUTurn-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.GeneralisedNoUTurn","text":"struct GeneralisedNoUTurn{F<:AbstractFloat} <: AdvancedHMC.DynamicTerminationCriterion\n\nGeneralised No-U-Turn criterion as described in Section A.4.2 in [1].\n\nFields\n\nmax_depth::Int64\nΔ_max::AbstractFloat\n\nReferences\n\nBetancourt, M. (2017). A Conceptual Introduction to Hamiltonian Monte Carlo. arXiv preprint arXiv:1701.02434.\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.GeneralizedLeapfrog-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.GeneralizedLeapfrog","text":"struct GeneralizedLeapfrog{T<:(Union{AbstractVector{var\"#s17\"}, var\"#s17\"} where var\"#s17\"<:AbstractFloat)} <: AdvancedHMC.AbstractLeapfrog{T<:(Union{AbstractVector{var\"#s17\"}, var\"#s17\"} where var\"#s17\"<:AbstractFloat)}\n\nGeneralized leapfrog integrator with fixed step size ϵ.\n\nFields\n\nϵ::Union{AbstractVector{var\"#s17\"}, var\"#s17\"} where var\"#s17\"<:AbstractFloat: Step size.\nn::Int64\n\nReferences\n\nGirolami, Mark, and Ben Calderhead. \"Riemann manifold Langevin and Hamiltonian Monte Carlo methods.\" Journal of the Royal Statistical Society Series B: Statistical Methodology 73, no. 2 (2011): 123-214.\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.HMC-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.HMC","text":"HMC(ϵ::Real, n_leapfrog::Int)\n\nHamiltonian Monte Carlo sampler with static trajectory.\n\nFields\n\nn_leapfrog: Number of leapfrog steps.\nintegrator: Choice of integrator, specified either using a Symbol or AbstractIntegrator\nmetric: Choice of initial metric; Symbol means it is automatically initialised. The metric type will be preserved during automatic initialisation and adaption.\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.HMCDA-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.HMCDA","text":"HMCDA(δ::Real, λ::Real, integrator = :leapfrog, metric = :diagonal)\n\nHamiltonian Monte Carlo sampler with Dual Averaging algorithm.\n\nFields\n\nδ: Target acceptance rate for dual averaging.\nλ: Target leapfrog length.\nintegrator: Choice of integrator, specified either using a Symbol or AbstractIntegrator\nmetric: Choice of initial metric; Symbol means it is automatically initialised. The metric type will be preserved during automatic initialisation and adaption.\n\nNotes\n\nFor more information, please view the following paper (arXiv link):\n\nHoffman, Matthew D., and Andrew Gelman. \"The No-U-turn sampler: adaptively setting path lengths in Hamiltonian Monte Carlo.\" Journal of Machine Learning Research 15, no. 1 (2014): 1593-1623.\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.HMCProgressCallback-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.HMCProgressCallback","text":"HMCProgressCallback\n\nA callback to be used with AbstractMCMC.jl's interface, replicating the logging behavior of the non-AbstractMCMC sample.\n\nFields\n\npm: Progress meter from ProgressMeters.jl.\nprogress: Specifies whether or not to use display a progress bar.\nverbose: If progress is not specified and this is true some information will be logged upon completion of adaptation.\nnum_divergent_transitions: Number of divergent transitions fo far.\nnum_divergent_transitions_during_adaption\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.HMCSampler-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.HMCSampler","text":"HMCSampler\n\nAn AbstractMCMC.AbstractSampler for kernels in AdvancedHMC.jl.\n\nFields\n\nκ: AbstractMCMCKernel.\nmetric: Choice of initial metric AbstractMetric. The metric type will be preserved during adaption.\nadaptor: AdvancedHMC.Adaptation.AbstractAdaptor.\n\nNotes\n\nNote that all the fields have the prefix initial_ to indicate that these will not necessarily correspond to the kernel, metric, and adaptor after sampling.\n\nTo access the updated fields, use the resulting HMCState.\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.HMCState-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.HMCState","text":"HMCState\n\nRepresents the state of a HMCSampler.\n\nFields\n\ni: Index of current iteration.\ntransition: Current Transition.\nmetric: Current AbstractMetric, possibly adapted.\nκ: Current AbstractMCMCKernel.\nadaptor: Current AbstractAdaptor.\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.JitteredLeapfrog-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.JitteredLeapfrog","text":"struct JitteredLeapfrog{FT<:AbstractFloat, T<:Union{AbstractArray{FT<:AbstractFloat, 1}, FT<:AbstractFloat}} <: AdvancedHMC.AbstractLeapfrog{T<:Union{AbstractArray{FT<:AbstractFloat, 1}, FT<:AbstractFloat}}\n\nLeapfrog integrator with randomly \"jittered\" step size ϵ for every trajectory.\n\nFields\n\nϵ0::Union{AbstractVector{FT}, FT} where FT<:AbstractFloat: Nominal (non-jittered) step size.\njitter::AbstractFloat: The proportion of the nominal step size ϵ0 that may be added or subtracted.\nϵ::Union{AbstractVector{FT}, FT} where FT<:AbstractFloat: Current (jittered) step size.\n\nDescription\n\nThis is the same as LeapFrog(@ref) but with a \"jittered\" step size. This means that at the beginning of each trajectory we sample a step size ϵ by adding or subtracting from the nominal/base step size ϵ0 some random proportion of ϵ0, with the proportion specified by jitter, i.e. ϵ = ϵ0 - jitter * ϵ0 * rand(). p Jittering might help alleviate issues related to poor interactions with a fixed step size:\n\nIn regions with high \"curvature\" the current choice of step size might mean over-shoot leading to almost all steps being rejected. Randomly sampling the step size at the beginning of the trajectories can therefore increase the probability of escaping such high-curvature regions.\nExact periodicity of the simulated trajectories might occur, i.e. you might be so unlucky as to simulate the trajectory forwards in time L ϵ and ending up at the same point (which results in non-ergodicity; see Section 3.2 in [1]). If momentum is refreshed before each trajectory, then this should not happen exactly but it can still be an issue in practice. Randomly choosing the step-size ϵ might help alleviate such problems.\n\nReferences\n\nNeal, R. M. (2011). MCMC using Hamiltonian dynamics. Handbook of Markov chain Monte Carlo, 2(11), 2. (arXiv)\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.Leapfrog-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.Leapfrog","text":"struct Leapfrog{T<:(Union{AbstractVector{var\"#s26\"}, var\"#s26\"} where var\"#s26\"<:AbstractFloat)} <: AdvancedHMC.AbstractLeapfrog{T<:(Union{AbstractVector{var\"#s26\"}, var\"#s26\"} where var\"#s26\"<:AbstractFloat)}\n\nLeapfrog integrator with fixed step size ϵ.\n\nFields\n\nϵ::Union{AbstractVector{var\"#s26\"}, var\"#s26\"} where var\"#s26\"<:AbstractFloat: Step size.\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.MultinomialTS-Tuple{MultinomialTS, AbstractFloat, AdvancedHMC.PhasePoint}-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.MultinomialTS","text":"struct MultinomialTS{F<:AbstractFloat} <: AdvancedHMC.AbstractTrajectorySampler\n\nMultinomial sampler for a trajectory consisting only a leaf node.\n\ntree weight is the (unnormalised) energy of the leaf.\n\n\n\n\n\n","category":"method"},{"location":"api/#AdvancedHMC.MultinomialTS-Tuple{Random.AbstractRNG, AdvancedHMC.PhasePoint}-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.MultinomialTS","text":"struct MultinomialTS{F<:AbstractFloat} <: AdvancedHMC.AbstractTrajectorySampler\n\nMultinomial sampler for the starting single leaf tree. (Log) weights for leaf nodes are their (unnormalised) Hamiltonian energies.\n\nRef: https://github.com/stan-dev/stan/blob/develop/src/stan/mcmc/hmc/nuts/base_nuts.hpp#L226\n\n\n\n\n\n","category":"method"},{"location":"api/#AdvancedHMC.MultinomialTS-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.MultinomialTS","text":"struct MultinomialTS{F<:AbstractFloat} <: AdvancedHMC.AbstractTrajectorySampler\n\nMultinomial trajectory sampler carried during the building of the tree. It contains the weight of the tree, defined as the total probabilities of the leaves.\n\nFields\n\nzcand::AdvancedHMC.PhasePoint: Sampled candidate PhasePoint.\nℓw::AbstractFloat: Total energy for the given tree, i.e. the sum of energies of all leaves.\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.NUTS-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.NUTS","text":"NUTS(δ::Real; max_depth::Int=10, Δ_max::Real=1000, integrator = :leapfrog, metric = :diagonal)\n\nNo-U-Turn Sampler (NUTS) sampler.\n\nFields\n\nδ: Target acceptance rate for dual averaging.\nmax_depth: Maximum doubling tree depth.\nΔ_max: Maximum divergence during doubling tree.\nintegrator: Choice of integrator, specified either using a Symbol or AbstractIntegrator\nmetric: Choice of initial metric; Symbol means it is automatically initialised. The metric type will be preserved during automatic initialisation and adaption.\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.PartialMomentumRefreshment-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.PartialMomentumRefreshment","text":"struct PartialMomentumRefreshment{F<:AbstractFloat} <: AdvancedHMC.AbstractMomentumRefreshment\n\nPartial momentum refreshment with refresh rate α.\n\nFields\n\nα::AbstractFloat\n\nSee equation (5.19) [1]\n\nr' = α⋅r + sqrt(1-α²)⋅G\n\nwhere r is the momentum and G is a Gaussian random variable.\n\nReferences\n\nNeal, Radford M. \"MCMC using Hamiltonian dynamics.\" Handbook of markov chain monte carlo 2.11 (2011): 2.\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.SliceTS-Tuple{Random.AbstractRNG, AdvancedHMC.PhasePoint}-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.SliceTS","text":"struct SliceTS{F<:AbstractFloat} <: AdvancedHMC.AbstractTrajectorySampler\n\nSlice sampler for the starting single leaf tree. Slice variable is initialized.\n\n\n\n\n\n","category":"method"},{"location":"api/#AdvancedHMC.SliceTS-Tuple{SliceTS, AbstractFloat, AdvancedHMC.PhasePoint}-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.SliceTS","text":"struct SliceTS{F<:AbstractFloat} <: AdvancedHMC.AbstractTrajectorySampler\n\nCreate a slice sampler for a single leaf tree:\n\nthe slice variable is copied from the passed-in sampler s and\nthe number of acceptable candicates is computed by comparing the slice variable against the current energy.\n\n\n\n\n\n","category":"method"},{"location":"api/#AdvancedHMC.SliceTS-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.SliceTS","text":"struct SliceTS{F<:AbstractFloat} <: AdvancedHMC.AbstractTrajectorySampler\n\nTrajectory slice sampler carried during the building of the tree. It contains the slice variable and the number of acceptable condidates in the tree.\n\nFields\n\nzcand::AdvancedHMC.PhasePoint: Sampled candidate PhasePoint.\nℓu::AbstractFloat: Slice variable in log-space.\nn::Int64: Number of acceptable candidates, i.e. those with probability larger than slice variable u.\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.StaticTerminationCriterion-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.StaticTerminationCriterion","text":"abstract type StaticTerminationCriterion <: AdvancedHMC.AbstractTerminationCriterion\n\nAbstract type for a fixed number of leapfrog integration steps.\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.StrictGeneralisedNoUTurn-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.StrictGeneralisedNoUTurn","text":"struct StrictGeneralisedNoUTurn{F<:AbstractFloat} <: AdvancedHMC.DynamicTerminationCriterion\n\nGeneralised No-U-Turn criterion as described in Section A.4.2 in [1] with added U-turn check as described in [2].\n\nFields\n\nmax_depth::Int64\nΔ_max::AbstractFloat\n\nReferences\n\nBetancourt, M. (2017). A Conceptual Introduction to Hamiltonian Monte Carlo. arXiv preprint arXiv:1701.02434.\nhttps://github.com/stan-dev/stan/pull/2800\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.TemperedLeapfrog-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.TemperedLeapfrog","text":"struct TemperedLeapfrog{FT<:AbstractFloat, T<:Union{AbstractArray{FT<:AbstractFloat, 1}, FT<:AbstractFloat}} <: AdvancedHMC.AbstractLeapfrog{T<:Union{AbstractArray{FT<:AbstractFloat, 1}, FT<:AbstractFloat}}\n\nTempered leapfrog integrator with fixed step size ϵ and \"temperature\" α.\n\nFields\n\nϵ::Union{AbstractVector{FT}, FT} where FT<:AbstractFloat: Step size.\nα::AbstractFloat: Temperature parameter.\n\nDescription\n\nTempering can potentially allow greater exploration of the posterior, e.g. in a multi-modal posterior jumps between the modes can be more likely to occur.\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.Termination-Union{Tuple{F}, Tuple{MultinomialTS, Trajectory, F, F}} where F<:AbstractFloat-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.Termination","text":"Termination(s, nt, H0, H′)\n\n\nCheck termination of a Hamiltonian trajectory.\n\n\n\n\n\n","category":"method"},{"location":"api/#AdvancedHMC.Termination-Union{Tuple{F}, Tuple{SliceTS, Trajectory, F, F}} where F<:AbstractFloat-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.Termination","text":"Termination(s, nt, H0, H′)\n\n\nCheck termination of a Hamiltonian trajectory.\n\n\n\n\n\n","category":"method"},{"location":"api/#AdvancedHMC.Termination-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.Termination","text":"Termination\n\nTermination reasons\n\ndynamic: due to stoping criteria\nnumerical: due to large energy deviation from starting (possibly numerical errors)\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.Trajectory-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.Trajectory","text":"struct Trajectory{TS<:AdvancedHMC.AbstractTrajectorySampler, I<:AdvancedHMC.AbstractIntegrator, TC<:AdvancedHMC.AbstractTerminationCriterion}\n\nNumerically simulated Hamiltonian trajectories.\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.Transition-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.Transition","text":"struct Transition{P<:AdvancedHMC.PhasePoint, NT<:NamedTuple}\n\nA transition that contains the phase point and other statistics of the transition.\n\nFields\n\nz::AdvancedHMC.PhasePoint: Phase-point for the transition.\nstat::NamedTuple: Statistics related to the transition, e.g. energy.\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.Adaptation.AbstractAdaptor-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.Adaptation.AbstractAdaptor","text":"abstract type AbstractAdaptor\n\nAbstract type for HMC adaptors. \n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.Adaptation.NesterovDualAveraging-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.Adaptation.NesterovDualAveraging","text":"An implementation of the Nesterov dual averaging algorithm to tune step size.\n\nReferences\n\nHoffman, M. D., & Gelman, A. (2014). The No-U-Turn Sampler: adaptively setting path lengths in Hamiltonian Monte Carlo. Journal of Machine Learning Research, 15(1), 1593-1623. Nesterov, Y. (2009). Primal-dual subgradient methods for convex problems. Mathematical programming, 120(1), 221-259.\n\n\n\n\n\n","category":"type"},{"location":"#AdvancedHMC.jl","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"","category":"section"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"(Image: CI) (Image: DOI) (Image: Coverage Status) (Image: Stable) (Image: Dev)","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"AdvancedHMC.jl provides a robust, modular, and efficient implementation of advanced HMC algorithms. An illustrative example of AdvancedHMC's usage is given below. AdvancedHMC.jl is part of Turing.jl, a probabilistic programming library in Julia. If you are interested in using AdvancedHMC.jl through a probabilistic programming language, please check it out!","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"Interfaces","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"IMP.hmc: an experimental Python module for the Integrative Modeling Platform, which uses AdvancedHMC in its backend to sample protein structures.","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"NEWS","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"We presented a paper for AdvancedHMC.jl at AABI in 2019 in Vancouver, Canada. (abs, pdf, OpenReview)\nWe presented a poster for AdvancedHMC.jl at StanCon 2019 in Cambridge, UK. (pdf)","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"API CHANGES","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"[v0.5.0] Breaking! Convenience constructors for common samplers changed to:\nHMC(leapfrog_stepsize::Real, n_leapfrog::Int)\nNUTS(target_acceptance::Real) \nHMCDA(target_acceptance::Real, integration_time::Real)\n[v0.2.22] Three functions are renamed.\nPreconditioner(metric::AbstractMetric) -> MassMatrixAdaptor(metric) and \nNesterovDualAveraging(δ, integrator::AbstractIntegrator) -> StepSizeAdaptor(δ, integrator)\nfind_good_eps -> find_good_stepsize\n[v0.2.15] n_adapts is no longer needed to construct StanHMCAdaptor; the old constructor is deprecated.\n[v0.2.8] Two Hamiltonian trajectory sampling methods are renamed to avoid a name clash with Distributions.\nMultinomial -> MultinomialTS\nSlice -> SliceTS\n[v0.2.0] The gradient function passed to Hamiltonian is supposed to return a value-gradient tuple now.","category":"page"},{"location":"#A-minimal-example-sampling-from-a-multivariate-Gaussian-using-NUTS","page":"AdvancedHMC.jl","title":"A minimal example - sampling from a multivariate Gaussian using NUTS","text":"","category":"section"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"This section demonstrates a minimal example of sampling from a multivariate Gaussian (10-dimensional) using the no U-turn sampler (NUTS). Below we describe the major components of the Hamiltonian system which are essential to sample using this approach:","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"Metric: In many sampling problems the sample space is associated with a metric that allows us to measure the distance between any two points, and other similar quantities. In the example in this section, we use a special metric called the Euclidean Metric, represented with a D × D matrix from which we can compute distances.[1]\nLeapfrog integration: Leapfrog integration is a second-order numerical method for integrating differential equations (In this case they are equations of motion for the relative position of one particle with respect to the other). The order of this integration signifies its rate of convergence. Any algorithm with a finite time step size will have numerical errors, and the order is related to this error. For a second-order algorithm, this error scales as the second power of the time step, hence, the name second-order. High-order integrators are usually complex to code and have a limited region of convergence; hence they do not allow arbitrarily large time steps. A second-order integrator is suitable for our purpose. Hence we opt for the leapfrog integrator. It is called leapfrog due to the ways this algorithm is written, where the positions and velocities of particles \"leap over\" each other.[2]\nKernel for trajectories (static or dynamic): Different kernels, which may be static or dynamic, can be used. At each iteration of any variant of the HMC algorithm, there are two main steps - the first step changes the momentum and the second step may change both the position and the momentum of a particle.[3]","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"using AdvancedHMC, ForwardDiff\nusing LogDensityProblems\nusing LinearAlgebra\n\n# Define the target distribution using the `LogDensityProblem` interface\nstruct LogTargetDensity\n dim::Int\nend\nLogDensityProblems.logdensity(p::LogTargetDensity, θ) = -sum(abs2, θ) / 2 # standard multivariate normal\nLogDensityProblems.dimension(p::LogTargetDensity) = p.dim\nLogDensityProblems.capabilities(::Type{LogTargetDensity}) = LogDensityProblems.LogDensityOrder{0}()\n\n# Choose parameter dimensionality and initial parameter value\nD = 10; initial_θ = rand(D)\nℓπ = LogTargetDensity(D)\n\n# Set the number of samples to draw and warmup iterations\nn_samples, n_adapts = 2_000, 1_000\n\n# Define a Hamiltonian system\nmetric = DiagEuclideanMetric(D)\nhamiltonian = Hamiltonian(metric, ℓπ, ForwardDiff)\n\n# Define a leapfrog solver, with the initial step size chosen heuristically\ninitial_ϵ = find_good_stepsize(hamiltonian, initial_θ)\nintegrator = Leapfrog(initial_ϵ)\n\n# Define an HMC sampler with the following components\n# - multinomial sampling scheme,\n# - generalised No-U-Turn criteria, and\n# - windowed adaption for step-size and diagonal mass matrix\nkernel = HMCKernel(Trajectory{MultinomialTS}(integrator, GeneralisedNoUTurn()))\nadaptor = StanHMCAdaptor(MassMatrixAdaptor(metric), StepSizeAdaptor(0.8, integrator))\n\n# Run the sampler to draw samples from the specified Gaussian, where\n# - `samples` will store the samples\n# - `stats` will store diagnostic statistics for each sample\nsamples, stats = sample(hamiltonian, kernel, initial_θ, n_samples, adaptor, n_adapts; progress=true)","category":"page"},{"location":"#Parallel-sampling","page":"AdvancedHMC.jl","title":"Parallel sampling","text":"","category":"section"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"AdvancedHMC enables parallel sampling (either distributed or multi-thread) via Julia's parallel computing functions. It also supports vectorized sampling for static HMC.","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"The below example utilizes the @threads macro to sample 4 chains across 4 threads.","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"# Ensure that Julia was launched with an appropriate number of threads\nprintln(Threads.nthreads())\n\n# Number of chains to sample\nnchains = 4\n\n# Cache to store the chains\nchains = Vector{Any}(undef, nchains)\n\n# The `samples` from each parallel chain is stored in the `chains` vector \n# Adjust the `verbose` flag as per need\nThreads.@threads for i in 1:nchains\n samples, stats = sample(hamiltonian, kernel, initial_θ, n_samples, adaptor, n_adapts; verbose=false)\n chains[i] = samples\nend","category":"page"},{"location":"#Using-the-AbstractMCMC-interface","page":"AdvancedHMC.jl","title":"Using the AbstractMCMC interface","text":"","category":"section"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"Users can also use the AbstractMCMC interface to sample, which is also used in Turing.jl. In order to show how this is done let us start from our previous example where we defined a LogTargetDensity, ℓπ.","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"using AbstractMCMC, LogDensityProblemsAD\n# Wrap the previous LogTargetDensity as LogDensityModel \n# where ℓπ::LogTargetDensity\nmodel = AdvancedHMC.LogDensityModel(LogDensityProblemsAD.ADgradient(Val(:ForwardDiff), ℓπ))\n\n# Wrap the previous sampler as a HMCSampler <: AbstractMCMC.AbstractSampler\nD = 10; initial_θ = rand(D)\nn_samples, n_adapts, δ = 1_000, 2_000, 0.8\nsampler = HMCSampler(kernel, metric, adaptor) \n\n# Now sample\nsamples = AbstractMCMC.sample(\n model,\n sampler,\n n_adapts + n_samples;\n n_adapts = n_adapts,\n initial_params = initial_θ,\n )","category":"page"},{"location":"#Convenience-Constructors","page":"AdvancedHMC.jl","title":"Convenience Constructors","text":"","category":"section"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"In the previous examples, we built the sampler by manually specifying the integrator, metric, kernel, and adaptor to build our own sampler. However, in many cases, users might want to initialize a standard NUTS sampler. In such cases having to define each of these aspects manually is tedious and error-prone. For these reasons AdvancedHMC also provides users with a series of convenience constructors for standard samplers. We will now show how to use them.","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"HMC:\n# HMC Sampler\n# step size, number of leapfrog steps \nn_leapfrog, ϵ = 25, 0.1\nhmc = HMC(ϵ, n_leapfrog)\nEquivalent to:\nmetric = DiagEuclideanMetric(D)\nhamiltonian = Hamiltonian(metric, ℓπ, ForwardDiff)\nintegrator = Leapfrog(0.1)\nkernel = HMCKernel(Trajectory{EndPointTS}(integrator, FixedNSteps(n_leapfrog)))\nadaptor = NoAdaptation()\nhmc = HMCSampler(kernel, metric, adaptor)\nNUTS:\n# NUTS Sampler\n# adaptation steps, target acceptance probability,\nδ = 0.8\nnuts = NUTS(δ)\nEquivalent to:\nmetric = DiagEuclideanMetric(D)\nhamiltonian = Hamiltonian(metric, ℓπ, ForwardDiff)\ninitial_ϵ = find_good_stepsize(hamiltonian, initial_θ)\nintegrator = Leapfrog(initial_ϵ)\nkernel = HMCKernel(Trajectory{MultinomialTS}(integrator, GeneralisedNoUTurn()))\nadaptor = StanHMCAdaptor(MassMatrixAdaptor(metric), StepSizeAdaptor(δ, integrator))\nnuts = HMCSampler(kernel, metric, adaptor)","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"HMCDA:\n#HMCDA (dual averaging)\n# adaptation steps, target acceptance probability, target trajectory length \nδ, λ = 0.8, 1.0\nhmcda = HMCDA(δ, λ)\nEquivalent to:\nmetric = DiagEuclideanMetric(D)\nhamiltonian = Hamiltonian(metric, ℓπ, ForwardDiff)\ninitial_ϵ = find_good_stepsize(hamiltonian, initial_θ)\nintegrator = Leapfrog(initial_ϵ)\nkernel = HMCKernel(Trajectory{EndPointTS}(integrator, FixedIntegrationTime(λ)))\nadaptor = StepSizeAdaptor(δ, initial_ϵ)\nhmcda = HMCSampler(kernel, metric, adaptor)","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"Moreover, there's some flexibility in how these samplers can be initialized. For example, a user can initialize a NUTS (HMC and HMCDA) sampler with their own metrics and integrators. This can be done as follows:","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"nuts = NUTS(δ, metric = :diagonal) #metric = DiagEuclideanMetric(D) (Default!)\nnuts = NUTS(δ, metric = :unit) #metric = UnitEuclideanMetric(D)\nnuts = NUTS(δ, metric = :dense) #metric = DenseEuclideanMetric(D)\n# Provide your own AbstractMetric\nmetric = DiagEuclideanMetric(10)\nnuts = NUTS(δ, metric = metric)\n\nnuts = NUTS(δ, integrator = :leapfrog) #integrator = Leapfrog(ϵ) (Default!)\nnuts = NUTS(δ, integrator = :jitteredleapfrog) #integrator = JitteredLeapfrog(ϵ, 0.1ϵ)\nnuts = NUTS(δ, integrator = :temperedleapfrog) #integrator = TemperedLeapfrog(ϵ, 1.0)\n\n# Provide your own AbstractIntegrator\nintegrator = JitteredLeapfrog(0.1, 0.2)\nnuts = NUTS(δ, integrator = integrator) ","category":"page"},{"location":"#GPU-Sampling-with-CUDA","page":"AdvancedHMC.jl","title":"GPU Sampling with CUDA","text":"","category":"section"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"There is experimental support for running static HMC on the GPU using CUDA. To do so, the user needs to have CUDA.jl installed, ensure the logdensity of the Hamiltonian can be executed on the GPU and that the initial points are a CuArray. A small working example can be found at test/cuda.jl.","category":"page"},{"location":"#API-and-supported-HMC-algorithms","page":"AdvancedHMC.jl","title":"API and supported HMC algorithms","text":"","category":"section"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"An important design goal of AdvancedHMC.jl is modularity; we would like to support algorithmic research on HMC. This modularity means that different HMC variants can be easily constructed by composing various components, such as preconditioning metric (i.e., mass matrix), leapfrog integrators, trajectories (static or dynamic), adaption schemes, etc. The minimal example above can be modified to suit particular inference problems by picking components from the list below.","category":"page"},{"location":"#Hamiltonian-mass-matrix-(metric)","page":"AdvancedHMC.jl","title":"Hamiltonian mass matrix (metric)","text":"","category":"section"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"Unit metric: UnitEuclideanMetric(dim)\nDiagonal metric: DiagEuclideanMetric(dim)\nDense metric: DenseEuclideanMetric(dim)","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"where dim is the dimensionality of the sampling space.","category":"page"},{"location":"#Integrator-(integrator)","page":"AdvancedHMC.jl","title":"Integrator (integrator)","text":"","category":"section"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"Ordinary leapfrog integrator: Leapfrog(ϵ)\nJittered leapfrog integrator with jitter rate n: JitteredLeapfrog(ϵ, n)\nTempered leapfrog integrator with tempering rate a: TemperedLeapfrog(ϵ, a)","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"where ϵ is the step size of leapfrog integration.","category":"page"},{"location":"#Kernel-(kernel)","page":"AdvancedHMC.jl","title":"Kernel (kernel)","text":"","category":"section"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"Static HMC with a fixed number of steps (n_steps) (Neal, R. M. (2011)): HMCKernel(Trajectory{EndPointTS}(integrator, FixedNSteps(integrator)))\nHMC with a fixed total trajectory length (trajectory_length) (Neal, R. M. (2011)): HMCKernel(Trajectory{EndPointTS}(integrator, FixedIntegrationTime(trajectory_length))) \nOriginal NUTS with slice sampling (Hoffman, M. D., & Gelman, A. (2014)): HMCKernel(Trajectory{SliceTS}(integrator, ClassicNoUTurn()))\nGeneralised NUTS with slice sampling (Betancourt, M. (2017)): HMCKernel(Trajectory{SliceTS}(integrator, GeneralisedNoUTurn()))\nOriginal NUTS with multinomial sampling (Betancourt, M. (2017)): HMCKernel(Trajectory{MultinomialTS}(integrator, ClassicNoUTurn()))\nGeneralised NUTS with multinomial sampling (Betancourt, M. (2017)): HMCKernel(Trajectory{MultinomialTS}(integrator, GeneralisedNoUTurn()))","category":"page"},{"location":"#Adaptor-(adaptor)","page":"AdvancedHMC.jl","title":"Adaptor (adaptor)","text":"","category":"section"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"Adapt the mass matrix metric of the Hamiltonian dynamics: mma = MassMatrixAdaptor(metric)\nThis is lowered to UnitMassMatrix, WelfordVar or WelfordCov based on the type of the mass matrix metric\nAdapt the step size of the leapfrog integrator integrator: ssa = StepSizeAdaptor(δ, integrator)\nIt uses Nesterov's dual averaging with δ as the target acceptance rate.\nCombine the two above naively: NaiveHMCAdaptor(mma, ssa)\nCombine the first two using Stan's windowed adaptation: StanHMCAdaptor(mma, ssa)","category":"page"},{"location":"#Gradients","page":"AdvancedHMC.jl","title":"Gradients","text":"","category":"section"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"AdvancedHMC supports AD-based using LogDensityProblemsAD and user-specified gradients. In order to use user-specified gradients, please replace ForwardDiff with ℓπ_grad in the Hamiltonian constructor, where the gradient function ℓπ_grad should return a tuple containing both the log-posterior and its gradient. ","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"All the combinations are tested in this file except for using tempered leapfrog integrator together with adaptation, which we found unstable empirically.","category":"page"},{"location":"#The-sample-function-signature-in-detail","page":"AdvancedHMC.jl","title":"The sample function signature in detail","text":"","category":"section"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"function sample(\n rng::Union{AbstractRNG, AbstractVector{<:AbstractRNG}},\n h::Hamiltonian,\n κ::HMCKernel,\n θ::AbstractVector{<:AbstractFloat},\n n_samples::Int,\n adaptor::AbstractAdaptor=NoAdaptation(),\n n_adapts::Int=min(div(n_samples, 10), 1_000);\n drop_warmup=false,\n verbose::Bool=true,\n progress::Bool=false,\n)","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"Draw n_samples samples using the kernel κ under the Hamiltonian system h","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"The randomness is controlled by rng.\nIf rng is not provided, GLOBAL_RNG will be used.\nThe initial point is given by θ.\nThe adaptor is set by adaptor, for which the default is no adaptation.\nIt will perform n_adapts steps of adaptation, for which the default is 1_000 or 10% of n_samples, whichever is lower. \ndrop_warmup specifies whether to drop samples.\nverbose controls the verbosity.\nprogress controls whether to show the progress meter or not.","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"Note that the function signature of the sample function exported by AdvancedHMC.jl differs from the sample function used by Turing.jl. We refer to the documentation of Turing.jl for more details on the latter.","category":"page"},{"location":"#Citing-AdvancedHMC.jl","page":"AdvancedHMC.jl","title":"Citing AdvancedHMC.jl","text":"","category":"section"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"If you use AdvancedHMC.jl for your own research, please consider citing the following publication:","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"Kai Xu, Hong Ge, Will Tebbutt, Mohamed Tarek, Martin Trapp, Zoubin Ghahramani: \"AdvancedHMC.jl: A robust, modular and efficient implementation of advanced HMC algorithms.\", Symposium on Advances in Approximate Bayesian Inference, 2020. (abs, pdf)","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"with the following BibTeX entry:","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"@inproceedings{xu2020advancedhmc,\n title={AdvancedHMC. jl: A robust, modular and efficient implementation of advanced HMC algorithms},\n author={Xu, Kai and Ge, Hong and Tebbutt, Will and Tarek, Mohamed and Trapp, Martin and Ghahramani, Zoubin},\n booktitle={Symposium on Advances in Approximate Bayesian Inference},\n pages={1--10},\n year={2020},\n organization={PMLR}\n}","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"If you using AdvancedHMC.jl directly through Turing.jl, please consider citing the following publication:","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"Hong Ge, Kai Xu, and Zoubin Ghahramani: \"Turing: a language for flexible probabilistic inference.\", International Conference on Artificial Intelligence and Statistics, 2018. (abs, pdf)","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"with the following BibTeX entry:","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"@inproceedings{ge2018turing,\n title={Turing: A language for flexible probabilistic inference},\n author={Ge, Hong and Xu, Kai and Ghahramani, Zoubin},\n booktitle={International Conference on Artificial Intelligence and Statistics},\n pages={1682--1690},\n year={2018},\n organization={PMLR}\n}","category":"page"},{"location":"#References","page":"AdvancedHMC.jl","title":"References","text":"","category":"section"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"Neal, R. M. (2011). MCMC using Hamiltonian dynamics. Handbook of Markov chain Monte Carlo, 2(11), 2. (arXiv)\nBetancourt, M. (2017). A Conceptual Introduction to Hamiltonian Monte Carlo. arXiv preprint arXiv:1701.02434.\nGirolami, M., & Calderhead, B. (2011). Riemann manifold Langevin and Hamiltonian Monte Carlo methods. Journal of the Royal Statistical Society: Series B (Statistical Methodology), 73(2), 123-214. (arXiv)\nBetancourt, M. J., Byrne, S., & Girolami, M. (2014). Optimizing the integrator step size for Hamiltonian Monte Carlo. arXiv preprint arXiv:1411.6669.\nBetancourt, M. (2016). Identifying the optimal integration time in Hamiltonian Monte Carlo. arXiv preprint arXiv:1601.00225.\nHoffman, M. D., & Gelman, A. (2014). The No-U-Turn Sampler: adaptively setting path lengths in Hamiltonian Monte Carlo. Journal of Machine Learning Research, 15(1), 1593-1623. (arXiv)","category":"page"},{"location":"#Footnotes","page":"AdvancedHMC.jl","title":"Footnotes","text":"","category":"section"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"[1]: The Euclidean metric is also known as the mass matrix in the physical perspective. See Hamiltonian mass matrix for available metrics.","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"[2]: About the leapfrog integration scheme: Suppose bf x and bf v are the position and velocity of an individual particle respectively; i and i+1 are the indices for time values t_i and t_i+1 respectively; dt = t_i+1 - t_i is the time step size (constant and regularly spaced intervals), and bf a is the acceleration induced on a particle by the forces of all other particles. Furthermore, suppose positions are defined at times t_i t_i+1 t_i+2 dots spaced at constant intervals dt, the velocities are defined at halfway times in between, denoted by t_i-12 t_i+12 t_i+32 dots where t_i+1 - t_i + 12 = t_i + 12 - t_i = dt 2, and the accelerations bf a are defined only on integer times, just like the positions. Then the leapfrog integration scheme is given as: x_i = x_i-1 + v_i-12 dt quad v_i+12 = v_i-12 + a_i dt. For available integrators refer to Integrator.","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"[3]: On kernels: In the classical HMC approach, during the first step, new values for the momentum variables are randomly drawn from their Gaussian distribution, independently of the current values of the position variables. A Metropolis update is performed during the second step, using Hamiltonian dynamics to provide a new state. For available kernels refer to Kernel.","category":"page"}] +[{"location":"api/#AdvancedHMC.jl","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"","category":"section"},{"location":"api/","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"Documentation for AdvancedHMC.jl","category":"page"},{"location":"api/","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"","category":"page"},{"location":"api/#Types","page":"AdvancedHMC.jl","title":"Types","text":"","category":"section"},{"location":"api/","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"ClassicNoUTurn\nHMCSampler\nHMC\nNUTS\nHMCDA","category":"page"},{"location":"api/#AdvancedHMC.ClassicNoUTurn","page":"AdvancedHMC.jl","title":"AdvancedHMC.ClassicNoUTurn","text":"struct ClassicNoUTurn{F<:AbstractFloat} <: AdvancedHMC.DynamicTerminationCriterion\n\nClassic No-U-Turn criterion as described in Eq. (9) in [1].\n\nInformally, this will terminate the trajectory expansion if continuing the simulation either forwards or backwards in time will decrease the distance between the left-most and right-most positions.\n\nFields\n\nmax_depth::Int64\nΔ_max::AbstractFloat\n\nReferences\n\nHoffman, M. D., & Gelman, A. (2014). The No-U-Turn Sampler: adaptively setting path lengths in Hamiltonian Monte Carlo. Journal of Machine Learning Research, 15(1), 1593-1623. (arXiv)\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.HMCSampler","page":"AdvancedHMC.jl","title":"AdvancedHMC.HMCSampler","text":"HMCSampler\n\nAn AbstractMCMC.AbstractSampler for kernels in AdvancedHMC.jl.\n\nFields\n\nκ: AbstractMCMCKernel.\nmetric: Choice of initial metric AbstractMetric. The metric type will be preserved during adaption.\nadaptor: AdvancedHMC.Adaptation.AbstractAdaptor.\n\nNotes\n\nNote that all the fields have the prefix initial_ to indicate that these will not necessarily correspond to the kernel, metric, and adaptor after sampling.\n\nTo access the updated fields, use the resulting HMCState.\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.HMC","page":"AdvancedHMC.jl","title":"AdvancedHMC.HMC","text":"HMC(ϵ::Real, n_leapfrog::Int)\n\nHamiltonian Monte Carlo sampler with static trajectory.\n\nFields\n\nn_leapfrog: Number of leapfrog steps.\nintegrator: Choice of integrator, specified either using a Symbol or AbstractIntegrator\nmetric: Choice of initial metric; Symbol means it is automatically initialised. The metric type will be preserved during automatic initialisation and adaption.\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.NUTS","page":"AdvancedHMC.jl","title":"AdvancedHMC.NUTS","text":"NUTS(δ::Real; max_depth::Int=10, Δ_max::Real=1000, integrator = :leapfrog, metric = :diagonal)\n\nNo-U-Turn Sampler (NUTS) sampler.\n\nFields\n\nδ: Target acceptance rate for dual averaging.\nmax_depth: Maximum doubling tree depth.\nΔ_max: Maximum divergence during doubling tree.\nintegrator: Choice of integrator, specified either using a Symbol or AbstractIntegrator\nmetric: Choice of initial metric; Symbol means it is automatically initialised. The metric type will be preserved during automatic initialisation and adaption.\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.HMCDA","page":"AdvancedHMC.jl","title":"AdvancedHMC.HMCDA","text":"HMCDA(δ::Real, λ::Real, integrator = :leapfrog, metric = :diagonal)\n\nHamiltonian Monte Carlo sampler with Dual Averaging algorithm.\n\nFields\n\nδ: Target acceptance rate for dual averaging.\nλ: Target leapfrog length.\nintegrator: Choice of integrator, specified either using a Symbol or AbstractIntegrator\nmetric: Choice of initial metric; Symbol means it is automatically initialised. The metric type will be preserved during automatic initialisation and adaption.\n\nNotes\n\nFor more information, please view the following paper (arXiv link):\n\nHoffman, Matthew D., and Andrew Gelman. \"The No-U-turn sampler: adaptively setting path lengths in Hamiltonian Monte Carlo.\" Journal of Machine Learning Research 15, no. 1 (2014): 1593-1623.\n\n\n\n\n\n","category":"type"},{"location":"api/#Functions","page":"AdvancedHMC.jl","title":"Functions","text":"","category":"section"},{"location":"api/","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"sample","category":"page"},{"location":"api/#StatsBase.sample","page":"AdvancedHMC.jl","title":"StatsBase.sample","text":"sample([rng], a::AbstractArray, [wv::AbstractWeights])\n\nSelect a single random element of a. Sampling probabilities are proportional to the weights given in wv, if provided.\n\nOptionally specify a random number generator rng as the first argument (defaults to Random.default_rng()).\n\n\n\n\n\nsample([rng], a, [wv::AbstractWeights], n::Integer; replace=true, ordered=false)\n\nSelect a random, optionally weighted sample of size n from an array a using a polyalgorithm. Sampling probabilities are proportional to the weights given in wv, if provided. replace dictates whether sampling is performed with replacement. ordered dictates whether an ordered sample (also called a sequential sample, i.e. a sample where items appear in the same order as in a) should be taken.\n\nOptionally specify a random number generator rng as the first argument (defaults to Random.default_rng()).\n\n\n\n\n\nsample([rng], a, [wv::AbstractWeights], dims::Dims; replace=true, ordered=false)\n\nSelect a random, optionally weighted sample from an array a specifying the dimensions dims of the output array. Sampling probabilities are proportional to the weights given in wv, if provided. replace dictates whether sampling is performed with replacement. ordered dictates whether an ordered sample (also called a sequential sample, i.e. a sample where items appear in the same order as in a) should be taken.\n\nOptionally specify a random number generator rng as the first argument (defaults to Random.default_rng()).\n\n\n\n\n\nsample([rng], wv::AbstractWeights)\n\nSelect a single random integer in 1:length(wv) with probabilities proportional to the weights given in wv.\n\nOptionally specify a random number generator rng as the first argument (defaults to Random.default_rng()).\n\n\n\n\n\nsample(\n rng::Random.AbatractRNG=Random.default_rng(),\n model::AbstractModel,\n sampler::AbstractSampler,\n N_or_isdone;\n kwargs...,\n)\n\nSample from the model with the Markov chain Monte Carlo sampler and return the samples.\n\nIf N_or_isdone is an Integer, exactly N_or_isdone samples are returned.\n\nOtherwise, sampling is performed until a convergence criterion N_or_isdone returns true. The convergence criterion has to be a function with the signature\n\nisdone(rng, model, sampler, samples, state, iteration; kwargs...)\n\nwhere state and iteration are the current state and iteration of the sampler, respectively. It should return true when sampling should end, and false otherwise.\n\nKeyword arguments\n\nSee https://turinglang.org/AbstractMCMC.jl/dev/api/#Common-keyword-arguments for common keyword arguments.\n\n\n\n\n\nsample(\n rng::Random.AbstractRNG=Random.default_rng(),\n model::AbstractModel,\n sampler::AbstractSampler,\n parallel::AbstractMCMCEnsemble,\n N::Integer,\n nchains::Integer;\n kwargs...,\n)\n\nSample nchains Monte Carlo Markov chains from the model with the sampler in parallel using the parallel algorithm, and combine them into a single chain.\n\nKeyword arguments\n\nSee https://turinglang.org/AbstractMCMC.jl/dev/api/#Common-keyword-arguments for common keyword arguments.\n\n\n\n\n\nsample(\n rng::Random.AbstractRNG=Random.default_rng(),\n logdensity,\n sampler::AbstractSampler,\n N_or_isdone;\n kwargs...,\n)\n\nWrap the logdensity function in a LogDensityModel, and call sample with the resulting model instead of logdensity.\n\nThe logdensity function has to support the LogDensityProblems.jl interface.\n\n\n\n\n\nsample(\n rng::Random.AbstractRNG=Random.default_rng(),\n logdensity,\n sampler::AbstractSampler,\n parallel::AbstractMCMCEnsemble,\n N::Integer,\n nchains::Integer;\n kwargs...,\n)\n\nWrap the logdensity function in a LogDensityModel, and call sample with the resulting model instead of logdensity.\n\nThe logdensity function has to support the LogDensityProblems.jl interface.\n\n\n\n\n\nsample(\n rng::AbstractRNG,\n h::Hamiltonian,\n κ::AbstractMCMCKernel,\n θ::AbstractVecOrMat{T},\n n_samples::Int,\n adaptor::AbstractAdaptor=NoAdaptation(),\n n_adapts::Int=min(div(n_samples, 10), 1_000);\n drop_warmup::Bool=false,\n verbose::Bool=true,\n progress::Bool=false\n)\n\nSample n_samples samples using the proposal κ under Hamiltonian h.\n\nThe randomness is controlled by rng. \nIf rng is not provided, the default random number generator (Random.default_rng()) will be used.\nThe initial point is given by θ.\nThe adaptor is set by adaptor, for which the default is no adaptation.\nIt will perform n_adapts steps of adaptation, for which the default is the minimum of 1_000 and 10% of n_samples\ndrop_warmup controls to drop the samples during adaptation phase or not\nverbose controls the verbosity\nprogress controls whether to show the progress meter or not\n\n\n\n\n\n","category":"function"},{"location":"api/#More-types","page":"AdvancedHMC.jl","title":"More types","text":"","category":"section"},{"location":"api/","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"Modules = [AdvancedHMC, AdvancedHMC.Adaptation]\nOrder = [:type]","category":"page"},{"location":"api/#AdvancedHMC.AbstractIntegrator-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.AbstractIntegrator","text":"abstract type AbstractIntegrator\n\nRepresents an integrator used to simulate the Hamiltonian system.\n\nImplementation\n\nA AbstractIntegrator is expected to have the following implementations:\n\nstat(@ref)\nnom_step_size(@ref)\nstep_size(@ref)\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.AbstractMCMCKernel-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.AbstractMCMCKernel","text":"abstract type AbstractMCMCKernel\n\nAbstract type for HMC kernels. \n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.AbstractMetric-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.AbstractMetric","text":"abstract type AbstractMetric\n\nAbstract type for preconditioning metrics. \n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.AbstractTerminationCriterion-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.AbstractTerminationCriterion","text":"abstract type AbstractTerminationCriterion\n\nAbstract type for termination criteria for Hamiltonian trajectories, e.g. no-U-turn and fixed number of leapfrog integration steps. \n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.AbstractTrajectorySampler-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.AbstractTrajectorySampler","text":"How to sample a phase-point from the simulated trajectory.\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.BinaryTree-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.BinaryTree","text":"A full binary tree trajectory with only necessary leaves and information stored.\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.ClassicNoUTurn-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.ClassicNoUTurn","text":"struct ClassicNoUTurn{F<:AbstractFloat} <: AdvancedHMC.DynamicTerminationCriterion\n\nClassic No-U-Turn criterion as described in Eq. (9) in [1].\n\nInformally, this will terminate the trajectory expansion if continuing the simulation either forwards or backwards in time will decrease the distance between the left-most and right-most positions.\n\nFields\n\nmax_depth::Int64\nΔ_max::AbstractFloat\n\nReferences\n\nHoffman, M. D., & Gelman, A. (2014). The No-U-Turn Sampler: adaptively setting path lengths in Hamiltonian Monte Carlo. Journal of Machine Learning Research, 15(1), 1593-1623. (arXiv)\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.DynamicTerminationCriterion-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.DynamicTerminationCriterion","text":"abstract type DynamicTerminationCriterion <: AdvancedHMC.AbstractTerminationCriterion\n\nAbstract type for dynamic Hamiltonian trajectory termination criteria. \n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.EndPointTS-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.EndPointTS","text":"Samples the end-point of the trajectory.\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.FixedIntegrationTime-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.FixedIntegrationTime","text":"struct FixedIntegrationTime{F<:AbstractFloat} <: AdvancedHMC.StaticTerminationCriterion\n\nStandard HMC implementation with a fixed integration time.\n\nFields\n\nλ::AbstractFloat: Total length of the trajectory, i.e. take floor(λ / integrator_step_size) number of leapfrog steps.\n\nReferences\n\nNeal, R. M. (2011). MCMC using Hamiltonian dynamics. Handbook of Markov chain Monte Carlo, 2(11), 2. (arXiv) \n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.FixedNSteps-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.FixedNSteps","text":"struct FixedNSteps <: AdvancedHMC.StaticTerminationCriterion\n\nStatic HMC with a fixed number of leapfrog steps.\n\nFields\n\nL::Int64: Number of steps to simulate, i.e. length of trajectory will be L + 1.\n\nReferences\n\nNeal, R. M. (2011). MCMC using Hamiltonian dynamics. Handbook of Markov chain Monte Carlo, 2(11), 2. (arXiv)\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.FullMomentumRefreshment-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.FullMomentumRefreshment","text":"Completly resample new momentum.\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.GeneralisedNoUTurn-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.GeneralisedNoUTurn","text":"struct GeneralisedNoUTurn{F<:AbstractFloat} <: AdvancedHMC.DynamicTerminationCriterion\n\nGeneralised No-U-Turn criterion as described in Section A.4.2 in [1].\n\nFields\n\nmax_depth::Int64\nΔ_max::AbstractFloat\n\nReferences\n\nBetancourt, M. (2017). A Conceptual Introduction to Hamiltonian Monte Carlo. arXiv preprint arXiv:1701.02434.\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.GeneralizedLeapfrog-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.GeneralizedLeapfrog","text":"struct GeneralizedLeapfrog{T<:(Union{AbstractVector{var\"#s17\"}, var\"#s17\"} where var\"#s17\"<:AbstractFloat)} <: AdvancedHMC.AbstractLeapfrog{T<:(Union{AbstractVector{var\"#s17\"}, var\"#s17\"} where var\"#s17\"<:AbstractFloat)}\n\nGeneralized leapfrog integrator with fixed step size ϵ.\n\nFields\n\nϵ::Union{AbstractVector{var\"#s17\"}, var\"#s17\"} where var\"#s17\"<:AbstractFloat: Step size.\nn::Int64\n\nReferences\n\nGirolami, Mark, and Ben Calderhead. \"Riemann manifold Langevin and Hamiltonian Monte Carlo methods.\" Journal of the Royal Statistical Society Series B: Statistical Methodology 73, no. 2 (2011): 123-214.\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.HMC-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.HMC","text":"HMC(ϵ::Real, n_leapfrog::Int)\n\nHamiltonian Monte Carlo sampler with static trajectory.\n\nFields\n\nn_leapfrog: Number of leapfrog steps.\nintegrator: Choice of integrator, specified either using a Symbol or AbstractIntegrator\nmetric: Choice of initial metric; Symbol means it is automatically initialised. The metric type will be preserved during automatic initialisation and adaption.\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.HMCDA-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.HMCDA","text":"HMCDA(δ::Real, λ::Real, integrator = :leapfrog, metric = :diagonal)\n\nHamiltonian Monte Carlo sampler with Dual Averaging algorithm.\n\nFields\n\nδ: Target acceptance rate for dual averaging.\nλ: Target leapfrog length.\nintegrator: Choice of integrator, specified either using a Symbol or AbstractIntegrator\nmetric: Choice of initial metric; Symbol means it is automatically initialised. The metric type will be preserved during automatic initialisation and adaption.\n\nNotes\n\nFor more information, please view the following paper (arXiv link):\n\nHoffman, Matthew D., and Andrew Gelman. \"The No-U-turn sampler: adaptively setting path lengths in Hamiltonian Monte Carlo.\" Journal of Machine Learning Research 15, no. 1 (2014): 1593-1623.\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.HMCProgressCallback-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.HMCProgressCallback","text":"HMCProgressCallback\n\nA callback to be used with AbstractMCMC.jl's interface, replicating the logging behavior of the non-AbstractMCMC sample.\n\nFields\n\npm: Progress meter from ProgressMeters.jl, or nothing.\nverbose: If pm === nothing and this is true some information will be logged upon completion of adaptation.\nnum_divergent_transitions: Number of divergent transitions.\nnum_divergent_transitions_during_adaption\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.HMCSampler-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.HMCSampler","text":"HMCSampler\n\nAn AbstractMCMC.AbstractSampler for kernels in AdvancedHMC.jl.\n\nFields\n\nκ: AbstractMCMCKernel.\nmetric: Choice of initial metric AbstractMetric. The metric type will be preserved during adaption.\nadaptor: AdvancedHMC.Adaptation.AbstractAdaptor.\n\nNotes\n\nNote that all the fields have the prefix initial_ to indicate that these will not necessarily correspond to the kernel, metric, and adaptor after sampling.\n\nTo access the updated fields, use the resulting HMCState.\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.HMCState-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.HMCState","text":"HMCState\n\nRepresents the state of a HMCSampler.\n\nFields\n\ni: Index of current iteration.\ntransition: Current Transition.\nmetric: Current AbstractMetric, possibly adapted.\nκ: Current AbstractMCMCKernel.\nadaptor: Current AbstractAdaptor.\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.JitteredLeapfrog-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.JitteredLeapfrog","text":"struct JitteredLeapfrog{FT<:AbstractFloat, T<:Union{AbstractArray{FT<:AbstractFloat, 1}, FT<:AbstractFloat}} <: AdvancedHMC.AbstractLeapfrog{T<:Union{AbstractArray{FT<:AbstractFloat, 1}, FT<:AbstractFloat}}\n\nLeapfrog integrator with randomly \"jittered\" step size ϵ for every trajectory.\n\nFields\n\nϵ0::Union{AbstractVector{FT}, FT} where FT<:AbstractFloat: Nominal (non-jittered) step size.\njitter::AbstractFloat: The proportion of the nominal step size ϵ0 that may be added or subtracted.\nϵ::Union{AbstractVector{FT}, FT} where FT<:AbstractFloat: Current (jittered) step size.\n\nDescription\n\nThis is the same as LeapFrog(@ref) but with a \"jittered\" step size. This means that at the beginning of each trajectory we sample a step size ϵ by adding or subtracting from the nominal/base step size ϵ0 some random proportion of ϵ0, with the proportion specified by jitter, i.e. ϵ = ϵ0 - jitter * ϵ0 * rand(). p Jittering might help alleviate issues related to poor interactions with a fixed step size:\n\nIn regions with high \"curvature\" the current choice of step size might mean over-shoot leading to almost all steps being rejected. Randomly sampling the step size at the beginning of the trajectories can therefore increase the probability of escaping such high-curvature regions.\nExact periodicity of the simulated trajectories might occur, i.e. you might be so unlucky as to simulate the trajectory forwards in time L ϵ and ending up at the same point (which results in non-ergodicity; see Section 3.2 in [1]). If momentum is refreshed before each trajectory, then this should not happen exactly but it can still be an issue in practice. Randomly choosing the step-size ϵ might help alleviate such problems.\n\nReferences\n\nNeal, R. M. (2011). MCMC using Hamiltonian dynamics. Handbook of Markov chain Monte Carlo, 2(11), 2. (arXiv)\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.Leapfrog-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.Leapfrog","text":"struct Leapfrog{T<:(Union{AbstractVector{var\"#s26\"}, var\"#s26\"} where var\"#s26\"<:AbstractFloat)} <: AdvancedHMC.AbstractLeapfrog{T<:(Union{AbstractVector{var\"#s26\"}, var\"#s26\"} where var\"#s26\"<:AbstractFloat)}\n\nLeapfrog integrator with fixed step size ϵ.\n\nFields\n\nϵ::Union{AbstractVector{var\"#s26\"}, var\"#s26\"} where var\"#s26\"<:AbstractFloat: Step size.\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.MultinomialTS-Tuple{MultinomialTS, AbstractFloat, AdvancedHMC.PhasePoint}-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.MultinomialTS","text":"struct MultinomialTS{F<:AbstractFloat} <: AdvancedHMC.AbstractTrajectorySampler\n\nMultinomial sampler for a trajectory consisting only a leaf node.\n\ntree weight is the (unnormalised) energy of the leaf.\n\n\n\n\n\n","category":"method"},{"location":"api/#AdvancedHMC.MultinomialTS-Tuple{Random.AbstractRNG, AdvancedHMC.PhasePoint}-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.MultinomialTS","text":"struct MultinomialTS{F<:AbstractFloat} <: AdvancedHMC.AbstractTrajectorySampler\n\nMultinomial sampler for the starting single leaf tree. (Log) weights for leaf nodes are their (unnormalised) Hamiltonian energies.\n\nRef: https://github.com/stan-dev/stan/blob/develop/src/stan/mcmc/hmc/nuts/base_nuts.hpp#L226\n\n\n\n\n\n","category":"method"},{"location":"api/#AdvancedHMC.MultinomialTS-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.MultinomialTS","text":"struct MultinomialTS{F<:AbstractFloat} <: AdvancedHMC.AbstractTrajectorySampler\n\nMultinomial trajectory sampler carried during the building of the tree. It contains the weight of the tree, defined as the total probabilities of the leaves.\n\nFields\n\nzcand::AdvancedHMC.PhasePoint: Sampled candidate PhasePoint.\nℓw::AbstractFloat: Total energy for the given tree, i.e. the sum of energies of all leaves.\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.NUTS-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.NUTS","text":"NUTS(δ::Real; max_depth::Int=10, Δ_max::Real=1000, integrator = :leapfrog, metric = :diagonal)\n\nNo-U-Turn Sampler (NUTS) sampler.\n\nFields\n\nδ: Target acceptance rate for dual averaging.\nmax_depth: Maximum doubling tree depth.\nΔ_max: Maximum divergence during doubling tree.\nintegrator: Choice of integrator, specified either using a Symbol or AbstractIntegrator\nmetric: Choice of initial metric; Symbol means it is automatically initialised. The metric type will be preserved during automatic initialisation and adaption.\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.PartialMomentumRefreshment-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.PartialMomentumRefreshment","text":"struct PartialMomentumRefreshment{F<:AbstractFloat} <: AdvancedHMC.AbstractMomentumRefreshment\n\nPartial momentum refreshment with refresh rate α.\n\nFields\n\nα::AbstractFloat\n\nSee equation (5.19) [1]\n\nr' = α⋅r + sqrt(1-α²)⋅G\n\nwhere r is the momentum and G is a Gaussian random variable.\n\nReferences\n\nNeal, Radford M. \"MCMC using Hamiltonian dynamics.\" Handbook of markov chain monte carlo 2.11 (2011): 2.\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.SliceTS-Tuple{Random.AbstractRNG, AdvancedHMC.PhasePoint}-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.SliceTS","text":"struct SliceTS{F<:AbstractFloat} <: AdvancedHMC.AbstractTrajectorySampler\n\nSlice sampler for the starting single leaf tree. Slice variable is initialized.\n\n\n\n\n\n","category":"method"},{"location":"api/#AdvancedHMC.SliceTS-Tuple{SliceTS, AbstractFloat, AdvancedHMC.PhasePoint}-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.SliceTS","text":"struct SliceTS{F<:AbstractFloat} <: AdvancedHMC.AbstractTrajectorySampler\n\nCreate a slice sampler for a single leaf tree:\n\nthe slice variable is copied from the passed-in sampler s and\nthe number of acceptable candicates is computed by comparing the slice variable against the current energy.\n\n\n\n\n\n","category":"method"},{"location":"api/#AdvancedHMC.SliceTS-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.SliceTS","text":"struct SliceTS{F<:AbstractFloat} <: AdvancedHMC.AbstractTrajectorySampler\n\nTrajectory slice sampler carried during the building of the tree. It contains the slice variable and the number of acceptable condidates in the tree.\n\nFields\n\nzcand::AdvancedHMC.PhasePoint: Sampled candidate PhasePoint.\nℓu::AbstractFloat: Slice variable in log-space.\nn::Int64: Number of acceptable candidates, i.e. those with probability larger than slice variable u.\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.StaticTerminationCriterion-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.StaticTerminationCriterion","text":"abstract type StaticTerminationCriterion <: AdvancedHMC.AbstractTerminationCriterion\n\nAbstract type for a fixed number of leapfrog integration steps.\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.StrictGeneralisedNoUTurn-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.StrictGeneralisedNoUTurn","text":"struct StrictGeneralisedNoUTurn{F<:AbstractFloat} <: AdvancedHMC.DynamicTerminationCriterion\n\nGeneralised No-U-Turn criterion as described in Section A.4.2 in [1] with added U-turn check as described in [2].\n\nFields\n\nmax_depth::Int64\nΔ_max::AbstractFloat\n\nReferences\n\nBetancourt, M. (2017). A Conceptual Introduction to Hamiltonian Monte Carlo. arXiv preprint arXiv:1701.02434.\nhttps://github.com/stan-dev/stan/pull/2800\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.TemperedLeapfrog-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.TemperedLeapfrog","text":"struct TemperedLeapfrog{FT<:AbstractFloat, T<:Union{AbstractArray{FT<:AbstractFloat, 1}, FT<:AbstractFloat}} <: AdvancedHMC.AbstractLeapfrog{T<:Union{AbstractArray{FT<:AbstractFloat, 1}, FT<:AbstractFloat}}\n\nTempered leapfrog integrator with fixed step size ϵ and \"temperature\" α.\n\nFields\n\nϵ::Union{AbstractVector{FT}, FT} where FT<:AbstractFloat: Step size.\nα::AbstractFloat: Temperature parameter.\n\nDescription\n\nTempering can potentially allow greater exploration of the posterior, e.g. in a multi-modal posterior jumps between the modes can be more likely to occur.\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.Termination-Union{Tuple{F}, Tuple{MultinomialTS, Trajectory, F, F}} where F<:AbstractFloat-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.Termination","text":"Termination(s, nt, H0, H′)\n\n\nCheck termination of a Hamiltonian trajectory.\n\n\n\n\n\n","category":"method"},{"location":"api/#AdvancedHMC.Termination-Union{Tuple{F}, Tuple{SliceTS, Trajectory, F, F}} where F<:AbstractFloat-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.Termination","text":"Termination(s, nt, H0, H′)\n\n\nCheck termination of a Hamiltonian trajectory.\n\n\n\n\n\n","category":"method"},{"location":"api/#AdvancedHMC.Termination-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.Termination","text":"Termination\n\nTermination reasons\n\ndynamic: due to stoping criteria\nnumerical: due to large energy deviation from starting (possibly numerical errors)\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.Trajectory-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.Trajectory","text":"struct Trajectory{TS<:AdvancedHMC.AbstractTrajectorySampler, I<:AdvancedHMC.AbstractIntegrator, TC<:AdvancedHMC.AbstractTerminationCriterion}\n\nNumerically simulated Hamiltonian trajectories.\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.Transition-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.Transition","text":"struct Transition{P<:AdvancedHMC.PhasePoint, NT<:NamedTuple}\n\nA transition that contains the phase point and other statistics of the transition.\n\nFields\n\nz::AdvancedHMC.PhasePoint: Phase-point for the transition.\nstat::NamedTuple: Statistics related to the transition, e.g. energy.\n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.Adaptation.AbstractAdaptor-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.Adaptation.AbstractAdaptor","text":"abstract type AbstractAdaptor\n\nAbstract type for HMC adaptors. \n\n\n\n\n\n","category":"type"},{"location":"api/#AdvancedHMC.Adaptation.NesterovDualAveraging-api","page":"AdvancedHMC.jl","title":"AdvancedHMC.Adaptation.NesterovDualAveraging","text":"An implementation of the Nesterov dual averaging algorithm to tune step size.\n\nReferences\n\nHoffman, M. D., & Gelman, A. (2014). The No-U-Turn Sampler: adaptively setting path lengths in Hamiltonian Monte Carlo. Journal of Machine Learning Research, 15(1), 1593-1623. Nesterov, Y. (2009). Primal-dual subgradient methods for convex problems. Mathematical programming, 120(1), 221-259.\n\n\n\n\n\n","category":"type"},{"location":"#AdvancedHMC.jl","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"","category":"section"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"(Image: CI) (Image: DOI) (Image: Coverage Status) (Image: Stable) (Image: Dev)","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"AdvancedHMC.jl provides a robust, modular, and efficient implementation of advanced HMC algorithms. An illustrative example of AdvancedHMC's usage is given below. AdvancedHMC.jl is part of Turing.jl, a probabilistic programming library in Julia. If you are interested in using AdvancedHMC.jl through a probabilistic programming language, please check it out!","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"Interfaces","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"IMP.hmc: an experimental Python module for the Integrative Modeling Platform, which uses AdvancedHMC in its backend to sample protein structures.","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"NEWS","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"We presented a paper for AdvancedHMC.jl at AABI in 2019 in Vancouver, Canada. (abs, pdf, OpenReview)\nWe presented a poster for AdvancedHMC.jl at StanCon 2019 in Cambridge, UK. (pdf)","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"API CHANGES","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"[v0.5.0] Breaking! Convenience constructors for common samplers changed to:\nHMC(leapfrog_stepsize::Real, n_leapfrog::Int)\nNUTS(target_acceptance::Real) \nHMCDA(target_acceptance::Real, integration_time::Real)\n[v0.2.22] Three functions are renamed.\nPreconditioner(metric::AbstractMetric) -> MassMatrixAdaptor(metric) and \nNesterovDualAveraging(δ, integrator::AbstractIntegrator) -> StepSizeAdaptor(δ, integrator)\nfind_good_eps -> find_good_stepsize\n[v0.2.15] n_adapts is no longer needed to construct StanHMCAdaptor; the old constructor is deprecated.\n[v0.2.8] Two Hamiltonian trajectory sampling methods are renamed to avoid a name clash with Distributions.\nMultinomial -> MultinomialTS\nSlice -> SliceTS\n[v0.2.0] The gradient function passed to Hamiltonian is supposed to return a value-gradient tuple now.","category":"page"},{"location":"#A-minimal-example-sampling-from-a-multivariate-Gaussian-using-NUTS","page":"AdvancedHMC.jl","title":"A minimal example - sampling from a multivariate Gaussian using NUTS","text":"","category":"section"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"This section demonstrates a minimal example of sampling from a multivariate Gaussian (10-dimensional) using the no U-turn sampler (NUTS). Below we describe the major components of the Hamiltonian system which are essential to sample using this approach:","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"Metric: In many sampling problems the sample space is associated with a metric that allows us to measure the distance between any two points, and other similar quantities. In the example in this section, we use a special metric called the Euclidean Metric, represented with a D × D matrix from which we can compute distances.[1]\nLeapfrog integration: Leapfrog integration is a second-order numerical method for integrating differential equations (In this case they are equations of motion for the relative position of one particle with respect to the other). The order of this integration signifies its rate of convergence. Any algorithm with a finite time step size will have numerical errors, and the order is related to this error. For a second-order algorithm, this error scales as the second power of the time step, hence, the name second-order. High-order integrators are usually complex to code and have a limited region of convergence; hence they do not allow arbitrarily large time steps. A second-order integrator is suitable for our purpose. Hence we opt for the leapfrog integrator. It is called leapfrog due to the ways this algorithm is written, where the positions and velocities of particles \"leap over\" each other.[2]\nKernel for trajectories (static or dynamic): Different kernels, which may be static or dynamic, can be used. At each iteration of any variant of the HMC algorithm, there are two main steps - the first step changes the momentum and the second step may change both the position and the momentum of a particle.[3]","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"using AdvancedHMC, ForwardDiff\nusing LogDensityProblems\nusing LinearAlgebra\n\n# Define the target distribution using the `LogDensityProblem` interface\nstruct LogTargetDensity\n dim::Int\nend\nLogDensityProblems.logdensity(p::LogTargetDensity, θ) = -sum(abs2, θ) / 2 # standard multivariate normal\nLogDensityProblems.dimension(p::LogTargetDensity) = p.dim\nLogDensityProblems.capabilities(::Type{LogTargetDensity}) = LogDensityProblems.LogDensityOrder{0}()\n\n# Choose parameter dimensionality and initial parameter value\nD = 10; initial_θ = rand(D)\nℓπ = LogTargetDensity(D)\n\n# Set the number of samples to draw and warmup iterations\nn_samples, n_adapts = 2_000, 1_000\n\n# Define a Hamiltonian system\nmetric = DiagEuclideanMetric(D)\nhamiltonian = Hamiltonian(metric, ℓπ, ForwardDiff)\n\n# Define a leapfrog solver, with the initial step size chosen heuristically\ninitial_ϵ = find_good_stepsize(hamiltonian, initial_θ)\nintegrator = Leapfrog(initial_ϵ)\n\n# Define an HMC sampler with the following components\n# - multinomial sampling scheme,\n# - generalised No-U-Turn criteria, and\n# - windowed adaption for step-size and diagonal mass matrix\nkernel = HMCKernel(Trajectory{MultinomialTS}(integrator, GeneralisedNoUTurn()))\nadaptor = StanHMCAdaptor(MassMatrixAdaptor(metric), StepSizeAdaptor(0.8, integrator))\n\n# Run the sampler to draw samples from the specified Gaussian, where\n# - `samples` will store the samples\n# - `stats` will store diagnostic statistics for each sample\nsamples, stats = sample(hamiltonian, kernel, initial_θ, n_samples, adaptor, n_adapts; progress=true)","category":"page"},{"location":"#Parallel-sampling","page":"AdvancedHMC.jl","title":"Parallel sampling","text":"","category":"section"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"AdvancedHMC enables parallel sampling (either distributed or multi-thread) via Julia's parallel computing functions. It also supports vectorized sampling for static HMC.","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"The below example utilizes the @threads macro to sample 4 chains across 4 threads.","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"# Ensure that Julia was launched with an appropriate number of threads\nprintln(Threads.nthreads())\n\n# Number of chains to sample\nnchains = 4\n\n# Cache to store the chains\nchains = Vector{Any}(undef, nchains)\n\n# The `samples` from each parallel chain is stored in the `chains` vector \n# Adjust the `verbose` flag as per need\nThreads.@threads for i in 1:nchains\n samples, stats = sample(hamiltonian, kernel, initial_θ, n_samples, adaptor, n_adapts; verbose=false)\n chains[i] = samples\nend","category":"page"},{"location":"#Using-the-AbstractMCMC-interface","page":"AdvancedHMC.jl","title":"Using the AbstractMCMC interface","text":"","category":"section"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"Users can also use the AbstractMCMC interface to sample, which is also used in Turing.jl. In order to show how this is done let us start from our previous example where we defined a LogTargetDensity, ℓπ.","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"using AbstractMCMC, LogDensityProblemsAD\n# Wrap the previous LogTargetDensity as LogDensityModel \n# where ℓπ::LogTargetDensity\nmodel = AdvancedHMC.LogDensityModel(LogDensityProblemsAD.ADgradient(Val(:ForwardDiff), ℓπ))\n\n# Wrap the previous sampler as a HMCSampler <: AbstractMCMC.AbstractSampler\nD = 10; initial_θ = rand(D)\nn_samples, n_adapts, δ = 1_000, 2_000, 0.8\nsampler = HMCSampler(kernel, metric, adaptor) \n\n# Now sample\nsamples = AbstractMCMC.sample(\n model,\n sampler,\n n_adapts + n_samples;\n n_adapts = n_adapts,\n initial_params = initial_θ,\n )","category":"page"},{"location":"#Convenience-Constructors","page":"AdvancedHMC.jl","title":"Convenience Constructors","text":"","category":"section"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"In the previous examples, we built the sampler by manually specifying the integrator, metric, kernel, and adaptor to build our own sampler. However, in many cases, users might want to initialize a standard NUTS sampler. In such cases having to define each of these aspects manually is tedious and error-prone. For these reasons AdvancedHMC also provides users with a series of convenience constructors for standard samplers. We will now show how to use them.","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"HMC:\n# HMC Sampler\n# step size, number of leapfrog steps \nn_leapfrog, ϵ = 25, 0.1\nhmc = HMC(ϵ, n_leapfrog)\nEquivalent to:\nmetric = DiagEuclideanMetric(D)\nhamiltonian = Hamiltonian(metric, ℓπ, ForwardDiff)\nintegrator = Leapfrog(0.1)\nkernel = HMCKernel(Trajectory{EndPointTS}(integrator, FixedNSteps(n_leapfrog)))\nadaptor = NoAdaptation()\nhmc = HMCSampler(kernel, metric, adaptor)\nNUTS:\n# NUTS Sampler\n# adaptation steps, target acceptance probability,\nδ = 0.8\nnuts = NUTS(δ)\nEquivalent to:\nmetric = DiagEuclideanMetric(D)\nhamiltonian = Hamiltonian(metric, ℓπ, ForwardDiff)\ninitial_ϵ = find_good_stepsize(hamiltonian, initial_θ)\nintegrator = Leapfrog(initial_ϵ)\nkernel = HMCKernel(Trajectory{MultinomialTS}(integrator, GeneralisedNoUTurn()))\nadaptor = StanHMCAdaptor(MassMatrixAdaptor(metric), StepSizeAdaptor(δ, integrator))\nnuts = HMCSampler(kernel, metric, adaptor)","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"HMCDA:\n#HMCDA (dual averaging)\n# adaptation steps, target acceptance probability, target trajectory length \nδ, λ = 0.8, 1.0\nhmcda = HMCDA(δ, λ)\nEquivalent to:\nmetric = DiagEuclideanMetric(D)\nhamiltonian = Hamiltonian(metric, ℓπ, ForwardDiff)\ninitial_ϵ = find_good_stepsize(hamiltonian, initial_θ)\nintegrator = Leapfrog(initial_ϵ)\nkernel = HMCKernel(Trajectory{EndPointTS}(integrator, FixedIntegrationTime(λ)))\nadaptor = StepSizeAdaptor(δ, initial_ϵ)\nhmcda = HMCSampler(kernel, metric, adaptor)","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"Moreover, there's some flexibility in how these samplers can be initialized. For example, a user can initialize a NUTS (HMC and HMCDA) sampler with their own metrics and integrators. This can be done as follows:","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"nuts = NUTS(δ, metric = :diagonal) #metric = DiagEuclideanMetric(D) (Default!)\nnuts = NUTS(δ, metric = :unit) #metric = UnitEuclideanMetric(D)\nnuts = NUTS(δ, metric = :dense) #metric = DenseEuclideanMetric(D)\n# Provide your own AbstractMetric\nmetric = DiagEuclideanMetric(10)\nnuts = NUTS(δ, metric = metric)\n\nnuts = NUTS(δ, integrator = :leapfrog) #integrator = Leapfrog(ϵ) (Default!)\nnuts = NUTS(δ, integrator = :jitteredleapfrog) #integrator = JitteredLeapfrog(ϵ, 0.1ϵ)\nnuts = NUTS(δ, integrator = :temperedleapfrog) #integrator = TemperedLeapfrog(ϵ, 1.0)\n\n# Provide your own AbstractIntegrator\nintegrator = JitteredLeapfrog(0.1, 0.2)\nnuts = NUTS(δ, integrator = integrator) ","category":"page"},{"location":"#GPU-Sampling-with-CUDA","page":"AdvancedHMC.jl","title":"GPU Sampling with CUDA","text":"","category":"section"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"There is experimental support for running static HMC on the GPU using CUDA. To do so, the user needs to have CUDA.jl installed, ensure the logdensity of the Hamiltonian can be executed on the GPU and that the initial points are a CuArray. A small working example can be found at test/cuda.jl.","category":"page"},{"location":"#API-and-supported-HMC-algorithms","page":"AdvancedHMC.jl","title":"API and supported HMC algorithms","text":"","category":"section"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"An important design goal of AdvancedHMC.jl is modularity; we would like to support algorithmic research on HMC. This modularity means that different HMC variants can be easily constructed by composing various components, such as preconditioning metric (i.e., mass matrix), leapfrog integrators, trajectories (static or dynamic), adaption schemes, etc. The minimal example above can be modified to suit particular inference problems by picking components from the list below.","category":"page"},{"location":"#Hamiltonian-mass-matrix-(metric)","page":"AdvancedHMC.jl","title":"Hamiltonian mass matrix (metric)","text":"","category":"section"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"Unit metric: UnitEuclideanMetric(dim)\nDiagonal metric: DiagEuclideanMetric(dim)\nDense metric: DenseEuclideanMetric(dim)","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"where dim is the dimensionality of the sampling space.","category":"page"},{"location":"#Integrator-(integrator)","page":"AdvancedHMC.jl","title":"Integrator (integrator)","text":"","category":"section"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"Ordinary leapfrog integrator: Leapfrog(ϵ)\nJittered leapfrog integrator with jitter rate n: JitteredLeapfrog(ϵ, n)\nTempered leapfrog integrator with tempering rate a: TemperedLeapfrog(ϵ, a)","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"where ϵ is the step size of leapfrog integration.","category":"page"},{"location":"#Kernel-(kernel)","page":"AdvancedHMC.jl","title":"Kernel (kernel)","text":"","category":"section"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"Static HMC with a fixed number of steps (n_steps) (Neal, R. M. (2011)): HMCKernel(Trajectory{EndPointTS}(integrator, FixedNSteps(integrator)))\nHMC with a fixed total trajectory length (trajectory_length) (Neal, R. M. (2011)): HMCKernel(Trajectory{EndPointTS}(integrator, FixedIntegrationTime(trajectory_length))) \nOriginal NUTS with slice sampling (Hoffman, M. D., & Gelman, A. (2014)): HMCKernel(Trajectory{SliceTS}(integrator, ClassicNoUTurn()))\nGeneralised NUTS with slice sampling (Betancourt, M. (2017)): HMCKernel(Trajectory{SliceTS}(integrator, GeneralisedNoUTurn()))\nOriginal NUTS with multinomial sampling (Betancourt, M. (2017)): HMCKernel(Trajectory{MultinomialTS}(integrator, ClassicNoUTurn()))\nGeneralised NUTS with multinomial sampling (Betancourt, M. (2017)): HMCKernel(Trajectory{MultinomialTS}(integrator, GeneralisedNoUTurn()))","category":"page"},{"location":"#Adaptor-(adaptor)","page":"AdvancedHMC.jl","title":"Adaptor (adaptor)","text":"","category":"section"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"Adapt the mass matrix metric of the Hamiltonian dynamics: mma = MassMatrixAdaptor(metric)\nThis is lowered to UnitMassMatrix, WelfordVar or WelfordCov based on the type of the mass matrix metric\nAdapt the step size of the leapfrog integrator integrator: ssa = StepSizeAdaptor(δ, integrator)\nIt uses Nesterov's dual averaging with δ as the target acceptance rate.\nCombine the two above naively: NaiveHMCAdaptor(mma, ssa)\nCombine the first two using Stan's windowed adaptation: StanHMCAdaptor(mma, ssa)","category":"page"},{"location":"#Gradients","page":"AdvancedHMC.jl","title":"Gradients","text":"","category":"section"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"AdvancedHMC supports AD-based using LogDensityProblemsAD and user-specified gradients. In order to use user-specified gradients, please replace ForwardDiff with ℓπ_grad in the Hamiltonian constructor, where the gradient function ℓπ_grad should return a tuple containing both the log-posterior and its gradient. ","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"All the combinations are tested in this file except for using tempered leapfrog integrator together with adaptation, which we found unstable empirically.","category":"page"},{"location":"#The-sample-function-signature-in-detail","page":"AdvancedHMC.jl","title":"The sample function signature in detail","text":"","category":"section"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"function sample(\n rng::Union{AbstractRNG, AbstractVector{<:AbstractRNG}},\n h::Hamiltonian,\n κ::HMCKernel,\n θ::AbstractVector{<:AbstractFloat},\n n_samples::Int,\n adaptor::AbstractAdaptor=NoAdaptation(),\n n_adapts::Int=min(div(n_samples, 10), 1_000);\n drop_warmup=false,\n verbose::Bool=true,\n progress::Bool=false,\n)","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"Draw n_samples samples using the kernel κ under the Hamiltonian system h","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"The randomness is controlled by rng.\nIf rng is not provided, the default random number generator (Random.default_rng()) will be used.\nThe initial point is given by θ.\nThe adaptor is set by adaptor, for which the default is no adaptation.\nIt will perform n_adapts steps of adaptation, for which the default is 1_000 or 10% of n_samples, whichever is lower. \ndrop_warmup specifies whether to drop samples.\nverbose controls the verbosity.\nprogress controls whether to show the progress meter or not.","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"Note that the function signature of the sample function exported by AdvancedHMC.jl differs from the sample function used by Turing.jl. We refer to the documentation of Turing.jl for more details on the latter.","category":"page"},{"location":"#Citing-AdvancedHMC.jl","page":"AdvancedHMC.jl","title":"Citing AdvancedHMC.jl","text":"","category":"section"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"If you use AdvancedHMC.jl for your own research, please consider citing the following publication:","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"Kai Xu, Hong Ge, Will Tebbutt, Mohamed Tarek, Martin Trapp, Zoubin Ghahramani: \"AdvancedHMC.jl: A robust, modular and efficient implementation of advanced HMC algorithms.\", Symposium on Advances in Approximate Bayesian Inference, 2020. (abs, pdf)","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"with the following BibTeX entry:","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"@inproceedings{xu2020advancedhmc,\n title={AdvancedHMC. jl: A robust, modular and efficient implementation of advanced HMC algorithms},\n author={Xu, Kai and Ge, Hong and Tebbutt, Will and Tarek, Mohamed and Trapp, Martin and Ghahramani, Zoubin},\n booktitle={Symposium on Advances in Approximate Bayesian Inference},\n pages={1--10},\n year={2020},\n organization={PMLR}\n}","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"If you using AdvancedHMC.jl directly through Turing.jl, please consider citing the following publication:","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"Hong Ge, Kai Xu, and Zoubin Ghahramani: \"Turing: a language for flexible probabilistic inference.\", International Conference on Artificial Intelligence and Statistics, 2018. (abs, pdf)","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"with the following BibTeX entry:","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"@inproceedings{ge2018turing,\n title={Turing: A language for flexible probabilistic inference},\n author={Ge, Hong and Xu, Kai and Ghahramani, Zoubin},\n booktitle={International Conference on Artificial Intelligence and Statistics},\n pages={1682--1690},\n year={2018},\n organization={PMLR}\n}","category":"page"},{"location":"#References","page":"AdvancedHMC.jl","title":"References","text":"","category":"section"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"Neal, R. M. (2011). MCMC using Hamiltonian dynamics. Handbook of Markov chain Monte Carlo, 2(11), 2. (arXiv)\nBetancourt, M. (2017). A Conceptual Introduction to Hamiltonian Monte Carlo. arXiv preprint arXiv:1701.02434.\nGirolami, M., & Calderhead, B. (2011). Riemann manifold Langevin and Hamiltonian Monte Carlo methods. Journal of the Royal Statistical Society: Series B (Statistical Methodology), 73(2), 123-214. (arXiv)\nBetancourt, M. J., Byrne, S., & Girolami, M. (2014). Optimizing the integrator step size for Hamiltonian Monte Carlo. arXiv preprint arXiv:1411.6669.\nBetancourt, M. (2016). Identifying the optimal integration time in Hamiltonian Monte Carlo. arXiv preprint arXiv:1601.00225.\nHoffman, M. D., & Gelman, A. (2014). The No-U-Turn Sampler: adaptively setting path lengths in Hamiltonian Monte Carlo. Journal of Machine Learning Research, 15(1), 1593-1623. (arXiv)","category":"page"},{"location":"#Footnotes","page":"AdvancedHMC.jl","title":"Footnotes","text":"","category":"section"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"[1]: The Euclidean metric is also known as the mass matrix in the physical perspective. See Hamiltonian mass matrix for available metrics.","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"[2]: About the leapfrog integration scheme: Suppose bf x and bf v are the position and velocity of an individual particle respectively; i and i+1 are the indices for time values t_i and t_i+1 respectively; dt = t_i+1 - t_i is the time step size (constant and regularly spaced intervals), and bf a is the acceleration induced on a particle by the forces of all other particles. Furthermore, suppose positions are defined at times t_i t_i+1 t_i+2 dots spaced at constant intervals dt, the velocities are defined at halfway times in between, denoted by t_i-12 t_i+12 t_i+32 dots where t_i+1 - t_i + 12 = t_i + 12 - t_i = dt 2, and the accelerations bf a are defined only on integer times, just like the positions. Then the leapfrog integration scheme is given as: x_i = x_i-1 + v_i-12 dt quad v_i+12 = v_i-12 + a_i dt. For available integrators refer to Integrator.","category":"page"},{"location":"","page":"AdvancedHMC.jl","title":"AdvancedHMC.jl","text":"[3]: On kernels: In the classical HMC approach, during the first step, new values for the momentum variables are randomly drawn from their Gaussian distribution, independently of the current values of the position variables. A Metropolis update is performed during the second step, using Hamiltonian dynamics to provide a new state. For available kernels refer to Kernel.","category":"page"}] }