User guide¶

Getting started¶

The pytram package comes with two examples for dTRAM and xTRAM in the form of ipython notebooks. In order to run run them, go the root directory of the pytram repositroy and type

ipython notebook dTRAM_example.ipynb

in your shell for dTRAM or

ipython notebook xTRAM_example.ipynb

for xTRAM, respectively. These examples will illustrate the basic usage of the API functions and the necessary data preparation.

Another way is a file-based approach which allows you to store simulation results for later analysis. To this aim, we have specified the required file format in the next section and implemented a reader function to import such data into pytram. Using file-based input data allows you to run pytram

from the API using a Reader and the TRAMData converter or

using run scripts directly from the shell.

The latter option requires the least effort, however, also offers only limited flexibility.

File format¶

The standard file format assumes text files with the following layout.

# This is a comment line, you can several of those.
# The next lines indicates the meaning of the columns,
# [M] denotes Markov state indices (starting from zero),
# [T] denotes thermodynamic state indices (starting from zero),
# and [b_K] denotes the reduced bias energies b_K/kT
# [M]  [T]  [b_0]  [b_1]  ...
   0    0    3.1   18.2
   1    0    3.2   18.3
   2    0    4.8   19.9
   3    0    7.4   22.5
   .    .      .      .
   .    .      .      .
   .    .      .      .

The minimal layout only requires the [M] and [T] columns and can only be used for dTRAM. These two columns contain the sequences of the Markov and generating thermodynamic states. For example, the entry 3 0 denotes that the actual sample corresponds to the Markov state 3 and was generated at thermodynamic state 0.

Important note: in order to run dTRAM successfully, you need an additional b_K_i file as explained in the dTRAM section.

The other TRAM estimators require at least one energy column. For this, we distinguish two different cases: temperature as the only thermodynamic variable, and all other thermodynamic conditions, i.e., different Hamiltonians, umbrella potentials, ...

Temperature as only thermodynamic variable¶

In this case, you need the [M] and [T] columns, and one energy column [b_K]; this column contains the reduced energy sequence. The energy is reduced according to the generating thermodynamic state. For example, the entry 2 5 20.5 denotes that the actual sample corresponds to the Markov state 2, was generated at temperature kT_5, and the corresponding energy was reduced with kT_5.

Important note: for temperature-dependent simulations, you need an additional single column kT file wich indicates all generating temperatures times the Boltzmann constant (consistent with your energy units). Note that the order of kT values must be constistent with the numbering of the thermodynamic states.

Hamiltonian replica exchange, umbrella sampling, etc¶

This is the most general application. Here, each sample must be evaluated at all thermodynamic states which means that you need as many energy columns as you have thermodynamic states. For example, the line 2 1 3.0 2.9 1.0 0.3 indicates that the actual sample corresponds to the Markov state 2, has been generated at thermodynamic state 1, the reduced energy is

3.0 kT at thermodynamic state 0,

2.9 kT at thermodynamic state 1,

1.0 kT at thermodynamic state 2, and

0.3 kT at thermodynamic state 3.

This example also requires you to have exactly four thermodynamic states.

Running dTRAM¶

from files¶

Assume that we have two files file_1.dat and file_2.dat with simulation data. In addition to that, the dTRAM method requires the user to specify the reduced bias energies of all Markov states in each of the thermodynamic states. The corresponding file format is given by

# we store the reduced bias energies b_K(x)/kT
# at the discrete states x_i
# [b_0]  [b_1]  ...
   0.0    4.0
   0.0    0.0
   0.0    8.0

In this example, we have three Markov states which are evaluated at two different thermodynamic states.

Using the API, we can run dTRAM via the following code:

# import the Reader, TRAMData and the dtram API function
from pytram import Reader, TRAMData, dtram

# specify your input data files
files = [
      'path/to/file_1.dat',
      'path/to/file_2.dat'
   ]
b_K_i_file = 'path/to/b_K_i_file.dat'

# import the files using the Reader
reader = Reader( files, b_K_i_file=b_K_i_file, verbose=True )

# convert the input data using TRAMData
data = TRAMData( reader.trajs, b_K_i=reader.b_K_i )

# run dTRAM using the API function
dtram_obj = dtram( data, maxiter=1000, ftol=1.0E-10, verbose=True )

# show unbiased stationary distribution
print dtram_obj.pi_i

# get transition matrix for thermodynamic state 0
T_0 = dtram_obj.estimate_transtition_matrix( 0 )
print T_0

# show thermodynamic free energies
print dtram_obj.f_K

Optionally, we can use the dTRAM run script from shell. Simply type

dtram.py --b_K_i_file=path/to/b_K_i_file.dat --verbose path/to/file_1.dat path/to/file_2.dat

and enjoy the show. Note that the run script will not work if the pytram package has not been properly installed!

You can run

dtram.py --help

for additional information on available parameters.

from seqential data¶

The data preparation and the API usage is shown in the ipython example.