pyemma.thermo.WHAM

class pyemma.thermo.WHAM(bias_energies_full, maxiter=10000, maxerr=1e-15, save_convergence_info=0, dt_traj='1 step', stride=1)

Weighted Histogram Analysis Method.

__init__(bias_energies_full, maxiter=10000, maxerr=1e-15, save_convergence_info=0, dt_traj='1 step', stride=1)

Weighted Histogram Analysis Method

Parameters:
  • bias_energies_full (numpy.ndarray(shape=(num_therm_states, num_conf_states)) object) – bias_energies_full[j, i] is the bias energy in units of kT for each discrete state i at thermodynamic state j.
  • maxiter (int, optional, default=10000) – The maximum number of self-consistent iterations before the estimator exits unsuccessfully.
  • maxerr (float, optional, default=1.0E-15) – Convergence criterion based on the maximal free energy change in a self-consistent iteration step.
  • save_convergence_info (int, optional, default=0) – Every save_convergence_info iteration steps, store the actual increment and the actual loglikelihood; 0 means no storage.
  • dt_traj (str, optional, default='1 step') –

    Description of the physical time corresponding to the lag. May be used by analysis algorithms such as plotting tools to pretty-print the axes. By default ‘1 step’, i.e. there is no physical time unit. Specify by a number, whitespace and unit. Permitted units are (* is an arbitrary string):

    ‘fs’, ‘femtosecond*’
    ‘ps’, ‘picosecond*’
    ‘ns’, ‘nanosecond*’
    ‘us’, ‘microsecond*’
    ‘ms’, ‘millisecond*’
    ‘s’, ‘second*’
  • stride (int, optional, default=1) – not used

Example

>>> from pyemma.thermo import WHAM
>>> import numpy as np
>>> B = np.array([[0, 0],[0.5, 1.0]])
>>> wham = WHAM(B)
>>> ttrajs = [np.array([0,0,0,0,0,0,0,0,0,0]),np.array([1,1,1,1,1,1,1,1,1,1])]
>>> dtrajs = [np.array([0,0,0,0,1,1,1,0,0,0]),np.array([0,1,0,1,0,1,1,0,0,1])]
>>> wham = wham.estimate((ttrajs, dtrajs))
>>> wham.log_likelihood() 
-6.6...
>>> wham.state_counts 
array([[7, 3],
       [5, 5]])
>>> wham.stationary_distribution 
array([ 0.5...,  0.4...])
>>> wham.meval('stationary_distribution') 
[array([ 0.5...,  0.4...]), array([ 0.6...,  0.3...])]

References

[1]Ferrenberg, A.M. and Swensen, R.H. 1988. New Monte Carlo Technique for Studying Phase Transitions. Phys. Rev. Lett. 23, 2635–2638
[2]Kumar, S. et al 1992. The Weighted Histogram Analysis Method for Free-Energy Calculations on Biomolecules. I. The Method. J. Comp. Chem. 13, 1011–1021

Methods

__init__(bias_energies_full[, maxiter, ...]) Weighted Histogram Analysis Method
estimate(trajs)
param X:Simulation trajectories. ttrajs contain the indices of the thermodynamic state and
expectation(a) Equilibrium expectation value of a given observable.
fit(X) Estimates parameters - for compatibility with sklearn.
get_model_params([deep]) Get parameters for this model.
get_params([deep]) Get parameters for this estimator.
log_likelihood()
meval(f, *args, **kw) Evaluates the given function call for all models
register_progress_callback(call_back[, stage]) Registers the progress reporter.
set_model_params([models, f_therm, pi, f, label])
set_params(**params) Set the parameters of this estimator.
update_model_params(**params) Update given model parameter if they are set to specific values

Attributes

active_set The active set of states on which all computations and estimations will be done.
f The free energies (in units of kT) on the configuration states.
f_full_state
free_energies The free energies (in units of kT) on the configuration states.
free_energies_full_state
label Human-readable description for the thermodynamic state of this model.
logger The logger for this class instance
model The model estimated by this Estimator
model_active_set
msm_active_set
name The name of this instance
nstates Number of active states on which all computations and estimations are done.
nstates_full Size of the full set of states.
pi The stationary distribution on the configuration states.
pi_full_state
show_progress whether to show the progress of heavy calculations on this object.
stationary_distribution The stationary distribution on the configuration states.
stationary_distribution_full_state
unbiased_state Index of the unbiased thermodynamic state.
active_set

The active set of states on which all computations and estimations will be done.

estimate(trajs)
Parameters:X (tuple of (ttrajs, dtrajs)) –

Simulation trajectories. ttrajs contain the indices of the thermodynamic state and dtrajs contains the indices of the configurational states.

ttrajs : list of numpy.ndarray(X_i, dtype=int)
Every elements is a trajectory (time series). ttrajs[i][t] is the index of the thermodynamic state visited in trajectory i at time step t.
dtrajs : list of numpy.ndarray(X_i, dtype=int)
dtrajs[i][t] is the index of the configurational state (Markov state) visited in trajectory i at time step t.
expectation(a)

Equilibrium expectation value of a given observable.

Parameters:a ((M,) ndarray) – Observable vector
Returns:val – Equilibrium expectation value of the given observable
Return type:float

Notes

The equilibrium expectation value of an observable a is defined as follows

\[\mathbb{E}_{\mu}[a] = \sum_i \mu_i a_i\]

\(\mu=(\mu_i)\) is the stationary vector of the transition matrix \(T\).

f

The free energies (in units of kT) on the configuration states.

fit(X)

Estimates parameters - for compatibility with sklearn.

Parameters:X (object) – A reference to the data from which the model will be estimated
Returns:estimator – The estimator (self) with estimated model.
Return type:object
free_energies

The free energies (in units of kT) on the configuration states.

get_model_params(deep=True)

Get parameters for this model.

Parameters:deep (boolean, optional) – If True, will return the parameters for this estimator and contained subobjects that are estimators.
Returns:params – Parameter names mapped to their values.
Return type:mapping of string to any
get_params(deep=True)

Get parameters for this estimator.

Parameters:deep (boolean, optional) – If True, will return the parameters for this estimator and contained subobjects that are estimators.
Returns:params – Parameter names mapped to their values.
Return type:mapping of string to any
label

Human-readable description for the thermodynamic state of this model.

logger

The logger for this class instance

meval(f, *args, **kw)

Evaluates the given function call for all models Returns the results of the calls in a list

model

The model estimated by this Estimator

name

The name of this instance

nstates

Number of active states on which all computations and estimations are done.

nstates_full

Size of the full set of states.

pi

The stationary distribution on the configuration states.

register_progress_callback(call_back, stage=0)

Registers the progress reporter.

Parameters:
  • call_back (function) –

    This function will be called with the following arguments:

    1. stage (int)
    2. instance of pyemma.utils.progressbar.ProgressBar
    3. optional *args and named keywords (**kw), for future changes
  • stage (int, optional, default=0) – The stage you want the given call back function to be fired.
set_params(**params)

Set the parameters of this estimator. The method works on simple estimators as well as on nested objects (such as pipelines). The former have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object. :returns: :rtype: self

show_progress

whether to show the progress of heavy calculations on this object.

stationary_distribution

The stationary distribution on the configuration states.

unbiased_state

Index of the unbiased thermodynamic state.

update_model_params(**params)

Update given model parameter if they are set to specific values