Wiki

To help new users, a few examples are provided along with the source code. This should help you kickstart your experience with nanoSCULPT. Currently, i.e. v1.2, we have two examples that we hope will be useful in understanding the working of nanoSCULPT.

##Example 1: Teddy Bear## This example pertains to the teddy bear structure shown in the main page of the wiki, which is also the graphical abstract of the nanoSCULPT paper. The structure was used to illustrate the working principle of nanoSCULPT in the paper.

FURTHER DESCRIPTION TO FOLLOW

##Example 2: Nanocrystalline structure## The second example pertains to the generation of polycrystalline structures, in particular for the study of nanocrystalline materials. The most commonly used method for generating polycrystalline structures is the Voronoi tessellation (See fig. 2 of the nanoSCULPT paper ).

In what follows, we provide a step-by-step procedure of generating a nanocrystalline structure using nanoSCULPT. Most of the scripts/programs required for this exam are provided in the util directory of nanoSCULPT.

####Step 1: Compile the required auxiliary programs Change to the util directory.

cd <nanoSCULPT_baseDir/util

Run the script compileUtil_forNanosculpt.bsh

./compileUtil_forNanosculpt.bsh

The script compiles the two *.c in the directory. If you have gcc installed on your machine, the script should run without problems.

####Step 2: Download and compile the Qhull program suite To generate the Voronoi structure, we will leverage well known programs of the Qhull program suite, which can be downloaded from http://qhull.org. The following instructions, as obtained from the Qhull package, should help you compile and obtain the requisite binaries

To build Qhull, static libraries, shared library, and C++ interface
   * Download and extract Qhull (either GitHub, .tgz file, or .zip file)
   * make
   * export LD_LIBRARY_PATH=$PWD/lib:$LD_LIBRARY_PATH

After compilation, you should find the required executables in a newly created bin directory. Please note down the path to this bin directory of Qhull, as this will required in the next step.

####Step3: Generate OBJ files for the structure of interest Change to the Nanocrys_Voronoi3D directory under the examples directory.

cd $nanoSCULPT_BaseDir/examples/Nanocrys_Voronoi3D

Edit the file QHULLDIR so that it contains the path to the bin directory of Qhull, which we obtained in the previous step.

vi QHULLDIR

Once this is done, you can run the script makeVoronoiOBJfiles_forNanosculpt.bsh. Merely running the script without any arguments displays a help message with the usage syntax of the script.

$>./makeVoronoiOBJfiles_forNanosculpt.bsh

********************************************************************************************************
  nanoSCULPT: A tool to generate complex and realistic configurations for atomistic simulations        
  Copyright (C) 2011-2016
  @authors: A. Prakash, M. Hummel, S. Schmauder and E. Bitzek
-----------------------------------------------------------------
  Version 1.2
-----------------------------------------------------------------
  makeVoronoiOBJfiles_forNanosculpt.bsh --> Script to generate OBJ files of Voronoi crystals
                              --> The OBJ files can then be used for filling atoms with nanoSCULPT      
  @author(s) of current script: A. Prakash and E. Bitzek
********************************************************************************************************

    Usage: makeVoronoiOBJfiles_forNanosculpt.bsh <Flag for generating/reading Grain centers> <Grain center file / PBCboxsizes> <NumOfGrains> <Output Dir for OBJ files> <String for identifying Sample>
---------------------------------------------------
    Example for generating 20 Voronoi grains with random grain centers in a box of 100x100x100:
      $> makeVoronoiOBJfiles_forNanosculpt.bsh 0 100.0 20 OBJdir/ Example1NCvoronoi
---------------------------------------------------
    Example for generating 100 Voronoi grains, with centers defined in a file, in a box of 100x150x250:
      $> makeVoronoiOBJfiles_forNanosculpt.bsh 0 100.0 150.0 250.0 100 OBJdir/ Example2NCvoronoi
---------------------------------------------------

In the current example, we generate a periodic polycrystal with 25 grains, in a box of size 120x180x150 A^3. The centers of the grain are chosen to be randomly spaced inside the box.

$>./makeVoronoiOBJfiles_forNanosculpt.bsh 0 120.0 180.0 150.0 25 OBJdir/ Example1NCvoronoi

should provide the following output

********************************************************************************************************
  nanoSCULPT: A tool to generate complex and realistic configurations for atomistic simulations        
  Copyright (C) 2011-2016
  @authors: A. Prakash, M. Hummel, S. Schmauder and E. Bitzek
-----------------------------------------------------------------
  Version 1.2
-----------------------------------------------------------------
  makeVoronoiOBJfiles_forNanosculpt.bsh --> Script to generate OBJ files of Voronoi crystals
                              --> The OBJ files can then be used for filling atoms with nanoSCULPT      
  @author(s) of current script: A. Prakash and E. Bitzek
********************************************************************************************************
      ---> Cmd executed: makeVoronoiOBJfiles_forNanosculpt.bsh 0 120.0 180.0 150.0 25 OBJdir1/ Example1NCvoronoi <---

     NANOSCULPT base directory:  /Users/Arun/Bitbucket/nanosculpt
     QHULL  directory:  /Users/Arun/bin/qhull-2015.2/bin
     number of command line parameters used for current run 7
     Date:  Sat Jun 4 00:33:11 CEST 2016
     Logfile for storing stdout:  makeVoronoiOBJfiles_forNanosculpt_20160604003311.stdout
