docs/reference-manual/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::
  69
  70    \begin{aligned}
  71    \mbox{for combination rule 1}: & &
  72    \begin{array}{llllll}
  73      \mbox{V}_{ii} & = & C^{(6)}_{i}  & = & 4\,\epsilon_i\sigma_i^{6} &
  74      \mbox{[ kJ mol$^{-1}$ nm$^{6}$ ]}\\
  75      \mbox{W}_{ii} & = & C^{(12)}_{i} & = & 4\,\epsilon_i\sigma_i^{12} &
  76      \mbox{[ kJ mol$^{-1}$ nm$^{12}$ ]}\\
  77    \end{array}
  78    \\
  79    \mbox{for combination rules 2 and 3}: & &
  80    \begin{array}{llll}
  81      \mbox{V}_{ii} & = & \sigma_i   & \mbox{[ nm ]} \\
  82      \mbox{W}_{ii} & = & \epsilon_i & \mbox{[ kJ mol$^{-1}$ ]}
  83    \end{array}\end{aligned}
  84
  85 Some or all combinations for different atom types can be given in the
  86 ``[ nonbond_params ]`` section, again with parameters V and
  87 W as defined above. Any combination that is not given will be computed
  88 from the parameters for the corresponding atom types, according to the
  89 combination rule:
  90
  91 .. math::
  92
  93    \begin{aligned}
  94    \mbox{for combination rules 1 and 3}: & &
  95    \begin{array}{lll}
  96      C^{(6)}_{ij}  & = & \left(C^{(6)}_i\,C^{(6)}_j\right)^{\frac{1}{2}} \\
  97      C^{(12)}_{ij} & = & \left(C^{(12)}_i\,C^{(12)}_j\right)^{\frac{1}{2}}
  98    \end{array}
  99    \\
 100    \mbox{for combination rule 2}: & &
 101    \begin{array}{lll}
 102      \sigma_{ij}   & = & \frac{1}{2}(\sigma_i+\sigma_j) \\
 103      \epsilon_{ij} & = & \sqrt{\epsilon_i\,\epsilon_j}
 104    \end{array}\end{aligned}
 105
 106 When :math:`\sigma` and :math:`\epsilon` need to be supplied (rules 2
 107 and 3), it would seem it is impossible to have a non-zero :math:`C^{12}`
 108 combined with a zero :math:`C^6` parameter. However, providing a
 109 negative :math:`\sigma` will do exactly that, such that :math:`C^6` is
 110 set to zero and :math:`C^{12}` is calculated normally. This situation
 111 represents a special case in reading the value of :math:`\sigma`, and
 112 nothing more.
 113
 114 There is only one set of combination rules for Buckingham potentials:
 115
 116 .. math::
 117
 118    \begin{array}{rcl}
 119    A_{ij}   &=& \left(A_{ii} \, A_{jj}\right)^{1/2}    \\
 120    B_{ij}   &=& 2 / \left(\frac{1}{B_{ii}} + \frac{1}{B_{jj}}\right)        \\
 121    C_{ij}   &=& \left(C_{ii} \, C_{jj}\right)^{1/2}
 122    \end{array}
 123
 124 Bonded parameters
 125 ~~~~~~~~~~~~~~~~~
 126
 127 The bonded
 128 parameters
 129 (*i.e.* bonds, bond angles, improper and proper dihedrals) are listed in
 130 ``ffbonded.itp``.  The entries in this database describe,
 131 respectively, the atom types in the interactions, the type of the
 132 interaction, and the parameters associated with that interaction. These
 133 parameters are then read by
 134 :ref:`grompp <gmx grompp>` when processing a
 135 topology and applied to the relevant bonded parameters, *i.e.*
 136 ``bondtypes`` are applied to entries in the
 137 ``[ bonds ]`` directive, etc. Any bonded parameter that is
 138 missing from the relevant :``[ *type ]`` directive generates
 139 a fatal error. The types of interactions are listed in
 140 :numref:`Table %s <tab-topfile2>`. Example excerpts from such files
 141 follow:
 142
 143 ::
 144
 145     [ bondtypes ]
 146       ; i    j func        b0          kb
 147         C    O    1   0.12300     502080.
 148         C   OM    1   0.12500     418400.
 149         ......
 150
 151     [ angletypes ]
 152       ; i    j    k func       th0         cth
 153        HO   OA    C    1   109.500     397.480
 154        HO   OA  CH1    1   109.500     397.480
 155        ......
 156
 157     [ dihedraltypes ]
 158       ; i    l func        q0          cq
 159      NR5*  NR5    2     0.000     167.360
 160      NR5* NR5*    2     0.000     167.360
 161      ......
 162
 163     [ dihedraltypes ]
 164       ; j    k func      phi0          cp   mult
 165         C   OA    1   180.000      16.736      2
 166         C    N    1   180.000      33.472      2
 167         ......
 168
 169     [ dihedraltypes ]
 170     ;
 171     ; Ryckaert-Bellemans Dihedrals
 172     ;
 173     ; aj    ak      funct
 174     CP2     CP2     3       9.2789  12.156  -13.120 -3.0597 26.240  -31.495
 175
 176 In the ``ffbonded.itp`` file, you can add bonded parameters.
 177 If you want to include parameters for new atom types, make sure you
 178 define them in ``atomtypes.atp`` as well.
 179
 180 For most interaction types, bonded parameters are searched and assigned
 181 using an exact match for all type names and allowing only a single set
 182 of parameters. The exception to this rule are
 183 dihedral
 184 parameters. For
 185 ``[ dihedraltypes ]`` wildcard atom type names can be
 186 specified with the letter ``X`` in one or more of the four
 187 positions. Thus one can for example assign proper dihedral parameters
 188 based on the types of the middle two atoms. The parameters for the entry
 189 with the most exact matches, i.e. the least wildcard matches, will be
 190 used. Note that |Gromacs| versions older than 5.1.3 used the first match,
 191 which means that a full match would be ignored if it is preceded by an
 192 entry that matches on wildcards. Thus it is suggested to put wildcard
 193 entries at the end, in case someone might use a forcefield with older
 194 versions of |Gromacs|. In addition there is a dihedral type 9 which adds
 195 the possibility of assigning multiple dihedral potentials, useful for
 196 combining terms with different multiplicities. The different dihedral
 197 potential parameter sets should be on directly adjacent lines in the
 198 ``[ dihedraltypes ]`` section.