MD++ Tutorial
An Example Tcl File
Saad Bhamla and Wei Cai
This tutorial walks you through a complete .tcl file that performs an MD simulation.
Before reading this document, the reader is advised to read the primer of using TCL for MD++ here.
In this document, we will demonstrate how the example script file in the | previous wiki page can be easily converted to a Tcl file to give the add more flexibility and functionality to the code.
Contents |
Overall Structure of *.tcl files
In general, a tcl file for MD++ will have the following parts:
- Definition of procedures
- Main program that calls the procedures
The definition of procedures is similar to defining routines or functions in Matlab or C++. This makes it easier perform certain calculations multiple times by just invoking the previously defined function.
The main program in the Tcl file is then able to call the procedures defined above it.
Suppose you have installed MD++ in your $HOME/Codes/MD++ folder.
export MDPP=$HOME/Codes/MD++ cd $MDPP
In this example, we will use the following Tcl file:
$MDPP/scripts/Examples/example02a-si-md.tcl
Using this tcl file, we can perform the same simulation as defined in the example02a-si-md.script file. In addition, this Tcl enables MD++ to carry out a few more related tasks easily.
All characters following the # (pound) sign are comments. They will be ignored by the Tcl parser (and the MD++ program) and we will not discuss them here either.
Defining procedures
Pretty much every Tcl file used in MD++ simulations begins with the definition of procedures. The syntax for procedure definition in Tcl is
proc name { args } { body }
To illustrate this with an example,
proc initmd { } { MD++ {
setnolog
setoverwrite
dirname = runs/si-example
} }
\\ \\ In this example, the procedure name is \tt{initmd} \rm and it doesn't accept any arguments. The body begins with a \tt{MD++\{ } \rm to indicate that each of the following statements that follow are MD++ commands.
This would be called later called in the Main MD code below as \\\\ \fcolorbox{black}{gray!20}{\parbox{\linewidth}{ \tt{initmd } }} \\ \\ and would be interpreted as following: \tt{setnolog} \rm indicates that everything will be printed to screen and the log file created will be empty. If commented, it will create a log in a separate file. Command \tt{set overwrite} \rm allows the new log to overwrite the old log in the directory. If this is commented, it will not overwrite. Finally, \tt{dirname = runs/si-example} \rm denotes the output directory. If it does not exist, it will be created.
Initialize atoms positions
The next procedure that is defined is the configuration of the atoms initially. The order in which these procedures are defined is not important as long as they are defined before the function is called. \\\\
\fcolorbox{black}{gray!20}{\parbox{\linewidth}{ \tt{proc makecrystal \{ nx ny nz \} \{ \\ MD++ crystalstructure = diamond-cubic \\ MD++ latticeconst = 5.4309529817532409 \\MD++ latticesize = \textbackslash[ 1 0 0 \$nx 0 1 0 \$ny 0 0 1 \$nz \textbackslash]\\MD++ makecrystal finalcnfile = perf.cn writecn\\ \} } }}\\\\
Here, the procedure name is \tt{makecrystal} \rm and it accepts three arguments, mainly the no. of repeats of the unit lattice in the x,y and z direction. This would be called later called in the Main MD code below as \\\\ \fcolorbox{black}{gray!20}{\parbox{\linewidth}{ \tt{ makecrystal 4 4 4 } }} \\ \\
which would create an atomic configuration of a perfect crystal structure of the following specifications:
\begin{itemize}
\item \tt{crystalstructure = diamond-cubic} \rm sets up the crystal structure to make a new crystal.
\item\tt{latticeconst = 5.4309529817532409} \rm sets up the lattice constant for the crystal you want to make.
\item Then \tt{latticesize =...} \rm Creates a lattice. The first three values in each line are an axis direction, while the fourth number is the number of repeats of this vector that exists and is provided as an argument when the procedure is called, in this case it is 4. \item Finally, \tt{makecrystal} \rm is the command that actually creates the crystal structure. It first computes the number of atoms to be allocated and then specifies their coordinates. The command \tt{writecn} \rm writes the configuration to a file in the .cn format. \end{itemize}
There are a couple of subtle points one should notice in this procedure:
\begin{enumerate} \item makecrystal is both a TCL and MD++ variable. This illustrates that one can use the same variable names for a Tcl file. The MD++ variables need to have a \tt{MD++} \rm command before them for the Tcl to parse them as MD++ commands. \item There are \textbackslash before the [ ] so that Tcl doesn't interpret them as commands \item In the \tt{initmd} \rm procedure, we had defined \tt{MD++ \{} \rm right at the beginning of the body of the procedure. The other way to do it would be to write \tt{MD++} \rm at the start of every command as in this procedure. Both are equally valid. \end{enumerate}
The rest of the procedures are similar in the way they are defined. The details of each command has been discussed in the MD++ script example \href{http://micro.stanford.edu/wiki/MD%2B%2B_An_Example_Script_File}{here}
Main Program
Unlike a script file, a tcl file can be called with an argument. For e.g. this tcl file could be called in the following ways.
\\\\
\fcolorbox{black}{gray!20}{\parbox{\linewidth}{
\tt{\$bin/sw\_mac scripts/ME346\/example02a-si-md.tcl\\ or \\ \$bin/sw\_mac scripts/ME346\/example02a-si-md.tcl 1 \\ or \\ \$bin/sw\_mac scripts/ME346\/example02a-si-md.tcl 2 \\
} }}\\\\
The argument at the end of the line is read by the tcl file in the following way:
\\\\
\fcolorbox{black}{gray!20}{\parbox{\linewidth}{
\tt{if \{ \$argc == 0 \} \{ \\
set status 0\\
\} elseif \{ \$argc > 0 \} \{ \\
set status [lindex \$argv 0]
\} \\ puts "status = \$status" \\
} }}\\\\
What happens in this part of the code is the following: \begin{itemize} \item \tt{argc} \rm is an in-built Tcl command which stores the value of the argument. If none is supplied by the user, then it defaults to 0. \item The statement \tt{set status 0} \rm sets the value of the variable \tt{status } \rm to 0. This is the default case. \item Supposing the user did supply an argument (e.g. 1 or 2) when executing the tcl script, then the value of the variable \tt{status} \rm is set to that. \item \tt{ \$argv} \rm is an array into which the user input (e.g. 1 or 2) is stored and \tt{[lindex \$argv 0} \rm retrieves the first element of that array. \end{itemize}
The rest of the code is calling of the procedures defined above. The reader is encouraged to notice the different cases defined in this part of the code for each argument specified by the user. This highlights one of the advantages of using a Tcl file over a .script file since multiple cases can be defined in one tcl file and depending on the argument, the specific case is executed. Whereas if a script file were used, then for each case, a separate script file would be needed. Thus, Tcl makes coding easier and eliminates redundancy in the script.