by Jerome Henin, Olaf Lenz, Cameron Mura and Jan Saam

This plugin provides procedures to handle periodic boundary conditions, i.e. to set and get the unitcell parameters, to wrap atoms into the central image, to unwrap atoms when they have been wrapped, and to draw the unit cell vectors. All of the procedures are able to handle non-rectangular periodic boundary conditions and changes of the unitcell parameters over time (as for example in constant pressure simulations).

Table of contents

Using the plugin

To use the plugin, put 

package require pbctools
into your Tcl-script or VMD startup file. All of the plugin's functions can be accessed via the Tcl text command 
pbc subcommand
. When no subcommand is provided, a short help message will be printed.

Syntax
pbc subcommand [options...]
Subcommands
set cell [options...]
 Set the VMD unit cell properties. 
readxst xstfile [options...]
 Read the VMD unit cell properties from an XST file. 
get [options...]
 Get the VMD unit cell properties. 
wrap [options...]
 Wrap atoms into a single unit cell. 
unwrap [options...]
 Unwrap atoms so that no wrapping occurs over a series of frames. 
join compound [options...]
 Joins compounds (residues, chains, segments, or bonded atoms) that have been split due to wrapping around the unit cell boundaries, so that they are not split anymore. 
box [options...]
 (Re)Draws an automatically updateing box that shows the boundaries of the unit cell. 
box_draw [options...]
 Draws a static box that shows the boundaries of the unit cell.

Setting the unitcell parameters in VMD

To be able to work correctly, all other procedures of the pbctools plugin require the VMD unitcell parameters to be set. Some file formats and their readers provide the necessary information (e.g. the DCD, VTF and Amber crdbox formats). When the format does not provide the information, the parameters can either be set from the Tcl level with help of the command pbc set, or it can be read in from a file in XST format via the procedure pbc readxst (see below).
Syntax
pbc set cell [options...]
Description
Sets the VMD unit cell properties to cell in the specified frames. cell must either contain a single set of unit cell parameters that will be used in all frames of the molecule, or it must contain a parameter set for every frame.
Options
-molid molid|top
 Which molecule to use (default: top) 
-first frame|first|now
 The first frame to use (default: now) 
-last frame|last|now
 The last frame to use (default: now) 
-all|-allframes
 Equivalent to 
-first first -last last
 
-now
 Equivalent to 
-first now -last now
 
-namd|-vmd
 Format of the unit cell parameters. When -vmd is used, a parameter set must be a list of the VMD unitcell parameters a, b, c and optionally alpha, beta, gamma for non-rectangular unitcells. When -namd is used, a parameter set must contain the three unit cell vectors A, B and C. (default: -vmd) 
-alignx|-noalignx
 If the format NAMD is used, alignx is given and the unit cell vector A is not parallel to the x-axis, the system will be rotated so that it is. If noalignx is given, the function will return with a warning.
Example
pbc set {10.0 10.0 10.0} -all

Reading the unitcell parameters from an XST/XSC file

Syntax
pbc readxst xstfile [options...]
Description
Read the unit cell information from an XST or XSC file.
Options
-molid molid|top
 Which molecule to use (default: top) 
-first frame|first|now
 The first frame to use (default: first) 
-last frame|last|now
 The last frame to use (default: last) 
-all|-allframes
 Equivalent to 
-first first -last last
 
-now
 Equivalent to 
-first now -last now
 
-stride stride
 Read only every stride-th timestep from the file. (default: 1) 
-skipfirst|-noskipfirst
 Whether to skip the first line of the file, or not (default: -skipfirst for XST files, -noskipfirst for XSC files) 
