Glossary

binary substitution

The simplest substitution mode: a single new species replaces a fraction of atoms on one target site type. For example, Ni/Mg in rocksalt MgO. Binary substitutions are a special case of multi-nary substitution with one new species.

calibration energies

Energies of selected configurations at the target intermediate composition nXX, used to fit the ε scale factors of a CPME Hamiltonian. They are stored in nXX/ENERGIES (two-column format m  E_nm: configuration index and energy in eV) and are read at the row indices listed in the calib_config_list line of cpme.model. The number of indices actually consumed is set by the n_calib field (0–9). Calibration energies are distinct from reference energies: reference energies define the Hamiltonian’s V terms; calibration energies tune the ε corrections.

canonical ensemble

A statistical-mechanical treatment of a system at fixed composition. Each inequivalent configuration is weighted by its Boltzmann factor \(g_i \exp(-E_i / k_\mathrm{B} T)\), where \(g_i\) is the degeneracy and \(E_i\) is the energy. The statsod program carries out canonical averaging and writes probabilities.dat and thermodynamics.dat. See also grand-canonical ensemble.

chemical potential

The thermodynamic variable that controls composition in a grand-canonical ensemble calculation. gcstatsod either accepts a fixed chemical potential (mu in INGC) or solves for the value that reproduces a target composition x at each temperature.

combsod

The enumeration executable. Given a parent structure (INSOD) and symmetry operators (SGO), it identifies all inequivalent configurations, computes their degeneracy, and writes ENSEMBLE and EQMATRIX. Normally invoked via sod_comb.sh.

configuration

An ordered arrangement of atoms in the supercell consistent with the specified substitution pattern. Each distinct arrangement is a configuration; SOD identifies the subset of inequivalent configurations from the full combinatorial set and assigns a degeneracy to each.

correlation functions

cluster correlation functions

pair correlations

The multi-site quantities that characterise the chemical ordering of a configuration: for each symmetry-distinct cluster (pair, triplet, …), the average of the site-occupation product over all instances of that cluster in the supercell. They are the criterion by which SQS and GQS configurations are selected — sqssod scores configurations from species-resolved pair probabilities (the order-2 correlations, target- and species-aware), and gqssod Boltzmann-averages cluster correlations up to MaxOrder. Warren-Cowley parameters are a normalised rewriting of the pair correlations, reported as a diagnostic rather than used for ranking.

CPME

Constrained Periodic Motif Expansion

An effective Hamiltonian for SOD that expresses the energy of a configuration as a sum of interaction terms up to 4-body, fitted from reference energies at low and/or high substitution levels. Three variants are available:

• CPME0 — low-side expansion only; energy evaluated as \(E_0^\mathrm{low} + \sum_i \varepsilon_i V_i^\mathrm{low}\).

• CPME1 — high-side (hole) expansion only; energy evaluated symmetrically in terms of the unoccupied sites.

• CPMEh — weighted hybrid of CPME0 and CPME1, \(w_\mathrm{low}(x) E_\mathrm{low} + w_\mathrm{high}(x) E_\mathrm{high}\), where \(x\) is the substitution fraction and the weights follow a piecewise power-law scheme controlled by alpha (sharpness, default 2.0) and eta (log-scale asymmetry, default 0.0). Edge regions within CPMEorder/N of either boundary use the corresponding end-member CPME with full weight.

The expansion order and ε scale factors are controlled via cpme.model. CPME energies for all enumerated configurations at the target level are written to nXX/CPMEx/ENERGIES. For large target levels where full enumeration is intractable, the CPME Hamiltonian drives Monte Carlo sampling (see mcsod).

cpme.model

Input/control file for the CPME Hamiltonian at a given composition level. The editable control file is placed at SODPROJECT/cpme.model and applies to the target level specified by INSOD; SOD copies it to nXX/cpme.model as a run record. The file has 7 data lines:

• CPME choice — which Hamiltonian variant to use: 0 (CPME0, low-side only), 1 (CPME1, high-side only), or 2 (CPMEh, weighted hybrid).

• CPMEorder — cap on the expansion order (must be 2, 3, or 4); a lower effective order is used with a warning if training data is insufficient.

