M01 Introduction to MD++

Manual 01 for MD++
Introduction to MD++

Keonwook Kang and Wei Cai

Nov 24 , 2007

---

Overview

MD++ is a molecular dynamics simulation package written in C++. It is originally developed by Wei Cai when he was a graduate student at MIT and still being updated to include more features. MD++ is supposed to run in a Unix/Linux environment. However, if you have cygwin, a linux-like environment installed in your Windows machine, you can also enjoy MD++ there. Currently, this code is designed mainly for studying the atomic behavior in solid crystal materials. It can also be extended to study other systems, such as fluids, polymers and bio-molecules. This document is the first of a series of manuals written for those new to MD simulations. These manuals explain how to use MD++ with simple examples.

---

Installation

The latest version of MD++ code can be downloaded from the web site, http://micro.stanford.edu/~caiwei/Forum/2004-12-12-MD++/. Here we assume that the reader is familiar with basic Unix/Linux shell commands. Before you download MD++ code, we recommend that you make a sub-directory Codes in your home directory.

$ mkdir Codes 
$ cd Codes 

Save the MD++ package in this directory(~/Codes). Suppose the downloaded file is md++-2007-01-07.tar.gz, then we can extract it by,

$ tar -zxvf md++-2007-01-07.tar.gz 

This command creates the MD++ sub-directory and extracts all the files into it. Go to the MD++ directory and make a runs directory if it does not exist.

$ cd MD++; mkdir runs 

To compile the codes in release(R) mode in a Linux system, type

$ make all build=R 

In order to compile MD++ In a different system (such as Windows), you can specify the SYS variable in the command line, such as

$ make all build=R SYS=cygwin 

provided that cygwin is installed. You can also compile MD++ code in an Apple/Machintosh computer, using

$ make all SYS=mac build=R 

By default, SYS=gpp which corresponds to the GNU c++ compiler. If you have the intel c/c++ compiler icc in your system, use SYS=intel to activate icc, which produces much faster executables than GNU c++ compiler. For more SYS values, take a look at the file ~/Codes/MD++/src/Makefie.base. You may get an TCL-related error during compilation. You can bypass this error using, e.g.

$make SYS=cygwin TCL=no 

by suppressing TCL option. After compilation, you have executable files such as fs_gpp, eam_gpp, and sw_gpp in the bin directory. If you just want to compile one executable file, such as fs_gpp, use

$ make fs build=R 

The name of each execution file stands for the potential model that will be used in the atomisitic simulation. For example, fs stands for the Finnis-Sinclair (FS) potential , lj for the Lennard-Jones (LJ) pair potential, eam for the embedded-atom method (EAM) potential, and sw for the Stillinger-Weber (SW) potential. Each potential model is applicable to a group of atomic species. For example, the FS potential was designed for body-centered-cubic (BCC) metals such as Mo, Ta and W. The SW potential was designed for diamond-cubic semiconductors such as Si and Ge. By the way, the executable md_gpp does not contain any potential model. Hence it cannot be used to compute any material properties but it can still be used to display atomic structures.

If you modify the source code (in the src directory), you need to recompile MD++. we recommend you to clean the previous executables and rebuild by typing,

$ make clean; make all build=R 

To see more help on make, type

$ make help 

To check if you successfully install and compile MD++, try to run one of example scripts in the Examples directory, e.g.

$ bin/fs_gpp scripts/Examples/example01-mo.script 

If you want to stop MD++ running, press ctrl+c or close the visualization window.

If you want to run MD++ on a cluster, e.g., on WCR, the following steps should be taken before you compile MD++.

Open the bashrc file by typing the command,

vi .bashrc

And add the following line into the file,

module load intel/intel-9

Then you can go to your MD++ directory and compile MD++ using the similar commands as shown above,

make all SYS=wcr build=R

MD++ Directories

After installation, the MD++ directory will contain the following sub-directories.

$ ls
bin	Doc	makefile	potentials	scripts	Tools
CSD-book	Examples	matlab	README	src

The contents in each directory are described below.

src	source codes
bin	binary executable files generated by make
Doc	manuals
scripts	input script files for running MD++
runs	where the simulation outputs are stored
potentials	potential files to read in
Examples	some example input script files
Tools	pre/post-simulation tools such as atomeye for visualization
matlab	useful Matlab codes.

---

Script File

To execute a molecular simulation, the MD++ code reads an input script file, which contains a series of commands to run and variables to be assigned for the simulation. To create or modify a script file in a Unix/Linux environment, you can use vi, emacs, nedit or any of your favorite editors. For example,

$ vi scripts/example01-mo.script 

or

$ emacs scripts/example01-mo.script &

You can see what is the format by opening one of example script files. All script files have a common head region,

# -*-shell-script-*- 
setnolog                       # No log file saved
setoverwrite                   # Overwrite a log file
dirname = runs/mo-example      # Specify output directory

In a script file, you can commnet out a line or a part of the line by the pound sign, #. You can use # to leave your own comment or explanation anywhere in the script. The first line tells the Emacs editor to use the shell-script mode to display the file. The setnolog command tells MD++ not to create a log file and the outputs will be printed on the screen. If setnolog is commented out, then the outputs will be redirected to a log file A.log in the output directory specified by the variable dirname.
The simulation stops whenever it reaches the quit command. Sometimes it is useful to put sleep before the quit command, such as

sleep quit        # System gets sleep for 600 sec before quit.

The sleep command keeps the visualization window alive for a while during which we can look at the atomic structure. Other commands and variables in the scripts file will be explained in more detail later.

---

Visualization Window Control

When you run MD++, a new window usually pops up through which you can observe the motion of atoms. We refer to this window as the "visualization window". There are several short keys to manipulate the object displayed in this window. For example, to translate the object press t and then use arrow keys. To rotate it, use r and arrow keys. To see more help, press F1, and the following will be printed to the screen (if setnolog is commented out)

Mouse drag to rotate 
Hot Keys: 
F1        : display this message 
Up        : rotate up 
Down      : rotate down 
Left      : rotate left 
Right     : rotate right 
PgUp      : rotate counterclockwise 
PgDn      : rotate clockwise 
Home      : back to initial viewpoint 
Space     : stop rotate 
p         : toggle pause 
t         : translation 
s         : scaling 
d         : move projection infinity point 
r         : rotation 
f         : toggle pbc enableness 
m         : toggle drawframe 
g         : pbc glide 
x         : pbc shift in x 
y         : pbc shift in y
z         : pbc shift in z 
w         : print window specification 
F9        : output gif
F10       : output postscript

---