tuneSampler

Class: HamiltonianSampler

Tune Hamiltonian Monte Carlo (HMC) sampler

Syntax

tunedSmp = tuneSampler(smp)
[tunedSmp,tuningInfo] = tuneSampler(smp)
[tunedSmp,tuningInfo] = tuneSampler(___,Name,Value)


Description

tunedSmp = tuneSampler(smp) returns a tuned Hamiltonian Monte Carlo (HMC) sampler.

First, tuneSampler tunes the mass vector of the HMC sampler smp. Then, it tunes the step size and number of steps of the leapfrog integrations to achieve a certain target acceptance ratio.

You can use the tuned sampler to create Markov chains using the drawSamples method.

[tunedSmp,tuningInfo] = tuneSampler(smp) returns additional tuning information in tuningInfo.

[tunedSmp,tuningInfo] = tuneSampler(___,Name,Value) specifies additional options using one or more name-value pair arguments. Specify name-value pair arguments after all other input arguments.

Input Arguments

smp — Hamiltonian Monte Carlo sampler

HamiltonianSampler object

Hamiltonian Monte Carlo sampler to tune, specified as a HamiltonianSampler object.

Use the hmcSampler function to create a sampler.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: 'StepSizeTuningMethod','dual-averaging','MassVectorTuningMethod','hessian' tunes an HMC sampler using the specified methods for tuning the step size and mass vector of the sampler.

StartPoint — Initial point to start tuning from

smp.StartPoint (default) | numeric column vector

Initial point to start tuning from, specified as a numeric column vector with the same number of elements as the StartPoint property of the sampler smp.

Example: 'StartPoint',randn(size(smp.StartPoint))

StepSizeTuningMethod — Method for tuning sampler step size

smp.StepSizeTuningMethod (default) | 'dual-averaging' | 'none'

Method for tuning sampler step size, specified as the comma-separated pair consisting of 'StepSizeTuningMethod' and 'dual-averaging' or 'none'.

If 'StepSizeTuningMethod' is set to 'dual-averaging', then tuneSampler tunes the leapfrog step size of the HMC sampler to achieve a target acceptance ratio for a fixed value of the simulation length. The simulation length equals the step size multiplied by the number of steps. To specify the target acceptance ratio, set the 'TargetAcceptanceRatio' value.

To change the simulation length, set smp.StepSize = a and smp.NumSteps = b, for some values of a and b. This gives a simulation length of a*b.

Example: 'StepSizeTuningMethod','none'

MassVectorTuningMethod — Method for tuning sampler mass vector

smp.MassVectorTuningMethod (default) | 'iterative-sampling' | 'hessian' | 'none'

Method for tuning the sampler mass vector, specified as the comma-separated pair consisting of 'MassVectorTuningMethod' and one of the following values.

Value	Description
'iterative-sampling'	Tune the MassVector via successive approximations by drawing samples using a sequence of mass vector estimates.
'hessian'	Set the MassVector equal to the negative diagonal Hessian of the logpdf at the startpoint.
'none'	Perform no tuning of the MassVector.

Example: 'MassVectorTuningMethod','hessian'

NumStepSizeTuningIterations — Number of step size tuning iterations

100 (default) | positive integer

Number of step size tuning iterations, specified as a positive integer.

If the 'StepSizeTuningMethod' value is 'none', then tuneSampler does not tune the step size.

Example: 'NumStepSizeTuningIterations',50

TargetAcceptanceRatio — Target acceptance ratio

0.65 (default) | scalar from 0 through 1

Target acceptance ratio of the Markov chain, specified as a scalar from 0 through 1.

tuneSampler tunes the step size and number of steps of the leapfrog integration to achieve the specified target acceptance ratio for a fixed value of the simulation length. The simulation length is the leapfrog integration step size multiplied by the number of integration steps.

If the 'StepSizeTuningMethod' value is 'none', then tuneSampler does not tune the step size.

To change the simulation length, set smp.StepSize = a and smp.NumSteps = b, for some values of a and b. This gives a simulation length of a*b.

Example: 'TargetAcceptanceRatio',0.55

NumStepsLimit — Maximum number of leapfrog steps

2000 (default) | positive integer

Maximum number of leapfrog steps allowed during step size tuning, specified as a positive integer.

If the 'StepSizeTuningMethod' value is 'none', then tuneSampler does not tune the step size.

Example: 'NumStepsLimit',1000

VerbosityLevel — Verbosity level of Command Window output

0 (default) | nonnegative integer

Verbosity level of Command Window output during sampler tuning, specified as a nonnegative integer.

• With the value set to 0, tuneSampler displays no details of the tuning.

• With the value set to 1, tuneSampler displays details of the step size tuning.

• With the value set to 2 or larger, tuneSampler displays details of the step size and mass vector tuning.

Heading	Description
ITER	Iteration number.
LOG PDF	Log probability density at the current iteration.
STEP SIZE	Leapfrog integration step size at the current iteration.
NUM STEPS	Number of leapfrog integration steps at the current iteration.
ACC RATIO	Acceptance ratio, that is, the fraction of proposals which are accepted.
DIVERGENT	Number of times the sampler failed to generate a valid proposal due to the leapfrog iterations generating NaNs or Infs. tuneSampler searches for a good value of the integration step size. While doing so, the algorithm can encounter regions of instability and report nonzero values in the DIVERGENT column. This behavior is normal and is not a problem in itself.

