docs/reference-manual/topologies/parameter-files.rst

   1 Parameter files
   2 ---------------
   3
   4 Atoms
   5 ~~~~~
   6
   7 The *static* properties (see  :numref:`Table %s <tab-statprop>`) assigned to the atom
   8 types are assigned based on data in several places. The mass is listed
   9 in ``atomtypes.atp`` (see :ref:`atomtype`), whereas the charge is listed
  10 in :ref:`rtp` (:ref:`rtp` = **r**\ esidue **t**\ opology **p**\ arameter file,
  11 see :ref:`rtp`). This implies that the charges are only defined in the
  12 building blocks of amino acids, nucleic acids or otherwise, as defined
  13 by the user. When generating a :ref:`topology <top>` using the :ref:`pdb2gmx <gmx pdb2gmx>`
  14 program, the information from these files is combined.
  15
  16 .. _tab-statprop:
  17
  18 .. table:: Static atom type properties in |Gromacs|
  19
  20            +----------+------------------+----------+
  21            | Property | Symbol           | Unit     |
  22            +==========+==================+==========+
  23            | Type     | -                | -        |
  24            +----------+------------------+----------+
  25            | Mass     | m                | a.m.u.   |
  26            +----------+------------------+----------+
  27            | Charge   | q                | electron |
  28            +----------+------------------+----------+
  29            | epsilon  | :math:`\epsilon` | kJ/mol   |
  30            +----------+------------------+----------+
  31            | sigma    | :math:`\sigma`   | nm       |
  32            +----------+------------------+----------+
  33
  34
  35 .. _nbpar:
  36
  37 Non-bonded parameters
  38 ~~~~~~~~~~~~~~~~~~~~~
  39
  40 The non-bonded parameters consist of the van der Waals parameters V (``c6``
  41 or :math:`\sigma`, depending on the combination rule) and W (``c12`` or
  42 :math:`\epsilon`), as listed in the file ``ffnonbonded.itp``, where ``ptype`` is
  43 the particle type (see :numref:`Table %s <tab-ptype>`). As with the bonded
  44 parameters, entries in ``[ *type ]`` directives are applied to their counterparts in
  45 the topology file. Missing parameters generate warnings, except as noted
  46 below in section :ref:`pairinteractions`.
  47
  48 ::
  49
  50     [ atomtypes ]
  51     ;name   at.num      mass      charge   ptype         V(c6)        W(c12)
  52         O        8  15.99940       0.000       A   0.22617E-02   0.74158E-06
  53        OM        8  15.99940       0.000       A   0.22617E-02   0.74158E-06
  54        .....
  55
  56     [ nonbond_params ]
  57       ; i    j func       V(c6)        W(c12)
  58         O    O    1 0.22617E-02   0.74158E-06
  59         O   OA    1 0.22617E-02   0.13807E-05
  60         .....
  61
  62 **Note** that most of the included force fields also include the ``at.num.``
  63 column, but this same information is implied in the OPLS-AA ``bond_type``
  64 column. The interpretation of the parameters V and W depends on the
  65 combination rule that was chosen in the ``[ defaults ]`` section of the topology file
  66 (see :ref:`topfile`):
  67
  68 .. math:: \begin{aligned}
  69           \mbox{for combination rule 1}: & &
  70           \begin{array}{llllll}
  71             \mbox{V}_{ii} & = & C^{(6)}_{i}  & = & 4\,\epsilon_i\sigma_i^{6} &
  72             \mbox{[ kJ mol$^{-1}$ nm$^{6}$ ]}\\
  73             \mbox{W}_{ii} & = & C^{(12)}_{i} & = & 4\,\epsilon_i\sigma_i^{12} &
  74             \mbox{[ kJ mol$^{-1}$ nm$^{12}$ ]}\\
  75           \end{array}
  76           \\
  77           \mbox{for combination rules 2 and 3}: & &
  78           \begin{array}{llll}
  79             \mbox{V}_{ii} & = & \sigma_i   & \mbox{[ nm ]} \\
  80             \mbox{W}_{ii} & = & \epsilon_i & \mbox{[ kJ mol$^{-1}$ ]}
  81           \end{array}\end{aligned}
  82           :label: eqndefcombrule
  83
  84 Some or all combinations for different atom types can be given in the
  85 ``[ nonbond_params ]`` section, again with parameters V and
  86 W as defined above. Any combination that is not given will be computed
  87 from the parameters for the corresponding atom types, according to the
  88 combination rule:
  89
  90 .. math:: \begin{aligned}
  91           \mbox{for combination rules 1 and 3}: & &
  92           \begin{array}{lll}
  93             C^{(6)}_{ij}  & = & \left(C^{(6)}_i\,C^{(6)}_j\right)^{\frac{1}{2}} \\
  94             C^{(12)}_{ij} & = & \left(C^{(12)}_i\,C^{(12)}_j\right)^{\frac{1}{2}}
  95           \end{array}
  96           \\
  97           \mbox{for combination rule 2}: & &
  98           \begin{array}{lll}
  99             \sigma_{ij}   & = & \frac{1}{2}(\sigma_i+\sigma_j) \\
 100             \epsilon_{ij} & = & \sqrt{\epsilon_i\,\epsilon_j}
 101           \end{array}\end{aligned}
 102           :label: eqngivencombrule
 103
 104 When :math:`\sigma` and :math:`\epsilon` need to be supplied (rules 2
 105 and 3), it would seem it is impossible to have a non-zero :math:`C^{12}`
 106 combined with a zero :math:`C^6` parameter. However, providing a
 107 negative :math:`\sigma` will do exactly that, such that :math:`C^6` is
 108 set to zero and :math:`C^{12}` is calculated normally. This situation
 109 represents a special case in reading the value of :math:`\sigma`, and
 110 nothing more.
 111
 112 There is only one set of combination rules for Buckingham potentials:
 113
 114 .. math:: \begin{array}{rcl}
 115           A_{ij}   &=& \left(A_{ii} \, A_{jj}\right)^{1/2}    \\
 116           B_{ij}   &=& 2 / \left(\frac{1}{B_{ii}} + \frac{1}{B_{jj}}\right)        \\
 117           C_{ij}   &=& \left(C_{ii} \, C_{jj}\right)^{1/2}
 118           \end{array}
 119           :label: eqnbuckinghamcombrule
 120
 121 Bonded parameters
 122 ~~~~~~~~~~~~~~~~~
 123
 124 The bonded
 125 parameters
 126 (*i.e.* bonds, bond angles, improper and proper dihedrals) are listed in
 127 ``ffbonded.itp``.  The entries in this database describe,
 128 respectively, the atom types in the interactions, the type of the
 129 interaction, and the parameters associated with that interaction. These
 130 parameters are then read by
 131 :ref:`grompp <gmx grompp>` when processing a
 132 topology and applied to the relevant bonded parameters, *i.e.*
 133 ``bondtypes`` are applied to entries in the
 134 ``[ bonds ]`` directive, etc. Any bonded parameter that is
 135 missing from the relevant :``[ *type ]`` directive generates
 136 a fatal error. The types of interactions are listed in
 137 :numref:`Table %s <tab-topfile2>`. Example excerpts from such files
 138 follow:
 139
 140 ::
 141
 142     [ bondtypes ]
 143       ; i    j func        b0          kb
 144         C    O    1   0.12300     502080.
 145         C   OM    1   0.12500     418400.
 146         ......
 147
 148     [ angletypes ]
 149       ; i    j    k func       th0         cth
 150        HO   OA    C    1   109.500     397.480
 151        HO   OA  CH1    1   109.500     397.480
 152        ......
 153
 154     [ dihedraltypes ]
 155       ; i    l func        q0          cq
 156      NR5*  NR5    2     0.000     167.360
 157      NR5* NR5*    2     0.000     167.360
 158      ......
 159
 160     [ dihedraltypes ]
 161       ; j    k func      phi0          cp   mult
 162         C   OA    1   180.000      16.736      2
 163         C    N    1   180.000      33.472      2
 164         ......
 165
 166     [ dihedraltypes ]
 167     ;
 168     ; Ryckaert-Bellemans Dihedrals
 169     ;
 170     ; aj    ak      funct
 171     CP2     CP2     3       9.2789  12.156  -13.120 -3.0597 26.240  -31.495
 172
 173 In the ``ffbonded.itp`` file, you can add bonded parameters.
 174 If you want to include parameters for new atom types, make sure you
 175 define them in ``atomtypes.atp`` as well.
 176
 177 For most interaction types, bonded parameters are searched and assigned
 178 using an exact match for all type names and allowing only a single set
 179 of parameters. The exception to this rule are
 180 dihedral
 181 parameters. For
 182 ``[ dihedraltypes ]`` wildcard atom type names can be
 183 specified with the letter ``X`` in one or more of the four
 184 positions. Thus one can for example assign proper dihedral parameters
 185 based on the types of the middle two atoms. The parameters for the entry
 186 with the most exact matches, i.e. the least wildcard matches, will be
 187 used. Note that |Gromacs| versions older than 5.1.3 used the first match,
 188 which means that a full match would be ignored if it is preceded by an
 189 entry that matches on wildcards. Thus it is suggested to put wildcard
 190 entries at the end, in case someone might use a forcefield with older
 191 versions of |Gromacs|. In addition there is a dihedral type 9 which adds
 192 the possibility of assigning multiple dihedral potentials, useful for
 193 combining terms with different multiplicities. The different dihedral
 194 potential parameter sets should be on directly adjacent lines in the
 195 ``[ dihedraltypes ]`` section.