MD++ Tutorial

An Example Tcl File

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 1 Overall Structure of *.tcl files 2 Defining procedures 2.1 Output set up 2.2 Initialize atoms positions 2.3 Visualization and simulation set up 3 Main Program

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 } 

Output set up

To illustrate this with an example,

proc initmd { } { MD++ { 
 setnolog
 setoverwrite 
 dirname = runs/si-example
} }

In this example, the procedure name is initmd and it doesn't accept any arguments. The body begins with a MD++ { to indicate that each of the following statements that follow are MD++ commands and variable assignments. These statements will be passed to the script parser of MD++.

This procedure will be called later in the main Tcl program as

initmd

At that time, three MD++ commands will be executed, which set up the output directory, as described in the previous wiki page.

Initialize atoms positions

The next procedure that is defined instructs MD++ how to create the initial configuration of the atoms. The order in which these procedures are defined is not important as long as they are defined before they are called.

proc makecrystal { nx ny nz } { 
 MD++ crystalstructure = diamond-cubic 
 MD++ latticeconst = 5.4309529817532409 
 MD++ latticesize  = \[ 1 0 0 $nx 0 1 0 $ny 0 0 1 $nz \]
 MD++ makecrystal  finalcnfile = perf.cn writecn
}

Here, the procedure name is makecrystal and it accepts three arguments, which are the number of repeats of the lattice vectors in the x, y, and z directions.

This procedure would be called later called in the main program below as

makecrystal 4 4 4  

which would create an atomic configuration of a perfect crystal structure with 4 repeats along the [100], [010] and [001] directions, as discussed in the previous wiki page.

There are a few subtle points one should notice in this procedure:

• makecrystal is both a Tcl and MD++ variable. This illustrates that one can use the same variable names for a Tcl file. In a Tcl file, the MD++ command must be called with the keyword MD++ in front of it, where as makecrystal by itself is a call to the Tcl procedure defined above.
• Here we put MD++ in front of all four lines inside this procedure, instead of enclosing all of them within MD++ { ... } as in the definition of initmd. This is done intentionally to allow $nx, $ny, $nz to be replaced by the value of arguments passed when procedure makecrystal is called (i.e. 4 4 4).
• There are \ symbols (backslashes) before the [ and ] symbos so that Tcl doesn't interpret them as commands special Tcl commands.

Visualization and simulation set up

The remaining procedures are similarly defined. They encapsulate different sections of the script file described in the previous wiki page.

• Plotting setup: setup_window and openwindow
• Relaxation: relax_fixbox and relax_freebox
• MD simulation setup: setup_md

Main Program

Unlike a script file, a tcl file can be run with an argument in the command line. For example, this Tcl file could be called in the following ways.

$bin/sw_gpp scripts/ME346\/example02a-si-md.tcl

or

$bin/sw_gpp scripts/ME346\/example02a-si-md.tcl 0

or

$bin/sw_gpp scripts/ME346\/example02a-si-md.tcl 1 

or

$bin/sw_gpp scripts/ME346\/example02a-si-md.tcl 2

The argument at the end of the line is read by the Tcl code in the beginning of the main program:

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:

• argc is a built-in Tcl variable which stores the number of arguments on the command line (following the .tcl script). If none is supplied by the user, then argc equals 0.
• When <tt>argc equals 0, the code executes the set status 0 line, which sets the value of the variable status to zero. Therefore, if we run the .tcl script without an argument, the effect is the same as running the .tcl script with argument 0. The value of variable status will be used later to instruct MD++ which tasks to execute.
• Supposing the user did supply an argument (e.g. 1 or 2) when executing the tcl script, then the value of the variable status is set to that.
• argv is a build-in array into which the user input (e.g. 1 or 2) is stored and [lindex $argv 0] retrieves the first element of that array.

The rest of the code is calling of the procedures defined above. The first call is to the procedure initmd. After that, MD++ will perform one of the three possible tasks depending on the status variable set by the command line. When status == 0, MD++ will perform exactly the same task as described in the example02a-si-md.script file. When status == 1, MD++ will read the configuration from a file (created by a previous run with status == 0). When status == 2, MD++ will load the configuration at the end of an MD simulation (created by a previous run with status == 0 or 1) and plot it in the X-window.

This highlights one of the advantages of using a .tcl file over a .script file since multiple related tasks can be defined in one .tcl file and depending on the argument, the specific task is executed. In comparison, if we were to use .script file as the input, then multiple .script files are needed, but they also have sections that are identical. Duplications in the codes needs to be minimized because it habors bugs. Thus, .tcl file makes our input file more modular, easier to read, eliminates redundancy, and less buggy compared to the .script file.