.. _gmx-getting-started:
Getting started
===============
.. toctree::
:hidden:
flow
In this chapter we assume the reader is familiar with Molecular Dynamics and
familiar with Unix, including the use of a text editor such as ``jot``, ``emacs``
or ``vi``. We furthermore assume the |Gromacs| software is installed properly on
your system. When you see a line like
::
ls -l
you are supposed to type the contents of that line on your computer terminal.
Setting up your environment
---------------------------
In order to check whether you have access to |Gromacs|, please
start by entering the command:
::
gmx -version
This command should print out information about the version of |Gromacs|
installed. If this, in contrast, returns the phrase
::
gmx: command not found.
then you have to find where your version of |Gromacs| is installed. In
the default case, the binaries are located in
``/usr/local/gromacs/bin``, however, you can ask your local system
administrator for more information, and then follow the advice for
:ref:`getting access to |Gromacs|`.
Flowchart of typical simulation
-------------------------------
A typical simulation workflow with |Gromacs| is :doc:`illustrated here <flow>`.
Important files
---------------
Here is an overview of the most important |Gromacs| file types that you will
encounter.
Molecular Topology file (``.top``)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The molecular topology file is generated by the program :ref:`gmx pdb2gmx`.
:ref:`gmx pdb2gmx` translates a :ref:`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.
.. _gmx-topo-include:
Topology #include file mechanism
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
When constructing a system topology in a :ref:`top` file for presentation to grompp,
GROMACS uses a built-in version of the so-called C preprocessor, cpp (in GROMACS 3, it really was cpp). cpp interprets lines like::
#include "ions.itp"
by looking for the indicated file in the current directory, the GROMACS share/top directory as indicated
by the GMXLIB environment variable, and any directory indicated by a ``-I`` flag in the value of the
include :mdp:`run parameter <include>` in the :ref:`mdp` file. It either finds this file or reports
a warning. (Note that when you supply a directory name, you should use Unix-style forward
slashes '/', not Windows-style backslashes '\' for separators.) When found, it then uses the contents
exactly as if you had cut and pasted the included file into the main file yourself. Note that you shouldn't
go and do this copy-and-paste yourself, since the main purposes of the include file mechanism are to re-use
previous work, make future changes easier, and prevent typos.
Further, ``cpp`` interprets code such as::
#ifdef POSRES_WATER
; Position restraint for each water oxygen
[ position_restraints ]
; i funct fcx fcy fcz
1 1 1000 1000 1000
#endif
by testing whether the preprocessor variable ``POSRES_WATER`` was defined somewhere (i.e. "if defined").
This could be done with ``#define POSRES_WATER`` earlier in the :ref:`top` file (or its ``#include`` files),
with a ``-D`` flag in the ``include`` run parameter as above, or on the command line to ``cpp``.
The function of the ``-D`` flag is borrowed from the similar usage in ``cpp``. The string that
follows ``-D`` must match exactly; using ``-DPOSRES`` will not trigger ``#ifdef POSRE`` or ``#ifdef DPOSRES``.
This mechanism allows you to change your :ref:`mdp` file to choose whether or not you want position
restraints on your solvent, rather than your :ref:`top` file. Note that preprocessor variables
are not the same as shell environment variables.
.. _gmx-need-for-gro:
Molecular Structure file (``.gro``, ``.pdb``)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
When :ref:`gmx pdb2gmx` is executed to generate a molecular topology, it
also translates the structure file (:ref:`pdb` file) to a GROMOS structure
file (:ref:`gro` file). The main difference between a :ref:`pdb` file and a gromos
file is their format and that a :ref:`gro` file can also hold
velocities. However, if you do not need the velocities, you can also
use a :ref:`PDB` file in all programs. To generate a box of solvent
molecules around the peptide, the program :ref:`gmx solvate` is
used. First the program :ref:`gmx editconf` should be used to define a box
of appropriate size around the molecule. :ref:`gmx solvate` solvates a
solute molecule (the peptide) into any solvent (in this case,
water). The output of :ref:`gmx solvate` is a gromos structure file of the
peptide solvated in water. :ref:`gmx solvate` also changes the molecular
topology file (generated by :ref:`gmx pdb2gmx`) to add solvent to the
topology.
Molecular Dynamics parameter file (``.mdp``)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The Molecular Dynamics Parameter (:ref:`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 :ref:`mdp` file. A :ref:`sample mdp file <mdp>`
is available.
Index file (``.ndx``)
^^^^^^^^^^^^^^^^^^^^^
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.
Run input file (``.tpr``)
^^^^^^^^^^^^^^^^^^^^^^^^^
The next step is to combine the molecular structure (:ref:`gro` file),
topology (:ref:`top` file) MD-parameters (:ref:`mdp` file) and (optionally) the
index file (:ref:`ndx`) to generate a run input file (:ref:`tpr` extension). This
file contains all information needed to start a simulation with
|Gromacs|. The :ref:`gmx grompp` program processes all input files and
generates the run input :ref:`tpr` file.
Trajectory file (``.trr``, ``.tng``, or ``.xtc``)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Once the run input file is available, we can start the simulation. The
program which starts the simulation is called :ref:`gmx mdrun`.
The only input file of :ref:`gmx mdrun`
that you usually need in order to start a run is the run input
file (:ref:`tpr` file). The typical output files of :ref:`gmx mdrun` are the
trajectory file (:ref:`trr` file), a logfile (:ref:`log` file), and perhaps a
checkpoint file (:ref:`cpt` file).
Tutorial material
-----------------
There are several third-party `tutorials`_ available that cover aspects of using |Gromacs|.
Further information can also be found in the :doc:`How to <../how-to/index>` section.
Background reading
------------------
* Berendsen, H.J.C., Postma, J.P.M., van Gunsteren, W.F., Hermans, J. (1981)
Intermolecular Forces, chapter Interaction models for water in relation to
protein hydration, pp 331-342. Dordrecht: D. Reidel Publishing Company
Dordrecht
* Kabsch, W., Sander, C. (1983). Dictionary of protein secondary
structure: Pattern recognition of hydrogen-bonded and geometrical features.
Biopolymers **22**, 2577--2637.
* Mierke, D.F., Kessler, H. (1991). Molecular dynamics with dimethyl
sulfoxide as a solvent. Conformation of a cyclic hexapeptide. J. Am. Chem.
Soc. **113**, 9446.
* Stryer, L. (1988). Biochemistry vol. 1, p. 211. New York: Freeman, 3
edition.