Документация Engee

Справка по AdvancedHMC

Указатель

Функции

Один шаг интеграции гамильтониана.

ПРИМЕЧАНИЕ. Эта функция предназначена для использования только в find_good_stepsize.

Рекурсивно строит дерево для заданной глубины j.

check_left_subtree(h, t, tleft, tright)

Выполняет проверку разворота между самой левой фазовой точкой t и самой левой фазовой точкой tright правого поддерева.

check_right_subtree(h, t, tleft, tright)

Выполняет проверку разворота между самой правой фазовой точкой t и самой правой фазовой точкой tleft левого поддерева.

combine(treeleft, treeright)

Объединяет левое дерево treeleft и правое дерево treeright при заданном гамильтониане h, затем делает новую выборку кандидатов и обновляет связанные статистики для полученного дерева.

determine_sampler_eltype(xs...)

Определяет тип элемента, который следует использовать для заданных аргументов.

Символы либо преобразуются к типу float по умолчанию, либо просто отбрасываются в пользу определенных типов из других аргументов.

Находит хороший начальный размер шага с перешагиванием с помощью эвристического поиска.

isterminated(_, h, t)

Определяет разворот для двух фазовых точек (zleft и zright) при заданном гамильтониане h, используя (оригинальный) критерий без разворота.

Справка: https://arxiv.org/abs/1111.4246, https://arxiv.org/abs/1701.02434

isterminated(_, h, t)

Определяет разворот для двух фазовых точек (zleft и zright) при заданном гамильтониане h, используя обобщенный критерий без разворота.

Справка: https://arxiv.org/abs/1701.02434

isterminated(tc, h, t, tleft, tright)

Определяет разворот для двух фазовых точек (zleft и zright) при заданном гамильтониане h, используя обобщенный критерий без разворота с дополнительными проверками разворота.

Справка: https://arxiv.org/abs/1701.02434 https://github.com/stan-dev/stan/pull/2800

maxabs(a, b)

Возвращает значение с наибольшим абсолютным значением.

Выполняет принятие MH на основе энергии, т. е. отрицательной логарифмической вероятности.

nom_step_size(::AbstractIntegrator)

Получает номинальный размер шага интеграции. Текущий размер шага интеграции может отличаться от него, например, если размер шага колеблется. Номинальный размер шага обычно используется при адаптации.

Обновляет индикатор хода выполнения с отображением всех статистических данных траектории, номера итерации и метрики.

randcat(rng, P::AbstractMatrix)

Генерирует категориальные случайные переменные в векторном режиме. Предполагается, что P — это матрица (D, N), где каждый столбец является вектором вероятности.

Пример

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
]

Тогда C .< u' — это

[
    0 1
    0 0
    0 0
]

