Home‎ > ‎

Tutorials & HowTo's

All of our HowTo's are collected on this one page, in this way you can use the find function in your browser to search for specific terms, or use the menu below.

                

Running a High-Throughput Study with random_substitution.x for Site Substitution

by Barry Haycock and James P. Lewis

This tutorial requires familiarity with FIREBALL. If you are not familiar with FIREBALL, then please go to the developers's manual or seek other tutorials for help on using FIREBALL.  This tutorial also requires that you understand how to generate a Lightning-style pair of input files also, details of which can be found here to use the random_substitution.x program. If you are not familiar with random_substitution.x, read through the short manual here.

In order to use fireball in an array job setting, you must establish a directory with the following the default structures.inp, an example of which is file shown below.  These must be placed in a working directory location from which you will run the calculations you plan to carry out

The initial.inp file combines the information for the supercell that has not been substituted, and will serve as the basic model which the randomly-substituted cells will be based on, it contains the number of atoms in the cell, the lattice vectors, kpoints and the atomic co-ordinates:

initial.inp

192 0 ! number of atoms, icluster
17.677800 0.000000 0.000000 ! LVS1 lattice vector
0.000000 15.309424 0.000000 ! LVS2 lattice vector
0.000000 0.000000 19.98172 ! LVS3 lattice vector
1 ! # of kpoints
0.000000 0.000000 0.000000 1.000000 ! kpoint, weight
22 10.518517 10.561772 7.174993 ! Atomic Number, co-ordinates.
22 9.732300 7.817309 9.551423
...
...
8 5.149039 2.301049 7.515000
8 12.38349 1.417719 1.432260
For a FIREBALL style array job, the default structures.inp file will suffice, and the example below can be used directly as in this tutorial:

structures.inp
1 ! number of structures
initial.inp ! structure input file
!Write out options- leave as comment or null
&OUTPUT
&END
&OPTIONS
&END
Finally, the random_substitution.inp file is required, this contains the information of what species are being substituted and what they shall be substituted with. It also contains the ratio of random substitution required and two flags, the first tells random_substitution.x if you will specify the random seed in the batch call rather than have it use linux time as a seed, and the second tells random_substitution.x to output FIREBALL-TG files or FIREBALL-Lightning files.

random_substitution.inp
8 ! Species at substitution sites
7 ! Replacement species
0.02 ! Ratio of atoms to replace
1 ! Number of structures to generate
.true. ! Cluster-specified seed toggle

The random_substitution.inp file above tells random_substitution.x to replace 0.02 (i.e. 2%) of the oxygen sites with nitrogen in each case. We have told random_substitution.x to use the PBS_ARRAYID as the random seed, if we set the logical flag to .false., then the random seed would be chosen based on linux time. In our example above, we are substituting nitrogen into oxygen sites and substituting 2% of the sites.

The contents of this directory can now be run in lightning.x, and DOS or other metrics can be evaluated.

Clustering Information

After your array job runs, then analysis begins. Much of these commands only work if you are in bash environment - enter bash if you are not already. One of the more interesting pieces of data is to plot the clustering information as a function of the total energy. In this type of plotwe can determine the energetics as it correlates to the clustering of the substitutional sites. Clustering here is defined as the root-mean-square distances of the substitutional sites (as compared to the perfect 1st nearest neighbor distance). To plot this datacopy and edit the files from cluster_analysis_tools directory to your directory from its current location which is /auto/data2/lewis_group/fireball2009/util/cluster_analysis_tools on moutaineer.hpc.wvu.edu). The format of these files are:

evaluating_cluster.inp

nZ ! atomic number of atom (substitutional sites) being analyzed
Rp ! perfect clustering distance (i.e. generally 1st nearest neighbor distance)

Fdata.inp

nspecies ! number of species
nZ ! atomic numbers
Fdata_location ! location of Fdata directory

structures.inp

nstructures ! # of structure files
structure_file ! name of structure file
Note that the files Fdata.inp and structures.inp are standard input files used for lightning.x;  hence, these two files can be edited later for a subseqeunt run with lightning.x (e.g., generating density of states). The structures.inp file has already been generated when we created the supercells. A call to /auto/data2/lewis_group/fireball2009/util/cluster_analysis_tools/
                                                           evaluate_clustering.x
 will then look at all supercells and generate the clustering_energy.dat file. Plot the results found in clustering_energy.dat in whatever program you are most comfortable.

