Advanced HMC
Functions
#
AdvancedHMC.A
— Method
A single Hamiltonian integration step.
this function is intended to be used in find_good_stepsize only.
|
#
AdvancedHMC.build_tree
— Method
Recursivly build a tree for a given depth j
.
#
AdvancedHMC.check_left_subtree
— Method
check_left_subtree(h, t, tleft, tright)
Do a U-turn check between the leftmost phase point of t
and the leftmost phase point of tright
, the right subtree.
#
AdvancedHMC.check_right_subtree
— Method
check_right_subtree(h, t, tleft, tright)
Do a U-turn check between the rightmost phase point of t
and the rightmost phase point of tleft
, the left subtree.
#
AdvancedHMC.combine
— Method
combine(treeleft, treeright)
Merge a left tree treeleft
and a right tree treeright
under given Hamiltonian h
, then draw a new candidate sample and update related statistics for the resulting tree.
#
AdvancedHMC.determine_sampler_eltype
— Method
determine_sampler_eltype(xs...)
Determine the element type to use for the given arguments.
Symbols are either resolved to the default float type or simply dropped in favour of determined types from the other arguments.
#
AdvancedHMC.find_good_stepsize
— Method
Find a good initial leap-frog step-size via heuristic search.
#
AdvancedHMC.isterminated
— Method
isterminated(_, h, t)
Detect U turn for two phase points (zleft
and zright
) under given Hamiltonian h
using the (original) no-U-turn cirterion.
#
AdvancedHMC.isterminated
— Method
isterminated(_, h, t)
Detect U turn for two phase points (zleft
and zright
) under given Hamiltonian h
using the generalised no-U-turn criterion.
#
AdvancedHMC.isterminated
— Method
isterminated(tc, h, t, tleft, tright)
Detect U turn for two phase points (zleft
and zright
) under given Hamiltonian h
using the generalised no-U-turn criterion with additional U-turn checks.
#
AdvancedHMC.maxabs
— Method
maxabs(a, b)
Return the value with the largest absolute value.
#
AdvancedHMC.mh_accept_ratio
— Method
Perform MH acceptance based on energy, i.e. negative log probability.
#
AdvancedHMC.nom_step_size
— Method
nom_step_size(::AbstractIntegrator)
Get the nominal integration step size. The current integration step size may differ from this, for example if the step size is jittered. Nominal step size is usually used in adaptation.
#
AdvancedHMC.pm_next!
— Method
Progress meter update with all trajectory stats, iteration number and metric shown.
#
AdvancedHMC.randcat
— Method
randcat(rng, P::AbstractMatrix)
Generating Categorical random variables in a vectorized mode. P
is supposed to be a matrix of (D, N) where each column is a probability vector.
Example
P = [ 0.5 0.3; 0.4 0.6; 0.1 0.1 ] u = [0.3, 0.4] C = [ 0.5 0.3 0.9 0.9 1.0 1.0 ]
Then C .< u'
is
[ 0 1 0 0 0 0 ]
thus convert.(Int, vec(sum(C .< u'; dims=1))) .+ 1
equals [1, 2]
.
#
AdvancedHMC.sampler_eltype
— Function
sampler_eltype(sampler)
Return the element type of the sampler.
#
AdvancedHMC.simple_pm_next!
— Method
Simple progress meter update without any show values.
#
AdvancedHMC.stat
— Method
Returns the statistics for transition t
.
#
AdvancedHMC.step_size
— Function
step_size(::AbstractIntegrator)
Get the current integration step size.
#
AdvancedHMC.temper
— Method
temper(lf::TemperedLeapfrog, r, step::NamedTuple{(:i, :is_half),<:Tuple{Integer,Bool}}, n_steps::Int)
Tempering step. step
is a named tuple with
-
i
being the current leapfrog iteration and -
is_half
indicating whether or not it’s (the first) half momentum/tempering step
#
AdvancedHMC.transition
— Method
transition(τ, h, z)
Make a MCMC transition from phase point z
using the trajectory τ
under Hamiltonian h
.
This is a RNG-implicit fallback function for transition(GLOBAL_RNG, τ, h, z)
|
#
AdvancedHMC.update_nom_step_size
— Function
update_nom_step_size(i::AbstractIntegrator, ϵ) -> AbstractIntegrator
Return a copy of the integrator i
with the new nominal step size (nom_step_size
) ϵ
.
#
StatsBase.sample
— Method
sample(
rng::AbstractRNG,
h::Hamiltonian,
κ::AbstractMCMCKernel,
θ::AbstractVecOrMat{T},
n_samples::Int,
adaptor::AbstractAdaptor=NoAdaptation(),
n_adapts::Int=min(div(n_samples, 10), 1_000);
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 of1_000
and 10% ofn_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
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)
#
AdvancedHMC.AbstractTrajectorySampler
— Type
How to sample a phase-point from the simulated trajectory.
#
AdvancedHMC.BinaryTree
— Type
A full binary tree trajectory with only necessary leaves and information stored.
#
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
-
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)
#
AdvancedHMC.EndPointTS
— Type
Samples the end-point of the trajectory.
#
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. takefloor(λ / integrator_step_size)
number of leapfrog steps.
References
-
Neal, R. M. (2011). MCMC using Hamiltonian dynamics. Handbook of Markov chain Monte Carlo, 2(11), 2. (arXiv)
#
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 beL + 1
.
References
-
Neal, R. M. (2011). MCMC using Hamiltonian dynamics. Handbook of Markov chain Monte Carlo, 2(11), 2. (arXiv)
#
AdvancedHMC.FullMomentumRefreshment
— Type
Completly resample new momentum.
#
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
-
Betancourt, M. (2017). A Conceptual Introduction to Hamiltonian Monte Carlo. arXiv preprint arXiv:1701.02434.
#
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 aSymbol
orAbstractIntegrator
-
metric
: Choice of initial metric;Symbol
means it is automatically initialised. The metric type will be preserved during automatic initialisation and adaption.
#
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 aSymbol
orAbstractIntegrator
-
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.
#
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
: Ifprogress
is not specified and this istrue
some information will be logged upon completion of adaptation. -
num_divergent_transitions
: Number of divergent transitions fo far. -
num_divergent_transitions_during_adaption
#
AdvancedHMC.HMCSampler
— Type
HMCSampler
An AbstractMCMC.AbstractSampler
for kernels in AdvancedHMC.jl.
Fields
-
metric
: Choice of initial metricAbstractMetric
. The metric type will be preserved during adaption. -
adaptor
:AbstractAdaptor
.
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
.
#
AdvancedHMC.HMCState
— Type
HMCState
Represents the state of a HMCSampler
.
Fields
-
i
: Index of current iteration. -
transition
: CurrentTransition
. -
metric
: CurrentAbstractMetric
, possibly adapted. -
κ
: CurrentAbstractMCMCKernel
. -
adaptor
: CurrentAbstractAdaptor
.
#
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
-
Neal, R. M. (2011). MCMC using Hamiltonian dynamics. Handbook of Markov chain Monte Carlo, 2(11), 2. (arXiv)
#
AdvancedHMC.Leapfrog
— Type
struct Leapfrog{T<:(Union{AbstractVector{var"#s29"}, var"#s29"} where var"#s29"<:AbstractFloat)} <: AdvancedHMC.AbstractLeapfrog{T<:(Union{AbstractVector{var"#s29"}, var"#s29"} where var"#s29"<:AbstractFloat)}
Leapfrog integrator with fixed step size ϵ
.
Fields
-
ϵ::Union{AbstractVector{var"#s29"}, var"#s29"} where var"#s29"<:AbstractFloat
: Step size.
#
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 candidatePhasePoint
. -
ℓw::AbstractFloat
: Total energy for the given tree, i.e. the sum of energies of all leaves.
#
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.
#
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.
#
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 aSymbol
orAbstractIntegrator
-
metric
: Choice of initial metric;Symbol
means it is automatically initialised. The metric type will be preserved during automatic initialisation and adaption.
#
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
-
Neal, Radford M. "MCMC using Hamiltonian dynamics." Handbook of markov chain monte carlo 2.11 (2011): 2.
#
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 candidatePhasePoint
. -
ℓu::AbstractFloat
: Slice variable in log-space. -
n::Int64
: Number of acceptable candidates, i.e. those with probability larger than slice variableu
.
#
AdvancedHMC.SliceTS
— Method
struct SliceTS{F<:AbstractFloat} <: AdvancedHMC.AbstractTrajectorySampler
Slice sampler for the starting single leaf tree. Slice variable is initialized.
#
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.
#
AdvancedHMC.StrictGeneralisedNoUTurn
— Type
struct StrictGeneralisedNoUTurn{F<:AbstractFloat} <: AdvancedHMC.DynamicTerminationCriterion
Generalised No-U-Turn criterion as described in Section A.4.2 in [1] with added U-turn check as described in [2].
Fields
-
max_depth::Int64
-
Δ_max::AbstractFloat
References
-
Betancourt, M. (2017). A Conceptual Introduction to Hamiltonian Monte Carlo. arXiv preprint arXiv:1701.02434.
#
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.
#
AdvancedHMC.Termination
— Type
Termination
Termination reasons
-
dynamic
: due to stoping criteria -
numerical
: due to large energy deviation from starting (possibly numerical errors)
#
AdvancedHMC.Termination
— Method
Termination(s, nt, H0, H′)
Check termination of a Hamiltonian trajectory.
#
AdvancedHMC.Termination
— Method
Termination(s, nt, H0, H′)
Check termination of a Hamiltonian trajectory.
#
AdvancedHMC.Trajectory
— Type
struct Trajectory{TS<:AdvancedHMC.AbstractTrajectorySampler, I<:AdvancedHMC.AbstractIntegrator, TC<:AdvancedHMC.AbstractTerminationCriterion}
Numerically simulated Hamiltonian trajectories.
#
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.