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 reasonable values for a 1 nanosecond
 439 MD run of a protein in a box of water.
 440
 441 ::
 442
 443     title                    = Yo
 444     cpp                      = /lib/cpp
 445     include                  = -I../top
 446     define                   =
 447     integrator               = md
 448     dt                       = 0.002
 449     nsteps                   = 500000
 450     nstxout                  = 5000
 451     nstvout                  = 5000
 452     nstlog                   = 5000
 453     nstenergy                = 250
 454     nstxout-compressed       = 250
 455     compressed-x-grps        = Protein
 456     energygrps               = Protein  SOL
 457     nstlist                  = 10
 458     ns-type                  = grid
 459     rlist                    = 0.8
 460     coulombtype              = cut-off
 461     rcoulomb                 = 1.4
 462     rvdw                     = 0.8
 463     tcoupl                   = Berendsen
 464     tc-grps                  = Protein      SOL
 465     tau-t                    = 0.1  0.1
 466     ref-t                    = 300  300
 467     Pcoupl                   = Berendsen
 468     tau-p                    = 1.0
 469     compressibility          = 4.5e-5
 470     ref-p                    = 1.0
 471     gen-vel                  = yes
 472     gen-temp                 = 300
 473     gen-seed                 = 173529
 474     constraints              = all-bonds
 475
 476 With this input :ref:`gmx grompp` will produce
 477 an ``mdout.mdp`` with all the options and descriptions:
 478
 479 ::
 480
 481     ; VARIOUS PREPROCESSING OPTIONS =
 482     title                    = Yo
 483     cpp                      = /lib/cpp
 484     include                  = -I../top
 485     define                   =
 486
 487     ; RUN CONTROL PARAMETERS =
 488     integrator               = md
 489     ; start time and timestep in ps =
 490     tinit                    = 0
 491     dt                       = 0.002
 492     nsteps                   = 500000
 493     ; number of steps for center of mass motion removal =
 494     nstcomm                  = 1
 495     comm-grps                =
 496
 497     ; LANGEVIN DYNAMICS OPTIONS =
 498     ; Temperature, friction coefficient (amu/ps) and random seed =
 499     bd-temp                  = 300
 500     bd-fric                  = 0
 501     ld-seed                  = 1993
 502
 503     ; ENERGY MINIMIZATION OPTIONS =
 504     ; Force tolerance and initial step-size =
 505     emtol                    = 100
 506     emstep                   = 0.01
 507     ; Max number of iterations in relax-shells =
 508     niter                    = 20
 509     ; Frequency of steepest descents steps when doing CG =
 510     nstcgsteep               = 1000
 511
 512     ; OUTPUT CONTROL OPTIONS =
 513     ; Output frequency for coords (x), velocities (v) and forces (f) =
 514     nstxout                  = 5000
 515     nstvout                  = 5000
 516     nstfout                  = 0
 517     ; Output frequency for energies to log file and energy file =
 518     nstlog                   = 5000
 519     nstenergy                = 250
 520     ; Output frequency and precision for xtc file =
 521     nstxout-compressed       = 250
 522     compressed-x-precision   = 1000
 523     ; This selects the subset of atoms for the xtc file. You can =
 524     ; select multiple groups. By default all atoms will be written. =
 525     compressed-x-grps        = Protein
 526     ; Selection of energy groups =
 527     energygrps               = Protein  SOL
 528
 529     ; NEIGHBORSEARCHING PARAMETERS =
 530     ; nblist update frequency =
 531     nstlist                  = 10
 532     ; ns algorithm (simple or grid) =
 533     ns-type                  = grid
 534     ; Periodic boundary conditions: xyz or none =
 535     pbc                      = xyz
 536     ; nblist cut-off         =
 537     rlist                    = 0.8
 538
 539     ; OPTIONS FOR ELECTROSTATICS AND VDW =
 540     ; Method for doing electrostatics =
 541     coulombtype              = cut-off
 542     rcoulomb-switch          = 0
 543     rcoulomb                 = 1.4
 544     ; Dielectric constant (DC) for cut-off or DC of reaction field =
 545     epsilon-r                = 1
 546     ; Method for doing Van der Waals =
 547     vdw-type                 = Cut-off
 548     ; cut-off lengths        =
 549     rvdw-switch              = 0
 550     rvdw                     = 0.8
 551     ; Apply long range dispersion corrections for Energy and Pressure =
 552     DispCorr                 = No
 553     ; Spacing for the PME/PPPM FFT grid =
 554     fourierspacing           = 0.12
 555     ; FFT grid size, when a value is 0 fourierspacing will be used =
 556     fourier-nx               = 0
 557     fourier-ny               = 0
 558     fourier-nz               = 0
 559     ; EWALD/PME/PPPM parameters =
 560     pme-order                = 4
 561     ewald-rtol               = 1e-05
 562     epsilon-surface          = 0
 563
 564     ; OPTIONS FOR WEAK COUPLING ALGORITHMS =
 565     ; Temperature coupling   =
 566     tcoupl                   = Berendsen
 567     ; Groups to couple separately =
 568     tc-grps                  = Protein      SOL
 569     ; Time constant (ps) and reference temperature (K) =
 570     tau-t                    = 0.1  0.1
 571     ref-t                    = 300  300
 572     ; Pressure coupling      =
 573     Pcoupl                   = Berendsen
 574     Pcoupltype               = Isotropic
 575     ; Time constant (ps), compressibility (1/bar) and reference P (bar) =
 576     tau-p                    = 1.0
 577     compressibility          = 4.5e-5
 578     ref-p                    = 1.0
 579
 580     ; SIMULATED ANNEALING CONTROL =
 581     annealing                = no
 582     ; Time at which temperature should be zero (ps) =
 583     zero-temp-time           = 0
 584
 585     ; GENERATE VELOCITIES FOR STARTUP RUN =
 586     gen-vel                  = yes
 587     gen-temp                 = 300
 588     gen-seed                 = 173529
 589
 590     ; OPTIONS FOR BONDS     =
 591     constraints              = all-bonds
 592     ; Type of constraint algorithm =
 593     constraint-algorithm     = Lincs
 594     ; Do not constrain the start configuration =
 595     unconstrained-start      = no
 596     ; Relative tolerance of shake =
 597     shake-tol                = 0.0001
 598     ; Highest order in the expansion of the constraint coupling matrix =
 599     lincs-order              = 4
 600     ; Lincs will write a warning to the stderr if in one step a bond =
 601     ; rotates over more degrees than =
 602     lincs-warnangle          = 30
 603     ; Convert harmonic bonds to morse potentials =
 604     morse                    = no
 605
 606     ; NMR refinement stuff  =
 607     ; Distance restraints type: No, Simple or Ensemble =
 608     disre                    = No
 609     ; Force weighting of pairs in one distance restraint: Equal or Conservative =
 610     disre-weighting          = Equal
 611     ; Use sqrt of the time averaged times the instantaneous violation =
 612     disre-mixed              = no
 613     disre-fc                 = 1000
 614     disre-tau                = 0
 615     ; Output frequency for pair distances to energy file =
 616     nstdisreout              = 100
 617
 618     ; Free energy control stuff =
 619     free-energy              = no
 620     init-lambda              = 0
 621     delta-lambda             = 0
 622     sc-alpha                 = 0
 623     sc-sigma                 = 0.3
 624
 625     ; Non-equilibrium MD stuff =
 626     acc-grps                 =
 627     accelerate               =
 628     freezegrps               =
 629     freezedim                =
 630     cos-acceleration         = 0
 631     energygrp-excl           =
 632
 633     ; Electric fields       =
 634     ; Format is number of terms (int) and for all terms an amplitude (real) =
 635     ; and a phase angle (real) =
 636     E-x                      =
 637     E-xt                     =
 638     E-y                      =
 639     E-yt                     =
 640     E-z                      =
 641     E-zt                     =
 642
 643     ; User defined thingies =
 644     user1-grps               =
 645     user2-grps               =
 646     userint1                 = 0
 647     userint2                 = 0
 648     userint3                 = 0
 649     userint4                 = 0
 650     userreal1                = 0
 651     userreal2                = 0
 652     userreal3                = 0
 653     userreal4                = 0
 654
 655 .. _mtx:
 656
 657 mtx
 658 ---
 659
 660 Files with the mtx file extension contain a matrix.
 661 The file format is identical to the :ref:`trr` format.
 662 Currently this file format is only used for hessian matrices,
 663 which are produced with :ref:`gmx mdrun` and read by
 664 :ref:`gmx nmeig`.
 665
 666 .. _ndx:
 667
 668 ndx
 669 ---
 670
 671 The GROMACS index file (usually called index.ndx) contains some
 672 user definable sets of atoms. The file can be read by
 673 most analysis programs, by the graphics program
 674 (:ref:`gmx view`)
 675 and by the preprocessor (:ref:`gmx grompp`).
 676 Most of these programs create default index groups when no index
 677 file is supplied, so you only need to make an index file when you need special
 678 groups.
 679
 680 First the group name is written between square brackets.
 681 The following atom numbers may be spread out over as many lines as you like.
 682 The atom numbering starts at 1.
 683
 684 An example file is here:
 685
 686 ::
 687
 688     [ Oxygen ]
 689     1  4  7
 690     [ Hydrogen ]
 691     2  3  5  6
 692     8  9
 693
 694 There are two groups, and total nine atoms. The first group
 695 **Oxygen** has 3 elements.
 696 The second group **Hydrogen** has 6 elements.
 697
 698 An index file generation tool is available:
 699 :ref:`gmx make_ndx`.
 700
 701 .. _out:
 702
 703 out
 704 ---
 705
 706 Files with the out file extension contain generic output. As it is not possible
 707 to categorise all data file formats, GROMACS has a generic file format called
 708 out of which no format is given.
 709
 710 .. _pdb:
 711
 712 pdb
 713 ---
 714
 715
 716 Files with the :ref:`pdb` extension are molecular
 717 structure files in the protein databank file format.  The protein
 718 databank file format describes the positions of atoms in a molecular
 719 structure. Coordinates are read from the ATOM and HETATM records,
 720 until the file ends or an ENDMDL record is encountered.
 721 GROMACS programs can read and write a simulation box in the
 722 CRYST1 entry.
 723 The pdb format can also be used as a trajectory format:
 724 several structures, separated by ENDMDL, can be read from
 725 or written to one file.
 726
 727 Example
 728 +++++++
 729
 730 A pdb file should look like this::
 731
 732     ATOM      1  H1  LYS     1      14.260   6.590  34.480  1.00  0.00
 733     ATOM      2  H2  LYS     1      13.760   5.000  34.340  1.00  0.00
 734     ATOM      3  N   LYS     1      14.090   5.850  33.800  1.00  0.00
 735     ATOM      4  H3  LYS     1      14.920   5.560  33.270  1.00  0.00
 736     ...
 737     ...
 738
 739 .. _rtp:
 740
 741 rtp
 742 ---
 743
 744 The rtp file extension stands for residue topology.
 745 Such a file is needed by :ref:`gmx pdb2gmx`
 746 to make a GROMACS topology for a protein contained in a :ref:`pdb`
 747 file. The file contains the default interaction type for the 4 bonded
 748 interactions and residue entries, which consist of atoms and
 749 optionally bonds, angles dihedrals and impropers.
 750 Parameters can be added to bonds, angles, dihedrals and impropers,
 751 these parameters override the standard parameters in the :ref:`itp` files.
 752 This should only be used in special cases.
 753 Instead of parameters a string can be added for each bonded interaction,
 754 the string is copied to the :ref:`top` file,
 755 this is used for the GROMOS96 forcefield.
 756
 757 :ref:`gmx pdb2gmx` automatically generates all angles,
 758 this means that the ``[angles]`` field is only
 759 useful for overriding :ref:`itp` parameters.
 760
 761 :ref:`gmx pdb2gmx` automatically generates one proper
 762 dihedral for every rotatable bond, preferably on heavy atoms.
 763 When the ``[dihedrals]`` field is used, no other dihedrals will
 764 be generated for the bonds corresponding to the specified dihedrals.
 765 It is possible to put more than one dihedral on a rotatable bond.
 766
 767 :ref:`gmx pdb2gmx` sets the number exclusions to 3, which
 768 means that interactions between atoms connected by at most 3 bonds are
 769 excluded. Pair interactions are generated for all pairs of atoms which are
 770 separated by 3 bonds (except pairs of hydrogens).
 771 When more interactions need to be excluded, or some pair interactions should
 772 not be generated, an ``[exclusions]`` field can be added, followed by
 773 pairs of atom names on separate lines. All non-bonded and pair interactions
 774 between these atoms will be excluded.
 775
 776 A sample is included below.
 777
 778 ::
 779
 780     [ bondedtypes ]  ; mandatory
 781     ; bonds  angles  dihedrals  impropers
 782          1       1          1          2  ; mandatory
 783
 784     [ GLY ]  ; mandatory
 785
 786      [ atoms ]  ; mandatory
 787     ; name  type  charge  chargegroup
 788          N     N  -0.280     0
 789          H     H   0.280     0
 790         CA   CH2   0.000     1
 791          C     C   0.380     2
 792          O     O  -0.380     2
 793
 794      [ bonds ]  ; optional
 795     ;atom1 atom2      b0      kb
 796          N     H
 797          N    CA
 798         CA     C
 799          C     O
 800         -C     N
 801
 802      [ exclusions ]  ; optional
 803     ;atom1 atom2
 804
 805      [ angles ]  ; optional
 806     ;atom1 atom2 atom3    th0    cth
 807
 808      [ dihedrals ]  ; optional
 809     ;atom1 atom2 atom3 atom4   phi0     cp   mult
 810
 811      [ impropers ]  ; optional
 812     ;atom1 atom2 atom3 atom4     q0     cq
 813          N    -C    CA     H
 814         -C   -CA     N    -O
 815
 816
 817     [ ZN ]
 818      [ atoms ]
 819         ZN    ZN   2.000     0
 820
 821 .. _tex:
 822
 823 tex
 824 ---
 825
 826 We use **LaTeX** for *document* processing.
 827 Although the input is not so
 828 user friendly, it has some  advantages over *word* processors.
 829
 830  * **LaTeX** knows a lot about formatting, probably much more than you.
 831  * The input is clear, you always know what you are doing
 832  * It makes anything from letters to a thesis
 833  * Much more...
 834
 835 .. _tng:
 836
 837 tng
 838 ---
 839
 840 Files with the ``.tng`` file extension can contain all kinds of data
 841 related to the trajectory of a simulation. For example, it might
 842 contain coordinates, velocities, forces and/or energies. Various :ref:`mdp`
 843 file options control which of these are written by mdrun, whether data
 844 is written with compression, and how lossy that compression can be.
 845 This file is in portable binary format an can be read with :ref:`gmx dump`.
 846
 847 .. parsed-literal:
 848
 849    % :ref:`gmx dump` -f traj.tng
 850
 851 or if you're not such a fast reader::
 852
 853    % gmx dump -f traj.tng | less
 854
 855 You can also get a quick look in the contents of the file (number of
 856 frames etc.) using:
 857
 858 .. parsed-literal:
 859
 860    % :ref:`gmx check` -f traj.tng
 861
 862 .. _top:
 863
 864 top
 865 ---
 866
 867 The top file extension stands for topology. It is an ascii file which is
 868 read by :ref:`gmx grompp` which processes it
 869 and creates a binary topology (:ref:`tpr` file).
 870
 871 A sample file is included below::
 872
 873     ;
 874     ; Example topology file
 875     ;
 876     [ defaults ]
 877     ; nbfunc        comb-rule       gen-pairs       fudgeLJ fudgeQQ
 878       1             1               no              1.0     1.0
 879
 880     ; The force field files to be included
 881     #include "rt41c5.itp"
 882
 883     [ moleculetype ]
 884     ; name  nrexcl
 885     Urea         3
 886
 887     [ atoms ]
 888     ;   nr    type   resnr  residu    atom    cgnr  charge
 889          1       C       1    UREA      C1       1   0.683
 890          2       O       1    UREA      O2       1  -0.683
 891          3      NT       1    UREA      N3       2  -0.622
 892          4       H       1    UREA      H4       2   0.346
 893          5       H       1    UREA      H5       2   0.276
 894          6      NT       1    UREA      N6       3  -0.622
 895          7       H       1    UREA      H7       3   0.346
 896          8       H       1    UREA      H8       3   0.276
 897
 898     [ bonds ]
 899     ;  ai    aj funct           c0           c1
 900         3     4     1 1.000000e-01 3.744680e+05
 901         3     5     1 1.000000e-01 3.744680e+05
 902         6     7     1 1.000000e-01 3.744680e+05
 903         6     8     1 1.000000e-01 3.744680e+05
 904         1     2     1 1.230000e-01 5.020800e+05
 905         1     3     1 1.330000e-01 3.765600e+05
 906         1     6     1 1.330000e-01 3.765600e+05
 907
 908     [ pairs ]
 909     ;  ai    aj funct           c0           c1
 910         2     4     1 0.000000e+00 0.000000e+00
 911         2     5     1 0.000000e+00 0.000000e+00
 912         2     7     1 0.000000e+00 0.000000e+00
 913         2     8     1 0.000000e+00 0.000000e+00
 914         3     7     1 0.000000e+00 0.000000e+00
 915         3     8     1 0.000000e+00 0.000000e+00
 916         4     6     1 0.000000e+00 0.000000e+00
 917         5     6     1 0.000000e+00 0.000000e+00
 918
 919     [ angles ]
 920     ;  ai    aj    ak funct           c0           c1
 921         1     3     4     1 1.200000e+02 2.928800e+02
 922         1     3     5     1 1.200000e+02 2.928800e+02
 923         4     3     5     1 1.200000e+02 3.347200e+02
 924         1     6     7     1 1.200000e+02 2.928800e+02
 925         1     6     8     1 1.200000e+02 2.928800e+02
 926         7     6     8     1 1.200000e+02 3.347200e+02
 927         2     1     3     1 1.215000e+02 5.020800e+02
 928         2     1     6     1 1.215000e+02 5.020800e+02
 929         3     1     6     1 1.170000e+02 5.020800e+02
 930
 931     [ dihedrals ]
 932     ;  ai    aj    ak    al funct           c0           c1           c2
 933         2     1     3     4     1 1.800000e+02 3.347200e+01 2.000000e+00
 934         6     1     3     4     1 1.800000e+02 3.347200e+01 2.000000e+00
 935         2     1     3     5     1 1.800000e+02 3.347200e+01 2.000000e+00
 936         6     1     3     5     1 1.800000e+02 3.347200e+01 2.000000e+00
 937         2     1     6     7     1 1.800000e+02 3.347200e+01 2.000000e+00
 938         3     1     6     7     1 1.800000e+02 3.347200e+01 2.000000e+00
 939         2     1     6     8     1 1.800000e+02 3.347200e+01 2.000000e+00
 940         3     1     6     8     1 1.800000e+02 3.347200e+01 2.000000e+00
 941
 942     [ dihedrals ]
 943     ;  ai    aj    ak    al funct           c0           c1
 944         3     4     5     1     2 0.000000e+00 1.673600e+02
 945         6     7     8     1     2 0.000000e+00 1.673600e+02
 946         1     3     6     2     2 0.000000e+00 1.673600e+02
 947
 948     ; Include SPC water topology
 949     #include "spc.itp"
 950
 951     [ system ]
 952     Urea in Water
 953
 954     [ molecules ]
 955     Urea    1
 956     SOL     1000
 957
 958 .. _tpr:
 959
 960 tpr
 961 ---
 962
 963 The tpr file extension stands for portable binary run input file. This file
 964 contains  the starting structure of your simulation, the molecular topology
 965 and all the simulation parameters. Because this file is in binary format it
 966 cannot be read with a normal editor. To read a portable binary run input
 967 file type:
 968
 969 .. parsed-literal:
 970
 971    % :ref:`gmx dump` -s topol.tpr
 972
 973 or if you're not such a fast reader::
 974
 975    % gmx dump -s topol.tpr | less
 976
 977 You can also compare two tpr files using:
 978
 979 .. parsed-literal:
 980
 981    % :ref:`gmx check` -s1 top1 -s2 top2 | less
 982
 983 .. _trr:
 984
 985 trr
 986 ---
 987
 988 Files with the trr file extension contain the trajectory of a simulation.
 989 In this file all the coordinates, velocities, forces and energies are
 990 printed as you told GROMACS in your mdp file. This file is in portable binary
 991 format an can be read with :ref:`gmx dump`::
 992
 993     % gmx dump -f traj.trr
 994
 995 or if you're not such a fast reader::
 996
 997     % gmx dump -f traj.trr | less
 998
 999 You can also get a quick look in the contents of the file (number of
1000 frames etc.) using:
1001
1002 .. parsed-literal:
1003
1004    % :ref:`gmx check` -f traj.trr
1005
1006 .. _xpm:
1007
1008 xpm
1009 ---
1010
1011 The GROMACS xpm file format is compatible with the XPixMap format
1012 and is used for storing matrix data.
1013 Thus GROMACS xpm files can be viewed directly with programs like XV.
1014 Alternatively, they can be imported into GIMP and scaled to 300 DPI,
1015 using strong antialiasing for font and graphics.
1016 The first matrix data line in an xpm file corresponds to the last matrix
1017 row.
1018 In addition to the XPixMap format, GROMACS xpm files may contain
1019 extra fields. The information in these fields is used when converting
1020 an xpm file to EPS with :ref:`gmx xpm2ps`.
1021 The optional extra field are:
1022
1023  * Before the ``gv_xpm`` declaration:  ``title``, ``legend``,
1024    ``x-label``, ``y-label`` and ``type``, all followed by a string.
1025    The ``legend`` field determines the legend title.
1026    The ``type`` field must be followed by ``"continuous"`` or
1027    ``"discrete"``, this determines which type of legend will be drawn in an EPS
1028    file, the default type is continuous.
1029  * The xpm colormap entries may be followed by a string, which is a label for
1030    that color.
1031  * Between the colormap and the matrix data, the fields ``x-axis`` and/or
1032    ``y-axis`` may be present followed by the tick-marks for that axis.
1033
1034 The example GROMACS xpm file below contains all the extra fields.
1035 The C-comment delimiters and the colon in the extra fields are optional.
1036
1037 ::
1038
1039     /* XPM */
1040     /* This matrix is generated by g_rms. */
1041     /* title:   "Backbone RMSD matrix" */
1042     /* legend:  "RMSD (nm)" */
1043     /* x-label: "Time (ps)" */
1044     /* y-label: "Time (ps)" */
1045     /* type:    "Continuous" */
1046     static char * gv_xpm[] = {
1047     "13 13   6 1",
1048     "A  c #FFFFFF " /* "0" */,
1049     "B  c #CCCCCC " /* "0.0399" */,
1050     "C  c #999999 " /* "0.0798" */,
1051     "D  c #666666 " /* "0.12" */,
1052     "E  c #333333 " /* "0.16" */,
1053     "F  c #000000 " /* "0.2" */,
1054     /* x-axis:  0 40 80 120 160 200 240 280 320 360 400 440 480 */
1055     /* y-axis:  0 40 80 120 160 200 240 280 320 360 400 440 480 */
1056     "FEDDDDCCCCCBA",
1057     "FEDDDCCCCBBAB",
1058     "FEDDDCCCCBABC",
1059     "FDDDDCCCCABBC",
1060     "EDDCCCCBACCCC",
1061     "EDCCCCBABCCCC",
1062     "EDCCCBABCCCCC",
1063     "EDCCBABCCCCCD",
1064     "EDCCABCCCDDDD",
1065     "ECCACCCCCDDDD",
1066     "ECACCCCCDDDDD",
1067     "DACCDDDDDDEEE",
1068     "ADEEEEEEEFFFF"
1069
1070 .. _xtc:
1071
1072 xtc
1073 ---
1074
1075 The xtc format is a **portable** format for trajectories.
1076 It uses the *xdr* routines for writing and reading
1077 data which was created for the Unix NFS system. The trajectories
1078 are written using a reduced precision algorithm which works
1079 in the following way: the coordinates (in nm) are multiplied by a scale
1080 factor, typically 1000, so that you have coordinates in pm.
1081 These are rounded to integer values. Then several other tricks are
1082 performed, for instance making use of the fact that atoms close
1083 in sequence are usually close in space too (e.g. a water molecule).
1084 To this end, the <i>xdr</i> library is extended with a special routine
1085 to write 3-D float coordinates.
1086
1087 .. link is broken: This routine was written by Frans van Hoesel
1088    as part of an Europort project, and can be obtained through <a
1089    href="http://hpcv100.rc.rug.nl/xdrf.html">this link</a>.
1090
1091 All the data is stored using calls to *xdr* routines.
1092
1093 **int** magic
1094     A magic number, for the current file version its value is 1995.
1095 **int** natoms
1096     The number of atoms in the trajectory.
1097 **int** step
1098     The simulation step.
1099 **float** time
1100     The simulation time.
1101 **float** box[3][3]
1102     The computational box which is stored as a set of three basis
1103     vectors, to allow for triclinic PBC. For a rectangular box the
1104     box edges are stored on the diagonal of the matrix.
1105 **3dfcoord** x[natoms]
1106     The coordinates themselves stored in reduced precision.
1107     Please note that when the number of atoms is smaller than 9
1108     no reduced precision is used.
1109
1110 Using xtc in your "C" programs
1111 ++++++++++++++++++++++++++++++
1112
1113 To read and write these files the following "C" routines are available::
1114
1115     /* All functions return 1 if successful, 0 otherwise */
1116
1117     extern int open_xtc(XDR *xd,char *filename,char *mode);
1118     /* Open a file for xdr I/O */
1119
1120     extern void close_xtc(XDR *xd);
1121     /* Close the file for xdr I/O */
1122
1123     extern int read_first_xtc(XDR *xd,char *filename,
1124                               int *natoms,int *step,real *time,
1125                               matrix box,rvec **x,real *prec);
1126     /* Open xtc file, read xtc file first time, allocate memory for x */
1127
1128     extern int read_next_xtc(XDR *xd,
1129                              int *natoms,int *step,real *time,
1130                              matrix box,rvec *x,real *prec);
1131     /* Read subsequent frames */
1132
1133     extern int write_xtc(XDR *xd,
1134                          int natoms,int step,real time,
1135                          matrix box,rvec *x,real prec);
1136     /* Write a frame to xtc file */
1137
1138 To use the library function include ``"gromacs/fileio/xtcio.h"``
1139 in your file and link with ``-lgmx.$(CPU)``.
1140
1141 Using xtc in your FORTRAN programs
1142 ++++++++++++++++++++++++++++++++++
1143
1144 To read and write these in a FORTRAN program use the calls to
1145 ``readxtc`` and ``writextc`` as in the following sample program
1146 which reads and xtc file and copies it to a new one::
1147
1148     program testxtc
1149
1150     parameter (maxatom=10000,maxx=3*maxatom)
1151     integer xd,xd2,natoms,step,ret,i
1152     real    time,box(9),x(maxx)
1153
1154     call xdrfopen(xd,"test.xtc","r",ret)
1155     print *,'opened test.xtc, ret=',ret
1156     call xdrfopen(xd2,"testout.xtc","w",ret)
1157     print *,'opened testout.xtc, ret=',ret
1158
1159     call readxtc(xd,natoms,step,time,box,x,prec,ret)
1160
1161     if ( ret .eq. 1 ) then
1162        call writextc(xd2,natoms,step,time,box,x,prec,ret)
1163     else
1164        print *,'Error reading xtc'
1165     endif
1166
1167     stop
1168     end
1169
1170 To link your program use ``-L$(GMXHOME)/lib/$(CPU) -lxtcf``
1171 on your linker command line.
1172
1173 .. _xvg:
1174
1175 xvg
1176 ---
1177
1178 Almost all output from GROMACS analysis tools is ready as input for
1179 Grace, formerly known as Xmgr. We use Grace, because it is very flexible, and it is also
1180 free software. It produces PostScript(tm) output, which is very suitable
1181 for inclusion in eg. LaTeX documents, but also for other word processors.
1182
1183 A sample Grace session with GROMACS data is shown below:
1184
1185 .. image:: xvgr.gif
1186    :alt:  hallo