USPEX

USPEX (Universal Structure Predictor: Evolutionary Xtallography…and in Russian “uspekh” means “success” - owing to the high success rate and many useful results produced by this method) is a method developed by the Oganov laboratory since 2004. The problem of crystal structure prediction is very old and does, in fact, constitute the central problem of theoretical crystal chemistry.

Policy

You need to download and install USPEX yourself and register/get your own license.

Citations

Citations to the original USPEX publications must be present in all papers that used USPEX:

  • Oganov A.R., Glass C.W. (2006). Crystal structure prediction using ab initio evolutionary techniques: principles and applications. J. Chem. Phys. 124, art. 244704.
  • Oganov A.R., Lyakhov A.O., Valle M. (2011). How evolutionary crystal structure prediction works - and why. Acc. Chem. Res. 44, 227-237
  • Lyakhov A.O., Oganov A.R., Stokes H.T., Zhu Q. (2013). New developments in evolutionary structure prediction algorithm USPEX. Comp. Phys. Comm. 184, 1172-1182.

Overview

In 1988 John Maddox wrote that:

"One of the continuing scandals in the physical sciences is that it remains in general impossible to predict the structure of even the simplest crystalline solids from a knowledge of their chemical composition solids such as crystalline water (ice) are still thought to lie beyond mortals' ken".

USPEX code solves this problem and allows to predict crystal structure with arbitrary P-T conditions by knowing only chemical composition of the material. Nowdays, it is used by over 10600 researchers worldwide. The First Blind Test of Inorganic Crystal Structure Prediction shows that USPEX outperforms other methods in terms of efficiency and reliability. The method continues to be rapidly developed.

In addition to crystal structure prediction, USPEX can work in other dimensionalities and predict the structure of nanoparticles, polymers, surfaces, interfaces and 2D-crystals. It can very efficiently handle molecular crystals (including those with flexible and very complex molecules). Moreover, it can predict stable chemical compositions and corresponding crystal structures, given just the names of the chemical elements. In addition to this fully non-empirical search, USPEX allows one to predict also a large set of robust metastable structures and perform several types of simulations using various degrees of prior knowledge.

USPEX can also be used for finding low-energy metastable phases, as well as stable structures of nanoparticles, surface reconstructions, molecular packings in organic crystals, and for searching for materials with desired physical (mechanical, electronic) properties. The USPEX code is based on an efficient evolutionary algorithm developed by A.R. Oganov’s group, but also has options for using alternative methods (random sampling, metadynamics, corrected particle swarm optimization algorithms). USPEX is interfaced with many ab initio codes, such as VASP, SIESTA, GULP, Quantum Espresso, CP2K, CASTEP, LAMMPS, and so on.

USPEX at HPC2N

Since USPEX is not installed at HPC2N, you need to install it yourself.

Note

From version 10.2 USPEX is no longer dependent on MATLAB, but is distributed as compiled code.

This documentation is valid for version 10.4 and the example used is for getting USPEX to work together with VASP.

Steps to get to run:

  1. Download and unpack the USPEX tar file: tar zxvf USPEX-10.4.tar.gz
  2. Change to the USPEX directory: cd USPEX_v10.4
  3. Load Python (3.7.4) and needed Python packages (numpy scipy spglib pysqlite3 ase matplotlib): 
    module load GCC/10.3.0
module load Python/3.9.5
module load OpenMPI/4.1.1
module load SciPy-bundle/2021.05 
module load matplotlib/3.4.2  
module load spglib/1.16.2 
module load SQLite/3.35.4 
module load ASE/3.22.0
    NOTE you need to load these modules each time you are using USPEX
  4. We need to install pysqlite3 in a virtual environment as it is note available site installed. 
    python -m venv USPEXvenv 
source USPEXvenv/bin/activate 
pip install --no-cache-dir pysqlite3
    NOTE you only do this install once, but you need to activate the environment each time you use USPEX, in order to access the self-installed Python package! NOTE you deactivate the environment with deactivate.
  5. In order to use the virtual environment you just created and installed to, together with USPEX, it is easiest to just activate it again with source USPEXenv/bin/activate when starting USPEX. Otherwise you can do this setup of paths in your .bashrc by adding these lines (adjusted to fit your path) to your .bashrc in your home directory: 
    export PATH=/path/to/the/installation/USPEX_v10.4/py3_uspex/bin:$PATH
export PYTHONPATH=/path/to/the/installation/USPEX_v10.4/USPEXvenv/lib/python3.9/site-packages:$PYTHONPATH
  6. Make sure the USPEX install file is executable (from the USPEX directory): 
    chmod u+x install.sh USPEX_MATLABruntime.install
  7. Now install USPEX: 
    ./install.sh
    NOTE: make sure you choose the non-GUI installation. Accept the questions and give the path to where you want the USPEX installation to be located. Example: /path/to/installation/USPEX_v10.4/my_install
  8. USPEX will be installed. NOTE As part of this process, there will be some parameters added to your .bashrc file. Make sure you remove these if you need to install another version.
  9. Do source ~/.bashrc

  10. Potentially needed setup!

    Setup

    To get the run-uspex_py.sh script, run 

    USPEX --generate

    in the job folder.

    This means the Submission folder will be created. The script should be copied from that to the job folder (i.e. the folder where INPUT.txt is located).

  11. You also need to do some minor changes to two files in order for this to work at HPC2N.

    • First do a backup of the files: 
      cd /path/to/my/installation/USPEX_v10.4/my_install/application/archive/src/Submission 
cp submitJob_local.py submitJob_local.py.orig 
cp checkStatus_local.py checkStatus_local.py.orig
    • Now download the lightly altered files submitJob_local.py and checkStatus_local.py.
    • Make the needed change in the line #SBATCH -A hpc2nXXXX-YYY in Step 1 in submitJob_local.py and also possibly the lines #SBATCH -n 4 and #SBATCH -t 05:00:00 depending on what you need.
  12. You can now run an example. To do so you also need to load a compatible VASP version, like version 6.2.1: 
    module load VASP/6.2.1
    this should be done inside the USPEX input file, and you should also run VASP from inside the USPEX input file INPUT.TXT so it should look something like this inside that file (change to relevant VASP executable for your own case): 
    % commandExecutable
module load VASP/6.2.1; srun vasp_std > log
% EndExecutable
    Note that you should stand in the directory of your VASP files when running this.

Note

To start the USPEX process in the background on the login node, so it will not stop when the terminal is closed, either start it in a terminal with screen or tmux and close it after working with USPEX or do:

nohup ./run-uspex_py.sh &

NOTE remember to remove the USPEX process after USPEX has finished, by doing

  • “ps -efH | grep <username> to find the process
  • kill -9 <the process-id>

Acknowledgment

This page was heavily inspired by

Additional info

For more information about running USPEX, please see