Cluster Expansion of TiAl

for helium version of Exciting

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.

0. General Preparations

Please note: For this exercise of the CECAM tutorial it is preferable to use the CECAM cluster — see How to use exciting on the CECAM machines.

For running this example on the cluster of the CECAM tutorial, a summary of the settings is found under Settings_CECAM_Cluster_ATAT_Example.

Before starting, the shell variable EXCITINGROOT must be set by the user. This can be done using the following command, substituting the placeholder "local_path_to_exciting_root" by the directory where exciting was downloaded:

export EXCITINGROOT=/local_path_to_exciting_root

Moreover, in order to do this tutorial you need the following additional software:

 tar -zxvf atat2_86.tar.gz

Then, set the shell variable ATATROOT to the directory created upon extracting atat2_86.tar.gz. Eg. if you are the user exciting this directory is /home/exciting/atat, execute 
 export ATATROOT=/home/exciting/atat
 export PATH=$PATH:$ATATROOT/bin

To compile and install ATAT, follow the instructions in Chapter 3 of the manual, found here.
During the installation, make sure to define $ATATROOT/bin as directory for the executables.
  • ATAT@exciting: Download this collection of scripts here: ATAT@exciting_Nov_8_2010.tar. In a suitable place extract the scripts from the tar-file with the command
tar -xvf ATAT@exciting_Nov_8_2010.tar

This will create the directory ATAT@exciting_Nov_8_2010.
Then, set the shell variable ATAT_EXCITING_ROOT, substituting the placeholder "local_path_to_atat_exciting_root" by the directory where ATAT@exciting has been downloaded, (e.g.: /home/userATAT@exciting_Nov_8_2010/): 
 export ATAT_EXCITING_ROOT=/local_path_to_atat_exciting_root
 export PATH=$PATH:$ATAT_EXCITING_ROOT

Please note: In the input-files shown on this page, the placeholder EXCITINGROOT always needs to be replaced by the value of the $EXCITINGROOT variable.

1. Cluster expansion — concepts

