[alexxy/gromacs.git] / docs / reference-manual / topologies / topology-file-formats.rst

File formats
------------

.. _topfile:

Topology file
~~~~~~~~~~~~~

The topology file is built following the |Gromacs| specification for a
molecular topology. A :ref:`top` file can be generated by
:ref:`pdb2gmx <gmx pdb2gmx>`. All possible entries in the topology file are
listed in :numref:`Tables %s <tab-topfile1>` and
:numref:`%s <tab-topfile2>`. Also tabulated are: all the units of
the parameters, which interactions can be perturbed for free energy
calculations, which bonded interactions are used by
:ref:`grompp <gmx grompp>` for generating exclusions, and which bonded
interactions can be converted to constraints by :ref:`grompp <gmx grompp>`.

.. |VCR| replace:: V\ :math:`^{(cr)}`
.. |WCR| replace:: W\ :math:`^{(cr)}`
.. |CRO| replace:: :math:`^{(cr)}`
.. |TREF| replace:: :numref:`Table %s <tab-topfile2>`
.. |AKJM| replace:: :math:`a~\mathrm{kJ~mol}^{-1}`
.. |KJN6| replace:: :math:`\mathrm{kJ~mol}^{-1}~\mathrm{nm}^{-6}`
.. |BNM| replace:: :math:`b~\mathrm{nm}^{-1}`
.. |C6LJ| replace:: :math:`c_6`
.. |STAR| replace:: :math:`^{(*)}`
.. |NREX| replace:: :math:`n_{ex}^{(nrexcl)}`
.. |QEMU| replace:: :math:`q` (e); :math:`m` (u)
.. |MQM| replace:: :math:`q,m`

.. _tab-topfile1:

.. table:: The :ref:`topology <top>` file.

        +------------------------------------------------------------------------------------------------------------+
        | Parameters                                                                                                 |
        +===================+===========================+=====+====+=================================================+
        | interaction type  | directive                 | #   | f. | parameters                                      |
        |                   |                           | at. | tp |                                                 |
        +-------------------+---------------------------+-----+----+-------------------------------------------------+
        | *mandatory*       | ``defaults``              |          | non-bonded function type;                       |
        |                   |                           |          | combination rule\ |CRO|;                        |
        |                   |                           |          | generate pairs (no/yes);                        |
        |                   |                           |          | fudge LJ (); fudge QQ ()                        |
        +-------------------+---------------------------+----------+-------------------------------------------------+
        | *mandatory*       | ``atomtypes``             |          | atom type; m (u); q (e); particle type;         |
        |                   |                           |          | |VCR| ; |WCR|                                   |
        +-------------------+---------------------------+----------+-------------------------------------------------+
        |                   | ``bondtypes``             |          | (see |TREF|, directive ``bonds``)               |
        +-------------------+---------------------------+------------------------------------------------------------+
        |                   | ``pairtypes``             |          | (see |TREF|, directive ``pairs``)               |
        +-------------------+---------------------------+------------------------------------------------------------+
        |                   | ``angletypes``            |          | (see |TREF|, directive ``angles``)              |
        +-------------------+---------------------------+------------------------------------------------------------+
        |                   | ``dihedraltypes``\ |STAR| |          | (see |TREF|, directive ``dihedrals``)           |
        +-------------------+---------------------------+------------------------------------------------------------+
        |                   | ``constrainttypes``       |          | (see |TREF|, directive ``constraints``)         |
        +-------------------+---------------------------+-----+----+-------------------------------------------------+
        | LJ                | ``nonbond_params``        |  2  | 1  |  |VCR|  ; |WCR|                                 |
        +-------------------+---------------------------+-----+----+-------------------------------------------------+
        | Buckingham        | ``nonbond_params``        |  2  | 2  |  |AKJM| ; |BNM|;                                |
        |                   |                           |     |    |  |C6LJ| (|KJN6|)                                |
        +-------------------+---------------------------+-----+----+-------------------------------------------------+

.. table::

        +----------------------------------------------------------------------------------------------------+-------+
        | Molecule definition(s)                                                                             | F. E. |
        +===================+===========================+=====+==============================================+=======+
        | *mandatory*       | ``moleculetype``          |     | molecule name; |NREX|                        |       |
        +-------------------+---------------------------+-----+----------------------------------------------+-------+
        | *mandatory*       | ``atoms``                 | 1   | atom type; residue number;                   | type  |
        |                   |                           |     | residue name; atom name;                     |       |
        |                   |                           |     | charge group number; |QEMU|                  | |MQM| |
        +-------------------+---------------------------+-----+----------------------------------------------+-------+
        | intra-molecular interaction and geometry definitions as described in |TREF|                                |
        +------------------------------------------------------------------------------------------------------------+

.. table::

        +-------------+---------------+------------------------------------+
        | System      |               |                                    |
        +=============+===============+====================================+
        | *mandatory* | ``system``    | system name                        |
        +-------------+---------------+------------------------------------+
        | *mandatory* | ``molecules`` | molecule name; number of molecules |
        +-------------+---------------+------------------------------------+

.. table::

        +------------------------------+----------------------------------------------------+
        | Inter-molecular interactions |                                                    |
        +==============================+====================================================+
        | *optional*                   | ``intermolecular_interactions``                    |
        +------------------------------+----------------------------------------------------+
        | one or more bonded interactions as described in |TREF|, with two or more atoms,   |
        | no interactions that generate exclusions, no constraints, use global atom numbers |
        +-----------------------------------------------------------------------------------+

-   ``# at`` is the required number of atom type indices for this directive

