Site-Occupation Disorder
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
Makefile version 0.47 Jan 31, 2019 version 0.47 Jan 31, 2019


SOD 0.47 - Notes for users

SOD (standing for Site-Occupation Disorder) is a package of tools for the computer modelling of periodic systems with site disorder, using the supercell ensemble method.

The package is distributed under the GPL licence.

You can find below the essential info needed to use SOD. Please note that SOD authors can give only limited support to users.


  • Identification of all inequivalent configurations of site substitutions in an arbitrary supercell of an initial target structure with any space group symmetry.
  • Calculation of the degeneracies of configurations.
  • Generation of input files for codes like GULP and VASP.
  • Simple extrapolation of energies from low to high concentrations within a supercell.
  • Statistical mechanics processing of output.

Content of the folders

  • sod(version)/src contains the source files.
  • sod(version)/sgo is a library of space group operators (e.g. 131.sgo contains the operators of the space group 131).
  • sod(version)/bin contains the executables. Linux executables are provided here.
  • sod(version)/examples contains three examples, based on the cubic perovskite, rutile and rocksalt structures.

Compiling & installing SOD

  • Download the file sod(version).tar.gz (e.g. sod0.44.tar.gz) and copy to a directory, say ROOTSOD:
tar xzvf sod(version).tar.gz
  • Make compile all the executables into the bin folder:
> make all
  • Add ROOTSOD/sod(version)/bin to your executables path
# add the bin folder to the executables path in your .bashrc file
export PATH=$PATH:ROOTSOD/sod(version)/bin

Running SOD

  • We recommend to create a new folder (say FOLDER_NAME) for each application. This will be referred to as the working directory.

  • In FOLDER_NAME, you must create a file named INSOD which contains all the information for running the combinatorics part of the program. Use the INSOD file given in one of the examples. The file is self-explanatory. The format of this file is rigid, so keep the same number of blank lines.

  • In FOLDER_NAME, you must also include a file named SGO with the matrix-vector representations of the symmetry operators. First check if your space group is included in the ROOTSOD/sod(version)/sgo library; if this is the case, just copy the file into your working directory, under the name SGO:

cp ROOTSOD/sod(version)/sgo ./SGO

otherwise you have to create the file using the Tables of Crystallography, or from the website of the Bilbao Crystallographic Server <>. The first three numbers in each line are one row of the operator matrix and the fourth number is the component of the operator translation vector.

  • If you want to generate Gulp input files for all the independent configurations found by SOD, in addition to setting FILER=1 in the INPUT file, you must provide two files in the working directory:

top.gulp contains the heading of the gulp input file (until the keyword cell).

bottom.gulp contains the tail of the gulp input file (everything after the list of coordinates, including species, potentials, etc).

  • To run the combinatorics program, just type:

Output of

  • When the programme finishes, it writes to the standard output the total number of configurations and the number of independent configurations according to the crystal symmetry, plus some other useful information.

  • It writes the data file OUTSOD, which contains information on the independent configurations (one line for each configuration). The first number is the index of the configuration, the second is its degeneracy, and the next numbers are the substitution sites.

  • It also writes the file EQMATRIX, which gives information about how each supercell operator transforms each atom position.

  • The directory CALCS is generated, which contains the input files for GULP or VASP, a copy of the OUTSOD and EQMATRIX files, and a script that sends the job.

Configurational averages and thermodynamics:

In order to calculate configurational averages and obtain thermodynamic quantities, you need to execute the script:

which requires 4 input files:

  • OUTSOD, which was the output from sod_comb

  • TEMPERATURES, a list of temperatures for the Boltzmann statistics, in one column, e.g.:


