HamiltonianSampler class
Hamiltonian Monte Carlo (HMC) sampler
Description
A Hamiltonian Monte Carlo (HMC) sampler is a gradientbased Markov Chain Monte Carlo sampler that you can use to generate samples from a probability density P(x). HMC sampling requires specification of log P(x) and its gradient.
The parameter vector x must be unconstrained, meaning that every element of x can be any real number. To sample constrained parameters, transform these parameters into unconstrained variables before using the HMC sampler.
After creating a sampler, you can compute MAP (maximumaposteriori) point estimates, tune the sampler, draw samples, and check convergence diagnostics using the methods of this class. For an example of this workflow, see Bayesian Linear Regression Using Hamiltonian Monte Carlo.
Construction
creates a Hamiltonian Monte Carlo (HMC) sampler, returned as a
hmc
= hmcSampler(logpdf
,startpoint
)HamiltonianSampler
object. logpdf
is a
function handle that evaluates the logarithm of the probability density of the
equilibrium distribution and its gradient. The column vector
startpoint
is the initial point from which to start HMC
sampling.
specifies additional options using one or more namevalue pair arguments. Specify
namevalue pair arguments after all other input arguments.hmc
= hmcSampler(___,Name,Value
)
Input Arguments
logpdf
— Logarithm of target density and its gradient
function handle
Logarithm of target density and its gradient, specified as a function handle.
logpdf
must return two output arguments:
[lpdf,glpdf] = logpdf(X)
. Here,
lpdf
is the basee log probability density (up to
an additive constant), glpdf
is the gradient of the
log density, and the point X
is a column vector with
the same number of elements as startpoint
.
The input argument X
to
logpdf
must be unconstrained, meaning that
every element of X
can be any real number. Transform
any constrained sampling parameters into unconstrained variables before
using the HMC sampler.
If the 'UseNumericalGradient'
value is set to
true
, then logpdf
does not
need to return the gradient as the second output. Using a numerical
gradient can be easier since logpdf
does not need
to compute the gradient, but it can make sampling slower.
Data Types: function_handle
startpoint
— Initial point to start sampling from
numeric column vector
Initial point to start sampling from, specified as a numeric column vector.
Data Types: single
 double
Specify optional pairs of arguments as
Name1=Value1,...,NameN=ValueN
, where Name
is
the argument name and Value
is the corresponding value.
Namevalue 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: 'VariableNames',{'Intercept','Beta'},'MassVectorTuningMethod','hessian'
specifies sampling variable names and the mass vector tuning method to be
'hessian'
.
StepSize
— Step size of Hamiltonian dynamics
0.1
(default)  positive scalar
Step size of Hamiltonian dynamics, specified as the
commaseparated pair consisting of 'StepSize'
and
a positive scalar.
To propose a new state for the Markov chain, the HMC sampler integrates the Hamiltonian dynamics using leapfrog integration. This argument controls the step size of that leapfrog integration.
You can automatically tune the step size using tuneSampler
.
Example: 'StepSize',0.2
NumSteps
— Number of steps of Hamiltonian dynamics
50
(default)  positive integer
Number of steps of Hamiltonian dynamics, specified as the
commaseparated pair consisting of 'NumSteps'
and
a positive integer.
To propose a new state for the Markov chain, the HMC sampler integrates the Hamiltonian dynamics using leapfrog integration. This argument controls the number of steps of that leapfrog integration.
You can automatically tune the number of steps using tuneSampler
.
Example: 'NumSteps',20
MassVector
— Mass vector of momentum variables
ones(size(startpoint,1),1)
(default)  numeric column vector
Mass vector of momentum variables, specified as the
commaseparated pair consisting of 'MassVector'
and a numeric column vector with positive values and the same length
as startpoint
.
The “masses” of the momentum variables associated with the variables of interest control the Hamiltonian dynamics in each Markov chain proposal.
You can automatically tune the mass vector using tuneSampler
.
Example: 'MassVector',rand(3,1)
JitterMethod
— Method for jittering step size and number of steps
'jitterboth'
(default)  'jitternumsteps'
 'none'
