The Turing Language GitHub Repo stars Twitter Follow

AdvancedHMC.jl

Index

Functions

AdvancedHMC.AMethod

A single Hamiltonian integration step.

NOTE: this function is intended to be used in find_good_stepsize only.

AdvancedHMC.check_left_subtreeMethod

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_subtreeMethod
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.combineMethod
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.isterminatedMethod
isterminated(_, h, t)

Detect U turn for two phase points (zleft and zright) under given Hamiltonian h using the (original) no-U-turn cirterion.

Ref: https://arxiv.org/abs/1111.4246, https://arxiv.org/abs/1701.02434

AdvancedHMC.isterminatedMethod
isterminated(_, h, t)

Detect U turn for two phase points (zleft and zright) under given Hamiltonian h using the generalised no-U-turn criterion.

Ref: https://arxiv.org/abs/1701.02434

AdvancedHMC.isterminatedMethod
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.

Ref: https://arxiv.org/abs/1701.02434 https://github.com/stan-dev/stan/pull/2800

AdvancedHMC.maxabsMethod
maxabs(a, b)

Return the value with the largest absolute value.

AdvancedHMC.nom_step_sizeMethod
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.randcatMethod
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.temperMethod
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.transitionMethod
transition(τ, h, z)

Make a MCMC transition from phase point z using the trajectory τ under Hamiltonian h.

NOTE: This is a RNG-implicit fallback function for transition(GLOBAL_RNG, τ, h, z)

StatsBase.sampleMethod
sample(model::AdvancedHMC.DifferentiableDensityModel, kernel::AdvancedHMC.AbstractMCMCKernel, metric::AdvancedHMC.AbstractMetric, adaptor::AdvancedHMC.Adaptation.AbstractAdaptor, N::Integer; kwargs...) -> Any

A convenient wrapper around AbstractMCMC.sample avoiding explicit construction of HMCSampler.

StatsBase.sampleMethod
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 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

Types

AdvancedHMC.AbstractIntegratorType
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.BinaryTreeType

A full binary tree trajectory with only necessary leaves and information stored.

AdvancedHMC.ClassicNoUTurnType
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)
AdvancedHMC.DifferentiableDensityModelType
DifferentiableDensityModel(ℓπ, ∂ℓπ∂θ)
DifferentiableDensityModel(ℓπ, m::Module)

A AbstractMCMC.AbstractMCMCModel representing a differentiable log-density.

If a module m is given as the second argument, then m is assumed to be an automatic-differentiation package and this will be used to compute the gradients.

Note that the module m must be imported before usage, e.g.

using Zygote: Zygote
model = DifferentiableDensityModel(ℓπ, Zygote)

results in a model which will use Zygote.jl as its AD-backend.

Fields

  • ℓπ

    Log-density. Maps AbstractArray to value of the log-density.

  • ∂ℓπ∂θ

    Gradient of log-density. Returns a tuple of ℓπ and the gradient evaluated at the given point.

AdvancedHMC.FixedIntegrationTimeType
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)
AdvancedHMC.FixedNStepsType
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)
AdvancedHMC.GeneralisedNoUTurnType
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.
AdvancedHMC.HMCProgressCallbackType
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.

AdvancedHMC.HMCSamplerType
HMCSampler

A 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.

AdvancedHMC.JitteredLeapfrogType
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)
AdvancedHMC.LeapfrogType
struct Leapfrog{T<:(Union{AbstractVector{var"#s67"}, var"#s67"} where var"#s67"<:AbstractFloat)} <: AdvancedHMC.AbstractLeapfrog{T<:(Union{AbstractVector{var"#s67"}, var"#s67"} where var"#s67"<:AbstractFloat)}

Leapfrog integrator with fixed step size ϵ.

Fields

  • ϵ::Union{AbstractVector{var"#s67"}, var"#s67"} where var"#s67"<:AbstractFloat

    Step size.

AdvancedHMC.MultinomialTSType
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.

AdvancedHMC.MultinomialTSMethod
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.MultinomialTSMethod
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

AdvancedHMC.NUTSMethod
NUTS(int, args; kwargs...)

Convenient constructor for the no-U-turn sampler (NUTS). This falls back to HMCKernel(Trajectory{TS}(int, TC(args...; kwargs...))) where

  • TS<:Union{MultinomialTS, SliceTS} is the type for trajectory sampler
  • TC<:Union{ClassicNoUTurn, GeneralisedNoUTurn, StrictGeneralisedNoUTurn} is the type for termination criterion.

See ClassicNoUTurn, GeneralisedNoUTurn and StrictGeneralisedNoUTurn for details in parameters.

AdvancedHMC.PartialMomentumRefreshmentType

Partial momentum refreshment with refresh rate α.

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.
AdvancedHMC.SliceTSType
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.

AdvancedHMC.SliceTSMethod
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.SliceTSMethod
struct SliceTS{F<:AbstractFloat} <: AdvancedHMC.AbstractTrajectorySampler

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

AdvancedHMC.TemperedLeapfrogType
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.TerminationType
Termination

Termination reasons

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

Numerically simulated Hamiltonian trajectories.

AdvancedHMC.TransitionType
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.