USPEX

https://uspex-team.org/online_utilities/tmp/uspex_manual_release/EnglishVersion/uspex_manual_english/
Admin
USPEX (Universal Structure Predictor: Evolutionary Xtallography) is a software package that uses...
Tokens:39,887
Snippets:364
Trust Score:8.1
Update:9 months ago
Show doc for...
Tokens:
Raw
### Install USPEX

Source: https://uspex-team.org/online_utilities/tmp/uspex_manual_release/EnglishVersion/uspex_manual_english/sect0011

This command initiates the USPEX installation process. It does not require root privileges unless installing to the root partition. The installation bundles USPEX with the necessary Matlab Runtime (MCR).

```shell
sh install.sh
```

--------------------------------

### Run USPEX Example EX02 (Using GULP)

Source: https://uspex-team.org/online_utilities/tmp/uspex_manual_release/EnglishVersion/uspex_manual_english/sect0013

This sequence demonstrates running USPEX example EX02, which utilizes the GULP code. It includes creating a directory, navigating into it, setting the ab initio code for GULP, configuring for serial execution, and initiating the calculation.

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

% abinitioCode
3 3 3 3
% ENDabinit

1     : whichCluster
1     : numParallelCalcs

% commandExecutable
gulp < input > output
% EndExecutable

>> USPEX -r
```

--------------------------------

### USPEX INPUT.txt Configuration for EX02 (GULP)

Source: https://uspex-team.org/online_utilities/tmp/uspex_manual_release/EnglishVersion/uspex_manual_english/sect0013

Configuration settings for USPEX example EX02 in `INPUT.txt`, specifying the use of GULP as the ab initio code, serial job execution, and the command to run GULP.

```plaintext
% abinitioCode
3 3 3 3
% ENDabinit

1     : whichCluster
1     : numParallelCalcs

% commandExecutable
gulp < input > output
% EndExecutable
```

--------------------------------

### Run USPEX Example EX13 (No External Code)

Source: https://uspex-team.org/online_utilities/tmp/uspex_manual_release/EnglishVersion/uspex_manual_english/sect0013

This sequence of commands demonstrates how to run USPEX example EX13, which does not require any external computational codes. It involves creating a directory, navigating into it, initiating the calculation with a specific parameter, and then running the calculation itself.

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

--------------------------------

### Check USPEX Version

Source: https://uspex-team.org/online_utilities/tmp/uspex_manual_release/EnglishVersion/uspex_manual_english/sect0013

This command retrieves the installed version of USPEX. It is a simple utility command with no external dependencies and provides the version information as output.

```bash
>> USPEX -v
```

--------------------------------

### Set Execute Permissions for USPEX Installation

Source: https://uspex-team.org/online_utilities/tmp/uspex_manual_release/EnglishVersion/uspex_manual_english/sect0011

This command recursively grants read and write (and execute) permissions to all files and directories within the USPEX installation path. This is crucial for avoiding errors and ensuring proper functionality when running USPEX examples.

```shell
chmod +rw -R /installation path of USPEX/application/archive/
```

--------------------------------

### USPEX INPUT.txt Configuration for EX01 (VASP Parallel)

Source: https://uspex-team.org/online_utilities/tmp/uspex_manual_release/EnglishVersion/uspex_manual_english/sect0013

Configuration for running USPEX example EX01 using a parallel version of VASP. This snippet shows the `abinitioCode` setting for VASP and the `commandExecutable` for parallel execution using `mpirun`.

```plaintext
% abinitioCode
1 1 1 1
% ENDabinit

% commandExecutable
mpirun -np 8 vasp
% EndExecutable
```

--------------------------------

### Evolutionary Metadynamics (calculationMethod=META) Input File

Source: https://uspex-team.org/online_utilities/tmp/uspex_manual_release/EnglishVersion/uspex_manual_english/appendix_input_files

This is an example of an INPUT.txt file for an evolutionary metadynamics calculation. It specifies the calculation method as META, along with parameters for external pressure, atom counts, vector lengths, population and generation counts, mutation degree, and Gaussian parameters for the metadynamics bias. It also includes abinitio code and execution commands.

```txt
META  : calculationMethod (USPEX, VCNEB, META)
301   : calculationType (dimension: 0-3; molecule: 0/1; varcomp: 0/1)

