pyemma.thermo.TRAM

class pyemma.thermo.TRAM(lag, count_mode='sliding', connectivity='summed_count_matrix', ground_state=None, nstates_full=None, equilibrium=None, maxiter=10000, maxerr=1e-15, save_convergence_info=0, dt_traj='1 step', nn=None, connectivity_factor=1.0, direct_space=False, N_dtram_accelerations=0, callback=None, init='mbar', init_maxiter=5000, init_maxerr=1e-08)

Transition(-based) Reweighting Analysis Method

Parameters:
  • lag (int) – Integer lag time at which transitions are counted.
  • count_mode (str, optional, default='sliding') –

    mode to obtain count matrices from discrete trajectories. Should be one of: * ‘sliding’ : A trajectory of length T will have \(T-\tau\) counts at time indexes

    \[(0 \rightarrow \tau), (1 \rightarrow \tau+1), ..., (T-\tau-1 \rightarrow T-1)\]
    • ‘sample’ : A trajectory of length T will have \(T/\tau\) counts at time indexes
      \[(0 \rightarrow \tau), (\tau \rightarrow 2 \tau), ..., ((T/\tau-1) \tau \rightarrow T)\]

    Currently only ‘sliding’ is supported.

  • 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.
  • ground_state (int, optional, default=None) – Index of the unbiased thermodynamic state or None if there is no unbiased data available.
  • nstates_full (int, optional, default=None) – Number of cluster centers, i.e., the size of the full set of states.
  • equilibrium (list of booleans, optional) – For every trajectory triple (ttraj[i], dtraj[i], btraj[i]), indicates whether to assume global equilibrium. If true, the triple is not used for computing kinetic quantities (but only thermodynamic quantities). By default, no trajectory is assumed to be in global equilibrium. This is the TRAMMBAR extension.
  • maxiter (int, optional, default=10000) – The maximum number of self-consistent 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*’
  • 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
    ‘mbar’: perform a short MBAR estimate to initialize the free energies
  • init_maxiter (int, optional, default=5000) – The maximum number of self-consistent iterations during the initialization.
  • init_maxerr (float, optional, default=1.0E-8) – Convergence criterion for the initialization.

References

[1]Wu, H. et al 2016 Multiensemble Markov models of molecular thermodynamics and kinetics Proc. Natl. Acad. Sci. USA 113 E3221–E3230
__init__(lag, count_mode='sliding', connectivity='summed_count_matrix', ground_state=None, nstates_full=None, equilibrium=None, maxiter=10000, maxerr=1e-15, save_convergence_info=0, dt_traj='1 step', nn=None, connectivity_factor=1.0, direct_space=False, N_dtram_accelerations=0, callback=None, init='mbar', init_maxiter=5000, init_maxerr=1e-08)

Methods

__init__(lag[, count_mode, connectivity, ...])
estimate(X, **params)
param X:Simulation trajectories. ttrajs contain the indices of the thermodynamic state, dtrajs
expectation(a) Equilibrium expectation value of a given observable.
fit(X) Estimates parameters - for compatibility with sklearn.
get_model_params([deep]) Get parameters for this model.
get_params([deep]) Get parameters for this estimator.
log_likelihood() Returns the value of the log-likelihood of the converged TRAM estimate.
mbar_pointwise_free_energies([therm_state])
meval(f, *args, **kw) Evaluates the given function call for all models
pointwise_free_energies([therm_state]) Computes the pointwise free energies \(-\log(\mu^k(x))\) for all points x.
register_progress_callback(call_back[, stage]) Registers the progress reporter.
set_model_params([models, f_therm, pi, f, label])
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
f_full_state The free energies of discrete states
free_energies
free_energies_full_state
logger The logger for this class instance
model The model estimated by this Estimator
model_active_set
msm
msm_active_set
name The name of this instance
nstates Number of active states on which all computations and estimations are done
nstates_full
pi_full_state
show_progress whether to show the progress of heavy calculations on this object.
stationary_distribution The stationary distribution
stationary_distribution_full_state
unbiased_state
estimate(X, **params)
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 element 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. :param a: Observable vector :type a: (M,) ndarray

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_full_state

The free energies of discrete states

fit(X)

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
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
log_likelihood()

Returns the value of the log-likelihood of the converged TRAM estimate.

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

pointwise_free_energies(therm_state=None)

Computes the pointwise free energies \(-\log(\mu^k(x))\) for all points x.

\(\mu^k(x)\) is the optimal estimate of the Boltzmann distribution of the k’th ensemble defined on the set of all samples.

Parameters:therm_state (int or None, default=None) – Selects the thermodynamic state k for which to compute the pointwise free energies. None selects the “unbiased” state which is defined by having zero bias energy.
Returns:mu_k – list of the same layout as dtrajs (or ttrajs). mu_k[i][t] contains the pointwise free energy of the frame seen in trajectory i and time step t. Frames that are not in the connected sets get assiged an infinite pointwise free energy.
Return type:list of numpy.ndarray(X_i, dtype=numpy.float64)
register_progress_callback(call_back, stage=0)

Registers the progress reporter.

Parameters:
  • call_back (function) –

    This function will be called with the following arguments:

    1. stage (int)
    2. instance of pyemma.utils.progressbar.ProgressBar
    3. optional *args and named keywords (**kw), for future changes
  • stage (int, optional, default=0) – The stage you want the given call back function to be fired.
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

show_progress

whether to show the progress of heavy calculations on this object.

stationary_distribution

The stationary distribution

update_model_params(**params)

Update given model parameter if they are set to specific values