docs/user-guide/getting-started.rst

   1 Getting started
   2 ===============
   3
   4 In this chapter we assume the reader is familiar with Molecular Dynamics and
   5 familiar with Unix, including the use of a text editor such as ``jot``, ``emacs``
   6 or ``vi``. We furthermore assume the |Gromacs| software is installed properly on
   7 your system. When you see a line like
   8
   9 ::
  10
  11     ls -l
  12
  13 you are supposed to type the contents of that line on your computer terminal.
  14
  15 Setting up your environment
  16 ---------------------------
  17 In order to check whether you have access to |Gromacs|, please
  18 start by entering the command:
  19
  20 ::
  21
  22     gmx -version
  23
  24 This command should print out information about the version of |Gromacs|
  25 installed. If this, in contrast, returns the phrase
  26
  27 ::
  28
  29     gmx: command not found.
  30
  31 then you have to find where your version of |Gromacs| is installed. In
  32 the default case, the binaries are located in
  33 ``/usr/local/gromacs/bin``, however, you can ask your local system
  34 administrator for more information, and then follow the advice for
  35 :ref:`getting access to Gromacs`.
  36
  37 Flowchart of typical simulation
  38 -------------------------------
  39 A typical simulation workflow with |Gromacs| is `illustrated here <../online/flow.html>`_.
  40
  41 Important files
  42 ---------------
  43 Here is an overview of the most important |Gromacs| file types that you will
  44 encounter.
  45
  46 Molecular Topology file (``.top``)
  47 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  48
  49 The molecular topology file is generated by the program :ref:`gmx pdb2gmx`.
  50 :ref:`gmx pdb2gmx` translates a :ref:`PDB` structure file of any
  51 peptide or protein to a molecular topology file. This topology file
  52 contains a complete description of all the interactions in your
  53 peptide or protein.
  54
  55 Molecular Structure file (``.gro``, ``.pdb``)
  56 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  57
  58 When :ref:`gmx pdb2gmx` is executed to generate a molecular topology, it
  59 also translates the structure file (:ref:`pdb` file) to a GROMOS structure
  60 file (:ref:`gro` file). The main difference between a :ref:`pdb` file and a gromos
  61 file is their format and that a :ref:`gro` file can also hold
  62 velocities. However, if you do not need the velocities, you can also
  63 use a :ref:`PDB` file in all programs. To generate a box of solvent
  64 molecules around the peptide, the program :ref:`gmx solvate` is
  65 used. First the program :ref:`gmx editconf` should be used to define a box
  66 of appropriate size around the molecule. :ref:`gmx solvate` solvates a
  67 solute molecule (the peptide) into any solvent (in this case,
  68 water). The output of :ref:`gmx solvate` is a gromos structure file of the
  69 peptide solvated in water. :ref:`gmx solvate` also changes the molecular
  70 topology file (generated by :ref:`gmx pdb2gmx`) to add solvent to the
  71 topology.
  72
  73 Molecular Dynamics parameter file (``.mdp``)
  74 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  75
  76 The Molecular Dynamics Parameter (:ref:`mdp`) file contains all information
  77 about the Molecular Dynamics simulation itself e.g. time-step, number
  78 of steps, temperature, pressure etc. The easiest way of handling such
  79 a file is by adapting a sample :ref:`mdp` file. A :ref:`sample mdp file <mdp>`
  80 is available.
  81
  82 Index file (``.ndx``)
  83 ^^^^^^^^^^^^^^^^^^^^^
  84
  85 Sometimes you may need an index file to specify actions on groups of
  86 atoms (e.g. temperature coupling, accelerations, freezing). Usually
  87 the default index groups will be sufficient, so for this demo we will
  88 not consider the use of index files.
  89
  90 Run input file (``.tpr``)
  91 ^^^^^^^^^^^^^^^^^^^^^^^^^
  92
  93 The next step is to combine the molecular structure (:ref:`gro` file),
  94 topology (:ref:`top` file) MD-parameters (:ref:`mdp` file) and (optionally) the
  95 index file (:ref:`ndx`) to generate a run input file (:ref:`tpr` extension). This
  96 file contains all information needed to start a simulation with
  97 |Gromacs|. The :ref:`gmx grompp` program processes all input files and
  98 generates the run input :ref:`tpr` file.
  99
 100 Trajectory file (``.trr``, ``.tng``, or ``.xtc``)
 101 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 102
 103 Once the run input file is available, we can start the simulation. The
 104 program which starts the simulation is called :ref:`gmx mdrun` (or
 105 sometimes just mdrun, or mdrun_mpi). The only input file of :ref:`gmx mdrun`
 106 that you usually need in order to start a run is the run input
 107 file (:ref:`tpr` file). The typical output files of :ref:`gmx mdrun` are the
 108 trajectory file (:ref:`trr` file), a logfile (:ref:`log` file), and perhaps a
 109 checkpoint file (:ref:`cpt` file).
 110
 111 Tutorial material
 112 -----------------
 113 There are many tutorials_ available that cover aspects of using |Gromacs|.
 114
 115 Background reading
 116 ------------------
 117 *   Berendsen, H.J.C., Postma, J.P.M., van Gunsteren, W.F., Hermans, J. (1981)
 118     Intermolecular Forces, chapter Interaction models for water in relation to
 119     protein hydration, pp 331-342. Dordrecht: D. Reidel Publishing Company
 120     Dordrecht
 121 *   Kabsch, W., Sander, C. (1983).     Dictionary of protein secondary
 122     structure: Pattern recognition of hydrogen-bonded and geometrical features.
 123     Biopolymers **22**, 2577--2637.
 124 *   Mierke, D.F., Kessler, H. (1991).     Molecular dynamics with dimethyl
 125     sulfoxide as a solvent. Conformation of a cyclic hexapeptide. J. Am. Chem.
 126     Soc. **113**, 9446.
 127 *   Stryer, L. (1988).     Biochemistry vol. 1, p. 211. New York: Freeman, 3
 128     edition.