0.0001 : ExternalPressure

16    : maxAt
2.0   : minVectorLength
8.0   : maxVectorLength

15    : populationSize
40    : numGenerations
3.0   : mutationDegree
250.0 : GaussianHeight
0.3   : GaussianWidth
2     : FullRelax

abinitioCode
1 1 1 (1 1)
ENDabinit

% KresolStart
0.12 0.10 0.09 0.10 0.08
% Kresolend

% commandExecutable
mpirun -np 4 vasp > log
% EndExecutable

```

--------------------------------

### Configure Bash Shell Environment Variables

Source: https://uspex-team.org/online_utilities/tmp/uspex_manual_release/EnglishVersion/uspex_manual_english/sect0011

These export commands should be added to the user's `.bashrc`, `.profile`, or `/etc/profile` file to make USPEX and its associated paths accessible in the Bash shell. MCRROOT points to the Matlab Runtime installation directory.

```shell
export PATH=/home/user/bin/USPEX/application/archive/:$PATH
export USPEXPATH=/home/user/bin/USPEX/application/archive/src
export MCRROOT=/usr/local/MATLAB/MATLAB_Runtime
```

--------------------------------

### Summary of Thermoelectric Optimization Results

Source: https://uspex-team.org/online_utilities/tmp/uspex_manual_release/EnglishVersion/uspex_manual_english/thermoelectricity

Example output from the 'summary.txt' file within the TEproperties subfolder, listing the structure ID and corresponding maximum chemical potential (mu_max) and thermoelectric figure of merit (ZT) values.

```text
#                 trace
# ID   mu_max_1  ZT_max_1  mu_max_2  ZT_max_2
    1  0.019900  0.314997 -0.186600  0.294976
    2  0.152270  0.913590  0.002270  0.864951
    3 -0.021300  4.951155  0.152200  3.244481
    4 -0.194630  0.677683  0.054370  0.628948
    6  0.024120  6.144226  0.053620  0.914606
    7  0.030460  0.887808  0.041960  0.831734
    9  0.167860  0.479234  0.159360  0.446431
   10  0.133260  0.893694  0.144760  0.822560
   12  0.063250  0.903193  0.075750  0.843479
   13  0.044820  1.793899  0.004820  1.026578

```

--------------------------------

### Fixed-Composition USPEX Calculation (calculationType=300) Input File

Source: https://uspex-team.org/online_utilities/tmp/uspex_manual_release/EnglishVersion/uspex_manual_english/appendix_input_files

This example shows a sample INPUT.txt file for a fixed-composition USPEX calculation. It includes parameters for the evolutionary algorithm, atom types, number of species, generations, external pressure, and abinitio code execution. The `commandExecutable` specifies how to run the abinitio code.

```txt
PARAMETERS EVOLUTIONARY ALGORITHM
% Example of the short input, using most options as defaults

% atomType
Mg Al O
% EndAtomType

% numSpecies
2 4 8
% EndNumSpecies

50   : numGenerations
50.0 : ExternalPressure

% abinitioCode
3 3 3 3 3
% ENDabinit

% commandExecutable
gulp < input > output
% EndExecutable

```

--------------------------------

### USPEX INPUT.txt Configuration for EX13

Source: https://uspex-team.org/online_utilities/tmp/uspex_manual_release/EnglishVersion/uspex_manual_english/sect0013

Configuration parameters within the `INPUT.txt` file for USPEX example EX13. This snippet shows settings for calculation method, atom types, number of species, and crucially, disabling external ab initio codes.

```plaintext
USPEX : calculationMethod
% optType
-4  
% EndOptType

300   : calculationType

% atomType
Co Ti O
% EndAtomType

% numSpecies
16 16 64
% EndNumSpecies

