Merge branch 'release-4-5-patches' of git@git.gromacs.org:gromacs into release-4...

[gromacs/rigid-bodies.git] / man / man1 / trjconv.1

.TH trjconv 1 "Thu 26 Aug 2010" "" "GROMACS suite, VERSION 4.5"
.SH NAME
trjconv - converts and manipulates trajectory files

.B VERSION 4.5
.SH SYNOPSIS
\f3trjconv\fP
.BI "\-f" " traj.xtc "
.BI "\-o" " trajout.xtc "
.BI "\-s" " topol.tpr "
.BI "\-n" " index.ndx "
.BI "\-fr" " frames.ndx "
.BI "\-sub" " cluster.ndx "
.BI "\-drop" " drop.xvg "
.BI "\-[no]h" ""
.BI "\-[no]version" ""
.BI "\-nice" " int "
.BI "\-b" " time "
.BI "\-e" " time "
.BI "\-tu" " enum "
.BI "\-[no]w" ""
.BI "\-xvg" " enum "
.BI "\-skip" " int "
.BI "\-dt" " time "
.BI "\-[no]round" ""
.BI "\-dump" " time "
.BI "\-t0" " time "
.BI "\-timestep" " time "
.BI "\-pbc" " enum "
.BI "\-ur" " enum "
.BI "\-[no]center" ""
.BI "\-boxcenter" " enum "
.BI "\-box" " vector "
.BI "\-trans" " vector "
.BI "\-shift" " vector "
.BI "\-fit" " enum "
.BI "\-ndec" " int "
.BI "\-[no]vel" ""
.BI "\-[no]force" ""
.BI "\-trunc" " time "
.BI "\-exec" " string "
.BI "\-[no]app" ""
.BI "\-split" " time "
.BI "\-[no]sep" ""
.BI "\-nzero" " int "
.BI "\-dropunder" " real "
.BI "\-dropover" " real "
.BI "\-[no]conect" ""
.SH DESCRIPTION
\&trjconv can convert trajectory files in many ways:

\&\fB 1.\fR from one format to another

\&\fB 2.\fR select a subset of atoms

\&\fB 3.\fR change the periodicity representation

\&\fB 4.\fR keep multimeric molecules together

\&\fB 5.\fR center atoms in the box

\&\fB 6.\fR fit atoms to reference structure

\&\fB 7.\fR reduce the number of frames

\&\fB 8.\fR change the timestamps of the frames 
\&(\fB \-t0\fR and \fB \-timestep\fR)

\&\fB 9.\fR cut the trajectory in small subtrajectories according
\&to information in an index file. This allows subsequent analysis of
\&the subtrajectories that could, for example be the result of a
\&cluster analysis. Use option \fB \-sub\fR.
\&This assumes that the entries in the index file are frame numbers and
\&dumps each group in the index file to a separate trajectory file.

\&\fB 10.\fR select frames within a certain range of a quantity given
\&in an \fB .xvg\fR file.


\&The program \fB trjcat\fR can concatenate multiple trajectory files.
\&


\&Currently seven formats are supported for input and output:
\&\fB .xtc\fR, \fB .trr\fR, \fB .trj\fR, \fB .gro\fR, \fB .g96\fR,
\&\fB .pdb\fR and \fB .g87\fR.
\&The file formats are detected from the file extension.
\&The precision of \fB .xtc\fR and \fB .gro\fR output is taken from the
\&input file for \fB .xtc\fR, \fB .gro\fR and \fB .pdb\fR,
\&and from the \fB \-ndec\fR option for other input formats. The precision
\&is always taken from \fB \-ndec\fR, when this option is set.
\&All other formats have fixed precision. \fB .trr\fR and \fB .trj\fR
\&output can be single or double precision, depending on the precision
\&of the trjconv binary.
\&Note that velocities are only supported in
\&\fB .trr\fR, \fB .trj\fR, \fB .gro\fR and \fB .g96\fR files.


\&Option \fB \-app\fR can be used to
\&append output to an existing trajectory file.
\&No checks are performed to ensure integrity
\&of the resulting combined trajectory file.


\&Option \fB \-sep\fR can be used to write every frame to a separate
\&.gro, .g96 or .pdb file, default all frames all written to one file.
\&\fB .pdb\fR files with all frames concatenated can be viewed with
\&\fB rasmol \-nmrpdb\fR.


