Tbtools Manual

Introduction

Tbtools is a set of commandline utilities for molecular modeling using the Tersoff-Brenner potential. It was written by Stephen Jordan and completed 2004. Tbtools is written entirely in C. To install it, go into the directory containing the source code and type make. Tbtools has been tested primarily under Linux and True64 Unix, but should probably work fine under all Unices.

Due to various unfortunate limitations of the .pdb file format, tbtools uses .abc files to store atomic coordinates. This is a file format invented by the author of Tbtools. The acronym abc stands for Atoms Bonds and Comments. An abc file consists of a series of lines each of which is one of these three types. Comment lines begin with the word COMM. Atom lines begin with the word ATOM, followed by the atom number, the atom type (H for hydrogen or C for carbon), and the atomic coordinates. Bond lines begin with the word BOND followed by atom numbers of the two atoms that are bonded. The data in the atom and bond entries is whitespace delimited, not fixed-width. The atom and bond entries can also contain additional numerical values, such as bond energies etc. Files in the .abc format can be visualized using Abcmol, which is a version of RasMol modified to handle the .abc format. Abcmol should also compile and run on most Unices.

Tbtools was designed using the Unix philosophy; it is a number of commandline utilities, which are suitable for batch processing and can work together in numerous ways. In fact, parts of the tbtools package are implemented as shell scripts. Specifically, animations of deformation of molecules simulated using the "deform" tool are generated using the shell scripts mkgif.sh and mkmpeg.sh. For mkgif.sh to work you need to have ImageMagick, Gifsicle, and Abcmol installed. For mkmpeg.sh to work you need to have Netpbm and Abcmol installed. Mkgif.sh generates an animated gif whereas mkmpeg.sh generates an mpeg. Because of this mkgif.sh runs faster than mkmpeg.sh but mkmpeg.sh produces a much smaller file as its final result.

Deform Utility and .def File Format

The only utility included in the tbtools package which is not relatively self-explanatory is "deform." This program is used to simulate the behavior of a hydrocarbon molecule being acted upon by moving external objects. For example, the author of tbtools used this utility to invert carbon nanocones by slowly pushing on them with a spherical indenter. The "deform" utility uses the quasi-static approximation. That is, at each stage, the external objects are moved by a small amount and the hydrocarbon molecule is relaxed to its equilibrium configuration relative to the external forces acting upon it. The parameters of the simulation are given in a .def file. The file demo.def provides an example.

A basic .def file consists of fixed sequence of 13 lines specifying various parameters of the simulation, followed by an unlimited number of lines specifying external objects to act on the hydrocarbon molecule. This is followed by a final line with the token "END". The forcers can be of the following types:

BALL	-   Lennard-Jones continuum graphene sphere
PLANE	-   Lennard-Jones continuum graphene plane
HOLE	-   Lennard-Jones continuum graphene plane with circular hole
SQUEEZE	-   Radial squeeze on all atoms
PUSH	-   Specified force-vector acting on a particular atom

BALL    mask  height   radius  dh   dr
PLANE   mask  height   dh
HOLE    mask  height   radius  dh   dr
SQUEEZE mask  strength
PUSH    mask  atom     x       y    z   dx  dy  dz

mask	   acts on
0	   nothing
1	   carbon only
2	   hydrogen only
3	   both

More complicated simulations can be constructed by chaining together multiple actions into a single .def file. As an example, see hysteresis_r.def, which causes the indenter to move in an N steps forward N/2 steps back type of motion.

The first three lines of a .def file are "relativex", "relativey", and "relativez", each followed by a 1 or a 0. Here 1 represents "yes" and 0 represents "no". These provide a way of pinning down the hydrocarbon molecule. If a direction is chosen to be relative, then the values fed to the routines which relax the hydrocarbon molecule will be relative to the molecule's center of mass. Effectively, this is as if the net force in that direction is zero during the simulation. This was used in some nanocone simulations to ensure that the nanocone didn't squirt out from beneath the indenter.

The next three lines are "start", "stop", and "offset". These refer to the stages of the simulation. In a basic simulation the start and offset can simply be set to zero and the stop can be set equal to the number of stages which are desired. Recall that at each stage the external forcers are moved and the hydrocarbon molecule is relaxed. At the end of each stage, an .abc file will be output containing the new configuration of the hydrocarbon molecule. In a more complicated simulation, such as defined in hysteresis_r.def, the start and offset can be used to ensure that the numbering of the .abc output files is consecutive, and therefore suitable for the construction of .gif or .mpeg animations.

