Main Content

hmcSampler

ハミルトニアン モンテカルロ (HMC) サンプラー

ページ内をすべて折りたたむ

構文

hmc = hmcSampler(logpdf,startpoint)
hmc = hmcSampler(___,Name,Value)

説明

例

hmc = hmcSampler(logpdf,startpoint) は、ハミルトニアン モンテカルロ (HMC) サンプラーを作成し、HamiltonianSampler オブジェクトとして返します。logpdf は、平衡分布の確率密度の対数およびその勾配を評価する関数ハンドルです。列ベクトル startpoint は、HMC サンプリングを開始する初期点です。

サンプラーの作成後、HamiltonianSampler クラスのメソッドを使用して、MAP (最大事後確率) 点推定の計算、サンプラーの調整、標本の抽出、収束診断のチェックを行うことができます。このワークフローの例については、ハミルトニアン モンテカルロの使用によるベイズ線形回帰を参照してください。

hmc = hmcSampler(___,Name,Value) では、1 つ以上の名前と値のペアの引数を使用して追加オプションを指定します。名前と値のペアの引数は、他のすべての入力引数の後で指定します。

例

すべて折りたたむ

ライブ スクリプトを開く

ハミルトニアン モンテカルロ (HMC) サンプラーを作成して、正規分布からサンプリングします。

はじめに、多変量正規対数確率密度およびその勾配を返す関数 normalDistGrad を MATLAB® パス上に保存します (normalDistGrad はこの例の終わりで定義します)。次に、引数を指定してこの関数を呼び出し、関数 hmcSampler の入力引数 logpdf を定義します。

means = [1;-3];
standevs = [1;2];
logpdf = @(theta)normalDistGrad(theta,means,standevs);

HMC サンプラーの開始点を選択します。

startpoint = randn(2,1);

HMC サンプラーを作成し、そのプロパティを表示します。

smp = hmcSampler(logpdf,startpoint);
smp
smp = 
  HamiltonianSampler with properties:

                  StepSize: 0.1000
                  NumSteps: 50
                MassVector: [2x1 double]
              JitterMethod: 'jitter-both'
      StepSizeTuningMethod: 'dual-averaging'
    MassVectorTuningMethod: 'iterative-sampling'
                    LogPDF: @(theta)normalDistGrad(theta,means,standevs)
             VariableNames: {2x1 cell}
                StartPoint: [2x1 double]

関数 normalDistGrad は、startpoint と同じ長さの列ベクトルまたはスカラーとして指定された Mu に格納されている平均および Sigma に格納されている標準偏差を使用して、多変量正規確率密度の対数を返します。2 番目の出力引数は、対応する勾配です。

function [lpdf,glpdf] = normalDistGrad(X,Mu,Sigma)
Z = (X - Mu)./Sigma;
lpdf = sum(-log(Sigma) - .5*log(2*pi) - .5*(Z.^2));
glpdf = -Z./Sigma;
end

入力引数

すべて折りたたむ

目標密度の対数とその勾配。関数ハンドルを指定します。

logpdf は、[lpdf,glpdf] = logpdf(X) である 2 つの出力引数を返さなければなりません。ここで、lpdf は e を底とする (最大で加算定数までの) 対数確率密度、glpdf は対数密度の勾配、点 X は startpoint と同じ要素数の列ベクトルです。

logpdf の入力引数 X は制約なしでなければなりません。つまり、X のどの要素も任意の実数をとり得ます。HMC サンプラーの使用前に制約付きサンプリング パラメーターを制約なしの変数に変換してください。

'UseNumericalGradient' の値が true に設定された場合、logpdf は 2 番目の出力として勾配を返す必要はありません。数値勾配を使用する方が logpdf による勾配計算が不要になるため簡単になる可能性がありますが、サンプリング速度が落ちる場合もあります。

データ型: function_handle

サンプリングを開始する初期点。数値列ベクトルを指定します。

データ型: single | double

名前と値の引数

オプションの引数のペアを Name1=Value1,...,NameN=ValueN として指定します。ここで Name は引数名、Value は対応する値です。名前と値の引数は他の引数の後ろにする必要がありますが、ペアの順序は関係ありません。

R2021a より前では、名前と値をそれぞれコンマを使って区切り、Name を引用符で囲みます。

例: 'VariableNames',{'Intercept','Beta'},'MassVectorTuningMethod','hessian' は、サンプリング変数の名前と、質量ベクトルの調整法として 'hessian' を指定します。

ハミルトニアン ダイナミクスのステップ サイズ。'StepSize' と正のスカラーから構成されるコンマ区切りのペアとして指定します。