\&It is possible to select part of your trajectory and write it out
\&to a new trajectory file in order to save disk space, e.g. for leaving
\&out the water from a trajectory of a protein in water.
\&\fB ALWAYS\fR put the original trajectory on tape!
\&We recommend to use the portable \fB .xtc\fR format for your analysis
\&to save disk space and to have portable files.


\&There are two options for fitting the trajectory to a reference
\&either for essential dynamics analysis or for whatever.
\&The first option is just plain fitting to a reference structure
\&in the structure file, the second option is a progressive fit
\&in which the first timeframe is fitted to the reference structure 
\&in the structure file to obtain and each subsequent timeframe is 
\&fitted to the previously fitted structure. This way a continuous
\&trajectory is generated, which might not be the case when using the
\&regular fit method, e.g. when your protein undergoes large
\&conformational transitions.


\&Option \fB \-pbc\fR sets the type of periodic boundary condition
\&treatment:

\&* \fB mol\fR puts the center of mass of molecules in the box.

\&* \fB res\fR puts the center of mass of residues in the box.

\&* \fB atom\fR puts all the atoms in the box.

\&* \fB nojump\fR checks if atoms jump across the box and then puts
\&them back. This has the effect that all molecules
\&will remain whole (provided they were whole in the initial
\&conformation), note that this ensures a continuous trajectory but
\&molecules may diffuse out of the box. The starting configuration
\&for this procedure is taken from the structure file, if one is
\&supplied, otherwise it is the first frame.

\&* \fB cluster\fR clusters all the atoms in the selected index
\&such that they are all closest to the center of mass of the cluster
\&which is iteratively updated. Note that this will only give meaningful
\&results if you in fact have a cluster. Luckily that can be checked
\&afterwards using a trajectory viewer. Note also that if your molecules
\&are broken this will not work either.

\&* \fB whole\fR only makes broken molecules whole.


\&Option \fB \-ur\fR sets the unit cell representation for options
\&\fB mol\fR, \fB res\fR and \fB atom\fR of \fB \-pbc\fR.
\&All three options give different results for triclinic boxes and
\&identical results for rectangular boxes.
\&\fB rect\fR is the ordinary brick shape.
\&\fB tric\fR is the triclinic unit cell.
\&\fB compact\fR puts all atoms at the closest distance from the center
\&of the box. This can be useful for visualizing e.g. truncated
\&octahedrons. The center for options \fB tric\fR and \fB compact\fR
\&is \fB tric\fR (see below), unless the option \fB \-boxcenter\fR
\&is set differently.


\&Option \fB \-center\fR centers the system in the box. The user can
\&select the group which is used to determine the geometrical center.
\&Option \fB \-boxcenter\fR sets the location of the center of the box
\&for options \fB \-pbc\fR and \fB \-center\fR. The center options are:
\&\fB tric\fR: half of the sum of the box vectors,
\&\fB rect\fR: half of the box diagonal,
\&\fB zero\fR: zero.
\&Use option \fB \-pbc mol\fR in addition to \fB \-center\fR when you
\&want all molecules in the box after the centering.


\&With \fB \-dt\fR it is possible to reduce the number of 
\&frames in the output. This option relies on the accuracy of the times
\&in your input trajectory, so if these are inaccurate use the
\&\fB \-timestep\fR option to modify the time (this can be done
\&simultaneously). For making smooth movies the program \fB g_filter\fR
\&can reduce the number of frames while using low\-pass frequency
\&filtering, this reduces aliasing of high frequency motions.


\&Using \fB \-trunc\fR trjconv can truncate \fB .trj\fR in place, i.e.
\&without copying the file. This is useful when a run has crashed
\&during disk I/O (one more disk full), or when two contiguous
\&trajectories must be concatenated without have double frames.


\&\fB trjcat\fR is more suitable for concatenating trajectory files.


\&Option \fB \-dump\fR can be used to extract a frame at or near
\&one specific time from your trajectory.


\&Option \fB \-drop\fR reads an \fB .xvg\fR file with times and values.
\&When options \fB \-dropunder\fR and/or \fB \-dropover\fR are set,
\&frames with a value below and above the value of the respective options
\&will not be written.
.SH FILES
.BI "\-f" " traj.xtc" 
.B Input
 Trajectory: xtc trr trj gro g96 pdb cpt 

.BI "\-o" " trajout.xtc" 
.B Output
 Trajectory: xtc trr trj gro g96 pdb 

