TINKER explained

The easiest way to start using TINKER

mechanic.gif

Welcome to the section dedicated to TINKER, a freeware molecular modeling package to perform molecular mechanics (MM) and molecular dynamics (MD) calculations developed at Jay Ponder's Lab.
This page is my personal wiki of Tinker, it is not the official wiki of TINKER, nor it is related in anyway with TINKER. My opinions are not necessary those of the TINKER developers, therefore, if you are looking for their official wiki go here

I started to work with Tinker since the beginning of my PhD, 5 years ago, and I'm still using it for my research and for teaching purpose, since I found it a lot easier to learn and use than most of the MD software out there, and yet powerful enough to manage useful computational models. A major drawback of Tinker is the poor available documentation, therefore this wiki is the product of my experience and a lot of trial-and-error experiments: this means you do not have to take my words as absolute truth. Any help to improve this page is more than welcome.

News

Last update October 4th 2010

New TINKER tutorial: Build molecular systems for TINKER.


Sticky Notes

Bug fix for sniffer (version 5.1.09 and older)

there is a bug in sniffer.f. To solve, change "format (f20.0)" in line 89 into "format (i20)" and recompile TINKER.

Obtaining TINKER

You can download TINKER from the official home page.
TINKER is available for Windows, Linux/Unix and MAC OS X systems and a graphical user interface in Java can be downloaded here. The GUI is also included in the installation kits you can find at the TINKER home page. Personally I prefer use TINKER without GUI… the command line is fine and much powerful, so I usually download the source only.

Recently a new major release of TINKER came out (5.1), but the documentation has not yet been updated and it refers to 4.2 version. As far as I have understood, most of the basic concepts in TINKER 4.2 apply also to the new version. I hope the new documentation will be available soon.

License agreement and references

Selected references for TINKER Package:

P. Ren and J. W. Ponder, J. Phys. Chem. B, 107, 5933-5947 (2003)
P. Ren and J. W. Ponder, J. Comput. Chem., 23, 1497-1506 (2002)
R. V. Pappu, R. K. Hart and J. W. Ponder, J. Phys. Chem. B, 102, 9725-9742 (1998)
M. E. Hodsdon, J. W. Ponder and D. P. Cistola, J. Mol. Biol., 264, 585-602 (1996)
C. E. Kundrot, J. W. Ponder and F. M. Richards, J. Comput. Chem., 12, 402-409 (1991)
J. W. Ponder and F. M. Richards, J. Comput. Chem., 8, 1016-1024 (1987)

Conditions for Use of the TINKER Package:

The TINKER software is registered under U.S. Copyright Law. The source code was developed by the author and is distributed solely through the Department of Biochemistry and Molecular Biophysics at Washington University. Its use is subject to the following conditions:

(1) Use of this software is restricted to the individual, laboratory or organization to which it is supplied. The package and portions thereof may not be sold nor may copies be distributed to third parties without the express permission of the author and Washington University.
(2) This software package is provided on an "as is" basis. The author in no way warrants either this software or results it may produce.
(3) The author is under no obligation to provide any services by way of maintenance, updates or corrections for this software.
(4) Reports or publications resulting from use of this software package must contain an acknowledgment in the form commonly used in academic research.

Here the direct link to original pdf of the license agreement.

The complete reference list for TINKER 5.1 is here.

Force Field parameter sets

TINKER is shipped with many customized force field (FF) parameter sets for proteins, organic molecules, inorganic systems and so on. Here the list of the available FF (TINKER 4.2):

  • AMOEBA
  • AMOEBA PRO
  • AMBER94 -96 -98
  • CHARMM19 -27
  • DUDEK
  • ENCAD
  • HOCH
  • MM2
  • MM3(2000)
  • MM3PRO
  • OPLSUA
  • OPLSAA -L
  • SMOOTH -AA
  • WATER

A short description for the FFs above is included in the TINKER user guide, but I suggest to have a look to the actual files containing the FFs you are interested in. Force field files are stored in the directory params in the source distribution.
Home made force fields can be built, once the way TINKER uses the parameters is understood (actually, I managed to understand oplsaa only :P)

Compile TINKER (linux and mac os x)

