\documentclass[a4paper,10pt]{article}
\usepackage[top=2.5cm, bottom=2.5cm, left=2.1cm, right=2.1cm]{geometry}
\usepackage[utf8]{inputenc}  %unicode support

%%% Load packages
\usepackage{amsthm,amsmath}
\RequirePackage{natbib}
%\usepackage{natbib}
%\RequirePackage{hyperref}
%\usepackage[applemac]{inputenc} %applemac support if unicode package fails
%\usepackage[latin1]{inputenc} %UNIX support if unicode package fails
\usepackage{multirow}
\usepackage{graphicx}
\usepackage{placeins}
\usepackage{array}
\usepackage[version=3]{mhchem}
\usepackage{enumitem}
\usepackage{lmodern}
\usepackage{textcomp}
\usepackage{gensymb}
\usepackage{minted}
\usepackage{fancyvrb}
\usepackage{color, soul}
\usepackage{hyperref}
\usepackage{siunitx}
\usepackage{tikz}
\usetikzlibrary{shapes,positioning}

%%% Put your definitions there:
\renewcommand\thesubsubsection{\arabic{subsubsection}}

%opening
%\title{\textbf{Supplimentary materials.} \linebreak \linebreak Supercell program: a combinatorial structure-generation approach for the local-level modeling of atomic substitutions and partial occupancies in crystals.}

\title{\textbf{Supercell program tutorial.}}

\author{Kirill Okhotnikov, Thibault Charpentier and Sylvian Cadars}

\begin{document}

\maketitle