The cluster-expansion technique is a sophisticated method to calculate alloy properties only based on the alloy configuration (=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 interchanging 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 the the ab-initio total energies. One very good way for doing this is to use the MIT Ab-initio phase-stability code maps of the ATAT package, in combination with the exciting code. A set of scripts and programs called ATAT@exciting does the connection between ATAT and exciting.

The maps code cares for all aspects of how to get the cluster expansion, i.e.:

  • it proposes structures to be calculated and provides input files in its own format;
  • it 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
  • based on the already known structures, it proposes new structures to be calculated in order to improve the cluster expansion.

The scripts of ATAT@exciting exciting

  • convert the structure files produced by maps to exciting format;
  • prepare an exciting input file, using the file exciting.wrap;
  • automatically perform the exciting calculations;
  • evaluate the result of the exciting calculation and provide the total energy to maps (inside the file energy);
  • communicate with maps via signal files (ready, wait, energy or error).

exciting, finally, determines the ground-state total energies for the structure produced by maps.

2. How to calculate the cluster expansion of TiAl with ATAT@exciting.

This section follows to a large extend parts of the ATAT manual, adapted to the specific situation of this session. You should find the original manual on your local machine under $ATATROOT/doc/manual.pdf or here.

2.1 Testing maps with a simple example.

Change to a directory of your choice (preferably empty) and type

cp $ATAT_EXCITING_ROOT/examples/TiAl/* .

Now you have three files in your directory:
The main input file lat.in, which describes the lattice type, the atomic positions, and which elements are allowed to "sit" on each site.
The man page of maps contains more detailed information on this file which is defining the lattice.

In order to start the maps program, execute

$ATATROOT/bin/maps -d &

Maps is running and waiting for a signal. Type

touch ready

to indicate that you are ready to for maps to generate a structure. Maps replies "Finding best structure…".
To find the structure just created, wait for done to appear and type: 
ls */wait

to observe that directory 0/ has been created. This directory contains a file str.out which describes the
structure whose energy needs to be calculated. The file wait is just a flag that allows you to find the newly
created directory. Let’s pretend that we have computed the energy of that structure. We need to let maps
know about it. Type, for instance (if 1.1 is the energy of the structure.):

echo 1.1 > 0/energy
rm 0/wait

Maps responds by "Finding best cluster expansion…", followed by "done". You can repeat the process
(touch ready, etc.) to add more structures. Maps will update the current cluster expansion every time a
new energy becomes known. (By default, maps checks every 10 sec.). For a description of the output files,
type:

$ATATROOT/bin/maps -h | more

or refer to the section "Command Reference" of the ATAT manual ($ATATROOT/doc/manual.pdf). A nice utility called mapsrep allows you to plot the results using gnuplot. To stop maps cleanly, type: 
touch stop

Suggestion: to clarify the output of the program, it is recommended that you run maps in one terminal window and type all other command in another terminal window.

2.2 Install and test the interface between MAPS and exciting

Type

$ATAT_EXCITING_ROOT/ezexciting

and follow the instructions posted on the screen to configure this command. Especially, change the variable excitingCMD inside the file ~/.ezexciting.rc (replacing EXCITINGROOT by he value of the $EXCITINGROOT variable!!) 
set excitingCMD="EXCITINGROOT/bin/excitingser"

Important: EXCITINGROOT must be replaced by the value of the $EXCITINGROOT variable

To test this interface, change to a directory of your choice and type

cp $ATAT_EXCITING_ROOT/examples/TiAl/* .

and start maps (unless maps is running already in that same directory): 
$ATATROOT/bin/maps -d | tee maps.out &

By using the tee command after the maps, the output is written both, to the display and and the file maps.out.

While MAPS automatically creates files that describe the geometry of the structures (called n/str.out, where n is the structure name), we need to provide a file containing all the other parameters needed by the first-principles code. Type:

cp $ATAT_EXCITING_ROOT/exciting.wrap .

to copy an example of such file in the current directory. For a description of these parameters, type: 
$ATAT_EXCITING_ROOT/ezexciting -h | more

Inside exciting.wrap, set the attribute speciespath to the value of EXCITINGROOT/species, replacing EXCITINGROOT by the value of the variable $EXCITINGROOT.

Then tell maps that you are ready to calculate a structure by executing

touch ready

Let’s say you have a new structure in directory 0 (created after typing touch ready). Type:

cd 0
runstruct_exciting

When the command has terminated, the directory 0 will contain a file energy giving the energy of the structure. If error messages appear consult the chapter Troubleshooting in the ATAT manual (see here).
If no error messages appear, you are ready for doing a cluster expansion with ATAT@exciting!

2.3 Starting ATAT@exciting for getting a cluster expansion — quick-start

Go back to the main directory of the last example, e.g. if you are in directory 0/ type

cd ..

For doing a quick calculation, do the following modifications in exciting.wrap:

  • Within the <groundstate> element, change the attribute nktot to 125, which corresponds to 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 executing

$ATATROOT/bin/pollmach runstruct_exciting &

This script will automatically call the runstruct_exciting command mentioned above repeatedly. To stop it cleanly, type:

touch stoppoll

(Disregard the warning message.)

2.4 Output of MAPS

The combination of maps with pollmach and runstruct_exciting will now, step by step, calculate new structures and improve the cluster expansion.
Each structure will be 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 will depend on the outcome of the first 3 structures. To see the existing structures in chronological order 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, such as the accuracy of the cluster expansion and various warning messages. Most of the messages pertains to the accurate prediction of the so-called ground states of the alloy system. The ground states, which are the structures that have the lowest energy for each given concentration, are extremely important to predict accurately because they determine which phases will appear on the phase diagram. The four possible messages are described below.

  • Not enough known energies to fit CE. Before displaying any results, maps waits until enough structural energies are known to fit a minimal cluster expansion containing only nearest-neighbor pair interactions and test its accuracy. Thus, the first cluster expansion is typically constructed after at least 4 structural energies have been computed (this number may vary as a function of the symmetry of the lattice).
  • Among structures of known energy, true ground states differ from fitted ground states. The current cluster expansion incorrectly predicts which structures have the lowest energy for given concentrations, among structures whose first-principles energy is known. The code has built-in checks to avoid this. However, in rare instances, it may be mathematically impossible to satisfy all the constraints that the code imposes for a cluster expansion to be acceptable. This problem ecomes increasingly unlikely as the number of calculated structural energies increases, so the user should just wait until the problem fixes itself.
  • Among structures of known energy, true and predicted ground states agree. Opposite of the previous message. When this message is displayed, maps also displays either one of the following two messages.
  • New ground states of volume less or equal to n predicted, see predstr.out. This indicates that the cluster expansion predicts that, at some concentration, there exist other structures that should have an energy even lower than the one of the structures whose energy has been calculated from first principles. In this case, maps will investigate the matter by generating those structures and requesting that their energy be calculated. Once again, the user should just wait for the problem to fix itself. The predicted ground states are flagged by a g in the predstr.out file, so that you can display their energy by typing grep g predstr.out
  • No other ground states of n atoms/unit cell or less exist. The energies of all ground states predicted by the cluster expansion have been confirmed by first- rinciples calculations. Because it can be computationally intensive to perform a full ground state search when interactions extend beyond the nearest-neighbor hell [6], maps uses a search algorithm that merely enumerates every possible structures having n atoms or less per unit cell and uses the cluster expansion to redict their energies. The upper limit n increases automatically as calculations progress. The log.out file also contains two other pieces of information:
  • Concentration range used for ground state checking: [a,b] This displays the user-selected range of concentration over which ground state checking is performed (which can be specified as a command-line option of the maps command: -c0=a -c1=b). It may be useful to relax the constraints that ground states be correctly reproduced over the whole concentration range when it is known that other parent lattices are stable in some concentration range. In this fashion, the code can focus on providing a higher accuracy in the concentration range where the user needs it.
  • Crossvalidation score: s. This provides the predictive power of the cluster expansion. It is analogous to the root mean square error, except that it is specifically designed to estimate the error made in predicting the energy for structures not included in the least-squares fit A. van de Walle and G. Ceder, Automating first-principles phase diagram calculations, Journal of Phase Equilibria, 23:348, 2002. It is defined as
(1)
\begin{align} CV = \left( \frac{1}{n} \sum\limits_{i=1}^n \left( E_i - \hat{E}_{(i)}\right)^2 \right)^{1/2} \end{align}

where $E_i$ is the calculated energy of structure i, while $\hat{E}_{(i)}$ is the predicted value of the energy of
structure i obtained from a least-squares fit to the (n − 1) other structural energies.

The maps code also outputs quantitative data in various output files. For details see section -> Output files in the man page of maps .

The simplest way to analyze this data is by typing

$ATATROOT/bin/mapsrep

This command displays a series of figures (to go from one figure to the next, close the current figure and hit "return" on the command line). All energies are in eV, and the concentration corresponds to "x" in the chemical formula TixAl1-x.

The most important figures are displayed in the following:

  • 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 red “$\square$"symbol. (Note that this ground state line is only meaningful if the log.out file contains “Among structures of known energy, true and predicted ground states agree.”)
fit_enes.png
  • The ab-initio formation energy of all structures calculated by exciting, and the associated ground state line.
calc_enes.png
  • A plot of the magnitude of the 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.
ecis.png
  • 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 the 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.
fit_residuals.png

2.5 Monitoring a cluster-expansion run

Using the tools described in the last chapter, you can monitor the run of your calculation. 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 doesn't 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, have a look at the file fit.out in the directory where maps was started. From the plot you should see, what the concentration for the bad data point is — look for structures which such a concentration in fit.out, and it should be easy to find out which structure belongs to this data point. 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, maps should not take into account this structure any more when looking for the next cluster expansion.

When the user is satisfied with the results (which are constantly updated), maps can be stopped by creating a file called stop in the current directory using the command:

touch stop

while the job dispatching system can be stopped by typing: 
touch stoppoll

A cluster expansion can be considered satisfactory when

  1. All ground states are correctly reproduced and no new ground states are predicted. (The log.out

file 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.)

  1. The crossvalidation score, as given in the log.out file, is small (typically less than 0.025 eV).
  2. Optionally, it is instructive to verify that the magnitude of the ECI decays as a function of the diameter

of the corresponding cluster and as a function of the number of sites it contains.

2.5 Starting ATAT@exciting for getting a cluster expansion — more serious calculation

For doing a quick calculation, do the following modifications in exciting.wrap:
Let's go now for a more realistic calculation:

  • create a new directory
  • copy the files lat.in, Al.lat.in, Ti.lat.in, exciting.wrap there.
  • Within the <groundstate> element, change the attribute nktot to 1728, which corresponds 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 again by executing

$ATATROOT/bin/maps -d | tee maps.out &

After, you can start the ATAT@exciting interface executing

$ATATROOT/bin/pollmach runstruct_exciting &
exercise
Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License