Complete Manual

The complete GASP manual contains a full description of the code and its usage and can be downloaded here: GASP Manual (PDF).

 

Quick-start Guide

Last updated: 12/09/14

Goal: Setup GASP to run on a desktop Linux machine and perform an Al-Cu binary phase diagram search with Gulp EAM potentials.

Note: Many of these steps involve configuring your system so that the various energy codes and helper utilities are on your PATH. In many cases, these requirements can all be met in one fell swoop by simply including the ~/bin directory of Ben Revard in your PATH. This is recommended, as it will also get you updates automatically when we update our files. If you are unfamiliar with the PATH variable, please see, for example:

http://www.cs.purdue.edu/homes/cs348/unix_path.html

We will generally assume in the following that you have a ~/bin directory and that it is on your path.

1) Get Java

Java is almost certainly already installed on your desktop machine, but it is not included on all computing clusters. In this case, download the Sun Java JRE. In case you do not have permission to install it system-wide, you can get the self-extracting or tarball distribution and install it in your own ~/bin directory.

2) Obtain ga.jar and create the ga convenience script

The GASP code is usually distributed as a .jar file called ga.jar. It is often helpful to create a 1-liner script to run this jar file:

java -jar ga.jar "$@"

Create this script in your ~/bin directory, specifying the locations of the java and ga.jar if necessary. Call it ‘ga’. Make it executable. At this point, if you run ‘ga’ without any arguments, the code should run and print out a list and short descriptions of all of its input arguments.
The code is still under very active development, so the format of input commands is still changing. The manual tends to get out of date, but this usage statement should always be correct.

3) Gulp and callgulp script

The GASP interfaces to the energy codes write input files specific to those codes. However, the way the codes are actually run is system-dependent. For example, running on many clusters involves submission to some sort of job queue. Since this stuff is system-dependent, the logic is located in scripts external to the java code. For the Gulp code, this script is called ‘callgulp’, and the convention is that this script is run with a single argument, the Gulp input filename, and stops running when the Gulp calculation is complete.
So, install, compile, and otherwise get Gulp working on your machine. Then create the one-liner callgulp script in your ~/bin directory:

gulp < $1

specifying the location of the gulp binary if it’s not on your path. Now the GA code will be able to use Gulp to relax structures and calculate their energies.

4) The findsym utility and callfindsym script

The findsym utility is used by the GA to find symmetry and space group information about structures. It can be obtained from

http://stokes.byu.edu/isotropy.html

Download and install this utility and then set up a ‘callfindsym’ script whose purpose is analogous to the callgulp script above.

export ISODATA="$HOME/bin/isobyu/"
$HOME/bin/isobyu/findsym ${@}

Defining the ISODATA variable in the script is necessary so that the findsym utility can find its data files. Of course, the path to the data and to the findsym binary in the callfindsym script should be customized.

5) The qconvex utility

The qconvex utility is used by GASP to find convex hulls. The interface has no real special requirements, so there is no helper script — the qconvex binary must simply be on your path. It can be obtained through your Linux distribution’s package manager or directly from

http://www.qhull.org

You should be able to run qconvex with no arguments to see its usage statement.

6) Write the GA input file

Great, now we are ready for our first calculation. Create a new directory to keep everything together. Copy the following into a file, perhaps calling it ‘input’. Please see the User Manual for detailed descriptions of each input parameter.

##### GASP Example Input File: GULP/AlCu #####
# title the run
runTitle alcu
saveStateEachIter true
# verbosity varies from 0 (no output) to 5 (lots of output)
verbosity 4
popSize 15
InitialPopulation 15 random givenVol 20
InitialPopulation 2 poscars refstates/
compositionSpace 2 Al Cu
Promotion 1
Variation1 0.2 0.2 structureMut 0 0.3 0.1
Variation2 0.80 0.8 Slicer 0.5 1 1 0.05 0 0
ObjectiveFunction pd gulp gulp_header gulppotl_alcu true
Selection probDist 13 1
useNiggliReducedCell true
optimizeDensity 0.5 4
useRedundancyGuard both 0.1 0.1 0.1
ConvergenceCriterion maxNumGens 10
# hard constraints
minInteratomicDistance 1.0
maxLatticeLength 35
minLatticeLength 1
maxLatticeAngle 140
minLatticeAngle 40
maxNumAtoms 10
minNumAtoms 1
doNonnegativityConstraint false

