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