pyemma.thermo.estimate_umbrella_sampling¶

pyemma.thermo.estimate_umbrella_sampling(us_trajs, us_dtrajs, us_centers, us_force_constants, md_trajs=None, md_dtrajs=None, kT=None, maxiter=10000, maxerr=1e-15, save_convergence_info=0, estimator='wham', lag=1, dt_traj='1 step', init=None, init_maxiter=10000, init_maxerr=1e-08, width=None, **kwargs)¶

This function acts as a wrapper for tram(), dtram(), mbar(), and wham() and handles the calculation of bias energies (bias) and thermodynamic state trajectories (ttrajs) when the data comes from umbrella sampling and (optional) unbiased simulations.

Parameters:	us_trajs (list of N arrays, each of shape (T_i, d)) – List of arrays, each having T_i rows, one for each time step, and d columns where d is the dimensionality of the subspace in which umbrella sampling was applied. Often d=1, and thus us_trajs will be a list of 1d-arrays. us_dtrajs (list of N int arrays, each of shape (T_i,)) – The integers are indexes in 0,…,n-1 enumerating the n discrete states or the bins the umbrella sampling trajectory is in at any time. us_centers (list of N floats or d-dimensional arrays of floats) – List or array of N center positions. Each position must be a d-dimensional vector. For 1d umbrella sampling, one can simply pass a list of centers, e.g. [-5.0, -4.0, -3.0, … ]. us_force_constants (list of N floats or d- or dxd-dimensional arrays of floats) – The force constants used in the umbrellas, unit-less (e.g. kT per squared length unit). For multidimensional umbrella sampling, the force matrix must be used. md_trajs (list of M arrays, each of shape (T_i, d), optional, default=None) – Unbiased molecular dynamics simulations; format like us_trajs. md_dtrajs (list of M int arrays, each of shape (T_i,)) – The integers are indexes in 0,…,n-1 enumerating the n discrete states or the bins the unbiased trajectory is in at any time. kT (float or None, optional, default=None) – Use this attribute if the supplied force constants are NOT unit-less; kT must have the same energy unit as the force constants. 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. estimator (str, optional, default='wham') – Specify one of the available estimators ’wham’: use WHAM ’mbar’: use MBAR ’dtram’: use the discrete version of TRAM ’tram’: use TRAM 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. 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’ init (str, optional, default=None) – Use a specific initialization for the 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 (only with dtram) ’mbar’: perform a short MBAR estimate to initialize the free energies (only with tram) 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. width (array-like of float, optional, default=None) – Specify periodicity for individual us_traj dimensions. Each positive entry will make the corresponding feature periodic and use the given value as width. None/zero values will be treated as non-periodic. *kwargs (dict, optional*) – You can use this to pass estimator-specific named parameters to the chosen estimator, which are not already coverd by `estimate_umbrella_sampling()`.
Returns:	The requested estimator/model object, i.e., WHAM, MBAR, DTRAM or TRAM. If multiple lag times are given, a list of objects is returned (one MEMM per lag time).
Return type:	A `MultiThermModel` or `MEMM` object or list thereof

Example

We look at a 1D umbrella sampling simulation with two umbrellas at 1.1 and 1.3 on the reaction coordinate with spring constant of 1.0; additionally, we have two unbiased simulations.

We start with a joint clustering and use TRAM for the estimation:

>>> from pyemma.coordinates import cluster_regspace as regspace
>>> from pyemma.thermo import estimate_umbrella_sampling as estimate_us
>>> import numpy as np
>>> us_centers = [1.1, 1.3]
>>> us_force_constants = [1.0, 1.0]
>>> us_trajs = [np.array([1.0, 1.1, 1.2, 1.1, 1.0, 1.1]).reshape((-1, 1)), np.array([1.3, 1.2, 1.3, 1.4, 1.4, 1.3]).reshape((-1, 1))]
>>> md_trajs = [np.array([0.9, 1.0, 1.1, 1.2, 1.3, 1.4]).reshape((-1, 1)), np.array([1.5, 1.4, 1.3, 1.4, 1.4, 1.5]).reshape((-1, 1))]
>>> cluster = regspace(data=us_trajs+md_trajs, max_centers=10, dmin=0.15)
>>> us_dtrajs = cluster.dtrajs[:2]
>>> md_dtrajs = cluster.dtrajs[2:]
>>> centers = cluster.clustercenters
>>> tram = estimate_us(us_trajs, us_dtrajs, us_centers, us_force_constants, md_trajs=md_trajs, md_dtrajs=md_dtrajs, estimator='tram', lag=1)
>>> tram.f # doctest: +ELLIPSIS
array([ 0.63...,  1.60...,  1.31...])

See MultiThermModel or MEMM 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

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.
`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.
`msm`	MSM of the unbiased thermodynamic state; only present when unbiased data available.
`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

msm¶: MSM of the unbiased thermodynamic state; only present when unbiased data available.

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