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