(if the TEMPERATURES file does not exist, sod_stat calculates thermodynamic properties at T=1K, 300K, 1000K and in the limit of a very high temperature).

  • ENERGIES, which contains (in one column) the energies of all the configurations, in the same order that they were generated by SOD (like in the OUTSOD file). There are some scripts in ROOTSOD/sod(version)/bin/ to help you do this:

    1. If you are using GULP, the script will extract all the energies, assuming all output files, with extension .gout, are in the same folder. If you have calculated vibrational free energies for each configuration, will extract these.

    2. If you are using VASP, the script will extract all the energies, assuming you have separate folders for each configuration.

  • DATA, which contains ncol colums of data to average. The first line contains just the number ncol of columns to read. For example:

34.5   4.34
37.7   4.35
35.6   4.38
38.8   4.41

The data can be cell lenghts, or volumes (please see SOD papers for strategies on how to obtain average cell parameters) or any other observable obtained from the calculations. Scripts like can help you do this, please edit carefully before using them. will generate two files: probabilities.dat and statistics.dat, whose content is self-explanatory.

Important note: While configurational averages (e.g. of cell parameters and enthalpies) tend to converge very quickly with supercell size, entropies and free energies, which are not defined by averaging, converge very slowly with supercell size, and are generally in large error when using the SOD method. We therefore do not recommend using SOD for the calculation of entropies and free energies, unless appropriate correcting procedures have been used.

Extrapolating energies from low to high concentrations

From version 0.44, we have implemented a simple pair-based extrapolation (SPBE) method, which uses the energies from n= 0, 1 and 2 substitutions to predict the energies for n>2 (equation 1 in Arce-Molina et al. PCCP 2018, 20, 18047-18055).

In order to run this program, you will need the following files:

  • EQMATRIX obtained from running sod_comb at any composition
  • OUTSOD for n substitutions
  • ENERGIES0: a file containing a single number, which is the energy for n=0
  • ENERGIES1 and OUTSOD1: the ENERGIES and OUTSOD files for n=1
  • ENERGIES2 and OUTSOD2: the ENERGIES and OUTSOD files for n=2
  • INSPBE file if you want to introduce some rescaling parameters (optional, see below)

If all the above files are present in a folder, you can run the spbe module by running the spbesod executable.

However, the easiest way to run the spbe module is like this:

  • Use the names n00 n01 n02 n03 etc for the folders containing the calculations for 0, 1, 2, 3... substitutions.
  • Make sure that the folders n00, n01 and n02 contain an ENERGIES and an OUTSOD file each (OUTSOD is not necessary for n00)
  • If you want to use spbe, say, for n=3, first run sod_comb for n=3 substitutions, rename CALCS to n03, and create a folder within n03, say n03/spbe/
  • From the n03/spbe folder, just run the script, which will copy the relevant input files into the current folder and will call spbesod
  • It is also possible to run the spbe program using data from the other end of the solid solution (i.e. x=1). In that case, run the script, which will copy the files from the folders with N, N-1, N-2 substitutions, will "invert" the OUTSOD files as needed, and call spbesod.

Finally, it is possible to introduce some rescaling in the first-order and second-order terms to improve the match with a reference set of calculations. You need to give two reference energies in the INSPBE file. The recommended procedure is to run spbe first without rescaling, pick the minimum-energy and maximum-energy configurations (they are identified at the end of the OUTSPBE file) and run them with DFT (or whatever method provides the reference/target values), then input these two values as reference energies in INSPBE, and run the script again. An example is given in the distribution (sodx.xx/examples/01-perovskite-gulp/n04/spbe0/INSPBE), where the reference energies for configurations 1 and 6 are given as input. When the spbe program runs, it creates a template INSPBE.tmp that can be edited and copied into INSPBE.

Citing SOD

If you use SOD in your research work, please include a citation to this article:

Grau-Crespo, R., Hamad, S., Catlow, C. R. A., & De Leeuw, N. H. (2007). Symmetry-adapted configurational modelling of fractional site occupancy in solids. Journal of Physics: Condensed Matter, 19(25), 256201. Original Paper

Happy SODing!!!

Ricardo Grau-Crespo (