Tutorial 14

🔮 USPEX: Crystal Structure Prediction

USPEX is a software tool that can predict the crystal structure of materials that haven’t been discovered yet. It uses evolutionary algorithms and interfaces with VASP to explore stable and metastable configurations.

While USPEX is our primary tool at the moment, there are several other structure-prediction frameworks available, each offering different optimization strategies or machine-learning enhancements. Some examples include:

• XtalOpt (Zurek Lab) - Evolutionary Algorithm

• Global optimization of atomic structure enhanced by machine learning (Phys. Rev. B) - Evolutionary Algorithm and Bayesian Optimization

• CrySPY (Python-based CSP framework) - Evolutionary Algorithm and Bayesian Optimization

---

🛠️ Preparing Your Environment

USPEX depends on other tools to function, especially VASP. Make sure you’ve completed Tutorial 8 first.

🧾 Step 1: .bashrc and .bash_profile

USPEX and other tools need to be available in your environment every time you log in. This is handled by your ~/.bashrc file. If you don’t have it, create both:

~/.bash_profile

# .bash_profile

# Get the aliases and functions
if [ -f ~/.bashrc ]; then
    . ~/.bashrc
fi

PATH=$PATH:$HOME/.local/bin:$HOME/bin

export PATH

Add this to the end of your ~/.bashrc:

#### ------------- USPEX v.10.5.0 ------------- ####
export MCRROOT=/leeburton-data/
export PATH=/leeburton-data/application/archive/:$PATH
export USPEXPATH=/leeburton-data/application/archive/src
### ------------------------------------------ ###

---

🚀 Running USPEX for an Example

1️⃣ Open a tmux session

tmux

2️⃣ Activate your mamba environment and make a folder

mkdir uspex
cd uspex

3️⃣ Generate example input files

USPEX -c 01

---

⚙️ Editing Submission Settings

📄 submitJob_local.py

Inside the Submission/ folder, replace the existing job script template with:

myrun_content = '''#!/bin/sh -l
#
# filename: slurm_script
#SBATCH -p leeburton-pool
#SBATCH --account=power-leeburton-users_v2
#SBATCH -J {} 
#SBATCH --time=04:00:00
#SBATCH --nodes=1
#SBATCH --ntasks=24
#SBATCH --mem=120GB

{}
'''

---

📄 INPUT.txt: Command Section

Find and replace:

% commandExecutable
mpirun vasp_std > log
% EndExecutable

with:

% commandExecutable
module load intel/rocky8-oneAPI-2023; module load vasp/rocky8-intel-6.4.1; mpirun vasp_std > output
% EndExecutable

---

🔁 Running the USPEX Loop

📄 EX01-3D_Si_vasp.sh

#!/bin/sh

while [ ! -f ./USPEX_IS_DONE ] ; do
   date >> log
   USPEX -r >> log
   sleep 300
done

This script automatically reactivates USPEX after each VASP job and exits cleanly when done.

✅ Run it with:

./EX01-3D_Si_vasp.sh

📋 Then detach safely with Ctrl+b, then d.

---

🧪 Matching the Results with Literature

Use this pymatgen script to compare USPEX results with known structures:

from pymatgen.core import Structure
from pymatgen.analysis.structure_matcher import StructureMatcher
from pymatgen.io.vasp import Poscar

poscar = Poscar.from_file('/path/to/final.vasp')
structure2 = Structure.from_file('/path/to/reference.cif')

matcher = StructureMatcher(ltol=0.2, stol=0.3, angle_tol=5)
are_same = matcher.fit(poscar.structure, structure2)

print(are_same)
print("The structures are the same." if are_same else "The structures are different.")

---

🧪 Setting Up USPEX for a New System

🔬 Add POTCAR files

Copy the required POTCARs into Specific/ and rename them:

POTCAR_Si, POTCAR_O, etc.

Find them here:

