docs/reference-manual/topologies/molecule-definition.rst

   1 Molecule definition
   2 -------------------
   3
   4 Moleculetype entries
   5 ~~~~~~~~~~~~~~~~~~~~
   6
   7 An organizational structure that usually corresponds to molecules is the
   8 ``[ moleculetype ]`` entry. This entry serves two main
   9 purposes. One is to give structure to the topology file(s), usually
  10 corresponding to real molecules. This makes the topology easier to read
  11 and writing it less labor intensive. A second purpose is computational
  12 efficiency. The system definition that is kept in memory is proportional
  13 in size of the ``moleculetype`` definitions. If a molecule
  14 is present in 100000 copies, this saves a factor of 100000 in memory,
  15 which means the system usually fits in cache, which can improve
  16 performance tremendously. Interactions that correspond to chemical
  17 bonds, that generate exclusions, can only be defined between atoms
  18 within a ``moleculetype``. It is allowed to have multiple
  19 molecules which are not covalently bonded in one
  20 ``moleculetype`` definition. Molecules can be made
  21 infinitely long by connecting to themselves over periodic boundaries.
  22 When such periodic molecules are present, an option in the
  23 :ref:`mdp` file needs to be set to tell |Gromacs| not to attempt
  24 to make molecules that are broken over periodic boundaries whole again.
  25
  26 Intermolecular interactions
  27 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  28
  29 In some cases, one would like atoms in different molecules to also
  30 interact with other interactions than the usual non-bonded interactions.
  31 This is often the case in binding studies. When the molecules are
  32 covalently bound, e.g. a ligand binding covalently to a protein, they
  33 are effectively one molecule and they should be defined in one
  34 ``[ moleculetype ]`` entry. Note that
  35 :ref:`pdb2gmx <gmx pdb2gmx>` has an option to put two or more molecules in
  36 one ``[ moleculetype ]`` entry. When molecules are not
  37 covalently bound, it is much more convenient to use separate
  38 ``moleculetype`` definitions and specify the intermolecular
  39 interactions in the ``[ intermolecular_interactions]``
  40 section. In this section, which is placed at the end of the topology
  41 (see :numref:`Table %s <tab-topfile1>`), normal bonded interactions
  42 can be specified using global atom indices. The only restrictions are
  43 that no interactions can be used that generates exclusions and no
  44 constraints can be used.
  45
  46 .. _pairinteractions:
  47
  48 Intramolecular pair interactions
  49 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  50
  51 Extra Lennard-Jones and electrostatic interactions between pairs of
  52 atoms in a molecule can be added in the ``[ pairs ]`` section of a molecule
  53 definition. The parameters for these interactions can be set
  54 independently from the non-bonded interaction parameters. In the GROMOS
  55 force fields, pairs are only used to modify the 1-4 interactions
  56 (interactions of atoms separated by three bonds). In these force fields
  57 the 1-4 interactions are excluded from the non-bonded interactions (see
  58 sec. :ref:`excl`).
  59
  60 ::
  61
  62
  63     [ pairtypes ]
  64       ; i    j func         cs6          cs12 ; THESE ARE 1-4 INTERACTIONS
  65         O    O    1 0.22617E-02   0.74158E-06
  66         O   OM    1 0.22617E-02   0.74158E-06
  67         .....
  68
  69 The pair interaction parameters for the atom types in ``ffnonbonded.itp``
  70 are listed in the ``[ pairtypes ]`` section. The GROMOS force fields list all these
  71 interaction parameters explicitly, but this section might be empty for
  72 force fields like OPLS that calculate the 1-4 interactions by uniformly
  73 scaling the parameters. Pair parameters that are not present in the ``[ pairtypes ]``
  74 section are only generated when ``gen-pairs`` is set to ``yes`` in the
  75 ``[ defaults ]`` directive of ``forcefield.itp`` (see :ref:`topfile`). When ``gen-pairs`` is
  76 set to ``no``, :ref:`grompp <gmx grompp>` will give a warning for each pair type for which no
  77 parameters are given.
  78
  79 The normal pair interactions, intended for 1-4 interactions, have
  80 function type 1. Function type 2 and the ``[ pairs_nb ]`` are intended for free-energy
  81 simulations. When determining hydration free energies, the solute needs
  82 to be decoupled from the solvent. This can be done by adding a B-state
  83 topology (see sec. :ref:`fecalc`) that uses zero for all solute
  84 non-bonded parameters, *i.e.* charges and LJ parameters. However, the
  85 free energy difference between the A and B states is not the total
  86 hydration free energy. One has to add the free energy for reintroducing
  87 the internal Coulomb and LJ interactions in the solute when in vacuum.
  88 This second step can be combined with the first step when the Coulomb
  89 and LJ interactions within the solute are not modified. For this
  90 purpose, there is a pairs function type 2, which is identical to
  91 function type 1, except that the B-state parameters are always identical
  92 to the A-state parameters. For searching the parameters in the ``[ pairtypes ]`` section,
  93 no distinction is made between function type 1 and 2. The pairs section
  94 ``[ pairs_nb ]`` is intended to replace the non-bonded interaction. It uses the unscaled
  95 charges and the non-bonded LJ parameters; it also only uses the A-state
  96 parameters. **Note** that one should add exclusions for all atom pairs
  97 listed in ``[ pairs_nb ]``, otherwise such pairs will also end up in the normal neighbor
  98 lists.
  99
 100 Alternatively, this same behavior can be achieved without ever touching
 101 the topology, by using the ``couple-moltype``, ``couple-lambda0``,
 102 ``couple-lambda1``, and ``couple-intramol`` keywords. See sections
 103 sec. :ref:`fecalc` and sec. :ref:`dgimplement` for more information.
 104
 105 All three pair types always use plain Coulomb interactions, even when
 106 Reaction-field, PME, Ewald or shifted Coulomb interactions are selected
 107 for the non-bonded interactions. Energies for types 1 and 2 are written
 108 to the energy and log file in separate “LJ-14” and “Coulomb-14” entries
 109 per energy group pair. Energies for ``[ pairs_nb ]`` are added to the “LJ-(SR)” and
 110 “Coulomb-(SR)” terms.
 111
 112 .. _excl:
 113
 114 Exclusions
 115 ~~~~~~~~~~
 116
 117 The exclusions for non-bonded interactions are generated by :ref:`grompp <gmx grompp>` for
 118 neighboring atoms up to a certain number of bonds away, as defined in
 119 the ``[ moleculetype ]`` section in the topology file (see :ref:`topfile`). Particles are
 120 considered bonded when they are connected by “chemical” bonds (``[ bonds ]`` types 1
 121 to 5, 7 or 8) or constraints (``[ constraints ]`` type 1). Type 5 ``[ bonds ]`` can be used to create a
 122 connection between two atoms without creating an interaction. There is a
 123 harmonic interaction (``[ bonds ]`` type 6) that does not connect the atoms by a
 124 chemical bond. There is also a second constraint type (``[ constraints ]`` type 2) that
 125 fixes the distance, but does not connect the atoms by a chemical bond.
 126 For a complete list of all these interactions, see :numref:`Table %s <tab-topfile2>`.
 127
 128 Extra exclusions within a molecule can be added manually in a
 129 ``[ exclusions ]`` section. Each line should start with one
 130 atom index, followed by one or more atom indices. All non-bonded
 131 interactions between the first atom and the other atoms will be
 132 excluded.
 133
 134 When all non-bonded interactions within or between groups of atoms need
 135 to be excluded, is it more convenient and much more efficient to use
 136 energy monitor group exclusions (see sec. :ref:`groupconcept`).