таким образом, convert.(Int, vec(sum(C .< u'; dims=1))) .+ 1 равно [1, 2].

sampler_eltype(sampler)

Возвращает тип элемента сэмплера.

Простое обновление индикатора хода выполнения без отображения значений.

Возвращает статистики для перехода t.

step_size(::AbstractIntegrator)

Получает текущий размер шага интеграции.

temper(lf::TemperedLeapfrog, r, step::NamedTuple{(:i, :is_half),<:Tuple{Integer,Bool}}, n_steps::Int)

Шаг выравнивания. step является именованным кортежем, где

  • i — текущая итерация перешагивания и

  • is_half указывает, является ли это (первым) полушагом импульса или выравнивания.

transition(τ, h, z)

Выполняет переход MCMC из фазовой точки z, используя траекторию τ при заданном гамильтониане h.

ПРИМЕЧАНИЕ. Это RNG-неявная резервная функция для transition(GLOBAL_RNG, τ, h, z).

update_nom_step_size(i::AbstractIntegrator, ϵ) -> AbstractIntegrator

Возвращает копию интегратора i с новым номинальным размером шага (nom_step_size) ϵ.

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
)

Выбирает n_samples образцов, используя предложение κ при заданном гамильтониане h.

  • Случайность регулируется с помощью rng.

    • Если rng не задан, будет использоваться GLOBAL_RNG.

  • Начальная точка задается с помощью θ.

  • Адаптор задается с помощью adaptor, для которого значением по умолчанию является отсутствие адаптации.

    • Он выполнит n_adapts шагов адаптации, для которых по умолчанию используется минимальное значение 1_000, и 10 % от n_samples.

  • drop_warmup определяет, отбрасывать ли образцы во время фазы адаптации.

  • verbose управляет уровнем детализации.

  • progress определяет, показывать ли индикатор хода выполнения.

Типы

abstract type AbstractIntegrator

Представляет собой интегратор, используемый для моделирования гамильтоновой системы.

Реализация

Ожидается, что AbstractIntegrator будет иметь следующие реализации:

  • stat(@ref)

  • nom_step_size(@ref)

  • step_size(@ref)

Как выбрать фазовую точку из моделируемой траектории.

Полная траектория бинарного дерева с хранимыми необходимыми листьями и информацией.

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

Классический критерий без разворота, описанный в Eq. (9) в [1].

Неформально, расширение траектории будет завершено, если при продолжении моделирования вперед или назад во времени уменьшится расстояние между крайней левой и крайней правой позициями.

Поля

  • max_depth::Int64

  • Δ_max::AbstractFloat

Ссылки

  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)

Выбирает конечную точку траектории.

struct FixedIntegrationTime{F<:AbstractFloat} <: AdvancedHMC.StaticTerminationCriterion

Стандартная реализация HMC с фиксированным временем интеграции.

Поля

  • λ::AbstractFloat: общая длина траектории, т. е. сделать floor(λ / integrator_step_size) количество шагов с перешагиванием.

Ссылки

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

struct FixedNSteps <: AdvancedHMC.StaticTerminationCriterion

Статический HMC с фиксированным числом шагов с перешагиванием.

Поля

  • L::Int64: количество шагов для моделирования, т. е. длина траектории будет равна L + 1.

Ссылки

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

Полностью повторно выполняет выборку нового импульса.

struct GeneralisedNoUTurn{F<:AbstractFloat} <: AdvancedHMC.DynamicTerminationCriterion

Обобщенный критерий без разворота, как описано в разделе A.4.2 в [1].

Поля

  • max_depth::Int64

  • Δ_max::AbstractFloat

Ссылки

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

HMC(ϵ::Real, n_leapfrog::Int)

Сэмплер гамильтониана Монте-Карло со статической траекторией.

Поля

  • n_leapfrog: количество шагов с перешагиванием.

  • integrator: выбор интегратора, заданный либо с помощью Symbol, либо AbstractIntegrator.

  • metric: выбор начальной метрики; Symbol означает, что она инициализируется автоматически. Тип метрики будет сохранен во время автоматической инициализации и адаптации.

HMCDA(δ::Real, λ::Real, integrator = :leapfrog, metric = :diagonal)

Сэмплер гамильтониана Монте-Карло с алгоритмом двойного среднего.

Поля

  • δ: целевой коэффициент принятия для двойного среднего.

  • λ: целевая длина перешагивания.

  • integrator: выбор интегратора, заданный либо с помощью Symbol, либо AbstractIntegrator.

  • metric: выбор начальной метрики; Symbol означает, что она инициализируется автоматически. Тип метрики будет сохранен во время автоматической инициализации и адаптации.

Примечания

Дополнительные сведения см. в следующем документе (ссылка на arXiv):

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

HMCProgressCallback

Обратный вызов, который будет использоваться с интерфейсом AbstractMCMC.jl, реплицируя поведение ведения журнала, отличного от AbstractMCMC sample.

Поля

  • pm: индикатор Progress ProgressMeters.jl.

  • progress: указывает, использовать ли отображение индикатора хода выполнения.

  • verbose: если progress не указан и это имеет значение true, по завершении адаптации в журнал будет занесена некоторая информация.

  • num_divergent_transitions: количество расходящихся переходов на данный момент.

  • num_divergent_transitions_during_adaption:

HMCSampler

AbstractMCMC.AbstractSampler для ядер в AdvancedHMC.jl.

Поля

  • κ: AbstractMCMCKernel.

  • metric: выбор начальной метрики AbstractMetric. Тип метрики будет сохранен во время адаптации.

  • adaptor: AbstractAdaptor.

Примечания

Обратите внимание, что все поля имеют префикс initial_, чтобы указать, что они необязательно будут соответствовать kernel, metric и adaptor после выборки.

Для доступа к этим обновленным полям используйте результирующее состояние HMCState.

HMCState

Представляет состояние HMCSampler.

Поля

  • i: индекс текущей итерации.

  • transition: текущий переход (Transition).

  • metric: текущая метрика AbstractMetric, возможно, адаптированная.

  • κ: текущий AbstractMCMCKernel.

  • adaptor: текущий AbstractAdaptor.

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

Интегратор с перешагиванием со случайным колеблющимся размером шага ϵ для каждой траектории.

Поля

  • ϵ0::Union{AbstractVector{FT}, FT} where FT<:AbstractFloat: номинальный (без колебаний) размер шага.

  • jitter::AbstractFloat: доля номинального размера шага ϵ0, которая может быть прибавлена или вычтена.

  • ϵ::Union{AbstractVector{FT}, FT} where FT<:AbstractFloat: текущий (без колебаний) размер шага.

Описание

То же самое, что и LeapFrog(@ref), но с колеблющимся размером шага. То есть в начале каждой траектории мы выбираем размер шага ϵ путем прибавления или вычитания из номинального/базового размера шага ϵ0 некоторой случайной доли ϵ0 причем доля задается jitter, т. е. ϵ = ϵ0 - jitter * ϵ0 * rand(). p Колебание может помочь решить проблемы, связанные с плохим взаимодействием с фиксированным размером шага.

  • В областях с высокой «кривизной» текущий выбор размера шага может привести к перерегулированию, в результате чего почти все шаги будут отклонены. Поэтому случайная выборка размера шага в начале траекторий может увеличить вероятность выхода из таких областей с высокой кривизной.

  • Может иметь место точная периодичность моделируемых траекторий, то есть вам может не повезти, и вы смоделируете траекторию вперед по времени L ϵ и окажетесь в той же точке (что приведет к отсутствию эргодичности; см. раздел 3.2 в [1]). Если импульс обновляется перед каждой траекторией, этого точно не должно происходить, но на практике это все равно может быть проблемой. Случайный выбор размера шага ϵ может помочь избежать таких проблем.

Ссылки

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

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)}

