Tools

Introduction

The tools consist of

1. Program chiral which can create nanotubes of a given chiral vector. For creation of multi-wall nanotubes, it has the capability of searching for tubes of a desired radius. It can indicate which tubes are length-compatible (which means that they can be put in the same periodic box without straining, assuming the bond length is constant.) It can also merge different coord.d files, or put several copies of a coord.d file into another one.
2. A set of tools that can do such manipulations as shift and rotate the atom distribution of a coord.d file, change its temperature, time-step, put in Stone-Wales defects, etcetera.
3. A shell Fortran program custom.f that can be used to perform manipulations not covered by the other tools.

More detailed descriptions and usage instructions are below.

Program chiral

In this section we describe how to use program chiral.

Startup:

Chiral first asks for the bond length to use. Just hit Return to use the default value or enter a modified value. Next chiral asks for the temperature in K to give the final coord.d file and the time step to put in the coord.d file.

Next chiral prints out a table for which of the nanotubes are "length compatible", which means that periodic multiwall nanotubes can be constructed of them without straining. Tubes marked with the same symbol are length compatible. Note that this is theoretical compatibility: it assumes the tubes are created by wrapping a graphite sheet with a constant bond length into a cylinder. In real life, there will still be internal stresses in the multiwall tube, especially for small tubes.

The table covers chiral vectors n,m in the range 1 ≤ n ≤ 15, 0 ≤ m ≤ n. Note that the m,n tube is the mirror image of the n,m one, so has the same length.

Adding atoms:

Chiral next displays a small menu, with the choices "vec", "rad", "file", "undo", "done", and "quit". We describe these choices in this order:

• Choice "vec" prompts for the chiral vector n,m of a nanotube to add to the coord.d file. It expects that n is positive and m nonnegative. I prefer this convention since the m,n tube is the mirror image of the n,m tube, giving a length-compatible but different tube. If you try to enter a negative value, the program suggests the equivalent chiral vector having nonnegative values.

  On entering a valid vector, chiral prints out a few statistics, in particular the number of atoms in each period of the tube.

  Next it asks for length and radial stretching factors. These can be used to correct the dimensions for curvature effects and temperature expansion. Hopefully, some day the default will show the true correction factors for the selected tube and temperature; for now the default is one (no stretching.) Chiral prints out the final period length and radius of the nanotube in Angstrom.

  Next it asks for any shift or angular rotation around the z (nanotube) axis you want to apply. This allows you to rotate and shift different tubes in a MWNT relative to each other, or create an array of tubes.

• Choice "rad" searches for a nanotube of a given radius. This allows you to achieve a desired radial spacing of the individual nanotubes within a multiwall nanotube. You enter a desired radius and a maximum allowed deviation from the desired radius, and chiral comes back with a list of nanotubes in that range (with n<100.) It also lists how close they are to the maximum tolerance, in percent, and the ones that are length compatible with the earlier defined nanotubes are marked with a star.

  Chiral then asks you the chiral vector of the nanotube you want to add, with as default the tube it thinks is the best match from the list. Enter "cancel" not to add a tube. Otherwise, the further procedure is as for the "vec" menu item.

• Choice "file" prompts you for a coord.d type file. The atoms in that file are then added to the new coord.d file being created. This gives chiral the capability of merging different coord.d files. For example, assuming an existing coord.d file with a functional group, you can attach that functional group on various places of the nanotube you are creating. Similarly, you can add hydrogen molecules in various places. (See the examples section.)

  Chiral allows you to put in stretching factors, displacements, and rotations as if it was a nanotube.

• Choice "undo" removes the last set of atoms added (nanotube or file) again.
• Choice "done" processes the defined collection of atoms in nanotubes and from files into a coord.d format file. This choice only shows up when there are atoms.

  After you select this choice, and you have defined only one nanotube or read only a single file, chiral asks how many axial periods you want, i.e. the number of times the defined set is repeated in the z-direction. It also asks how big you want to make the periodic box size in the z-direction. Then it writes the coord.d file and exits.

  If, however, you have defined more than one object (nanotube or file data), chiral first checks whether they are length compatible. (Note that varying the length stretching factors destroys length compatibility.) If they are, it tells you how many atoms are in the smallest common period of the tubes, and asks you how many of those common periods you want. It next asks for the periodic box size you want, prints the total number of atoms, and writes the coord.d file.

  If the objects are not length compatible, chiral can still try to find multiples of the defined objects that have the least strain, provided that you tell it how many multiples of the longest (in z-direction) object to use. Chiral then adjusts the multiples of the other objects to match that length with approximately minimum strain. (Assuming that the stiffness of the tubes is proportional to their radius.) You can specify a range of multiples of the longest object to try, in order to find a particularly good match in length. It will keep prompting for such ranges until you specify a range of only one possibility, which it takes as acceptance. It then asks whether it should stretch the objects to exactly the same length, asks for the periodic box size, writes the coord.d file and exits.

