# hmcSampler

Hamiltonian Monte Carlo (HMC) sampler

## Description

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.

After you create the sampler, 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.

specifies
additional options using one or more name-value pair arguments. Specify
name-value pair arguments after all other input arguments.`hmc`

= hmcSampler(___,`Name,Value`

)

## 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: 'jitter-both' StepSizeTuningMethod: 'dual-averaging' MassVectorTuningMethod: 'iterative-sampling' 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

## 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 base-e
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`

### 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: **`'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 comma-separated
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`

**Data Types: **`single`

| `double`

`NumSteps`

— Number of steps of Hamiltonian dynamics

`50`

(default) | positive integer

Number of steps of Hamiltonian dynamics, specified as the comma-separated
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`

**Data Types: **`single`

| `double`

`MassVector`

— Mass vector of momentum variables

`ones(size(startpoint,1),1)`

(default) | numeric column vector

Mass vector of momentum variables, specified as the comma-separated
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)`

**Data Types: **`single`

| `double`

`JitterMethod`

— Method for jittering step size and number of steps

`'jitter-both'`

(default) | `'jitter-numsteps'`

| `'none'`

Method for jittering the step size and the number of steps,
specified as the comma-separated pair consisting of `'JitterMethod'`

and
one of the following values.

Value | Description |
---|---|

`'jitter-both'` | Randomly jitter the step size and number of steps for each leapfrog trajectory. |

`'jitter-numsteps'` | 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','jitter-both'`

`StepSizeTuningMethod`

— Method for tuning sampler step size

`'dual-averaging'`

(default) | `'none'`

Method for tuning the sampler step size, specified as the comma-separated
pair consisting of `'StepSizeTuningMethod'`

and `'dual-averaging'`

or `'none'`

.

If the `'StepSizeTuningMethod'`

value is set
to `'dual-averaging'`

, 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'`

name-value
pair argument of the `tuneSampler`

method.

**Example: **`'StepSizeTuningMethod','none'`

`MassVectorTuningMethod`

— Method for tuning sampler mass vector

`'iterative-sampling'`

(default) | `'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 |

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
comma-separated 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 comma-separated pair
consisting of `'VariableNames'`

and a string array or a
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'}`

**Data Types: **`string`

| `cell`

`UseNumericalGradient`

— Flag for using numerical gradient

`false`

(or `0`

) (default) | `true`

(or `1`

)

Flag for using numerical gradient, specified as the comma-separated
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`

## Output Arguments

`hmc`

— Hamiltonian Monte Carlo sampler

`HamiltonianSampler`

object

Hamiltonian Monte Carlo sampler, returned as a `HamiltonianSampler`

object.

## Version History

**Introduced in R2017a**

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