a plugin for VMD
last revision 2nd of February 2014
Thomas Evangelidis (tevang3@gmail.com)
Large trajectories have a lot of redundant hetero compounds which augment their size and render calculations cumbersome. Truncate Trajectory is designed to help you discard these compounds. It works with orthorhombic unit cells and periodic boundary conditions, as it is able to detect periodic contacts with hetero compounds from the 26 nearest cells, and incorporates these compounds to the final trajectory. The dimensions and angles (a, b, c, alpha, beta, and gamma) should be also provided in the original trajectory files. You can define both the number of water molecules and other hetero compounds to keep.
Beta version 0.9 for Linux and Mac can be downloaded from here.
Save and decompress trunctraj0.9.tar.gz preferably inside the default plugins/noarch/tcl/ directory:
tar xvfz trunctraj0.9.tar.gz
Then your are ready to run Truncate Trajectory. If you save it elsewhere then issue the following command in the VMD Tk Console, or even better, add it to your .vmdrc startup file (for unix the path should be $HOME/.vmdrc, if you don't have it then create one; TRUNCTRAJ_HOME is the full path to your trunctraj0.9/ folder):
set auto_path [linsert $auto_path 0 {TRUNCTRAJ_HOME}] # For VMD 1.8.4 and up
or
lappend auto_path {TRUNCTRAJ_HOME} # For VMD 1.8.3
WARNING: Truncate Trajectory uses it own version of bigdcd.tcl, therefore avoid sourcing bigdcd.tcl in the VMD Console or in your .vmdrc file when using the plugin.
To use the plugin from VMD invoke the package with the following command:
package require trunctraj
To run the parallel version you need to have the Bourne shell and Perl installed. It is also recommended to create a symbolic link to the parallel_trunctraj.sh script:
cd TRUNCTRAJ_HOME
sudo ln -s `pwd`/parallel_trunctraj.sh /usr/local/bin/
Then open "parallel_trunctraj.sh" file and set the variables VMD and CatDCD to your VMD and CatDCD executables respectively. For the parallel version it is not necessary to append the TRUNCTRAJ_HOME folder to the auto_path.
USAGE
Open the VMD Tk Console and type "trunctraj" to get a detailed description of the available arguments:
% trunctraj
Info)Usage: trunctraj -psf <psf file> -dcd <dcd file> -waternum <number of waters> -macromol <macromolecule type>
-sel <atomselection> <option1> <option2>...
Info)Switches:
Info) -gui(not supported yet): force graphical interface mode
Info)
Compulsory arguments:
Info) -psf : the path to your psf file
Info) -dcd : the path to your dcd file
Info) -waternum : the number of waters to be included in the final trajectory
Info) -macromol : the type of macromolecule in the trajectory (i.e. "protein", "nucleic", "protein or nucleic" )
Info) -sel : the part of the macromolecule you wish the program to consider when searching for the closed hetero
Info) compounds (i.e. "all", "resid 1 to 50")
Info)
Optional arguments:
Info) -image : wraps the selected atoms of the macromolecule with hetero compounds from the 26 nearest cells
Info) (default is "false": includes only hetero compounds within the unit cell)
Info) -frmoffset : assemble trajectory every frmoffset frames (default is 10)
Info) -addhetero: add athother kind of hetero compounds. Give the segname, number, and type separated
Info) by space (i.e. "ION 4 SOD")
Info) -workdir : the working directory where all the temporary files along with the final trajectory will be saved
Info) -catdcdpath: the path to catdcd (default is /home/thomas/Programs/vmd-1.9.1/installation_dir/lib/plugins/LINUXAMD64/bin/catdcd4.0/catdcd)
Info) -topology : the topology file (default is /home/thomas/Programs/vmd-1.9.1/installation_dir/lib/plugins/noarch/tcl/readcharmmtop1.1/top_all27_prot_lipid_na.inp)
Type "parallel_trunctraj.sh" to see a summary of the usage of the script:
$ parallel_trunctraj.sh
Usage: parallel_trunctraj.sh
-psf <psf topology file>
-dcd <dcd coordinate file>
-waternum <number of waters>
-macromol <macromolecule selection>
-threads <number of threads>
[ -sel <selection to measure distances from> ]
[ -image <consider periodic images (true/false)> ]
[ -workdir <work directory> ]
[ -frmoffset <number of frames to write before concatenating> ]
[ -safemode <leave intermediate trajectory files (true/false)> ]
[ -nicelevel <set job priority (highest -20 to lowest 19)> ]
Compulsory:
-psf : the path to your psf file
-dcd : the path to your dcd file
-waternum : the number of waters to be included in the final trajectory
-macromol : the type of macromolecule in the trajectory (i.e. "protein", "protein and resid 100 to 300 and chain B" ). ALWAYS USE DOUBLE QUOTES!
-threads : the number of threads. Avoid using all available threads, especially with big systems, because you may encounter memory issues
Optional:
-sel : the part of the macromolecule you wish the program to consider when searching for the closed hetero
compounds (i.e. "all", "resid 100 to 150"). ALWAYS USE DOUBLE QUOTES!
-image : wraps the selected atoms of the macromolecule with hetero compounds from the 26 nearest cells. (default is "false":
includes only hetero compounds within the unit cell)
-workdir : the work directory where all the temporary files along with the final trajectory will be saved
-frmoffset : assemble trajectory every frmoffset frames (default is 10). I. e. an frmoffset of 100 means that the program truncates
frames 1-100 and saves them to individual .dcd files, but when it finishes with the 100th frame it will invoke CATDCD to
concatenate them all and create a temporary file called final_100.dcd with the truncated 100 frames. Then it will analyze
frames 201-300, append them to final_100.dcd and rename it to final_200.dcd, and so on. A small frmoffset (e.g. 5) means
this concatenation will happen in too frquently and that will slow down the calculations dramatically as the frame number
increases.
-safemode :leave intermediate trajectory files for debugging.
-nicelevel :set the job priority of the jobs (threads) to be launched; takes values between -20 (highest priority) and 19 (lowest
priority).
A simple usage example: keep the 1000 closest waters to the protein as well as the 3 closest chlorine ions. In the VMD Tk Console write (replace the filepaths given with -psf, -dcd, and -workdir arguments with your own):
package require trunctraj
trunctraj -psf DCD_with_cell.psf -dcd DCD_with_cell.dcd -waternum 1000 -macromol protein -addhetero "ION 3 CLA" -workdir . -frmoffset 100
Below is the unit cell before and after processing. Notice the tail that sticks out of the cell. To wrap it with waters from periodic cells you must add the option "-image true".
To do the same job in parallel using 6 threads issue the following command in a Unix terminal:
parallel_trunctraj.sh -psf DCD_with_cell.psf -dcd DCD_with_cell.dcd -waternum 1000 -macromol protein -addhetero "ION 3 CLA" -workdir `pwd` -frmoffset 100 -threads 6
A more complicated example: keep only chain D and find the closest 300 waters to residues 10 to 15 that stick out of the cell. In the VMD Tk Console write:
package require trunctraj
trunctraj -psf DCD_with_cell.psf -dcd DCD_with_cell.dcd -waternum 300 -macromol "protein and chain D" -sel "resid 10 to 15" -image true -workdir .
-frmoffset 100
Below is the unit cell after processing. Notice that the tail that sticks out of the cell (residues 10 to 15 have been colored yellow) has been wrapped with the 300 closest waters from the nearest cells.
To do the same job in parallel using 6 threads issue the following command in a Unix terminal:
parallel_trunctraj.sh -psf DCD_with_cell.psf -dcd DCD_with_cell.dcd -waternum 300 -macromol "protein and chain D" -sel "resid 10 to 15" -image true -workdir `pwd`
-frmoffset 100 -threads 6
More examples to come soon...
Thomas Evangelidis (tevang3@gmail.com)
I would like to thank Dr Nicholas Glykos for familiarizing me with the concept and guiding me through the first steps of development, Dr Axel Kohlmeyer for his technical support and for adapting bigdcd.tcl to the needs of this plugin, Mr John Stone and the members of the VMD mailing list for their technical assistance.