% abinitioCode
0
% ENDabinit
```

--------------------------------

### USPEX Seed Technique: Variable Composition POSCAR Example

Source: https://uspex-team.org/online_utilities/tmp/uspex_manual_release/EnglishVersion/uspex_manual_english/faq_seeds

This example illustrates how to specify atomic symbols for variable composition calculations within the seed file. It shows the required format for the atomic symbols line, which is crucial for USPEX to correctly interpret the structure.

```plaintext
H_I-P63/mc
    1
    4.754726  -2.74514  0.000000
    -0.00000  5.490285  0.000000
    0.000000  0.000000  4.508715
    H
    16
    Direct
    ...
    (the atomic positions information is omitted here)
```

--------------------------------

### Configure C Shell Environment Variables

Source: https://uspex-team.org/online_utilities/tmp/uspex_manual_release/EnglishVersion/uspex_manual_english/sect0011

These setenv commands are for configuring USPEX environment variables in the C shell. They should be added to the user's `.cshrc`, `.profile`, or `/etc/profile` file. MCRROOT specifies the Matlab Runtime path.

```shell
setenv PATH "/home/user/bin/USPEX/application/archive :$PATH"
setenv USPEXPATH "/home/user/bin/USPEX/application/archive/src"
setenv MCRROOT “/usr/local/MATLAB/MATLAB_Runtime”
```

--------------------------------

### USPEX Optimization Type: Basic Examples

Source: https://uspex-team.org/online_utilities/tmp/uspex_manual_release/EnglishVersion/uspex_manual_english/sect0017

Examples of defining the 'optType' variable in USPEX for single-objective optimization. This specifies the property to be optimized.

```text
% optType
enthalpy
% EndOptType
```

```text
% optType
Min_(bandgap-1.34)^2
% EndOptType
```

--------------------------------

### USPEX Optimization Type: Multiobjective Examples

Source: https://uspex-team.org/online_utilities/tmp/uspex_manual_release/EnglishVersion/uspex_manual_english/sect0017

Examples of defining 'optType' for multiobjective (Pareto) optimization in USPEX. This allows optimizing multiple properties simultaneously.

```text
% optType
3 1
% EndOptType
```

```text
% optType
max_Hardness enthalpy
% EndOptType
```

--------------------------------

### VCNEB Calculation (calculationMethod=VCNEB) Input File

Source: https://uspex-team.org/online_utilities/tmp/uspex_manual_release/EnglishVersion/uspex_manual_english/appendix_input_files

This sample INPUT.txt file demonstrates the configuration for a VCNEB (Variable Composition Nudged Elastic Band) calculation. It includes parameters for the number of species, atom types, external pressure, VCNEB specific types, number of images, steps, optimizer settings, convergence criteria, and path length. It also specifies the abinitio code and execution command.

```txt
VCNEB : calculationMethod

% numSpecies
4
% EndNumSpecies

% atomType
Ar
% EndAtomType

0.0   : ExternalPressure

111   : vcnebType
15    : numImages
500   : numSteps
1     : optimizerType
2     : optReadImages
3     : optRelaxType
0.25  : dt
0.003 : ConvThreshold

0.3   : VarPathLength
3     : K_min
6     : K_max
0     : optFreezing
0     : optMethodCIDI

2     : FormatType
10    : PrintStep

abinitioCode
3
ENDabinit

% commandExecutable
gulp < input > output
% EndExecutable

```

--------------------------------

### Connect via SSH Without Password

Source: https://uspex-team.org/online_utilities/tmp/uspex_manual_release/EnglishVersion/uspex_manual_english/faq_passwordless

Establishes an SSH connection to the remote host without requiring a password, utilizing the previously set up public key authentication. This confirms the passwordless setup is successful.

```bash
ssh -p portB userB@hostB
```

--------------------------------

### Submit Job to Remote Cluster (Python)

Source: https://uspex-team.org/online_utilities/tmp/uspex_manual_release/EnglishVersion/uspex_manual_english/faq_job_submit

This Python function submits a job to a remote cluster. It prepares a shell script for the job, transfers input files (POSCAR, INCAR, POTCAR, KPOINTS) to the remote directory, and then submits the job using 'qsub'. It returns the job ID assigned by the cluster. Dependencies include the 'argparse', 'os', 're', and 'subprocess' modules. Input parameters are the working directory, job index, and the command to execute.

```python
import argparse
import os
import re
from subprocess import check_output

