mcsqs

This code uses a Monte Carlo algorithm to find a Special Quasirandom Structure (SQS).
In writing this code, Axel van de Walle benefited from the input of
Alexey Dick, Dongwon Shin and Yi Wang.

If you use this code in a publication, please cite:
A. van de Walle, P. Tiwary, M. de Jong, D.L. Olmsted, M. Asta, A. Dick, D. Shin, Y. Wang, L.-Q. Chen, Z.-K. Liu,
Efficient stochastic generation of special quasirandom structures, Calphad Journal 42, pp. 13-18 (2013)

-> This code requires 2 input files:
1) A file defining the random state (by default rndstr.in) in a format similar to the lat.in that
   is needed for maps or corrdump but with partial occupation of the sites (see below).
2) A cluster file (by default clusters.out), generated, for instance, with the command line:
   mcsqs -2=... -3=... etc.
   where -2=... -3=... indicate the range of pairs, triplets etc.
   The code display the clusters found (format: nb of points, diameter, multiplicity).
   
   Internally, this actually calls the command
   corrdump -l=rndstr.in -ro -noe -nop -clus -2=... -3=...  ; getclus
      Note that the (new) -ro option allows corrdump to read the same input file as mcsqs (here rndstr.in)
      The -noe and -nop skip the empty and point clusters that are not used by mcsqs
      -clus indicates to generate clusters only
      -2=... -3=... indicate the range of pairs, triplets etc.
      getclus just indicates to write out the clusters (nb of points, length, multiplicity)
      See corrdump -h for more info.

When generating SQS, one typically needs to specify the -n=[number of atoms per cell] parameter on the command line.

-> Output files:
  bestsqs.out
	The best SQS found so far (in stardard ATAT structure file format - see mmaps -h for a description)
  bestcorr.out
	For each of the clusters selected,
	its number of pointd (1st column)
	its diameter (2nd column)
	the correlations of the best SQS found so far (3rd column)
	along with the target disordered state correlation (4th column)
	and the difference between the two (5th column).
  rndstrgrp.out
	A file containing the same info as the input file defining the random state (rndstr.in),
	but with symmetrically equivalent sites grouped together and separated by blank lines.
	(This helps determine which sites can have the same occupations.)
  mcsqs.log
	A log file.

The code stops if a perfect match is found (all correlations requested match the disordered state),
but this may never happen if there are too many clusters in clusters.out or -n (the number of atoms) is too small.
In any case, the bestsqs.out and bestcorr.out always contain the best solution found so far.
Stopping the code prematurely if the solution is satisfactory is fine.

-> Optional files:
  Creating a file called stopsqs stops the code cleanly.

  Creating a file called sqsparam.in (or as specified by the -pf option)
  with 4 numbers in it allows you to set the -wr, -wn, -wd and -T options during runtime.
  (for backward compatibility, if 2 numbers are specified, they set the -wr and -T options
   while the remaining options are set to their defaults.)

  The -rc option lets you specify supercells to use (via a sqscell.out file).
  Useful if brute force enumeration takes too long.
  The  sqscell.out usually comes from a previous mcsqs run but you can create it yourself.
  Note that the sqscell.out file must start with the number supercells you will provide
  and that supercells must be expressed in multiple of the axes defined in the rndstr.in file
  (in particular, all numbers entered would typically be integers).
  [If your are using a version prior to  3.07, these should be entered in cartesian coordinates.]

-> Format of the input file defining the lattice (specified by the -l option)

First, the coordinate system a,b,c is specified, either as
[a] [b] [c] [alpha] [beta] [gamma]
or as:
[ax] [ay] [az]
[bx] [by] [bz]
[cx] [cy] [cz]
Then the lattice vectors u,v,w are listed, expressed in the coordinate system just defined:
[ua] [ub] [uc]
[va] [vb] [vc]
[wa] [wb] [wc]
Finally, atom positions and types are given, expressed in the same coordinate system
as the lattice vectors:
[atom1a] [atom1b] [atom1c] [atomtype11]=[occupation11],[atomtype12]=[occupation12],...
[atom2a] [atom2b] [atom2c] [atomtype21]=[occupation21],[atomtype22]=[occupation22],...
etc.

Examples:

The fcc lattice of the Cu-Au system; request for an SQS at composition 0.5:
3.8 3.8 3.8 90 90 90
0   0.5 0.5
0.5 0   0.5
0.5 0.5 0
0 0 0 Cu=0.5,Au=0.5

A lattice for the Li_x Co_y Al_(1-y) O_2 system; request for an SQS
with different composition on each sublattice:
 0.707 0.707 6.928 90 90 120
 0.3333  0.6667 0.3333
-0.6667 -0.3333 0.3333
 0.3333 -0.3333 0.3333
 0       0      0       Li=0.75,Vac=0.25
 0.3333  0.6667 0.0833  O
 0.6667  0.3333 0.1667  Co=0.25,Ni=0.25,Al=0.5
 0       0      0.25    O

Please note that sites that are equivalent by symmetry must have the same occupation.
The file rndstrgrp.out can help you figure out which sites are equivalent.
If you want override this, you can simply use slightly different species labels (e.g. Fe_a,Fe_b) on the
sites whose occupation must differ, even though these sites are a priori equivalent.
Using different labels forces the code to consider the sites as inequivalent.

-> The objective function used is:

(sum (absolute difference from the disordered state correlations)*exp(-wd*(diameter of cluster))*(wn^(nb of points in cluster-2)))
/
(normalization for weights to sum up to 1 over clusters bigger than the smallest nonmatching cluster)

-sum over p wr* wn^(p-2)*(diameter of smallest cluster of p points or less whose correlation does not match the disordered state)

The wr, wn and wd are set through the -wr,-wn and -wd options respectively (or as the 3 first numbers of in the sqsparam.in file).
The diameter of a cluster is the length of the longest pair contained in a cluster (normalized by nearest-neighbor distance).

See routine calc_objective_func in mcsqs.c++ for a more precise description.

This objective function reflect researchers' desire to perfectly match all correlation up to some range.
Adding the absolute difference serves to guide the algorithm in the right direction to extend the range
of perfect match.

This objective function is a generalization of the one found in the Calphad paper cited above
(reduces to it for wn=1 and wd=0, the defaults).

-> Post-processing

If you have obtained an SQS and would like to see how good/bad the correlations you have NOT included
in the objective function are, you can use a command of the form:
   corrdump -l=rndstr.in -ro -noe -2=... -3=... -s=bestsqs.out
and compare to the output (for a perfectly random solid solution) of
   corrdump -l=rndstr.in -ro -noe -2=... -3=... -s=bestsqs.out -rnd

Beware that the above commands overwrite the clusters.out file.
Make sure to NOT include the -nop option (which is incompatible with the -rnd option).

The getclus command is useful to get a summary of what the clusters are (number of points, diameter, multiplicity).

<