Main Content

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

expand all

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.

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

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'

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

ValueDescription
'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'

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

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

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

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.

HeadingDescription
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

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

expand all

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

Tuning information, returned as a structure with these fields.

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

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

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

FieldDescription
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

expand all

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

Version History

Introduced in R2017a