docs/user-guide/getting-started.rst

   1 Getting started
   2 ===============
   3
   4 .. toctree::
   5    :hidden:
   6
   7    flow
   8
   9 In this chapter we assume the reader is familiar with Molecular Dynamics and
  10 familiar with Unix, including the use of a text editor such as ``jot``, ``emacs``
  11 or ``vi``. We furthermore assume the |Gromacs| software is installed properly on
  12 your system. When you see a line like
  13
  14 ::
  15
  16     ls -l
  17
  18 you are supposed to type the contents of that line on your computer terminal.
  19
  20 Setting up your environment
  21 ---------------------------
  22 In order to check whether you have access to |Gromacs|, please
  23 start by entering the command:
  24
  25 ::
  26
  27     gmx -version
  28
  29 This command should print out information about the version of |Gromacs|
  30 installed. If this, in contrast, returns the phrase
  31
  32 ::
  33
  34     gmx: command not found.
  35
  36 then you have to find where your version of |Gromacs| is installed. In
  37 the default case, the binaries are located in
  38 ``/usr/local/gromacs/bin``, however, you can ask your local system
  39 administrator for more information, and then follow the advice for
  40 :ref:`getting access to |Gromacs|`.
  41
  42 Flowchart of typical simulation
  43 -------------------------------
  44 A typical simulation workflow with |Gromacs| is :doc:`illustrated here <flow>`.
  45
  46 Important files
  47 ---------------
  48 Here is an overview of the most important |Gromacs| file types that you will
  49 encounter.
  50
  51 Molecular Topology file (``.top``)
  52 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  53
  54 The molecular topology file is generated by the program :ref:`gmx pdb2gmx`.
  55 :ref:`gmx pdb2gmx` translates a :ref:`PDB` structure file of any
  56 peptide or protein to a molecular topology file. This topology file
  57 contains a complete description of all the interactions in your
  58 peptide or protein.
  59
  60 .. _gmx-topo-include:
  61
  62 Topology #include file mechanism
  63 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  64
  65 When constructing a system topology in a :ref:`top` file for presentation to grompp,
  66 GROMACS uses a built-in version of the so-called C preprocessor, cpp (in GROMACS 3, it really was cpp). cpp interprets lines like::
  67
  68     #include "ions.itp"
  69
  70 by looking for the indicated file in the current directory, the GROMACS share/top directory as indicated
  71 by the GMXLIB environment variable, and any directory indicated by a ``-I`` flag in the value of the
  72 include :mdp:`run parameter <include>` in the :ref:`mdp` file. It either finds this file or reports
  73 a warning. (Note that when you supply a directory name, you should use Unix-style forward
  74 slashes '/', not Windows-style backslashes '\' for separators.) When found, it then uses the contents
  75 exactly as if you had cut and pasted the included file into the main file yourself. Note that you shouldn't
  76 go and do this copy-and-paste yourself, since the main purposes of the include file mechanism are to re-use
  77 previous work, make future changes easier, and prevent typos.
  78
  79 Further, ``cpp`` interprets code such as::
  80
  81     #ifdef POSRES_WATER
  82     ; Position restraint for each water oxygen
  83     [ position_restraints ]
  84     ;  i funct       fcx        fcy        fcz
  85         1    1       1000       1000       1000
  86     #endif
  87
  88 by testing whether the preprocessor variable ``POSRES_WATER`` was defined somewhere (i.e. "if defined").
  89 This could be done with ``#define POSRES_WATER`` earlier in the :ref:`top` file (or its ``#include`` files),
  90 with a ``-D`` flag in the ``include`` run parameter as above, or on the command line to ``cpp``.
  91 The function of the ``-D`` flag is borrowed from the similar usage in ``cpp``. The string that
  92 follows ``-D`` must match exactly; using ``-DPOSRES`` will not trigger ``#ifdef POSRE`` or ``#ifdef DPOSRES``.
  93 This mechanism allows you to change your :ref:`mdp` file to choose whether or not you want position
  94 restraints on your solvent, rather than your :ref:`top` file. Note that preprocessor variables
  95 are not the same as shell environment variables.
  96
  97 .. _gmx-need-for-gro:
  98
  99 Molecular Structure file (``.gro``, ``.pdb``)
 100 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 101
 102 When :ref:`gmx pdb2gmx` is executed to generate a molecular topology, it
 103 also translates the structure file (:ref:`pdb` file) to a GROMOS structure
 104 file (:ref:`gro` file). The main difference between a :ref:`pdb` file and a gromos
 105 file is their format and that a :ref:`gro` file can also hold
 106 velocities. However, if you do not need the velocities, you can also
 107 use a :ref:`PDB` file in all programs. To generate a box of solvent
 108 molecules around the peptide, the program :ref:`gmx solvate` is
 109 used. First the program :ref:`gmx editconf` should be used to define a box
 110 of appropriate size around the molecule. :ref:`gmx solvate` solvates a
 111 solute molecule (the peptide) into any solvent (in this case,
 112 water). The output of :ref:`gmx solvate` is a gromos structure file of the
 113 peptide solvated in water. :ref:`gmx solvate` also changes the molecular
 114 topology file (generated by :ref:`gmx pdb2gmx`) to add solvent to the
 115 topology.
 116
 117 Molecular Dynamics parameter file (``.mdp``)
 118 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 119
 120 The Molecular Dynamics Parameter (:ref:`mdp`) file contains all information
 121 about the Molecular Dynamics simulation itself e.g. time-step, number
 122 of steps, temperature, pressure etc. The easiest way of handling such
 123 a file is by adapting a sample :ref:`mdp` file. A :ref:`sample mdp file <mdp>`
 124 is available.
 125
 126 Index file (``.ndx``)
 127 ^^^^^^^^^^^^^^^^^^^^^
 128
 129 Sometimes you may need an index file to specify actions on groups of
 130 atoms (e.g. temperature coupling, accelerations, freezing). Usually
 131 the default index groups will be sufficient, so for this demo we will
 132 not consider the use of index files.
 133
 134 Run input file (``.tpr``)
 135 ^^^^^^^^^^^^^^^^^^^^^^^^^
 136
 137 The next step is to combine the molecular structure (:ref:`gro` file),
 138 topology (:ref:`top` file) MD-parameters (:ref:`mdp` file) and (optionally) the
 139 index file (:ref:`ndx`) to generate a run input file (:ref:`tpr` extension). This
 140 file contains all information needed to start a simulation with
 141 |Gromacs|. The :ref:`gmx grompp` program processes all input files and
 142 generates the run input :ref:`tpr` file.
 143
 144 Trajectory file (``.trr``, ``.tng``, or ``.xtc``)
 145 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 146
 147 Once the run input file is available, we can start the simulation. The
 148 program which starts the simulation is called :ref:`gmx mdrun` (or
 149 sometimes just mdrun, or mdrun_mpi). The only input file of :ref:`gmx mdrun`
 150 that you usually need in order to start a run is the run input
 151 file (:ref:`tpr` file). The typical output files of :ref:`gmx mdrun` are the
 152 trajectory file (:ref:`trr` file), a logfile (:ref:`log` file), and perhaps a
 153 checkpoint file (:ref:`cpt` file).
 154
 155 Tutorial material
 156 -----------------
 157 There are many tutorials_ available that cover aspects of using |Gromacs|.
 158
 159 Background reading
 160 ------------------
 161 *   Berendsen, H.J.C., Postma, J.P.M., van Gunsteren, W.F., Hermans, J. (1981)
 162     Intermolecular Forces, chapter Interaction models for water in relation to
 163     protein hydration, pp 331-342. Dordrecht: D. Reidel Publishing Company
 164     Dordrecht
 165 *   Kabsch, W., Sander, C. (1983).     Dictionary of protein secondary
 166     structure: Pattern recognition of hydrogen-bonded and geometrical features.
 167     Biopolymers **22**, 2577--2637.
 168 *   Mierke, D.F., Kessler, H. (1991).     Molecular dynamics with dimethyl
 169     sulfoxide as a solvent. Conformation of a cyclic hexapeptide. J. Am. Chem.
 170     Soc. **113**, 9446.
 171 *   Stryer, L. (1988).     Biochemistry vol. 1, p. 211. New York: Freeman, 3
 172     edition.