Note: a graphical version of this manual is provided by
tbtools_manual.html.

INTRODUCTION

Tbtools is a set of commandline utilities for molecular modeling
using the Tersoff-Brenner potential. It was written by Stephen Jordan
and completed in 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

Tho 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

The forcers take the following parameters:

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

The mask indicates what types of atom the forcer should act upon. The
more significant bit indicates whether the forcer should act on
hydrogen and the less significant bit indicates whether the forcer
should act on carbon. In other words:

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

Because tbtools was originally developed for nanocone inversion, all
of the forcers are centered at x=0, y=0. The entries labeled dh, dr,
dx, dy, and dz, represent motions. A simulation consists of a series
of stages, and at each stage the external forcers can move. Dh
indicates the change in height per stage, dr the change in radius per
stage, dx the change in x-coordinate per stage and so on. The units
used in a .def file, as well as throughout the tbtools package are
electron volts and angstroms (forces are in eV/A). More detail about
how the forcers work can be obtained by examining force.c and defs.c.

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 potential used in the Tbtools package is defined in:

D. W. Brenner, O. A. Shenderova, J. A. Harrison, B. S. J. Stuart,
B. Ni, and S. B. Sinnot, J. Phys.:Condens. Matter 14, 783 (2002).

Tbtools does not use ab initio calculations of the electron
wavefunction within the hydrocarbon molecule. Rather it uses the
empirical potential of Brenner, et. al., which is a parametrization of
results obtained from ab initio calculations as well as from
experiment.

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.

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

S. P. Jordan and V. H. Crespi, Mechanical manipulation of carbon
nanocones: Chiral inversion of a micron-scale three-dimensional
object.