Return to Top


Fdata benchmarking with Fdata_rhombhedral_benchmark.x 
by Barry Haycock

One major component of any high-throughput study is the choice of basis set. You cannot carry out accurate calculations unless you are positive that the initial setup is correct. We judiciously choose our basis set in order to optimize the balance between highly efficient and highly accurate calculations when we carry out any study. This tutorial focusses on the steps carried out to confirm the approximations made in the generation of an Fdata yield experimentally-accurate results. This tutorial is based on the work we do for Delafossites, however in coming months we will expand this tool to work with other primitive-lattice types. The Delafossite primitive cell is rhombohedral, so this tool can be used for any primitive rhombohedral structure with R-3m symmetry

We use the Fdata_rhombohedral_benchmark.x program located at /data2/lewis/fireball2009/util/Fdata_rhombohedral_benchmarking on MOUNTAINEER to quickly insure that the choices made in Fdata generation hold true. The general philosophy is that it accepts the lattice vectors for the "ideal" crystal structure of the material you're studying, and then generates a large number of supercells by varying those lattice vectors +/- some predetermined amount. We then calculate the energy minimization of these cells, and make a surface plot of the vectors versus energy of the cell. In this way, we can see that the lowest-energy vector combination is very close to the values in the literature or we can see that the approximations chosen are incorrect for our purposes and generate a new Fdata.

This tutorial requires you to understand basic concepts about the crystal structure you are studying and what an Fdata actually is. Familiarity with FIREBALL is also assumed . As people need other primitive structures for their own work they can use the Fdata_rhombehedral_benchmark.f90 as a template and very quickly generate a new tool for a different primitive lattice type, please forward the code to me at barry.haycock@mail.wvu.edu and I will add it to the repository.

Setting up the central directory

To run this suite of programs, copy the files from the /data2/lewis/fireball2009/util/Fdata_rhombohedral_benchmarking directory to wherever you will run this in your home folder (we will refer to this place as [DIRECTORY]). The files in that directory are:

Fdata_rhombohedral_benchmark.f90   - Source code for Fdata_rhombohedral_benchmark.x
Fdata_rhombohedral_benchmark.x      - The main executable you will use
greatKauto.x                                          - This is an automated version of greatK, and generates your kpoints
greatK.input                                         - This is the input file for greatKauto
Harvest_Fdata_rhombohedral_benchmark.x - Collectes the data generated after your calculations
r-3m.sym                                                  - The symmetry operations for R-3m
SampleOpt.opt                                       - Sample input file for the entire toolbox
SamplePlot.gnuplot                             - Sample gnuplot script for plotting results
template.job                                          - "Blank" job-script used in sending calculations to the cluster

There are a number of files to edit here. We begin with the most pertinent, namely the SampleOpt.opt (rename this file as required)

SampleOpt.opt 

name ! name of the material
ideal_a ideal_c ! lattice constants a and c
var_a var_c ! distance to explore from a and c
step_a step_c ! step size for exploration
u ! internal parameter of crystal
nZ_b ! B-site species
nZ_a ! A-site species
Fdata_location ! location of Fdata directory

!All values from Beznosikov and K. S. Aleksandrov Journal of Structural Chemistry. Vol. 50, No.  1, pp. 102-107, 2009

! NaInO2 valuess from: http://pubs.rsc.org/en/content/articlelanding/2000/jm/a908505j

! Lattice Parameters for CuInO2 are from http://www.sciencedirect.com/science/article/pii/S0022369703000714

! Interesting Papers:
! http://prb.aps.org/pdf/PRB/v84/i3/e035125
! http://prb.aps.org/pdf/PRB/v82/i8/e085115


You need to edit all fields in square brackets above and the notes at the end of the file to show the reference to the parameters used.  A further description of every field is below:

