Skip to content

Tutorial 13

Jump to bottom
nadavmoav edited this page Oct 21, 2025 · 17 revisions

🔀 Tutorial 13: Introduction to SQS and Disordered Materials

Disordered materials and alloys have atoms that are mixed randomly, not arranged in a perfect repeating pattern. That means there’s no long-range periodic order like in crystals. Instead of knowing exactly where each atom is, we can only describe the overall statistics — how often each type of atom shows up and where it's likely to be.

To simulate this kind of randomness, experimentalists often use fractional occupancies, where a single site is shared between different elements (e.g. 50% Cu and 50% Mn at the same site).

But ab initio software like VASP requires well-defined positions and periodic structures. Many real materials, such as disordered alloys, don’t follow this kind of perfect order.

Enter: Special Quasirandom Structures (SQS). Introduced by Alex Zunger in 1990,[1] SQS builds a periodic supercell that mimics the local statistics of a disordered atomic structure — making it suitable for simulation with tools like VASP.

🎯 What Does SQS Do?

SQS starts from a known framework structure (like a perfect crystal), keeping atom positions fixed but shuffling around atom types.

It tests many combinations of element assignments, and selects the one that best matches the statistics of a fully random alloy — like how often certain atoms appear as neighbors.

This gives you a periodic model that resembles real-world disorder.

📊 How SQS Measures Randomness: Correlation Functions

SQS relies on correlation functions, which capture how atoms are arranged relative to each other.

In a binary alloy (e.g. A and B), these functions look at:

  • How often A-A, B-B, and A-B pairs occur
  • How those pairs appear at 1st, 2nd, 3rd neighbor distances
  • Higher-order clusters of 3 or 4 atoms

The better the match between these functions and those of a truly random alloy, the better your SQS model.

🧰 SQS with ATAT

We use the Alloy Theoretic Automated Toolkit (ATAT) to generate SQS structures.

ATAT uses a Monte Carlo algorithm to shuffle atoms and improve the match to random statistics:

  1. Start with a random structure
  2. Measure correlation functions
  3. Swap atoms
  4. Accept/reject the swap based on improvement
  5. Repeat until satisfied

This efficiently finds a good approximation of a disordered material.

⚙️ Setting Up ATAT on the Cluster

To run ATAT on the POWER cluster, update your ~/.bashrc file:

### ----------- ATAT ----------- ###
export PATH=/bmd/shared/atat/bin/:$PATH
export PYTHONPATH=$PYTHONPATH:/bmd/shared/python_func/
### ---------------------------- ###

Then apply changes:

source ~/.bashrc

Verify setup with:

which mcsqs

You should see:

/bmd/shared/atat/bin/mcsqs

✅ That means you're ready.

🚀 Running an SQS Job

In your working directory, place:

  1. A POSCAR file — the crystal framework
  2. A job script — to run the SQS generator

📝 Sample SLURM Script

#!/bin/bash
#SBATCH -p leeburton-pool
#SBATCH --account=power-leeburton-users_v2
#SBATCH --job-name=sqs-binary
#SBATCH --time=36:00:00
#SBATCH --nodes=1
#SBATCH --ntasks=1
#SBATCH --mem=12GB

ulimit -s 81920

module load mamba > /dev/null
mamba activate /bmd/nadavmoav/envs/pymatgen-env

date > log

python -u /bmd/shared/python_func/generate-binary-sqs.py \
  --species ELEMENT_A ELEMENT_B \
  --compositions MIN MAX STEP \
  --scaling 20 \
  >> log

🧾 Flags Breakdown

--species ELEMENT_A ELEMENT_B

Required.
ELEMENT_A must exist in your POSCAR — it defines which atom sites will be substituted.

--compositions VALUE or MIN MAX STEP

Required.
Defines the desired proportion of ELEMENT_A to ELEMENT_B.
Examples:

--compositions 0.825
--compositions 0.60 0.90 0.05  # → 0.60, 0.65, ..., 0.90

--scaling INT or INT INT INT

Required.
Defines the size of the supercell.

  • --scaling 4 → total atom count scaled by 4
  • --scaling 2 2 2 → 2×2×2 cell replication

Optional Flags

--search-time 180     # Time in seconds (default: 180)
--temperature 1.0     # Monte Carlo T (default: 1.0)
--wr 1.0              # Raw error weight
--wn 1.0              # Normalized error weight
--wd 0.0              # Cluster size decay
--tol 1e-3            # Correlation match tolerance

🧪 Typical Usage

--species Mo Hf \
--compositions 0.60 0.90 0.05 \
--scaling 2 2 2

That’s usually all you need.

📦 Output Files

Each composition generates a .vasp structure like:

sqs_structure_80.0Mo.vasp

Here, 80.0Mo means 80% of Mo atoms.

🧹 Sorting Output Files

Sometimes the output .vasp files have atoms out of order:

Mo Hf Mo Hf Mo Hf Mo Hf Mo Hf Mo Hf Mo C
3 1 7 3 4 1 2 1 10 1 4 1 2 20

To fix this:

python /bmd/shared/python_func/sort-poscar-by-species.py sqs_structure_80.0Mo.vasp

This will create:

sqs_structure_80.0Mo-sorted.vasp

Now it’s clean and ready for VASP.

🧪 Verifying the Structure

You can verify that your SQS is still consistent with your framework using StructureMatcher from PyMatGen:

from pymatgen.analysis.structure_matcher import StructureMatcher, FrameworkComparator

matcher = StructureMatcher(
    comparator=FrameworkComparator(),
    attempt_supercell=True
)

📚 Documentation Reference

For further details, check out PyMatGen's SQS docs.

Also refer to this quick summary of key flags:

--species ELEMENT_A ELEMENT_B      # Required
--compositions VAL or MIN MAX STEP # Required
--scaling INT or INT INT INT       # Required
--search-time FLOAT                # Optional (default: 180)
--temperature FLOAT                # Optional (default: 1.0)
--wr FLOAT                         # Optional (default: 1.0)
--wn FLOAT                         # Optional (default: 1.0)
--wd FLOAT                         # Optional (default: 0.0)
--tol FLOAT                        # Optional (default: 1e-3)

🎉 Success!

You now have:

✅ ATAT installed and working on the POWER cluster
✅ Knowledge of how to generate and verify SQS structures
✅ Clean POSCARs ready for VASP simulations

👉 Continue to Tutorial 14 →

References

[1] A. Zunger, S.-H. Wei, L. G. Ferreira, and J. E. Bernard, Phys. Rev. Lett. 65, 353 (1990).

Clone this wiki locally