2.7 How to run USPEX

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

There are two ways to run the code — old and new, and both work.

(i) In the old way, you need to have the entire USPEX code (file USPEX.m, directory FunctionFolder, etc.) in your execution folder. Then type

    nohup matlab < USPEX.m > log &

or, if you use Octave, type

    nohup octave < USPEX.m > log &

(ii) In the new way, if you used the USPEX installer for the Python-based runner, all you need to execute the code is just type:

    nohup USPEX -r > log &

or, if you use Octave, type

    nohup USPEX -r -o > log &

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.

For the USPEX runner, we have a number of user-friendly options:

• -v, --version: show program’s version number and exit

• -h, --help: show this help message and exit

• -p, --parameter: specify parameter to get help. If no value or ’all’ value is specified, all INPUT.txt parameters will be shown

• -e, --example: show USPEX example details. If no value or ’all’ value is specified, all examples will be shown

• -c NUM, --copy=NUM: copy the INPUT.txt file and Specific Folder of ExampleXX.

• -g, --generate: generate directories for preparing an USPEX calculation, including AntiSeeds, Seeds, Specific, Submission folders

• -r, --run: run USPEX calculation

• -o, --octave: run USPEX calculation with Octave instead of MATLAB

• --clean: clean calculation folder

When running USPEX in the massively parallel mode, the user needs to do minimal work to configure files to the user’s computers (hence, we cannot guarantee support for solving problems with massively parallel mode).

There are two modes for job submission — (1) local submission and (2) remote submission, depending on whether you submit ab initio calculations on the same machine where you run USPEX and MATLAB, or if you send your jobs to a remote supercomputer. See the keyword whichCluster and Subsection 8.9 of this Manual.

Please note, that you shoud have bash shell set by default to make USPEX working correctly. Users frequently report issues when running USPEX on a machine with csh shell, where “echo -e …” command might not be supported.