.. _gmx grompp:

gmx grompp
==========

Synopsis
--------

.. parsed-literal::

    gmx grompp [:strong:`-f` :emphasis:`[<.mdp>]`] [:strong:`-c` :emphasis:`[<.gro/.g96/...>]`] [:strong:`-r` :emphasis:`[<.gro/.g96/...>]`]
               [:strong:`-rb` :emphasis:`[<.gro/.g96/...>]`] [:strong:`-n` :emphasis:`[<.ndx>]`] [:strong:`-p` :emphasis:`[<.top>]`]
               [:strong:`-t` :emphasis:`[<.trr/.cpt/...>]`] [:strong:`-e` :emphasis:`[<.edr>]`] [:strong:`-qmi` :emphasis:`[<.inp>]`]
               [:strong:`-ref` :emphasis:`[<.trr/.cpt/...>]`] [:strong:`-po` :emphasis:`[<.mdp>]`] [:strong:`-pp` :emphasis:`[<.top>]`]
               [:strong:`-o` :emphasis:`[<.tpr>]`] [:strong:`-imd` :emphasis:`[<.gro>]`] [:strong:`-[no]v`] [:strong:`-time` :emphasis:`<real>`]
               [:strong:`-[no]rmvsbds`] [:strong:`-maxwarn` :emphasis:`<int>`] [:strong:`-[no]zero`] [:strong:`-[no]renum`]

Description
-----------

``gmx grompp`` (the gromacs preprocessor)
reads a molecular topology file, checks the validity of the
file, expands the topology from a molecular description to an atomic
description. The topology file contains information about
molecule types and the number of molecules, the preprocessor
copies each molecule as needed.
There is no limitation on the number of molecule types.
Bonds and bond-angles can be converted into constraints, separately
for hydrogens and heavy atoms.
Then a coordinate file is read and velocities can be generated
from a Maxwellian distribution if requested.
``gmx grompp`` also reads parameters for :doc:`gmx mdrun <gmx-mdrun>`
(eg. number of MD steps, time step, cut-off).
Eventually a binary file is produced that can serve as the sole input
file for the MD program.

``gmx grompp`` uses the atom names from the topology file. The atom names
in the coordinate file (option ``-c``) are only read to generate
warnings when they do not match the atom names in the topology.
Note that the atom names are irrelevant for the simulation as
only the atom types are used for generating interaction parameters.

``gmx grompp`` uses a built-in preprocessor to resolve includes, macros,
etc. The preprocessor supports the following keywords::

    #ifdef VARIABLE
    #ifndef VARIABLE
    #else
    #endif
    #define VARIABLE
    #undef VARIABLE
    #include "filename"
    #include <filename>

The functioning of these statements in your topology may be modulated by
using the following two flags in your :ref:`.mdp <mdp>` file::

    define = -DVARIABLE1 -DVARIABLE2
    include = -I/home/john/doe

For further information a C-programming textbook may help you out.
Specifying the ``-pp`` flag will get the pre-processed
topology file written out so that you can verify its contents.

When using position restraints, a file with restraint coordinates
must be supplied with ``-r`` (can be the same file as supplied
for ``-c``). For free energy calculations, separate reference
coordinates for the B topology can be supplied with ``-rb``,
otherwise they will be equal to those of the A topology.

Starting coordinates can be read from trajectory with ``-t``.
The last frame with coordinates and velocities will be read,
unless the ``-time`` option is used. Only if this information
is absent will the coordinates in the ``-c`` file be used.
Note that these velocities will not be used when ``gen_vel = yes``
in your :ref:`.mdp <mdp>` file. An energy file can be supplied with
``-e`` to read Nose-Hoover and/or Parrinello-Rahman coupling
variables.

