docs/user-guide/getting-started.md

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