docs/user-guide/getting-started.rst

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