Method for jittering the step size and number of steps, specified
as the commaseparated pair consisting of
'JitterMethod'
and one of the following:
Value  Description 

'jitterboth'  Randomly jitter the step size and number of steps for each leapfrog trajectory. 
'jitternumsteps'  Jitter only the number of steps of each leapfrog trajectory. 
'none'  Perform no jittering. 
With jittering, the sampler randomly selects the step size or the
number of steps of each leapfrog trajectory as values smaller than
the 'StepSize'
and 'NumSteps'
values. Use jittering to improve the stability of the leapfrog
integration of the Hamiltonian dynamics.
Example: 'JitterMethod','jitterboth'
StepSizeTuningMethod
— Method for tuning sampler step size
'dualaveraging'
(default)  'none'
Method for tuning the sampler step size, specified as the
commaseparated pair consisting of
'StepSizeTuningMethod'
and
'dualaveraging'
or
'none'
.
If the 'StepSizeTuningMethod'
value is set to
'dualaveraging'
, then tuneSampler
tunes the
leapfrog step size of the HMC sampler to achieve a certain
acceptance ratio for a fixed value of the simulation length. The
simulation length equals the step size multiplied by the number of
steps. To set the target acceptance ratio, use the
'TargetAcceptanceRatio'
namevalue pair
argument of the tuneSampler
method.
Example: 'StepSizeTuningMethod','none'
MassVectorTuningMethod
— Method for tuning sampler mass vector
'iterativesampling'
(default)  'hessian'
 'none'
Method for tuning the sampler mass vector, specified as the
commaseparated pair consisting of
'MassVectorTuningMethod'
and one of the
following values
Value  Description 

'iterativesampling'  Tune the 
'hessian'  Set the 
'none'  Perform no tuning of the

To perform the tuning, use the tuneSampler
method.
Example: 'MassVectorTuningMethod','hessian'
CheckGradient
— Flag for checking analytical gradient
true
(or
1
) (default)  false
(or 0
)
Flag for checking the analytical gradient, specified as the
commaseparated pair consisting of
'CheckGradient'
and either
true
(or 1
) or
false
(or 0
).
If 'CheckGradient'
is true
,
then the sampler calculates the numerical gradient at the
startpoint
and compares it to the
analytical gradient returned by logpdf
.
Example: 'CheckGradient',true
VariableNames
— Sampling variable names
{'x1','x2',...}
(default)  string array  cell array of character vectors
Sampling variable names, specified as the commaseparated pair
consisting of 'VariableNames'
and a string array
or cell array of character vectors. Elements of the array must be
unique. The length of the array must be the same as the length of
startpoint
.
Supply a 'VariableNames'
value to label the
components of the vector you want to sample using the HMC
sampler.
Example: 'VariableNames',{'Intercept','Beta'}
UseNumericalGradient
— Flag for using numerical gradient
false
(or
0
) (default)  true
(or 1
)
Flag for using numerical gradient, specified as the
commaseparated pair consisting of
'UseNumericalGradient'
and either
true
(or 1
) or
false
(or 0
).
If you set the 'UseNumericalGradient'
value to
true
, then the HMC sampler numerically
estimates the gradient from the log density returned by
logpdf
. In this case, the
logpdf
function does not need to return the
gradient of the log density as the second output. Using a numerical
gradient makes HMC sampling slower.
Example: 'UseNumericalGradient',true
Properties
StepSize
— Step size of Hamiltonian dynamics
0.1
(default)  positive scalar
Step size of Hamiltonian dynamics, specified as a positive scalar.
To propose a new state for the Markov chain, the HMC sampler integrates the Hamiltonian dynamics using leapfrog integration. The value of this property controls the step size of that leapfrog integration.
NumSteps
— Number of steps of Hamiltonian dynamics
50
(default)  positive integer
Number of steps of Hamiltonian dynamics, specified as a positive integer.
To propose a new state for the Markov chain, the HMC sampler integrates the Hamiltonian dynamics using leapfrog integration. The value of this property controls the number of steps of that leapfrog integration.
MassVector
— Mass vector of momentum variables
ones(size(startpoint,1),1)
(default)  numeric column vector
Mass vector of momentum variables, specified as a numeric column vector
with positive values and the same length as
startpoint
.
The “masses” of the momentum variables associated with the variables of interest control the Hamiltonian dynamics in each Markov chain proposal.
JitterMethod
— Method for jittering step size and number of steps
'jitterboth'
(default)  'jitternumsteps'
 'none'