name Name of the material, e.g. CuFeO2, this will form part of the name of the directories created.
ideal_a,ideal_c The a and c lattice parameters that you expect to be correct- use the literature values.
var_a, var_c The distance from IDEAL_A  and IDEAL_C to check. Typically this is IDEAL / 10
step_a, step_c The step size for the study, typically VAR / 10
The internal parameter for the R-3m structure, it's in the literature.
nZ_a, nZ_b The atomic number of the species in the chemical formula ABO2
Fdata_location Location of the Fdata being benchmarked.

It is unacceptable to run this program without adding the citation of where your lattice parameters are from. Add other notes as required for your work also.

Next, edit the template.job file, it contains:

template.job
#!/bin/bash
#PBS -q day
#PBS -l nodes=1:ppn1
#PBS -m ae
#PBS -M [EMAIL@ADDRESS]
#PBS -N [NAME]_AAA 

source ~/.bashrc


cd [DIRECTORY]/AAA



      ./fireball.x > runlog.log

For the template.job edits, change what is in the square brackets- Namely add an email address, name the job on the PBS queue and add the parent directory of your structures. 
N.B.: Leave in the AAA strings, the program will use those in job generation.

The next file to look at is the greatK.input file, if you are running a delafossite most are R-3m and this file should not require any editing:

greatK.input
input.lvs ! lattice vector file
n1, n2, n3 ! Monkhorst-Pack integers.
r-3m.sym ! first symmetry file
1 ! 1 for inversion
r-3m.sym ! second symmetry file
1 ! 1 for inversion
0 ! Remove k's which are minus a - k.
It's outside the scope of this tutorial to explain what a Monkhorst-Pack mesh is. 
NOTE- there is nothing in square brackets in this file, you shouldn't need to edit it.

Run calculations

Call the Fdata_rhombohedral_benchmark.x program and tell it the name of your opt file. In this tutorial, the default name, SampleOpt.opt is used. Type:

./Fdata_rhombohedral_benchmark.x  

in the working directory, you will be greeted with:

 Welcome to r3m lattice optimizer
 First, input your optimization file.
 Enter the name of the .opt file

simply type:

SampleOpt.opt

Each run should take about 30 minute. If you used the examples of [VAR] = [IDEAL] / 10 and [STEP] = [VAR] / 10, there will be 41 separate jobs. 

Collecting data

Once all calculations are finished. type:

./Harvest_Fdata_rhombohedral_benchmark.x

in your work directory and enter the opt file name. This will take a minute or two to process, but the final result will be a file called:

[NAME]_astep_cstep_alat_clat_FinalE_FinalT.dat

where [NAME] is the study name in your opt file. This file contains 5 columns, as the name suggests, the number corresponding to astep and cstep, the lattice value at that address for a, the lattice value at that address for c, the energy and the final temperature. Open this file- check the temperatures to insure that the jobs ran correctly. Use a spreadsheet to find the lowest energy value.

The final step is to plot this data, you can use any program you like. There is a quick script for gnuplot to quickly view the data. The gnuplot script is a file called "SamplePlot.gnuplot" in your directory. There are two fields to edit, namely the [NAME] as before and [MIN ENERGY] which is the lowest energy value in your data file. Edit those then type:

gnuplot SamplePlot.gnuplot

This will generate a PDF called FdataBenchmarking.pdf, which contains your graph. Typically add a cross-hairs showing the middle of the graph using GIMP and place an X at the lowest value on the graph from the data.


Generating and running randomly-substituted delafossite structures

(by Barry Haycock)

This HowTo requires familiarity with FIREBALL. If you are not familiar with FIREBALL, then please go to http://nanosurf.fzu.cz/wiki/doku.php?id=fireball for help on using FIREBALL. Run the first few tutorials to familiarize yourself with FIREBALL. In this HowTo, we are discussing high-throughput calculations of delafossite structures specifically. It is assumed you have at least read the more generalized tutorial on HT calculations, above, which is titled "Running a High-Throughput Study with Randomizer for Site Substitution". In this HowTo, we will show you how we generate and sun randomly-substituted delafossite structures at any level of percentage substitution. We will generate directories that run separately and independently of one another and then we will make a specialized job script that will carry out the actual generation of directories and the calculation. This will soon be superceded by the java package "Tornados", however the tutorial will remain on site as it can be used for future work and understanding what happens in this section of the of the Tornados program will help with analysis and development. 

Setting up

