pyemma.thermo.wham¶
-
pyemma.thermo.
wham
(ttrajs, dtrajs, bias, maxiter=100000, maxerr=1e-15, save_convergence_info=0, dt_traj='1 step')¶ Weighted histogram analysis method
Parameters: - ttrajs (numpy.ndarray(T) of int, or list of numpy.ndarray(T_i) of int) – A single discrete trajectory or a list of discrete trajectories. The integers are indexes in 0,...,num_therm_states-1 enumerating the thermodynamic states the trajectory is in at any time.
- dtrajs (numpy.ndarray(T) of int, or list of numpy.ndarray(T_i) of int) – A single discrete trajectory or a list of discrete trajectories. The integers are indexes in 0,...,num_conf_states-1 enumerating the num_conf_states Markov states or the bins the trajectory is in at any time.
- bias (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 dTRAM iterations before the estimator exits unsuccessfully.
- maxerr (float, optional, default=1e-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*’
Returns: A stationary model which consists of thermodynamic quantities at all temperatures/thermodynamic states.
Return type: A
MultiThermModel
objectExample
Umbrella sampling: Suppose we simulate in K umbrellas, centered at positions \(y_0,...,y_{K-1}\) with bias energies
\[b_k(x) = \frac{c_k}{2 \textrm{kT}} \cdot (x - y_k)^2\]Suppose we have one simulation of length T in each umbrella, and they are ordered from 0 to K-1. We have discretized the x-coordinate into 100 bins. Then dtrajs and ttrajs should each be a list of \(K\) arrays. dtrajs would look for example like this:
[ (0, 0, 0, 0, 1, 1, 1, 0, 0, 0, ...), (0, 1, 0, 1, 0, 1, 1, 0, 0, 1, ...), ... ]
where each array has length T, and is the sequence of bins (in the range 0 to 99) visited along the trajectory. ttrajs would look like this:
[ (0, 0, 0, 0, 0, 0, 0, 0, 0, 0, ...), (1, 1, 1, 1, 1, 1, 1, 1, 1, 1, ...), ... ]
Because trajectory 1 stays in umbrella 1 (index 0), trajectory 2 stays in umbrella 2 (index 1), and so forth. bias is a \(K \times n\) matrix with all reduced bias energies evaluated at all centers:
\[\begin{split}\left(\begin{array}{cccc} b_0(y_0) & b_0(y_1) & ... & b_0(y_{n-1}) \\ b_1(y_0) & b_1(y_1) & ... & b_1(y_{n-1}) \\ ... \\ b_{K-1}(y_0) & b_{K-1}(y_1) & ... & b_{K-1}(y_{n-1}) \end{array}\right)\end{split}\]Let us try the above example:
>>> from pyemma.thermo import wham >>> import numpy as np >>> 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])] >>> bias = np.array([[0.0, 0.0], [0.5, 1.0]]) >>> wham_obj = wham(ttrajs, dtrajs, bias) >>> wham_obj.log_likelihood() -6.6... >>> wham_obj.state_counts array([[7, 3], [5, 5]]) >>> wham_obj.stationary_distribution array([ 0.5..., 0.4...])
See
MultiThermModel
for a full documentation.-
class
pyemma.thermo.models.multi_therm.
MultiThermModel
(models, f_therm, pi=None, f=None, label='ground state')¶ Coupled set of stationary models at multiple thermodynamic states
Methods
expectation
(a)Equilibrium expectation value of a given observable. get_model_params
([deep])Get parameters for this model. meval
(f, *args, **kw)Evaluates the given function call for all models set_model_params
([models, f_therm, pi, f, label])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. model_active_set
msm_active_set
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
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.
-
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.
-
f_full_state
¶
-
free_energies
¶ The free energies (in units of kT) on the configuration states.
-
free_energies_full_state
¶
-
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
-
label
¶ Human-readable description for the thermodynamic state of this model.
-
meval
(f, *args, **kw)¶ Evaluates the given function call for all models Returns the results of the calls in a list
-
model_active_set
¶
-
msm_active_set
¶
-
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
¶
-
set_model_params
(models=None, f_therm=None, pi=None, f=None, label='ground state')¶
-
stationary_distribution
¶ The stationary distribution on the configuration states.
-
stationary_distribution_full_state
¶
-
unbiased_state
¶ Index of the unbiased thermodynamic state.
-
update_model_params
(**params)¶ Update given model parameter if they are set to specific values
-
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