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