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