マルコフ連鎖の新しい状態を提案するため、HMC サンプラーはリープフロッグ法を使用してハミルトニアン ダイナミクスを積分します。この引数は、リープフロッグ法のステップ サイズを抑制します。

ステップ サイズは、tuneSampler を使用して自動的に調整できます。

例: 'StepSize',0.2

データ型: single | double

ハミルトニアン ダイナミクスのステップ数。'NumSteps' と正の整数から構成されるコンマ区切りのペアとして指定します。

マルコフ連鎖の新しい状態を提案するため、HMC サンプラーはリープフロッグ法を使用してハミルトニアン ダイナミクスを積分します。この引数は、リープフロッグ法のステップ数を抑制します。

ステップ数は、tuneSampler を使用して自動的に調整できます。

例: 'NumSteps',20

データ型: single | double

運動量変数の質量ベクトル。'MassVector' と、正の値をもち長さが startpoint に等しい数値列ベクトルから構成されるコンマ区切りのペアとして指定します。

目的の変数に関連する運動量変数の "質量" は、マルコフ連鎖の各提案でハミルトニアン ダイナミクスを抑制します。

質量ベクトルは、tuneSampler を使用して自動的に調整できます。

例: 'MassVector',rand(3,1)

データ型: single | double

ステップ サイズとステップ数の微変動方法。'JitterMethod' と次のいずれかの値から構成されるコンマ区切りのペアとして指定します。

値説明
'jitter-both'

各リープフロッグ軌跡についてステップ サイズとステップ数をランダムに微変動させます。

'jitter-numsteps'

各リープフロッグ軌跡のステップ数のみを微変動させます。

'none'

微変動させません。

微変動させる場合、サンプラーは各リープフロッグ軌跡のステップ サイズまたはステップ数として 'StepSize' および 'NumSteps' の値より小さい値を無作為に選択します。微変動を使用すると、ハミルトニアン ダイナミクスに対するリープフロッグ法の安定性が向上します。

例: 'JitterMethod','jitter-both'

サンプラーのステップ サイズの調整方法。'StepSizeTuningMethod' と 'dual-averaging' または 'none' から構成されるコンマ区切りのペアとして指定します。

'StepSizeTuningMethod' の値が 'dual-averaging' に設定された場合、tuneSampler は長さ固定のシミュレーションについて特定の採択比率を実現するように HMC サンプラーのリープフロッグ ステップ サイズを調整します。シミュレーションの長さは、ステップ サイズにステップ数を乗算した値です。目標採択比率を設定するには、tuneSampler メソッドの名前と値のペアの引数 'TargetAcceptanceRatio' を使用します。

例: 'StepSizeTuningMethod','none'

サンプラーの質量ベクトルの調整方法。'MassVectorTuningMethod' と次のいずれかの値から構成されるコンマ区切りのペアとして指定します。

値説明
'iterative-sampling'

一連の推定質量ベクトルを使用して標本を抽出することにより、連続的な近似で MassVector を調整します。

'hessian'

startpoint における logpdf の負の対角ヘッシアンに等しい値に MassVector を設定します。

'none'

MassVector を調整しません。

調整を実行するには、tuneSampler メソッドを使用します。

例: 'MassVectorTuningMethod','hessian'

解析的勾配チェックのフラグ。'CheckGradient' と true (または 1) または false (または 0) のいずれかから構成されるコンマ区切りのペアとして指定します。

'CheckGradient' が true の場合、サンプラーは startpoint における数値勾配を計算し、logpdf によって返された解析的勾配と比較します。

例: 'CheckGradient',true

サンプリング変数の名前。'VariableNames' と string 配列、または文字ベクトルの cell 配列から構成されるコンマ区切りのペアとして指定します。配列の要素は一意でなければなりません。配列の長さは startpoint の長さと同じでなければなりません。

'VariableNames' の値を与えることで、HMC サンプラーを使用してサンプリングするベクトルの成分にラベルを付けます。

例: 'VariableNames',{'Intercept','Beta'}

データ型: string | cell

数値勾配の使用フラグ。'UseNumericalGradient' と true (または 1) または false (または 0) のいずれかから構成されるコンマ区切りのペアとして指定します。

'UseNumericalGradient' の値を true に設定した場合、HMC サンプラーは logpdf によって返される対数密度から勾配を数値的に推定します。この場合、関数 logpdf は 2 番目の出力として対数密度の勾配を返す必要はありません。数値勾配を使用すると、HMC サンプリングが低速になります。

例: 'UseNumericalGradient',true

出力引数

すべて折りたたむ

ハミルトニアン モンテカルロ サンプラー。HamiltonianSampler オブジェクトとして返されます。

バージョン履歴

R2017a で導入

参考

関数

クラス

トピック