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