Интегратор с перешагиванием с фиксированным размером шага ϵ.

Поля

  • ϵ::Union{AbstractVector{var"#s29"}, var"#s29"} where var"#s29"<:AbstractFloat: размер шага.

struct MultinomialTS{F<:AbstractFloat} <: AdvancedHMC.AbstractTrajectorySampler

Многочленный сэмплер траектории, используемый при построении дерева. Он содержит вес дерева, определяемый как полные вероятности листьев.

Поля

  • zcand::AdvancedHMC.PhasePoint: выбранный кандидат PhasePoint.

  • ℓw::AbstractFloat: Общая энергия для данного дерева, т. е. сумма энергий всех листьев.

struct MultinomialTS{F<:AbstractFloat} <: AdvancedHMC.AbstractTrajectorySampler

Многочленный сэмплер для начального дерева с одним листом. (Логарифм) веса для узлов листьев — это их (ненормализованные) гамильтоновы энергии.

Справка: https://github.com/stan-dev/stan/blob/develop/src/stan/mcmc/hmc/nuts/base_nuts.hpp#L226

struct MultinomialTS{F<:AbstractFloat} <: AdvancedHMC.AbstractTrajectorySampler

Многочленный сэмплер для траектории, состоящей только из узла листа.

  • Вес дерева — это (ненормализованная) энергия листа.

