| blob | 35a42269ecb7849b1a4c31b3906fe7e3373585b1 |
1 File formats
2 ============
4 .. TODO in future patch: update for accuracy, organize better, improve formatting
6 Summary of file formats
7 ^^^^^^^^^^^^^^^^^^^^^^^
9 Parameter files
10 ---------------
12 :ref:`mdp`
13 run parameters, input for :ref:`gmx grompp` and :ref:`gmx convert-tpr`
15 :ref:`m2p`
16 input for :ref:`gmx xpm2ps`
18 Structure files
19 ---------------
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.
31 Topology files
32 --------------
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
43 Run Input files
44 ---------------
46 :ref:`tpr`
47 system topology, parameters, coordinates and velocities (binary, portable)
49 Trajectory files
50 ----------------
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`
69 Energy files
70 ------------
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`
79 Other files
80 -----------
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
103 File format details
104 ^^^^^^^^^^^^^^^^^^^
106 .. _cpt:
108 cpt
109 ---
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.
118 See also :ref:`gmx mdrun`.
120 .. _dat:
122 dat
123 ---
125 Files with the dat file extension contain generic input or output.
126 As it is not possible
127 to categorize all data file formats, GROMACS has a generic file format called
128 dat of which no format is given.
130 .. _dlg:
132 dlg
133 ---
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.
138 Sample
139 ++++++
141 ::
143 grid 39 18 {
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 }
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 }
159 simple 1 15 37 2 {
160 defbutton "Ok" "Ok" "Ok" "Ok" "help bonds"
161 }
163 }
165 .. _edi:
167 edi
168 ---
170 Files with the edi file extension contain information for :ref:`gmx mdrun`
171 to run Molecular Dynamics with Essential Dynamics constraints.
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.
178 .. _edr:
180 edr
181 ---
183 The edr file extension stands for portable energy file.
184 The energies are stored using the xdr protocol.
186 See also :ref:`gmx energy`.
188 .. _ene:
190 ene
191 ---
193 The ene file extension stands for binary energy file. It holds the
194 energies as generated during your :ref:`gmx mdrun`.
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`.
200 See also :ref:`gmx energy`.
202 .. _eps:
204 eps
205 ---
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.
213 .. image:: plotje.gif
214 :alt: hallo
216 .. _g96:
218 g96
219 ---
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:
226 * Header block:
228 - ``TITLE`` (mandatory)
230 * Frame blocks:
232 - ``TIMESTEP`` (optional)
233 - ``POSITION/POSITIONRED`` (mandatory)
234 - ``VELOCITY/VELOCITYRED`` (optional)
235 - ``BOX`` (optional)
237 See the GROMOS-96 manual for a complete description of the blocks.
239 Note that all GROMACS programs can read compressed or g-zipped files.
241 .. _gro:
243 gro
244 ---
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.
252 A sample piece is included below::
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
264 Lines contain the following information (top to bottom):
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.
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):
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)
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:
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
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.
306 .. _hdb:
308 hdb
309 ---
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``.
316 .. _itp:
318 itp
319 ---
321 The itp file extension stands for include topology. These files are included in
322 topology files (with the :ref:`top` extension).
324 .. _log:
326 log
327 ---
329 Logfiles are generated by some GROMACS programs and are usually in
330 human-readable format. Use ``more logfile``.
332 .. _m2p:
334 m2p
335 ---
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`.
342 ::
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
381 .. _map:
383 map
384 ---
386 This file maps matrix data to RGB values which is used by the
387 :ref:`gmx do_dssp` program.
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.
395 In this case the colors are
396 (in order of appearance): white, red, black, cyan, yellow, blue, magenta, orange.
398 ::
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
410 .. _mdp:
412 mdp
413 ---
415 See the user guide for a detailed description of the options.
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.
422 The values of the options are values for a 1 nanosecond
423 MD run of a protein in a box of water.
425 **Note:** The parameters chosen (*e.g.,* short-range cutoffs) depend on the
426 force field being used.
428 ::
430 integrator = md
431 dt = 0.002
432 nsteps = 500000
434 nstlog = 5000
435 nstenergy = 5000
436 nstxout-compressed = 5000
438 continuation = yes
439 constraints = all-bonds
440 constraint-algorithm = lincs
442 cutoff-scheme = Verlet
444 coulombtype = PME
445 rcoulomb = 1.0
447 vdwtype = Cut-off
448 rvdw = 1.0
449 DispCorr = EnerPres
451 tcoupl = V-rescale
452 tc-grps = Protein SOL
453 tau-t = 0.1 0.1
454 ref-t = 300 300
456 pcoupl = Parrinello-Rahman
457 tau-p = 2.0
458 compressibility = 4.5e-5
459 ref-p = 1.0
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.
465 .. _mtx:
467 mtx
468 ---
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`.
476 .. _ndx:
478 ndx
479 ---
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.
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.
494 An example file is here:
496 ::
498 [ Oxygen ]
499 1 4 7
500 [ Hydrogen ]
501 2 3 5 6
502 8 9
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.
508 An index file generation tool is available:
509 :ref:`gmx make_ndx`.
511 .. _out:
513 out
514 ---
516 Files with the out file extension contain generic output. As it is not possible
517 to categorize all data file formats, GROMACS has a generic file format called
518 out of which no format is given.
520 .. _pdb:
522 pdb
523 ---
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.
537 Example
538 +++++++
540 A pdb file should look like this::
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 ...
549 .. _rtp:
551 rtp
552 ---
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.
567 :ref:`gmx pdb2gmx` automatically generates all angles,
568 this means that the ``[angles]`` field is only
569 useful for overriding :ref:`itp` parameters.
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.
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.
586 A sample is included below.
588 ::
590 [ bondedtypes ] ; mandatory
591 ; bonds angles dihedrals impropers
592 1 1 1 2 ; mandatory
594 [ GLY ] ; mandatory
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
604 [ bonds ] ; optional
605 ;atom1 atom2 b0 kb
606 N H
607 N CA
608 CA C
609 C O
610 -C N
612 [ exclusions ] ; optional
613 ;atom1 atom2
615 [ angles ] ; optional
616 ;atom1 atom2 atom3 th0 cth
618 [ dihedrals ] ; optional
619 ;atom1 atom2 atom3 atom4 phi0 cp mult
621 [ impropers ] ; optional
622 ;atom1 atom2 atom3 atom4 q0 cq
623 N -C CA H
624 -C -CA N -O
627 [ ZN ]
628 [ atoms ]
629 ZN ZN 2.000 0
631 .. _tex:
633 tex
634 ---
636 We use **LaTeX** for *document* processing.
637 Although the input is not so
638 user friendly, it has some advantages over *word* processors.
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...
645 .. _tng:
647 tng
648 ---
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 :ref:`gmx mdrun`, whether data
654 is written with compression, and how lossy that compression can be.
655 This file is in portable binary format and can be read with :ref:`gmx dump`.
657 .. parsed-literal::
659 :ref:`gmx dump` -f traj.tng
661 or if you're not such a fast reader::
663 gmx dump -f traj.tng | less
665 You can also get a quick look in the contents of the file (number of
666 frames etc.) using:
668 .. parsed-literal::
670 :ref:`gmx check` -f traj.tng
672 .. _top:
674 top
675 ---
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).
681 A sample file is included below::
683 ;
684 ; Example topology file
685 ;
686 [ defaults ]
687 ; nbfunc comb-rule gen-pairs fudgeLJ fudgeQQ
688 1 1 no 1.0 1.0
690 ; The force field files to be included
691 #include "rt41c5.itp"
693 [ moleculetype ]
694 ; name nrexcl
695 Urea 3
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
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
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
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
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
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
758 ; Include SPC water topology
759 #include "spc.itp"
761 [ system ]
762 Urea in Water
764 [ molecules ]
765 Urea 1
766 SOL 1000
768 .. _tpr:
770 tpr
771 ---
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:
779 .. parsed-literal::
781 :ref:`gmx dump` -s topol.tpr
783 or if you're not such a fast reader::
785 gmx dump -s topol.tpr | less
787 You can also compare two tpr files using:
789 .. parsed-literal::
791 :ref:`gmx check` -s1 top1 -s2 top2 | less
793 .. _trr:
795 trr
796 ---
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 and can be read with :ref:`gmx dump`::
803 gmx dump -f traj.trr
805 or if you're not such a fast reader::
807 gmx dump -f traj.trr | less
809 You can also get a quick look in the contents of the file (number of
810 frames etc.) using:
812 .. parsed-literal::
814 % :ref:`gmx check` -f traj.trr
816 .. _xpm:
818 xpm
819 ---
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:
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.
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.
847 ::
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"
880 .. _xtc:
882 xtc
883 ---
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.
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>.
901 All the data is stored using calls to *xdr* routines.
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.
920 Using xtc in your "C" programs
921 ++++++++++++++++++++++++++++++
923 To read and write these files the following "C" routines are available::
925 /* All functions return 1 if successful, 0 otherwise */
927 extern int open_xtc(XDR *xd,char *filename,char *mode);
928 /* Open a file for xdr I/O */
930 extern void close_xtc(XDR *xd);
931 /* Close the file for xdr I/O */
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 */
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 */
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 */
948 To use the library function include ``"gromacs/fileio/xtcio.h"``
949 in your file and link with ``-lgmx.$(CPU)``.
951 Using xtc in your FORTRAN programs
952 ++++++++++++++++++++++++++++++++++
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::
958 program testxtc
960 parameter (maxatom=10000,maxx=3*maxatom)
961 integer xd,xd2,natoms,step,ret,i
962 real time,box(9),x(maxx)
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
969 call readxtc(xd,natoms,step,time,box,x,prec,ret)
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
977 stop
978 end
980 To link your program use ``-L$(GMXHOME)/lib/$(CPU) -lxtcf``
981 on your linker command line.
983 .. _xvg:
985 xvg
986 ---
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.
993 A sample Grace session with GROMACS data is shown below:
995 .. image:: xvgr.gif
996 :alt: hallo