# Getting started¶

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.

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 Getting access to GROMACS after installation.

## Flowchart of typical simulation¶

A typical simulation workflow with GROMACS is illustrated here.

## 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 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.

### Topology #include file mechanism¶

When constructing a system topology in a 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 run parameter in the 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 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 mdp file to choose whether or not you want position restraints on your solvent, rather than your top file. Note that preprocessor variables are not the same as shell environment variables.

### Molecular Structure file (.gro, .pdb)¶

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.

### Molecular Dynamics parameter file (.mdp)¶

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 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 (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.

### 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 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), and perhaps a checkpoint file (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 How to section.