docs/reference-manual/topologies/topology-file-formats.rst

   1 File formats
   2 ------------
   3
   4 .. _topfile:
   5
   6 Topology file
   7 ~~~~~~~~~~~~~
   8
   9 The topology file is built following the |Gromacs| specification for a
  10 molecular topology. A :ref:`top` file can be generated by
  11 :ref:`pdb2gmx <gmx pdb2gmx>`. All possible entries in the topology file are
  12 listed in :numref:`Tables %s <tab-topfile1>` and
  13 :numref:`%s <tab-topfile2>`. Also tabulated are: all the units of
  14 the parameters, which interactions can be perturbed for free energy
  15 calculations, which bonded interactions are used by
  16 :ref:`grompp <gmx grompp>` for generating exclusions, and which bonded
  17 interactions can be converted to constraints by :ref:`grompp <gmx grompp>`.
  18
  19 .. |VCR| replace:: V\ :math:`^{(cr)}`
  20 .. |WCR| replace:: W\ :math:`^{(cr)}`
  21 .. |CRO| replace:: :math:`^{(cr)}`
  22 .. |TREF| replace:: :numref:`Table %s <tab-topfile2>`
  23 .. |AKJM| replace:: :math:`a~\mathrm{kJ~mol}^{-1}`
  24 .. |KJN6| replace:: :math:`\mathrm{kJ~mol}^{-1}~\mathrm{nm}^{-6}`
  25 .. |BNM| replace:: :math:`b~\mathrm{nm}^{-1}`
  26 .. |C6LJ| replace:: :math:`c_6`
  27 .. |STAR| replace:: :math:`^{(*)}`
  28 .. |NREX| replace:: :math:`n_{ex}^{(nrexcl)}`
  29 .. |QEMU| replace:: :math:`q` (e); :math:`m` (u)
  30 .. |MQM| replace:: :math:`q,m`
  31
  32 .. _tab-topfile1:
  33
  34 .. table:: The :ref:`topology <top>` file.
  35
  36         +------------------------------------------------------------------------------------------------------------+
  37         | Parameters                                                                                                 |
  38         +===================+===========================+=====+====+=========================================+=======+
  39         | interaction type  | directive                 | #   | f. | parameters                              | F. E. |
  40         |                   |                           | at. | tp |                                         |       |
  41         +-------------------+---------------------------+-----+----+-----------------------------------------+-------+
  42         | *mandatory*       | ``defaults``              |            non-bonded function type;                       |
  43         |                   |                           |            combination rule\ |CRO|;                        |
  44         |                   |                           |            generate pairs (no/yes);                        |
  45         |                   |                           |            fudge LJ (); fudge QQ ()                        |
  46         +-------------------+---------------------------+------------------------------------------------------------+
  47         | *mandatory*       | ``atomtypes``             |            atom type; m (u); q (e); particle type;         |
  48         |                   |                           |            |VCR| ; |WCR|                                   |
  49         +-------------------+---------------------------+------------------------------------------------------------+
  50         |                   | ``bondtypes``             |  (see |TREF|, directive ``bonds``)                         |
  51         +                   +                           +                                                            +
  52         |                   | ``pairtypes``             |  (see |TREF|, directive ``pairs``)                         |
  53         +                   +                           +                                                            +
  54         |                   | ``angletypes``            |  (see |TREF|, directive ``angles``)                        |
  55         +                   +                           +                                                            +
  56         |                   | ``dihedraltypes``\ |STAR| |  (see |TREF|, directive ``dihedrals``)                     |
  57         +                   +                           +                                                            +
  58         |                   | ``constrainttypes``       |  (see |TREF|, directive ``constraints``)                   |
  59         +-------------------+---------------------------+-----+----+-------------------------------------------------+
  60         | LJ                | ``nonbond_params``        |  2  | 1  |  |VCR|  ; |WCR|                                 |
  61         +                   +                           +     +    +                                                 +
  62         | Buckingham        | ``nonbond_params``        |  2  | 2  |  |AKJM| ; |BNM|;                                |
  63         |                   |                           |     |    |  |C6LJ| (|KJN6|)                                |
  64         +-------------------+---------------------------+-----+----+-------------------------------------------------+
  65
  66 .. table::
  67
  68         +------------------------------------------------------------------------------------------------------------+
  69         | Molecule definition(s)                                                                                     |
  70         +===================+===========================+============================================================+
  71         | *mandatory*       | ``moleculetype``          | molecule name; |NREX|                                      |
  72         +-------------------+---------------------------+-----+----------------------------------------------+-------+
  73         | *mandatory*       | ``atoms``                 | 1   | atom type; residue number;                   | type  |
  74         |                   |                           |     | residue name; atom name;                     |       |
  75         |                   |                           |     | charge group number; |QEMU|                  | |MQM| |
  76         +-------------------+---------------------------+-----+----------------------------------------------+-------+
  77         | intra-molecular interaction and geometry definitions as described in |TREF|                                |
  78         +------------------------------------------------------------------------------------------------------------+
  79
  80 .. table::
  81
  82         +-------------+---------------+------------------------------------+
  83         | System      |               |                                    |
  84         +=============+===============+====================================+
  85         | *mandatory* | ``system``    | system name                        |
  86         +-------------+---------------+------------------------------------+
  87         | *mandatory* | ``molecules`` | molecule name; number of molecules |
  88         +-------------+---------------+------------------------------------+
  89
  90 .. table::
  91
  92         +------------------------------+----------------------------------------------------+
  93         | Inter-molecular interactions |                                                    |
  94         +==============================+====================================================+
  95         | *optional*                   | ``intermolecular_interactions``                    |
  96         +------------------------------+----------------------------------------------------+
  97         | one or more bonded interactions as described in |TREF|, with two or more atoms,   |
  98         | no interactions that generate exclusions, no constraints, use global atom numbers |
  99         +-----------------------------------------------------------------------------------+
 100
 101 .. parsed-literal::
 102
 103     '\# at' is the required number of atom type indices for this directive
 104     'f. tp' is the value used to select this function type
 105     'F. E.' indicates which of the parameters can be interpolated in free energy calculations
 106     |CRO| the combination rule determines the type of LJ parameters, see
 107     |STAR| for ``dihedraltypes`` one can specify 4 atoms or the inner (outer for improper) 2 atoms
 108     |NREX| exclude neighbors :math:`n_{ex}` bonds away for non-bonded interactions
 109     For free energy calculations, type, :math:`q` and :math:`m`  or no parameters should be added
 110     for topology 'B' (:math:`\lambda = 1`) on the same line, after the normal parameters.
 111
 112 .. |BZERO| replace:: :math:`b_0`
 113 .. |KB| replace:: :math:`k_b`
 114 .. |KDR| replace:: :math:`k_{dr}`
 115 .. |NM2| replace:: (kJ mol\ :math:`^{-1}`\ nm\ :math:`^{-2}`
 116 .. |NM4| replace:: (kJ mol\ :math:`^{-1}`\ nm\ :math:`^{-4}`
 117 .. |DKJ| replace:: :math:`D` (kJ mol\ :math:`^{-1}`
 118 .. |BETA| replace:: :math:`\beta` (nm\ :math:`^{-1}`
 119 .. |C23| replace:: :math:`C_{i=2,3}` (kJ mol\ :math:`^{-1}\ nm\ :math:`^{-i}`
 120 .. |BMM| replace:: :math:`b_m`
 121 .. |GE0| replace:: :math:`\geq 0`
 122 .. |KO| replace:: :math:`k`
 123 .. |KJM| replace:: kJ mol\ :math:`^{-1}`
 124 .. |LUU| replace:: low, up\ :math:`_1`,\ :math:`_2`
 125 .. |MV| replace:: :math:`V`
 126 .. |MW| replace:: :math:`W`
 127 .. |QIJ| replace:: :math:`q_i`; :math:`q_j`
 128 .. |THE0| replace:: :math:`\theta_0`
 129 .. |KTHE| replace:: :math:`k_\theta`
 130 .. |KJR2| replace:: kJ mol\ :math:`^{-1}`\ rad\ :math:`^{-2}`
 131 .. |RN13| replace:: :math:`r_{13}`
 132 .. |KUB| replace:: :math:`k_{UB}`
 133 .. |C024| replace:: :math:`C_{i=0,1,2,3,4}`
 134 .. |KJRI| replace:: kJ mol\ :math:`^{-1}`\ rad\ :math:`^{-i}`
 135 .. |PHIS| replace:: :math:`\phi_s`
 136 .. |PHI0| replace:: :math:`\phi_0`
 137 .. |KPHI| replace:: :math:`k_\phi`
 138 .. |PHIK| replace:: :math:`\phi,k`
 139 .. |XI0| replace:: :math:`\xi_0`
 140 .. |KXI| replace:: :math:`k_\xi`
 141 .. |C0| replace:: :math:`C_0`
 142 .. |C1| replace:: :math:`C_1`
 143 .. |C2| replace:: :math:`C_2`
 144 .. |C3| replace:: :math:`C_3`
 145 .. |C4| replace:: :math:`C_4`
 146 .. |C5| replace:: :math:`C_5`
 147 .. |A0| replace:: :math:`a_0`
 148 .. |A1| replace:: :math:`a_1`
 149 .. |A2| replace:: :math:`a_2`
 150 .. |A3| replace:: :math:`a_3`
 151 .. |A4| replace:: :math:`a_4`
 152 .. |DOH| replace:: :math:d_{\mbox{\sc oh}}`
 153 .. |DHH| replace:: :math:d_{\mbox{\sc hh}}`
 154 .. |AO| replace:: :math:`a`
 155 .. |BO| replace:: :math:`b`
 156 .. |CO| replace:: :math:`c`
 157 .. |DO| replace:: :math:`d`
 158 .. |KX| replace:: :math:`k_{x}`
 159 .. |KY| replace:: :math:`k_{y}`
 160 .. |KZ| replace:: :math:`k_{z}`
 161 .. |GO| replace:: :math:`g`
 162 .. |RO| replace:: :math:`r`
 163 .. |DPHI| replace:: :math:`\Delta\phi`
 164 .. |DIHR| replace:: :math:`k_{\mathrm{dihr}}`
 165 .. |THET| replace:: :math:`\theta`
 166 .. |NM| replace:: nm\ :math:`^{-1}`
 167 .. |KC| replace:: :math:`k_c`
 168 .. |THEK| replace:: :math:`\theta,k`
 169 .. |R1E| replace:: :math:`r_{1e}`
 170 .. |R2E| replace:: :math:`r_{2e}`
 171 .. |R3E| replace:: :math:`r_{3e}`
 172 .. |KRR| replace:: :math:`k_{rr'}`
 173 .. |KRTH| replace:: :math:`k_{r\theta}`
 174 .. |ALPH| replace:: :math:`\alpha`; |CO| (U nm\ :math:`^{\alpha}`
 175 .. |UM1| replace:: U\ :math:`^{-1}`
 176
 177 .. _tab-topfile2:
 178
 179 .. table:: Details of ``[ moleculetype ]`` directives
 180
 181             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 182             | Name of interaction                | Topology file directive    | num.       | func.     | Order of parameters and their units                                     | use in     |
 183             |                                    |                            | atoms [1]_ | type [2]_ |                                                                         | F.E.? [3]_ |
 184             +====================================+============================+============+===========+=========================================================================+============+
 185             | bond                               | ``bonds`` [4]_, [5]_       | 2          | 1         | |BZERO| (nm); |KB| |NM2|                                                | all        |
 186             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 187             | G96 bond                           | ``bonds`` [4]_, [5]_       | 2          | 2         | |BZERO| (nm); |KB| |NM4|                                                | all        |
 188             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 189             | Morse                              | ``bonds`` [4]_, [5]_       | 2          | 3         | |BZERO| (nm); |DKJ|; |BETA|                                             | all        |
 190             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 191             | cubic bond                         | ``bonds`` [4]_, [5]_       | 2          | 4         | |BZERO| (nm); |C23|                                                     |            |
 192             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 193             | connection                         | ``bonds`` [4]_             | 2          | 5         |                                                                         |            |
 194             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 195             | harmonic potential                 | ``bonds``                  | 2          | 6         | |BZERO| (nm); |KB| |NM2|                                                | all        |
 196             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 197             | FENE bond                          | ``bonds`` [4]_             | 2          | 7         | |BMM|   (nm); |KB| |NM2|                                                |            |
 198             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 199             | tabulated bond                     | ``bonds`` [4]_             | 2          | 8         | table number (|GE0|); |KO| |KJM|                                        | |KO|       |
 200             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 201             | tabulated bond [6]_                | ``bonds``                  | 2          | 9         | table number (|GE0|); |KO| |KJM|                                        | |KO|       |
 202             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 203             | restraint potential                | ``bonds``                  | 2          | 10        | |LUU| (nm); |KDR| (|NM2|)                                               | all        |
 204             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 205             | extra LJ or Coulomb                | ``pairs``                  | 2          | 1         | |MV| [7]_; |MW| [7]_                                                    | all        |
 206             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 207             | extra LJ or Coulomb                | ``pairs``                  | 2          | 2         | fudge QQ (); |QIJ| (e), |MV| [7]_; |MW| [7]_                            |            |
 208             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 209             | extra LJ or Coulomb                | ``pairs_nb``               | 2          | 1         | |QIJ| (e); |MV| [7]_; |MW| [7]_                                         |            |
 210             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 211             | angle                              | ``angles`` [5]_            | 3          | 1         | |THE0| (deg); |KTHE| (|KJR2|)                                           | all        |
 212             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 213             | G96 angle                          | ``angles`` [5]_            | 3          | 2         | |THE0| (deg); |KTHE| (|KJM|)                                            | all        |
 214             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 215             | cross bond-bond                    | ``angles``                 | 3          | 3         | |R1E|, |R2E| (nm); |KRR| (|NM2|)                                        |            |
 216             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 217             | cross bond-angle                   | ``angles``                 | 3          | 4         | |R1E|, |R2E|, |R3E| (nm); |KRTH| (|NM2|)                                |            |
 218             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 219             | Urey-Bradley                       | ``angles`` [5]_            | 3          | 5         | |THE0| (deg); |KTHE| (|KJR2|); |RN13| (nm); |KUB| (|NM2|)               | all        |
 220             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 221             | quartic angle                      | ``angles`` [5]_            | 3          | 6         | |THE0| (deg); |C024| (|KJRI|)                                           |            |
 222             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 223             | tabulated angle                    | ``angles``                 | 3          | 8         | table number (|GE0|); |KO| (|KJM|)                                      | |KO|       |
 224             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 225             |  |  restricted                     |                            |            |           |                                                                         |            |
 226             |  |  bending potential              | ``angles``                 | 3          | 10        | |THE0| (deg); |KTHE| (|KJM|)                                            |            |
 227             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 228             | proper dihedral                    | ``dihedrals``              | 4          | 1         | |PHIS| (deg); |KPHI| (|KJM|); multiplicity                              | |PHIK|     |
 229             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 230             | improper dihedral                  | ``dihedrals``              | 4          | 2         | |XI0| (deg); |KXI| (|KJR2|)                                             | all        |
 231             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 232             | Ryckaert-Bellemans dihedral        | ``dihedrals``              | 4          | 3         | |C0|, |C1|, |C2|, |C3|, |C4|, |C5| (|KJM|)                              | all        |
 233             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 234             | periodic improper dihedral         | ``dihedrals``              | 4          | 4         | |PHIS| (deg); |KPHI| (|KJM|); multiplicity                              | |PHIK|     |
 235             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 236             | Fourier dihedral                   | ``dihedrals``              | 4          | 5         | |C1|, |C2|, |C3|, |C4|, |C5| (|KJM|)                                    | all        |
 237             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 238             | tabulated dihedral                 | ``dihedrals``              | 4          | 8         | table number (|GE0|); |KO| (|KJM|)                                      | |KO|       |
 239             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 240             | proper dihedral (multiple)         | ``dihedrals``              | 4          | 9         | |PHIS| (deg); |KPHI| (|KJM|); multiplicity                              | |PHIK|     |
 241             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 242             | restricted dihedral                | ``dihedrals``              | 4          | 10        | |PHI0| (deg); |KPHI| (|KJM|)                                            |            |
 243             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 244             | combined bending-torsion potential | ``dihedrals``              | 4          | 11        | |A0|, |A1|, |A2|, |A3|, |A4| (|KJM|)                                    |            |
 245             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 246             | exclusions                         | ``exclusions``             | 1          |           | one or more atom indices                                                |            |
 247             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 248             | constraint                         | ``constraints`` [4]_       | 2          | 1         | |BZERO| (nm)                                                            | all        |
 249             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 250             | constraint [6]_                    | ``constraints``            | 2          | 2         | |BZERO| (nm)                                                            | all        |
 251             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 252             | SETTLE                             | ``settles``                | 1          | 1         | |DOH|, |DHH| (nm)                                                       |            |
 253             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 254             | 2-body virtual site                | ``virtual_sites2``         | 3          | 1         | |AO| ()                                                                 |            |
 255             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 256             | 2-body virtual site (fd)           | ``virtual_sites2``         | 3          | 2         | |DO| (nm)                                                               |            |
 257             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 258             | 3-body virtual site                | ``virtual_sites3``         | 4          | 1         | |AO|, |BO| ()                                                           |            |
 259             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 260             | 3-body virtual site (fd)           | ``virtual_sites3``         | 4          | 2         | |AO| (); |DO| (nm)                                                      |            |
 261             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 262             | 3-body virtual site (fad)          | ``virtual_sites3``         | 4          | 3         | |THET| (deg); |DO| (nm)                                                 |            |
 263             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 264             | 3-body virtual site (out)          | ``virtual_sites3``         | 4          | 4         | |AO|, |BO| (); |CO| (|NM|)                                              |            |
 265             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 266             | 4-body virtual site (fdn)          | ``virtual_sites4``         | 5          | 2         | |AO|, |BO| (); |CO| (nm)                                                |            |
 267             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 268             | N-body virtual site (COG)          | ``virtual_sitesn``         | 1          | 1         | one or more constructing atom indices                                   |            |
 269             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 270             | N-body virtual site (COM)          | ``virtual_sitesn``         | 1          | 2         | one or more constructing atom indices                                   |            |
 271             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 272             | N-body virtual site (COW)          | ``virtual_sitesn``         | 1          | 3         |  |  one or more pairs consisting of                                     |            |
 273             |                                    |                            |            |           |  |  constructing atom index and weight                                  |            |
 274             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 275             | position restraint                 | ``position_restraints``    | 1          | 1         | |KX|, |KY|, |KZ| (|NM2|)                                                | all        |
 276             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 277             | flat-bottomed position restraint   | ``position_restraints``    | 1          | 2         | |GO|, |RO| (nm), |KO| (|NM2|)                                           |            |
 278             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 279             | distance restraint                 | ``distance_restraints``    | 2          | 1         | type; label; |LUU| (nm); weight ()                                      |            |
 280             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 281             | dihedral restraint                 | ``dihedral_restraints``    | 4          | 1         | |PHI0| (deg); |DPHI| (deg); |DIHR| (|KJR2|)                             | all        |
 282             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 283             | orientation restraint              | ``orientation_restraints`` | 2          | 1         | exp.; label; |ALPH|; obs. (U); weight (|UM1|)                           |            |
 284             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 285             | angle restraint                    | ``angle_restraints``       | 4          | 1         | |THE0| (deg); |KC| (|KJM|); multiplicity                                | |THEK|     |
 286             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 287             | angle restraint (z)                | ``angle_restraints_z``     | 2          | 1         | |THE0| (deg); |KC| (|KJM|); multiplicity                                | |THEK|     |
 288             +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
 289
 290 .. [1]
 291    The required number of atom indices for this directive
 292
 293 .. [2]
 294    The index to use to select this function type
 295
 296 .. [3]
 297    Indicates which of the parameters can be interpolated in free energy calculations
 298
 299 .. [4]
 300    This interaction type will be used by :ref:`grompp <gmx grompp>` for generating exclusions
 301
 302 .. [5]
 303    This interaction type can be converted to constraints by :ref:`grompp <gmx grompp>`
 304
 305 .. [7]
 306    The combination rule determines the type of LJ parameters, see
 307
 308 .. [6]
 309    No connection, and so no exclusions, are generated for this interaction
 310
 311 Description of the file layout:
 312
 313 -  Semicolon (;) and newline characters surround comments
 314
 315 -  On a line ending with :math:`\backslash` the newline character is
 316    ignored.
 317
 318 -  Directives are surrounded by ``[`` and ``]``
 319
 320 -  The topology hierarchy (which must be followed) consists of three
 321    levels:
 322
 323    -  the parameter level, which defines certain force-field
 324       specifications (see :numref:`Table %s <tab-topfile1>`)
 325
 326    -  the molecule level, which should contain one or more molecule
 327       definitions (see :numref:`Table %s <tab-topfile2>`)
 328
 329    -  the system level, containing only system-specific information
 330       (``[ system ]`` and ``[ molecules ]``)
 331
 332 -  Items should be separated by spaces or tabs, not commas
 333
 334 -  Atoms in molecules should be numbered consecutively starting at 1
 335
 336 -  Atoms in the same charge group must be listed consecutively
 337
 338 -  The file is parsed only once, which implies that no forward
 339    references can be treated: items must be defined before they can be
 340    used
 341
 342 -  Exclusions can be generated from the bonds or overridden manually
 343
 344 -  The bonded force types can be generated from the atom types or
 345    overridden per bond
 346
 347 -  It is possible to apply multiple bonded interactions of the same type
 348    on the same atoms
 349
 350 -  Descriptive comment lines and empty lines are highly recommended
 351
 352 -  Starting with |Gromacs| version 3.1.3, all directives at the parameter
 353    level can be used multiple times and there are no restrictions on the
 354    order, except that an atom type needs to be defined before it can be
 355    used in other parameter definitions
 356
 357 -  If parameters for a certain interaction are defined multiple times
 358    for the same combination of atom types the last definition is used;
 359    starting with |Gromacs| version 3.1.3 :ref:`grompp <gmx grompp>` generates
 360    a warning for parameter redefinitions with different values
 361
 362 -  Using one of the ``[ atoms ]``,
 363    ``[ bonds ]``, ``[ pairs ]``,
 364    ``[ angles ]``, etc. without having used
 365    ``[ moleculetype ]`` before is meaningless and generates
 366    a warning
 367
 368 -  Using ``[ molecules ]`` without having used
 369    ``[ system ]`` before is meaningless and generates a
 370    warning.
 371
 372 -  After ``[ system ]`` the only allowed directive is
 373    ``[ molecules ]``
 374
 375 -  Using an unknown string in ``[ ]`` causes all the data
 376    until the next directive to be ignored and generates a warning
 377
 378 Here is an example of a topology file, ``urea.top``:
 379
 380 ::
 381
 382     ;
 383     ;       Example topology file
 384     ;
 385     ; The force-field files to be included
 386     #include "amber99.ff/forcefield.itp"
 387
 388     [ moleculetype ]
 389     ; name  nrexcl
 390     Urea         3
 391
 392     [ atoms ]
 393        1  C  1  URE      C      1     0.880229  12.01000   ; amber C  type
 394        2  O  1  URE      O      2    -0.613359  16.00000   ; amber O  type
 395        3  N  1  URE     N1      3    -0.923545  14.01000   ; amber N  type
 396        4  H  1  URE    H11      4     0.395055   1.00800   ; amber H  type
 397        5  H  1  URE    H12      5     0.395055   1.00800   ; amber H  type
 398        6  N  1  URE     N2      6    -0.923545  14.01000   ; amber N  type
 399        7  H  1  URE    H21      7     0.395055   1.00800   ; amber H  type
 400        8  H  1  URE    H22      8     0.395055   1.00800   ; amber H  type
 401
 402     [ bonds ]
 403         1       2
 404         1       3
 405         1   6
 406         3       4
 407         3       5
 408         6       7
 409         6       8
 410
 411     [ dihedrals ]
 412     ;   ai    aj    ak    al funct  definition
 413          2     1     3     4   9
 414          2     1     3     5   9
 415          2     1     6     7   9
 416          2     1     6     8   9
 417          3     1     6     7   9
 418          3     1     6     8   9
 419          6     1     3     4   9
 420          6     1     3     5   9
 421
 422     [ dihedrals ]
 423          3     6     1     2   4
 424          1     4     3     5   4
 425          1     7     6     8   4
 426
 427     [ position_restraints ]
 428     ; you wouldn't normally use this for a molecule like Urea,
 429     ; but we include it here for didactic purposes
 430     ; ai   funct    fc
 431        1     1     1000    1000    1000 ; Restrain to a point
 432        2     1     1000       0    1000 ; Restrain to a line (Y-axis)
 433        3     1     1000       0       0 ; Restrain to a plane (Y-Z-plane)
 434
 435     [ dihedral_restraints ]
 436     ; ai   aj    ak    al  type  phi  dphi  fc
 437         3    6     1    2     1  180     0  10
 438         1    4     3    5     1  180     0  10
 439
 440     ; Include TIP3P water topology
 441     #include "amber99/tip3p.itp"
 442
 443     [ system ]
 444     Urea in Water
 445
 446     [ molecules ]
 447     ;molecule name   nr.
 448     Urea             1
 449     SOL              1000
 450
 451 Here follows the explanatory text.
 452
 453 **#include “amber99.ff/forcefield.itp” :** this includes
 454 the information for the force field you are using, including bonded and
 455 non-bonded parameters. This example uses the AMBER99 force field, but
 456 your simulation may use a different force field. :ref:`grompp <gmx grompp>`
 457 will automatically go and find this file and copy-and-paste its content.
 458 That content can be seen in
 459 ``share/top/amber99.ff/forcefield.itp}``, and it
 460 is
 461
 462 ::
 463
 464     #define _FF_AMBER
 465     #define _FF_AMBER99
 466
 467     [ defaults ]
 468     ; nbfunc        comb-rule       gen-pairs       fudgeLJ fudgeQQ
 469     1               2               yes             0.5     0.8333
 470
 471     #include "ffnonbonded.itp"
 472     #include "ffbonded.itp"
 473
 474 The two ``#define`` statements set up the conditions so that
 475 future parts of the topology can know that the AMBER 99 force field is
 476 in use.
 477
 478 **[ defaults ] :**
 479
 480 -  ``nbfunc`` is the non-bonded function type. Use 1 (Lennard-Jones) or 2
 481    (Buckingham)
 482
 483 -  ``comb-rule`` is the number of the combination rule (see :ref:`nbpar`).
 484
 485 -  ``gen-pairs`` is for pair generation. The default is
 486    ‘no’, *i.e.* get 1-4 parameters from the pairtypes list. When
 487    parameters are not present in the list, stop with a fatal error.
 488    Setting ‘yes’ generates 1-4 parameters that are not present in the
 489    pair list from normal Lennard-Jones parameters using
 490    ``fudgeLJ``
 491
 492 -  ``fudgeLJ`` is the factor by which to multiply
 493    Lennard-Jones 1-4 interactions, default 1
 494
 495 -  ``fudgeQQ`` is the factor by which to multiply
 496    electrostatic 1-4 interactions, default 1
 497
 498 -  :math:`N` is the power for the repulsion term in a 6-\ :math:`N`
 499    potential (with nonbonded-type Lennard-Jones only), starting with
 500    |Gromacs| version 4.5, :ref:`grompp <gmx mdrun>` also reads and applies
 501    :math:`N`, for values not equal to 12 tabulated interaction functions
 502    are used (in older version you would have to use user tabulated
 503    interactions).
 504
 505 **Note** that ``gen-pairs``, ``fudgeLJ``,
 506 ``fudgeQQ``, and :math:`N` are optional.
 507 ``fudgeLJ`` is only used when generate pairs is set to
 508 ‘yes’, and ``fudgeQQ`` is always used. However, if you want
 509 to specify :math:`N` you need to give a value for the other parameters
 510 as well.
 511
 512 Then some other ``#include`` statements add in the large
 513 amount of data needed to describe the rest of the force field. We will
 514 skip these and return to ``urea.top``. There we will see
 515
 516 **[ moleculetype ] :** defines the name of your molecule
 517 in this :ref:`top` and nrexcl = 3 stands for excluding
 518 non-bonded interactions between atoms that are no further than 3 bonds
 519 away.
 520
 521 **[ atoms ] :** defines the molecule, where
 522 ``nr`` and ``type`` are fixed, the rest is user
 523 defined. So ``atom`` can be named as you like,
 524 ``cgnr`` made larger or smaller (if possible, the total
 525 charge of a charge group should be zero), and charges can be changed
 526 here too.
 527
 528 **[ bonds ] :** no comment.
 529
 530 **[ pairs ] :** LJ and Coulomb 1-4 interactions
 531
 532 **[ angles ] :** no comment
 533
 534 **[ dihedrals ] :** in this case there are 9 proper
 535 dihedrals (funct = 1), 3 improper (funct = 4) and no Ryckaert-Bellemans
 536 type dihedrals. If you want to include Ryckaert-Bellemans type dihedrals
 537 in a topology, do the following (in case of *e.g.* decane):
 538
 539 ::
 540
 541     [ dihedrals ]
 542     ;  ai    aj    ak    al funct       c0       c1       c2
 543         1    2     3     4     3
 544         2    3     4     5     3
 545
 546 In the original implementation of the potential for
 547 alkanes \ :ref:`131 <refRyckaert78>` no 1-4 interactions were used, which means that in
 548 order to implement that particular force field you need to remove the
 549 1-4 interactions from the ``[ pairs ]`` section of your
 550 topology. In most modern force fields, like OPLS/AA or Amber the rules
 551 are different, and the Ryckaert-Bellemans potential is used as a cosine
 552 series in combination with 1-4 interactions.
 553
 554 **[ position_restraints ] :** harmonically restrain the selected particles to reference
 555 positions (:ref:`positionrestraint`). The reference positions are read
 556 from a separate coordinate file by :ref:`grompp <gmx grompp>`.
 557
 558 **[ dihedral_restraints ] :** restrain selected dihedrals to a reference value. The
 559 implementation of dihedral restraints is described in section
 560 :ref:`dihedralrestraint` of the manual. The parameters specified in
 561 the ``[dihedral_restraints]`` directive are as follows:
 562
 563 -  ``type`` has only one possible value which is 1
 564
 565 -  ``phi`` is the value of :math:`\phi_0` in :eq:`eqn. %s <eqndphi>` and
 566    :eq:`eqn. %s <eqndihre>` of the manual.
 567
 568 -  ``dphi`` is the value of :math:`\Delta\phi` in :eq:`eqn. %s <eqndihre>` of the
 569    manual.
 570
 571 -  ``fc`` is the force constant :math:`k_{dihr}` in :eq:`eqn. %s <eqndihre>` of the
 572    manual.
 573
 574 **#include “tip3p.itp” :** includes a topology file that was already
 575 constructed (see section :ref:`molitp`).
 576
 577 **[ system ] :** title of your system, user-defined
 578
 579 **[ molecules ] :** this defines the total number of (sub)molecules in your system
 580 that are defined in this :ref:`top`. In this example file, it stands for 1
 581 urea molecule dissolved in 1000 water molecules. The molecule type ``SOL``
 582 is defined in the ``tip3p.itp`` file. Each name here must correspond to a
 583 name given with ``[ moleculetype ]`` earlier in the topology. The order of the blocks of
 584 molecule types and the numbers of such molecules must match the
 585 coordinate file that accompanies the topology when supplied to :ref:`grompp <gmx grompp>`.
 586 The blocks of molecules do not need to be contiguous, but some tools
 587 (e.g. :ref:`genion <gmx genion>`) may act only on the first or last such block of a
 588 particular molecule type. Also, these blocks have nothing to do with the
 589 definition of groups (see sec. :ref:`groupconcept` and
 590 sec. :ref:`usinggroups`).
 591
 592 .. _molitp:
 593
 594 Molecule.itp file
 595 ~~~~~~~~~~~~~~~~~
 596
 597 If you construct a topology file you will use frequently (like the water
 598 molecule, ``tip3p.itp``, which is already constructed for
 599 you) it is good to make a ``molecule.itp`` file. This only
 600 lists the information of one particular molecule and allows you to
 601 re-use the ``[ moleculetype ]`` in multiple systems without
 602 re-invoking :ref:`pdb2gmx <gmx pdb2gmx>` or manually copying and pasting. An
 603 example ``urea.itp`` follows:
 604
 605 ::
 606
 607     [ moleculetype ]
 608     ; molname   nrexcl
 609     URE         3
 610
 611     [ atoms ]
 612        1  C  1  URE      C      1     0.880229  12.01000   ; amber C  type
 613     ...
 614        8  H  1  URE    H22      8     0.395055   1.00800   ; amber H  type
 615
 616     [ bonds ]
 617         1       2
 618     ...
 619         6       8
 620     [ dihedrals ]
 621     ;   ai    aj    ak    al funct  definition
 622          2     1     3     4   9
 623     ...
 624          6     1     3     5   9
 625     [ dihedrals ]
 626          3     6     1     2   4
 627          1     4     3     5   4
 628          1     7     6     8   4
 629
 630 Using :ref:`itp` files results in a very short
 631 :ref:`top` file:
 632
 633 ::
 634
 635     ;
 636     ;       Example topology file
 637     ;
 638     ; The force field files to be included
 639     #include "amber99.ff/forcefield.itp"
 640
 641     #include "urea.itp"
 642
 643     ; Include TIP3P water topology
 644     #include "amber99/tip3p.itp"
 645
 646     [ system ]
 647     Urea in Water
 648
 649     [ molecules ]
 650     ;molecule name   nr.
 651     Urea             1
 652     SOL              1000
 653
 654 Ifdef statements
 655 ~~~~~~~~~~~~~~~~
 656
 657 A very powerful feature in |Gromacs| is the use of ``#ifdef``
 658 statements in your :ref:`top` file. By making use of this
 659 statement, and associated ``#define`` statements like were
 660 seen in ``amber99.ff/forcefield.itp`` earlier,
 661 different parameters for one molecule can be used in the same
 662 :ref:`top` file. An example is given for TFE, where there is
 663 an option to use different charges on the atoms: charges derived by De
 664 Loof et al. :ref:`132 <refLoof92>` or by Van Buuren and
 665 Berendsen \ :ref:`133 <refBuuren93a>`. In fact, you can use much of the
 666 functionality of the C preprocessor, ``cpp``, because
 667 :ref:`grompp <gmx grompp>` contains similar pre-processing functions to scan
 668 the file. The way to make use of the ``#ifdef`` option is as
 669 follows:
 670
 671 -  either use the option ``define = -DDeLoof`` in the
 672    :ref:`mdp` file (containing :ref:`grompp <gmx grompp>` input
 673    parameters), or use the line ``#define DeLoof`` early in
 674    your :ref:`top` or :ref:`itp` file; and
 675
 676 -  put the ``#ifdef`` statements in your
 677    :ref:`top`, as shown below:
 678
 679
 680 ::
 681
 682     ...
 683
 684
 685
 686     [ atoms ]
 687     ; nr     type     resnr    residu     atom      cgnr      charge        mass
 688     #ifdef DeLoof
 689     ; Use Charges from DeLoof
 690        1        C        1        TFE        C         1        0.74
 691        2        F        1        TFE        F         1       -0.25
 692        3        F        1        TFE        F         1       -0.25
 693        4        F        1        TFE        F         1       -0.25
 694        5      CH2        1        TFE      CH2         1        0.25
 695        6       OA        1        TFE       OA         1       -0.65
 696        7       HO        1        TFE       HO         1        0.41
 697     #else
 698     ; Use Charges from VanBuuren
 699        1        C        1        TFE        C         1        0.59
 700        2        F        1        TFE        F         1       -0.2
 701        3        F        1        TFE        F         1       -0.2
 702        4        F        1        TFE        F         1       -0.2
 703        5      CH2        1        TFE      CH2         1        0.26
 704        6       OA        1        TFE       OA         1       -0.55
 705        7       HO        1        TFE       HO         1        0.3
 706     #endif
 707
 708     [ bonds ]
 709     ;  ai    aj funct           c0           c1
 710         6     7     1 1.000000e-01 3.138000e+05
 711         1     2     1 1.360000e-01 4.184000e+05
 712         1     3     1 1.360000e-01 4.184000e+05
 713         1     4     1 1.360000e-01 4.184000e+05
 714         1     5     1 1.530000e-01 3.347000e+05
 715         5     6     1 1.430000e-01 3.347000e+05
 716     ...
 717
 718 This mechanism is used by :ref:`pdb2gmx <gmx pdb2gmx>` to implement optional position
 719 restraints (:ref:`positionrestraint`) by ``#include``-ing an :ref:`itp` file
 720 whose contents will be meaningful only if a particular ``#define`` is set
 721 (and spelled correctly!)
 722
 723 Topologies for free energy calculations
 724 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 725
 726 Free energy differences between two systems, A and B, can be calculated
 727 as described in sec. :ref:`fecalc`. Systems A and B are described by
 728 topologies consisting of the same number of molecules with the same
 729 number of atoms. Masses and non-bonded interactions can be perturbed by
 730 adding B parameters under the ``[ atoms ]`` directive. Bonded interactions can be
 731 perturbed by adding B parameters to the bonded types or the bonded
 732 interactions. The parameters that can be perturbed are listed in
 733 :numref:`Tables %s <tab-topfile1>` and :numref:`%s <tab-topfile2>`.
 734 The :math:`\lambda`-dependence of the
 735 interactions is described in section sec. :ref:`feia`. The bonded
 736 parameters that are used (on the line of the bonded interaction
 737 definition, or the ones looked up on atom types in the bonded type
 738 lists) is explained in :numref:`Table %s <tab-topfe>`. In most cases, things should
 739 work intuitively. When the A and B atom types in a bonded interaction
 740 are not all identical and parameters are not present for the B-state,
 741 either on the line or in the bonded types, :ref:`grompp <gmx grompp>` uses the A-state
 742 parameters and issues a warning. For free energy calculations, all or no
 743 parameters for topology B (:math:`\lambda = 1`) should be added on the
 744 same line, after the normal parameters, in the same order as the normal
 745 parameters. From |Gromacs| 4.6 onward, if :math:`\lambda` is treated as a
 746 vector, then the ``bonded-lambdas`` component controls all bonded terms that
 747 are not explicitly labeled as restraints. Restrain terms are controlled
 748 by the ``restraint-lambdas`` component.
 749
 750 .. |NOT| replace:: :math:`-`
 751
 752 .. _tab-topfe:
 753
 754 .. table:: The bonded parameters that are used for free energy topologies,
 755            on the line of the bonded interaction definition or looked up
 756            in the bond types section based on atom types. A and B indicate the
 757            parameters used for state A and B respectively, + and |NOT| indicate
 758            the (non-)presence of parameters in the topology, x indicates that
 759            the presence has no influence.
 760
 761            +--------------------+---------------+---------------------------------+---------+
 762            | B-state atom types | parameters    | parameters in bonded types      |         |
 763            +                    +               +-----------------+---------------+         +
 764            | all identical to   | on line       | A atom types    | B atom types  | message |
 765            +                    +-------+-------+-------+---------+-------+-------+         +
 766            | A-state atom types | A     | B     | A     | B       | A     | B     |         |
 767            +====================+=======+=======+=======+=========+=======+=======+=========+
 768            |                    | +AB   | |NOT| | x     | x       |       |       |         |
 769            |                    | +A    | +B    | x     | x       |       |       |         |
 770            | yes                | |NOT| | |NOT| | |NOT| | |NOT|   |       |       | error   |
 771            |                    | |NOT| | |NOT| | +AB   | |NOT|   |       |       |         |
 772            |                    | |NOT| | |NOT| | +A    | +B      |       |       |         |
 773            +--------------------+-------+-------+-------+---------+-------+-------+---------+
 774            |                    | +AB   | |NOT| | x     | x       | x     | x     | warning |
 775            |                    | +A    | +B    | x     | x       | x     | x     |         |
 776            |                    | |NOT| | |NOT| | |NOT| | |NOT|   | x     | x     | error   |
 777            | no                 | |NOT| | |NOT| | +AB   | |NOT|   | |NOT| | |NOT| | warning |
 778            |                    | |NOT| | |NOT| | +A    | +B      | |NOT| | |NOT| | warning |
 779            |                    | |NOT| | |NOT| | +A    | x       | +B    | |NOT| |         |
 780            |                    | |NOT| | |NOT| | +A    | x       | +     | +B    |         |
 781            +--------------------+-------+-------+-------+---------+-------+-------+---------+
 782
 783
 784
 785 Below is an example of a topology which changes from 200 propanols to
 786 200 pentanes using the GROMOS-96 force field.
 787
 788 ::
 789
 790
 791     ; Include force field parameters
 792     #include "gromos43a1.ff/forcefield.itp"
 793
 794     [ moleculetype ]
 795     ; Name            nrexcl
 796     PropPent          3
 797
 798     [ atoms ]
 799     ; nr type resnr residue atom cgnr  charge    mass  typeB chargeB  massB
 800       1    H    1     PROP    PH    1   0.398    1.008  CH3     0.0  15.035
 801       2   OA    1     PROP    PO    1  -0.548  15.9994  CH2     0.0  14.027
 802       3  CH2    1     PROP   PC1    1   0.150   14.027  CH2     0.0  14.027
 803       4  CH2    1     PROP   PC2    2   0.000   14.027
 804       5  CH3    1     PROP   PC3    2   0.000   15.035
 805
 806     [ bonds ]
 807     ;  ai    aj funct    par_A  par_B
 808         1     2     2    gb_1   gb_26
 809         2     3     2    gb_17  gb_26
 810         3     4     2    gb_26  gb_26
 811         4     5     2    gb_26
 812
 813     [ pairs ]
 814     ;  ai    aj funct
 815         1     4     1
 816         2     5     1
 817
 818     [ angles ]
 819     ;  ai    aj    ak funct    par_A   par_B
 820         1     2     3     2    ga_11   ga_14
 821         2     3     4     2    ga_14   ga_14
 822         3     4     5     2    ga_14   ga_14
 823
 824     [ dihedrals ]
 825     ;  ai    aj    ak    al funct    par_A   par_B
 826         1     2     3     4     1    gd_12   gd_17
 827         2     3     4     5     1    gd_17   gd_17
 828
 829     [ system ]
 830     ; Name
 831     Propanol to Pentane
 832
 833     [ molecules ]
 834     ; Compound        #mols
 835     PropPent          200
 836
 837 Atoms that are not perturbed, ``PC2`` and
 838 ``PC3``, do not need B-state parameter specifications, since
 839 the B parameters will be copied from the A parameters. Bonded
 840 interactions between atoms that are not perturbed do not need B
 841 parameter specifications, as is the case for the last bond in the
 842 example topology. Topologies using the OPLS/AA force field need no
 843 bonded parameters at all, since both the A and B parameters are
 844 determined by the atom types. Non-bonded interactions involving one or
 845 two perturbed atoms use the free-energy perturbation functional forms.
 846 Non-bonded interactions between two non-perturbed atoms use the normal
 847 functional forms. This means that when, for instance, only the charge of
 848 a particle is perturbed, its Lennard-Jones interactions will also be
 849 affected when lambda is not equal to zero or one.
 850
 851 **Note** that this topology uses the GROMOS-96 force field, in which the
 852 bonded interactions are not determined by the atom types. The bonded
 853 interaction strings are converted by the C-preprocessor. The force-field
 854 parameter files contain lines like:
 855
 856 ::
 857
 858     #define gb_26       0.1530  7.1500e+06
 859
 860     #define gd_17     0.000       5.86          3
 861
 862 .. _constraintforce:
 863
 864 Constraint forces
 865 ~~~~~~~~~~~~~~~~~
 866
 867 | The constraint force between two atoms in one molecule can be
 868   calculated with the free energy perturbation code by adding a
 869   constraint between the two atoms, with a different length in the A and
 870   B topology. When the B length is 1 nm longer than the A length and
 871   lambda is kept constant at zero, the derivative of the Hamiltonian
 872   with respect to lambda is the constraint force. For constraints
 873   between molecules, the pull code can be used, see sec. :ref:`pull`.
 874   Below is an example for calculating the constraint force at 0.7 nm
 875   between two methanes in water, by combining the two methanes into one
 876   “molecule.” **Note** that the definition of a “molecule” in |Gromacs|
 877   does not necessarily correspond to the chemical definition of a
 878   molecule. In |Gromacs|, a “molecule” can be defined as any group of
 879   atoms that one wishes to consider simultaneously. The added constraint
 880   is of function type 2, which means that it is not used for generating
 881   exclusions (see sec. :ref:`excl`). Note that the constraint free energy
 882   term is included in the derivative term, and is specifically included
 883   in the ``bonded-lambdas`` component. However, the free energy for changing
 884   constraints is *not* included in the potential energy differences used
 885   for BAR and MBAR, as this requires reevaluating the energy at each of
 886   the constraint components. This functionality is planned for later
 887   versions.
 888
 889 ::
 890
 891     ; Include force-field parameters
 892     #include "gromos43a1.ff/forcefield.itp"
 893
 894     [ moleculetype ]
 895     ; Name            nrexcl
 896     Methanes               1
 897
 898     [ atoms ]
 899     ; nr   type   resnr  residu   atom    cgnr     charge    mass
 900        1    CH4     1     CH4      C1       1          0    16.043
 901        2    CH4     1     CH4      C2       2          0    16.043
 902     [ constraints ]
 903     ;  ai    aj funct   length_A  length_B
 904         1     2     2        0.7       1.7
 905
 906     #include "gromos43a1.ff/spc.itp"
 907
 908     [ system ]
 909     ; Name
 910     Methanes in Water
 911
 912     [ molecules ]
 913     ; Compound        #mols
 914     Methanes              1
 915     SOL                2002
 916
 917 Coordinate file
 918 ~~~~~~~~~~~~~~~
 919
 920 Files with the :ref:`gro` file extension contain a molecular
 921 structure in GROMOS-87 format. A sample piece is included below:
 922
 923 ::
 924
 925     MD of 2 waters, reformat step, PA aug-91
 926         6
 927         1WATER  OW1    1   0.126   1.624   1.679  0.1227 -0.0580  0.0434
 928         1WATER  HW2    2   0.190   1.661   1.747  0.8085  0.3191 -0.7791
 929         1WATER  HW3    3   0.177   1.568   1.613 -0.9045 -2.6469  1.3180
 930         2WATER  OW1    4   1.275   0.053   0.622  0.2519  0.3140 -0.1734
 931         2WATER  HW2    5   1.337   0.002   0.680 -1.0641 -1.1349  0.0257
 932         2WATER  HW3    6   1.326   0.120   0.568  1.9427 -0.8216 -0.0244
 933        1.82060   1.82060   1.82060
 934
 935 This format is fixed, *i.e.* all columns are in a fixed position. If you
 936 want to read such a file in your own program without using the |Gromacs|
 937 libraries you can use the following formats:
 938
 939 **C-format:**
 940 ``“%5i%5s%5s%5i%8.3f%8.3f%8.3f%8.4f%8.4f%8.4f”``
 941
 942 Or to be more precise, with title *etc.* it looks like this:
 943
 944 ::
 945
 946       "%s\n", Title
 947       "%5d\n", natoms
 948       for (i=0; (i<natoms); i++) {
 949         "%5d%-5s%5s%5d%8.3f%8.3f%8.3f%8.4f%8.4f%8.4f\n",
 950           residuenr,residuename,atomname,atomnr,x,y,z,vx,vy,vz
 951       }
 952       "%10.5f%10.5f%10.5f%10.5f%10.5f%10.5f%10.5f%10.5f%10.5f\n",
 953         box[X][X],box[Y][Y],box[Z][Z],
 954         box[X][Y],box[X][Z],box[Y][X],box[Y][Z],box[Z][X],box[Z][Y]
 955
 956 **Fortran format:**
 957 ``(i5,2a5,i5,3f8.3,3f8.4)``
 958
 959 So ``confin.gro`` is the |Gromacs| coordinate file and is
 960 almost the same as the GROMOS-87 file (for GROMOS users: when used with
 961 ``ntx=7``). The only difference is the box for which |Gromacs|
 962 uses a tensor, not a vector.