NIH Resource for Macromolecular Modeling & Visualization University of Illinois at Urbana-Champaign

PBCTools Plugin, Version 2.7

Please note that this is the documentation of the PBCTools plugin as it comes with the current development version of VMD, and it may therefore not match the plugin version you are using. If you want to find the documentation of a specific version of the plugin, please refer to the PBCTools development page.

The plugin pbctools provides Tcl functions to handle periodic boundary conditions.

1 Basic usage

All of the plugin’s functions can be accessed via the Tcl text command

that you can write in a VMD-Tcl-script or interactively enter in the VMD console window or the VMD TkConsole (accessible via VMD Main Menu → Extensions → Tk Console). When no subcommand is provided, a short help message will be printed. The list of available subcommands can be found in table 1.

2 Installation

Since VMD version 1.8.6, the PBCTools plugin is part of the official distribution of VMD¹, and all commands can be used within VMD without further preparation.

In the case that you are using an older version of VMD, or that you want to use a more recent version of PBCTools than what came with the VMD distribution, you can activate the PBCTools plugin as follows:

1. Fetch the PBCTools plugin from Github
     git clone git://github.com/olenz/pbctools.git

   This will create a new directory pbctools in the current directory.

2. Add the following lines to your VMD startup file (~/.vmdrc on Unix or vmd.rc on Windows)²:
     set dir pbctools-directory
     source $dir/pkgIndex.tcl
     package require pbctools

3 set – Setting the unitcell parameters

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 with help of the command pbc set, or they can be read in from a file in XST format via the procedure pbc readxst (see section 5).

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.

Example

Options

4 get – Getting the unitcell parameters

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.

Example

Options

5 readxst and writexst – Handling XST files

Syntax

pbc readxst xstfile [options…]
pbc writexst xstfile [options…]

Description

Read/write the unit cell information from an XST or XSC file.

Example

Options

6 wrap – Wrapping atoms

Syntax

pbc wrap [options…]

Description

Wrap atoms into a single unitcell.

Example

Options

7 unwrap – 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, and to bonds that stretch the whole box length. 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.

In the case of a simulation trajectory, the following process most probably gives the best result:

1. Go to the first frame.
2. Shape the unitcell of the frame for the best visualization by using the commands
   pbc join -now and pbc wrap -now with appropriate options.
3. Unwrap the trajectory, starting from the current frame, by using
   pbc unwrap -first now.
4. Visually check the result. If the system gets smeared out too fast because the diffusion is too high, repeat the procedure with successively later frames.

Example

Options

8 join – Joining residues, chains, segments, fragments, and connected/bonded groups

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 res[id[ue]], chain, seg[id], fragment or connected.

This procedure can help to remove bonds that stretch the whole box. Note, however, that join is relatively slow and is required only in few cases. If you have a simulation trajectory that contains frames with overstretched bonds, it is usually enough to apply join only to the first frame and then the much faster procedure unwrap to all of the frames:

Note also, that the (faster) default algorithm only works when none of the compounds stretches more than half the periodic box in any direction. With the option -bondlist you can select an alternate algorithm that joins compounds based on direct bonds and does not suffer from this limitation, but can be significantly slower.

Examples

Options

9 box and box_draw – Drawing the unit cell boundaries

9.1 box – Automatically updateing box

Syntax

pbc box [options…]

Description

(Re)Draws a box that shows the boundaries of the unit cell. The box will automatically adapt to changes in the unit cell parameters in the course of a trajectory, as for example for simulations at constant pressure. Only a single automatically updated box can exist at a time.

Example

Options

9.2 box_draw – Drawing a static box

Syntax

pbc box_draw [options…]

Description

Draws a static box that shows the boundaries of the unit cell, but will not adapt to changes in the unitcell properties. 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.

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

10 Credits

The PBCTools plugin has been written by (in alphabetical order)

• Toni Giorgino <toni.giorgino _at_ isib.cnr.it>
• Jerome Henin <jhenin _at_ cmm.upenn.edu>
• Olaf Lenz <olenz _at_ icp.uni-stuttgart.de> (maintainer)
• Cameron Mura <cmura _at_ mccammon.ucsd.edu>
• Jan Saam <saam _at_ charite.de>

The pbcbox procedure copies a lot of the ideas of Axel Kohlmeyer’s script vmd_draw_unitcell. Please submit your bug reports, comments and feature requests on the PBCTools homepage³.

Funded by a grant from
the National Institute of
General Medical Sciences
of the National Institutes
of Health

Beckman Institute for Advanced Science and Technology // National Institutes of Health // National Science Foundation // Physics, Computer Science, and Biophysics at University of Illinois at Urbana-Champaign