• n_calib — how many calibration energies to use when fitting the ε corrections: 0 (no calibration, use manual ε values given in this file) or 1–9 (fit ε₀..ε_{n−1} from the first n_calib indices of calib_config_list).

• calib_config_list — space-separated configuration indices (up to 9) selected from nXX/ENERGIES for calibration. Auto-filled by cpmesod via recursive bisection of the predicted energy range when writing cpme.model.tmp.

• epsilon_low — ε₀..ε_{CPMEorder} for the low-side expansion (CPMEorder + 1 values; defaults 0, 1, 1, …; ε₀ is an additive energy offset in eV, ε₁..ε_K are multiplicative scale factors).

• epsilon_high — ε₀..ε_{CPMEorder} for the high-side expansion (same format as epsilon_low).

• alpha eta — CPMEh hybrid weighting parameters (alpha > 1 sharpness of the low/high blend, default 2.0; eta log-scale asymmetry, default 0.0; > 0 favours low-end, < 0 favours high-end). Always present but only used for CPMEh.

Optionally followed by # CPME energy terms and the fitted V₀ and V_k coefficients (low and high side), which are written by cpmesod after fitting and are read back on subsequent runs to skip refitting.

When SODPROJECT/cpme.model is absent, cpmesod defaults to CPMEh (or CPME0 if no high-side reference data is available) with ε = 1, alpha = 2.0, eta = 0.0, and writes SODPROJECT/cpme.model.tmp plus a copy at nXX/cpme.model.tmp as a starting template.

cpmesod

The CPME fitting and evaluation executable. Reads INSOD, the reference energy files (n00/ENERGIES, n01/ENERGIES, …), and optionally cpme.model (with any sparse calibration energies in nXX/ENERGIES referenced by calib_config_list). Fits the CPME V terms from reference energies, applies any calibration energies via the ε corrections, evaluates the resulting Hamiltonian for all enumerated configurations at the target level, and writes predictions under nXX/CPME0/, nXX/CPME1/, and/or nXX/CPMEh/. When no cpme.model is present it also writes SODPROJECT/cpme.model.tmp as a suggested control file, with a bisection-selected calib_config_list spanning the predicted energy range. Normally invoked via sod_cpme.sh.

degeneracy

The number of symmetry-equivalent supercell arrangements that map onto a given inequivalent configuration under the crystal symmetry operators. Degeneracies act as statistical weights in thermodynamic averaging: a configuration with degeneracy \(g\) contributes \(g\) times as much to the partition function as a non-degenerate one. Degeneracies are listed in ENSEMBLE.

ENSEMBLE

The main configuration-list file. For enumeration by combsod, it contains one line per inequivalent configuration listing its index, degeneracy, and substituted atom positions. For Monte Carlo output from mcsod, rows and Omega have sampler-dependent meanings documented in OUTMC and the CPME/MC guide. ENSEMBLE is required by statsod, gcstatsod, and sqssod. Known as OUTSOD in versions of SOD before 0.80.

EQMATRIX

An output file written by combsod that records, for each symmetry operator, how it maps atomic positions in the supercell onto one another. EQMATRIX is used internally by genersod and the SQS tools and does not normally require direct inspection.

FILER

An integer parameter in INSOD that selects which external calculator’s input files genersod produces. The supported values are: -1 (no files), 0 (CIF), 1 (GULP), 2 (LAMMPS), 11 (VASP), 12 (CASTEP), and 13 (Quantum ESPRESSO). For most calculators a template file must be present in the SODPROJECT; VASP is the exception and generates a POSCAR directly.

gcstatsod

The grand-canonical statistical analysis executable. Reads ENSEMBLE and ENERGIES files for multiple compositions together with INGC, and produces Boltzmann-weighted averages of energies and other observables across the composition range. Normally invoked via sod_gcstat.sh. See grand-canonical ensemble.

genersod

The input-file generation executable. It reads ENSEMBLE and a calculator template file to produce configuration-specific input files in the nXX/cYY/ directory tree (see SODPROJECT). Normally invoked automatically by sod_comb.sh; can be re-run independently via sod_gener.sh after changing FILER or the template.

