# HMC (Hamiltonian Monte Carlo)

This is an implementation of the *Hamiltonian Monte Carlo* algorithm,
as published in Hoffman and Gelman.
This solver can also be configured to run the standard *HMC* method.

## Usage

`e["Solver"]["Type"] = "Sampler/HMC"`

## Results

These are the results produced by this solver:

- Sample Database
**Usage**: e[“Results”][“Sample Database”] = List of Lists of*real number***Description**: Collection of samples describing the probability distribution.

## Variable-Specific Settings

These are settings required by this module that are added to each of the experiment’s variables when this module is selected.

- Initial Mean
**Usage**: e[“Variables”][*index*][“Initial Mean”] =*real number***Description**: Specifies the Initial Mean of the proposal distribution.

- Initial Standard Deviation
**Usage**: e[“Variables”][*index*][“Initial Standard Deviation”] =*real number***Description**: Specifies the Standard Deviation for each variable. The proposal distribution is defined through a covariance matrix with the variance of the variables in its diagonal.

- Lower Bound
**Usage**: e[“Variables”][*index*][“Lower Bound”] =*real number***Description**: Specifies the lower bound for the variable’s value.

- Upper Bound
**Usage**: e[“Variables”][*index*][“Upper Bound”] =*real number***Description**: Specifies the upper bound for the variable’s value.

- Initial Value
**Usage**: e[“Variables”][*index*][“Initial Value”] =*real number***Description**: Defines the initial value at or around which the algorithm shall start looking for an optimum.

## Configuration

These are settings required by this module.

- Burn In
**Usage**: e[“Solver”][“Burn In”] =*unsigned integer***Description**: Specifies the number of preliminary HMC steps before samples are being drawn. This may reduce effects from improper initialization.

- Use Diagonal Metric
**Usage**: e[“Solver”][“Use Diagonal Metric”] =*True/False***Description**: Specifies if Metric is restricted to be diagonal.

- Num Integration Steps
**Usage**: e[“Solver”][“Num Integration Steps”] =*unsigned integer***Description**: Number of Integration steps used in Leapfrog scheme. Only relevant if Adaptive Step Size not used.

- Max Integration Steps
**Usage**: e[“Solver”][“Max Integration Steps”] =*unsigned integer***Description**: Number of Integration steps used in Leapfrog scheme. Only relevant if Adaptive Step Size is used.

- Use NUTS
**Usage**: e[“Solver”][“Use NUTS”] =*True/False***Description**: Specifies if No-U-Turn Sampler (NUTS) is used.

- Step Size
**Usage**: e[“Solver”][“Step Size”] =*real number***Description**: Step size used in Leapfrog scheme.

- Use Adaptive Step Size
**Usage**: e[“Solver”][“Use Adaptive Step Size”] =*True/False***Description**: Controls whether dual averaging technique for adaptive step size calibration is used.

- Target Acceptance Rate
**Usage**: e[“Solver”][“Target Acceptance Rate”] =*real number***Description**: Desired Acceptance Rate for Adaptive Step Size calibration.

- Acceptance Rate Learning Rate
**Usage**: e[“Solver”][“Acceptance Rate Learning Rate”] =*real number***Description**: Learning rate of running acceptance rate estimate.

- Target Integration Time
**Usage**: e[“Solver”][“Target Integration Time”] =*real number***Description**: Targeted Integration Time for Leapfrog scheme. Only relevant if Adaptive Step Size used.

- Adaptive Step Size Speed Constant
**Usage**: e[“Solver”][“Adaptive Step Size Speed Constant”] =*real number***Description**: Controls how fast the step size is adapted. Only relevant if Adaptive Step Size used.

- Adaptive Step Size Stabilization Constant
**Usage**: e[“Solver”][“Adaptive Step Size Stabilization Constant”] =*real number***Description**: Controls stability of adaptive step size calibration during the inital iterations. Only relevant if Adaptive Step Size used.

- Adaptive Step Size Schedule Constant
**Usage**: e[“Solver”][“Adaptive Step Size Schedule Constant”] =*real number***Description**: Controls the weight of the previous step sizes. Only relevant if Adaptive Step Size used. The smaller the higher the weight.

- Max Depth
**Usage**: e[“Solver”][“Max Depth”] =*unsigned integer***Description**: Sets the maximum depth of NUTS binary tree.

