top of page

Generate Quasirandom Doping Structure with MCSQS method implemented by ATAT

Introduction Generating the model of a randomly disordered solid solution phase has alway been a hard nut to crack. The MCSQS (Monte Carlo Special Quasirandom Structure) method offers a new algorithm to generate Special Quasirandom Structures (SQS), i.e., best periodic supercell approximations to the true disordered state for a given number of atoms per supercell. The method is based on a Monte Carlo simulated annealing loop with an objective function that seeks to perfectly match the maximum number of correlation functions. The proposed method optimizes the shape of the supercell jointly with the occupation of the atomic sites, thus ensuring that the configurational space searched is exhaustive and not biased by a pre-specified supercell shape.

The MCSQS method can be implemented by Alloy Theoretic Automated Toolkit (ATAT), which a collection of alloy theory tools developped by Axel van de Walle et. al. Please cite this paper if you use this code in a publication:

A. van de Walle, et. al., Efficient stochastic generation of special quasirandom structures, Calphad Journal 42, pp. 13-18 (2013)

Installation of ATAT on a Linux Machine 1. Make sure you have all the following utilities installed prior to the installation of ATAT: • g++ version 2.7.2 or later. Type g++ --version to verify this. This package can be downloaded from • GNU make (any version). Type make --version to verify this. On some systems this command may be called gmake or gnumake. This package can be downloaded from

[xwang99@login02 xwang99]$ g++ --version
g++ (GCC) 4.8.5 20150623 (Red Hat 4.8.5-44)
Copyright (C) 2015 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO

[xwang99@login02 xwang99]$ make --version
GNU Make 3.82
Built for x86_64-redhat-linux-gnu
Copyright (C) 2010  Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

2. Download and Compile ATAT: The ATAT package can be downloaded from

tar -xvf atatX XX.tar.gz # Here XXX is the version number.
cd atat
mkdir bin # Creat a directory to accomodate the output executable files of the tools
sed -i '1c BINDIR=/your directory/atat/bin' makefile # Change the output directory to yours
make install

Wait for a few minutes and then you will see a lot of executable files in /your directory/atat/bin, including mcsqs.

root@DESKTOP-54J707O:~/atat/bin# ls
apb chl extract_vasp gce infdet mcsqs nntouch sspp blanktonl cleanvasp ezvasp gencs kmesh memc2 node str2cif calc clusterexpand felec gensqs lookup minload pdef str2xyz calcbulk clusterpredict fitfc genstr lsfit mkteci phb strpath cellcvrt corrdump fitsvsl getclus makelat mmaps pollmach svsl checkcell csfit fixcell getlines maps mmapsrep robustrelax_vasp symbrklib checkerr_vasp cv fixeol getproto mapsrep nltoblank runstruct_vasp triph checkrelax emc2 foreachfile getvalue mcdroplast nnshell sqs2tdb wycked

You may also want to add this command to your ~/.bashrc

export PATH=/your directory/atat/bin:$PATH # For bash, Add the path of the installation directory to $PATH
setenv PATH /your directory/atat/bin:$PATH # For csh

Generating SQS: Using V2Fe2O4 as an example Target: Creat a V4O4 model and replace 2 V sites with 2 Fe.

  1. Prepare the ATAT input file that contains the coordinates information:

Remember to remove all the annotations "e.g. # Line 1-6: ..." in to avoid the "Segmentation fault" error.

4.0619997978     	0.0000000000     	0.0000000000 # Line 1-6: Lattice parameters
0.0000000000     	4.0619997978     	0.0000000000
0.0000000000     	0.0000000000     	4.0619997978
1 0 0
0 1 0
0 0 1
0.000000000     	0.000000000     	0.000000000 V=0.5,Fe=0.5 # Line 7-14: Atomic fraction coordinates
0.000000000     	0.500000000     	0.500000000 V=0.5,Fe=0.5 # 50% V and 50% Fe
0.500000000    	0.000000000     	0.500000000 V=0.5,Fe=0.5
0.500000000     	0.500000000     	0.000000000 V=0.5,Fe=0.5
0.500000000     	0.500000000     	0.500000000 O
0.500000000     	0.000000000     	0.000000000 O
0.000000000     	0.500000000     	0.000000000 O
0.000000000    	0.000000000     	0.500000000 O

2. If you hope the output crystal structure has the same lattice constants as the input crystal, you may want to add another input file: sqscell.out


1.000 0.000 0.000
0.000 1.000 0.000
0.000 0.000 1.000 # These settings keep the output lattice constants the same as the input ones.

3. Type the command: corrdump -ro -noe -nop -clus -2=6 -3=5.2 -4=5.2 The function of corrdump is to 1) reads the lattice file (specified by the -l option). 2) determine the space group of this lattice and writes it to the sym.out file. 3) find all symmetrically distinct clusters that satisfy the conditions specified by the options -2 through -6. For instance, if -2=6 -3=5.2 is specified, only pairs shorter than 6 units and triplets containing no pairs longer than 5.2 will be selected. 4) write all clusters found to clusters.out. If the -c option is specified, clusters are read from clusters.out instead. ... See the manual for more details:

4. Invoke the mcsqs code:

mcsqs -rc -n=8

Here -rc means that the mcsqs code reads the settings in sqscell.out; -n=8 is the number of atoms in the crystal model. Normally, the mcsqs code will keep searching and will not stop by itself. Therefore we usually set a time limit of mcsqs:

timeout 120 mcsqs -rc -n=8

5. Generate the cif file of the SQS: Once completed, the generated file bestsqs.out contains the structural informaiton of the SQS. Use the command to convert it to cif.

str2cif < bestsqs.out > V2Fe2O4.cif

Finally, the SQS of V2Fe2O4.cif is obtained.

6. Frequently encountered problems Error message when using mcsqs: "Impossible to match point correlations due to incompatible supercell size." This error is caused by the too small input crystal strucutre, which is not large enough to generate a SQS. To solve this problem you may want to set a larger supercell of the sqscell.out such as:


1.000 0.000 0.000
0.000 2.000 0.000
0.000 0.000 1.000

and then enlarge the number of atoms when invoke mcsqs:

mcsqs -rc -n=X

Here X = 2*the atom numbers in the input For instance, in our case, mcsqs -rc -n=16.


If you found this tutorial helpful, consider joining our community by making a donation. Your support will enable me to continue creating valuable content while also supporting my baby's care. Together, we can make a meaningful impact. Thank you!


bottom of page