NUTS(δ::Real; max_depth::Int=10, Δ_max::Real=1000, integrator = :leapfrog, metric = :diagonal)

Сэмплер без разворота (NUTS).

Поля

  • δ: целевой коэффициент принятия для двойного среднего.

  • max_depth: максимальная глубина удвоенного дерева.

  • Δ_max: максимальная дивергенция при удвоении дерева.

  • integrator: выбор интегратора, заданный либо с помощью Symbol, либо AbstractIntegrator.

  • metric: выбор начальной метрики; Symbol означает, что она инициализируется автоматически. Тип метрики будет сохранен во время автоматической инициализации и адаптации.

struct PartialMomentumRefreshment{F<:AbstractFloat} <: AdvancedHMC.AbstractMomentumRefreshment

Частичное обновление импульса с частотой обновления α.

Поля

  • α::AbstractFloat

См. уравнение (5.19) [1],

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

где r — импульс, а G — гауссова случайная величина.

Ссылки

  1. Neal, Radford M., MCMC using Hamiltonian dynamics. Handbook of markov chain monte carlo 2.11 (2011): 2.

struct SliceTS{F<:AbstractFloat} <: AdvancedHMC.AbstractTrajectorySampler

Сэмплер срезов траектории, используемый при построении дерева. Она содержит переменную среза и количество допустимых кандидатов в дереве.

Поля

  • zcand::AdvancedHMC.PhasePoint: выбранный кандидат PhasePoint.

  • ℓu::AbstractFloat: переменная среза в логарифмическом пространстве.

  • n::Int64: количество приемлемых кандидатов, т. е. тех, вероятность которых больше переменной среза u.

struct SliceTS{F<:AbstractFloat} <: AdvancedHMC.AbstractTrajectorySampler

Сэмплер срезов для начального дерева с одним листом. Переменная среза инициализируется.

struct SliceTS{F<:AbstractFloat} <: AdvancedHMC.AbstractTrajectorySampler

Создает сэмплер срезов для дерева с одним листом:

  • переменная среза копируется из переданного сэмплера s, и

  • количество допустимых кандидатов вычисляется путем сравнения переменной среза с текущей энергией.

struct StrictGeneralisedNoUTurn{F<:AbstractFloat} <: AdvancedHMC.DynamicTerminationCriterion

Обобщенный критерий без разворота, как описано в разделе A.4.2 в [1], с добавленной проверкой без разворота, как описано в [2].

Поля

  • max_depth::Int64

  • Δ_max::AbstractFloat

Ссылки

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

  2. https://github.com/stan-dev/stan/pull/2800

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

Интегратор с темперированным перешагиванием с фиксированным размером шага ϵ и «температурой» α.

Поля

  • ϵ::Union{AbstractVector{FT}, FT} where FT<:AbstractFloat: размер шага.

  • α::AbstractFloat: параметр температуры.

Описание

Темперирование потенциально может позволить более эффективно исследовать апостериорное значение, например, в мультимодальном апостериорном значении может быть больше шансов на скачки между модами.

Termination

Причины завершения

  • dynamic: из-за критериев остановки

  • numerical: из-за большого отклонения энергии от начальной (возможно, численные ошибки)

Termination(s, nt, H0, H′)

Проверяет завершение гамильтоновой траектории.

Termination(s, nt, H0, H′)

Проверяет завершение гамильтоновой траектории.

struct Trajectory{TS<:AdvancedHMC.AbstractTrajectorySampler, I<:AdvancedHMC.AbstractIntegrator, TC<:AdvancedHMC.AbstractTerminationCriterion}

Численно смоделированные гамильтоновы траектории.

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

Переход, содержащий фазовую точку и другую статистику перехода.

Поля

  • z::AdvancedHMC.PhasePoint: фазовая точка для перехода.

  • stat::NamedTuple: статистика, связанная с переходом, например энергия.