- Version
**Usage**: e[“Solver”][“Version”] =*string***Description**: Metric can be set to ‘Static’, ‘Euclidean’ or ‘Riemannian’.

- Inverse Regularization Parameter
**Usage**: e[“Solver”][“Inverse Regularization Parameter”] =*real number***Description**: Controls hardness of inverse metric approximation: For large values the Inverse Metric is closer the to Hessian (and therefore closer to degeneracy in certain cases).

- Max Fixed Point Iterations
**Usage**: e[“Solver”][“Max Fixed Point Iterations”] =*unsigned integer***Description**: Max number of fixed point iterations during implicit leapfrog scheme.

- Step Size Jitter
**Usage**: e[“Solver”][“Step Size Jitter”] =*real number***Description**: Step Size Jitter to vary trajectory length. Number must be in the interval [0.0. 1.0]. A uniform realization between [-(Step Size Jitter) * (Step Size), (Step Size Jitter) * (Step Size)) is sampled and added to the current Step Size.

- Initial Fast Adaption Interval
**Usage**: e[“Solver”][“Initial Fast Adaption Interval”] =*unsigned integer***Description**: Initial warm-up interval during which step size is adaptively adjusted.

- Final Fast Adaption Interval
**Usage**: e[“Solver”][“Final Fast Adaption Interval”] =*unsigned integer***Description**: Final warm-up interval during which step size is adaptively adjusted.

- Initial Slow Adaption Interval
**Usage**: e[“Solver”][“Initial Slow Adaption Interval”] =*unsigned integer***Description**: Lenght of first (out of 5) warm-up intervals during which euclidean metric is adapted. The length of each following slow adaption intervals is doubled.

## Termination Criteria

These are the customizable criteria that indicates whether the solver should continue or finish execution. Korali will stop when at least one of these conditions are met. The criteria is expressed in C++ since it is compiled and evaluated as seen here in the engine.

- Max Samples
**Usage**: e[“Solver”][“Max Samples”] =*unsigned integer***Description**: Number of Samples to Generate.**Criteria**:`_sampleDatabase.size() >= _maxSamples`

- Max Model Evaluations
**Usage**: e[“Solver”][“Max Model Evaluations”] =*unsigned integer***Description**: Specifies the maximum allowed evaluations of the computational model.**Criteria**:`_maxModelEvaluations <= _modelEvaluationCount`

- Max Generations
**Usage**: e[“Solver”][“Max Generations”] =*unsigned integer***Description**: Determines how many solver generations to run before stopping execution. Execution can be resumed at a later moment.**Criteria**:`_k->_currentGeneration > _maxGenerations`

## Default Configuration

These following configuration will be assigned by default. Any settings defined by the user will override the given settings specified in these defaults.

{ "Acceptance Count NUTS": 0.0, "Acceptance Rate Learning Rate": 0.85, "Adaptive Step Size Schedule Constant": 0.75, "Adaptive Step Size Speed Constant": 0.05, "Adaptive Step Size Stabilization Constant": 10.0, "Burn In": 300, "Final Fast Adaption Interval": 50, "Initial Fast Adaption Interval": 75, "Initial Slow Adaption Interval": 25, "Inverse Regularization Parameter": 1.0, "Max Depth": 5, "Max Fixed Point Iterations": 8, "Max Integration Steps": 100, "Model Evaluation Count": 0, "Multivariate Generator": { "Type": "Multivariate/Normal" }, "Normal Generator": { "Mean": 0.0, "Standard Deviation": 1.0, "Type": "Univariate/Normal" }, "Num Integration Steps": 4, "Step Size": 0.1, "Step Size Jitter": 0.0, "Target Acceptance Rate": 0.65, "Target Integration Time": 1.0, "Termination Criteria": { "Max Generations": 10000000000, "Max Model Evaluations": 1000000000, "Max Samples": 500 }, "Uniform Generator": { "Maximum": 1.0, "Minimum": 0.0, "Type": "Univariate/Uniform" }, "Use Adaptive Step Size": true, "Use Diagonal Metric": true, "Use NUTS": true, "Variable Count": 0, "Version": "Euclidean" }

## Variable Defaults

These following configuration will be assigned to each of the experiment variables by default. Any settings defined by the user will override the given settings specified in these defaults.

{ "Initial Value": -Infinity, "Lower Bound": -Infinity, "Upper Bound": Infinity }