\newcolumntype{M}[1]{>{\centering\arraybackslash}m{\dimexpr#1\linewidth-2\tabcolsep}}
\newcommand{\sups}{\mbox{\textit{supercell}}}
\newcommand{\Sups}{\mbox{\textit{Supercell}}}
\newcommand{\clic}[1]{\Verb^#1^}

\overfullrule=2cm

\section*{Examples of \sups{} program application.}

In the tutorial we discuss technical details of the \sups{} program use. All the examples are based on literature data, which was compared in detail to the results obtained with \sups{} where possible.

\subsection*{Basic functionality: \ce{Ca2Al2SiO7}.}

To understand how the \sups{} program works it is necessary to know the structure of Crystallographic Information File (CIF), which is used as both the output and input formats. (The conversion to a number of other format is made very easy by the OpenBabel library, which is used by the program). The CIF file is a standard text file format for representing crystallographic information. The format promulgated by the International Union of Crystallography (IUCr) and the detailed information about it can be found on IUCr site (\url{http://www.iucr.org/})

The structure of the sections of a CIF file relevant to our program will be illustrated with the \linebreak \clic{Ca2Al2SiO7.cif} file located in the \path{supercell/data/example} folder. 

\begin{Verbatim}[commandchars=\\\{\}, numbers=left]
\textcolor{red}{data_Ca2Al2SiO7}
\textcolor{blue}{_cell_length_a}                   7.716
\textcolor{blue}{_cell_length_b}                   7.716
\textcolor{blue}{_cell_length_c}                   5.089
\textcolor{blue}{_cell_angle_alpha}                90
\textcolor{blue}{_cell_angle_beta}                 90
\textcolor{blue}{_cell_angle_gamma}                90
\textcolor{blue}{_cell_volume}                     302.982
\textcolor{blue}{_symmetry_space_group_name_H-M}   'P -4 21 m'
\textcolor{blue}{_symmetry_int_tables_number}      113
\textcolor{magenta}{loop_}
\textcolor{blue}{_space_group_symop_operation_xyz}
x,y,z
1/2-y,1/2-x,z
y,-x,-z
1/2-x,1/2+y,-z
-x,-y,z
1/2+y,1/2+x,z
-y,x,-z
1/2+x,1/2-y,-z
\textcolor{magenta}{loop_}
\textcolor{blue}{_atom_type_symbol}
\textcolor{blue}{_atom_type_oxidation_number}
  Ca1  +2
  AlT1 +3
  AlT2 +3
  SiT2 +4
  O1   -2
  O2   -2
  O3   -2
\textcolor{magenta}{loop_}
\textcolor{blue}{_atom_site_label}
\textcolor{blue}{_atom_site_fract_x}
\textcolor{blue}{_atom_site_fract_y}
\textcolor{blue}{_atom_site_fract_z}
\textcolor{blue}{_atom_site_occupancy}
AlT1 0.00000 0.00000 0.00000 1.00000
\colorbox{yellow}{AlT2 0.14310 0.35690 0.95280 0.50000}
\colorbox{yellow}{SiT2 0.14310 0.35690 0.95280 0.50000}
O1   0.50000 0.00000 0.18840 1.00000
O2   0.14180 0.35820 0.28320 1.00000
O3   0.08720 0.17060 0.80330 1.00000
\end{Verbatim}

The file consists of cell and spacegroup information at lines 2-21 (required by \sups{}), atoms charges (lines 22-30, optional) and atomic positions (lines 32-43, required). The partial occupancies of some sites (last column in lines 32-43) are a feature specific to disordered crystals. In the case presented here, partial occupancies are found for AlT2 and SiT2 sites, which are highlighted above. Both correspond to the same crystallographic position and will therefore be assigned to a single group by the \sups{} program. All other sites are fully occupied and will remain as such throughout the procedure.

The \sups{} program is a user-friendly command-line software. It can be directly applied to CIF files. Let us use it for an \clic{Ca2Al2SiO7.cif} file in 
\path{supercell/data/examples} folder.
\begin{Verbatim}[breaklines]
supercell -d -i Ca2Al2SiO7.cif -m
\end{Verbatim}

The output of the command will be
\begin{minted}[linenos, breaklines]{shell-session}
kirill@asus-laptop:~/supercell/data/examples$ supercell -d -i Ca2Al2SiO7.cif -m 
-----------------------------------------------------
-            Supercell program (v2.0)               -
-----------------------------------------------------
-      Authors:   * Kirill Okhotnikov               -
-                  (kirill.okhotnikov@gmail.com)    -
-                 * Sylvian Cadars                  -
-                  (sylvian.cadars@cnrs-imn.fr)     -
-                 * Thibault Charpentier            -
-                  (Thibault.Charpentier@cea.fr)    -
-----------------------------------------------------
-  please cite:                                     -
-    K. Okhotnikov, T. Charpentier and S. Cadars    -
-    J. Cheminform. 8 (2016) 17 - 33.               -
-----------------------------------------------------

Command line: supercell -d -i Ca2Al2SiO7.cif -m 
Random SEED: 1452874625
CIF file info: 
  INFO: Using symmetries from space group.
  
Initial system:
  Chemical Formula: Al4 Ca4 O14 Si2

Supercell system (1x1x1):
  Size a=7.716, b=7.716, c=5.089

Current charge balance option is "try"
Total charge oxidation state (cif):  0
Total charge cell:   0
Charge balancing:   yes
----------------------------------------------------------------
| Atom Label    |       charge          | mult  | occup x mult
|               | Ox. state     | Used  | (cif) |                
----------------------------------------------------------------
|  AlT1         |  3            |  3    |  2    |  2
|  AlT2         |  3            |  3    |  4    |  2
|  Ca1          |  2            |  2    |  4    |  4
|  O1           |  -2           |  -2   |  2    |  2
|  O2           |  -2           |  -2   |  4    |  4
|  O3           |  -2           |  -2   |  8    |  8
|  SiT2         |  4            |  4    |  4    |  2
----------------------------------------------------------------

Chemical formula of the supercell: Al4 Ca4 O14 Si2
Total charge of supercell: 0

----------------------------------------------------
 Identification of groups of crystallographic sites 
----------------------------------------------------

 Group 1 (2 atomic positions in supercell):
  * Site #1: AlT1 (occ. 1) -> FIXED with occupancy 1.000.

 Group 2 (4 atomic positions in supercell):
  * Site #1: AlT2 (occ. 0.5) -> distributed over 2 positions out of 4 (actual occ.: 0.500).
  * Site #2: SiT2 (occ. 0.5) -> distributed over 2 positions out of 4 (actual occ.: 0.500).
  Number of combinations for the group is 6

 Group 3 (4 atomic positions in supercell):
  * Site #1: Ca1 (occ. 1) -> FIXED with occupancy 1.000.

 Group 4 (2 atomic positions in supercell):
  * Site #1: O1 (occ. 1) -> FIXED with occupancy 1.000.

 Group 5 (4 atomic positions in supercell):
  * Site #1: O2 (occ. 1) -> FIXED with occupancy 1.000.

 Group 6 (8 atomic positions in supercell):
  * Site #1: O3 (occ. 1) -> FIXED with occupancy 1.000.

Minimal distance between atoms of two distinct groups: 1.68147 A.

-------------------------------------------------
The total number of combinations is 6
-------------------------------------------------
8 symmetry operation found for supercell.
Total enumeration time: 0:00:0.000507297
Combinations after merge: 2
\end{minted}

The output header provides a technical information about the program. Random seed (line 18) stores information about seed, using for random numbers calculation in the run. By default, it changes from run to run, but you can specify it explicitly in command line to reproduce the run later. 
Next lines of the output give information about the initial and supercell system sizes, the total charge, and the chemical formula. The information about atomic species properties in the system are summarized in the table (lines 32-43). The multiplicity parameter is calculated using the symmetry information and atomic positions. The total charge is calculated using \path{_atom_type_oxidation_number} data in the CIF file or user-defined charges, specified with commands of the type:
\clic{-p "Ca1:c=+2" -p "O1:c=-2"...}
See the manual and other examples below for more information on the \clic{-p} option. The information about the total number of combinations is presented in line 75. The last three lines (77-79) appear only when the \clic{-m} option is present in the command line. 

To generate structures for cell $1\times1\times2$ (the example presented in the main paper), the \sups{} program should be run with the following parameters:
\begin{Verbatim}[breaklines]
supercell -i Ca2Al2SiO7.cif -s 1x1x2 -m -o Ca2Al2SiO7_cell_1x1x2
\end{Verbatim}
where the supercell size is controlled by the \clic{-s} option (with ``x'' letter to represent the ``$\times$'' symbol) and the output file name prefix by the \clic{-o} parameter.

\subsection*{Sampling methods: \ce{Ca2Al2SiO7}.}

The number of combinations increases extremely rapidly with the number of atoms in the supercell (see main text and table~\ref{tab:FeSbO4} for example). In the case of the \ce{Ca2Al2SiO7} compound, the number of unique combinations for a $2\times2\times2$ supercell will be \num{9402622} which is too high to process and store, therefore sampling is required. \Sups{} offers a few methods of sampling. All of them are controlled by the \clic{-n <type><number>} option, where \clic{<type>} is a letter that determines the sampling method (\clic{r} for random, \clic{l} or \clic{h} for lowest- or highest-$E\_C$ structures, \clic{f} or \clic{a} for first or last-generated generated configurations) and \clic{<number>} is the number of sampled configurations. To get \num{100} configurations picked randomly for the supercell $2\times2\times2$ the program should be executed with the following parameters:
\begin{Verbatim}[breaklines]
supercell -i Ca2Al2SiO7.cif -s 2x2x2 -m -n r100 -v 2 -o Ca2Al2SiO7_r100
\end{Verbatim}
The option \clic{-v 2} switches the verbosity to level 2, to follow the program execution, this example being time consuming.

Increasing the supercell size to $2\times2\times3$ gives a total number of combinations around $3.2 \times 10^{13}$. This number is too high to be treated by \sups{} directly, but some of random configurations can nevertheless be created with our program, even for such a big system. To perform the operation, the initial file should be processed with \sups{} program first.
\begin{Verbatim}[breaklines]
supercell -i Ca2Al2SiO7.cif -p "*:fixed" && mv supercell_i0.cif Ca2Al2SiO7_abg.cif
\end{Verbatim}
The parameter \clic{-p "*:fixed"} means, that all of the groups should be fixed (stored to output file with the initial partial occupancies). The result file \path{Ca2Al2SiO7_abg.cif} will then be used as an initial structure, but with P1 space group. It contains four crystallographic sites with partial Al/Si occupation. The sites \clic{(Al|Si)T2} should be renamed to \clic{(Al|Si)T2a} (for $z=0.95280$) and \clic{(Al|Si)T2b} for positions with $z=0.04720$. Because the group identification procedure in the \sups{} program uses the site labels as a first criterion (see main text for details), this new input CIF file now results in the identification of 2 independent groups of sites. The permutations can now be performed step by step, with the commands:
\begin{Verbatim}[breaklines]
rm Ca2Al2SiO7_step*.cif
supercell -i Ca2Al2SiO7_abg.cif -s 2x2x3 -p "*T2b:fixed" -n r1 -o Ca2Al2SiO7_step1 
supercell -i Ca2Al2SiO7_step1_ir*.cif -n r1 -o Ca2Al2SiO7_step2
\end{Verbatim}
The first \sups{} execution generates one random structure (with \clic{-n r1}) within the T2a group, leaving T2b group partially occupied (\clic{-p "*T2b:fixed"}). The next command generates a random configuration within the T2b group, based on the previously-generated file (\clic{Ca2Al2SiO7_step1_ir*.cif}). Strictly speaking, the generated structure is nearly random, not fully. The splitting of T2 group to T2a and T2b imposes an occupancy restriction of this groups, 12 atoms of Al and 12 atoms of Si in each group. The restriction can be overcome to some extent by setting the number of Al and Si atoms for each group manually with \clic{-p} command. The parameter is discussed below.

\subsection*{Disorder exploration in \ce{FeSbO4}: Comparison with SOD code.}

The \ce{FeSbO4} system was explored with the SOD program in ref. \cite{Grau2007}. This compound has cation disorder on a single octahedral \ce{MO6} site. The results of the SOD program reported in ref. \cite{Grau2007} are reproduced here in table~\ref{tab:FeSbO4}. Applying the \sups{} program with the symmetry-merging (\clic{-m}) option for the same supercell sizes gives exactly the same number of symmetry operations, total number of combinations and number of independent configurations as with the SOD code.

\begin{table}[ht!]
\caption{Total number of possible combination of atoms for different supercell sizes of \ce{FeSbO4} for comparison with the results published in ref. \cite{Grau2007}.}
\renewcommand{\arraystretch}{1.7}
\newcolumntype{x}[1]{>{\centering\arraybackslash}m{#1}}
\newcolumntype{y}[1]{>{\arraybackslash}m{#1}}
\centering
\begin{tabular}{|x{2.0cm}|x{2.3cm}|x{2.3cm}|x{2.3cm}|x{2.3cm}|}
\hline
Cell, $a\times~b~\times~c$ & Number of symmetry operations & Total number of configurations & Number of unique configurations &  \sups{}/SOD run time\textsuperscript{**} \\
\hline 
 ~$1\times 1 \times 1$\textsuperscript{*} & 16  & 2                   & 1        & \textless~1~s \\
 ~$1\times 1 \times 2$\textsuperscript{*} & 32  & 6                   & 2        & \textless~1~s \\
 ~$1\times 1 \times 3$\textsuperscript{*} & 48  & 20                  & 3        & \textless~1~s \\
 ~$1\times 1 \times 4$\textsuperscript{*} & 64  & 70                  & 8        & \textless~1~s \\
 ~$2\times 2 \times 1$\textsuperscript{*} & 64  & 70                  & 7        & \textless~1~s \\
 ~$2\times 2 \times 2$\textsuperscript{*} & 128 & 12870               & 180      & \textless~1~s/8.0~s \\
$2\times 2 \times 3$                      & 192 & 2704156             & 15565    & \textless~1~s/7~days \\
$2\times 3 \times 3$                      & 144 & ~$9\cdot 10^9$      & 63075916 & 142.67~s/crash      \\
$3\times 3 \times 3$                      & 432 & ~$1.9\cdot 10^{15}$ & N/A      & $\approx$ 1y/--- \\
\hline
\multicolumn{5}{y{12.5cm}}{\footnotesize{\textsuperscript{*}The data is also presented in table~1 in ref. \cite{Grau2007} and fully agrees with \sups{} results.}} \\
\multicolumn{5}{y{12.5cm}}{\footnotesize{\textsuperscript{**}Supercell performance mesuared using Intel\textsuperscript{\textregistered} Xeon\textsuperscript{\texttrademark} CPU 2.20~GHz under KVM virtual machine with 8 cores available.}} \\
\end{tabular}
\label{tab:FeSbO4}
\end{table}

The \sups{} command whose output is used to generate a row (for example for supercell size $2\times2\times1$) in table~\ref{tab:FeSbO4} is of the form:
\begin{Verbatim}[breaklines]
  supercell -d -i FeSbO4.cif -s 2x2x1 -m 
\end{Verbatim}
where \texttt{-d} (\texttt{--dry-run}) option switches the program to dry-run mode (no output-file generation), \clic{-i} (\clic{--input}) must be followed by the input file name (required), \clic{-s} (\clic{--cell-size}) sets the cell size in format \texttt{AxBxC}, where \texttt{A}, \clic{B} and \clic{C} are positive integer numbers.

Table~\ref{tab:FeSbO4} can be generated automatically (except information about SOD run time) with the script \linebreak \path{df_chg.bash} in \path{supercell/data/examples/FeSbO4} folder. The output of \sups{} is parsed during the execution of the script to extract the relevant information.

As mentioned above this example does not generate output structures. To do so, the user should first create a directory where the structures will be stored and then execute the same type of \sups{} command without the \clic{-d}, and with the \clic{-o <path_to_new_directory>/<ouput_file_prefix>} command instead, as in the example below:
\begin{Verbatim}[breaklines]
  mkdir FeSbO4_cell221/
  supercell -i FeSbO4.cif -s 2x2x1 -m -o FeSbO4_cell221/FeSbO4_cell221
\end{Verbatim}

\subsection*{Coulomb energy calculations in $\gamma$-\ce{Fe2O3}.}

The case of the $\gamma$-\ce{Fe2O3} system, investigated in ref. \cite{Grau2010}, was also examined. The input structure with name \clic{Fe2O3-P4332.cif} can be found in folder \path{supercell/data/examples/gamma-Fe2O3/}. Detailed information about the configurations and their degeneracies was presented therein for a supercell $1\times1\times3$ of $\gamma$-\ce{Fe2O3}, all of which were perfectly reproduced by the \sups{} program.\footnote{Table~2 in~\cite{Grau2010} has a mistyping: L1L3L5L10 degeneracy should be 24 and space group for configuration L1L2L4L5 should be \textit{C2}.}. Among other things, the correlation between total and Coulomb energies was examined in their paper. It was shown that, at least for this particular system, a quite strong correlation is obtained, such that Coulomb energy can be used to approximate the total energy with a reasonable precision. Electrostatic energies can be calculated directly with \sups{}, provided charges are specified for all sites in the CIF input file (with tag \clic{_atom_type_oxidation_number}) and/or in the command line. The following command should be used to calculate the electrostatic energy of all explored unique configurations for supercell size $1\times1\times3$ (examined in ref. \cite{Grau2010})\footnote{Please create folder \path{cell113_out} before running the command. Option \clic{-g} will not work without the folder.}
\begin{Verbatim}[breaklines]
  mkdir cell113_out/
  supercell -i Fe2O3-P4332.cif -s 1x1x3 -m -q -g -v 2 -o cell113_out/cell113 
\end{Verbatim}
where the \clic{-q} activates electrostatic energy calculations. This option requires the cell to be charge-balanced, and the calculation of all electrostatic energies will take up to 1 min. Option \clic{-g} generates file named \path{cell113_out/cell113_coulomb_energy.txt}, which contains the electrostatic energy of each structure processed. The \clic{_chemical_name_common} parameter value in each output CIF file also contains the energy value.

We can go further and explore the cell $1\times2\times3$ of $\gamma$-\ce{Fe2O3}. A fast dry-run of \sups{} program:
\begin{Verbatim}[breaklines]
  supercell -d -i Fe2O3-P4332.cif -s 1x2x3 -m -v 2 
\end{Verbatim}
provides information on the total number of combinations \num{735471} and the number of unique ones as \num{30834}. The number of configurations is too high to process them all, but they can nevertheless be sampled. The random sampling was discussed above. Here we also extract the structures with lowest (\clic{-n l<number>}) and highest (\clic{-n h<number>}) electrostatic-energies. All possible samplings can be done simultaneously. 
\begin{Verbatim}[breaklines]
  mkdir cell123_out/
  supercell -i Fe2O3-P4332.cif -s 1x2x3 -v 2 -m -q -n l50 -n r100 -n h20 -o cell123_out/cell123
\end{Verbatim}
Options \clic{-n l50}, \clic{-n h20} and \clic{-n r100} forces program to output only the 50 structures with lowest Coulomb energy, the first 20 structures with highest Coulomb energy and 100 random structures, respectively. The \clic{-q} option is of course mandatory to perform such Coulomb-energy-based samplings.

It is important to keep in mind that the output text file \clic{cell123_coulomb_energy.txt} will list the Coulomb energies of all configurations, and not only of the sampled. If you are not interested in energies of all configurations, but only in the sampled one, you can find useful files \clic{cell123_coulomb_energy_r.txt}, \clic{cell123_coulomb_energy_l.txt}, and \clic{cell123_coulomb_energy_h.txt}, which list only the Coulomb energies of configurations sampled with each method. Most of the popular filesystems, have a significant performance degradation, when the total number of file in the folder is more than \num{10000}. To overcome this limitation, the archiving option (\clic{-a}), which will automatically compress the output files, can be used.
\begin{Verbatim}[breaklines]
  supercell -i Fe2O3-P4332.cif -s 1x2x3 -m -q -v 2 -o Fe2O3/cell123 -a Fe2O3_cell123.zip
\end{Verbatim}
This run of \sups{} packs all the output files (except \clic{cell123_coulomb_energy.txt}) to \path{Fe2O3_cell123.zip} archive. The files will be located in the folder \path{Fe2O3} within this archive. The name of the files will start from \path{cell123}. The possible file formats \path{.zip}, \path{.tar}, \path{.tgz}, \path{.tar.gz}, \path{.tar.bz2} and \path{.tar.xz} should be specified like an extension of archive file. The parameter is optional and requires \textit{libarchive} installed, during program compilation.


\subsection*{\Sups{} program verification on the $\alpha$-\ce{Si_xGe_{1-x}O2} system}

The ``disorder'' part of the CRYSTAL code has previously been applied to a $\alpha$-\ce{Si_xGe_{1-x}O2} solid solution based on the $\alpha$-quartz structure\cite{El-Kelany2014}. Repeating the same calculations with the \sups{} program again led to the same total number of configurations, number of distinct configurations, and symmetry of individual structures for all $x$ values. The corresponding table may be generated automatically with the script \clic{df_cfg.bash} located in directory \clic{supercell/data/examples/alpha-SiGeO2/}. The \sups{} commands used in this example are of the form:
\begin{Verbatim}[breaklines]
  supercell -i alpha-SiGeO2.cif -s 1x1x2 -p "Si1:p=2" -p "Ge1:p=4" -m -o cell112/Si2/SiGeO2_112-Si2
\end{Verbatim}
here the \clic{-p} option is used to set the number of \ce{Si} and \ce{Ge} atoms occupying the disordered mixed site Si1/Ge1. The multiplicity of this site is 3 (trigonal space group \ce{P{3}_{2}{21}}, no. 154), which gives for a supercell of size $1\times1\times2$ a total number of 6 positions and imposes that $0 \leq p(\text{Si1})\leq 6$ and $p(\text{Ge1})+p(\text{Si1})=6$. The structures are generated and stored in directory \clic{cell112/Si2/}, which is created by the script before the command is run. The number ``2'' in ``Si2'' stands here for the population $p(\text{Si1})$, and the script actually creates seven such directories named: \path{cell112/Si<p(Si1)>/} where $p(\text{Si1})=0...6$ which contain the generated structures.

\subsection*{\Sups{} program verification on the \ce{Cu2ZnSnS_{x}Se_{4-x}} system.}

Another verification was done by comparison with data published on \ce{Cu2ZnSnS_{x}Se_{4-x}}\cite{Dun2014}, in which the authors performed the symmetry search manually, rather than with any of the software discussed above. The data can therefore be treated as one more independent evidence of the correctness of our algorithm, which again provides results in complete agreement with those reported in ref. \cite{Dun2014}. This example is again distributed with the source code of the \sups{} program, along with a script (\clic{df_cfg.bash} in directory \clic{supercell/data/examples/Cu2ZnSnSxSe4-x/}) that will automatically generate the corresponding tables for direct comparison with the cited article. The \sups{} commands used in this example are of the form:
\begin{Verbatim}[breaklines]
  supercell -i stannite.cif -s 1x1x1 -p "S:p=3" -p "Se:p=5" -m -o <output_directory>/stannite
\end{Verbatim}
in which, as in the previous example, the \texttt{<output\_directory>} is created before the command is run and the populations of S and Se atoms on crystallographic sites ``S'' and ``Se'' are specified with the \clic{-p} option. It is important to keep in mind that ``S'' and ``Se'' in ``S:p=3'' and ``Se:p=5'' arguments refer to the \textit{crystallographic labels} as they are defined in the CIF file rather than to atom symbols (more typical labels would be of the form ``S1'' and ``Se1''). The multiplicity of these overlapping sites in the cell being 8 and the supercell size being $1\times1\times1$, the population values ``p'' should obey $0 \leq p(\text{S})\leq 8$ and $p(\text{Se}) + p(\text{S})=8$.

\subsection*{\Sups{} program verification on piezoelectric ceramics \ce{PbZr_{x}Ti_{1-x}O3} (PZT).}

Disorder in piezoelectric ceramics can be also processed with \sups{} program. The well-known \ce{PbZr_{x}Ti_{1-x}O3} (PZT) ceramics is particularly interesting because of the displacement disorder on the Pb position, which is induced by \ce{Zr-Ti} substitution and crucially affects its electric and mechanical properties. The example described here is based on Ref. \cite{Grinberg2004}, where authors used DFT calculations to investigate the correlation between substitution ordering in supercell models and the physical properties of the system. They used in this particular case a strongly anisotropic $4\times2\times1$ supercell of composition \ce{PbZr_{0.5}Ti_{0.5}O3}. The approximations leads to 10 symmetry unique configurations, which were all presented in the paper. They can be easily generated with the \sups{} program embedded in a simple script \clic{df_cfg.bash} located in \clic{supercell/data/examples/PZT/} folder. We note that the order of configurations differs in the script and in the paper. The command line used in this script is:
\begin{Verbatim}[breaklines]
  supercell  -s 4x2x1 -i PZT-PbZr05Ti05O3.cif -m -o <output_directory>/PZT421
\end{Verbatim}
Using the \sups{} program makes it possible to proceed with larger supercell sizes $4\times2\times2$ and $4\times3\times2$, yielding 490 and 29606 unique configurations, respectively. The second case may be difficult to process, but the first one is absolutely feasible. Such supercell size allows to research structure distortion in z-dimension also.

\subsection*{Disorder in \ce{Pb_{0.5}Sn_{0.5}Te}: calculation of atom-pair correlation functions}
The purpose of this section is to describe the procedure and results of the exploration of the \ce{Pb_{0.5}Sn_{0.5}Te} system discussed in the main text, in which we use the \sups{} program combined with a structure-analysis tool (the GULP program) to calculate atom-pair correlation functions. These functions are then used to evaluate to what extent the generated structures are representative of random Pb/Se disorder through their adequacy with Special-Quasirandom-Structure (SQS) character\cite{Zunger1990}.

This example is performed automatically with the script \clic{df_cfg.bash} located in directory \path{supercell/data/examples/PbSnTe-SQS/} for two supercell sizes: $1\times1\times2$ and $1\times2\times2$. The script uses \sups{} commands such as:
\begin{Verbatim}[breaklines]
  supercell -i PbSnTe2.cif -s 1x1x2 -m -o cell_1x1x2/PbSnTe_1x1x2
\end{Verbatim}
The GULP program is then used to perform the following structure analysis on each one of the (symmetry-unique since the \clic{-m} option is used) output configurations. The correlation functions are calculated like a total energy of the system with set of ``fake'' potentials. The potential energy it set to +1 for \ce{A-A} and \ce{B-B} interactions and -1 for \ce{A-B} at distance $R_m$, with $m$ being the coordination sphere number (see main text), and zero for all other distances. The result is saved in text files \path{SQS-1x1x2} and \path{SQS-1x1x2} in the form of tables which list, for each configuration:
\begin{itemize}
 \item the structure name (ex. \path{cell_1x1x2/PbSnTe_c1x1x2_i<index>_w<weight>.cif})
 \item the atom-pair correlation coefficients (see main text) calculated for the first 4 shells of each cationic site (ignoring \ce{Te} atoms), which correspond to \ce{A-B} distances (where \ce{A}, \ce{B} = \ce{Pb} or \ce{Sn}) of 4.51, 6.39, 7.83, and 9.04~\AA, as listed in the file header.
\end{itemize}
The adequacy of the structure to the SQS criteria is indicated by how close these four correlation functions, and in particular the first three, are to zero (because the substituted \ce{Pb} and \ce{Sn} atoms are present in equal concentrations, see main text). A good way to visualize these results is for example to sort the structures by ascending order of the absolute value of those coefficients in columns 1, 2, 3, and 4 (in this order).

\subsection*{Permutations in ice \ce{I_h} $1\times1\times2$ supercell.}

\begin{figure}[t]
  \caption{ Crystal structure of ice \ce{I_h}. Cell 1x1x2. Hydrogen sites connected to the same oxygen atoms are displayed with the same color, each color being associated in this initial structure to a different H-atom label (from H1 to H8). }   
  
  \centering
  \includegraphics[scale=0.20]{figures/ice-Ih-121-adv.png}
  
  \label{fig:iceIh-adv}
\end{figure}

The method described in the main paper to generate correlated ice \ce{I_h} structures will not work with supercells larger than the original one. An advanced method to do so is therefore presented here. The input CIF file should be changed manually to use this method. We strongly encourage the user to also check the \path{df_cfg.bash} script in folder \path{supercell/data/examples/ice-Ih-adv/}, which implements this procedure. 

As mentioned in the main text, the ordering of H atoms in this system is governed by two restrictions: the coordination number of all O atoms should be two and H atoms should not be in close contact with each other. Further below, we describe how to impose the first restriction in the initial structure, by grouping atoms in a non-standard way. But first of all, we generate a $1\times1\times2$ supercell, keeping the disorder:
\begin{Verbatim}[breaklines]
  supercell -i ice-Ih.cif -s 1x1x2 -p "*:fixed" -o ice-Ih-121-adv.cif
\end{Verbatim}
where the partial occupancies on both sites are kept fixed. (This step could of course alternatively be done with any program for the visualization of crystallographic structures.) The output structure is shown on fig.~\ref{fig:iceIh-adv}. Each oxygen atom is still surrounded by 4 hydrogen positions, strictly two of which should be occupied by H atoms in the end. In the figure, the hydrogen sites are associated with different O atoms marked with different colors. The H atom labels are then changed manually in the same way as the color code, ensuring that (i) all hydrogen positions attached to the same O atom have the same label and that (ii) hydrogen atoms positions associated with different O atoms have different labels (ex. H1, H2, H3, etc).

Importantly, the \sups{} program will associate sites with identical crystallographic labels within a common group (as defined in the main text), so that a run with this customized file (\path{supercell/data/examples/ice-Ih-adv/ice-Ih-121-adv.cif}) as an input gives 8 groups with $C^2_4=6$ combinations each, which yields a total of $6^8=$\num{1679616} configurations. The \sups{} command used for this step is the following:
\begin{Verbatim}[breaklines]
  supercell -i ice-Ih-121-adv.cif -m -q -p "O:c=-2" -p "H*:c=+1" -p "r(H[5-8]):fixed" -o <output_directory>/ice-Ih-l1
\end{Verbatim}
where the \clic{-p --property} option is first used to set the charges (\clic{<label>:c=<charge_value>}) of O and H crystallographic sites for the Coulomb energy calculation (\clic{-q} option). The ``\clic{H*}'' notation here sets the specified charge to all sites starting with ``H''. The \clic{-p} option is then used again to fix the partial occupancies of H sites labelled ``H5'' to ``H8'' with the notation ``\clic{r(H[5-8]):fixed}'', which excludes these sites from the permutation. Here the ``r'' means that the expression inside the parentheses should be interpreted like a Perl regular expression (RegEx). A description of the corresponding syntax can be found at \url{http://en.wikipedia.org/wiki/Regular_expression}. More information on these wild cards and other advanced text search functionalities to set the properties of several crystallographic sites are provided in the manual (\clic{man supercell}). By comparison, applying the \sups{} program to the same supercell size with the original grouping gives a total of \num{189290920} configurations, which is approximately one hundred times more than with the customized CIF file.

This new group assignment not only solves the problem of the O coordination, but also splits the 32 H positions into 8 groups of sites. The number of configurations (1.6~million) is still very high to generate them all simultaneously, but the process can be done step-by-step. We note that such a number of configurations is not a problem for the \sups{} algorithm, which can deal with up to ${10^16}$ configurations, but it is a problem for storage and data analysis (by the GULP program). 4 out of 8 groups can be fixed in a first step to generate 656 (after symmetry merging) output structures. These files can then be analyzed to exclude those with \ce{H-H} close contact. Only valid structures are kept for the next step, where they are used as new inputs for the \sups{} program, with the command:
\begin{Verbatim}[breaklines]
  supercell -i <new_input_structure> -m -q -p "O:c=-2" -p "H*:c=+1"  -o <output_directory>/<prefix>
\end{Verbatim}
The process gives only 9 structures which obey both conditions, and which may be found in the \linebreak \path{ice-Ih-cfgs-final/} directory.

The directories and files created for this example by the script: \clic{df_cfg.bash} in folder \path{supercell/data/examples/ice-Ih-adv/} are organized as follows:
\begin{itemize}
 \item \clic{ice-Ih-121-adv.cif}: the starting structure, based on a $1\times2\times1$ supercell of the original ice \ce{I_h} structure, with labels modified as described above.
 \item \clic{ice-Ih.gin_template}: contains the input-file template for the structure analysis performed with Gulp, which lists inter-atomic distances and is parsed to locate H-H close contacts and check the O-atom coordination.
 \item \clic{ice-Ih-cfgs-l1/}: contains partially-disordered configurations files with names \path{ice-Ih-l1_i<index>_w<weight>.cif}, in which permutations were treated on groups of H sites H1 to H4, but where partial occupancies were kept on groups H5 to H8. Each structure is associated with a folder (\path{ice-Ih-cfgs-l1/ice-Ih-l1_i<index>_w<weight>/gulp/}) which contains the output of the structure analysis performed with the GULP program.
 \item \clic{ice-Ih-cfgs-l2/}: Contains copies of the structures satisfying both restrictions on the local structure (no \ce{H-H} close contact and 2-coordinated O) among those obtained during the first step. Each of these structures are then associated with directories of the type:
 \item \clic{ice-Ih-cfgs-l2/ice-Ih-l1_i<index>_w<weight>/} which contains the structures generated by the second run of the algorithm, where the remaining disordered sites (H5 to H8) are treated. These structures are named \path{ice-Ih-l1_i<step1_index>_w<step1_weight>-l2_i<step2_index>w_<step2_weight>.cif} and are again associated with all folder (same name without the extension) containing the result of the structure analysis.  
 \item \clic{ice-Ih-cfgs-final/}: contains the final selection of structures where disorder in all H sites is treated, and which satisfy both structure-restriction conditions.
\end{itemize}

\subsection*{Application of \sups{} program to Rb-PST-1 zeolite.}

The ``scientific'' part of the research is described by S. Cadars \textit{et.al.}\cite{Rb-PST-1}. Here only ``technical'' part will be described. The zeolite has two Ga/Si sites, both of the cites are disordered. The compound has also two Rubidium sites, one disordered and one fully occupied. All Oxygen sites are fully occupied.  

Let's run \sups{} program with several extra options (see Table~\ref{tab:Rb-PST-1-run}) and check the output:
\begin{Verbatim}[breaklines]
  supercell -i RB-PST-1-DEHY_1_new.cif -d -v 2 <extra_options>
\end{Verbatim}


\begin{table}[ht!]
\caption{\Sups{} program run for Rb-PST-1 structure.}
\renewcommand{\arraystretch}{1.7}
\newcolumntype{x}[1]{>{\centering\arraybackslash}m{#1}}
\newcolumntype{y}[1]{>{\arraybackslash}m{#1}}
\centering
\begin{tabular}{|x{3.4cm}|x{2.6cm}|x{2.2cm}|x{1.2cm}|x{1.2cm}|x{3.5cm}|}
\hline
Program extra options & Approx cell size,~\AA & Total number of configurations & Si/Ga ratio & Charge of the system &  Comment \\
\hline 
 -                                         & $12.6\times12.6\times6.6$   & $\approx5.5\cdot10^5$     &  1.22 & 0   &  Plain \sups{} program run. \\
\verb+-p "Rb2:p=0"+ \verb+-c no+           & $12.6\times12.6\times6.6$   & \num{68640}               &  1.22 & -1  &  Removing Rb2 disordered site without charge balancing. \\
\verb+-p "Rb2:p=0"+ \verb+-c yes+          & $12.6\times12.6\times6.6$   & \num{48048}               &  1.5  & 0   &  The same, but with charge balancing  \\
\verb+-s 1x1x2+                            & $12.6\times12.6\times13.2$  & $\approx4.0\cdot10^{12}$  &  1.22 & 0   &  Twice cell along \textit{z}-direction. \\
\verb+-s 1x1x2+ \verb+-p "Rb2:p=0"+        & $12.6\times12.6\times13.2$  & $\approx1.6\cdot10^{10}$  &  1.5  & 0   &  Same, but without Rb2 site. \\
\verb+-s 1x1x2+ \verb+-m+ \verb+-p "Rb2:p=0" -p+        
\verb+"r(Si1|Ga1):fixed"+                  & $12.6\times12.6\times13.2$  & 70(8)                     &  1.5  & 0   &  Like previous, but excluding (Si/Ga)1 site from permutation. \\
\hline
\end{tabular}
\label{tab:Rb-PST-1-run}
\end{table} 

As you can see from the table, the cell $1\times1\times1$ has only 6~\AA{} in \textit{z}-direction, therefore periodic effects can be strong. Increasing the cell twice along the direction will decrease the effects, but the number of permutation ($\approx4.0\cdot10^{12}$) is too high to process with ``brute-force'' approach. implemented in \sups{} program. the most easy way to decrease the number is to completely remove Rb2 site, but this will change the charge neutrality of the system. Therefore, Si/Ga ratio should be also adjusted. After the manipulation, the number of permutations is still higher, than the program can process, but it can be processed in two steps. At first step, (Si/Ga)1 site should be fixed. The number of SIC configuration, obtained by permutations of (Si/Ga)2 site is 8 (70 total). At second step, these 8 structures are used like an input for next supercell program run:
\begin{Verbatim}[breaklines]
  supercell -i <first_step_cif_file> -v 2 -q -p "Si*:c=4" -p "Ga*:c=3" -p "Rb*:c=1" -p "O*:c=-2" -o <output_file_prefix> -n r5000 -n l1000 -n h1000
\end{Verbatim}

The run generates text file with electrostatic energy of all possible structures, \num{5000} random structures, and \num{1000} structures with lowest and highest energy each. The following analysis of surrounding and connectivity were done with ``in-house'' software. Manual charge settings is needed for Coulomb

The \clic{RB-PST-1-DEHY_1_new.cif} file and script (\clic{df_cfg.bash}) for structure generation you can find in \path{supercell/data/example/Rb-PST-1} folder. The structure generation will take around one hour on 8 cores workstation and up to ten hours on netbook. It will also require a several gigabytes of storage space to write Coulomb energy for all possible structures.

\section*{\Sups{} program good practices.}
\subsection*{Basic}
The pieces of advice in the section are recommended for all \sups{} users. It is always safe to follow them.
\subsubsection{Save program output.}
In case of production run, it is always good to save program output. You can do this just by coping the screen manually or redirecting output to a file. For example
\begin{Verbatim}[breaklines]
supercell -d -i Ca2Al2SiO7.cif -m > <supercell log file name> 
\end{Verbatim}
or
\begin{Verbatim}[breaklines]
supercell -d -i Ca2Al2SiO7.cif -m | tee <supercell log file name> 
\end{Verbatim}
Both of the examples store the output to file, but the second one also duplicates the output to your screen.

\subsubsection{Check input CIF files.}
CIF files, in general, can have a variety of different problems. If you get \sups{} program crash for $99\%$ it is because of wrong or corrupted input file. For example, \sups{} users tried to process html files, instead of CIF, files with ``glued'' coordination values or to use partially downloaded file with some data missing. Even if you are 100\% sure that the file is OK, try to open it with text editor, another crystallographic program or, if possible, use enCIFer to prepare a bugfree input.

\subsubsection{Visualize input and output structures.}
Visualization is the most powerful approach to get the information about structure. Please use visualization software to check input and output structure. It can give you a lot of information about your compound, type of disorder etc. \Sups{} and VESTA programs are good friends, but try to avoid Material Studio, as its output can be not compatible with \sups{}.
Basic functionality: \ce{Ca2Al2SiO7}.
\subsubsection{Convert an input structure to \textit{P1}. }
Spacegroups are quite complex mathematical objects, so it is difficult to find a simple representation of it. Currently space group can be represented by a number, a Hermann–Mauguin notation, a Hall notation, a symmetry operations list etc. Symmetry operations notation is the most unambiguous one, but it is very often wrong in real CIF files. I'm trying to do my best in the program algorithms and correct the input, but it is not always possible.

The good news is that \sups{} program is not using the spacegroup information directly. It has its own algorithms, which can find symmetry operations of the input structure purely mathematicaly. Therefore it uses symmetry information from input file only to convert the structure to \textit{P1} structure. After that internal algorithms will find proper symmetries. So, if you suspect spacegroup problem, just convert the structure to \textit{P1} with external tool. Visualize the result structure and check that it correctly represents the initial one. And use the structure as \sups{} input. Don't worry, you will not loose any symmetry information. For example, you can find a video tutorial for structure conversion in VESTA program \href{https://www.youtube.com/watch?v=LCdb6LrD24E}{here}.

\subsubsection{ Check supporting materials }
I did my best to prepare all supporting materials for \sups{} program: paper, tutorial, manual and example. For example, we (authors) tried to prepare the paper as user-friendly as possible. We skip a long boring algorithm descriptions, but concentrate on impact of the algorithm implementation to user and underline some important conceptions like supercell itself, groups, charge balancing etc. This tutorial concentrates on practical aspects of using supercell with both very simple and very complex examples from different areas of material science. Manual describes all the parameters you can use with \sups{}. Check it, if you have doubts what the parameter exactly means.

\subsubsection{ Work interactively }
Don't concentrate only on the tasks you need to do. Try different parameters: supercell size and shape, occupation, charge balancing, consider to use primitive and conventional cells, if applicable etc. Check the results and try again. It will give you more confidence about the result and probably hints about other approaches.

\subsubsection{ Performance }
The best performance you can achieve with modern hi-end workstation with Linux OS.

\subsection*{Advanced}
The piece of advice in the section requires deep understanding of specific technologies.

\subsubsection{ Edit CIF file manually }
\textit{Deep knowledge about spacegroups and CIF file structure are required.} By editing the file you can:
\begin{itemize}
 \item exclude all unnecessary information, thus make the file better readable.
 \item add charges information (can be added by command line as well).
 \item add new elements to existing site.
 \item delete some sites. Don't worry about possible symmetry changes. \Sups{} sorts it out.
 \item remove displacement disorder, if needed.
 \item resolve ambiguity in spacegroup notation.
\end{itemize}

\subsubsection{ Use special CLI programs to prepare input for DFT calculation }
\textit{Command line interface skills required } I can recommend to use \mbox{\textit{cif2cell}}\cite{cif2cell} or \mbox{\textit{OpenBabel}}\cite{OpenBabel} programs to convert the output CIF files to DFT programs input. Automatic conversion approach is very useful when you process many output files in the same way. 

\subsubsection{ Performance }
\textit{Deep knowledge about modern CPU  are required.} Use \mbox{\textit{taskset}} command to attach CPU cores to \sups{} program. Try to find an optimal numbers of cores for \sups{} run. My experience shows that Intel\textregistered Hyper-Threading Technology gives anything neither for DFT calculation nor for \sups{} program. Therefore try to switch it off, or assign \sups{} threads to real cores.

\subsection*{Expert}
To implement suggestions below, you have to have a solid knowledge of specific technologies.

\subsubsection{Combine \sups{} with other approaches }
\Sups{} program was developed for DFT calculations, but currently it can be used within many different approaches like machine learning\cite{Dieb2018, Midgley2021}, genetic\cite{Han2018} algorithms. You can also perform advance structure selection (beyond random and electric) with such frameworks like \mbox{\textit{ASE}} or \mbox{\textit{pymatgen}}. \Sups{} is Free and open-source software (FOSS), therefore you can change the code to fit your project needs.

\subsubsection{ Performance }
\textit{Excellent skills in compiling programs with different compilers.} Try to compile \sups{} for specific platform with different compilers and compiler parameters. The compiler should support C++14 standard. Be careful with \mbox{\textit{fast-math}} option, as it can produce unexpected results.

\begin{figure}[ht!]
  \caption{ An approximate algorithm for \sups{} problems resolving. }   
  
\begin{center}
 
\begin{tikzpicture}[font=\small,thick, inner sep=6pt]
 
% Start block
\node[draw,
    rounded rectangle,
    minimum width=2.5cm,
    minimum height=1cm] (bStart) {\Sups{} is not working};
\node[draw,
    below=of bStart,
    minimum width=3.5cm,
    minimum height=1cm
] (bRunCa) { Run program with \ce{Ca2Al2SiO7} example\footnotesize{\textsuperscript{a)}}};
\node[draw,
    diamond,
    below=of bRunCa,
    minimum width=2.5cm,
    text width=2.0cm, align=center,
    inner sep=0] (bifCa) { Working as expected? };
\node[draw,
    diamond,
    left=of bifCa,
    minimum width=2.5cm,
    minimum height=1cm,
    text width=2.3cm, align=center,
    inner sep=2pt] (bIsSSNorm) { Is the program standard?\footnotesize{\textsuperscript{b)}}};
\node[draw,
    below=of bIsSSNorm,
    minimum width=2.5cm,
    text width=2.3cm, align=center,
    minimum height=1.2cm] (bCheckSSNorm) { Check standard configuration. };
\node[coordinate, left = 0.5 of bIsSSNorm] (c1) {};    
\node[coordinate, below = 3.0 of bifCa] (c2) {};
\node[draw,
    right=of bifCa,
    minimum width=4.0cm,
    minimum height=1.0cm] (bGoodPract) { Read good practices \footnotesize{\textsuperscript{c)}}};
\node[draw,
    below=0.5 of bGoodPract,
    minimum width=4.0cm] (bCheckCIF) { Check CIF file };
\node[draw,
    below=0.5 of bCheckCIF,
    minimum width=4.0cm] (bCheckVESTA) { Check structure };
\node[draw,
    below=0.5 of bCheckVESTA,
    minimum width=4.0cm] (bCheckP1) { Convert structure to P1 };
\node[draw,
    below = 0.5 of c2,
    minimum width=2.5cm,
    minimum height=1cm] (bCheckIssues) { Check \sups{} issues\footnotesize{\textsuperscript{d)}}};
\node[draw,
    diamond,
    below = 0.5 of bCheckIssues,
    text width=1.3cm, align=center,
    minimum width=2.5cm,
    minimum height=1cm] (bSolved) { Problem solved? };
\node[draw,
    circle,
    left = of bSolved] (bLeftA) { A };
\node[draw,
    circle,
    right = of bSolved] (bRightA) { A };
\node[draw,
    below = 0.7 of bSolved,
    minimum width=4.0cm] (bCheckV12) { Compare with version 1.2 };    
\node[draw,
    circle,
    left = of bCheckV12] (bLeftB) { B };
\node[draw,
    circle,
    right = of bCheckV12] (bRightC) { C };    

% Arrows
\draw[-latex] (bStart) edge (bRunCa)
    (bRunCa) edge (bifCa);
\draw[-latex] (bifCa) -- (bIsSSNorm)
    node[pos=0.35,fill=white,inner sep=2pt]{No};
\draw[-latex] (bifCa) -- (bGoodPract)
    node[pos=0.35,fill=white,inner sep=2pt]{Yes};
\draw[-latex] (bIsSSNorm) -- (bCheckSSNorm) 
    node[pos=0.4,fill=white,inner sep=2pt]{No};
\draw[-latex] (bIsSSNorm.west) |- (c1) |- (c2)
    node[pos=0.25,fill=white,inner sep=2pt]{Yes};
\draw[-latex] (bCheckSSNorm) |- (c2);    
\draw[-latex] (bGoodPract) -- (bCheckCIF);
\draw[-latex] (bCheckCIF) -- (bCheckVESTA);
\draw[-latex] (bCheckVESTA) -- (bCheckP1);
\draw[-latex] (bCheckP1) |- (c2);
\draw[-latex] (c2) -- (bCheckIssues);
\draw[-latex] (bCheckIssues) -- (bSolved);
\draw[-latex] (bSolved) -- (bLeftA) node[pos=0.35,fill=white,inner sep=2pt]{Yes};
\draw[-latex] (bSolved) -- (bRightA) node[pos=0.35,fill=white,inner sep=2pt]{Yes};
\draw[-latex] (bSolved) -- (bCheckV12) node[pos=0.35,fill=white,inner sep=2pt]{No};
\draw[-latex] (bCheckV12) -- (bLeftB);
\draw[-latex] (bCheckV12) -- (bRightC);
   
\end{tikzpicture}
\end{center}

\label{fig:algo}

\begin{tabular}{l}
\footnotesize{\textsuperscript{a)} Subsection ``Basic functionality: \ce{Ca2Al2SiO7}.'' in the tutorial. } \\
\footnotesize{\textsuperscript{b)} Standard configuration is \sups{}~v2.0 Linux binary from supercell site. } \\
\footnotesize{\textsuperscript{c)} Section ``\Sups{} program good practices'' above. } \\
\footnotesize{\textsuperscript{d)} Check open and closed issues on this page \href{https://github.com/orex/supercell/issues?q=is\%3Aissue+is\%3Aclosed+is\%3Aopen}{https://github.com/orex/supercell/issues}.} \\
\end{tabular}
\begin{description}
  \item[A] Awesome! You solved your problem by yourself. Probably you spent a lot of time on it and found some useful information which can help other users to prevent the problem? Don't hesitate to share this experience with others by opening an issue on github with detailed description of the problem and your solution. 
  \item[B] You have a general problem of \sups{}. Open an issue on github page (\href{https://github.com/orex/supercell/issues/new/choose}{link}) and describe as much as possible your environment, including system information, hardware etc. and, of course, \sups{} program output.
  \item[C] You have a problem only with your structure. Open an issue on github page (\href{https://github.com/orex/supercell/issues/new/choose}{link}) and describe your problem as much as possible. Please include the input file (rename to ``.txt'' to attach), the structure figure, supercell program output and results of ``good practices'' which you applied.
\end{description}
\end{figure}

\section*{What to do if supercell program is not working? }
This is a very common question from \sups{} program users. And the answer can be very different. Summarizing the problems of users, I create an approximate algorithm of solving such problems, which I sketched in fig.~\ref{fig:algo}. It consists of two main branches, when the program itself is not working (fig.~\ref{fig:algo}, left branch) and your input structure cannot be processed (fig.~\ref{fig:algo}, right branch). During the early days of \sups{} program, the left branch was much more problematic than now. A lot of effort was applied to make \sups{} program installation as easy as possible. Today, I think, that you can hardly have general problems with \sups{} binaries from site, if you follow the requirements.

Version 2 of \sups{} code is a breakthrough release in terms of CIF file support. \mbox{\textit{OpenBabel}} library has been replaced in favor of \mbox{\textit{gemmi}} library. Now \sups{} program have full control over parsing and processing, using \mbox{\textit{gemmi}} specific ``low level'' functions. Output is performed fully internally.

Although such changes solved many problems (with monoclinic lattices, for example) there are many problems which can still appear. Please, try to follow the good practices described above. Even if described practices will not solve your problem, they provide a lot of useful information for bug report.

\FloatBarrier


\section*{\Sups{} program integration to research process.}
Our program is ``link in chain'' and the efficiency of the research process, obviously, depends on another links and connection between them. Below, there is a list of the programs/resources (in addition to discussed in the main paper), which can be possibly used with supercell program in disorder compound research.
\begin{description}
  \item[ASE] (\url{https://wiki.fysik.dtu.dk/ase/}). Atomic Simulation Environment is another set of python tool for setting up, manipulating, running, visualizing and analyzing atomistic simulations. Supports many calculation software, both classical and \textit{ab-initio}, including CASTEP and VASP. 
  \item[cif2cell] (\url{http://sourceforge.net/projects/cif2cell/}). Cif2cell is a tool to generate an input structure in different formats, like CASTEP, CP2K, CRYSTAL09, Quantum Espresso, VASP and many more. 
  \item[COD] (\url{http://www.crystallography.net}). Open-access  structural database with more than \num{473520} records (May 2021). 
  \item[GULP] (\url{http://gulp.curtin.edu.au/}). GULP is a force-field program for performing a variety of tasks on a range of system types. It can be useful for optimizations, energy calculation and analysis of the structure.
  \item[EnCIFer] (\url{http://www.ccdc.cam.ac.uk/Community/freeservices/encifer/}). A GUI tool for validating of \sups{} input structures. Useful for draft structures.
  \item[OpenBabel] (\url{http://openbabel.org/}). Open Babel is a chemical toolbox designed to speak many languages of chemical data. It's an open, collaborative project allowing anyone to search, convert, analyze, or store data from molecular modeling, chemistry, solid-state materials, biochemistry, or related areas. Over 110 formats are supported.
  \item[VESTA] (\url{http://jp-minerals.org/vesta/}). A powerful tool for visualization and editing of crystallographic structures. It supports many input/output formats (including cif) and can visualize partially occupied sites.
\end{description}

 
\bibliographystyle{unsrt} % Style BST file
\bibliography{supercell_tutorial}  % Bibliography file (usually '*.bib' )


\end{document}