TINKER can be compiled on many computer architectures and operative systems using many fortran compilers. Firstly, you need to download and uncompress the source distribution of TINKER. Then, the simplest way to compile TINKER is to copy all the required files for your operative system and fortran compiler into the source directory. Supposing you are on linux and you have g77 gfortran compiler, you should copy in source all the files in linux/gfortran directory of TINKER. After that, create a directory bin in TINKER and just execute the following list of commands:

rm -rf *.o *.a *.x
./compile.make
./library.make
./link.make
./rename.make

or, if we want to do all in once:

rm -rf *.o *.a *.x && ./compile.make && ./library.make && ./link.make && ./rename.make

The name of the executables can be changed editing the script rename.make.

Another way to compile tinker is to use the Makefile in the make directory of your TINKER distribution. Copy the Makefile in the source directory and edit it because you need to properly choose the installation dirs and the compiler you want to use.
Once the Makefile is correct, just type:

sudo make remove_links (if created. Sudo is needed if link dir is in /user/bin)
make clean
make all
make rename
sudo make create_links.

Note If you are using gfortran as compiler, be sure you are using gfortran-4.2: newer versions will not compile TINKER (or they will do but are really really slow, dunno why) Now gfortran seems to work.

Run TINKER calculations

To run a calculation with TINKER you need two files: the first contains the description of the model (i.e., atomic coordinates, atom types and atom connectivity), while the second file, the KEY file, contains all the instructions and properties for the calculations such as cutoff, new potentials parameters, unit cell definitions, thermostats, etc…

The TINKER XYZ file
The molecular model is described using the TINKER XYZ file format:

4016
1 C -31.3176308 -36.2778015 -2.63730001 50 2 31 1771
2 C -29.8976307 -36.2778015 -2.63730001 50 1 32 1772
3 C -27.0576305 -36.2778015 -2.63730001 50 4 33 1773
4 C -25.6376305 -36.2778015 -2.63730001 50 3 34 1774
5 C -22.7976303 -36.2778015 -2.63730001 50 6 35 1775
6 C -21.3776302 -36.2778015 -2.63730001 50 5 36 1776
7 C -18.5376301 -36.2778015 -2.63730001 50 8 37 1777
…

The first line contains the number of atoms in the model, followed by a line for each atom. These lines contain the progressive number of the atom in the model, the atom name, the atomic X- Y- Z- coordinates, the atom type and the connectivity, respectively. For connectivity I mean the progressive numbers of the atoms physically connected to the current one. To clarify the TINKER format, in the example above the Carbon atom 1, has coordinates indicated in the 3rd, 4th and 5th column, has atom type 50 (this depend on force field you are using, MM2/MM3 in this case) and it is connected to the atoms 2, 31 and 1771.

The TINKER KEY file
TINKER use a key file in order to set up the required calculation. Though is not strictly necessary, the use of a key file is, in my experience, highly recommended. The key file is used to specify (or define) the force field to be used by the simulation, and other important parameters like cutoff, unit cell, and more. Many of the possible keywords that you can set in the key file have a default value, which is used when you do not use explicitly the keyword: for example, if not specified, the cutoff will be set to 9Å. So, have a look in the manual to know which keywords have a default values that, if not set differently, will screw up your calculation ;)

Below an example of key file: the standard oplsaa force field is used and a new atom type has been defined. I have set the general cutoff to 15Å and I have specified the size of the periodic cell setting only the length of the cell vectors. Therefore, since angles have not been specified, their default values of 90º is used. Electrostatic are treated with the Ewald summation (pme) method. This key file is used to run NVT simulations using the Andersen thermostat with a coupling constant of 0.1ps. Finally, constraints on CH bond length are used and the first 2000 atoms in the model (representing a carbon nanotube) have been inactivated, i.e., frozen in their positions and left interacting only with active atoms.

#forcefield
parameters /home/aminoia/tinker/params/oplsaa.prm

#additional oplsaa parameters for pdmaema from gromacs oplsaa
atom      251     1    CT      "CH2 pdmaema"              6     12.000     4
charge  251 -0.06

#periodic cell specifications
a-axis 150
b-axis 122.9756
c-axis 150

#cutoffs
cutoff 15

#electrostatic
ewald

#thermostats and coupling
thermostat andersen
tau-temperature 0.1

#constraints
rattle
inactive -1 2000

