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 Molecular Structure file (``.gro``, ``.pdb``)
  61 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  62
  63 When :ref:`gmx pdb2gmx` is executed to generate a molecular topology, it
  64 also translates the structure file (:ref:`pdb` file) to a GROMOS structure
  65 file (:ref:`gro` file). The main difference between a :ref:`pdb` file and a gromos
  66 file is their format and that a :ref:`gro` file can also hold
  67 velocities. However, if you do not need the velocities, you can also
  68 use a :ref:`PDB` file in all programs. To generate a box of solvent
  69 molecules around the peptide, the program :ref:`gmx solvate` is
  70 used. First the program :ref:`gmx editconf` should be used to define a box
  71 of appropriate size around the molecule. :ref:`gmx solvate` solvates a
  72 solute molecule (the peptide) into any solvent (in this case,
  73 water). The output of :ref:`gmx solvate` is a gromos structure file of the
  74 peptide solvated in water. :ref:`gmx solvate` also changes the molecular
  75 topology file (generated by :ref:`gmx pdb2gmx`) to add solvent to the
  76 topology.
  77
  78 Molecular Dynamics parameter file (``.mdp``)
  79 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  80
  81 The Molecular Dynamics Parameter (:ref:`mdp`) file contains all information
  82 about the Molecular Dynamics simulation itself e.g. time-step, number
  83 of steps, temperature, pressure etc. The easiest way of handling such
  84 a file is by adapting a sample :ref:`mdp` file. A :ref:`sample mdp file <mdp>`
  85 is available.
  86
  87 Index file (``.ndx``)
  88 ^^^^^^^^^^^^^^^^^^^^^
  89
  90 Sometimes you may need an index file to specify actions on groups of
  91 atoms (e.g. temperature coupling, accelerations, freezing). Usually
  92 the default index groups will be sufficient, so for this demo we will
  93 not consider the use of index files.
  94
  95 Run input file (``.tpr``)
  96 ^^^^^^^^^^^^^^^^^^^^^^^^^
  97
  98 The next step is to combine the molecular structure (:ref:`gro` file),
  99 topology (:ref:`top` file) MD-parameters (:ref:`mdp` file) and (optionally) the
 100 index file (:ref:`ndx`) to generate a run input file (:ref:`tpr` extension). This
 101 file contains all information needed to start a simulation with
 102 |Gromacs|. The :ref:`gmx grompp` program processes all input files and
 103 generates the run input :ref:`tpr` file.
 104
 105 Trajectory file (``.trr``, ``.tng``, or ``.xtc``)
 106 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 107
 108 Once the run input file is available, we can start the simulation. The
 109 program which starts the simulation is called :ref:`gmx mdrun` (or
 110 sometimes just mdrun, or mdrun_mpi). The only input file of :ref:`gmx mdrun`
 111 that you usually need in order to start a run is the run input
 112 file (:ref:`tpr` file). The typical output files of :ref:`gmx mdrun` are the
 113 trajectory file (:ref:`trr` file), a logfile (:ref:`log` file), and perhaps a
 114 checkpoint file (:ref:`cpt` file).
 115
 116 Tutorial material
 117 -----------------
 118 There are many tutorials_ available that cover aspects of using |Gromacs|.
 119
 120 Background reading
 121 ------------------
 122 *   Berendsen, H.J.C., Postma, J.P.M., van Gunsteren, W.F., Hermans, J. (1981)
 123     Intermolecular Forces, chapter Interaction models for water in relation to
 124     protein hydration, pp 331-342. Dordrecht: D. Reidel Publishing Company
 125     Dordrecht
 126 *   Kabsch, W., Sander, C. (1983).     Dictionary of protein secondary
 127     structure: Pattern recognition of hydrogen-bonded and geometrical features.
 128     Biopolymers **22**, 2577--2637.
 129 *   Mierke, D.F., Kessler, H. (1991).     Molecular dynamics with dimethyl
 130     sulfoxide as a solvent. Conformation of a cyclic hexapeptide. J. Am. Chem.
 131     Soc. **113**, 9446.
 132 *   Stryer, L. (1988).     Biochemistry vol. 1, p. 211. New York: Freeman, 3
 133     edition.