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>`.
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`
34 .. table:: The :ref:`topology <top>` file.
36 +------------------------------------------------------------------------------------------------------------+
38 +===================+===========================+=====+====+=================================================+
39 | interaction type | directive | # | f. | parameters |
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 +-------------------+---------------------------+-----+----+-------------------------------------------------+
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 +------------------------------------------------------------------------------------------------------------+
82 +-------------+---------------+------------------------------------+
84 +=============+===============+====================================+
85 | *mandatory* | ``system`` | system name |
86 +-------------+---------------+------------------------------------+
87 | *mandatory* | ``molecules`` | molecule name; number of molecules |
88 +-------------+---------------+------------------------------------+
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 +-----------------------------------------------------------------------------------+
101 - ``# at`` is the required number of atom type indices for this directive
103 - ``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
107 - |CRO| the combination rule determines the type of LJ parameters, see :ref:`nbpar`
109 - |STAR| for ``dihedraltypes`` one can specify 4 atoms or the inner (outer for improper) 2 atoms
111 - |NREX| exclude neighbors :math:`n_{ex}` bonds away for non-bonded interactions
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.
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}`
182 .. table:: Details of ``[ moleculetype ]`` directives
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 | |k_phi|, |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 +------------------------------------+----------------------------+------------+-----------+-------------------------------------------------------------------------+------------+
296 The required number of atom indices for this directive
299 The index to use to select this function type
302 Indicates which of the parameters can be interpolated in free energy calculations
305 This interaction type will be used by :ref:`grompp <gmx grompp>` for generating exclusions
308 This interaction type can be converted to constraints by :ref:`grompp <gmx grompp>`
311 The combination rule determines the type of LJ parameters, see :ref:`nbpar`
314 No connection, and so no exclusions, are generated for this interaction
316 Description of the file layout:
318 - Semicolon (;) and newline characters surround comments
320 - On a line ending with :math:`\backslash` the newline character is
323 - Directives are surrounded by ``[`` and ``]``
325 - The topology hierarchy (which must be followed) consists of three
328 - the parameter level, which defines certain force-field
329 specifications (see :numref:`Table %s <tab-topfile1>`)
331 - the molecule level, which should contain one or more molecule
332 definitions (see :numref:`Table %s <tab-topfile2>`)
334 - the system level, containing only system-specific information
335 (``[ system ]`` and ``[ molecules ]``)
337 - Items should be separated by spaces or tabs, not commas
339 - Atoms in molecules should be numbered consecutively starting at 1
341 - Atoms in the same charge group must be listed consecutively
343 - Bonded atom type name must contain at least one non-digit character.
345 - The file is parsed only once, which implies that no forward
346 references can be treated: items must be defined before they can be
349 - Exclusions can be generated from the bonds or overridden manually
351 - The bonded force types can be generated from the atom types or
354 - It is possible to apply multiple bonded interactions of the same type
357 - Descriptive comment lines and empty lines are highly recommended
359 - Starting with |Gromacs| version 3.1.3, all directives at the parameter
360 level can be used multiple times and there are no restrictions on the
361 order, except that an atom type needs to be defined before it can be
362 used in other parameter definitions
364 - If parameters for a certain interaction are defined multiple times
365 for the same combination of atom types the last definition is used;
366 starting with |Gromacs| version 3.1.3 :ref:`grompp <gmx grompp>` generates
367 a warning for parameter redefinitions with different values
369 - Using one of the ``[ atoms ]``,
370 ``[ bonds ]``, ``[ pairs ]``,
371 ``[ angles ]``, etc. without having used
372 ``[ moleculetype ]`` before is meaningless and generates
375 - Using ``[ molecules ]`` without having used
376 ``[ system ]`` before is meaningless and generates a
379 - After ``[ system ]`` the only allowed directive is
382 - Using an unknown string in ``[ ]`` causes all the data
383 until the next directive to be ignored and generates a warning
385 Here is an example of a topology file, ``urea.top``:
390 ; Example topology file
392 ; The force-field files to be included
393 #include "amber99.ff/forcefield.itp"
400 1 C 1 URE C 1 0.880229 12.01000 ; amber C type
401 2 O 1 URE O 2 -0.613359 16.00000 ; amber O type
402 3 N 1 URE N1 3 -0.923545 14.01000 ; amber N type
403 4 H 1 URE H11 4 0.395055 1.00800 ; amber H type
404 5 H 1 URE H12 5 0.395055 1.00800 ; amber H type
405 6 N 1 URE N2 6 -0.923545 14.01000 ; amber N type
406 7 H 1 URE H21 7 0.395055 1.00800 ; amber H type
407 8 H 1 URE H22 8 0.395055 1.00800 ; amber H type
419 ; ai aj ak al funct definition
434 [ position_restraints ]
435 ; you wouldn't normally use this for a molecule like Urea,
436 ; but we include it here for didactic purposes
438 1 1 1000 1000 1000 ; Restrain to a point
439 2 1 1000 0 1000 ; Restrain to a line (Y-axis)
440 3 1 1000 0 0 ; Restrain to a plane (Y-Z-plane)
442 [ dihedral_restraints ]
443 ; ai aj ak al type phi dphi fc
447 ; Include TIP3P water topology
448 #include "amber99.ff/tip3p.itp"
458 Here follows the explanatory text.
460 **#include “amber99.ff/forcefield.itp” :** this includes
461 the information for the force field you are using, including bonded and
462 non-bonded parameters. This example uses the AMBER99 force field, but
463 your simulation may use a different force field. :ref:`grompp <gmx grompp>`
464 will automatically go and find this file and copy-and-paste its content.
465 That content can be seen in
466 ``share/top/amber99.ff/forcefield.itp}``, and it
475 ; nbfunc comb-rule gen-pairs fudgeLJ fudgeQQ
478 #include "ffnonbonded.itp"
479 #include "ffbonded.itp"
481 The two ``#define`` statements set up the conditions so that
482 future parts of the topology can know that the AMBER 99 force field is
487 - ``nbfunc`` is the non-bonded function type. Use 1 (Lennard-Jones) or 2
490 - ``comb-rule`` is the number of the combination rule (see :ref:`nbpar`).
492 - ``gen-pairs`` is for pair generation. The default is
493 ‘no’, *i.e.* get 1-4 parameters from the pairtypes list. When
494 parameters are not present in the list, stop with a fatal error.
495 Setting ‘yes’ generates 1-4 parameters that are not present in the
496 pair list from normal Lennard-Jones parameters using
499 - ``fudgeLJ`` is the factor by which to multiply
500 Lennard-Jones 1-4 interactions, default 1
502 - ``fudgeQQ`` is the factor by which to multiply
503 electrostatic 1-4 interactions, default 1
505 - :math:`N` is the power for the repulsion term in a 6-\ :math:`N`
506 potential (with nonbonded-type Lennard-Jones only), starting with
507 |Gromacs| version 4.5, :ref:`grompp <gmx mdrun>` also reads and applies
508 :math:`N`, for values not equal to 12 tabulated interaction functions
509 are used (in older version you would have to use user tabulated
512 **Note** that ``gen-pairs``, ``fudgeLJ``,
513 ``fudgeQQ``, and :math:`N` are optional.
514 ``fudgeLJ`` is only used when generate pairs is set to
515 ‘yes’, and ``fudgeQQ`` is always used. However, if you want
516 to specify :math:`N` you need to give a value for the other parameters
519 Then some other ``#include`` statements add in the large
520 amount of data needed to describe the rest of the force field. We will
521 skip these and return to ``urea.top``. There we will see
523 **[ moleculetype ] :** defines the name of your molecule
524 in this :ref:`top` and nrexcl = 3 stands for excluding
525 non-bonded interactions between atoms that are no further than 3 bonds
528 **[ atoms ] :** defines the molecule, where
529 ``nr`` and ``type`` are fixed, the rest is user
530 defined. So ``atom`` can be named as you like,
531 ``cgnr`` made larger or smaller (if possible, the total
532 charge of a charge group should be zero), and charges can be changed
535 **[ bonds ] :** no comment.
537 **[ pairs ] :** LJ and Coulomb 1-4 interactions
539 **[ angles ] :** no comment
541 **[ dihedrals ] :** in this case there are 9 proper
542 dihedrals (funct = 1), 3 improper (funct = 4) and no Ryckaert-Bellemans
543 type dihedrals. If you want to include Ryckaert-Bellemans type dihedrals
544 in a topology, do the following (in case of *e.g.* decane):
549 ; ai aj ak al funct c0 c1 c2
553 In the original implementation of the potential for
554 alkanes \ :ref:`131 <refRyckaert78>` no 1-4 interactions were used, which means that in
555 order to implement that particular force field you need to remove the
556 1-4 interactions from the ``[ pairs ]`` section of your
557 topology. In most modern force fields, like OPLS/AA or Amber the rules
558 are different, and the Ryckaert-Bellemans potential is used as a cosine
559 series in combination with 1-4 interactions.
561 **[ position_restraints ] :** harmonically restrain the selected particles to reference
562 positions (:ref:`positionrestraint`). The reference positions are read
563 from a separate coordinate file by :ref:`grompp <gmx grompp>`.
565 **[ dihedral_restraints ] :** restrain selected dihedrals to a reference value. The
566 implementation of dihedral restraints is described in section
567 :ref:`dihedralrestraint` of the manual. The parameters specified in
568 the ``[dihedral_restraints]`` directive are as follows:
570 - ``type`` has only one possible value which is 1
572 - ``phi`` is the value of :math:`\phi_0` in :eq:`eqn. %s <eqndphi>` and
573 :eq:`eqn. %s <eqndihre>` of the manual.
575 - ``dphi`` is the value of :math:`\Delta\phi` in :eq:`eqn. %s <eqndihre>` of the
578 - ``fc`` is the force constant :math:`k_{dihr}` in :eq:`eqn. %s <eqndihre>` of the
581 **#include “tip3p.itp” :** includes a topology file that was already
582 constructed (see section :ref:`molitp`).
584 **[ system ] :** title of your system, user-defined
586 **[ molecules ] :** this defines the total number of (sub)molecules in your system
587 that are defined in this :ref:`top`. In this example file, it stands for 1
588 urea molecule dissolved in 1000 water molecules. The molecule type ``SOL``
589 is defined in the ``tip3p.itp`` file. Each name here must correspond to a
590 name given with ``[ moleculetype ]`` earlier in the topology. The order of the blocks of
591 molecule types and the numbers of such molecules must match the
592 coordinate file that accompanies the topology when supplied to :ref:`grompp <gmx grompp>`.
593 The blocks of molecules do not need to be contiguous, but some tools
594 (e.g. :ref:`genion <gmx genion>`) may act only on the first or last such block of a
595 particular molecule type. Also, these blocks have nothing to do with the
596 definition of groups (see sec. :ref:`groupconcept` and
597 sec. :ref:`usinggroups`).
604 If you construct a topology file you will use frequently (like the water
605 molecule, ``tip3p.itp``, which is already constructed for
606 you) it is good to make a ``molecule.itp`` file. This only
607 lists the information of one particular molecule and allows you to
608 re-use the ``[ moleculetype ]`` in multiple systems without
609 re-invoking :ref:`pdb2gmx <gmx pdb2gmx>` or manually copying and pasting. An
610 example ``urea.itp`` follows:
619 1 C 1 URE C 1 0.880229 12.01000 ; amber C type
621 8 H 1 URE H22 8 0.395055 1.00800 ; amber H type
628 ; ai aj ak al funct definition
637 Using :ref:`itp` files results in a very short
643 ; Example topology file
645 ; The force field files to be included
646 #include "amber99.ff/forcefield.itp"
650 ; Include TIP3P water topology
651 #include "amber99/tip3p.itp"
664 A very powerful feature in |Gromacs| is the use of ``#ifdef``
665 statements in your :ref:`top` file. By making use of this
666 statement, and associated ``#define`` statements like were
667 seen in ``amber99.ff/forcefield.itp`` earlier,
668 different parameters for one molecule can be used in the same
669 :ref:`top` file. An example is given for TFE, where there is
670 an option to use different charges on the atoms: charges derived by De
671 Loof et al. :ref:`132 <refLoof92>` or by Van Buuren and
672 Berendsen \ :ref:`133 <refBuuren93a>`. In fact, you can use much of the
673 functionality of the C preprocessor, ``cpp``, because
674 :ref:`grompp <gmx grompp>` contains similar pre-processing functions to scan
675 the file. The way to make use of the ``#ifdef`` option is as
678 - either use the option ``define = -DDeLoof`` in the
679 :ref:`mdp` file (containing :ref:`grompp <gmx grompp>` input
680 parameters), or use the line ``#define DeLoof`` early in
681 your :ref:`top` or :ref:`itp` file; and
683 - put the ``#ifdef`` statements in your
684 :ref:`top`, as shown below:
694 ; nr type resnr residu atom cgnr charge mass
696 ; Use Charges from DeLoof
701 5 CH2 1 TFE CH2 1 0.25
702 6 OA 1 TFE OA 1 -0.65
705 ; Use Charges from VanBuuren
710 5 CH2 1 TFE CH2 1 0.26
711 6 OA 1 TFE OA 1 -0.55
717 6 7 1 1.000000e-01 3.138000e+05
718 1 2 1 1.360000e-01 4.184000e+05
719 1 3 1 1.360000e-01 4.184000e+05
720 1 4 1 1.360000e-01 4.184000e+05
721 1 5 1 1.530000e-01 3.347000e+05
722 5 6 1 1.430000e-01 3.347000e+05
725 This mechanism is used by :ref:`pdb2gmx <gmx pdb2gmx>` to implement optional position
726 restraints (:ref:`positionrestraint`) by ``#include``-ing an :ref:`itp` file
727 whose contents will be meaningful only if a particular ``#define`` is set
728 (and spelled correctly!)
730 Topologies for free energy calculations
731 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
733 Free energy differences between two systems, A and B, can be calculated
734 as described in sec. :ref:`fecalc`. Systems A and B are described by
735 topologies consisting of the same number of molecules with the same
736 number of atoms. Masses and non-bonded interactions can be perturbed by
737 adding B parameters under the ``[ atoms ]`` directive. Bonded interactions can be
738 perturbed by adding B parameters to the bonded types or the bonded
739 interactions. The parameters that can be perturbed are listed in
740 :numref:`Tables %s <tab-topfile1>` and :numref:`%s <tab-topfile2>`.
741 The :math:`\lambda`-dependence of the
742 interactions is described in section sec. :ref:`feia`. The bonded
743 parameters that are used (on the line of the bonded interaction
744 definition, or the ones looked up on atom types in the bonded type
745 lists) is explained in :numref:`Table %s <tab-topfe>`. In most cases, things should
746 work intuitively. When the A and B atom types in a bonded interaction
747 are not all identical and parameters are not present for the B-state,
748 either on the line or in the bonded types, :ref:`grompp <gmx grompp>` uses the A-state
749 parameters and issues a warning. For free energy calculations, all or no
750 parameters for topology B (:math:`\lambda = 1`) should be added on the
751 same line, after the normal parameters, in the same order as the normal
752 parameters. From |Gromacs| 4.6 onward, if :math:`\lambda` is treated as a
753 vector, then the ``bonded-lambdas`` component controls all bonded terms that
754 are not explicitly labeled as restraints. Restrain terms are controlled
755 by the ``restraint-lambdas`` component.
757 .. |NOT| replace:: :math:`-`
761 .. table:: The bonded parameters that are used for free energy topologies,
762 on the line of the bonded interaction definition or looked up
763 in the bond types section based on atom types. A and B indicate the
764 parameters used for state A and B respectively, + and |NOT| indicate
765 the (non-)presence of parameters in the topology, x indicates that
766 the presence has no influence.
768 +--------------------+---------------+-----------------------------------+---------+
769 | B-state atom types | parameters | parameters in | parameters in | |
770 | | | bonded types | bonded types | expected|
771 | all identical to | on line | of A atoms | of B atoms | message |
772 | +-------+-------+-------+---------+-------+---------+ |
773 | A-state atom types | A | B | A | B | A | B | |
774 +====================+=======+=======+=======+=========+=======+=========+=========+
775 | yes | +AB | |NOT| | x | x | | | |
776 +--------------------+-------+-------+-------+---------+-------+---------+---------+
777 | yes | +A | +B | x | x | | | |
778 +--------------------+-------+-------+-------+---------+-------+---------+---------+
779 | yes | |NOT| | |NOT| | |NOT| | |NOT| | | | error |
780 +--------------------+-------+-------+-------+---------+-------+---------+---------+
781 | yes | |NOT| | |NOT| | +AB | |NOT| | | | |
782 +--------------------+-------+-------+-------+---------+-------+---------+---------+
783 | yes | |NOT| | |NOT| | +A | +B | | | |
784 +--------------------+-------+-------+-------+---------+-------+---------+---------+
785 | no | +AB | |NOT| | x | x | x | x | warning |
786 +--------------------+-------+-------+-------+---------+-------+---------+---------+
787 | no | +A | +B | x | x | x | x | |
788 +--------------------+-------+-------+-------+---------+-------+---------+---------+
789 | no | |NOT| | |NOT| | |NOT| | |NOT| | x | x | error |
790 +--------------------+-------+-------+-------+---------+-------+---------+---------+
791 | no | |NOT| | |NOT| | +AB | |NOT| | |NOT| | |NOT| | warning |
792 +--------------------+-------+-------+-------+---------+-------+---------+---------+
793 | no | |NOT| | |NOT| | +A | +B | |NOT| | |NOT| | warning |
794 +--------------------+-------+-------+-------+---------+-------+---------+---------+
795 | no | |NOT| | |NOT| | +A | x | +B | |NOT| | |
796 +--------------------+-------+-------+-------+---------+-------+---------+---------+
797 | no | |NOT| | |NOT| | +A | x | + | +B | |
798 +--------------------+-------+-------+-------+---------+-------+---------+---------+
802 Below is an example of a topology which changes from 200 propanols to
803 200 pentanes using the GROMOS-96 force field.
808 ; Include force field parameters
809 #include "gromos43a1.ff/forcefield.itp"
816 ; nr type resnr residue atom cgnr charge mass typeB chargeB massB
817 1 H 1 PROP PH 1 0.398 1.008 CH3 0.0 15.035
818 2 OA 1 PROP PO 1 -0.548 15.9994 CH2 0.0 14.027
819 3 CH2 1 PROP PC1 1 0.150 14.027 CH2 0.0 14.027
820 4 CH2 1 PROP PC2 2 0.000 14.027
821 5 CH3 1 PROP PC3 2 0.000 15.035
824 ; ai aj funct par_A par_B
836 ; ai aj ak funct par_A par_B
842 ; ai aj ak al funct par_A par_B
843 1 2 3 4 1 gd_12 gd_17
844 2 3 4 5 1 gd_17 gd_17
854 Atoms that are not perturbed, ``PC2`` and
855 ``PC3``, do not need B-state parameter specifications, since
856 the B parameters will be copied from the A parameters. Bonded
857 interactions between atoms that are not perturbed do not need B
858 parameter specifications, as is the case for the last bond in the
859 example topology. Topologies using the OPLS/AA force field need no
860 bonded parameters at all, since both the A and B parameters are
861 determined by the atom types. Non-bonded interactions involving one or
862 two perturbed atoms use the free-energy perturbation functional forms.
863 Non-bonded interactions between two non-perturbed atoms use the normal
864 functional forms. This means that when, for instance, only the charge of
865 a particle is perturbed, its Lennard-Jones interactions will also be
866 affected when lambda is not equal to zero or one.
868 **Note** that this topology uses the GROMOS-96 force field, in which the
869 bonded interactions are not determined by the atom types. The bonded
870 interaction strings are converted by the C-preprocessor. The force-field
871 parameter files contain lines like:
875 #define gb_26 0.1530 7.1500e+06
877 #define gd_17 0.000 5.86 3
884 | The constraint force between two atoms in one molecule can be
885 calculated with the free energy perturbation code by adding a
886 constraint between the two atoms, with a different length in the A and
887 B topology. When the B length is 1 nm longer than the A length and
888 lambda is kept constant at zero, the derivative of the Hamiltonian
889 with respect to lambda is the constraint force. For constraints
890 between molecules, the pull code can be used, see sec. :ref:`pull`.
891 Below is an example for calculating the constraint force at 0.7 nm
892 between two methanes in water, by combining the two methanes into one
893 “molecule.” **Note** that the definition of a “molecule” in |Gromacs|
894 does not necessarily correspond to the chemical definition of a
895 molecule. In |Gromacs|, a “molecule” can be defined as any group of
896 atoms that one wishes to consider simultaneously. The added constraint
897 is of function type 2, which means that it is not used for generating
898 exclusions (see sec. :ref:`excl`). Note that the constraint free energy
899 term is included in the derivative term, and is specifically included
900 in the ``bonded-lambdas`` component. However, the free energy for changing
901 constraints is *not* included in the potential energy differences used
902 for BAR and MBAR, as this requires reevaluating the energy at each of
903 the constraint components. This functionality is planned for later
908 ; Include force-field parameters
909 #include "gromos43a1.ff/forcefield.itp"
916 ; nr type resnr residu atom cgnr charge mass
917 1 CH4 1 CH4 C1 1 0 16.043
918 2 CH4 1 CH4 C2 2 0 16.043
920 ; ai aj funct length_A length_B
923 #include "gromos43a1.ff/spc.itp"
937 Files with the :ref:`gro` file extension contain a molecular
938 structure in GROMOS-87 format. A sample piece is included below:
942 MD of 2 waters, reformat step, PA aug-91
944 1WATER OW1 1 0.126 1.624 1.679 0.1227 -0.0580 0.0434
945 1WATER HW2 2 0.190 1.661 1.747 0.8085 0.3191 -0.7791
946 1WATER HW3 3 0.177 1.568 1.613 -0.9045 -2.6469 1.3180
947 2WATER OW1 4 1.275 0.053 0.622 0.2519 0.3140 -0.1734
948 2WATER HW2 5 1.337 0.002 0.680 -1.0641 -1.1349 0.0257
949 2WATER HW3 6 1.326 0.120 0.568 1.9427 -0.8216 -0.0244
950 1.82060 1.82060 1.82060
952 This format is fixed, *i.e.* all columns are in a fixed position. If you
953 want to read such a file in your own program without using the |Gromacs|
954 libraries you can use the following formats:
957 ``“%5i%5s%5s%5i%8.3f%8.3f%8.3f%8.4f%8.4f%8.4f”``
959 Or to be more precise, with title *etc.* it looks like this:
965 for (i=0; (i<natoms); i++) {
966 "%5d%-5s%5s%5d%8.3f%8.3f%8.3f%8.4f%8.4f%8.4f\n",
967 residuenr,residuename,atomname,atomnr,x,y,z,vx,vy,vz
969 "%10.5f%10.5f%10.5f%10.5f%10.5f%10.5f%10.5f%10.5f%10.5f\n",
970 box[X][X],box[Y][Y],box[Z][Z],
971 box[X][Y],box[X][Z],box[Y][X],box[Y][Z],box[Z][X],box[Z][Y]
974 ``(i5,2a5,i5,3f8.3,3f8.4)``
976 So ``confin.gro`` is the |Gromacs| coordinate file and is
977 almost the same as the GROMOS-87 file (for GROMOS users: when used with
978 ``ntx=7``). The only difference is the box for which |Gromacs|
979 uses a tensor, not a vector.