The "infile" line gives the path and filename for the .abc file containing the initial configuration of the hydrocarbon molecule. The "digits" line indicates how many digits of precision should be used for the atomic coordinates in the .abc outputs. The "automatic" line indicates whether the bonding between the atoms should be computed automatically using the Tersoff-Brenner potential or whether it should be taken from the input .abc file. Here again 0 means "no" and 1 means "yes."

The "color" line indicates what to put into the extra data field in the BOND lines of the .abc outputs. 0 indicates that nothing should be put there, 1 indicates that the energy of the bond should be put there, and 2 indicates that the relative energy should be put there. The relative energy is the energy of each bond minus the energy of the least energetic bond. In all cases the total external force on each atom will be output as the extra data field in the ATOM lines of the .abc outputs.

In some cases it may be desirable to apply small random perturbations to the atomic coordinates at the beginning of each stage. This can be used to break any symmetries that would be unlikely to be present in the real world, and which could affect the behavior of the molecule, especially with regard to buckling-type behaviors. On the randomization line a 0 indicates that no symmetry breaking perturbations should be applied. Any nonzero value will be used as the random seed. The perturbations on each coordinate of each atom will be uniformly distributed on the range of -0.01 Angstroms to 0.01 Angstroms.

The relaxation of the atomic coordinates is accomplished using the Polak-Ribiere variant of the conjugate gradient method. The "threshold" line indicates the convergence threshold at which the coordinates will be considered sufficiently relaxed and the energy minimization by conjugate gradient will stop. Smaller thresholds indicate more thorough relaxation. A value of around 10^-9 seems to yield good convergence.

During the simulation, various data is recorded in a file with the same base name as the .def file, but with the extension of .dat. The .dat file is in suitable format for use with gnuplot. In addition to the .dat file and the .abc outputs, a file with the same base name as the .def file, but with an extension of .log is produced, which contains a basic transcript of the progress of the simulation as well as any error messages that may have been generated. One of the pieces of data logged in the .dat file is the height of the tip, which is one of the forcers. The "tip" line in the .def file indicates which forcer should be considered the tip. The forcers are numbered based on their order of appearance in the .def file, the first one being numbered 0. As an example, in demo.def the tip is 0, indicating the first forcer, which is a BALL.

Technical Background

The tbtools package is somewhat similar to a number of molecular dynamics packages available on the internet and commercially. However, tbtools is designed for quasi-static simulation, which is distinct from molecular dynamics. In a molecular dynamics simulation, F=ma is iteratively solved to obtain the trajectories of a collection of atoms interacting with each other and perhaps some external forces. This can become computationally intensive if the amount of time being simulated is long. Sometimes, the motions of the external factors acting on a molecule can be much slower than the motions of the atoms composing the molecule itself. In this case, one can make the approximation that the molecule instantly adapts to its lowest energy configuration relative to the instantaneous values of external forcing. This is the quasi-static approximation.

In the tbtools package, the energy minimization is performed using the conjugate gradient method, which is a generic optimization algorithm, which people use for a variety of problems, physically motivated and otherwise. No thermal effects are included in the simulations, which can be said to be at zero temperature.

Earlier it was stated the the external objects are modelled as "continuum Lennard-Jones graphene." Given a continuous density of atoms , each of which generates a Lennard-Jones potential, the total potential will be:

.

This integral can be solved analytically for both the infinite plane and the spherical shell. Let be the 2-dimensional atom density of the material from which the sphere and the plane are constructed. Then


and
.

An analytical solution for the potential of an infinite plane with a circular hole was not found. Therefore the potential was used, where:

.

According to L. Girifalco and R. Lad, J. Chem. Phys. 25, 693 (1956), appropriate Lennard-Jones parameters for carbon are, and . By straightforward geometry, for graphene.

For more information, it may be useful to see the paper culminating from the project which this software was developed for:

Stephen P. Jordan and Vincent H. Crespi, Mechanical manipulation of graphene nanocones: Chiral inversion of a micron-scale three-dimensional object. Phys. Rev. Lett. 93, 255504 (2004)