pyemma.thermo.mbar

pyemma.thermo.mbar(ttrajs, dtrajs, bias, maxiter=100000, maxerr=1e-15, save_convergence_info=0, dt_traj='1 step', direct_space=False)

Multi-state Bennet acceptance ratio

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(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)
  • 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*’
  • 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.
Returns:

A stationary model which consists of thermodynamic quantities at all temperatures/thermodynamic states.
Return type:

A MultiThermModel object

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 mbar
>>> 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)]
>>> mbar_obj = mbar(ttrajs, dtrajs, bias, maxiter=1000000, maxerr=1.0E-14)
>>> mbar_obj.stationary_distribution # doctest: +ELLIPSIS
array([ 0.5...  0.5...])

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.
load(file_name[, model_name]) Loads a previously saved PyEMMA object from disk.
meval(f, *args, **kw) Evaluates the given function call for all models Returns the results of the calls in a list
save(file_name[, model_name, overwrite, …]) saves the current state of this object to given file and name.
set_model_params([models, f_therm, pi, f, label]) Call to set all basic model parameters.
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.
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.

classmethod load(file_name, model_name='default')

Loads a previously saved PyEMMA object from disk.

Parameters:
  • file_name (str or file like object (has to provide read method)) – The file like object tried to be read for a serialized object.
  • model_name (str, default='default') – if multiple models are contained in the file, these can be accessed by their name. Use pyemma.list_models() to get a representation of all stored models.
Returns:

obj
Return type:

the de-serialized object
meval(f, *args, **kw)

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

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
save(file_name, model_name='default', overwrite=False, save_streaming_chain=False)

saves the current state of this object to given file and name.

Parameters:
  • file_name (str) – path to desired output file
  • model_name (str, default='default') – creates a group named ‘model_name’ in the given file, which will contain all of the data. If the name already exists, and overwrite is False (default) will raise a RuntimeError.
  • overwrite (bool, default=False) – Should overwrite existing model names?
  • save_streaming_chain (boolean, default=False) – if True, the data_producer(s) of this object will also be saved in the given file.

Examples

>>> import pyemma, numpy as np
>>> from pyemma.util.contexts import named_temporary_file
>>> m = pyemma.msm.MSM(P=np.array([[0.1, 0.9], [0.9, 0.1]]))

>>> with named_temporary_file() as file: # doctest: +SKIP
...    m.save(file, 'simple') # doctest: +SKIP
...    inst_restored = pyemma.load(file, 'simple') # doctest: +SKIP
>>> np.testing.assert_equal(m.P, inst_restored.P) # doctest: +SKIP
set_model_params(models=None, f_therm=None, pi=None, f=None, label='ground state')

Call to set all basic model parameters.

Parameters:
  • pi (ndarray(n)) – Stationary distribution. If not already normalized, pi will be scaled to fulfill \(\sum_i \pi_i = 1\). The free energies f will then be computed from pi via \(f_i = - \log(\pi_i)\).
  • f (ndarray(n)) – Discrete-state free energies. If normalized_f = True, a constant will be added to normalize the stationary distribution. Otherwise f is left as given. Then, pi will be computed from f via \(\pi_i = \exp(-f_i)\) and, if necessary, scaled to fulfill \(\sum_i \pi_i = 1\). If both (pi and f) are given, f takes precedence over pi.
  • normalize_energy (bool, default=True) – If parametrized by free energy f, normalize them such that \(\sum_i \pi_i = 1\), which is achieved by \(\log \sum_i \exp(-f_i) = 0\).
  • label (str, default=None) – Human-readable description for the thermodynamic state of this model. May contain a temperature description, such as ‘300 K’ or a description of bias energy such as ‘unbiased’ or ‘Umbrella 1’.
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]Shirts, M.R. and Chodera, J.D. 2008 Statistically optimal analysis of samples from multiple equilibrium states J. Chem. Phys. 129, 124105