def submitJob_remote(workingDir : str, index : int, commandExecutable : str) -> int:
    """
    This routine is to submit job to remote cluster
    One needs to do a little edit based on your own case.
    Step 1: to prepare the job script which is required by your supercomputer
    Step 2: to submit the job with the command like qsub, bsub, llsubmit, .etc.
    Step 3: to get the jobID from the screen message
    :param workingDir: working directory on remote machine
    :param index: index of the structure.
    :param commandExecutable: command executable for current step of optimization
    :return: 
    """
    # Step 1
    # Specify the PATH to put your calculation folder
    Home = '/home/etikhonov' # 'pwd' of your home directory of your remote machine
    Address = 'rurik' # your target server: ssh alias or username@address
    Path = Home + '/' + workingDir + '/CalcFold' + str(index)

    # Just keep it
    run_content = ''
    run_content += '#!/bin/sh\n'
    run_content += '#SBATCH -o out\n'
    run_content += '#SBATCH -p cpu\n'
    run_content += '#SBATCH -J USPEX-' + str(index) + '\n'
    run_content += '#SBATCH -t 06:00:00\n'
    run_content += '#SBATCH -N 1\n'
    run_content += '#SBATCH -n 8\n'
    run_content += 'cd /cephfs'+ Path + '\n'
    run_content += commandExecutable + '\n'

    with open('myrun', 'w') as fp:
        fp.write(run_content)

    # Create the remote directory
    # Please change the ssh/scp command if necessary.
    try:
        os.system('ssh -i ~/.ssh/id_rsa ' + Address + ' mkdir -p ' + Path)
    except:
        pass

    # Copy calculation files
    # add private key -i ~/.ssh/id_rsa if necessary
    os.system('scp POSCAR ' + Address + ':' + Path)
    os.system('scp INCAR ' + Address + ':' + Path)
    os.system('scp POTCAR ' + Address + ':' + Path)
    os.system('scp KPOINTS ' + Address + ':' + Path)
    os.system('scp myrun ' + Address + ':' + Path)

    # Step 2
    # Run command
    output = str(check_output('ssh -i ~/.ssh/id_rsa ' + Address + ' qsub ' + Path + '/myrun', shell=True))

    # Step 3
    # Here we parse job ID from the output of previous command
    jobNumber = int(re.findall(r'\d+', output)[0])
    return jobNumber

if __name__ == '__main__':
    parser = argparse.ArgumentParser()
    parser.add_argument('-i', dest='index', type=int)
    parser.add_argument('-c', dest='commnadExecutable', type=str)
    parser.add_argument('-f', dest='workingDir', type=str)
    args = parser.parse_args()
    jobNumber = submitJob_remote(workingDir=args.workingDir, index=args.index, commnadExecutable=args.commnadExecutable)
    print('CALLBACK ' + str(jobNumber))

```

--------------------------------

### Variable-Composition USPEX Calculation (calculationType=301) Input File

Source: https://uspex-team.org/online_utilities/tmp/uspex_manual_release/EnglishVersion/uspex_manual_english/appendix_input_files

This sample INPUT.txt file is for a variable-composition USPEX calculation. It defines the calculation method, type, and various parameters such as atom types, number of species, population sizes, generations, stopping criteria, and constraints on atom counts. It also specifies the abinitio code and execution command.

```txt
USPEX : calculationMethod (USPEX, VCNEB, META)
301   : calculationType (dimension: 0-3; molecule: 0/1; varcomp: 0/1)
1     : AutoFrac

% atomType
Mo B
% EndAtomType

% numSpecies
1 0
0 1
% EndNumSpecies

80    : populationSize
200   : initialPopSize
60    : numGenerations
20    : stopCrit

11    : firstGeneMax
8     : minAt
18    : maxAt

% abinitioCode
3 3 3
% ENDabinit

% commandExecutable
gulp < input > output
% EndExecutable

