emc2

Easy Monte Carlo Code (emc2)
by Axel van de Walle

Command line parameters:

-T0 : initial temperature
-T1 : final temperature
-dT : temperature step
-db : inverse temperature step

Temperatures are given in units of energy unless the -k option is set.
-dT and -db are mutually exclusive. Which option you use determines
whether T or 1/T are unformly spaced. The output file always shows T.
Avoid setting -T0 or -T1 to 0: The output will be nonsensical.

-k : Sets boltman'z constant (default k=1). This only affects how
     temperatures are converted in energies.  -k=8.617e-5 lets you enter
     temperatures in kelvins when energies are in eV.
     (You can also select this value by using the -keV option.)

-mu0 : initial chemical potential
-mu1 : final chemical potential

  By default, these are input as dimensionless values defined as
  follows: If x is integer, x is the chemical potential that
  stabilizes a two phase equilibrium between ground state x-1 and
  x. (Ground states are numbered starting at 0.) Fractional values
  interpolate linearly between these integer values.  Negative values
  or values larger than the number of ground states - 1 are allowed.
  The values of mu are found by linear extrapolation.  If the -abs
  option is specified, the value of mu are in units of energy per spin
  value (as in the output file).  (The ground states are read in from
  the file gs_str.out .)

  If there are only two ground states, the only correction performed is
  to shift mu so that mu=0 stabilizes a two-phase equilibrium between
  the two ground states.
  If there are less than 2 ground states (!), no correction is made.

-dmu : chemical potential step (expressed in the same units as mu0 and mu1).

NOTE: If mu1 is omitted, only a scan through T is performed keeping mu=mu0.
      If T1 is omitted, only scan through mu is performed keeping T=T0.

-gs : Gives the index of the ground state to use as an initial spin
      configuration (the leftmost pure element is numbered 0).  If the
      index is -1, the disordered state with an average spin of zero
      is used as the starting configuration.

-phi0 : value of the grand canonical potential at the initial point of
        the run.  If left unspecified, it is set to the grand canonical
        potential of given by either the 1-spin Low Temperature Expansion
        or the High Temperature Expansion, depending whether the initial
        state is an ordered or a disordered phase.

-er : enclosed radius. The Monte Carlo cell will the smallest possible
    supercell of unit cell of the initial configuration such that a
    sphere of that radius fits inside it.  This allows you to specify
    the system size in a structure-independent fashion.

-innerT : by default, the inner loop is over values mu while the outer
          loop is over values of T. This flag permutes that order.

-eq : number of equilibration passes. (Equilibration is performed at
      the beginning of each step of the outer loop.)

-n : number of Monte Carlo passes performed to evaluate thermodynamic
     quanties at each step of the inner loop.

-dx: instead of specifying -eq and -n, you can ask the code to equilibrate
     and run for a time such that the average concentration is accurate
     within the target precision specifified by -dx=.

-tstat : Critical value of the test for discontinuity. The code is
         able to catch phase transformations (most of the time) when
         going from an ordered phase to another or to the disordered
         state. This involves a statistical test which a
         user-specified confidence level. The default, 3, corresponds
         to a 0.4% chance of finding a transition where there is
         none. (Refer to a standard normal table.)  -tstat=0 turns off
         this option.  Suggestion: if a phase transition is
         undetected, first try to reduce dT or dmu or increase n or decrease dx
         before toying around with this parameter.  Also: beware of
         hysteresis.

-cm: canonical mode (constant composition, set with -x=... in the range ]-1,1[ ).
     Note that thermodynamic integration is not fully supported:
     only starting from an ordered phase and only as a function of T, not x.
     The lte, mf, hte approximations are not available.

-sigdig : Number of significant digits printed. Default is 6.

-o:       Name of the output file (default: mc.out).

Tricks:

   To read parameters from a file, use:
    emc2 `cat inputfile`
   where inputfile contains the commands line options.

   To selectively display a few of the output quantities, use:
    emc2 [options] | cut -f n1,n2,n3,...
   where n1,n2,n3,... are the column number desired (see below).

Input files:

lat.in       : description of the lattice.
clusters.out : describes the clusters. 
eci.out      : provides the ECI. 
gs_str.out   : a list of ground states, in increasing order of concentration.

   These 4 files can be created by maps.
   See maps documentation (maps -h) for a description of the formats.

Optional input file:

teci.out     : if present, provides temperature-dependent eci (overrides eci.out)
               (Note that, even when the teci.out file is used, column 6 of the output file
                reflects only the configurational contribution to the heat capacity.)

The format this file is:
[maximum temperature: Tm]
[number of temperatures where eci are provided: nT]
[ECIs for temperature 0]
[ECIs for temperature Tm/(nT-1)]
[ECIs for temperature 2*Tm/(nT-1)]
...
[ECIs for temperature Tm]

Note that these numbers can be seperated by blanks or newlines, as desired.

Format of the output file:

Each line contains, in order:

 1) T:  Temperature
 2) mu: chemical potential (derivative of the free energy wrt to average spin)
 3) E-mu*x:  Average energy (per spin)
 4) x:  Average Concentration [ranges from -1 to 1]
 5) phi: grand canonical potential per spin (F-mu*x, where F is the Helmholtz free energy)
 6) E2: Variance of the energy (proportional to heat capacity)
 7) x2: Variance of the concentration (proportional to susceptibility)
 8) E_lte-mu*x_lte: calculated with a one spin Low Temperature Expansion
 9) x_lte
10) phi_lte
11) E_mf-mu*x_mf:  calculated with the Mean Field approximation
12) x_mf
13) phi_mf
14) E_hte-mu*x_hte: calculated with a High Temperature Expansion (ideal solution + polynomial in x)
15) x_hte
16) phi_hte
17) lro: Long Range Order parameter of the initial ordered phase (=0 if initial phase is disordered).
18-) corr: the average correlations associated with each cluster.

NOTE: to obtain 'canonical' rather than grand canonical quantities,
use the -g2c option. This has the effect of adding mu*x to columns
3,5,8,10,11,13,14,16.
Then, for instance, column 5 gives F, the Helmholtz free energy while column 3 gives E, the energy.