pyemma.thermo.MBAR¶

class pyemma.thermo.MBAR(maxiter=10000, maxerr=1e-15, save_convergence_info=0, dt_traj='1 step', direct_space=False)¶

Multi-state Bennet Acceptance Ratio Method.

__init__(maxiter=10000, maxerr=1e-15, save_convergence_info=0, dt_traj='1 step', direct_space=False)¶

Multi-state Bennet Acceptance Ratio Method

Parameters:

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

References

Methods

__init__([maxiter, maxerr, …]) Multi-state Bennet Acceptance Ratio Method

estimate(X)

param X:	Simulation trajectories.

expectation(a) Equilibrium expectation value of a given observable.

fit(X[, y]) Estimates parameters - for compatibility with sklearn.

get_model_params([deep]) Get parameters for this model.

get_params([deep]) Get parameters for this estimator.

load(file_name[, model_name]) loads a previously saved object of this class from a file.

meval(f, *args, **kw) Evaluates the given function call for all models Returns the results of the calls in a list

pointwise_free_energies([therm_state])

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.

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.
`dt_traj`
`f`	The free energies (in units of kT) on the configuration states.
`f_full_state`
`force_constants`	The individual force matrices labelled accordingly to ttrajs.
`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
`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`
`stationary_distribution`	The stationary distribution on the configuration states.
`stationary_distribution_full_state`
`temperatures`	The individual temperatures labelled accordingly to ttrajs.
`umbrella_centers`	The individual umbrella centers labelled accordingly to ttrajs.
`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(X)¶

Parameters:

X (tuple of (ttrajs, dtrajs, btrajs)) –

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

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.
btrajs : list of numpy.ndarray((X_i, T), dtype=numpy.float64): For every simulation frame seen in trajectory i and time step t, btrajs[i][t,k] is the bias energy of that frame evaluated in the k’th thermodynamic state (i.e. at the k’th Umbrella/Hamiltonian/temperature).

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, y=None)¶

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

force_constants¶: The individual force matrices labelled accordingly to ttrajs. (only set, when estimated from umbrella data).

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.

classmethod load(file_name, model_name='default')¶

loads a previously saved object of this class from a file.

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 func:`pyemma.list_models` to get a representation of all stored models.
Returns:	obj
Return type:	the de-serialized object

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.

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: 
...    m.save(file, 'simple') 
...    inst_restored = pyemma.load(file, 'simple') 
>>> np.testing.assert_equal(m.P, inst_restored.P) 

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’.

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

stationary_distribution¶: The stationary distribution on the configuration states.

temperatures¶: The individual temperatures labelled accordingly to ttrajs. (only set, when estimated from multi-temperature data).

umbrella_centers¶: The individual umbrella centers labelled accordingly to ttrajs. (only set, when estimated from umbrella data).

unbiased_state¶: Index of the unbiased thermodynamic state.

update_model_params(**params)¶: Update given model parameter if they are set to specific values