Cluster Expansion of TiAl

for lithium version of Exciting

---

Purpose: This tutorial shows how to do a cluster expansion of the total energy of fcc Ti_xAl_1-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 Ti_xAl_1-x in the whole concentration range from x=0 to x=1.

---

---

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: [https://www.brown.edu/Departments/Engineering/Labs/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.

Install ATAT@exciting

In order to install the ATAT@exciting tool, you should use the following command.

$ ezexciting

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,
• etc.

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

$ check_maps

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 Ti_xAl_1-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.

[read more on maps.log]

4.5 Information contained in maps.log

List of warning messages.

• 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 becomes 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 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-principles calculations. Because it can be computationally intensive to perform a full groundstate search when interactions extend beyond the nearest-neighbor shell, 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 predict their energies. The upper limit n increases automatically as calculations progress.

The maps.log 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 (see here for more information on cross validation). If we indicate with $E_i$ the calculated energy of structure $i$ and with $\hat{E}_{(i)}$ the predicted value of the energy of the structure $i$ obtained from a least-squares fit to the $n − 1$ other structural energies, then, the cross-validation score, $CV$, can be defined as

(1)

\begin{align} CV = \sqrt{\frac{1}{n} \sum\limits_{i=1}^n \left( E_i - \hat{E}_{(i)}\right)^2 }\,. \end{align}

---

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)

1. the Al concentration of the structure,
2. the energy obtained with exciting,
3. the energy as obtained from the fit,
4. the difference between the two energies,
5. a weight for the structure,
6. 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

1. 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".
2. The crossvalidation score, as given in the maps.log file, is small (typically less than 0.025 eV).
3. 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

1. concentration,
2. calculated energy,
3. fitted energy,
4. 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.

---