.BI "\-s" " topol.tpr" 
.B Input, Opt.
 Structure+mass(db): tpr tpb tpa gro g96 pdb 

.BI "\-n" " index.ndx" 
.B Input, Opt.
 Index file 

.BI "\-fr" " frames.ndx" 
.B Input, Opt.
 Index file 

.BI "\-sub" " cluster.ndx" 
.B Input, Opt.
 Index file 

.BI "\-drop" " drop.xvg" 
.B Input, Opt.
 xvgr/xmgr file 

.SH OTHER OPTIONS
.BI "\-[no]h"  "no    "
 Print help info and quit

.BI "\-[no]version"  "no    "
 Print version info and quit

.BI "\-nice"  " int" " 19" 
 Set the nicelevel

.BI "\-b"  " time" " 0     " 
 First frame (ps) to read from trajectory

.BI "\-e"  " time" " 0     " 
 Last frame (ps) to read from trajectory

.BI "\-tu"  " enum" " ps" 
 Time unit: \fB fs\fR, \fB ps\fR, \fB ns\fR, \fB us\fR, \fB ms\fR or \fB s\fR

.BI "\-[no]w"  "no    "
 View output xvg, xpm, eps and pdb files

.BI "\-xvg"  " enum" " xmgrace" 
 xvg plot formatting: \fB xmgrace\fR, \fB xmgr\fR or \fB none\fR

.BI "\-skip"  " int" " 1" 
 Only write every nr\-th frame

.BI "\-dt"  " time" " 0     " 
 Only write frame when t MOD dt = first time (ps)

.BI "\-[no]round"  "no    "
 Round measurements to nearest picosecond

.BI "\-dump"  " time" " \-1    " 
 Dump frame nearest specified time (ps)

.BI "\-t0"  " time" " 0     " 
 Starting time (ps) (default: don't change)

.BI "\-timestep"  " time" " 0     " 
 Change time step between input frames (ps)

.BI "\-pbc"  " enum" " none" 
 PBC treatment (see help text for full description): \fB none\fR, \fB mol\fR, \fB res\fR, \fB atom\fR, \fB nojump\fR, \fB cluster\fR or \fB whole\fR

.BI "\-ur"  " enum" " rect" 
 Unit\-cell representation: \fB rect\fR, \fB tric\fR or \fB compact\fR

.BI "\-[no]center"  "no    "
 Center atoms in box

.BI "\-boxcenter"  " enum" " tric" 
 Center for \-pbc and \-center: \fB tric\fR, \fB rect\fR or \fB zero\fR

.BI "\-box"  " vector" " 0 0 0" 
 Size for new cubic box (default: read from input)

.BI "\-trans"  " vector" " 0 0 0" 
 All coordinates will be translated by trans. This can advantageously be combined with \-pbc mol \-ur compact.

.BI "\-shift"  " vector" " 0 0 0" 
 All coordinates will be shifted by framenr*shift

.BI "\-fit"  " enum" " none" 
 Fit molecule to ref structure in the structure file: \fB none\fR, \fB rot+trans\fR, \fB rotxy+transxy\fR, \fB translation\fR, \fB transxy\fR or \fB progressive\fR

.BI "\-ndec"  " int" " 3" 
 Precision for .xtc and .gro writing in number of decimal places

.BI "\-[no]vel"  "yes   "
 Read and write velocities if possible

.BI "\-[no]force"  "no    "
 Read and write forces if possible

.BI "\-trunc"  " time" " \-1    " 
 Truncate input trj file after this time (ps)

.BI "\-exec"  " string" " " 
 Execute command for every output frame with the frame number as argument

.BI "\-[no]app"  "no    "
 Append output

.BI "\-split"  " time" " 0     " 
 Start writing new file when t MOD split = first time (ps)

.BI "\-[no]sep"  "no    "
 Write each frame to a separate .gro, .g96 or .pdb file

.BI "\-nzero"  " int" " 0" 
 Prepend file number in case you use the \-sep flag with this number of zeroes

.BI "\-dropunder"  " real" " 0     " 
 Drop all frames below this value

.BI "\-dropover"  " real" " 0     " 
 Drop all frames above this value

.BI "\-[no]conect"  "no    "
 Add conect records when writing pdb files. Useful for visualization of non\-standard molecules, e.g. coarse grained ones

.SH SEE ALSO
.BR gromacs(7)

More information about \fBGROMACS\fR is available at <\fIhttp://www.gromacs.org/\fR>.