``gmx grompp`` can be used to restart simulations (preserving
continuity) by supplying just a checkpoint file with ``-t``.
However, for simply changing the number of run steps to extend
a run, using :doc:`gmx convert-tpr <gmx-convert-tpr>` is more convenient than ``gmx grompp``.
You then supply the old checkpoint file directly to :doc:`gmx mdrun <gmx-mdrun>`
with ``-cpi``. If you wish to change the ensemble or things
like output frequency, then supplying the checkpoint file to
``gmx grompp`` with ``-t`` along with a new :ref:`.mdp <mdp>` file
with ``-f`` is the recommended procedure. Actually preserving
the ensemble (if possible) still requires passing the checkpoint
file to :doc:`gmx mdrun <gmx-mdrun>` ``-cpi``.

By default, all bonded interactions which have constant energy due to
virtual site constructions will be removed. If this constant energy is
not zero, this will result in a shift in the total energy. All bonded
interactions can be kept by turning off ``-rmvsbds``. Additionally,
all constraints for distances which will be constant anyway because
of virtual site constructions will be removed. If any constraints remain
which involve virtual sites, a fatal error will result.

To verify your run input file, please take note of all warnings
on the screen, and correct where necessary. Do also look at the contents
of the ``mdout.mdp`` file; this contains comment lines, as well as
the input that ``gmx grompp`` has read. If in doubt, you can start ``gmx grompp``
with the ``-debug`` option which will give you more information
in a file called ``grompp.log`` (along with real debug info). You
can see the contents of the run input file with the :doc:`gmx dump <gmx-dump>`
program. :doc:`gmx check <gmx-check>` can be used to compare the contents of two
run input files.

The ``-maxwarn`` option can be used to override warnings printed
by ``gmx grompp`` that otherwise halt output. In some cases, warnings are
harmless, but usually they are not. The user is advised to carefully
interpret the output messages before attempting to bypass them with
this option.

Options
-------

Options to specify input files:

``-f`` [<.mdp>] (grompp.mdp)
    grompp input file with MD parameters
``-c`` [<.gro/.g96/...>] (conf.gro)
    Structure file: :ref:`gro` :ref:`g96` :ref:`pdb` brk ent esp :ref:`tpr`
``-r`` [<.gro/.g96/...>] (restraint.gro) (Optional)
    Structure file: :ref:`gro` :ref:`g96` :ref:`pdb` brk ent esp :ref:`tpr`
``-rb`` [<.gro/.g96/...>] (restraint.gro) (Optional)
    Structure file: :ref:`gro` :ref:`g96` :ref:`pdb` brk ent esp :ref:`tpr`
``-n`` [<.ndx>] (index.ndx) (Optional)
    Index file
``-p`` [<.top>] (topol.top)
    Topology file
``-t`` [<.trr/.cpt/...>] (traj.trr) (Optional)
    Full precision trajectory: :ref:`trr` :ref:`cpt` :ref:`tng`
``-e`` [<.edr>] (ener.edr) (Optional)
    Energy file
``-qmi`` [<.inp>] (topol-qmmm.inp) (Optional)
    Input file for QM program

Options to specify input/output files:

``-ref`` [<.trr/.cpt/...>] (rotref.trr) (Optional)
    Full precision trajectory: :ref:`trr` :ref:`cpt` :ref:`tng`

Options to specify output files:

``-po`` [<.mdp>] (mdout.mdp)
    grompp input file with MD parameters
``-pp`` [<.top>] (processed.top) (Optional)
    Topology file
``-o`` [<.tpr>] (topol.tpr)
    Portable xdr run input file
``-imd`` [<.gro>] (imdgroup.gro) (Optional)
    Coordinate file in Gromos-87 format

Other options:

``-[no]v``  (no)
    Be loud and noisy
``-time`` <real> (-1)
    Take frame at or first after this time.
``-[no]rmvsbds``  (yes)
    Remove constant bonded interactions with virtual sites
``-maxwarn`` <int> (0)
    Number of allowed warnings during input processing. Not for normal use and may generate unstable systems
``-[no]zero``  (no)
    Set parameters for bonded interactions without defaults to zero instead of generating an error
``-[no]renum``  (yes)
    Renumber atomtypes and minimize number of atomtypes

.. only:: man

   See also
   --------

   :manpage:`gmx(1)`

   More information about |Gromacs| is available at <http://www.gromacs.org/>.