Here's what you do to run such a study:

Firstly, you need to have an Fdata for your work, the a and c lattice parameters and a reference for them, and (for this specific tutorial) access to MOUNTAINEER. The first thing you are going to do is make yourself a directory where you will run all calculations that you need for a complete study. In this tutorial, that directory will be simply referred to as [DIRECTORY].

/data2/lewis_group/fireball2009/util/Delafossite_Generation_Suite/Sample_Blank_Directory/ into your work directory to a directory called "blank", like this:

cd [DIRECTORY]

cp -r 

/data/lewis/fireball2009/DelafossiteTools/Primbas_Suite/Sample_Blank_Directory/ ./blank

This directory contains the following files:

Fdata.optional                     - Part of FIREBALL-TG's input files, read http://nanosurf.fzu.cz/wiki/doku.php?id=fireball

fireball.in                               - Part of FIREBALL-TG's input files, read http://nanosurf.fzu.cz/wiki/doku.php?id=fireball

gamma.kpts                          - Gamma-only kpoints file

pbs.jobscript                         - A "blanked" job script for the cluster, explained below

primbas.input                       - Input file for the supercell generator

rms.input                               - Tells FIREBALL to stop running at a forces tolerance for HT calculations

the file that concerns you most for this work is primbas.input, which contains all the information for generating a primitive molecular basis file and then building it up into a supercell for calculations, primbas.input looks like this:

29 ! a-Site Species
31 ! b-Site Species
0.1073 ! internal variable
17.154 ! c-lat original structure
2.975 ! a-lat original structure
17.388 ! c-lat 100% doped structure
3.2922 ! a-lat 100% doped structure
XXXX ! amount of doping
'6 6 1 ! Extend primitive by factors
49 ! B-Site Doping species


! CuInO2 values from : "Synthesis of the Delafossite-Type CulnO2"
M Shimode, (2000), Journal of Solid State Chemistry 151  p. 16-20
http://dx.doi.org/10.1006/jssc.1999.8603 

Edit these lines as you need to. The comments explain what is required in each line. We *always* use the last lines to reference where these parameter's came from for  *both* delafossites in our alloyed material. Make sure to select the value of X, as highlighted above, for your work.

Next, go back to [DIRECTORY] and copy the PBS array run script to there:

cp /data2/lewis_group/fireball2009/util/Delafossite_Generation_Suite/General_Random_ Delafossite_Generator_Command_Line_Seeded/Sample_PBS_script.sh ./ArrayJobScript.pbs

This file needs to be edited to do your run, it contains:

#!/bin/bash
#PBS -q week
#PBS -l nodes=1:ppn=1
#PBS -l walltime=160:00:00
#PBS -t [1-200]
#PBS -m ae
#PBS -M [email@address]
#PBS -N [JOBNAME].${PBS_ARRAYID}

source ~/.bashrc

