Purpose: This tutorial shows how to do a cluster expansion of the total energy of fcc TixAl1-x, using the Alloy Theoretic Automated Toolkit (ATAT) in combination with exciting. It is shown how to prepare and setup the calculation, how to run it and how to evaluate the results. The goal of this tutorial is to compute the groundstate structures of fcc TixAl1-x in the whole concentration range from x=0 to x=1.
Table of Contents
0. General Preparations
Before starting, be sure that relevant shell variables are already defined and that the excitingscripts directory has already been downloaded, as specified in Tutorial scripts and environment variables. Here is a list of the scripts which are relevant for this tutorial with a short description.
Extra requirement: The ATAT package
In order to perform calculation with the cluster-expansion method exciting uses the Alloy Theoretic Automated Toolkit (ATAT) package.
- Tool name: ATAT
- Author: Axel van der Walle
- Website: http://www.its.caltech.edu/~avdw/atat
Install the ATAT package
You can find the complete ATAT package in the directory $ATATROOT. In order to install the package, you have to execute the following commands.
$ cd $ATATROOT $ make
If no error message appears, proceed with the next step.
$ make install
Now, the ATAT package is available to be used.
In order to install the ATAT@exciting tool, you should use the following command.
Note that in this case it is not relevant the directory where you are actually typing the command ezexciting.
1. The cluster-expansion method
The cluster-expansion technique is a sophisticated method to calculate alloy properties only based on the alloy configuration, i.e., the distribution of the alloy constituents on the crystal lattice. It relies on the following theoretical considerations:
- The physical processes determining the free energy of an alloys take place on very different time scales. Especially, electronic excitations, magnetisation, and changes in the atomic positions take place on a much faster time scale compared to atoms changing their position on the lattice. Therefore, the faster mechanisms can either be treated implicitly as part of the configuration, or neglected. This way, the total energy becomes a function of the configuration, only.
- The total energy of the whole system can be mapped onto the energies of atoms in smaller clusters: pairs, triplets, etc. The energies assigned to the clusters are called "Effective Cluster Interactions" (ECIs).
- Expanding the total energy in terms of these so-called "effective cluster interactions" (ECIs) shows fast convergence with respect to the number of clusters taken into account. Once the ECIs are known, the total energies of arbitrary configuration are available.
So the point of interest is: How can one obtain the effective cluster interactions? The answer is: By calculating special, ordered structures ab initio, and then fitting the ECIs for a suitable set of clusters to ab-initio total energies.
1.1 Tools for cluster-expansion calculations
The cluster-expansion method is implemented in the MIT Ab-initio phase-stability (MAPS) code maps of ATAT, which can be interfaced with the exciting software package. A set of scripts and programs called ATAT@exciting does the connection between ATAT and exciting.
The maps code is the part of ATAT which cares for all aspects of how to get the cluster expansion. It
- proposes structures to be calculated and provides input files (in ATAT format);
- uses the ab-initio total energies and tries to find the best cluster expansion for the given set of structures and energies available at any step of the calculation;
- proposes new structures to be calculated in order to improve the cluster expansion.
The scripts of ATAT@exciting
- convert structure files produced by maps to the exciting format;
- prepare an exciting input file, using information from the file exciting.wrap;
- automatically perform exciting calculations;
- evaluate the result of an exciting calculation and provide the total energy to maps (inside the file energy);
- communicate with maps via signal files (ready, wait, energy, or error).
Finally, exciting determines groundstate total energies for the structures produced by maps.
2. Preliminary tests.
This section follows to a large extend parts of the ATAT manual, adapted to the specific situation of this tutorial. The original ATAT manual can be found as $ATATROOT/doc/manual.pdf.
2.1 Testing maps with a simple example
Create a new directory /home/exciting-tutorial/CE-TiAl and enter the directory by executing
$ mkdir /home/exciting-tutorial/CE-TiAl $ cd /home/exciting-tutorial/CE-TiAl
Please note that the explicit path given above (/home/exciting-tutorial) is only valid as example which can be changed by the user to the appropriate one. Keeping this in mind, then, type
$ cp $EXCITINGATAT/examples/TiAl/* ./
Now, you have three files in your directory:
- lat.in: Describes the lattice type, atomic positions, and which elements are allowed to "sit" on each site. Further information on this file is found here.
- Al.lat.in: Lattice vectors of pure Al.
- Ti.lat.in: Lattice vectors of pure Ti.
In order to start the maps program, execute
$ maps -d &
maps is now running and waiting for a signal. Type
$ touch ready
to indicate that you are ready for maps to generate a structure. After a few seconds, maps will reply
$ Finding best structure... done!
To find the structure just created, wait until "done!" appears on the screen, press the enter key, and then type
$ ls */wait
to observe that a directory 0 has been created. This directory contains initially the files str.out and wait. The first file describes the structure for which the energy needs to be calculated. The latter file, wait, is just a flag that allows you to find the newly created directory, and may be removed after appereance.
For the sake of this example, we assume that we already know the energy of the structure labeled 0 and that the value of this energy is 1.1eV. Then, we must tell maps about it. To do so, we create a file 0/energy containing the energy of the structure by typing
$ echo 1.1 > 0/energy
As soon as maps detects the file energy in directory 0 (which may take a couple of seconds…), it responds again with
$ Finding best cluster expansion... done!
Now, press the enter key and remove the file 0/wait.
$ rm 0/wait
You can repeat the complete procedure (touch ready, etc.) to add more structures. maps will update the current cluster expansion every time a new energy becomes known.
For the moment, let's stop maps by typing
$ touch stop
To clean up the directory after this first test, remove the directory 0, including the energy file just created, by typing
$ rm -r 0/
2.2 Test the interface between maps and exciting
Start maps again typing
$ maps -d | tee maps.out &
By using the tee command after maps, the output is written both to the display and the file maps.out.
While maps automatically creates the file that describes the geometry of a structure (called n/str.out, where the directory name n is typically a number between 0 and 10000), we need to provide a file containing all the other parameters needed by the first-principles code. In the case of ATAT@exciting, this file is named exciting.wrap. Copy the file $EXCITINGATAT/exciting.wrap to your working directory.
$ cp $EXCITINGATAT/exciting.wrap ./
For a description of the parameters which are found in the exciting.wrap file, type
$ ezexciting -h | more
Set the correct path in the attribute speciespath by the command
$ SETUP-excitingroot.sh exciting.wrap
Then, tell maps that you are ready to calculate a structure by executing
$ touch ready
and pressing the enter key. Now, you have a new structure in directory 0 (created after typing touch ready). This time instead of giving explicitly the energy of this structure, we let exciting to calculate it. Type
$ cd 0 $ runstruct_exciting
The latter command will
- create the file input.xml from the information found in exciting.wrap;
- start the exciting calculation;
- extract the total energy from info.xml after the calculation has finished;
- write the value of the total energy into the file energy (after converting it from Hartree to eV).
If error messages appear, consult the chapter Troubleshooting in the ATAT manual. If no error messages appear, you are ready for doing a complete cluster expansion with ATAT@exciting!
3. Starting ATAT@exciting for a first cluster-expansion calculation
Go back to the main directory of the last example.
$ cd /home/exciting-tutorial/CE-TiAl
For doing a quick calculation, do the following modifications in exciting.wrap.
- Change the parameter kppra to 125. This way you specify that the k point density should correspond to a mesh of ngridk="5 5 5" in the 1-atom unit cell.
- Include the attribute rgkmax="6.0" in the groundstate element.
Now you can start the cluster-expansion run, by executing
$ pollmach runstruct_exciting &
This command will
- create a new structure,
- automatically call runstruct_exciting for calculating the corresponding total energy,
- fit a cluster expansion to all available structures and energies,
- create another structure,
If you want to stop the cluster-expansion run, type (inside the diretory /home/exciting-tutorial/CE-TiAl, disregard the warning message)
$ touch stop
However, before stopping the execution, let's have a look at the running calculation as explained in the next section.
4. Output of maps
The combined use of maps, pollmach, and runstruct_exciting allows for the calculation of new structures and the improvement of the cluster expansion. Each structure is labeled with a number and calculated in the corresponding subdirectory. The first calculations should correspond to the directories (structures) 0, 1, and 2. The further development of the calculation depends on the outcome for the first 3 structures. In order to list in chronological order structures which have been already calculated, just execute
$ ls -ltr */str.out
While the calculations are running, you can check on the status of the best cluster expansion obtained so far. The file maps.log contains a brief description of the status of the calculations, including the accuracy of the cluster expansion and various warning messages (see a list of examples of messages at the end of this section). Most of the messages pertain to the accurate prediction of the so-called "ground states of the alloy system". Ground states, which are the structures that have the lowest energy for each given concentration, are extremely important to be predicted accurately, because they determine which phases appear in the phase diagram.
The maps code also outputs quantitative data in various output files. For details see the section Output files of the ATAT manual.
The simplest way to analyze this data is by typing
This command displays a series of plots (to proceed from one figure to the next, close the current figure and press the entry key on the command line). All energies are in eV, and the concentration corresponds to "x" in the chemical formula TixAl1-x. Since maps performs a new (trial) cluster expansion and produces new files each time a new energy file is ready, also check_maps will deliver new plots at each such instance. Thus, it may be interesting to run check_maps every 2-3 minutes, to see how the cluster-expansion is progressing. Examples for the most important plots are displayed in the following.
4.1 Formation energies from cluster expansion
The formation energies predicted from the cluster expansion. Structures of known energy, i.e. structures where a corresponding ab-initio result exists, are marked with +. In addition, the predicted energy of all structures maps has in memory are displaced (marked with x.). The convex hull of the ground states among structures of known energy is overlaid. If new ground states were predicted, they would be marked by a blue “*"symbol. (Note that this ground state line is only meaningful if the maps.log file contains “Among structures of known energy, true and predicted ground states agree.”).
4.2 Ab-initio formation energies
The ab-initio formation energy of all structures calculated by exciting, and the associated ground state line.
4.3 Magnitude of effective cluster interactions
A plot of the magnitude of Effective Cluster Interactions (ECI) as a function of the diameter of their associated cluster (defined as the maximum distance between any two sites in the cluster). Pairs, triplets, etc. are plotted consecutively. This plot is useful to assess the convergence of the cluster expansion. When the magnitude of the ECI for the larger clusters has clearly decayed to a negligible value (relative to the nearest-neighbor pair ECI), this is indicative of a well-converged cluster expansion.
4.4 Residuals of the fit
A plot of the residuals of the fit (i.e., the fitting error) for each structure. This information is useful to locate potential problems in first-principles calculations. Indeed, when first-principles calculations exhibit numerical problems, this typically results in calculated energies that are poorly reproduced by the cluster expansion.
5. Monitoring a cluster-expansion run
Using the tools described in the last section, you can monitor the run of your calculation. Apart from the graphical monitoring provided by ckeck_maps, you may also have a closer look at the output files. The main file, with a summary of the current status of the cluster expansion, is the file fit.out. It is generated/refreshed by maps each time the energy of a new structure is available and contains one line for each structure calculated by exciting so far. In each line, you find (in this order)
- the Al concentration of the structure,
- the energy obtained with exciting,
- the energy as obtained from the fit,
- the difference between the two energies,
- a weight for the structure,
- the name (=directory) of the structure.
It may happen from time to time, that the energy of one structure is completely off the rest, e.g., if a scf calculation does not converge, or it does not converge to the right results. You would realize this in the plot of the formation energies when one data point is far away from the rest. If this is the case, check the plot for the concentration of the "bad" data point. Then, look for structures which such a concentration in fit.out, it should be easy to identify this "bad" structure. If you have succeeded to do so, you can tell the maps program to ignore this structure, by going to the corresponding directory, and executing
$ touch error
After this action, maps will not take into account this structure any more when doing the next cluster expansion.
A cluster expansion can be considered satisfactory when
- All ground states are correctly reproduced and no new ground states are predicted. In this case, the file maps.log would then indicate that "Among structures of known energy, true and predicted ground states agree. No other ground states of n atoms/unit cell or less exist".
- The crossvalidation score, as given in the maps.log file, is small (typically less than 0.025 eV).
- Optionally, it is instructive to verify that the magnitude of the ECIs decays both as a function of the diameter of the corresponding cluster and as a function of the number of sites it contains, using the check_maps command described above.
When you are satisfied with the results (typically after 20-30 structures for a "real" calculation, taking a couple of hours), you can stop maps by creating a file called stop in the main directory using the command
$ cd /home/exciting-tutorial/CE-TiAl $ touch stop
while the job dispatching system can be stopped by typing (in the same directory)
$ touch stoppoll
To see the groundstates found by ATAT@exciting, have a look at the file gs.out. This file contains all groundstate structures found in the concetration range from x=0 (pure Ti) to x=1 (pure Al), one per line. Each line contains (in this order) the
- calculated energy,
- fitted energy,
- name (=directory) of the structure.
Note that the file gs.out is changing as long as the cluster-expansion is not converged/still in progress.
In order to see a structure looks like, just open the input.xml file in the corresponding directory with XCrySDen (in order to configure XCrySDen for viewing exciting input files, follow the instructions in XCrySDen Setup for exciting). If, e.g., the structure numbered as 27 would be identified as a groudstate, you could visualize it by executing
$ xcrysden --exciting 27/input.xml
6. Starting ATAT@exciting for more serious calculations
In order to perform a more serious calculation, you should
- create a new directory, which should not be a subdirectory of the previous one;
- copy the files lat.in, Al.lat.in, Ti.lat.in, exciting.wrap there;
- in exciting.wrap, change the parameter kppra to 1728 (corresponding to ngridk="12 12 12" in the 1-atom unit cell);
- set the attribute rgkmax="7.0" in the groundstate element.
Now, you can start maps in the new directory by executing
$ maps -d | tee maps.out &
Then, you can start the ATAT@exciting interface executing
$ pollmach runstruct_exciting &
This will start a new cluster-expansion run, yielding more reliable results. The run will take a couple of hours, until a reasonable number of structures is calculated and the cluster expansion converges.