2. Getting started¶

2.1. How to obtain USPEX¶

USPEX can be downloaded at:

In the download page you will need to register and soon thereafter will receive a password for downloading USPEX.

2.2. Necessary citations¶

Whenever using USPEX, in all publications and reports you must cite the original papers, for example, in the following way:

“Crystal structure prediction was performed using the USPEX code ^2,14,20, based on an evolutionary algorithm developed by Oganov, Glass, Lyakhov and Zhu and featuring local optimization, real-space representation and flexible physically motivated variation operators”.

Consult the OUTPUT.txt file for some of the most important references.

2.3. Bug reports¶

Like any large code, USPEX may have bugs. If you see strange behavior in your simulations, please report it to us in USPEX Google group at:

https://groups.google.com/forum/#!forum/uspex

Please describe your problem in details and attach input.uspex, OUTPUT.txt, log, and other related files when you report a problem. You can also send the questions or problem descriptions to bugreport@uspex-team.org).

2.4. On which machines USPEX can be run¶

Pythonized version of USPEX can be used on linux platform — all you need is one CPU with installed python and — using its special remote submission mechanism, USPEX will be able to connect to any remote machine and use it for calculations.

2.5. Codes that can work with USPEX¶

Trial structures generated by USPEX are relaxed and then evaluated by an external code interfaced with USPEX. Based on the obtained ranking of relaxed structures, USPEX generates new structures — which are again relaxed and ranked. Our philosophy is to use existing well-established ab initio (or classical forcefield) codes for structure relaxation and energy calculations. Currently, USPEX-2022.1 is interfaced with:

We chose these codes based on 1) their efficiency for structure relaxation; 2) robustness; and 3) popularity. Of course, there are other codes that can satisfy these criteria, and in the future we can interface USPEX to them.

2.6. How to install USPEX¶

USPEX v.2022.1 is compiled using Cython compiler. After you download the archive with USPEX, you need to unpack and install it using pip installer.

pip install USPEX-2022.1.0-<ver>-<ver>-linux_x86_64.whl

Chose one of whl files in archive depending on version of python you are using.

The file random_cell should be copied manually into any directory listed in user’s PATH environment setting. For example into ~/.local/bin/ folder.

2.7. How to run USPEX¶

To run USPEX, you need to have Python and to have the executable of the external code on the compute nodes that you use for relaxing structures and computing their energies (see Section 2.5 for a list of supported codes). To set up your calculation, find an example (see Section 4 for a list of examples) similar to what you want to do, and start by editing input.uspex. The variables of this crucial file are described in Section 5 below. Then, gather the files needed for the external code performing structure relaxation in the folder — the executable (e.g., vasp ), and such files as (if you use VASP) INCAR_1, INCAR_2, …, INCAR_N, and POTCAR_A, POTCAR_B, …, where A, B, … are the symbols of the chemical elements of your compound.

To run USPEX just type:

uspex -r

File log will contain information on the progress of the simulation and, if any, errors (send these to us, if you would like to report a bug). File OUTPUT.txt will contain details of the calculation and an analysis of each generation.