Method for jittering the step size and the number of steps, specified as one of the following values.
Value  Description 

'jitterboth'  Randomly jitter the step size and number of steps of each leapfrog trajectory. 
'jitternumsteps'  Jitter only the number of steps of each leapfrog trajectory. 
'none'  Perform no jittering. 
With jittering, the sampler randomly selects the step size or the number
of steps of each leapfrog trajectory as values smaller than the
'StepSize'
and 'NumSteps'
values.
Use jittering to improve the stability of the leapfrog integration of the
Hamiltonian dynamics.
StepSizeTuningMethod
— Method for tuning sampler step size
'dualaveraging'
(default)  'none'
Method for tuning the sampler step size, specified as
'dualaveraging'
or 'none'
.
If StepSizeTuningMethod
equals
'dualaveraging'
, then tuneSampler
tunes the leapfrog
step size of the HMC sampler to achieve a certain acceptance ratio for a
fixed value of the simulation length. The simulation length equals the step
size multiplied by the number of steps. To set the target acceptance ratio,
use the 'TargetAcceptanceRatio'
namevalue pair argument
of the tuneSampler
method.
MassVectorTuningMethod
— Method for tuning sampler mass vector
'iterativesampling'
(default)  'hessian'
 'none'
Method for tuning the sampler mass vector, specified as one of the following values.
Value  Description 

'iterativesampling'  Tune the 
'hessian'  Set the 
'none'  Perform no tuning of the

To perform the tuning, use the tuneSampler
method.
LogPDF
— Logarithm of target density and its gradient
function handle
Logarithm of target density and its gradient, specified as a function handle.
LogPDF
returns two output arguments:
[lpdf,glpdf] = LogPDF(X)
. Here,
lpdf
is the basee log probability density (up to an
additive constant) and glpdf
is the gradient of the log
density at the point X
. The input argument
X
must be a column vector with the same number of
elements as the StartPoint
property.
If you set the 'UseNumericalGradient'
value to
true
when creating the sampler, then
LogPDF
returns the numerical gradient in
glpdf
.
StartPoint
— Initial point to start sampling from
numeric column vector
Initial point to start sampling from, specified as a numeric column vector.
VariableNames
— Sampling variable names
{'x1','x2',...}
(default)  cell array of unique character vectors
Sampling variable names, specified as a cell array of unique character vectors.
Methods
diagnostics  Markov Chain Monte Carlo diagnostics 
drawSamples  Generate Markov chain using Hamiltonian Monte Carlo (HMC) 
estimateMAP  Estimate maximum of log probability density 
tuneSampler  Tune Hamiltonian Monte Carlo (HMC) sampler 
Examples
Create Hamiltonian Monte Carlo Sampler
Create a Hamiltonian Monte Carlo (HMC) sampler to sample from a normal distribution.
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.
means = [1;3]; standevs = [1;2]; logpdf = @(theta)normalDistGrad(theta,means,standevs);
Choose a starting point for the HMC sampler.
startpoint = randn(2,1);
Create the HMC sampler and display its properties.
smp = hmcSampler(logpdf,startpoint);
smp
smp = HamiltonianSampler with properties: StepSize: 0.1000 NumSteps: 50 MassVector: [2x1 double] JitterMethod: 'jitterboth' StepSizeTuningMethod: 'dualaveraging' MassVectorTuningMethod: 'iterativesampling' LogPDF: @(theta)normalDistGrad(theta,means,standevs) VariableNames: {2x1 cell} StartPoint: [2x1 double]
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
Version History
Introduced in R2017a
See Also
Functions
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)