• Choice "quit" quits without writing out a coord.d file.

Notes:

• Chiral orders the atoms in a nanotube in order of increasing axial position. In case some atoms have the same axial position, they are ordered further in order of of increasing circumferential angle. Since chiral uses exact arithmetic internally, this can be done without ambiguity.

Manipulation tools

The following tools manipulate coord.d format files.

chbox

Changes the periodic box size without adding atoms. Usually to do other manipulations without worrying about the box boundaries.

chcg

Centers the center of gravity. Subsequently chshift can be used to move it to another place.

chdelta

Change the time step. Takes care of also correcting the Nordsieck parameters r2, r3, and r4.

chfind

Finds the precise location of atoms, bonds, hexagons, given an approximate location.

chlims

Prints out the atom position limits.

chmult

Increase the period sizes by integer multiples. In other words, compute more periods. This can be used to increase the size of the simulation after killing off transients. In that case, use chtemp to destroy the periodicity in kinetic energy.

chrot

Rotates the atom positions. Often around the z-axis to get a rotated nanotube.

chshift

Shift the atom positions.

chtemp

Sets the temperature to a new value. Resets the now meaningless Nordsieck parameters to 0.

defects

Adds 7557 defects to nanutubes in coord.d files. Currently assumes that the nanotube is centered around the z-axis. Use chshift if necessary to achieve that.

getxyz

Creates an xmol xyz file from a coord.d file.

To merge coord.d files, use program chiral.

How to use the tools

Enabling usage:

Here we describe how to enable chiral and the tools on the COE Unix cluster. If you want to use them elsewhere, see the section on installing the tools.

Edit your ".tcshrc" file in your login directory (this is a hidden file) and cut and paste the following lines into this file:

# A command shell to allow input line editing and input line recall
alias con_shell '~dommelen/research/nano/lib/con_shell'
# Create nanotubes and/or merge coord.d type files
alias chiral 'con_shell ~dommelen/research/nano/chiral/chiral2'
# Create 7557 defects in tubes around the z-axis
alias defects 'con_shell ~dommelen/research/nano/coordmod/defects2'
# Extract a plottable xyz file from a coord.d type file
alias getxyz 'con_shell ~dommelen/research/nano/coordmod/getxyz2'
# Change the periodic box size without adding atoms
alias chbox 'con_shell ~dommelen/research/nano/coordmod/chbox2'
# Center the center of gravity
alias chcg 'con_shell ~dommelen/research/nano/coordmod/chcg2'
# change time step and correct the Norsieck parameters correspondingly
alias chdelta 'con_shell ~dommelen/research/nano/coordmod/chdelta2'
# find atoms, bond, hexagons
alias chfind 'con_shell ~dommelen/research/nano/coordmod/chfind2'
# Print out the atom position limits
alias chlims 'con_shell ~dommelen/research/nano/coordmod/chlims2'
# Increase the period sizes by integer multiples
alias chmult 'con_shell ~dommelen/research/nano/coordmod/chmult2'
# Rotates the atom positions
alias chrot 'con_shell ~dommelen/research/nano/coordmod/chrot2'
# Shift the atom positions
alias chshift 'con_shell ~dommelen/research/nano/coordmod/chshift2'
# Set the temperature to a new value
alias chtemp 'con_shell ~dommelen/research/nano/coordmod/chtemp2'

Log file:

All programs keep a log file of all screen output. For example, 'chiral' keeps log file 'chiral.log'. If you are wondering if you made a mistake, or forgot to write some result down, look at 'chiral.log'.

Error recovery

If you did make a mistake, and you do not want to retype everything, exit, copy 'chiral.log' into recovery file 'chiral.rcv' and edit that file to correct your mistake. When running 'chiral' again, it will see the recovery file and take its input from there, instead of from the keyboard. Delete the .rcv file afterwards.

Repeated use

If you need to run one of the program repeatedly, and each time provide similar inputs, you could use a procedure similar to the error recovery above: edit the .rcv file to only retype the variables that change.

Batch use

You could, with some care, write your own program to create .rcv files, and thus run the programs noninteractively.

Command line parameters

