pyemma.thermo.tram¶

pyemma.thermo.tram(ttrajs, dtrajs, bias, lag, unbiased_state=None, count_mode='sliding', connectivity='summed_count_matrix', maxiter=10000, maxerr=1e-15, save_convergence_info=0, dt_traj='1 step', connectivity_factor=1.0, nn=None, direct_space=False, N_dtram_accelerations=0, callback=None, init='mbar', init_maxiter=10000, init_maxerr=1e-08, equilibrium=None, overcounting_factor=1.0)¶

Transition-based reweighting analysis method

Parameters:	ttrajs (numpy.ndarray(T), or list of numpy.ndarray(T_i)) – 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(T, num_therm_states), or list of numpy.ndarray(T_i, num_therm_states)) – A single reduced bias energy trajectory or a list of reduced bias energy trajectories. For every simulation frame seen in trajectory i and time step t, btrajs[i][t, k] is the reduced bias energy of that frame evaluated in the k’th thermodynamic state (i.e. at the k’th umbrella/Hamiltonian/temperature) lag (int or list of int, optional, default=1) – Integer lag time at which transitions are counted. Providing a list of lag times will trigger one estimation per lag time. 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’ connectivity (str, optional, default='summed_count_matrix') – One of ‘summed_count_matrix’, ‘strong_in_every_ensemble’, ‘neighbors’, ‘post_hoc_RE’ or ‘BAR_variance’. Defines what should be considered a connected set in the joint space of conformations and thermodynamic ensembles. For details see thermotools.cset.compute_csets_TRAM. nn (int, optional, default=None) – Only needed if connectivity=’neighbors’ See thermotools.cset.compute_csets_TRAM. connectivity_factor (float, optional, default=1.0) – Only needed if connectivity=’post_hoc_RE’ or ‘BAR_variance’. Weakens the connectivity requirement, see thermotools.cset.compute_csets_TRAM. direct_space (bool, optional, default=False) – Whether to perform the self-consitent iteration with Boltzmann factors (direct space) or free energies (log-space). When analyzing data from multi-temperature simulations, direct-space is not recommended. N_dtram_accelerations (int, optional, default=0) – Convergence of TRAM can be speeded up by interleaving the updates in the self-consitent iteration with a dTRAM-like update step. N_dtram_accelerations says how many times the dTRAM-like update step should be applied in every iteration of the TRAM equations. Currently this is only effective if direct_space=True. init (str, optional, default=None) – Use a specific initialization for self-consistent iteration: None: use a hard-coded guess for free energies and Lagrangian multipliers ‘wham’: perform a short WHAM estimate to initialize the free energies init_maxiter (int, optional, default=10000) – The maximum number of self-consistent iterations during the initialization. init_maxerr (float, optional, default=1.0E-8) – Convergence criterion for the initialization.
Returns:	A multi-ensemble Markov state model (for each given lag time) which consists of stationary and kinetic quantities at all temperatures/thermodynamic states.
Return type:	A `MEMM` object or list thereof

Example

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.

The bias would be a list of \(T \times K\) arrays which specify each frame’s bias energy in all thermodynamic states:

[ ((0, 1.7, 2.3, 6.1, ...), ...), ((0, 2.4, 3.1, 9,5, ...), ...), ... ]

Let us try the above example:

>>> from pyemma.thermo import tram
>>> import numpy as np
>>> ttrajs = [np.array([0,0,0,0,0,0,0]), np.array([1,1,1,1,1,1,1])]
>>> dtrajs = [np.array([0,0,0,0,1,1,1]), np.array([0,1,0,1,0,1,1])]
>>> bias = [np.array([[1,0],[1,0],[0,0],[0,0],[0,0],[0,0],[0,0]],dtype=np.float64), np.array([[1,0],[0,0],[0,0],[1,0],[0,0],[1,0],[1,0]],dtype=np.float64)]
>>> tram_obj = tram(ttrajs, dtrajs, bias, 1)
>>> tram_obj.log_likelihood() 
-29.111...
>>> tram_obj.count_matrices 
array([[[1 1]
        [0 4]]
       [[0 3]
        [2 1]]], dtype=int32)
>>> tram_obj.stationary_distribution 
array([ 0.38...  0.61...])

See MEMM for a full documentation.

class pyemma.thermo.models.memm.MEMM(models, f_therm, pi=None, f=None, label='ground state')¶

Coupled set of Markov state models at multiple thermodynamic states

Parameters:

models (list of Model objects) – List of Model objects, e.g. StationaryModel or MSM objects, at the different thermodynamic states. This list may include the ground state, such that self.pi = self.models[0].pi holds. An example for that is data obtained from parallel tempering or replica-exchange, where the lowest simulated temperature is usually identical to the thermodynamic ground state. However, the list does not have to include the thermodynamic ground state. For example, when obtaining data from umbrella sampling, models might be the list of stationary models for n umbrellas (biased ensembles), while the thermodynamic ground state is the unbiased ensemble. In that case, self.pi would be different from any self.models[i].pi
f_therm (ndarray(k)) – free energies at the different thermodynamic states
pi (ndarray(n), default=None) – Stationary distribution of the thermodynamic ground state. If not already normalized, pi will be scaled to fulfill \(\sum_i \pi_i = 1\). If None, models[0].pi will be used
f (ndarray(n)) – Discrete-state free energies of the thermodynamic ground state.
label (str, default='ground state') – Human-readable description for the thermodynamic ground state or reference state of this multiensemble. May contain a temperature description, such as ‘300 K’ or a description of bias energy such as ‘unbiased’.

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`
`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¶

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]	Wu, H. et al 2016 Multiensemble Markov models of molecular thermodynamics and kinetics Proc. Natl. Acad. Sci. USA 113 E3221–E3230