```

--------------------------------

### Set Up Passwordless SSH with DSA Keys

Source: https://uspex-team.org/online_utilities/tmp/uspex_manual_release/EnglishVersion/uspex_manual_english/faq_passwordless

This alternative method involves generating DSA keys, securely copying the public key to the remote cluster, and then appending it to the authorized_keys file on the remote host. It ensures secure and passwordless remote access.

```bash
local # ssh-keygen -t dsa
local # scp ~/.ssh2/id_dsa.pub oganov@palu.cscs.ch:~/.ssh/tmp.pub
remote # cd ~/.ssh/
remote # ssh-keygen -f tmp.pub -i >> authorized_keys
remote # rm tmp.pub
```

--------------------------------

### Structure Relaxation using VASP and BoltzTraP

Source: https://uspex-team.org/online_utilities/tmp/uspex_manual_release/EnglishVersion/uspex_manual_english/thermoelectricity

Configures USPEX to combine VASP and BoltzTraP for structure relaxation, essential for thermoelectric property calculations. The 'abinitioCode' keyblock specifies the VASP execution series with varying k-point grids, and 'KresolStart' defines the k-point parameters for these relaxations.

```text
% abinitioCode
1 1 1 (1 14)
% ENDabinit

% KresolStart
0.12 0.10 0.07 0.05 0.05
% Kresolend

```

--------------------------------

### Configure Local Job Submission Script

Source: https://uspex-team.org/online_utilities/tmp/uspex_manual_release/EnglishVersion/uspex_manual_english/faq_job_submit

This Python script configures and submits a job locally. It prepares a shell script for job execution (e.g., using SLURM directives), submits it using 'sbatch', and parses the job ID from the output. It requires Python and standard libraries like 'subprocess', 're', and 'sys'.

```python
from subprocess import check_output
import re
import sys

def submitJob_local(index : int, commnadExecutable : str) -> int:
    """
    This routine is to submit job locally
    One needs to do a little edit based on your own case.
    Step 1: to prepare the job script which is required by your supercomputer
    Step 2: to submit the job with the command like qsub, bsub, llsubmit, .etc.
    Step 3: to get the jobID from the screen message
    :return: job ID
    """
    # Step 1
    myrun_content = ''
    myrun_content += '#!/bin/sh\n'
    myrun_content += '#SBATCH -o out\n'
    myrun_content += '#SBATCH -p cpu\n'
    myrun_content += '#SBATCH -J USPEX-' + str(index) + '\n'
    myrun_content += '#SBATCH -t 06:00:00\n'
    myrun_content += '#SBATCH -N 1\n'
    myrun_content += '#SBATCH -n 8\n'
    # myrun_content += '#PBS -l walltime=06:00:00,nodes=1:ppn=8\n'
    # myrun_content += '#PBS -N USPEX_job\n'
    # myrun_content += '#PBS -o out\n'
    # myrun_content += '#PBS -j oe\n'
    # myrun_content += 'cd ${PBS_O_WORKDIR}\n'
    # check this, must have /cephfs suffix with SBATCH in my case
    myrun_content += 'mpirun vasp_std > log\n'
    with open('myrun', 'w') as fp:
        fp.write(myrun_content)

    # Step 2
    # It will output some message on the screen like '2350873.nano.cfn.bnl.local'
    output = str(check_output('sbatch myrun', shell=True))

    # Step 3
    # Here we parse job ID from the output of previous command
    jobNumber = int(re.findall(r'\d+', output)[0])
    return jobNumber

if __name__ == '__main__':
    import argparse
    parser = argparse.ArgumentParser()
    parser.add_argument('-i', dest='index', type=int)
    parser.add_argument('-c', dest='commnadExecutable', type=str)
    args = parser.parse_args()
    jobNumber = submitJob_local(index=args.index, commnadExecutable=args.commnadExecutable)
    print('CALLBACK ' + str(jobNumber))
```

--------------------------------

### USPEX Variable Definition: atomType (Atomic Names)

Source: https://uspex-team.org/online_utilities/tmp/uspex_manual_release/EnglishVersion/uspex_manual_english/sect0017

Example of specifying atom types using their element names for USPEX calculations.

```text
% atomType
Mg Si O
% EndAtomType
```

```text
% atomType
Magnesium Silicon Oxygen
% EndAtomType
```
Tokens:
Raw