GQS

Generalized Quasirandom Structures

An extension of SQS to finite temperatures. Rather than selecting the single configuration whose correlation functions are closest to ideal random values at 0 K, GQS computes the thermally weighted average of the multi-site cluster correlation functions (orders 1 to MaxOrder) from the full Boltzmann ensemble at each temperature. The result reflects how short-range order evolves with temperature. Implemented in gqssod and invoked via sod_gqs.sh.

grand-canonical ensemble

A statistical-mechanical treatment that includes configurations from supercells with different numbers of substitutions (i.e. different compositions). The chemical potential or target composition is held fixed rather than the substitution count. The grand-canonical approach is necessary when comparing energies across compositions or when computing phase boundaries. Implemented in gcstatsod. See also canonical ensemble.

inequivalent configuration

A configuration that is not related to any other enumerated configuration by a crystal symmetry operation. The set of all inequivalent configurations is the minimal representative set: each is counted once, weighted by its degeneracy. SOD’s primary task is to identify this set efficiently for arbitrary substitution patterns and space groups.

INGC

Input file for grand-canonical analysis, placed in an x???/ working folder. It specifies the composition range (nsubsmin/nsubsmax) and whether to fix the chemical potential (mu) or the composition fraction (x). Optionally enables the stress-volume correction.

INMC

Input file for Metropolis Monte Carlo sampling, placed in SODPROJECT. Specifies: symmetry reduction flag (0 off / 1 on), number of production steps (n_prod), starting configuration (random or space-separated site indices), whether to write a per-step trace (write_trace), number of equilibration steps (n_equil), restart probability (restart_prob), and random seed (-1 for system clock, any positive integer for a fixed seed). Temperature is not stored in INMC; instead, TEMPERATURES in SODPROJECT lists one temperature per line for the sod_mc.sh loop. Read by mcsod via sod_mc.sh. A copy is saved next to each MC run’s output (nXX/MCT_TTTK/CPMEx/) for reference. Uniform random sampling uses randomsod and does not read INMC.

INSOD

The main input file for a SOD calculation, placed in the SODPROJECT. It specifies the parent crystal structure, supercell dimensions, symmetry file reference, substitution targets, the nsubs count(s), and the FILER value. The format is strict: each data value occupies a fixed line, preceded by a blank line and a comment line.

INSQS

Input file for SQS and GQS analysis, placed in the SODPROJECT or a specific nXX/ folder. Specifies the maximum cluster order, cutoff radii, cluster weights, and van de Walle scoring parameters. For the generalized sqssod scorer, order 2 controls the species-resolved pair score; higher-order entries are accepted for compatibility and currently ignored by sqssod.

MAINFOLDER

Former name for SODPROJECT. Retained here for reference; all documentation and scripts now use SODPROJECT.

mcsod

The Metropolis Monte Carlo sampling executable. Uses a CPME effective Hamiltonian to drive sampling of the configuration space at a single temperature. The loop over multiple temperatures is handled by sod_mc.sh, which invokes one single-temperature MC run per TEMPERATURES entry. Reads INSOD, INMC, and SODPROJECT/cpme.model when present, and writes output to nXX/MCT_TTTK/CPMEx/. Any ε corrections from calibration energies are already baked into the loaded Hamiltonian before sampling begins. Normally invoked via sod_mc.sh. For energy-free uniform random sampling, see randomsod.

mcstatsod

The Monte Carlo thermodynamics program. Run from nXX/, it reads ../TEMPERATURES and the MCT_TTTK/CPMEx/ENSEMBLE and MCT_TTTK/CPMEx/ENERGIES files for each sampled temperature (the CPMEx variant is taken from ../cpme.model, defaulting to CPMEh), computes \(E_\mathrm{ave}(T) = \sum \omega E / \sum \omega\) from MC visit counts, and integrates \(d(\beta F)/d\beta = U(\beta)\) by trapezoidal quadrature. The exact high-temperature reference \(S(T \to \infty) = k_\mathrm{B} \ln C(n_\mathrm{pos}, \mathrm{lev})\) anchors the integration; a linear extrapolation handles the tail from the highest sampled inverse temperature to \(\beta = 0\). Output is written to thermodynamics.dat in the same column format as statsod. Always invoked via sod_mcstat.sh from nXX/. See also MCT.

