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