MD++ An Example Tcl File - Revision history

Caiwei at 23:28, 4 May 2012

2012-05-04T23:28:14Z

← Older revision		Revision as of 23:28, 4 May 2012
Line 131:		Line 131:

	What happens in this part of the code is the following:		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}

		⚫	* <tt>argc</tt> 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 <tt>argc</tt> equals 0.
	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.
			* <tt>When <tt>argc</tt> equals 0, the code executes the <tt>set status 0</tt> line, which sets the value of the variable <tt>status</tt> 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 <tt>status</tt> 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 <tt>status</tt> is set to that.
		⚫	* <tt>argv</tt> is a build-in array into which the user input (e.g. 1 or 2) is stored and <tt>[lindex $argv 0]</tt> 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 <tt>initmd</tt>. After that, MD++ will perform one of the three possible tasks depending on the <tt>status</tt> variable set by the command line. When <tt>status == 0</tt>, MD++ will perform exactly the same task as described in the example02a-si-md.script file. When <tt>status == 1</tt>, MD++ will read the configuration from a file (created by a previous run with <tt>status == 0</tt>). When <tt>status == 2</tt>, MD++ will load the configuration at the end of an MD simulation (created by a previous run with <tt>status == 0</tt> or <tt>1</tt>) 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.

Caiwei at 20:58, 4 May 2012

2012-05-04T20:58:03Z

← Older revision		Revision as of 20:58, 4 May 2012
Line 99:		Line 99:
	* [http://micro.stanford.edu/wiki/MD%2B%2B_An_Example_Script_File#Relaxation Relaxation]: <tt>relax_fixbox</tt> and <tt>relax_freebox</tt>		* [http://micro.stanford.edu/wiki/MD%2B%2B_An_Example_Script_File#Relaxation Relaxation]: <tt>relax_fixbox</tt> and <tt>relax_freebox</tt>
	* [http://micro.stanford.edu/wiki/MD%2B%2B_An_Example_Script_File#MD_simulation_set_up MD simulation setup]: <tt>setup_md</tt>		* [http://micro.stanford.edu/wiki/MD%2B%2B_An_Example_Script_File#MD_simulation_set_up MD simulation setup]: <tt>setup_md</tt>



	== Main Program ==		== 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.		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
	\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 \\~~		$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~~ ~~file~~ in the ~~following~~ ~~way~~:
	\\\\

	\fcolorbox{black}{gray!20}{\parbox{\linewidth}{

		⚫	The argument at the end of the line is read by the Tcl code in the beginning of the main program:
⚫	~~\tt{~~if \{ \$argc == 0 \} \{ \\
⚫	set status 0\\
⚫	\} elseif \{ \$argc > 0 \} \{ \\
⚫	set status [lindex \$argv 0]
	\} \\
⚫	puts "status = \$status" \\

		⚫	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:		What happens in this part of the code is the following:

Caiwei: /* Visualization and simulation set up */

2012-05-04T20:54:26Z

Visualization and simulation set up

← Older revision		Revision as of 20:54, 4 May 2012
Line 94:		Line 94:
	=== Visualization and simulation set up ===		=== Visualization and simulation set up ===

	The remaining procedures are similarly defined. They encapsulate different sections of the script file described in ~~[http://micro.stanford.edu/wiki/MD%2B%2B_An_Example_Script_File#Initialize_atoms_positions~~ the previous wiki page].		The remaining procedures are similarly defined. They encapsulate different sections of the script file described in the previous wiki page.

	* [http://micro.stanford.edu/wiki/MD%2B%2B_An_Example_Script_File#Plotting_set_up Plotting setup]: <tt>setup_window</tt> and <tt>openwindow</tt>		* [http://micro.stanford.edu/wiki/MD%2B%2B_An_Example_Script_File#Plotting_set_up Plotting setup]: <tt>setup_window</tt> and <tt>openwindow</tt>

Caiwei: /* Defining procedures */

2012-05-04T20:53:46Z

Defining procedures

← Older revision		Revision as of 20:53, 4 May 2012
Line 90:		Line 90:
	* Here we put <tt>MD++</tt> in front of all four lines inside this procedure, instead of enclosing all of them within <tt>MD++ { ... }</tt> as in the definition of <tt>initmd</tt>. This is done intentionally to allow $nx, $ny, $nz to be replaced by the value of arguments passed when procedure <tt>makecrystal</tt> is called (i.e. <tt>4 4 4</tt>).		* Here we put <tt>MD++</tt> in front of all four lines inside this procedure, instead of enclosing all of them within <tt>MD++ { ... }</tt> as in the definition of <tt>initmd</tt>. This is done intentionally to allow $nx, $ny, $nz to be replaced by the value of arguments passed when procedure <tt>makecrystal</tt> is called (i.e. <tt>4 4 4</tt>).
	* There are \ symbols (backslashes) before the [ and ] symbos so that Tcl doesn't interpret them as commands special Tcl commands.		* 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 [http://micro.stanford.edu/wiki/MD%2B%2B_An_Example_Script_File#Initialize_atoms_positions the previous wiki page].

			* [http://micro.stanford.edu/wiki/MD%2B%2B_An_Example_Script_File#Plotting_set_up Plotting setup]: <tt>setup_window</tt> and <tt>openwindow</tt>
			* [http://micro.stanford.edu/wiki/MD%2B%2B_An_Example_Script_File#Relaxation Relaxation]: <tt>relax_fixbox</tt> and <tt>relax_freebox</tt>
			* [http://micro.stanford.edu/wiki/MD%2B%2B_An_Example_Script_File#MD_simulation_set_up MD simulation setup]: <tt>setup_md</tt>

	== Main Program ==		== Main Program ==

Caiwei: /* Defining procedures */

2012-05-04T20:46:37Z

Defining procedures

Show changes

Caiwei: Created page with '
MD++ Tutorial

An Example Tcl File

Saad Bha…'

2012-05-04T20:28:24Z

Created page with ' MD++ Tutorial An Example Tcl File <DIV> Saad Bha…'

New page
 MD++ Tutorial 
 
An Example Tcl File
<DIV>
Saad Bhamla and Wei Cai
</DIV>

This tutorial walks you through a complete .tcl file that performs an MD simulation.

<HR>

Before reading this document, the reader is advised to read the primer of using TCL for MD++ [http://micro.stanford.edu/wiki/M08_MD%2B%2B_Powered_by_Tcl_Language here].

In this document, we will demonstrate how the example script file in the [http://micro.stanford.edu/wiki/MD%2B%2B_An_Example_Script_File | previous wiki page] can be easily converted to a Tcl file to give the add more flexibility and functionality to the code.

== 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 <tt>example02a-si-md.script</tt> 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.

MD++ An Example Tcl File - Revision history

Caiwei at 23:28, 4 May 2012

Caiwei at 20:58, 4 May 2012

Caiwei: /* Visualization and simulation set up */

Caiwei: /* Defining procedures */

Caiwei: /* Defining procedures */

Caiwei: Created page with ' MD++ Tutorial An Example Tcl File Saad Bha…'

Caiwei: Created page with '
MD++ Tutorial

An Example Tcl File

Saad Bha…'