/leeburton-data/shared/VASP/

Use PBE POTCARs for most cases.

🧬 Specify System Composition

Example for SiO₂:

% atomType
Si O
% EndAtomType

% numSpecies
8 16
% EndNumSpecies

🔄 VASP Runs

Specify 4 VASP runs:

% abinitioCode
1 1 1 1
% ENDabinit

Ensure 4 matching INCAR files: INCAR_1 → INCAR_4.

---

🌱 Seed, Specific, and INPUT.txt

• Specific/: Contains POTCARs and INCARs
• Seed/: Optional. Add known structures here to "seed" the simulation
• Submission/: Contains job submission settings

---

⚙️ INPUT.txt Key Settings

🧠 Calculation Control

USPEX : calculationMethod (USPEX, VCNEB, META)
300   : calculationType (dim / molecule / varcomp)
1     : AutoFrac

• calculationType = 3D, no molecule, fixed composition
• AutoFrac = On → adjusts evolution operators dynamically

🧬 Evolutionary Algorithm

20    : populationSize
30    : initialPopSize
25    : numGenerations
8     : stopCrit

This results in ~510 structures × 4 VASP runs = 2000+ jobs!

---

🧬 Variation Operators

0.50  : fracGene
0.30  : fracRand
0.20  : fracAtomsMut
0.00  : fracLatMut
0.00  : fracPerm 

Leave as-is unless you're tuning behavior.

---

🔧 KPOINT Resolution

% KresolStart
0.13 0.11 0.09 0.07
% Kresolend

4 values = 4 VASP runs. Must decrease in spacing.

---

⚙️ Final Configuration

Executable:

% commandExecutable
module load intel/rocky8-oneAPI-2023; module load vasp/rocky8-intel-6.4.1; mpirun vasp_std > output
% EndExecutable

Run Location:

1       : whichCluster (1 = local)
10      : numParallelCalcs

---

🧾 BMD's Recommended INCAR Files

INCAR_1

PREC = LOW
EDIFF = 2e-3
IBRION = 2
ISIF = 4
NSW = 85
ISMEAR = 1 ; SIGMA = 0.10
POTIM = 0.020
ISTART = 0
EDIFFG = -2e-1
LCHARG = FALSE
LWAVE = FALSE
NPAR=4

INCAR_2

PREC = Normal
EDIFF = 1e-3
IBRION = 1
ISIF = 4
NSW = 85
ISMEAR = 1 ; SIGMA = 0.09
POTIM = 0.25
LCHARG = FALSE
LWAVE = FALSE
EDIFFG = 1e-2
NPAR=4

INCAR_3

PREC = Normal
ENCUT = 400.0
EDIFF = 1e-5
IBRION = 2
ISIF = 3
NSW = 100
ISMEAR = 1 ; SIGMA = 0.060
POTIM = 0.020
ISTART = 0
LCHARG = FALSE
LWAVE = FALSE
NPAR=4

INCAR_4

PREC = Normal
ENCUT = 450.0
EDIFF = 3e-6
IBRION = 2
ISIF = 3
NSW = 100
ISMEAR = 1 ; SIGMA = 0.060
POTIM = 0.020
ISTART = 0
LCHARG = FALSE
LWAVE = FALSE
NPAR=4

---

🤖 Automating Folder Setup

BMD has a script to generate consistent USPEX folders:

📄 /bmd/shared/python_func/create_directories_and_edit_input.py

🏃 Run it like this:

python create_directories_and_edit_input.py <input_file> <uspex_template_dir> <multiplier>

• <input_file> = list of chemical formulas
• <uspex_template_dir> = USPEX template directory
• <multiplier> = multiply formula stoichiometry for larger supercells

🧪 Example:

Al2O3
SiO2
TiO2

🔁 With multiplier 4, Al2O3 becomes 8 Al and 12 O.

---

🎉 Congratulations! You are ready for Tutorial 15!