share/html/online/xtc.html

   1 <title>xtc file format</title>
   2 <LINK rel=stylesheet href="style.css" type="text/css">
   3 <BODY text="#000000" bgcolor="#FFFFFF" link="#0000EF" vlink="#650065" alink="#FF0000">
   4 <h2>xtc file format</h2>
   5 <CENTER><TABLE BORDER=0 CELLSPACING=0 CELLPADDING=0 COLS=2 WIDTH="98%">
   6 <TR>
   7 <TD><font size=-1><A HREF="../online.html">Main Table of Contents</A></font></TD>
   8 <TD ALIGN=RIGHT><B>VERSION 4.0</B></TR>
   9 <TR><TD><font size=-1><A HREF="http://www.gromacs.org">GROMACS homepage</A></font></TD>
  10 <TD ALIGN=RIGHT><B>Sun 18 Jan 2009</B></TR></TABLE></CENTER><HR>
  11 <H3>Description</H3>
  12 The xtc format is a <b>portable</b> format for trajectories.
  13 It uses the <i>xdr</i> routines for writing and reading
  14 data which was created for the Unix NFS system. The trajectories
  15 are written using a reduced precision algorithm which works
  16 in the following way: the coordinates (in nm) are multiplied by a scale
  17 factor, typically 1000, so that you have coordinates in pm.
  18 These are rounded to integer values. Then several other tricks are
  19 performed, for instance making use of the fact that atoms close
  20 in sequence are usually close in space too (e.g. a water molecule).
  21 To this end, the <i>xdr</i> library is extended with a special routine
  22 to write 3-D float coordinates. This routine was written by Frans van Hoesel
  23 as part of an Europort project, and can be obtained through <a href="http://hpcv100.rc.rug.nl/xdrf.html">this link</a>.
  24 <p>
  25 All the data is stored using calls to <i>xdr</i> routines.
  26
  27 <dl>
  28 <dt><b>int</b> magic
  29         <dd>A magic number, for the current file version its value is 1995.
  30 <dt><b>int</b> natoms
  31         <dd>The number of atoms in the trajectory.
  32 <dt><b>int</b> step
  33         <dd>The simulation step.
  34 <dt><b>float</b> time
  35         <dd>The simulation time.
  36 <dt><b>float</b> box[3][3]
  37         <dd>The computational box which is stored as a set of three basis
  38         vectors, to allow for triclinic PBC. For a rectangular box the
  39         box edges are stored on the diagonal of the matrix.
  40 <dt><b>3dfcoord</b> x[natoms]
  41         <dd>The coordinates themselves stored in reduced precision.
  42         Please note that when the number of atoms is smaller than 9
  43         no reduced precision is used.
  44 </dl>
  45
  46 <h3>Using xtc in your "C" programs</h3>
  47 To read and write these files the following "C" routines are available:
  48 <pre>
  49 /* All functions return 1 if successful, 0 otherwise */
  50
  51 extern int open_xtc(XDR *xd,char *filename,char *mode);
  52 /* Open a file for xdr I/O */
  53
  54 extern void close_xtc(XDR *xd);
  55 /* Close the file for xdr I/O */
  56
  57 extern int read_first_xtc(XDR *xd,char *filename,
  58                           int *natoms,int *step,real *time,
  59                           matrix box,rvec **x,real *prec);
  60 /* Open xtc file, read xtc file first time, allocate memory for x */
  61
  62 extern int read_next_xtc(XDR *xd,
  63                          int *natoms,int *step,real *time,
  64                          matrix box,rvec *x,real *prec);
  65 /* Read subsequent frames */
  66
  67 extern int write_xtc(XDR *xd,
  68                      int natoms,int step,real time,
  69                      matrix box,rvec *x,real prec);
  70 /* Write a frame to xtc file */
  71 </pre>
  72 To use the library function include <tt>"xtcio.h"</tt>
  73 in your file and link with <tt>-lgmx.$(CPU)</tt>
  74 <p>
  75
  76 <h3>Using xtc in your FORTRAN programs</h3>
  77 To read and write these in a FORTRAN program use the calls to
  78 <tt>readxtc</tt> and <tt>writextc</tt> as in the following sample program
  79 which reads and xtc file and copies it to a new one:
  80 <pre>
  81       program testxtc
  82
  83       parameter (maxatom=10000,maxx=3*maxatom)
  84       integer xd,xd2,natoms,step,ret,i
  85       real    time,box(9),x(maxx)
  86
  87       call xdrfopen(xd,"test.xtc","r",ret)
  88       print *,'opened test.xtc, ret=',ret
  89       call xdrfopen(xd2,"testout.xtc","w",ret)
  90       print *,'opened testout.xtc, ret=',ret
  91
  92  10   call readxtc(xd,natoms,step,time,box,x,prec,ret)
  93
  94       if ( ret .eq. 1 ) then
  95          call writextc(xd2,natoms,step,time,box,x,prec,ret)
  96       else
  97          print *,'Error reading xtc'
  98       endif
  99
 100       stop
 101       end
 102 </pre>
 103 To link your program use <tt>-L$(GMXHOME)/lib/$(CPU) -lxtcf</tt>
 104 on your linker command line.
 105 The source for this test can be found in file
 106 <tt>$(GMXHOME)/src/gmxlib/testxtcf.f</ff>.
 107 <hr>
 108 <div ALIGN=RIGHT>
 109 <font size="-1"><a href="http://www.gromacs.org">http://www.gromacs.org</a></font><br>
 110 </div>
 111 </body>