If you are running the same tool multiple times, I recommend providing the first few inputs on the command line. For example, 'defects coord.d coord2.d y' to run 'defects' and set the input file to coord.d, the output file to coord2.d and confirm overwrite. The next time you run 'defects', retrieve the command line using the up cursor key, and you won't have to retype the file names again. (Note: this may not work for all installations of the tools.)

Line editing

The cursor keys also work inside the programs to correct input errors and recall earlier inputs. Many queries have a default that you can accept by simply hitting Return, or that disappear automatically as soon as you type something. (Note: this may not work the same way for all installations of the tools.)

Custom manipulations

If the tools do not cover the manipulations you want to do with a coord.d file, you will have to write your own Fortran program. The file custom.f is a good place to start; it is a shell program that is already set up to read in and write out a coord.d file. Just add your custom manipulations to this file and compile it. You can comment away the call to subroutine 'coordg' if no input file is to be read.

The easiest is to use the custom.f file on the COE Unix cluster. (If you want to use it elsewhere, refer to the section on installing the tools.) On the COE Unix cluster, simply copy it over from Leon:
    cp   ~dommelen/research/nano/coordmod/custom.f   .
Edit the file to perform the desired task. Then compile it using the command:
    make   -f   ~dommelen/research/nano/coordmod/makefile
This will create an executable 'custom' in your own directory.

If you want an executable with line editing, append ' custom2' to the above line This one must be run through con_shell, as:
    con_shell   custom2

Examples

1. To create bundles of nanotubes:
   • Run 'chiral' to create a single nanotube of the desired properties in coord.d.
   • Run 'chiral' again, reading the file coord.d inrepeatedly and shifting the tubes to the desired positions.
2. To put matching Stone-Wales defects in multiwall nanotubes:
   • Create the multiwall nanotube using 'chiral'.
   • Use 'defects' to locate bonds in the individual tubes with almost the same axial and angular position. (Typically near theta=0 for the same family; it may be a good idea to have a look at the MWNT using 'getxyz' to produce a Rasmol plotfile from coord.d.) Let 'defects' rotate those bonds to create the matching defects.
3. To attach functional groups to nanotubes:
   • Create a func.d file with the functional group in it, either manually, or, probably better in the long run, by following the procedure in the custom modification section. You may want to align the axis of the group with the x-direction.
   • Use 'chshift' to shift the atom that will attach to the tube wall to the origin. (Use 'chlims' to check where it is initially.)
   • If varying angles between the functional group and the tube wall are desired, at this time use 'chrot' to make func*.d files with the group under the desired angles.
   • Use 'chiral' to create the SWNT or MWNT and note the radius of the outermost tube. Add to that radius the desired distance of the group from the tube wall.
   • Use 'chshift' to shift the func*.d files in the x-direction over that distance.
   • Assuming that you want groups to attach to atoms in the tube wall, use 'chfind' to find the exact z and theta values of atoms at the desired tube wall locations. (To put the groups above hexagon centers, do the same, but note the location of the centers.)
   • Run 'chiral' to combine the tube and functional group coord.d files. Specify the z-shift of the functional group file as the z-position of the atom to attach to and specify the angular rotation as the the theta value of the atom. Do not equalize lengths on exit.

Installation

If you want to use the tools elsewhere than on the COE Unix cluster, you will need to install them. If you do not have a Fortran compiler because you are on M$ Windows, there is a free one at Open Watcom. You also need the ranlib library from netlib.org or provide your own random number generator.

Next you will need to get the Windows source files or unix source files. Unzip them, making sure to preserve the directory structure in the zip file. On Unix, use 'unzip -a'. Subdirectories chiral, coordmod, util, and lib will be created. For various MS Windows compilers, you will have to rename the various .f files into .for files.

In directory lib, you need to compile lib.f, one args... file, and one con... file into object files. Safe choices for the last two are argsgen.f and congen.f, but if you want to enable nice features such as command line variables and line editing, select one targetted to your operating system and compiler. If using Watcom, select argswat.for, conwat.for and conwat2.c. If your compiler does not have a build-in exit subroutine, also compile exitgen.f.

In directory util, compile all .f files into object files.

In directory coordmod look at the Unix makefile to see how to create the individual tools. Tool names that end in a "2" are compiled to allow command line arguments and line editing; the ones without are generic versions suitable for most any compiler. For tools that use the random number generator, replace lib/ranlib.a with the library in which you put the compiled ranlib files, or link in all the individually compiled ranlib files.

Create the chiral tool in directory chiral the same way.

If you compiled for command line editing on Unix, you need to disable the terminal I/O system from messing up your screen. You do that by running the executables through con_shell in the lib directory, eg, 'lib/con_shell chiral/chiral2'.

Verified installation instructions for Sun and Linux are here.