docs/reference-manual/file-formats.rst

   1 File formats
   2 ============
   3
   4 .. TODO in future patch: update for accuracy, organize better, improve formatting
   5
   6 Summary of file formats
   7 ^^^^^^^^^^^^^^^^^^^^^^^
   8
   9 Parameter files
  10 ---------------
  11
  12 :ref:`mdp`
  13     run parameters, input for :ref:`gmx grompp` and :ref:`gmx convert-tpr`
  14
  15 :ref:`m2p`
  16     input for :ref:`gmx xpm2ps`
  17
  18 .. _gmx-structure-files:
  19
  20 Structure files
  21 ---------------
  22
  23 :ref:`gro`
  24     |Gromacs| format
  25 :ref:`g96`
  26     GROMOS-96 format
  27 :ref:`pdb`
  28     brookhaven Protein DataBank format
  29 **Structure+mass(db):** :ref:`tpr`, :ref:`gro`, :ref:`g96`, or :ref:`pdb`
  30     Structure and mass input for analysis tools.
  31     When gro or pdb is used approximate masses will be read from the mass database.
  32
  33 Topology files
  34 --------------
  35
  36 :ref:`top`
  37     system topology (ascii)
  38 :ref:`itp`
  39     include topology (ascii)
  40 :ref:`rtp`
  41     residue topology (ascii)
  42 :ref:`ndx`
  43     index file (ascii)
  44 :ref:`n2t`
  45     atom naming definition (ascii)
  46 :ref:`atp`
  47     atom type library (ascii)
  48 :ref:`r2b`
  49     residue to building block mapping (ascii)
  50 :ref:`arn`
  51     atom renaming database (ascii)
  52 :ref:`hdb`
  53     hydrogen atom database (ascii)
  54 :ref:`vsd`
  55     virtual site database (ascii)
  56 :ref:`tdb`
  57     termini database (ascii)
  58
  59
  60 Run Input files
  61 ---------------
  62
  63 :ref:`tpr`
  64     system topology, parameters, coordinates and velocities (binary, portable)
  65
  66 Trajectory files
  67 ----------------
  68
  69 :ref:`tng`
  70     Any kind of data (compressed, portable, any precision)
  71 :ref:`trr`
  72     x, v and f (binary, full precision, portable)
  73 :ref:`xtc`
  74     x only (compressed, portable, any precision)
  75 :ref:`gro`
  76     x and v (ascii, any precision)
  77 :ref:`g96`
  78     x only (ascii, fixed high precision)
  79 :ref:`pdb`
  80     x only (ascii, reduced precision)
  81 **Formats for full-precision data:**
  82     :ref:`tng` or :ref:`trr`
  83 **Generic trajectory formats:**
  84     :ref:`tng`, :ref:`xtc`, :ref:`trr`, :ref:`gro`, :ref:`g96`, or :ref:`pdb`
  85
  86 Energy files
  87 ------------
  88
  89 :ref:`ene`
  90     energies, temperature, pressure, box size, density and virials (binary)
  91 :ref:`edr`
  92     energies, temperature, pressure, box size, density and virials (binary, portable)
  93 **Generic energy formats:**
  94     :ref:`edr` or :ref:`ene`
  95
  96 Other files
  97 -----------
  98
  99 :ref:`dat`
 100     generic, preferred for input
 101 :ref:`edi`
 102     essential dynamics constraints input for :ref:`gmx mdrun`
 103 :ref:`eps`
 104     Encapsulated Postscript
 105 :ref:`log`
 106     log file
 107 :ref:`map`
 108     colormap input for :ref:`gmx do_dssp`
 109 :ref:`mtx`
 110     binary matrix data
 111 :ref:`out`
 112     generic, preferred for output
 113 :ref:`tex`
 114     LaTeX input
 115 :ref:`xpm`
 116     ascii matrix data, use :ref:`gmx xpm2ps` to convert to :ref:`eps`
 117 :ref:`xvg`
 118     xvgr input
 119
 120 File format details
 121 ^^^^^^^^^^^^^^^^^^^
 122
 123 .. _atp:
 124
 125 atp
 126 ---
 127
 128 The atp file contains general information about atom types, like the atom
 129 number and the mass in atomic mass units.
 130
 131 .. _arn:
 132
 133 arn
 134 ---
 135
 136 The arn file allows the renaming of atoms from their force field names to the names
 137 as defined by IUPAC/PDB, to allow easier visualization and identification.
 138
 139 .. _cpt:
 140
 141 cpt
 142 ---
 143
 144 The cpt file extension stands for portable checkpoint file.
 145 The complete state of the simulation is stored in the checkpoint file,
 146 including extended thermostat/barostat variables, random number states
 147 and NMR time averaged data.
 148 With domain decomposition also the some decomposition setup information
 149 is stored.
 150
 151 See also :ref:`gmx mdrun`.
 152
 153 .. _dat:
 154
 155 dat
 156 ---
 157
 158 Files with the dat file extension contain generic input or output.
 159 As it is not possible
 160 to categorize all data file formats, |Gromacs| has a generic file format called
 161 dat of which no format is given.
 162
 163 .. _dlg:
 164
 165 dlg
 166 ---
 167
 168 The dlg file format is used as input for the :ref:`gmx view`
 169 trajectory viewer. These files are not meant to be altered by the end user.
 170
 171 Sample
 172 ++++++
 173
 174 ::
 175
 176     grid 39 18 {
 177
 178     group "Bond Options" 1 1 16 9 {
 179       radiobuttons { " Thin Bonds"  " Fat Bonds" " Very Fat Bonds" " Spheres" }
 180             "bonds" "Ok" " F" "help bonds"
 181     }
 182
 183     group "Other Options" 18 1 20 13 {
 184       checkbox " Show Hydrogens"      ""  "" "FALSE" "help opts"
 185       checkbox " Draw plus for atoms" ""  "" "TRUE"  "help opts"
 186       checkbox " Show Box"            ""  "" "TRUE"  "help opts"
 187       checkbox " Remove PBC"          ""  "" "FALSE" "help opts"
 188       checkbox " Depth Cueing"        ""  "" "TRUE"  "help opts"
 189       edittext "Skip frames: "        ""  "" "0"     "help opts"
 190     }
 191
 192     simple 1 15 37 2 {
 193       defbutton "Ok" "Ok" "Ok" "Ok" "help bonds"
 194     }
 195
 196     }
 197
 198 .. _edi:
 199
 200 edi
 201 ---
 202
 203 Files with the edi file extension contain information for :ref:`gmx mdrun`
 204 to run Molecular Dynamics with Essential Dynamics constraints.
 205 It used to be possible to generate those through the options
 206 provided in the `WHAT IF <http://swift.cmbi.ru.nl/whatif/>`_ program.
 207
 208 .. WEDSAM and ESSDYN seem to have vanished from WhatIf and the web
 209    These files can be generated by the program <tt>WEDSAM</tt> which uses
 210    output from the programs in the <tt>ESSDYN</tt> menu of the
 211    <A HREF="http://www.sander.embl-heidelberg.de/whatif/">WHAT IF</A> program.
 212
 213 .. _edr:
 214
 215 edr
 216 ---
 217
 218 The edr file extension stands for portable energy file.
 219 The energies are stored using the xdr protocol.
 220
 221 See also :ref:`gmx energy`.
 222
 223 .. _ene:
 224
 225 ene
 226 ---
 227
 228 The ene file extension stands for binary energy file. It holds the
 229 energies as generated during your :ref:`gmx mdrun`.
 230
 231 The file can be transformed to a portable energy file (portable
 232 across hardware platforms), the :ref:`edr` file using the program
 233 :ref:`gmx eneconv`.
 234
 235 See also :ref:`gmx energy`.
 236
 237 .. _eps:
 238
 239 eps
 240 ---
 241
 242 The eps file format is not a special |Gromacs| format, but just a
 243 variant of the standard PostScript(tm). A sample eps file as
 244 generated by the :ref:`gmx xpm2ps` program is
 245 included below. It shows the secondary structure of a peptide as a function
 246 of time.
 247
 248 .. image:: plots/plotje.*
 249    :alt:  hallo
 250
 251 .. _g96:
 252
 253 g96
 254 ---
 255
 256 A file with the g96 extension can be a GROMOS-96 initial/final
 257 configuration file or a coordinate trajectory file or a combination of both.
 258 The file is fixed format, all floats are written as 15.9 (files can get huge).
 259 |Gromacs| supports the following data blocks in the given order:
 260
 261  * Header block:
 262
 263     - ``TITLE`` (mandatory)
 264
 265  * Frame blocks:
 266
 267     - ``TIMESTEP`` (optional)
 268     - ``POSITION/POSITIONRED`` (mandatory)
 269     - ``VELOCITY/VELOCITYRED`` (optional)
 270     - ``BOX`` (optional)
 271
 272 See the GROMOS-96 manual for a complete description of the blocks.
 273
 274 Note that all |Gromacs| programs can read compressed or g-zipped files.
 275
 276 .. _gro:
 277
 278 gro
 279 ---
 280
 281 Files with the gro file extension contain a molecular structure in
 282 Gromos87 format. gro files can be used as trajectory by simply
 283 concatenating files. An attempt will be made to read a time value from
 284 the title string in each frame, which should be preceded by
 285 '``t=``', as in the sample below.
 286
 287 A sample piece is included below::
 288
 289     MD of 2 waters, t= 0.0
 290         6
 291         1WATER  OW1    1   0.126   1.624   1.679  0.1227 -0.0580  0.0434
 292         1WATER  HW2    2   0.190   1.661   1.747  0.8085  0.3191 -0.7791
 293         1WATER  HW3    3   0.177   1.568   1.613 -0.9045 -2.6469  1.3180
 294         2WATER  OW1    4   1.275   0.053   0.622  0.2519  0.3140 -0.1734
 295         2WATER  HW2    5   1.337   0.002   0.680 -1.0641 -1.1349  0.0257
 296         2WATER  HW3    6   1.326   0.120   0.568  1.9427 -0.8216 -0.0244
 297        1.82060   1.82060   1.82060
 298
 299 Lines contain the following information (top to bottom):
 300
 301  * title string (free format string, optional time in ps after '``t=``')
 302  * number of atoms (free format integer)
 303  * one line for each atom (fixed format, see below)
 304  * box vectors (free format, space separated reals), values:
 305    v1(x) v2(y) v3(z) v1(y) v1(z) v2(x) v2(z) v3(x) v3(y),
 306    the last 6 values may be omitted (they will be set to zero).
 307    |Gromacs| only supports boxes with v1(y)=v1(z)=v2(z)=0.
 308
 309 This format is fixed, ie. all columns are in a fixed
 310 position. Optionally (for now only yet with trjconv) you can write gro
 311 files with any number of decimal places, the format will then be
 312 ``n+5`` positions with ``n`` decimal places (``n+1``
 313 for velocities) in stead of ``8`` with ``3`` (with
 314 ``4`` for velocities). Upon reading, the precision will be
 315 inferred from the distance between the decimal points (which will be
 316 ``n+5``). Columns contain the following information (from left to
 317 right):
 318
 319  * residue number (5 positions, integer)
 320  * residue name (5 characters)
 321  * atom name (5 characters)
 322  * atom number (5 positions, integer)
 323  * position (in nm, x y z in 3 columns, each 8 positions with 3 decimal places)
 324  * velocity (in nm/ps (or km/s), x y z in 3 columns, each 8 positions with 4 decimal places)
 325
 326 Note that separate molecules or ions (e.g. water or Cl-) are regarded
 327 as residues.  If you want to write such a file in your own program
 328 without using the |Gromacs| libraries you can use the following formats:
 329
 330 C format
 331     ``"%5d%-5s%5s%5d%8.3f%8.3f%8.3f%8.4f%8.4f%8.4f"``
 332 Fortran format
 333     ``(i5,2a5,i5,3f8.3,3f8.4)``
 334 Pascal format
 335     This is left as an exercise for the user
 336
 337 Note that this is the format for writing, as in the above example
 338 fields may be written without spaces, and therefore can not be read
 339 with the same format statement in C.
 340
 341 .. _hdb:
 342
 343 hdb
 344 ---
 345
 346 The hdb file extension stands for hydrogen database
 347 Such a file is needed by :ref:`gmx pdb2gmx`
 348 when building hydrogen atoms that were either originally missing, or that
 349 were removed with ``-ignh``.
 350
 351 .. _itp:
 352
 353 itp
 354 ---
 355
 356 The itp file extension stands for include topology. These files are included in
 357 topology files (with the :ref:`top` extension).
 358
 359 .. _log:
 360
 361 log
 362 ---
 363
 364 Logfiles are generated by some |Gromacs| programs and are usually in
 365 human-readable format. Use ``more logfile``.
 366
 367 .. _m2p:
 368
 369 m2p
 370 ---
 371
 372 The m2p file format contains input options for the
 373 :ref:`gmx xpm2ps` program. All of these options
 374 are very easy to comprehend when you look at the PosScript(tm) output
 375 from :ref:`gmx xpm2ps`.
 376
 377 ::
 378
 379     ; Command line options of xpm2ps override the parameters in this file
 380     black&white              = no           ; Obsolete
 381     titlefont                = Times-Roman  ; A PostScript Font
 382     titlefontsize            = 20           ; Font size (pt)
 383     legend                   = yes          ; Show the legend
 384     legendfont               = Times-Roman  ; A PostScript Font
 385     legendlabel              =              ; Used when there is none in the .xpm
 386     legend2label             =              ; Used when merging two xpm's
 387     legendfontsize           = 14           ; Font size (pt)
 388     xbox                     = 2.0          ; x-size of a matrix element
 389     ybox                     = 2.0          ; y-size of a matrix element
 390     matrixspacing            = 20.0         ; Space between 2 matrices
 391     xoffset                  = 0.0          ; Between matrix and bounding box
 392     yoffset                  = 0.0          ; Between matrix and bounding box
 393     x-major                  = 20           ; Major ticks on x axis every .. frames
 394     x-minor                  = 5            ; Id. Minor ticks
 395     x-firstmajor             = 0            ; First frame for major tick
 396     x-majorat0               = no           ; Major tick at first frame
 397     x-majorticklen           = 8.0          ; x-majorticklength
 398     x-minorticklen           = 4.0          ; x-minorticklength
 399     x-label                  =              ; Used when there is none in the .xpm
 400     x-fontsize               = 16           ; Font size (pt)
 401     x-font                   = Times-Roman  ; A PostScript Font
 402     x-tickfontsize           = 10           ; Font size (pt)
 403     x-tickfont               = Helvetica    ; A PostScript Font
 404     y-major                  = 20
 405     y-minor                  = 5
 406     y-firstmajor             = 0
 407     y-majorat0               = no
 408     y-majorticklen           = 8.0
 409     y-minorticklen           = 4.0
 410     y-label                  =
 411     y-fontsize               = 16
 412     y-font                   = Times-Roman
 413     y-tickfontsize           = 10
 414     y-tickfont               = Helvetica
 415
 416 .. _map:
 417
 418 map
 419 ---
 420
 421 This file maps matrix data to RGB values which is used by the
 422 :ref:`gmx do_dssp` program.
 423
 424 The format of this file is as follow: first line number of elements
 425 in the colormap. Then for each line: The first character is
 426 a code for the secondary structure type.
 427 Then comes a string for use in the legend of the plot and then the
 428 R (red) G (green) and B (blue) values.
 429
 430 In this case the colors are
 431 (in order of appearance): white, red, black, cyan, yellow, blue, magenta, orange.
 432
 433 ::
 434
 435     8
 436     ~   Coil            1.0       1.0     1.0
 437     E   B-Sheet         1.0       0.0     0.0
 438     B   B-Bridge        0.0       0.0     0.0
 439     S   Bend            0.0       0.8     0.8
 440     T   Turn            1.0       1.0     0.0
 441     H   A-Helix         0.0       0.0     1.0
 442     G   3-Helix         1.0       0.0     1.0
 443     I   5-Helix         1.0       0.6     0.0
 444
 445 .. _mdp:
 446
 447 mdp
 448 ---
 449
 450 See the user guide for a detailed description of the options.
 451
 452 Below is a sample mdp file.
 453 The ordering of the items is not important, but if you enter the same
 454 thing twice, the **last** is used (:ref:`gmx grompp` gives you a note when
 455 overriding values). Dashes and underscores on the left hand side are ignored.
 456
 457 The values of the options are values for a 1 nanosecond
 458 MD run of a protein in a box of water.
 459
 460 **Note:** The parameters chosen (*e.g.,* short-range cutoffs) depend on the
 461 force field being used.
 462
 463 ::
 464
 465     integrator               = md
 466     dt                       = 0.002
 467     nsteps                   = 500000
 468
 469     nstlog                   = 5000
 470     nstenergy                = 5000
 471     nstxout-compressed       = 5000
 472
 473     continuation             = yes
 474     constraints              = all-bonds
 475     constraint-algorithm     = lincs
 476
 477     cutoff-scheme            = Verlet
 478
 479     coulombtype              = PME
 480     rcoulomb                 = 1.0
 481
 482     vdwtype                  = Cut-off
 483     rvdw                     = 1.0
 484     DispCorr                 = EnerPres
 485
 486     tcoupl                   = V-rescale
 487     tc-grps                  = Protein  SOL
 488     tau-t                    = 0.1      0.1
 489     ref-t                    = 300      300
 490
 491     pcoupl                   = Parrinello-Rahman
 492     tau-p                    = 2.0
 493     compressibility          = 4.5e-5
 494     ref-p                    = 1.0
 495
 496 With this input :ref:`gmx grompp` will produce a commented file with the default name
 497 ``mdout.mdp``. That file will contain the above options, as well as all other
 498 options not explicitly set, showing their default values.
 499
 500 .. _mtx:
 501
 502 mtx
 503 ---
 504
 505 Files with the mtx file extension contain a matrix.
 506 The file format is identical to the :ref:`trr` format.
 507 Currently this file format is only used for hessian matrices,
 508 which are produced with :ref:`gmx mdrun` and read by
 509 :ref:`gmx nmeig`.
 510
 511 .. _ndx:
 512
 513 ndx
 514 ---
 515
 516 The |Gromacs| index file (usually called index.ndx) contains some
 517 user definable sets of atoms. The file can be read by
 518 most analysis programs, by the graphics program
 519 (:ref:`gmx view`)
 520 and by the preprocessor (:ref:`gmx grompp`).
 521 Most of these programs create default index groups when no index
 522 file is supplied, so you only need to make an index file when you need special
 523 groups.
 524
 525 First the group name is written between square brackets.
 526 The following atom numbers may be spread out over as many lines as you like.
 527 The atom numbering starts at 1.
 528
 529 An example file is here:
 530
 531 ::
 532
 533     [ Oxygen ]
 534     1  4  7
 535     [ Hydrogen ]
 536     2  3  5  6
 537     8  9
 538
 539 There are two groups, and total nine atoms. The first group
 540 **Oxygen** has 3 elements.
 541 The second group **Hydrogen** has 6 elements.
 542
 543 An index file generation tool is available:
 544 :ref:`gmx make_ndx`.
 545
 546 .. _n2t:
 547
 548 n2t
 549 ---
 550
 551 This |Gromacs| file can be used to perform primitive translations between
 552 atom names found in structure files and the corresponding atom types.
 553 This is mostly useful for using utilities such as :ref:`gmx x2top`, but users
 554 should be aware that the knowledge in this file is extremely limited.
 555
 556 An example file (``share/top/gromos53a5.ff/atomname2type.n2t``) is here:
 557
 558 ::
 559
 560     H       H    0.408  1.008  1  O     0.1
 561     O       OA  -0.674 15.9994 2  C     0.14 H 0.1
 562     C       CH3  0.000 15.035  1  C     0.15
 563     C       CH0  0.266 12.011  4  C     0.15 C 0.15     C 0.15     O 0.14
 564
 565 A short description of the file format follows:
 566
 567 * Column 1: Elemental symbol of the atom/first character in the atom name.
 568 * Column 2: The atom type to be assigned.
 569 * Column 3: The charge to be assigned.
 570 * Column 4: The mass of the atom.
 571 * Column 5: The number N of other atoms to which this atom is bonded.
 572   The number of fields that follow are related to this number;
 573   for each atom, an elemental symbol and the reference distance for its bond length.
 574 * Columns 6-onward: The elemental symbols and reference bond lengths for N connections
 575   (column 5) to the atom being assigned parameters (column 1). The reference bond
 576   lengths have a tolerance of +/- 10% from the value specified in this file. Any bond
 577   outside this tolerance will not be recognized as being connected to the atom being assigned parameters.
 578
 579 .. _out:
 580
 581 out
 582 ---
 583
 584 Files with the out file extension contain generic output. As it is not possible
 585 to categorize all data file formats, |Gromacs| has a generic file format called
 586 out of which no format is given.
 587
 588 .. _pdb:
 589
 590 pdb
 591 ---
 592
 593
 594 Files with the :ref:`pdb` extension are molecular
 595 structure files in the protein databank file format.  The protein
 596 databank file format describes the positions of atoms in a molecular
 597 structure. Coordinates are read from the ATOM and HETATM records,
 598 until the file ends or an ENDMDL record is encountered.
 599 |Gromacs| programs can read and write a simulation box in the
 600 CRYST1 entry.
 601 The pdb format can also be used as a trajectory format:
 602 several structures, separated by ENDMDL, can be read from
 603 or written to one file.
 604
 605 Example
 606 +++++++
 607
 608 A pdb file should look like this::
 609
 610     ATOM      1  H1  LYS     1      14.260   6.590  34.480  1.00  0.00
 611     ATOM      2  H2  LYS     1      13.760   5.000  34.340  1.00  0.00
 612     ATOM      3  N   LYS     1      14.090   5.850  33.800  1.00  0.00
 613     ATOM      4  H3  LYS     1      14.920   5.560  33.270  1.00  0.00
 614     ...
 615     ...
 616
 617 .. _rtp:
 618
 619 rtp
 620 ---
 621
 622 The rtp file extension stands for residue topology.
 623 Such a file is needed by :ref:`gmx pdb2gmx`
 624 to make a |Gromacs| topology for a protein contained in a :ref:`pdb`
 625 file. The file contains the default interaction type for the 4 bonded
 626 interactions and residue entries, which consist of atoms and
 627 optionally bonds, angles dihedrals and impropers.
 628 Parameters can be added to bonds, angles, dihedrals and impropers,
 629 these parameters override the standard parameters in the :ref:`itp` files.
 630 This should only be used in special cases.
 631 Instead of parameters a string can be added for each bonded interaction,
 632 the string is copied to the :ref:`top` file,
 633 this is used for the GROMOS96 forcefield.
 634
 635 :ref:`gmx pdb2gmx` automatically generates all angles,
 636 this means that the ``[angles]`` field is only
 637 useful for overriding :ref:`itp` parameters.
 638
 639 :ref:`gmx pdb2gmx` automatically generates one proper
 640 dihedral for every rotatable bond, preferably on heavy atoms.
 641 When the ``[dihedrals]`` field is used, no other dihedrals will
 642 be generated for the bonds corresponding to the specified dihedrals.
 643 It is possible to put more than one dihedral on a rotatable bond.
 644
 645 :ref:`gmx pdb2gmx` sets the number exclusions to 3, which
 646 means that interactions between atoms connected by at most 3 bonds are
 647 excluded. Pair interactions are generated for all pairs of atoms which are
 648 separated by 3 bonds (except pairs of hydrogens).
 649 When more interactions need to be excluded, or some pair interactions should
 650 not be generated, an ``[exclusions]`` field can be added, followed by
 651 pairs of atom names on separate lines. All non-bonded and pair interactions
 652 between these atoms will be excluded.
 653
 654 A sample is included below.
 655
 656 ::
 657
 658     [ bondedtypes ]  ; mandatory
 659     ; bonds  angles  dihedrals  impropers
 660          1       1          1          2  ; mandatory
 661
 662     [ GLY ]  ; mandatory
 663
 664      [ atoms ]  ; mandatory
 665     ; name  type  charge  chargegroup
 666          N     N  -0.280     0
 667          H     H   0.280     0
 668         CA   CH2   0.000     1
 669          C     C   0.380     2
 670          O     O  -0.380     2
 671
 672      [ bonds ]  ; optional
 673     ;atom1 atom2      b0      kb
 674          N     H
 675          N    CA
 676         CA     C
 677          C     O
 678         -C     N
 679
 680      [ exclusions ]  ; optional
 681     ;atom1 atom2
 682
 683      [ angles ]  ; optional
 684     ;atom1 atom2 atom3    th0    cth
 685
 686      [ dihedrals ]  ; optional
 687     ;atom1 atom2 atom3 atom4   phi0     cp   mult
 688
 689      [ impropers ]  ; optional
 690     ;atom1 atom2 atom3 atom4     q0     cq
 691          N    -C    CA     H
 692         -C   -CA     N    -O
 693
 694
 695     [ ZN ]
 696      [ atoms ]
 697         ZN    ZN   2.000     0
 698
 699 .. _r2b:
 700
 701 r2b
 702 ---
 703
 704 The r2b file translates the residue names for residues that have different names in different
 705 force fields, or have different names depending on their protonation states.
 706
 707 .. _tdb:
 708
 709 tdb
 710 ---
 711
 712 tdb files contain the information about amino acid termini that can be placed at the
 713 end of a polypeptide chain.
 714
 715 .. _tex:
 716
 717 tex
 718 ---
 719
 720 We use **LaTeX** for *document* processing.
 721 Although the input is not so
 722 user friendly, it has some  advantages over *word* processors.
 723
 724  * **LaTeX** knows a lot about formatting, probably much more than you.
 725  * The input is clear, you always know what you are doing
 726  * It makes anything from letters to a thesis
 727  * Much more...
 728
 729 .. _tng:
 730
 731 tng
 732 ---
 733
 734 Files with the ``.tng`` file extension can contain all kinds of data
 735 related to the trajectory of a simulation. For example, it might
 736 contain coordinates, velocities, forces and/or energies. Various :ref:`mdp`
 737 file options control which of these are written by :ref:`gmx mdrun`, whether data
 738 is written with compression, and how lossy that compression can be.
 739 This file is in portable binary format and can be read with :ref:`gmx dump`.
 740
 741 .. parsed-literal::
 742
 743    :ref:`gmx dump` -f traj.tng
 744
 745 or if you're not such a fast reader::
 746
 747    gmx dump -f traj.tng | less
 748
 749 You can also get a quick look in the contents of the file (number of
 750 frames etc.) using:
 751
 752 .. parsed-literal::
 753
 754    :ref:`gmx check` -f traj.tng
 755
 756 .. _top:
 757
 758 top
 759 ---
 760
 761 The top file extension stands for topology. It is an ascii file which is
 762 read by :ref:`gmx grompp` which processes it
 763 and creates a binary topology (:ref:`tpr` file).
 764
 765 A sample file is included below::
 766
 767     ;
 768     ; Example topology file
 769     ;
 770     [ defaults ]
 771     ; nbfunc        comb-rule       gen-pairs       fudgeLJ fudgeQQ
 772       1             1               no              1.0     1.0
 773
 774     ; The force field files to be included
 775     #include "rt41c5.itp"
 776
 777     [ moleculetype ]
 778     ; name  nrexcl
 779     Urea         3
 780
 781     [ atoms ]
 782     ;   nr    type   resnr  residu    atom    cgnr  charge
 783          1       C       1    UREA      C1       1   0.683
 784          2       O       1    UREA      O2       1  -0.683
 785          3      NT       1    UREA      N3       2  -0.622
 786          4       H       1    UREA      H4       2   0.346
 787          5       H       1    UREA      H5       2   0.276
 788          6      NT       1    UREA      N6       3  -0.622
 789          7       H       1    UREA      H7       3   0.346
 790          8       H       1    UREA      H8       3   0.276
 791
 792     [ bonds ]
 793     ;  ai    aj funct           c0           c1
 794         3     4     1 1.000000e-01 3.744680e+05
 795         3     5     1 1.000000e-01 3.744680e+05
 796         6     7     1 1.000000e-01 3.744680e+05
 797         6     8     1 1.000000e-01 3.744680e+05
 798         1     2     1 1.230000e-01 5.020800e+05
 799         1     3     1 1.330000e-01 3.765600e+05
 800         1     6     1 1.330000e-01 3.765600e+05
 801
 802     [ pairs ]
 803     ;  ai    aj funct           c0           c1
 804         2     4     1 0.000000e+00 0.000000e+00
 805         2     5     1 0.000000e+00 0.000000e+00
 806         2     7     1 0.000000e+00 0.000000e+00
 807         2     8     1 0.000000e+00 0.000000e+00
 808         3     7     1 0.000000e+00 0.000000e+00
 809         3     8     1 0.000000e+00 0.000000e+00
 810         4     6     1 0.000000e+00 0.000000e+00
 811         5     6     1 0.000000e+00 0.000000e+00
 812
 813     [ angles ]
 814     ;  ai    aj    ak funct           c0           c1
 815         1     3     4     1 1.200000e+02 2.928800e+02
 816         1     3     5     1 1.200000e+02 2.928800e+02
 817         4     3     5     1 1.200000e+02 3.347200e+02
 818         1     6     7     1 1.200000e+02 2.928800e+02
 819         1     6     8     1 1.200000e+02 2.928800e+02
 820         7     6     8     1 1.200000e+02 3.347200e+02
 821         2     1     3     1 1.215000e+02 5.020800e+02
 822         2     1     6     1 1.215000e+02 5.020800e+02
 823         3     1     6     1 1.170000e+02 5.020800e+02
 824
 825     [ dihedrals ]
 826     ;  ai    aj    ak    al funct           c0           c1           c2
 827         2     1     3     4     1 1.800000e+02 3.347200e+01 2.000000e+00
 828         6     1     3     4     1 1.800000e+02 3.347200e+01 2.000000e+00
 829         2     1     3     5     1 1.800000e+02 3.347200e+01 2.000000e+00
 830         6     1     3     5     1 1.800000e+02 3.347200e+01 2.000000e+00
 831         2     1     6     7     1 1.800000e+02 3.347200e+01 2.000000e+00
 832         3     1     6     7     1 1.800000e+02 3.347200e+01 2.000000e+00
 833         2     1     6     8     1 1.800000e+02 3.347200e+01 2.000000e+00
 834         3     1     6     8     1 1.800000e+02 3.347200e+01 2.000000e+00
 835
 836     [ dihedrals ]
 837     ;  ai    aj    ak    al funct           c0           c1
 838         3     4     5     1     2 0.000000e+00 1.673600e+02
 839         6     7     8     1     2 0.000000e+00 1.673600e+02
 840         1     3     6     2     2 0.000000e+00 1.673600e+02
 841
 842     ; Include SPC water topology
 843     #include "spc.itp"
 844
 845     [ system ]
 846     Urea in Water
 847
 848     [ molecules ]
 849     Urea    1
 850     SOL     1000
 851
 852 .. _tpr:
 853
 854 tpr
 855 ---
 856
 857 The tpr file extension stands for portable binary run input file. This file
 858 contains  the starting structure of your simulation, the molecular topology
 859 and all the simulation parameters. Because this file is in binary format it
 860 cannot be read with a normal editor. To read a portable binary run input
 861 file type:
 862
 863 .. parsed-literal::
 864
 865    :ref:`gmx dump` -s topol.tpr
 866
 867 or if you're not such a fast reader::
 868
 869    gmx dump -s topol.tpr | less
 870
 871 You can also compare two tpr files using:
 872
 873 .. parsed-literal::
 874
 875    :ref:`gmx check` -s1 top1 -s2 top2 | less
 876
 877 .. _trr:
 878
 879 trr
 880 ---
 881
 882 Files with the trr file extension contain the trajectory of a simulation.
 883 In this file all the coordinates, velocities, forces and energies are
 884 printed as you told |Gromacs| in your mdp file. This file is in portable binary
 885 format and can be read with :ref:`gmx dump`::
 886
 887     gmx dump -f traj.trr
 888
 889 or if you're not such a fast reader::
 890
 891     gmx dump -f traj.trr | less
 892
 893 You can also get a quick look in the contents of the file (number of
 894 frames etc.) using:
 895
 896 .. parsed-literal::
 897
 898    % :ref:`gmx check` -f traj.trr
 899
 900 .. _vsd:
 901
 902 vsd
 903 ---
 904
 905 The vsd file contains the information on how to place virtual sites on a number
 906 of different molecules in a force field.
 907
 908 .. _xdr:
 909
 910 xdr
 911 ---
 912
 913 |Gromacs| uses the XDR file format to store things like coordinate files internally.
 914
 915 .. _xpm:
 916
 917 xpm
 918 ---
 919
 920 The |Gromacs| xpm file format is compatible with the XPixMap format
 921 and is used for storing matrix data.
 922 Thus |Gromacs| xpm files can be viewed directly with programs like XV.
 923 Alternatively, they can be imported into GIMP and scaled to 300 DPI,
 924 using strong antialiasing for font and graphics.
 925 The first matrix data line in an xpm file corresponds to the last matrix
 926 row.
 927 In addition to the XPixMap format, |Gromacs| xpm files may contain
 928 extra fields. The information in these fields is used when converting
 929 an xpm file to EPS with :ref:`gmx xpm2ps`.
 930 The optional extra field are:
 931
 932  * Before the ``gv_xpm`` declaration:  ``title``, ``legend``,
 933    ``x-label``, ``y-label`` and ``type``, all followed by a string.
 934    The ``legend`` field determines the legend title.
 935    The ``type`` field must be followed by ``"continuous"`` or
 936    ``"discrete"``, this determines which type of legend will be drawn in an EPS
 937    file, the default type is continuous.
 938  * The xpm colormap entries may be followed by a string, which is a label for
 939    that color.
 940  * Between the colormap and the matrix data, the fields ``x-axis`` and/or
 941    ``y-axis`` may be present followed by the tick-marks for that axis.
 942
 943 The example |Gromacs| xpm file below contains all the extra fields.
 944 The C-comment delimiters and the colon in the extra fields are optional.
 945
 946 ::
 947
 948     /* XPM */
 949     /* This matrix is generated by g_rms. */
 950     /* title:   "Backbone RMSD matrix" */
 951     /* legend:  "RMSD (nm)" */
 952     /* x-label: "Time (ps)" */
 953     /* y-label: "Time (ps)" */
 954     /* type:    "Continuous" */
 955     static char * gv_xpm[] = {
 956     "13 13   6 1",
 957     "A  c #FFFFFF " /* "0" */,
 958     "B  c #CCCCCC " /* "0.0399" */,
 959     "C  c #999999 " /* "0.0798" */,
 960     "D  c #666666 " /* "0.12" */,
 961     "E  c #333333 " /* "0.16" */,
 962     "F  c #000000 " /* "0.2" */,
 963     /* x-axis:  0 40 80 120 160 200 240 280 320 360 400 440 480 */
 964     /* y-axis:  0 40 80 120 160 200 240 280 320 360 400 440 480 */
 965     "FEDDDDCCCCCBA",
 966     "FEDDDCCCCBBAB",
 967     "FEDDDCCCCBABC",
 968     "FDDDDCCCCABBC",
 969     "EDDCCCCBACCCC",
 970     "EDCCCCBABCCCC",
 971     "EDCCCBABCCCCC",
 972     "EDCCBABCCCCCD",
 973     "EDCCABCCCDDDD",
 974     "ECCACCCCCDDDD",
 975     "ECACCCCCDDDDD",
 976     "DACCDDDDDDEEE",
 977     "ADEEEEEEEFFFF"
 978
 979 .. _xtc:
 980
 981 xtc
 982 ---
 983
 984 The xtc format is a **portable** format for trajectories.
 985 It uses the *xdr* routines for writing and reading
 986 data which was created for the Unix NFS system. The trajectories
 987 are written using a reduced precision algorithm which works
 988 in the following way: the coordinates (in nm) are multiplied by a scale
 989 factor, typically 1000, so that you have coordinates in pm.
 990 These are rounded to integer values. Then several other tricks are
 991 performed, for instance making use of the fact that atoms close
 992 in sequence are usually close in space too (e.g. a water molecule).
 993 To this end, the *xdr* library is extended with a special routine
 994 to write 3-D float coordinates. The routine was originally written
 995 by Frans van Hoesel as part of an Europort project. An updated
 996 version of it can be obtained through `this link <https://github.com/Pappulab/xdrf>`_.
 997
 998 All the data is stored using calls to *xdr* routines.
 999
1000 **int** magic
1001     A magic number, for the current file version its value is 1995.
1002 **int** natoms
1003     The number of atoms in the trajectory.
1004 **int** step
1005     The simulation step.
1006 **float** time
1007     The simulation time.
1008 **float** box[3][3]
1009     The computational box which is stored as a set of three basis
1010     vectors, to allow for triclinic PBC. For a rectangular box the
1011     box edges are stored on the diagonal of the matrix.
1012 **3dfcoord** x[natoms]
1013     The coordinates themselves stored in reduced precision.
1014     Please note that when the number of atoms is smaller than 9
1015     no reduced precision is used.
1016
1017 Using xtc in your "C" programs
1018 ++++++++++++++++++++++++++++++
1019
1020 To read and write these files the following "C" routines are available::
1021
1022     /* All functions return 1 if successful, 0 otherwise */
1023
1024     extern int open_xtc(XDR *xd,char *filename,char *mode);
1025     /* Open a file for xdr I/O */
1026
1027     extern void close_xtc(XDR *xd);
1028     /* Close the file for xdr I/O */
1029
1030     extern int read_first_xtc(XDR *xd,char *filename,
1031                               int *natoms,int *step,real *time,
1032                               matrix box,rvec **x,real *prec);
1033     /* Open xtc file, read xtc file first time, allocate memory for x */
1034
1035     extern int read_next_xtc(XDR *xd,
1036                              int *natoms,int *step,real *time,
1037                              matrix box,rvec *x,real *prec);
1038     /* Read subsequent frames */
1039
1040     extern int write_xtc(XDR *xd,
1041                          int natoms,int step,real time,
1042                          matrix box,rvec *x,real prec);
1043     /* Write a frame to xtc file */
1044
1045 To use the library function include ``"gromacs/fileio/xtcio.h"``
1046 in your file and link with ``-lgmx.$(CPU)``.
1047
1048 Using xtc in your FORTRAN programs
1049 ++++++++++++++++++++++++++++++++++
1050
1051 To read and write these in a FORTRAN program use the calls to
1052 ``readxtc`` and ``writextc`` as in the following sample program
1053 which reads and xtc file and copies it to a new one::
1054
1055     program testxtc
1056
1057     parameter (maxatom=10000,maxx=3*maxatom)
1058     integer xd,xd2,natoms,step,ret,i
1059     real    time,box(9),x(maxx)
1060
1061     call xdrfopen(xd,"test.xtc","r",ret)
1062     print *,'opened test.xtc, ret=',ret
1063     call xdrfopen(xd2,"testout.xtc","w",ret)
1064     print *,'opened testout.xtc, ret=',ret
1065
1066     call readxtc(xd,natoms,step,time,box,x,prec,ret)
1067
1068     if ( ret .eq. 1 ) then
1069        call writextc(xd2,natoms,step,time,box,x,prec,ret)
1070     else
1071        print *,'Error reading xtc'
1072     endif
1073
1074     stop
1075     end
1076
1077 To link your program use ``-L$(GMXHOME)/lib/$(CPU) -lxtcf``
1078 on your linker command line.
1079
1080 .. _xvg:
1081
1082 xvg
1083 ---
1084
1085 Almost all output from |Gromacs| analysis tools is ready as input for
1086 Grace, formerly known as Xmgr. We use Grace, because it is very flexible, and it is also
1087 free software. It produces PostScript(tm) output, which is very suitable
1088 for inclusion in eg. LaTeX documents, but also for other word processors.
1089
1090 A sample Grace session with |Gromacs| data is shown below:
1091
1092 .. image:: plots/xvgr.*
1093    :alt:  Sample xvg graphic produced using the |Gromacs| tools