MCT

A Metropolis Monte Carlo output directory, named MCT_TTTK where TTT is the integer temperature in kelvin (e.g. MCT_600K). Lives directly under nXX/ (sampling method first); because the Metropolis walk is Hamiltonian-driven, the run’s ENSEMBLE, ENERGIES, OUTMC, INMC and optional MCTRACE are written in a CPMEx subdirectory, nXX/MCT_TTTK/CPMEx/. All MCT_*K directories are processed together by sod_mcstat.sh to perform thermodynamic integration.

molecule substitution

Substitution of a rigid multi-atom molecular group at a crystal site, specified in INSOD using the @NAME prefix in newsymbol. SOD reads the geometry from NAME.xyz (standard XYZ format), computes the centre of mass, and places the molecule at the substituted site with an independent random orientation for each configuration. All calculator output formats expand the molecule into its constituent atoms. See also parent molecule and vacancy.

multi-nary substitution

Simultaneous placement of two or more new species on a single target site type, covering ternary, quaternary, and higher disordered alloys. The nsubs field in INSOD takes a space-separated list of counts, one per new species (e.g. 2 2 2 for three species). Can be combined with multi-target substitution.

multi-target substitution

Simultaneous substitution on two or more crystallographically distinct site types, with all configurations enumerated jointly under the full crystal symmetry. The sptarget line in INSOD lists the involved site indices, and nsubs provides one count per target site. Can be combined with multi-nary substitution.

nsubs

The substitution count field in INSOD. Controls how many atoms of each new species are placed on the target site(s). Accepts a fixed integer, a range (n1:n2) for scanning all compositions, a space-separated list for multi-nary substitution, or multiple lines for multi-target substitution. The endpoints are valid: 0 yields the single parent (unsubstituted) configuration, and a count equal to the number of target sites yields the single fully-substituted configuration.

OUTGQS

Output file written by gqssod (via sod_gqs.sh). Contains the thermally averaged multi-site cluster correlation functions at each temperature requested in the TEMPERATURES file, computed by Boltzmann weighting over the configurational ensemble. gqssod also writes wc_parameters.dat, which converts the pair correlations into Warren-Cowley parameters for each pair shell. See GQS.

OUTSQS

Output file written by sqssod (via sod_sqs.sh). A ranked list of inequivalent configurations, from best to worst SQS candidate, with matched distance, total species-pair probability error, score, and target-pair family errors. Rank 1 is the configuration closest to ideal random mixing. Detailed channel probabilities for the best configuration are written to SQS_CORRELATIONS. See SQS.

parent molecule

A molecular group that is part of the parent structure rather than substituted in. The parent keeps a single spherical placeholder species at the site — a point that obeys the SGO site symmetry and the inequivalent-configuration enumeration — and genersod materialises the molecule only when writing the calculation inputs. Declared by writing the parent species with an @NAME prefix in the INSOD symbol list (e.g. @MA) — the same @NAME convention used for molecule substitution. The @ is stripped, leaving an ordinary placeholder species NAME, and NAME.xyz is recorded as the molecule to materialise. The placeholder must not also be a substitution target. Each site is expanded with an independent random orientation, as for molecule substitution; this suits a dynamically isotropic (free-rotor) group, represented as a sphere for the symmetry analysis and made explicit only for individual calculations. Expanded by genersod across all calculator output formats; combsod treats @NAME as a plain placeholder species.

randomsod

The uniform random-sampling executable (wrapper sod_random.sh). Draws N independent uniform configurations at the target level with no energy evaluation and writes them to nXX/random/ENSEMBLE (with -sym on, the degeneracy column holds visit counts). It is the sampling counterpart of combsod for levels too large to enumerate; energies, if wanted, are computed a posteriori via the usual structure-writer → DFT → statsod path. Reads INSOD and SGO (always), plus EQMATRIX with -sym on.

reference energies