The ObjectiveFunction command says that we are doing a phase diagram (pd) run using Gulp, and indicates two files, the Gulp header file and the Gulp potential file which will be needed. Create these now in the same directory.
Create the ‘gulp_header’ file with contents:

opti conp conj
switch_minimiser bfgs gnorm 0.02

and the ‘gulppotl_alcu’ file with contents:

manybody
Al core Al core 0.000 12.000
Cu core Cu core 0.000 12.000
Al core Cu core 0.000 12.000
lennard 7 6
Al core Al core 601.9448 0.000000000E+00 0.000 12.000
lennard 9 6
Cu core Cu core 1285.6223 0.000000000E+00 0.000 12.000
lennard 7 6
Al core Cu core 375.0000 0.000000000E+00 0.000 12.000
eam_functional square_root
eam_density power 6
Al core 1350.7776
Cu core 526.5984

The contents of these files are specific to the Gulp code.
When performing a phase diagram search, it’s important to make sure that at least one pure elemental structure is included in the population for each element in the composition space. The input file specifies that the initial population be drawn from two sources: 15 structures from random generation and 2 structures from POSCAR files located in a directory called ‘refstates’. Create this directory and two files in it. The two files should have names that end in ‘.POSCAR’ and contents:

copper reference
1.0
2.55270000 0.00000000 0.00000000
-0.00001260 3.61000000 0.00000000
-0.00002612 -0.00001887 5.10526315
Cu
4
Direct
0.28542000 0.87559000 0.16217000
0.78543000 0.37559000 0.91216000
0.28543000 0.87559000 0.66216000
0.78543000 0.37559000 0.41216000

and

aluminum reference
1.0
2.86370000 0.00000000 0.00000000
0.00002597 4.96000000 0.00000000
1.43184566 0.82676964 9.35389604
Al
8
Direct
0.69476000 0.95667000 0.64392000
0.94478000 0.04000000 0.14394000
0.44478000 0.54000000 0.14393000
0.06978000 0.74833000 0.89393000
0.19476000 0.45668000 0.64392000
0.81979000 0.33166000 0.39394000
0.56978000 0.24833000 0.89393000
0.31979000 0.83166000 0.39394000

7) Run the calculation

Next, run the calculation with the command

ga --f input | tee output

If everything was set up correctly and all goes smoothly, the GA will print out various information as it goes about creating the ground state Al-Cu binary phase diagram. The input file specified 10 generations with few structures per generation, so this should only take a few
minutes.

8) Examine output files and perform postprocessing

The code will have created a subdirectory called ‘garun_alcu’ where it puts all of its output. The ‘index’ file contains a listing of the structures encountered in each generation along with their objective function values. In this case, since we did a phase diagram search, for all generations after the first, the objective function value is a formation energy with respect to the convex hull known at that time.
The structures are numbered, and there are two files for each structure in the output directory. The .cif file gives the relaxed structural parameters in CIF format which can be viewed using almost any crystal structure viewing program. The .fso file contains the output of the findsym command for each structure.
There are two .tgz files for each generation. The .save.tgz files save the state of the algorithm at the end of each generation and can be used to restart it if necessary. The .pdb.tgz files are binary data files which contain phase diagram information. These can be viewed using the pdviewer utility.
The garun_alcu/temp subdirectory contains the input and output files of the energy code.
The parse_ga_results script is useful for performing a condensed listing of the structures found by the algorithm, but our post-processing tools are still under heavy development.