tuneSampler
Class: HamiltonianSampler
Tune Hamiltonian Monte Carlo (HMC) sampler
Syntax
tunedSmp = tuneSampler(smp)
[tunedSmp,tuningInfo]
= tuneSampler(smp)
[tunedSmp,tuningInfo]
= tuneSampler(___,Name,Value)
Description
returns
a tuned Hamiltonian Monte Carlo (HMC) sampler.tunedSmp
= tuneSampler(smp
)
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.
[
returns additional
tuning information in tunedSmp
,tuningInfo
]
= tuneSampler(smp
)tuningInfo
.
[
specifies
additional options using one or more name-value pair arguments. Specify
name-value pair arguments after all other input arguments. tunedSmp
,tuningInfo
]
= tuneSampler(___,Name,Value
)
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 |
'hessian' | Set the |
'none' | Perform no tuning of the |
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 |
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 |
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 theHamiltonianSampler
class. For an example of this workflow, see Bayesian Linear Regression Using Hamiltonian Monte Carlo.
Version History
Introduced in R2017a
See Also
Functions
Classes
Open Example
You have a modified version of this example. Do you want to open this example with your edits?
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)