Example: 'VerbosityLevel',1

NumPrint — Verbose output frequency

100 (default) | positive integer

Verbose output frequency, specified as a positive integer.

If the 'VerbosityLevel' value is a positive integer, tuneSampler outputs tuning details every 'NumPrint' iterations.

Example: 'NumPrint',50

Output Arguments

tunedSmp — Tuned Hamiltonian Monte Carlo sampler

HamiltonianSampler object

Tuned Hamiltonian Monte Carlo sampler, returned as a HamiltonianSampler object.

tuningInfo — Tuning information

structure

Tuning information, returned as a structure with these fields.

Field	Description
MassVector	Tuned mass vector
StepSize	Tuned leapfrog step size
NumSteps	Tuned value of the number of leapfrog integration steps
MassVectorTuningInfo	Structure with additional information on the mass vector tuning
StepSizeTuningInfo	Structure with additional information on the step size tuning

If you tune the mass vector using the 'iterative-sampling' method, then MassVectorTuningInfo has the following fields.

Field	Description
MassVector	Tuned mass vector
IterativeSamplingMassVectorProfile	P-by-K matrix of mass vectors used during the K iterations, where P is the number of sampling variables
IterativeSamplingNumSamples	K-by-1 vector of the number of samples drawn for each of the K iterations

If you tune the mass vector using the 'hessian' method, then MassVectorTuningInfo has the following fields.

Field	Description
MassVector	Tuned mass vector
NegativeDiagonalHessian	Negative diagonal Hessian of logpdf at the tuning start point. If some elements are negative, this field can be different from the MassVector field.
HessianPoint	Point at which the Hessian is evaluated

If the MassVectorTuningMethod value is 'none', then MassVectorTuningInfo is empty.

If you tune the step size using the 'dual-averaging' method, then StepSizeTuningInfo has the following fields.

Field	Description
StepSize	Tuned step size
NumSteps	Tuned value of the number of steps
StepSizeProfile	Column vector containing the step sizes at each tuning iteration
AcceptanceRatio	Final acceptance ratio achieved during tuning

If the step size is not tuned, thenStepSizeTuningInfo is empty.

Data Types: struct

Examples

Tune Hamiltonian Monte Carlo Sampler

Tune the parameters of a Hamiltonian Monte Carlo (HMC) sampler.

Define the number of parameters to sample and their means.

NumParams = 9;
means = [1:NumParams]';
standevs = 1;

First, save a function normalDistGrad on the MATLAB® path that returns the multivariate normal log probability density and its gradient (normalDistGrad is defined at the end of this example). Then, call the function with arguments to define the logpdf input argument to the hmcSampler function.

logpdf = @(theta)normalDistGrad(theta,means,standevs);

Choose a starting point and create the HMC sampler.

startpoint = randn(NumParams,1);
smp = hmcSampler(logpdf,startpoint);

It is important to select good values for the sampler parameters to get efficient sampling. The best way to find good values is to automatically tune the MassVector, StepSize, and NumSteps parameters using tuneSampler. The method:

1. Tunes the MassVector of the sampler.

2. Tunes StepSize and NumSteps for a fixed simulation length to achieve a certain acceptance ratio. The default target acceptance ratio of 0.65 is good in most cases.

[smp,info] = tuneSampler(smp,'NumStepSizeTuningIterations',50,'VerbosityLevel',1,'NumPrint',10);

o Tuning mass vector using method: iterative-sampling 
Finished mass vector tuning iteration 1 of 5. 
Finished mass vector tuning iteration 2 of 5. 
Finished mass vector tuning iteration 3 of 5. 
Finished mass vector tuning iteration 4 of 5. 
Finished mass vector tuning iteration 5 of 5. 

o Tuning step size using method: dual-averaging. Target acceptance ratio = 0.65

o Initial step size for dual-averaging = 2

|==================================================================================|
|   ITER   |    LOG PDF    |  STEP SIZE  |  NUM STEPS  |  ACC RATIO  |  DIVERGENT  |
|==================================================================================|
|       10 | -1.710457e+01 |   1.193e+00 |           4 |   5.000e-01 |           0 |
|       20 | -9.152514e+00 |   9.527e-01 |           5 |   5.500e-01 |           0 |
|       30 | -1.068923e+01 |   8.856e-01 |           6 |   5.333e-01 |           0 |
|       40 | -1.290816e+01 |   8.506e-01 |           6 |   5.750e-01 |           0 |
|       50 | -1.770386e+01 |   8.581e-01 |           6 |   6.000e-01 |           0 |

Plot the evolution of the step size during tuning to ensure that the step size tuning has converged. Display the achieved acceptance ratio.

figure;
plot(info.StepSizeTuningInfo.StepSizeProfile);
xlabel('Iteration');
ylabel('Step Size');

accratio = info.StepSizeTuningInfo.AcceptanceRatio

accratio = 
0.6000

The normalDistGrad function returns the logarithm of the multivariate normal probability density with means in Mu and standard deviations in Sigma, specified as scalars or columns vectors the same length as startpoint. The second output argument is the corresponding gradient.

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

Tips

• After creating an HMC sampler using the hmcSampler function, you can compute MAP (maximum-a-posteriori) point estimates, tune the sampler, draw samples, and check convergence diagnostics using the methods of the HamiltonianSampler class. For an example of this workflow, see Bayesian Linear Regression Using Hamiltonian Monte Carlo.

Version History

Introduced in R2017a