TINKER has a number of algorithms used to carry out different calculations. The ones I use most are:

  • analyze, optimize and newton to minimize the structure
  • dynamic to perform NVE, NVT, NPT and NPH molecular dynamics
  • xyzedit to prepare the structure to model
  • radial to calculate radial distribution functions

but many others are available and shortly described in the manual.

The typical way to perform a task is to use one of the TINKER algorithms with the TINKER XYZ file, the key file and the appropriate parameters. Parameters, if missing, are asked interactively. For example:

analyze bithiophene.xyz -k 2t.key e

will print the energy of the structure in bithiophene.xyz using the informations found in the 2t.key key file. Usually, many information are printed on screen, therefore is useful to redirect the output of TINKER to a file for further analysis:

analyze bithiophene.xyz -k 2t.key e > energy.out

Submit TINKER calculation on clusters using a queuing system

Here an example of a script to submit TINKER calculations:

#!/bin/bash
#$ -N jobname
#$ -cwd
#$ -l virtual_free=1G
#$ -l h_cpu=32:00:00
#$ -j y

./cluster/apps/modules/etc/profile.modules
module load common

#Backup check file
if [ -f dyn.dyn ]
then
count = `ls *dyn.dyn* |wc -l`
count=$((count+1))
cp dyn.dyn backdyn.dyn_$count
fi

#Backup log file
if [ -f md.log ]
then
count = `ls *md.log* |wc -l`
count=$((count+1))
cp md.log md.log_$count
fi

~/tinker/bin/dynamic dyn.xyz -k dyn.key 1000000 1 1 2 300 >> md.log

This script is not universal: it works for me, but you may need some tuning to make it work for you: it depends mainly from which queuing system is installed on the server. What is important here, is backup the check file (.dyn) use to restart/continue dynamics (so, if a restarting fail we don't mess up the good check file) and to redirect the TINKER output from the screen to a file. This is the log for the molecular dynamics and it is worthy to backup it for later analysis. Also, mind that *all* the required parameters for the TINKER calculation must be given, since it will not be possible to use interactive mode once the script is submitted to the queue.

Tutorials

This is not part of the official documentation of TINKER program package, but have been ideated by me for this wiki. If you do use these tutorials for teaching, please consider to acknowledge Chembytes and spread the word.
You are welcome to improve the tutorial, and, if you do it, please consider to help me improve Chembytes and send me your tutorial or become member of Chembytes and write it yourself. Don't worry, you will be properly acknowledged for your work.

Build molecular systems for TINKER

This tutorial will cover how to build several kind of molecular systems for TINKER, such as single molecules, polymers, surfaces, solvent boxes and nanotubes. Read more...

Analyze and optimize a peptide molecule

This tutorial will cover the analysis and the optimization of TINKER structures, using a peptide as test molecule. Different minimization algorithms are described and compared. Read more...

Work with internal coordinates

This tutorial will cover how to use to internal coordinates in TINKER. The internal coordinate format is described and different utilities and algorithms are used. The test case molecule is a simple ethane. Read more...

Troubleshooting, aka WTF?!

Sometimes, in particular with Tinker, RTFM is not the policy will put you back in business. This section is dedicated to the most common source of problems in Tinker. These are the problems I have encountered and this is how I have solved (or not) them. Always, triple check what I have written with critical eye before apply my solutions to your research

Missing parameters: Unable to continue

Some potential parameters are missing in the force field. You need to find a way to include all the parameters in the force field. If you are using OPLSAA, you can try to steal the missing parameters from the OPLSAA for GROMACS (see TIps and Tricks section). Another source of parameters is, of course the literature. Worst case, you may try to extract the parameters from quantum chemical calculations. This is also a good way to improve existing force field parameters for highly accurate versions of the force field for specific molecules.

Increase a parameter, e.g. maxatm

Something in your systems is exceeding the size of one (or more) parameters. Being written in Fortran, sizes of vectors and matrices are hard coded in the source. That is, increase the value for the proper parameter and recompile the program.Many of the parameters are in the file sizes.i. Problems with pme and ewald could be fixed by increasing the value of MAXVEC parameter in ewreg.i file. Anyway, using grep to try to locate the parameter to increase is quite easy.
Probably, you could recompile only the code that is affected by your modification, but since compile all the sources is quite fast, I always recompile entirely TINKER.

Zero energies and nan G RMS

If you are going to freeze, i.e., inactivate, part of your system, be careful you are leaving something free to move. If you, by mistake, inactivate all the atoms you will have problems in running your calculations: if you analyze the energy, you will get zero energy and no energy breakdown. If you are going to minimize or optimize the system, your G RMS value is nan. Dynamics will run, but the energy will stay zero forever.

Where did my inactive atoms go?

When you use the INACTIVE keyword, another source of problems is that inactive structures are not included in the trajectory. With this I mean that if you use also the ARCHIVE keyword in the key file or you run the program archive with the key file containing the INACTIVE directive, the inactive atoms are not included in the resulting trajectory file (arc file). That is quite a pain in the neck, because you may want to analyze the structure or do some post-production analysis that could involve the inactive structure. A typical example is the study of molecules on surface, where the surface is set inactive: if you loose the surface, then you will not be able to recover the intermolecular interactions between molecules and surface along the MD trajectory. My suggestion is to avoid to use the ARCHIVE keyword along with INACTIVE. This will force TINKER to create a complete structure for each frame that is going to be saved. Then use the archive program, without specifying the key file, to create the arc file.

Limits in Rigid Body Calculations

The only way to do a rigid body simulation is to use the GROUP/GROUP-MOLECULE keyword along with GROUP-INTER. Unfortunately, if you use GROUP, all the atoms in the systems must be assigned to a group. Therefore is not possible, as far as I know, do rigid body calculations on a part of the system only, e.g. treating only some parts of a molecule as rigid body.

I got Killed

Sometimes, it can happen that a perfectly compiled version of TINKER will stop to work and the only error message you will get is Killed . I strongly suspect this has to do with some problem in managing the memory, in particular when TINKER is compiled for a big number of atoms. TINKER does not use dynamic allocation of memory, therefore, if for some reason the system does not have enough free memory the program will fail to run. The main clue I have to say the problem is related to the amount of available memory, is the fact that TINKER will get back to work if the machine is rebooted. I have noticed in Linux that the cached (inactive in mac os x) memory does not seems to be "good enough" for TINKER.
The first step is then try to understand how much memory we need to free. The amount of memory required by a program can be checked, under *nix-based systems, with the command size, e.g.:

size /home/minoiaa/tinker/bin/minimize

which on mac os x produces an output like the following one:

__TEXT    __DATA    __OBJC    others    dec    hex
1376256    907771904    0    36864    909185024    36311000

Here, the total amount of bytes required by the program is 909185024 (in decimal, or 36311000 in hexadecimal), i.e., minimize need to allocate 909185024/1024^2=867MB of memory.

The output in linux is not that different, but you can always RTFM ;)