-   ``f. tp`` is the value used to select this function type

-   ``F. E.`` indicates which of the parameters can be interpolated in free energy calculations

-   |CRO| the combination rule determines the type of LJ parameters, see :ref:`nbpar`

-   |STAR| for ``dihedraltypes`` one can specify 4 atoms or the inner (outer for improper) 2 atoms

-   |NREX| exclude neighbors :math:`n_{ex}` bonds away for non-bonded interactions

-   For free energy calculations, type, :math:`q` and :math:`m`  or no parameters should be added for topology ``B`` (:math:`\lambda = 1`) on the same line, after the normal parameters.

.. |BZERO| replace:: :math:`b_0`
.. |KB| replace:: :math:`k_b`
.. |KDR| replace:: :math:`k_{dr}`
.. |NM2| replace:: (kJ mol\ :math:`^{-1}`\ nm\ :math:`^{-2}`
.. |NM4| replace:: (kJ mol\ :math:`^{-1}`\ nm\ :math:`^{-4}`
.. |DKJ| replace:: :math:`D` (kJ mol\ :math:`^{-1}`
.. |BETA| replace:: :math:`\beta` (nm\ :math:`^{-1}`
.. |C23| replace:: :math:`C_{i=2,3}` (kJ mol\ :math:`^{-1}`\ nm\ :math:`^{-i}`
.. |BMM| replace:: :math:`b_m`
.. |GE0| replace:: :math:`\geq 0`
.. |KO| replace:: :math:`k`
.. |KJM| replace:: kJ mol\ :math:`^{-1}`
.. |LUU| replace:: low, up\ :math:`_1`,\ :math:`_2`
.. |MV| replace:: :math:`V`
.. |MW| replace:: :math:`W`
.. |QIJ| replace:: :math:`q_i`; :math:`q_j`
.. |THE0| replace:: :math:`\theta_0`
.. |KTHE| replace:: :math:`k_\theta`
.. |KJR2| replace:: kJ mol\ :math:`^{-1}`\ rad\ :math:`^{-2}`
.. |RN13| replace:: :math:`r_{13}`
.. |KUB| replace:: :math:`k_{UB}`
.. |C024| replace:: :math:`C_{i=0,1,2,3,4}`
.. |KJRI| replace:: kJ mol\ :math:`^{-1}`\ rad\ :math:`^{-i}`
.. |PHIS| replace:: :math:`\phi_s`
.. |PHI0| replace:: :math:`\phi_0`
.. |KPHI| replace:: :math:`k_\phi`
.. |PHIK| replace:: :math:`\phi,k`
.. |XI0| replace:: :math:`\xi_0`
.. |KXI| replace:: :math:`k_\xi`
.. |C0| replace:: :math:`C_0`
.. |C1| replace:: :math:`C_1`
.. |C2| replace:: :math:`C_2`
.. |C3| replace:: :math:`C_3`
.. |C4| replace:: :math:`C_4`
.. |C5| replace:: :math:`C_5`
.. |A0| replace:: :math:`a_0`
.. |A1| replace:: :math:`a_1`
.. |A2| replace:: :math:`a_2`
.. |A3| replace:: :math:`a_3`
.. |A4| replace:: :math:`a_4`
.. |DOH| replace:: :math:`d_{\mbox{\sc oh}}`
.. |DHH| replace:: :math:`d_{\mbox{\sc hh}}`
.. |AO| replace:: :math:`a`
.. |BO| replace:: :math:`b`
.. |CO| replace:: :math:`c`
.. |DO| replace:: :math:`d`
.. |KX| replace:: :math:`k_{x}`
.. |KY| replace:: :math:`k_{y}`
.. |KZ| replace:: :math:`k_{z}`
.. |GO| replace:: :math:`g`
.. |RO| replace:: :math:`r`
.. |DPHI| replace:: :math:`\Delta\phi`
.. |DIHR| replace:: :math:`k_{\mathrm{dihr}}`
.. |THET| replace:: :math:`\theta`
.. |NM| replace:: nm\ :math:`^{-1}`
.. |KC| replace:: :math:`k_c`
.. |THEK| replace:: :math:`\theta,k`
.. |R1E| replace:: :math:`r_{1e}`
.. |R2E| replace:: :math:`r_{2e}`
.. |R3E| replace:: :math:`r_{3e}`
.. |KRR| replace:: :math:`k_{rr'}`
.. |KRTH| replace:: :math:`k_{r\theta}`
.. |ALPH| replace:: :math:`\alpha`; |CO| (U nm\ :math:`^{\alpha}`
.. |UM1| replace:: U\ :math:`^{-1}`

.. _tab-topfile2:

.. table:: Details of ``[ moleculetype ]`` directives

            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | Name of interaction                | Topology file directive    | num.       | func.     | Order of parameters and their units                                     | use in     |
            |                                    |                            | atoms [1]_ | type [2]_ |                                                                         | F.E.? [3]_ |
            +====================================+============================+============+===========+=========================================================================+============+
            | bond                               | ``bonds`` [4]_, [5]_       | 2          | 1         | |BZERO| (nm); |KB| |NM2|                                                | all        |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | G96 bond                           | ``bonds`` [4]_, [5]_       | 2          | 2         | |BZERO| (nm); |KB| |NM4|                                                | all        |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | Morse                              | ``bonds`` [4]_, [5]_       | 2          | 3         | |BZERO| (nm); |DKJ|; |BETA|                                             | all        |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | cubic bond                         | ``bonds`` [4]_, [5]_       | 2          | 4         | |BZERO| (nm); |C23|                                                     |            |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | connection                         | ``bonds`` [4]_             | 2          | 5         |                                                                         |            |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | harmonic potential                 | ``bonds``                  | 2          | 6         | |BZERO| (nm); |KB| |NM2|                                                | all        |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | FENE bond                          | ``bonds`` [4]_             | 2          | 7         | |BMM|   (nm); |KB| |NM2|                                                |            |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | tabulated bond                     | ``bonds`` [4]_             | 2          | 8         | table number (|GE0|); |KO| |KJM|                                        | |KO|       |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | tabulated bond [6]_                | ``bonds``                  | 2          | 9         | table number (|GE0|); |KO| |KJM|                                        | |KO|       |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | restraint potential                | ``bonds``                  | 2          | 10        | |LUU| (nm); |KDR| (|NM2|)                                               | all        |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | extra LJ or Coulomb                | ``pairs``                  | 2          | 1         | |MV| [7]_; |MW| [7]_                                                    | all        |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | extra LJ or Coulomb                | ``pairs``                  | 2          | 2         | fudge QQ (); |QIJ| (e), |MV| [7]_; |MW| [7]_                            |            |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | extra LJ or Coulomb                | ``pairs_nb``               | 2          | 1         | |QIJ| (e); |MV| [7]_; |MW| [7]_                                         |            |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | angle                              | ``angles`` [5]_            | 3          | 1         | |THE0| (deg); |KTHE| (|KJR2|)                                           | all        |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | G96 angle                          | ``angles`` [5]_            | 3          | 2         | |THE0| (deg); |KTHE| (|KJM|)                                            | all        |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | cross bond-bond                    | ``angles``                 | 3          | 3         | |R1E|, |R2E| (nm); |KRR| (|NM2|)                                        |            |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | cross bond-angle                   | ``angles``                 | 3          | 4         | |R1E|, |R2E|, |R3E| (nm); |KRTH| (|NM2|)                                |            |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | Urey-Bradley                       | ``angles`` [5]_            | 3          | 5         | |THE0| (deg); |KTHE| (|KJR2|); |RN13| (nm); |KUB| (|NM2|)               | all        |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | quartic angle                      | ``angles`` [5]_            | 3          | 6         | |THE0| (deg); |C024| (|KJRI|)                                           |            |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | tabulated angle                    | ``angles``                 | 3          | 8         | table number (|GE0|); |KO| (|KJM|)                                      | |KO|       |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            |  |  restricted                     |                            |            |           |                                                                         |            |
            |  |  bending potential              | ``angles``                 | 3          | 10        | |THE0| (deg); |KTHE| (|KJM|)                                            |            |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | proper dihedral                    | ``dihedrals``              | 4          | 1         | |PHIS| (deg); |KPHI| (|KJM|); multiplicity                              | |PHIK|     |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | improper dihedral                  | ``dihedrals``              | 4          | 2         | |XI0| (deg); |KXI| (|KJR2|)                                             | all        |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | Ryckaert-Bellemans dihedral        | ``dihedrals``              | 4          | 3         | |C0|, |C1|, |C2|, |C3|, |C4|, |C5| (|KJM|)                              | all        |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | periodic improper dihedral         | ``dihedrals``              | 4          | 4         | |PHIS| (deg); |KPHI| (|KJM|); multiplicity                              | |PHIK|     |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | Fourier dihedral                   | ``dihedrals``              | 4          | 5         | |C1|, |C2|, |C3|, |C4|, |C5| (|KJM|)                                    | all        |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | tabulated dihedral                 | ``dihedrals``              | 4          | 8         | table number (|GE0|); |KO| (|KJM|)                                      | |KO|       |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | proper dihedral (multiple)         | ``dihedrals``              | 4          | 9         | |PHIS| (deg); |KPHI| (|KJM|); multiplicity                              | |PHIK|     |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | restricted dihedral                | ``dihedrals``              | 4          | 10        | |PHI0| (deg); |KPHI| (|KJM|)                                            |            |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | combined bending-torsion potential | ``dihedrals``              | 4          | 11        | |k_phi|, |A0|, |A1|, |A2|, |A3|, |A4|, (|KJM|)                          |            |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | exclusions                         | ``exclusions``             | 1          |           | one or more atom indices                                                |            |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | constraint                         | ``constraints`` [4]_       | 2          | 1         | |BZERO| (nm)                                                            | all        |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | constraint [6]_                    | ``constraints``            | 2          | 2         | |BZERO| (nm)                                                            | all        |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | SETTLE                             | ``settles``                | 1          | 1         | |DOH|, |DHH| (nm)                                                       |            |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | 1-body virtual site                | ``virtual_sites1``         | 2          | 0         |                                                                         |            |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | 2-body virtual site                | ``virtual_sites2``         | 3          | 1         | |AO| ()                                                                 |            |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | 2-body virtual site (fd)           | ``virtual_sites2``         | 3          | 2         | |DO| (nm)                                                               |            |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | 3-body virtual site                | ``virtual_sites3``         | 4          | 1         | |AO|, |BO| ()                                                           |            |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | 3-body virtual site (fd)           | ``virtual_sites3``         | 4          | 2         | |AO| (); |DO| (nm)                                                      |            |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | 3-body virtual site (fad)          | ``virtual_sites3``         | 4          | 3         | |THET| (deg); |DO| (nm)                                                 |            |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | 3-body virtual site (out)          | ``virtual_sites3``         | 4          | 4         | |AO|, |BO| (); |CO| (|NM|)                                              |            |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | 4-body virtual site (fdn)          | ``virtual_sites4``         | 5          | 2         | |AO|, |BO| (); |CO| (nm)                                                |            |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | N-body virtual site (COG)          | ``virtual_sitesn``         | 1          | 1         | one or more constructing atom indices                                   |            |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | N-body virtual site (COM)          | ``virtual_sitesn``         | 1          | 2         | one or more constructing atom indices                                   |            |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | N-body virtual site (COW)          | ``virtual_sitesn``         | 1          | 3         |  |  one or more pairs consisting of                                     |            |
            |                                    |                            |            |           |  |  constructing atom index and weight                                  |            |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | position restraint                 | ``position_restraints``    | 1          | 1         | |KX|, |KY|, |KZ| (|NM2|)                                                | all        |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | flat-bottomed position restraint   | ``position_restraints``    | 1          | 2         | |GO|, |RO| (nm), |KO| (|NM2|)                                           |            |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | distance restraint                 | ``distance_restraints``    | 2          | 1         | type; label; |LUU| (nm); weight ()                                      |            |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | dihedral restraint                 | ``dihedral_restraints``    | 4          | 1         | |PHI0| (deg); |DPHI| (deg); |DIHR| (|KJR2|)                             | all        |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | orientation restraint              | ``orientation_restraints`` | 2          | 1         | exp.; label; |ALPH|; obs. (U); weight (|UM1|)                           |            |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | angle restraint                    | ``angle_restraints``       | 4          | 1         | |THE0| (deg); |KC| (|KJM|); multiplicity                                | |THEK|     |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
            | angle restraint (z)                | ``angle_restraints_z``     | 2          | 1         | |THE0| (deg); |KC| (|KJM|); multiplicity                                | |THEK|     |
            +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+

.. [1]
   The required number of atom indices for this directive

.. [2]
   The index to use to select this function type

.. [3]
   Indicates which of the parameters can be interpolated in free energy calculations

.. [4]
   This interaction type will be used by :ref:`grompp <gmx grompp>` for generating exclusions

.. [5]
   This interaction type can be converted to constraints by :ref:`grompp <gmx grompp>`

.. [7]
   The combination rule determines the type of LJ parameters, see :ref:`nbpar`

.. [6]
   No connection, and so no exclusions, are generated for this interaction

Description of the file layout:

-  Semicolon (;) and newline characters surround comments

-  On a line ending with :math:`\backslash` the newline character is
   ignored.

-  Directives are surrounded by ``[`` and ``]``

-  The topology hierarchy (which must be followed) consists of three
   levels:

   -  the parameter level, which defines certain force-field
      specifications (see :numref:`Table %s <tab-topfile1>`)

   -  the molecule level, which should contain one or more molecule
      definitions (see :numref:`Table %s <tab-topfile2>`)

   -  the system level, containing only system-specific information
      (``[ system ]`` and ``[ molecules ]``)

-  Items should be separated by spaces or tabs, not commas

-  Atoms in molecules should be numbered consecutively starting at 1

-  Atoms in the same charge group must be listed consecutively

-  Bonded atom type name must contain at least one non-digit character.

-  The file is parsed only once, which implies that no forward
   references can be treated: items must be defined before they can be
   used

-  Exclusions can be generated from the bonds or overridden manually

-  The bonded force types can be generated from the atom types or
   overridden per bond

-  It is possible to apply multiple bonded interactions of the same type
   on the same atoms

-  Descriptive comment lines and empty lines are highly recommended

-  Starting with |Gromacs| version 3.1.3, all directives at the parameter
   level can be used multiple times and there are no restrictions on the
   order, except that an atom type needs to be defined before it can be
   used in other parameter definitions

-  If parameters for a certain interaction are defined multiple times
   for the same combination of atom types the last definition is used;
   starting with |Gromacs| version 3.1.3 :ref:`grompp <gmx grompp>` generates
   a warning for parameter redefinitions with different values

-  Using one of the ``[ atoms ]``,
   ``[ bonds ]``, ``[ pairs ]``,
   ``[ angles ]``, etc. without having used
   ``[ moleculetype ]`` before is meaningless and generates
   a warning

-  Using ``[ molecules ]`` without having used
   ``[ system ]`` before is meaningless and generates a
   warning.

-  After ``[ system ]`` the only allowed directive is
   ``[ molecules ]``

-  Using an unknown string in ``[ ]`` causes all the data
   until the next directive to be ignored and generates a warning

Here is an example of a topology file, ``urea.top``:

::

    ;
    ;       Example topology file
    ;
    ; The force-field files to be included
    #include "amber99.ff/forcefield.itp"

    [ moleculetype ]
    ; name  nrexcl
    Urea         3

    [ atoms ]
       1  C  1  URE      C      1     0.880229  12.01000   ; amber C  type
       2  O  1  URE      O      2    -0.613359  16.00000   ; amber O  type
       3  N  1  URE     N1      3    -0.923545  14.01000   ; amber N  type
       4  H  1  URE    H11      4     0.395055   1.00800   ; amber H  type
       5  H  1  URE    H12      5     0.395055   1.00800   ; amber H  type
       6  N  1  URE     N2      6    -0.923545  14.01000   ; amber N  type
       7  H  1  URE    H21      7     0.395055   1.00800   ; amber H  type
       8  H  1  URE    H22      8     0.395055   1.00800   ; amber H  type

    [ bonds ]
        1    2
        1    3
        1    6
        3    4
        3    5
        6    7
        6    8

    [ dihedrals ]
    ;   ai    aj    ak    al funct  definition
         2     1     3     4   9
         2     1     3     5   9
         2     1     6     7   9
         2     1     6     8   9
         3     1     6     7   9
         3     1     6     8   9
         6     1     3     4   9
         6     1     3     5   9

    [ dihedrals ]
         3     6     1     2   4
         1     4     3     5   4
         1     7     6     8   4

    [ position_restraints ]
    ; you wouldn't normally use this for a molecule like Urea,
    ; but we include it here for didactic purposes
    ; ai   funct    fc
       1     1     1000    1000    1000 ; Restrain to a point
       2     1     1000       0    1000 ; Restrain to a line (Y-axis)
       3     1     1000       0       0 ; Restrain to a plane (Y-Z-plane)

    [ dihedral_restraints ]
    ; ai   aj    ak    al  type  phi  dphi  fc
        3    6     1    2     1  180     0  10
        1    4     3    5     1  180     0  10

    ; Include TIP3P water topology
    #include "amber99.ff/tip3p.itp"

    [ system ]
    Urea in Water

    [ molecules ]
    ;molecule name   nr.
    Urea             1
    SOL              1000

Here follows the explanatory text.

**#include “amber99.ff/forcefield.itp” :** this includes
the information for the force field you are using, including bonded and
non-bonded parameters. This example uses the AMBER99 force field, but
your simulation may use a different force field. :ref:`grompp <gmx grompp>`
will automatically go and find this file and copy-and-paste its content.
That content can be seen in
``share/top/amber99.ff/forcefield.itp}``, and it
is

::

    #define _FF_AMBER
    #define _FF_AMBER99

    [ defaults ]
    ; nbfunc        comb-rule       gen-pairs       fudgeLJ fudgeQQ
    1               2               yes             0.5     0.8333

    #include "ffnonbonded.itp"
    #include "ffbonded.itp"

The two ``#define`` statements set up the conditions so that
future parts of the topology can know that the AMBER 99 force field is
in use.

**[ defaults ] :**

-  ``nbfunc`` is the non-bonded function type. Use 1 (Lennard-Jones) or 2
   (Buckingham)

-  ``comb-rule`` is the number of the combination rule (see :ref:`nbpar`).

-  ``gen-pairs`` is for pair generation. The default is
   ‘no’, *i.e.* get 1-4 parameters from the pairtypes list. When
   parameters are not present in the list, stop with a fatal error.
   Setting ‘yes’ generates 1-4 parameters that are not present in the
   pair list from normal Lennard-Jones parameters using
   ``fudgeLJ``

-  ``fudgeLJ`` is the factor by which to multiply
   Lennard-Jones 1-4 interactions, default 1

-  ``fudgeQQ`` is the factor by which to multiply
   electrostatic 1-4 interactions, default 1

-  :math:`N` is the power for the repulsion term in a 6-\ :math:`N`
   potential (with nonbonded-type Lennard-Jones only), starting with
   |Gromacs| version 4.5, :ref:`grompp <gmx mdrun>` also reads and applies
   :math:`N`, for values not equal to 12 tabulated interaction functions
   are used (in older version you would have to use user tabulated
   interactions).

**Note** that ``gen-pairs``, ``fudgeLJ``,
``fudgeQQ``, and :math:`N` are optional.
``fudgeLJ`` is only used when generate pairs is set to
‘yes’, and ``fudgeQQ`` is always used. However, if you want
to specify :math:`N` you need to give a value for the other parameters
as well.

Then some other ``#include`` statements add in the large
amount of data needed to describe the rest of the force field. We will
skip these and return to ``urea.top``. There we will see

**[ moleculetype ] :** defines the name of your molecule
in this :ref:`top` and nrexcl = 3 stands for excluding
non-bonded interactions between atoms that are no further than 3 bonds
away.

**[ atoms ] :** defines the molecule, where
``nr`` and ``type`` are fixed, the rest is user
defined. So ``atom`` can be named as you like,
``cgnr`` made larger or smaller (if possible, the total
charge of a charge group should be zero), and charges can be changed
here too.

**[ bonds ] :** no comment.

**[ pairs ] :** LJ and Coulomb 1-4 interactions

**[ angles ] :** no comment

**[ dihedrals ] :** in this case there are 9 proper
dihedrals (funct = 1), 3 improper (funct = 4) and no Ryckaert-Bellemans
type dihedrals. If you want to include Ryckaert-Bellemans type dihedrals
in a topology, do the following (in case of *e.g.* decane):

::

    [ dihedrals ]
    ;  ai    aj    ak    al funct       c0       c1       c2
        1    2     3     4     3
        2    3     4     5     3

In the original implementation of the potential for
alkanes \ :ref:`131 <refRyckaert78>` no 1-4 interactions were used, which means that in
order to implement that particular force field you need to remove the
1-4 interactions from the ``[ pairs ]`` section of your
topology. In most modern force fields, like OPLS/AA or Amber the rules
are different, and the Ryckaert-Bellemans potential is used as a cosine
series in combination with 1-4 interactions.

**[ position_restraints ] :** harmonically restrain the selected particles to reference
positions (:ref:`positionrestraint`). The reference positions are read
from a separate coordinate file by :ref:`grompp <gmx grompp>`.

**[ dihedral_restraints ] :** restrain selected dihedrals to a reference value. The
implementation of dihedral restraints is described in section
:ref:`dihedralrestraint` of the manual. The parameters specified in
the ``[dihedral_restraints]`` directive are as follows:

-  ``type`` has only one possible value which is 1

-  ``phi`` is the value of :math:`\phi_0` in :eq:`eqn. %s <eqndphi>` and
   :eq:`eqn. %s <eqndihre>` of the manual.

-  ``dphi`` is the value of :math:`\Delta\phi` in :eq:`eqn. %s <eqndihre>` of the
   manual.

-  ``fc`` is the force constant :math:`k_{dihr}` in :eq:`eqn. %s <eqndihre>` of the
   manual.

**#include “tip3p.itp” :** includes a topology file that was already
constructed (see section :ref:`molitp`).

**[ system ] :** title of your system, user-defined

**[ molecules ] :** this defines the total number of (sub)molecules in your system
that are defined in this :ref:`top`. In this example file, it stands for 1
urea molecule dissolved in 1000 water molecules. The molecule type ``SOL``
is defined in the ``tip3p.itp`` file. Each name here must correspond to a
name given with ``[ moleculetype ]`` earlier in the topology. The order of the blocks of
molecule types and the numbers of such molecules must match the
coordinate file that accompanies the topology when supplied to :ref:`grompp <gmx grompp>`.
The blocks of molecules do not need to be contiguous, but some tools
(e.g. :ref:`genion <gmx genion>`) may act only on the first or last such block of a
particular molecule type. Also, these blocks have nothing to do with the
definition of groups (see sec. :ref:`groupconcept` and
sec. :ref:`usinggroups`).

.. _molitp:

Molecule.itp file
~~~~~~~~~~~~~~~~~

If you construct a topology file you will use frequently (like the water
molecule, ``tip3p.itp``, which is already constructed for
you) it is good to make a ``molecule.itp`` file. This only
lists the information of one particular molecule and allows you to
re-use the ``[ moleculetype ]`` in multiple systems without
re-invoking :ref:`pdb2gmx <gmx pdb2gmx>` or manually copying and pasting. An
example ``urea.itp`` follows:

::

    [ moleculetype ]
    ; molname   nrexcl
    URE         3

    [ atoms ]
       1  C  1  URE      C      1     0.880229  12.01000   ; amber C  type
    ...
       8  H  1  URE    H22      8     0.395055   1.00800   ; amber H  type

    [ bonds ]
        1       2
    ...
        6       8
    [ dihedrals ]
    ;   ai    aj    ak    al funct  definition
         2     1     3     4   9
    ...
         6     1     3     5   9
    [ dihedrals ]
         3     6     1     2   4
         1     4     3     5   4
         1     7     6     8   4

Using :ref:`itp` files results in a very short
:ref:`top` file:

::

    ;
    ;       Example topology file
    ;
    ; The force field files to be included
    #include "amber99.ff/forcefield.itp"

    #include "urea.itp"

    ; Include TIP3P water topology
    #include "amber99/tip3p.itp"

    [ system ]
    Urea in Water

    [ molecules ]
    ;molecule name   nr.
    Urea             1
    SOL              1000

Ifdef statements
~~~~~~~~~~~~~~~~

A very powerful feature in |Gromacs| is the use of ``#ifdef``
statements in your :ref:`top` file. By making use of this
statement, and associated ``#define`` statements like were
seen in ``amber99.ff/forcefield.itp`` earlier,
different parameters for one molecule can be used in the same
:ref:`top` file. An example is given for TFE, where there is
an option to use different charges on the atoms: charges derived by De
Loof et al. :ref:`132 <refLoof92>` or by Van Buuren and
Berendsen \ :ref:`133 <refBuuren93a>`. In fact, you can use much of the
functionality of the C preprocessor, ``cpp``, because
:ref:`grompp <gmx grompp>` contains similar pre-processing functions to scan
the file. The way to make use of the ``#ifdef`` option is as
follows:

-  either use the option ``define = -DDeLoof`` in the
   :ref:`mdp` file (containing :ref:`grompp <gmx grompp>` input
   parameters), or use the line ``#define DeLoof`` early in
   your :ref:`top` or :ref:`itp` file; and

-  put the ``#ifdef`` statements in your
   :ref:`top`, as shown below:


::

    ...



    [ atoms ]
    ; nr     type     resnr    residu     atom      cgnr      charge        mass
    #ifdef DeLoof
    ; Use Charges from DeLoof
       1        C        1        TFE        C         1        0.74
       2        F        1        TFE        F         1       -0.25
       3        F        1        TFE        F         1       -0.25
       4        F        1        TFE        F         1       -0.25
       5      CH2        1        TFE      CH2         1        0.25
       6       OA        1        TFE       OA         1       -0.65
       7       HO        1        TFE       HO         1        0.41
    #else
    ; Use Charges from VanBuuren
       1        C        1        TFE        C         1        0.59
       2        F        1        TFE        F         1       -0.2
       3        F        1        TFE        F         1       -0.2
       4        F        1        TFE        F         1       -0.2
       5      CH2        1        TFE      CH2         1        0.26
       6       OA        1        TFE       OA         1       -0.55
       7       HO        1        TFE       HO         1        0.3
    #endif

    [ bonds ]
    ;  ai    aj funct           c0           c1
        6     7     1 1.000000e-01 3.138000e+05
        1     2     1 1.360000e-01 4.184000e+05
        1     3     1 1.360000e-01 4.184000e+05
        1     4     1 1.360000e-01 4.184000e+05
        1     5     1 1.530000e-01 3.347000e+05
        5     6     1 1.430000e-01 3.347000e+05
    ...

This mechanism is used by :ref:`pdb2gmx <gmx pdb2gmx>` to implement optional position
restraints (:ref:`positionrestraint`) by ``#include``-ing an :ref:`itp` file
whose contents will be meaningful only if a particular ``#define`` is set
(and spelled correctly!)

Topologies for free energy calculations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Free energy differences between two systems, A and B, can be calculated
as described in sec. :ref:`fecalc`. Systems A and B are described by
topologies consisting of the same number of molecules with the same
number of atoms. Masses and non-bonded interactions can be perturbed by
adding B parameters under the ``[ atoms ]`` directive. Bonded interactions can be
perturbed by adding B parameters to the bonded types or the bonded
interactions. The parameters that can be perturbed are listed in
:numref:`Tables %s <tab-topfile1>` and :numref:`%s <tab-topfile2>`.
The :math:`\lambda`-dependence of the
interactions is described in section sec. :ref:`feia`. The bonded
parameters that are used (on the line of the bonded interaction
definition, or the ones looked up on atom types in the bonded type
lists) is explained in :numref:`Table %s <tab-topfe>`. In most cases, things should
work intuitively. When the A and B atom types in a bonded interaction
are not all identical and parameters are not present for the B-state,
either on the line or in the bonded types, :ref:`grompp <gmx grompp>` uses the A-state
parameters and issues a warning. For free energy calculations, all or no
parameters for topology B (:math:`\lambda = 1`) should be added on the
same line, after the normal parameters, in the same order as the normal
parameters. From |Gromacs| 4.6 onward, if :math:`\lambda` is treated as a
vector, then the ``bonded-lambdas`` component controls all bonded terms that
are not explicitly labeled as restraints. Restrain terms are controlled
by the ``restraint-lambdas`` component.

.. |NOT| replace:: :math:`-`

.. _tab-topfe:

.. table:: The bonded parameters that are used for free energy topologies,
           on the line of the bonded interaction definition or looked up
           in the bond types section based on atom types. A and B indicate the
           parameters used for state A and B respectively, + and |NOT| indicate
           the (non-)presence of parameters in the topology, x indicates that
           the presence has no influence.

           +--------------------+---------------+-----------------------------------+---------+
           | B-state atom types | parameters    | parameters in   | parameters in   |         |
           |                    |               | bonded types    | bonded types    | expected|
           | all identical to   | on line       | of A atoms      | of B atoms      | message |
           |                    +-------+-------+-------+---------+-------+---------+         |
           | A-state atom types | A     | B     | A     | B       | A     | B       |         |
           +====================+=======+=======+=======+=========+=======+=========+=========+
           | yes                | +AB   | |NOT| | x     | x       |       |         |         |
           +--------------------+-------+-------+-------+---------+-------+---------+---------+
           | yes                | +A    | +B    | x     | x       |       |         |         |
           +--------------------+-------+-------+-------+---------+-------+---------+---------+
           | yes                | |NOT| | |NOT| | |NOT| | |NOT|   |       |         | error   |
           +--------------------+-------+-------+-------+---------+-------+---------+---------+
           | yes                | |NOT| | |NOT| | +AB   | |NOT|   |       |         |         |
           +--------------------+-------+-------+-------+---------+-------+---------+---------+
           | yes                | |NOT| | |NOT| | +A    | +B      |       |         |         |
           +--------------------+-------+-------+-------+---------+-------+---------+---------+
           | no                 | +AB   | |NOT| | x     | x       | x     | x       | warning |
           +--------------------+-------+-------+-------+---------+-------+---------+---------+
           | no                 | +A    | +B    | x     | x       | x     | x       |         |
           +--------------------+-------+-------+-------+---------+-------+---------+---------+
           | no                 | |NOT| | |NOT| | |NOT| | |NOT|   | x     | x       | error   |
           +--------------------+-------+-------+-------+---------+-------+---------+---------+
           | no                 | |NOT| | |NOT| | +AB   | |NOT|   | |NOT| | |NOT|   | warning |
           +--------------------+-------+-------+-------+---------+-------+---------+---------+
           | no                 | |NOT| | |NOT| | +A    | +B      | |NOT| | |NOT|   | warning |
           +--------------------+-------+-------+-------+---------+-------+---------+---------+
           | no                 | |NOT| | |NOT| | +A    | x       | +B    | |NOT|   |         |
           +--------------------+-------+-------+-------+---------+-------+---------+---------+
           | no                 | |NOT| | |NOT| | +A    | x       | +     | +B      |         |
           +--------------------+-------+-------+-------+---------+-------+---------+---------+



Below is an example of a topology which changes from 200 propanols to
200 pentanes using the GROMOS-96 force field.

::


    ; Include force field parameters
    #include "gromos43a1.ff/forcefield.itp"

    [ moleculetype ]
    ; Name            nrexcl
    PropPent          3

    [ atoms ]
    ; nr type resnr residue atom cgnr  charge    mass  typeB chargeB  massB
      1    H    1     PROP    PH    1   0.398    1.008  CH3     0.0  15.035
      2   OA    1     PROP    PO    1  -0.548  15.9994  CH2     0.0  14.027
      3  CH2    1     PROP   PC1    1   0.150   14.027  CH2     0.0  14.027
      4  CH2    1     PROP   PC2    2   0.000   14.027
      5  CH3    1     PROP   PC3    2   0.000   15.035

    [ bonds ]
    ;  ai    aj funct    par_A  par_B
        1     2     2    gb_1   gb_26
        2     3     2    gb_17  gb_26
        3     4     2    gb_26  gb_26
        4     5     2    gb_26

    [ pairs ]
    ;  ai    aj funct
        1     4     1
        2     5     1

    [ angles ]
    ;  ai    aj    ak funct    par_A   par_B
        1     2     3     2    ga_11   ga_14
        2     3     4     2    ga_14   ga_14
        3     4     5     2    ga_14   ga_14

    [ dihedrals ]
    ;  ai    aj    ak    al funct    par_A   par_B
        1     2     3     4     1    gd_12   gd_17
        2     3     4     5     1    gd_17   gd_17

    [ system ]
    ; Name
    Propanol to Pentane

    [ molecules ]
    ; Compound        #mols
    PropPent          200

Atoms that are not perturbed, ``PC2`` and
``PC3``, do not need B-state parameter specifications, since
the B parameters will be copied from the A parameters. Bonded
interactions between atoms that are not perturbed do not need B
parameter specifications, as is the case for the last bond in the
example topology. Topologies using the OPLS/AA force field need no
bonded parameters at all, since both the A and B parameters are
determined by the atom types. Non-bonded interactions involving one or
two perturbed atoms use the free-energy perturbation functional forms.
Non-bonded interactions between two non-perturbed atoms use the normal
functional forms. This means that when, for instance, only the charge of
a particle is perturbed, its Lennard-Jones interactions will also be
affected when lambda is not equal to zero or one.

**Note** that this topology uses the GROMOS-96 force field, in which the
bonded interactions are not determined by the atom types. The bonded
interaction strings are converted by the C-preprocessor. The force-field
parameter files contain lines like:

::

    #define gb_26       0.1530  7.1500e+06

    #define gd_17     0.000       5.86          3

.. _constraintforce:

Constraint forces
~~~~~~~~~~~~~~~~~

| The constraint force between two atoms in one molecule can be
  calculated with the free energy perturbation code by adding a
  constraint between the two atoms, with a different length in the A and
  B topology. When the B length is 1 nm longer than the A length and
  lambda is kept constant at zero, the derivative of the Hamiltonian
  with respect to lambda is the constraint force. For constraints
  between molecules, the pull code can be used, see sec. :ref:`pull`.
  Below is an example for calculating the constraint force at 0.7 nm
  between two methanes in water, by combining the two methanes into one
  “molecule.” **Note** that the definition of a “molecule” in |Gromacs|
  does not necessarily correspond to the chemical definition of a
  molecule. In |Gromacs|, a “molecule” can be defined as any group of
  atoms that one wishes to consider simultaneously. The added constraint
  is of function type 2, which means that it is not used for generating
  exclusions (see sec. :ref:`excl`). Note that the constraint free energy
  term is included in the derivative term, and is specifically included
  in the ``bonded-lambdas`` component. However, the free energy for changing
  constraints is *not* included in the potential energy differences used
  for BAR and MBAR, as this requires reevaluating the energy at each of
  the constraint components. This functionality is planned for later
  versions.

::

    ; Include force-field parameters
    #include "gromos43a1.ff/forcefield.itp"

    [ moleculetype ]
    ; Name            nrexcl
    Methanes               1

    [ atoms ]
    ; nr   type   resnr  residu   atom    cgnr     charge    mass
       1    CH4     1     CH4      C1       1          0    16.043
       2    CH4     1     CH4      C2       2          0    16.043
    [ constraints ]
    ;  ai    aj funct   length_A  length_B
        1     2     2        0.7       1.7

    #include "gromos43a1.ff/spc.itp"

    [ system ]
    ; Name
    Methanes in Water

    [ molecules ]
    ; Compound        #mols
    Methanes              1
    SOL                2002

Coordinate file
~~~~~~~~~~~~~~~

Files with the :ref:`gro` file extension contain a molecular
structure in GROMOS-87 format. A sample piece is included below:

::

    MD of 2 waters, reformat step, PA aug-91
        6
        1WATER  OW1    1   0.126   1.624   1.679  0.1227 -0.0580  0.0434
        1WATER  HW2    2   0.190   1.661   1.747  0.8085  0.3191 -0.7791
        1WATER  HW3    3   0.177   1.568   1.613 -0.9045 -2.6469  1.3180
        2WATER  OW1    4   1.275   0.053   0.622  0.2519  0.3140 -0.1734
        2WATER  HW2    5   1.337   0.002   0.680 -1.0641 -1.1349  0.0257
        2WATER  HW3    6   1.326   0.120   0.568  1.9427 -0.8216 -0.0244
       1.82060   1.82060   1.82060

This format is fixed, *i.e.* all columns are in a fixed position. If you
want to read such a file in your own program without using the |Gromacs|
libraries you can use the following formats:

**C-format:**
``“%5i%5s%5s%5i%8.3f%8.3f%8.3f%8.4f%8.4f%8.4f”``

Or to be more precise, with title *etc.* it looks like this:

::

      "%s\n", Title
      "%5d\n", natoms
      for (i=0; (i<natoms); i++) {
        "%5d%-5s%5s%5d%8.3f%8.3f%8.3f%8.4f%8.4f%8.4f\n",
          residuenr,residuename,atomname,atomnr,x,y,z,vx,vy,vz
      }
      "%10.5f%10.5f%10.5f%10.5f%10.5f%10.5f%10.5f%10.5f%10.5f\n",
        box[X][X],box[Y][Y],box[Z][Z],
        box[X][Y],box[X][Z],box[Y][X],box[Y][Z],box[Z][X],box[Z][Y]

**Fortran format:**
``(i5,2a5,i5,3f8.3,3f8.4)``

So ``confin.gro`` is the |Gromacs| coordinate file and is
almost the same as the GROMOS-87 file (for GROMOS users: when used with
``ntx=7``). The only difference is the box for which |Gromacs|
uses a tensor, not a vector.