Energies of low-x (n00–n04) or high-x (n(M)–n(M-4)) configurations used to fit the V1–V4 interaction terms that define a CPME Hamiltonian. They are stored in the respective nXX/ENERGIES files in two-column format m  E_nm (configuration index and energy in eV), and are the training data for the Hamiltonian. Contrast with calibration energies, which tune the fitted model at an intermediate target composition.

SGO

The space group operators file, placed in SODPROJECT. Each line encodes one symmetry operation as three matrix elements (one row of the rotation matrix) and one translation component. Pre-computed SGO files for common space groups are distributed with SOD in the sgo/ library; custom files can be constructed from the International Tables of Crystallography or the Bilbao Crystallographic Server.

site-occupancy disorder

Structural disorder in which two or more distinct atomic species share the same crystallographic site type — that is, the atoms are mixed randomly (or with partial order) over a set of symmetry-equivalent positions. SOD models this type of disorder by explicitly enumerating the ordered configurations that represent the disordered solid.

sod_type_map

A comment directive used in calculator template files (GULP and LAMMPS) to map SOD species names to the type names expected by the calculator. Lines of the form # sod_type_map <SOD_species> <calc_type> are parsed by genersod and stripped from the generated input files; they do not appear in the final calculator inputs. Required whenever a SOD species label differs from the corresponding calculator atom type.

SODPROJECT

The top-level working directory for a SOD project (previously called MAINFOLDER). It contains INSOD, SGO, any calculator template files, TEMPERATURES, INMC, and receives EQMATRIX and supercell.cif after running combsod. Composition-level subdirectories nXX/ hold enumeration results, calculator runs, and CPME outputs; x???/ directories hold grand-canonical inputs.

SQS

Special Quasirandom Structures

The inequivalent configurations whose correlation functions most closely match the ideal random-mixing values at the same composition. Identified by sqssod (via sod_sqs.sh), which ranks all configurations by the deviation of their species-resolved pair probabilities from the independent-random targets. The rank-1 configuration is the best SQS for use in single-configuration calculations that aim to represent the disordered solid. See also GQS.

statsod

The canonical statistical analysis executable. Reads ENSEMBLE, ENERGIES, an optional DATA file, and an optional TEMPERATURES file. Enumeration and Uniform Monte Carlo ENSEMBLE files are interpreted with Boltzmann weighting. Metropolis-sampled ENSEMBLE files are identified from their sampling-temperature header and are averaged with Omega/sum(Omega) because the sample already contains the energy bias. Normally invoked via sod_stat.sh. See canonical ensemble.

stress-volume correction

A correction applied in grand-canonical ensemble analysis to account for the elastic energy penalty that arises when a supercell at one composition contributes to the ensemble at a different composition. The correction is based on the second-order Birch-Murnaghan equation of state and requires only the bulk modulus and equilibrium volumes of the two solid-solution end-members as input. Enabled in INGC.

supercell

A periodic cell formed by repeating the primitive unit cell of the parent structure in one or more directions. SOD enumerates all inequivalent configurations within a fixed supercell; the supercell size controls the accessible compositions and the quality of configurational averages and SQS.

supercell ensemble method

The approach used by SOD to model substitutional disorder: all inequivalent configurations of a fixed supercell are explicitly enumerated, and thermodynamic properties are computed as Boltzmann-weighted averages over this ensemble. As supercell size increases, the ensemble converges toward the thermodynamic limit.

vacancy

A lattice site from which the host atom is absent. Vacancies are specified in INSOD using the %NAME prefix in newsymbol (e.g. %O for an oxygen vacancy); the atom is simply omitted from all generated output files. Multiple vacancy types can coexist with ordinary and molecule substitution modes in the same calculation.

Warren-Cowley parameters

Warren parameters

Normalised pair correlation functions that measure the degree of chemical short-range order at each neighbour distance, \(\alpha_n = (\Pi_n - (1-2x)^2) / (4x(1-x))\) for a binary alloy at composition x, so that \(\alpha_n = 0\) under ideal random mixing. gqssod writes the thermally averaged \(\alpha_n\) of every symmetrically distinct pair shell to wc_parameters.dat. They are a post-hoc SRO diagnostic: neither SQS nor GQS selection is performed on them — the ranking uses the correlation functions directly.