man size

I then suspect that if the free memory (not cached) is less than the value we have just calculated, the program will fail. Unfortunately, /var/log/messages does not report any error related to the reason why the program crash. If reboot is not possible (or not desirable), you can try to force the system to free the cached memory. Thanks to my sysadmin, I had an example of code written in Fortran 90 that should do the trick. I have modified it and commented, but, as usually you are all alone if you want to use this program: NO WARRANTY IS GIVEN, THEREFORE NO LIABILITY IS ACCEPTED

c FORTRAN 90 code to free memory
c **NO WARRANTY IS GIVEN, THEREFORE NO LIABILITY IS ACCEPTED**
c  g is an integer to specify how much g memory must be free
        real g
        allocatable::i(:)
c imax set the minimal amount of memory to free (g=1)
c Here free 1gb when an integer is represented
c with 32bits (32*8*1024*1024=268435456=1GB)
c you may want to change this number to free a different amount of ram.
c the total amount of memory that will be free, if possible is g*imax.
        imax=268435456
        write(*,*) 'how many G memory do you want to free? (G must be an integer)'
        read(*,*) g
        imax=g*imax
        allocate(i(imax))
        do j=1,imax
        i(j)=j
        enddo
        deallocate(i)
        end

The program will allocate dynamically the specified amount of memory using the cached and free memory. Once all the memory is allocated, it is deallocated, i.e. becomes free memory (not cached). That should do the trick.

Tip and Tricks, aka How can I do this and that?

Use GROMACS OPLSAA parameters with TINKER

Analyze TINKER structures

Rigid body calculations and stochastic dynamics

Build a solvent box

Comments

Add a New Comment
or Sign in as Wikidot user
(will not be published)
- +
Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License