pyemma.thermo.TRAM

class pyemma.thermo.TRAM(lag, count_mode='sliding', connectivity='summed_count_matrix', ground_state=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.

  • 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*’
  • 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
    ‘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 in press
__init__(lag, count_mode='sliding', connectivity='summed_count_matrix', ground_state=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

free_energies The free energies of discrete states
logger The logger for this class instance
model The model estimated by this Estimator
msm
msm_active_set
name The name of this instance
nstates Number of active states on which all computations and estimations are done
show_progress whether to show the progress of heavy calculations on this object.
stationary_distribution The stationary distribution
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 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. :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\).

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
free_energies

The free energies of discrete 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
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