# TMCMC (Transitional Markov Chain Monte Carlo)

This is the implementation of the *Transitional Markov Chain Monte Carlo*
algorithm, as published in Ching2007.

TMCMC avoids sampling from difficult target probability densities (e.g. posterior distributions in a Bayesian inference problem) but samples from a series of intermediate PDFs that converge to the target PDF. This technique is also known as Sampling Importance Resampling in the Bayesian community.

## Usage

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

## Results

These are the results produced by this solver:

- Posterior Sample Datase
**Usage**: e[“Results”][“Posterior Sample Datase”] = List of Lists of*real number***Description**: Samples that approximate the posterior distribution.

- Posterior Sample LogPrior Database
**Usage**: e[“Results”][“Posterior Sample LogPrior Database”] = List of*real number***Description**: Log Priors of Samples in Posterior Samples Database.

- Posterior Sample LogLikelihood Database
**Usage**: e[“Results”][“Posterior Sample LogLikelihood Database”] = List of*real number***Description**: Log Likelihood of Samples in Posterior Samples Database.

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

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

- Version
**Usage**: e[“Solver”][“Version”] =*string***Description**: Indicates which variant of the TMCMC algorithm to use.**Options**:“

*TMCMC*”: Uses the TMCMC algorithm.“

*mTMCMC*”: Uses the mTMCMC algoritm.

- Population Size
**Usage**: e[“Solver”][“Population Size”] =*unsigned integer***Description**: Specifies the number of samples drawn from the posterior distribution at each generation.

- Max Chain Length
**Usage**: e[“Solver”][“Max Chain Length”] =*unsigned integer***Description**: Chains longer than Max Chain Length will be broken and samples will be duplicated (replacing samples associated with a chain length of 0). Max Chain Length of 1 corresponds to the BASIS algorithm [Wu2018].

- Burn In
**Usage**: e[“Solver”][“Burn In”] =*unsigned integer***Description**: Specifies the number of additional TMCMC steps per chain per generation (except for generation 0 and 1).

- Per Generation Burn In
**Usage**: e[“Solver”][“Per Generation Burn In”] = List of*unsigned integer***Description**: Specifies the number of additional TMCMC steps per chain at specified generations (this property will overwrite Default Burn In at specified generations). The first entry of the vector corresponds to the 2nd TMCMC generation.

- Target Coefficient Of Variation
**Usage**: e[“Solver”][“Target Coefficient Of Variation”] =*real number***Description**: Target coefficient of variation of the plausibility weights to update the annealing exponent \(\rho\) (by default, this value is 1.0 as suggested in [Ching2007]).

- Covariance Scaling
**Usage**: e[“Solver”][“Covariance Scaling”] =*real number***Description**: Scaling factor \(\beta^2\) of Covariance Matrix (by default, this value is 0.04 as suggested in [Ching2007]).

- Min Annealing Exponent Update
**Usage**: e[“Solver”][“Min Annealing Exponent Update”] =*real number***Description**: Minimum increment of the exponent \(\rho\). This parameter prevents TMCMC from stalling.

- Max Annealing Exponent Update
**Usage**: e[“Solver”][“Max Annealing Exponent Update”] =*real number***Description**: Maximum increment of the exponent \(\rho\) (by default, this value is 1.0 (inactive)).

- Step Size
**Usage**: e[“Solver”][“Step Size”] =*real number***Description**: Scaling factor of gradient and proposal distribution (only relevant for mTMCMC).

- Domain Extension Factor
**Usage**: e[“Solver”][“Domain Extension Factor”] =*real number***Description**: Defines boundaries for eigenvalue adjustments of proposal distribution (only relevant for mTMCMC).

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

- Target Annealing Exponent
**Usage**: e[“Solver”][“Target Annealing Exponent”] =*real number***Description**: Determines the annealing exponent \(\rho\) to achieve before termination. TMCMC converges if \(\rho\) equals 1.0.**Criteria**:`_previousAnnealingExponent >= _targetAnnealingExponent`

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

{ "Burn In": 0, "Covariance Scaling": 0.04, "Domain Extension Factor": 0.2, "Max Annealing Exponent Update": 1.0, "Max Chain Length": 1, "Min Annealing Exponent Update": 1e-05, "Model Evaluation Count": 0, "Multinomial Generator": { "Type": "Specific/Multinomial" }, "Multivariate Generator": { "Type": "Multivariate/Normal" }, "Per Generation Burn In": [], "Step Size": 0.1, "Target Coefficient Of Variation": 1.0, "Termination Criteria": { "Max Generations": 10000000000, "Max Model Evaluations": 1000000000, "Target Annealing Exponent": 1.0 }, "Uniform Generator": { "Maximum": 1.0, "Minimum": 0.0, "Type": "Univariate/Uniform" }, "Variable Count": 0, "Version": "TMCMC" }

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