2.8 Running USPEX examples: a mini-tutorial

Once you have downloaded the USPEX package and installed it, you can run the first USPEX example. The description of the examples is listed in Appendix 9.1. The required external codes to run the examples (except EX13) are shown below:

Now, let us start our first USPEX experience:

Test the USPEX python runner

To get the version information, you can use the following command:

>> USPEX -v

You should get the following information:

  USPEX Version 9.4.2 (19/03/2015)
If it does not work, please check your installation procedure and environment settings as described above.

Run the EX13-3D_special_quasirandom_structure_TiCoO

EX13 does not require any external code, you can run it to get familiar with the USPEX running procedure. The calculation would take $\sim $30 minutes. To start the calculation, first create a test folder, copy the example files and then run the calculation through the USPEX Python runner, with the following commands:

>> mkdir EX13
>> cd EX13
>> USPEX -c 13
>> USPEX -r

Meanwhile you have some time to get more details about example EX13. In EX13, the structural order is optimized (minimized) with the evolutionary algorithm. Therefore in INPUT.txt the following is set:

USPEX : calculationMethod
-4    : optType

and these parameters are used below:

300   : calculationType

% atomType
Co Ti O
% EndAtomType

% numSpecies
16 16 64
% EndNumSpecies

to specify USPEX to evaluate the Co$_{16}$Ti$_{16}$O$_{64}$ system. To reduce calculation time of EX13, you can reduce populationSize and numGenerations, for example:

5    : populationSize
5    : numGenerations

However, with such a small populationSize and numGenerations, you cannot expect USPEX to find the structure with the lowest order. Since you do not need to use any external code, you can simply set

% abinitioCode
% ENDabinit

The Seeds/POSCARS file contains the initial Ti$_{16}$Co$_{16}$O$_{64}$ structure.

When you find the USPEX_IS_DONE file, congratulations, you have successfully finished your first USPEX example. Next, you can run calculations using external codes.

Run an example using external code

In this step, we suggest to run examples interfaced with GULP or VASP, starting from EX02 or EX01. You will also use USPEX runner to get the example information of EX02, create a separate folder and copy the files, with commands:

>> mkdir EX02
>> cd EX02
>> USPEX -c 2

Since in example EX02 GULP code is used, set:

% abinitioCode
3 3 3 3
% ENDabinit

To run a serial job without a job batch system, you should change the following parameters in the INPUT.txt below:

0     : whichCluster 
1     : numParallelCalcs

In the example INPUT.txt file whichCluster=QSH, where QSH is our group’s cluster name. We also provide the same way to help users to define their own cluster. For more details, please see Section 8.9.

In INPUT.txt, we do not specify how to run GULP, because we assume all users use the same command:

% commandExecutable
gulp < input > output
% EndExecutable

But make sure, this command also works on your machine. If you want to run EX01 with a parallel version of VASP, you should set something like:

% abinitioCode
1 1 1 1
% ENDabinit

% commandExecutable
mpirun -np 8 vasp
% EndExecutable

With wrong commandExecutable settings, you will fail to start the USPEX calculation. When everything is set correctly, we can run the calculation through USPEX runner using the command:

>> USPEX -r

Checking the results

After starting the command, you can check the output files in results1/ folder.

Now, you have a basic experience of using USPEX to run simple calculations. Please read the following sections of this manual to get more insight into USPEX. When analyzing results, it is essential that you visualize the structures (for visualization, see section 8.1).