HMC

class hmclab.Samplers.HMC(seed: Optional[int] = None)

Bases: hmclab.Samplers._AbstractSampler

__init__(seed: Optional[int] = None) → None

Constructor that sets the random number generator for the sampler. Pass a seed to make a Markov chain reproducible (given that all settings are re-used.)

Parameters

seed (int) – Description of parameter seed.

Methods

__init__	Constructor that sets the random number generator for the sampler.
autotune
get_diagnostics
load_results
plot_acceptance_rate
plot_stepsizes
print_results	Print Jupyter widget from _repr_html_() to stdout.
sample	Sampling using the Hamiltonian Monte Carlo algorithm.

Attributes

acceptance_rates	A NumPy ndarray containing all past acceptance rates.
accepted_proposals	An integer representing the amount of accepted proposals.
amount_of_steps	A positive integer representing the amount of integration steps to be used in solving Hamiltons equations.
amount_of_writes	A positive integer representing the amount of times the sampler has written to disk.
autotuning	A boolean indicating if the stepsize is tuned towards a specific acceptance rate using diminishing adaptive parameters.
available_integrators
current_h	A float representing the total energy associated with the current state.
current_k	A float representing the kinetic energy associated with the current state.
current_model	A NumPy array containing the model at the current state of the Markov chain.
current_momentum	A NumPy ndarray (shape dimensions × 1) containing the momentum at the current state of the Markov chain.
current_proposal	An integer representing the current proposal index (before thinning) of the Markov chain.
current_proposal_after_thinning	An integer representing the current proposal index after thinning of the Markov chain.
current_x	A float containing \(\chi = -\log\left( p\\right)\) (i.e.
diagnostic_mode	Boolean describing whether functions need to be profiled for performance.
dimensions	An integer representing the dimensionality in which the MCMC sampler works.
disable_progressbar	A bool describing whether or not to disable the TQDM progressbar
distribution	The _AbstractDistribution-derived object on which the sampler works.
end_time	Time (and date) at which sampling was terminated / finished.
exchange_interval	Integer describing how many samples lie between the attempted swap of states between samplers.
exchange_schedule	A pre-communicated exchange schedule determining when and which samplers try to exchange states.
functions_to_diagnose	Array of functions to be profiled, typically contains functions only from the abstract base class.
integrator
integrators
integrators_full_names
learning_rate	A float tuning the rate of decrease at which a new step size is adapted, according to rate = (iteration_number) ** (-learning_rate).
main_thread_keyboard_interrupt
mass_matrix	An object representing the artificial masses assigned to each parameters.
max_time	A float representing the maximum time in seconds that sampling is allowed to take before it is automatically terminated.
minimal_stepsize	Minimal stepsize which is chosen if stepsize becomes zero or negative during autotuning.
name	Sampler name.
online_thinning	An integer representing the interval between stored samples.
parallel	A boolean describing if this sampler works in an array of multiple samplers.
pipe_matrix	A matrix of two-way communicators between samplers.
progressbar_refresh_rate	A float representing how many seconds lies between an update of the progress bar statistics (acceptance rate etc.).
proposals	An integer representing the amount of requested proposals for a run.
proposed_h	A float representing the total energy associated with the proposed state.
proposed_k	A float representing the kinetic energy associated with the proposed state.
proposed_model	A NumPy array containing the model at the proposed state of the Markov chain.
proposed_momentum	A NumPy ndarray (shape dimensions × 1) containing the momentum at the proposed state of the Markov chain.
proposed_x	A float containing \(\chi = -\log\left( p\\right)\) (i.e.
ram_buffer	A NumPy ndarray containing the samples that are as of yet not written to disk.
ram_buffer_size	A positive integer indicating the size of the RAM buffer in amount of samples.
randomize_stepsize	Boolean describing whether or not to randomize the stepsize slightly for every trajectory, by a Uniform~[0.5-1.5] * stepsize.
rng
sampler_index	An integer describing the index of the parallel sampler in the array of samplers.
sampler_specific_functions_to_diagnose	Array of sampler specific functions to be profiled.
samples_hdf5_dataset	A string containing the HDF5 group of the hdf5 file to which samples will be stored.
samples_hdf5_filehandle	A HDF5 file handle of the hdf5 file to which samples will be stored.
samples_hdf5_filename	A string containing the path+filename of the hdf5 file to which samples will be stored.
start_time	Time (and date) at which sampling was started.
stepsize	A positive float representing the time step to be used in solving Hamiltons equations.
stepsizes	A NumPy ndarray containing all past stepsizes for the HMC algorithm.
target_acceptance_rate	A float representing the optimal acceptance rate used for autotuning, if autotuning is True.
times_started	An integer representing how often this sampler object has started sampling.

stepsize: float = 0.1

A positive float representing the time step to be used in solving Hamiltons equations. Has a strong influence on acceptance rate. An essential tuning parameter.

amount_of_steps: int = 10

A positive integer representing the amount of integration steps to be used in solving Hamiltons equations. Has a medium influence on acceptance rate. An essential tuning parameter.

mass_matrix: hmclab.MassMatrices._AbstractMassMatrix = None

An object representing the artificial masses assigned to each parameters. Needs to be a subtype of _AbstractMassMatrix. Has a strong influence on convergence rate. An essential tuning parameter.

current_momentum: numpy.ndarray = None

A NumPy ndarray (shape dimensions × 1) containing the momentum at the current state of the Markov chain. Indicates direction in which the model will initially move along its numerical trajectory. Will be resampled from the mass matrix for each proposal.

current_k: float = nan

A float representing the kinetic energy associated with the current state. Typically follows the ChiSquared[dimensions] distribution.

current_h: float = nan

A float representing the total energy associated with the current state.

proposed_momentum: numpy.ndarray = None

A NumPy ndarray (shape dimensions × 1) containing the momentum at the proposed state of the Markov chain. Indicates direction in which the model was moving at the end of its numerical trajectory. Will be computed deterministically from the current_momentum, i.e. the state the Markov chain started in.

proposed_k: float = nan

A float representing the kinetic energy associated with the proposed state.

proposed_h: float = nan

A float representing the total energy associated with the proposed state.

name: str = 'Hamiltonian Monte Carlo'

Sampler name.

autotuning: bool = False

A boolean indicating if the stepsize is tuned towards a specific acceptance rate using diminishing adaptive parameters.

learning_rate: float = 0.75

A float tuning the rate of decrease at which a new step size is adapted, according to rate = (iteration_number) ** (-learning_rate). Needs to be larger than 0.5 and equal to or smaller than 1.0.

target_acceptance_rate: float = 0.65

A float representing the optimal acceptance rate used for autotuning, if autotuning is True.

acceptance_rates: numpy.ndarray = None

A NumPy ndarray containing all past acceptance rates. Collected if autotuning is True.

randomize_stepsize: bool = True

Boolean describing whether or not to randomize the stepsize slightly for every trajectory, by a Uniform~[0.5-1.5] * stepsize.

print_results() → None

Print Jupyter widget from _repr_html_() to stdout.

stepsizes: numpy.ndarray = None

A NumPy ndarray containing all past stepsizes for the HMC algorithm. Collected if autotuning is True.

minimal_stepsize: float = 1e-18

Minimal stepsize which is chosen if stepsize becomes zero or negative during autotuning.

sample(samples_hdf5_filename: str, distribution: hmclab.Distributions.base._AbstractDistribution, stepsize: float = 0.1, randomize_stepsize: Optional[bool] = None, amount_of_steps: int = 10, mass_matrix: Optional[hmclab.MassMatrices._AbstractMassMatrix] = None, integrator: str = 'lf', initial_model: Optional[numpy.ndarray] = None, proposals: int = 100, online_thinning: int = 1, diagnostic_mode: bool = False, ram_buffer_size: Optional[int] = None, overwrite_existing_file: bool = False, max_time: Optional[float] = None, autotuning: bool = False, target_acceptance_rate: float = 0.65, learning_rate: float = 0.75, queue=None, disable_progressbar=False)

Sampling using the Hamiltonian Monte Carlo algorithm.

Parameters

• samples_hdf5_filename (str) – String containing the (path+)filename of the HDF5 file to contain the samples. A required parameter.

• distribution (_AbstractDistribution) – The distribution to sample. Should be an instance of a subclass of _AbstractDistribution. A required parameter.

• stepsize (float) – A positive float representing the time step to be used in solving Hamiltons equations. Has a strong influence on acceptance rate. An essential tuning parameter.

• amount_of_steps (int) – A positive integer representing the amount of integration steps to be used in solving Hamiltons equations. Has a medium influence on acceptance rate. An essential tuning parameter.

• mass_matrix (_AbstractMassMatrix) – An object representing the artificial masses assigned to each parameters. Needs to be a subtype of _AbstractMassMatrix. Has a strong influence on convergence rate. One passing None, defaults to the Unit mass matrix. An essential tuning parameter.

• integrator (str) – String containing “lf”, “3s” or “4s” for a leapfrog, 3-stage or 4-stage symplectic integrator respectively, to be used during the trajectory calculation.

• initial_model (_numpy) – A NumPy column vector (shape dimensions × 1) containing the starting model of the Markov chain. This model will not be written out as a sample.

• proposals (int) – An integer representing the amount of proposals the algorithm should make.

• online_thinning (int) – An integer representing the degree of online thinning, i.e. the interval between storing samples.

• randomize_stepsize (bool) – A boolean enabling the randomization of the stepsize, which helps avoiding MCMC resonance.

• diagnostic_mode (bool) – A boolean describing if subroutines of sampling should be timed. Useful for finding slow parts of the algorithm. Will add overhead to each function.

• ram_buffer_size (int) – An integer representing how many samples should be kept in RAM before writing to storage.

• overwrite_existing_file (bool) – A boolean describing whether or not to silently overwrite existing files. Use with caution.

• max_time (float) – A float representing the maximum time in seconds that sampling is allowed to take before it is automatically terminated. The value None is used for unlimited time.

• autotuning (bool) – A boolean describing whether or not stepsize is automatically adjusted. Uses a diminishing adapting scheme to satisfy detailed balance.

• target_acceptance_rate (float) – A float between 0.0 and 1.0 that is the target acceptance rate of autotuning. The algorithm will try to achieve this acceptance rate.

• learning_rate (float) – A float larger than 0.5 but smaller than or equal to 1.0, describing how aggressively the stepsize is updated. Lower is more aggresive.

Raises

• AssertionError – For any unspecified invalid entry.

• ValueError – For any invalid value of algorithm settings.

• TypeError – For any invalid value of algorithm settings.