WORKDIR=[DIRECTORY]
cd $WORKDIR
mkdir ${PBS_ARRAYID}
cd ${PBS_ARRAYID}
cp ../blank/* .

#link in the Fdata
                ln -s [FDATA LOCATION] ./Fdata

# Link to the executible
                ln -s /data2/lewis_group/fireball2009/bin/fireball.x ./fireball.x


# Call the Lvs and bas maker
 /data2/lewis_group/fireball2009/util/Delafossite_Generation_Suite/     \           General_Random_Delafossite_Generator_Command_Line_Seeded/             \   General_Random_Delafossite_Generator_Command_Line_Seeded.x   ${PBS_ARRAYID}

# Call the executible
       ./fireball.x > runlog.log

The beauty of this is that it's really easy to edit. You need to change anything highlighted in square brackets. The [1-200] tells the computer to do this for a count of 1 through to 200, edit these numbers as you need. The field labelled [FDATA LOCATION] must be changed to the absolute path to your Fdata. Change the  [JOBNAME], and [email@address].

That's it, just submit your edited ArrayJobScript.pbs and the computer will take care of the rest:

qsub ArrayJobScript.pbs

This will go through and generate the required directories and run it on the pbs queue. Come back in about 6 hours, they should be ready to study.


Return to Top

2% substituted delafossite structures- complete seachspace calculation 

(by Barry Haycock)

This HowTo requires familiarity with FIREBALL. If you are not familiar with FIREBALL, then please go to http://nanosurf.fzu.cz/wiki/doku.php?id=fireball for help on using FIREBALL. Run the first few tutorials to familiarize yourself with FIREBALL. In this HowTo, we are discussing high-throughput calculations of delafossite structures specifically. It is assumed you have at least read the more generalized tutorial on HT calculations, above, which is titled "Running a High-Throughput Study with Randomizer for Site Substitution"For the delafossite high-throughput studies, we have a special case at x = 0.02, at this level of alloying, there is no need to use random substitution site selection. Here's what you do to run such a study:

Setting up

Firstly, you need to have an Fdata for your work, the a and c lattice parameters and a reference for them, and (for this specific tutorial) access to MOUNTAINEER. The first thing you are going to do is make yourself a directory where you will run all 107 calculations that you need for a complete x = 0.02 study. In this tutorial, that directory will be simply referred to as [DIRECTORY].

The first thing you need to do is copy the directory /data2/lewis_group/fireball2009/util/Delafossite_Generation_Suite/Sample_Blank_Directory/ into your work directory to a directory called "blank", like this:

cd [DIRECTORY]

cp -r 

/data/lewis/fireball2009/DelafossiteTools/Primbas_Suite/Sample_Blank_Directory/ ./blank

This directory contains the following files:

Fdata.optional                     - Part of FIREBALL-TG's input files, read http://nanosurf.fzu.cz/wiki/doku.php?id=fireball

fireball.in                               - Part of FIREBALL-TG's input files, read http://nanosurf.fzu.cz/wiki/doku.php?id=fireball

gamma.kpts                          - Gamma-only kpoints file

pbs.jobscript                         - A "blanked" job script for the cluster, explained below

primbas.input                       - Input file for the supercell generator

rms.input                               - Tells FIREBALL to stop running at a forces tolerance for HT calculations

the one that concerns you most for this work is primbas.input, which contains all the information for generating a primitive molecular basis file and then building it up, this file looks like this:

29! a-Site Species
31! b-Site Species
0.1073! internal variable
17.154! c-lat original structure
2.975! a-lat original structure
17.388! c-lat 100% doped structure
3.2922! a-lat 100% doped structure
0.02! amount of doping
6 6 1! Extend primitive by factors
49! B-Site Doping species


! CuInO2 values from : "Synthesis of the Delafossite-Type CulnO2"
M Shimode, (2000), Journal of Solid State Chemistry 151  p. 16-20
http://dx.doi.org/10.1006/jssc.1999.8603 
Edit these lines as per the study you are carrying out. The comments explain what is required in each line. We *always* use the last lines to reference where these parameter's came from for  *both* delafossites in our alloyed material.

Running Calculations

Next, go back to [DIRECTORY] and copy the run script to there:

cp /data2/lewis_group/fireball2009/util/Delafossite_Generation_Suite/ 2_percent_Delafossite_Generator/2percent_sequenced_runs.sh .

This file needs to be edited to do your run, it contains:

for a in `seq 1 107` ; do
mkdir $a
cd $a
cp ../blank/* .
#set up the Fdata
                                    ln -s [FDATA LOCATION] ./Fdata

# Link to the executible
              ln -s /data/lewis/fireball2009/bin/fireball.x ./fireball.x

#send the jobscript the NAME and the DIRECTORY
              pwd |  sed "s/\//\\\DIM\//g" |sed "s/DIM//g" > directoryplacer.txt

              e=`paste directoryplacer.txt`

                

                                     cat pbs.jobscript | sed "s/DIRECTORY/$e/g"  > job.script.tmp
              cat job.script.tmp | sed "s/NAME/[STUDY NAME]_$a/"  > job.script

# Call the Lvs and bas maker
              /data/lewis/fireball2009/DelafossiteTools/Primbas_Suite/2percentMake_primBas.x $a

# Call the queue
     qsub < job.script

cd ..
   echo "Just did job number $a"
   sleep 1
done

The beauty of this is that it's really easy to edit. There are two fields you need to change. The first one is labelled [FDATA LOCATION] change that to the absolute path to your Fdata. The second is [STUDY NAME], change this to whatever you call this study.

That's it, just call your edited 2percent_sequenced_runs.sh and it will take care of the rest:

./2percent_sequenced_runs.sh

This will go through and generate the required directories, make a job script and put it on the pbs queue. Come back in about 6 hours, they should be ready to study. Much of the analysis we typically carry out is to plot the clustering factor and the variance. Clustering factor is discussed in the section on Random Substitution. 

Return to Top

Plotting a DOS of the contributing elements: Partial Density of States

Jessica Carr

This is a quick step-by-step to plot a PDOS from a completed DOS calculation by FIREBALL. It assumes you have an understanding of FIREBALL, what a Density of States is, Linux and any plotting program.

1. Sort the input structure file such that the atoms are grouped by element, and run the DOS calculation.

2. Open the answer.bas file generated after a successful DOS completion using vi.  Take note of the lines on which each element appears in the file; the first atom that appears in this file corresponds to the dens_001.dat file, and so on. Using vi allows us to quickly group atoms by element and find their number, because it displays the line number of the file at the bottom right. Just remember that the first line of the file is the total number of atoms, so the first atom corresponds to line 2, and so on.  

In the example below, we can see that Sulfur (element 16) is atoms 1-6 because it is on lines 2-7 of the file, and thus corresponds to files dens_001.dat through dens_006.dat.

 

3. Next, we want to group all of the dens_###.dat files of a particular element into one file. We can display all of the dens_###.dat files that correspond to one element (determined above) in a row of the terminal with the command:

for a in `seq 1 6` ; do echo –n “dens_00$a.dat “; done

 Note that the first marks are grave accents (on the tilde key), not apostrophes, and there should be a space between dens_00$a.dat and “. If the sequence number is two digits use “dens_0$a.dat “ and if three digits, use “dens_$a.dat “. If an element appears in multiple sequences with the same number of digits, these can be placed in the same line:

for a in `seq 10 15` `seq 30 57` `90`; do echo –n “dens_0$a.dat “; done

If the atom numbers do not have the same number of digits, these will have to be done with separate commands.

4. Copy the line of dens_###.dat files now displayed in the terminal on their own line.

5. cat the files together, sorting them numerically (sort -n) into a file whose name is determined 

by  > filename

To append a file that already exists use  >> filename

For example:

 

6. Create a file dos_tot.X (where X corresponds to the element being studied) that contains the following script:


BEGIN {e=-14.99; dos=0; }
   {if (($1==e) && (NF==16)) {dos+=$15}
   if (($1!=e) && (NF==16)) {printf("%f %f \n",e,dos); e=$1; dos=$15}}
END {printf("%f %f\n",e,dos)}


Change NF== to the total number of columns in your cat file output and the dos+=$ and dos=$ values to one less than that number.

7. Carry out the script on your cat output file using the command:

awk –f dos_tot.X tot_X > X.dat

changing the X’s to your particular atom.  We now have used the script to create a file called X.dat that contains only the energy and the density of all of the atoms of that particular element.

8. After carrying this out for each element, you can plot all elements on the same plot with the total density using vmd:

xmgrace S.dat O.dat Au.dat N.dat C.dat dens_TOT.dat



XcrySDen How To:  Isosurface Rendering Partial Density

Nancy Isner.

For reference, this is a step-by-step to plot an isosurface in XCrysDen. You can calculate the input files for such a infographic by using the Real-Space Electronic Density functions of FIREBALL. A tutorial on how to carry out such a calculation is available here.

1. Under file go to Open Structure. 

2. Next click on open XSF. 

3. Choose specific file. 

4. Under display turn on Coordinate System by clicking on it. Turn off Crystal Cells by clicking 

5. Under Tools go to Data Grid. A box will show up and you should press OK when the box comes up. (If you don't see the OK just expand the box and it should show up.)

6. Next a box labeled Isosurface/Property-Plane Controls will pop up. 

7. Under Isovalue in the pink box choose a value to display the isosurface that fits your structures  appropriately. Found that the range from .0008-.0004 will typically yield best display.

8. Press Submit to view the surface.

9. Click and drag to find appropriate angle to display the isosurface.   

10. Then under File either save XSF file or Print.