-step2frame num
 Conversion factor between step num in XST file and frame num in DCDs (useful when loading multiple XSTs and want to avoid over-writing info of earlier frames by having a unique mapping between step and frame. 
-alignx|-noalignx
 If alignx is given and the unit cell vector A is not parallel to the x-axis, the system will be rotated so that it is. If noalignx is given, the function will return with a warning. 
-log log
 Log for debugging information.
Example
pbc readxst system.xst

Getting the unitcell parameters from VMD

Syntax
pbc get [options...]
Description
Gets the VMD unit cell properties from the specified frames. Returns a list of one parameter set for each frame or an empty list when an error occured.
Options
-molid molid|top
 Which molecule to use (default: top) 
-first frame|first|now
 The first frame to use (default: now) 
-last frame|last|now
 The last frame to use (default: now) 
-all|-allframes
 Equivalent to 
-first first -last last
 
-now
 Equivalent to 
-first now -last now
 
-namd|-vmd
 Format of the unit cell parameters. When -vmd is used, a parameter set will contains the VMD unitcell parameters a, b, c, alpha, beta, gamma. When -namd is used, a parameter set contains the three unit cell vectors A, B and C. (default: -vmd) 
-[no]check
 Check whether the unit cell parameters seem reasonable, i.e. whether the side lengths are not too small and the angles are not very small or very large.
Example
pbc get -now

Wrapping atoms

Syntax
pbc wrap [options...]
Description
Wrap atoms into the central image of a system with periodic boundary conditions.
Options
-molid molid|top
 Which molecule to use (default: top) 
-first frame|first|now
 The first frame to use (default: now) 
-last frame|last|now
 The last frame to use (default: now) 
-all|-allframes
 Equivalent to 
-first first -last last
 
-now
 Equivalent to 
-first now -last now
 
-parallelepiped|-rectangular
 Wrap the atoms into the unitcell parallelepiped or the corresponding rectangular box with the same volume and center as the (nonorthogonal) unitcell. The unitcell displacement vectors are not changed. (default: -parallelepiped) 
-sel sel
 The selection of atoms to be wrapped (default: all). 
-nocompound|-compound res[idue]|seg[ment]|chain
 Defines, which atom compounds should be kept together, i.e. atoms will not be wrapped if a compound would be split. (default: residue) 
-nocompoundref|-compoundref refsel
 When compounds have been defined via the -compound option, this defines a reference selection of atoms. After the wrapping, at least one of the atoms in this selection will be in the central image. This can be useful, for example, when water molecules should be wrapped such that the oxygen atom ends up in the central image. (default: -norefsel) 
-center origin|unitcell|sel
 Set the center of the wrapping cell to the origin, to the center of the unit cell or to the center of the enclosing box of a given selection sel. (default: unitcell) 
-shiftcenter shift
 Shift the center of the wrapping cell by shift. shift has to be a list of three numerical values. (default: {0 0 0}) 
-shiftcenterrel shift
 Shift the center of the wrapping cell by shift (in units of the unit cell vectors). $shift has to be a list of three umerical values. (default: {0 0 0}) 
-verbose
 Increase verbosity of the function (for debugging). (default: off) 
-draw|-nodraw
 Draw some test vectors (for debugging). (default: -nodraw)
Example
pbc wrap -rectangular -shiftcenterrel {0.5 0.5 0.5}

Unwrapping atoms

Syntax
pbc unwrap [options...]
Description
If a simulation only saves the central image coordinates of a system, atoms are wrapped around when they reach the boundaries. This leads to big jumps in the coordinates of the atoms. This procedure will reverse these jumps and make the movement of the atoms continuous over a series of frames. This process is not necessarily unique, so this procedure can NOT exactly reverse the effects of the command pbc wrap.
Options
-molid molid|top
 Which molecule to use (default: top) 
-first frame|first|now
 The first frame to use (default: now) 
-last frame|last|now
 The last frame to use (default: now) 
-all|-allframes
 Equivalent to 
-first first -last last
 
-now
 Equivalent to 
-first now -last now
 
-sel sel
 The selection of atoms to be unwrapped (default: all). 
-verbose
 Increase verbosity of the function (for debugging). (default: off)

Joining compounds

Syntax
pbc join compound [options...]
Description
Joins compounds of type compound of atoms that have been split due to wrapping around the unit cell boundaries, so that they are not split anymore. compound must be one of the values residue, chain, segment or bonded.
Options
-molid molid|top
 Which molecule to use (default: top) 
-first frame|first|now
 The first frame to use (default: now) 
-last frame|last|now
 The last frame to use (default: now) 
-all|-allframes
 Equivalent to 
-first first -last last
 
-now
 Equivalent to 
-first now -last now
 
-sel sel
 The selection of atoms to be unwrapped (default: all). 
-noref|-ref refsel
 This defines a reference selection of atoms. When joining compounds, the first atom matching the selection in each compound will be chosen, and all atoms will be wrapped into a unit cell around this atom. If noref is given, the first atom in the compound is the reference atom. (default: -noref) 
-verbose
 Increase verbosity of the function (for debugging). (default: off)

Drawing the unit cell boundaries

Syntax
pbc box [options...]
Description
(Re)Draws a box that shows the boundaries of the unit cell. The box will automatically update when the frame is changed and the unit cell parameters change.
Options
-molid molid|top
 Which molecule to use (default: top) 
-on|-off|-toggle
 Turn the box on, off, or toggle. (default: on) 
-parallelepiped|-rectangular
 Draw the box as a parallelpiped, or as the corresponding rectangular box. (default: -parallelepiped) 
-color color
 Draw the box in color color. (default: blue) 
-style lines|dashed|arrows|tubes
 Choose the style of the box (default: lines). 
-width width
 Define the width of the lines/arrows/tubes (default: 3). 
-resolution res
 Use resolution faces for the tube style (default: 8). 
-center origin|unitcell|sel
 Set the center of the box to the origin, to the center of the unit cell or to the center of the enclosing box of a given selection sel. (default: unitcell) 
-shiftcenter shift
 Shift the center of the box by shift. shift has to be a list of three numerical values. (default: {0 0 0}) 
-shiftcenterrel shift
 Shift the center of the box by shift (in units of the unit cell vectors). $shift has to be a list of three umerical values. (default: {0 0 0})
Example
pbc box -center unitcell

Drawing a static box

It is also possible to draw a static box around the unit cell boundaries with help of the command pbc box_draw that is not automatically updated. This might be useful when you want to draw more than one box at a time (e.g. to show periodic images of a box), or to show the initial box in a simulation with fluctuating box unit cell geometry.
Syntax
pbc box_draw [options...]
or 
draw molid pbcbox [options...]
Description
Draw a static box that shows the boundaries of the unit cell. The procedure returns a list of VMD GIDs that can be used to delete the box.
Options
pbc box_draw uses the same options as the command pbc box, with the exception of the options -on|-off|-toggle and -color, which can not be used. To set the color of the box, use the graphics color command.
Example
  # draw a box around the central image
  set box0 [pbc box_draw -shiftcenterrel { 0 0 0 }]
  # draw a box around the cenral image shifted by the unit cell vector C 
  set box1 [pbc box_draw -shiftcenterrel { 0 0 1 }]

History

In the following, we list the user-visible changes in the pbctools plugin.

User-visible changes since v2.0

Initial version

Several mainly independent scripts written by different authors from the script library have been assembled to form the pbctools plugin.

Credits

The PBCTools plugin has been written by The pbcbox procedure copies a lot of the ideas of Axel Kohlmeiers script vmd_draw_unitcell.