---------------------------------------------------
+++++++++++++++++++++++++++++++++++++++++++++++++++
    Generating random grain centers for Voronoi tessellation (prog: generate_random_grain_centers_w_pbc)...
-------------------------------------------------------------
      Creating 25 grain centers in a 120.000000x120.000000x120.000000 Angstrom^3 box
      Average grain volume 69120.000000 Angstrom^3 average (spherical) grain diameter: 50.917652 Angstrom
       Grain centers are written out to grain_centers_pbc.dat
      wrote 675 grains under pbc in all direction, should be 25*27=675
-------------------------------------------------------------
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
    Generating OBJ files for use with nanoSCULPT
      Input values:
             File containing grain centers:  grain_centers_pbc.dat
             Number of grains:  25
             Output Directory of OBJ files:  OBJdir1/
             String for identifying sample:  Example1NCvoronoi
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
j= 0
grain 1
j= 1
grain 2
j= 2
grain 3
j= 3
grain 4
j= 4
grain 5
j= 5
grain 6
j= 6
grain 7
j= 7
grain 8
j= 8
grain 9
j= 9
grain 10
j= 10
grain 11
j= 11
grain 12
j= 12
grain 13
j= 13
grain 14
j= 14
grain 15
j= 15
grain 16
j= 16
grain 17
j= 17
grain 18
j= 18
grain 19
j= 19
grain 20
j= 20
grain 21
j= 21
grain 22
j= 22
grain 23
j= 23
grain 24
j= 24
grain 25

The above messages on stdout are also written to a log file. The log file is named makeVoronoiOBJfiles_forNanosculpt_<DateStr>.stdout. The <DateStr>is unique string obtained by concatenating the current date and time.

The log files are primarily required for debugging purposes, and furthermore, for bookkeeping since it contains all relevant info of a particular run.

####Step 4: Check your output Upon successful execution of the script makeVoronoiOBJfiles_forNanosculpt.bsh, you will find two important files written out in the same directory.

1. grain_centers_pbc.dat --> contains the centers of the individual grains
1. rotmat_RandomOrientation.dat --> A data file containing rotation matrices of random orientations that can be used later in the parameter file of nanoSCULPT.

The *.obj files required for running nanoSCULPT can be found in the directory OBJdir provided as the penultimate argument to the script makeVoronoiOBJfiles_forNanosculpt.bsh. The files are named Example1NCvoronoi*.obj where the prefix was the last argument provided to the script makeVoronoiOBJfiles_forNanosculpt.bsh.

$> ls OBJdir

Example1NCvoronoi1.obj  Example1NCvoronoi13.obj Example1NCvoronoi17.obj Example1NCvoronoi20.obj Example1NCvoronoi24.obj Example1NCvoronoi5.obj  Example1NCvoronoi9.obj
Example1NCvoronoi10.obj Example1NCvoronoi14.obj Example1NCvoronoi18.obj Example1NCvoronoi21.obj Example1NCvoronoi25.obj Example1NCvoronoi6.obj
Example1NCvoronoi11.obj Example1NCvoronoi15.obj Example1NCvoronoi19.obj Example1NCvoronoi22.obj Example1NCvoronoi3.obj  Example1NCvoronoi7.obj
Example1NCvoronoi12.obj Example1NCvoronoi16.obj Example1NCvoronoi2.obj  Example1NCvoronoi23.obj Example1NCvoronoi4.obj  Example1NCvoronoi8.obj

The above *.OBJ files can be visualized with Paraview.

####Step 5: Create a parameter file for each grain and run nanoSCULPT Recall that executing nanoSCULPT requires a parameter file. In what follows, the parameter file for one particular grain is provided.

But first change to OBJdir

$> cd OBJdir

$> cat Example1NCvoronoi1.nsparam

# nanoSCULPT: A tool to generate complex and realistic configurations for atomistic simulations
# @authors: A. Prakash, M. Hummel, S. Schmauder and E. Bitzek, 2011
#
#
# NanoSculpt Parameter File - Grain1

structure        fcc

# Epsilon added to prevent rounding errors epsilon
epsilon          0.001

# Input and Output file names
eingabe          Example1NCvoronoi1.obj
outfile          Example1NCvoronoi1.pos

# Starting value for atom numbering 
startnr         1

# element / structure information
atomtype        0        # atom type. Important for composite structures
mass     107.8682
lattice_const    4.09


#shiftvec for diamond shift lattice
shiftvec        0 0 0           # vector to shift the atoms

#center shift -- to shift the center from where atoms are to be filled
center_shift    0 0 0   # vector to shift the atoms

# Write header info in the outfile?
header          1
box_x          120.0    0.0   0.0
box_y            0.0  180.0   0.0
box_z            0.0    0.0  150.0

#coordinate axis / unit vectors of the rotated axis (taken from rotmat_RandomOrientation.dat)
vector1           -0.9842824414663625    0.1751049428685064    0.0229419790784032
vector2            0.1741720052626773    0.9839897704923855   -0.0377921175527443
vector3           -0.0291922593129522   -0.0332022672322190   -0.9990222327089852

Once the parameter file has been generated, you can execute nanoSCULPT as follows:

$> $nanoSCULPT_BaseDir/source/nanoSCULPT Example1NCvoronoi1.nsparam

The generated atomistic structure is now ready for simulations with the massively parallel atomistic simulation tool IMD.