############################################################
#
# PBCWRAP:
# --------
#              
# VERSION: 1.4
#
# REQUIREMENTS:
#   The package PBCtools (v1.1 or later) from the VMD script library.
#
# DESCRIPTION:
#   Wraps atoms of selection around PBC unit cell boundaries.  Unit
#   cell geometry is taken from 'molinfo' or can be read from an
#   XST-file.  The first timestep in the XST is omitted, because XST
#   info starts at frame 0 while DCD files start at frame 1 (when both
#   are generated by NAMD). Other than that you must yourself take care
#   that the XST file entries match with the loaded frames.
#
#   If your XST file contains an unitcell with the first vector not
#   being parallel to the x-axis, then VMD will not display the image
#   cells correctly. The reason is, that VMD follows the standard
#   crystallographic conventions for the meaning of
#   a/b/c/alpha/beta/gamma where vector A is assumed to be parallel to
#   X.  Possible problems arise from the fact that NAMD is able to work
#   with nonstandard unitcell geometries. PBCwrap solves this problem by
#   rotating your system accordingly.
#
# DOWNLOAD FILE:
#   pbcwrap.tcl
#
# PROCEDURES:
#   pbcwrap [OPTIONS...]
#
#   Options:
#     -molid $molid    Wrap molecule $molid (default: "top")
#     -sel $sel	       Wrap the selection $sel of atoms (default: "all")
#     -first $from|now|first
#                      First frame to wrap. "now" denotes the current frame,
#                      "first" denotes the first frame. Otherwise, give the 
#                      number $from of the frame. (default: "now")
#     -last $to|now|last
#                      Last frame to wrap. "now" denotes the current frame, 
#                      "last" denotes the last frame. Otherwise, give the
#                      number $to of the frame. (default: "now")
#     -xst $xstfile    Read the unitcell info from $xstfile. Otherwise, the 
#                      unitcell info has to be set before.
#     -splitresidues   By default atoms will only be wrapped if the entire 
#                      residue lies outside the unit cell. This option can be 
#                      used to override this behaviour.
#     -origin $origin  $origin has to be a Tcl-list containing three numerical 
#                      values $a $b $c. Place the origin of the unitcell at 
#                      ($a*A, $b*B, $c*C). (default: {-0.5 -0.5 -0.5})
#     -positive        Equal to "-origin {0.0 0.0 0.0}".
#     -parallelepiped|-rectangular
#                      Wrap the atoms into the unitcell parallelepiped or the 
#                      corresponding rectangular box. (default: -parallelepiped)
#     (-draw          Draw some test vectors (for debugging))
#
# EXAMPLE USAGE:           
#   require pbcwrap
#   pbcwrap -sel "segname OXY" -xst lox_oxy_equi1-nopi.xst -first 0 -last last
#
#   (This wraps all atoms in the selection $sel around the unitcell defined in the
#    XST file. All loaded frames are processed.)
#
# Author:
#   Jan Saam
#   Institute of Biochemistry, Charite
#   Monbijoustr. 2, Berlin
#   Germany
#   saam@charite.de
#
#   Olaf Lenz
#   olenz _at_ fias.uni-frankfurt.de
#
# Feel free to send comments, bugs, etc.
############################################################