4. Typical use cases

4.1. Crystal structure prediction (3D): fixed-composition

4.1.1. Highlights

This is the simplest in terms of input use case. Here we describe all its input blocks.

type : GlobalOptimizer

It tells program that we want to look for global optimum in some space. The alternative would be an optimization of some single entity, for example a phase transition pathway in the case of VCNEB calculation (it is not yet implemented in USPEX-2022.1).

target: {
   type : Atomistic
   conditions: {externalPressure: 100}
   compositionSpace: {
      symbols: [Mg Al O]
      blocks: [[4 8 16]]
   }
}

This block is specific for global optimization. Here you specify type of the space you want to investigate and its parameters. In this example type is Atomistic, which covers all systems composed from atoms: crystals (including molecular ones), surfaces, thin films, grain boundaries, polymers, nanoparticles. The alternative types cover chemical composition in case of Mendeleev search, transition pathway in case of phase transition global optimization, and so on. These regimes are not yet transferred to the Python version of USPEX.

The main property of the search space in any Atomistic calculation is compositionSpace. In this example it is a space of fixed-composition, non-molecular \(\text{Mg}_4\text{Al}_8\text{O}_{16}\) structures.

The other property set for target space in the example is conditions.externalPressure. It has two effects: it is used in estimating the initial structure volume (useful for relaxation), and it is then used for structure relaxation. In the example conditions.externalPressure is set to 100 GPa.

optType: enthalpy

This parameter is also specific for global optimization. It tells program which property we want to optimize.

selection: {
   type: USPEXClassic
   popSize: 50
   optType: (aging enthalpy)
   fractions: {
      heredity: (0.1 1.0 0.5)
      softModeMutation: (0.1 1.0 0.2)
      permutation: (0.5 1.0 0.1)
      randSym: (0.05 1.0 0.1)
      randTop: (0.05 1.0 0.1)
   }
}

This block, specific for global optimization, determines the optimization algorithm and its parameters. In the example the USPEXClassic algorithm is used, which is the evolutionary algorithm. Other algorithms: PSO and Metadynamics from USPEX-10 series are not reimplemented at the moment. Parameter popSize defines the number of individuals in each generation. Parameter optType in this section governs parents selection. It could be skipped, in which case the optType from optimizer section will be used. But often you would like to apply additional adjustments to how parents are chosen. In this case aging procedure (also known as antiseeds method) is applied. In this method all structures which have already been visited will be penalized by an extra energy term each time they appear again.

The fractions block here governs variation operators fractions in generations. Each variation operator have three parameters: minimum fraction. maximum fraction and initial weight. Program will ensure (or at least try to) that in each population the fraction of structures created with certain operator will be in range between its minimum and maximum values. The initial weights describes from which value the operator starts in the search. The weights not necessarily add up to one.

numGenerations: 50
stopCrit: 28

This two parameters are generic for all USPEX regimes. They defines total number of generation to be processed and the main halting criteria. Which is the number of generations during which optimization did not found any better solution. For example if the calculation found new global optimum on 3rd generation and then until 23rd it did not found new global optimum, it will be stopped.

stages: [glp glp glp glp glp]
numParallelCalcs: 10

#define glp
{type : gulp commandExecutable : 'gulp'}

Here you define how you do ab initio (or classical) calculations of your structures. In this example, you use GULP for relaxing structures in 5 stages. And you do 10 relaxations in parallel.

4.1.2. Example

{
   optimizer: {
      type : GlobalOptimizer
      target: {
         type : Atomistic
         conditions: {externalPressure: 100}
         compositionSpace: {
               symbols: [Mg Al O]
               blocks: [[4 8 16]]
         }
      }
      optType: enthalpy
      selection: {
         type: USPEXClassic
         popSize: 50
         optType: (aging enthalpy)
         fractions: {
            heredity: (0.1 1.0 0.5)
            softModeMutation: (0.1 1.0 0.2)
            permutation: (0.5 1.0 0.1)
            randSym: (0.05 1.0 0.1)
            randTop: (0.05 1.0 0.1)
         }
      }
   }
   numGenerations: 50
   stopCrit: 28
   stages: [glp glp glp glp glp]
   numParallelCalcs: 10
}

#define glp
{type : gulp commandExecutable : 'gulp'}

4.1.3. Checklist

To predict crystal structure for a certain composition, you need to:

  • Specify optimizer.type: GlobalOptimizer, optimizer.target.type: Atomistic and optimizer.selection.type: USPEXClassic.

  • Specify composition in optimizer.target.compositionSpace block. For a fixed composition only symbols and blocks required there. See Section 5.5.1 for details.

  • Optionally specify optimizer.target.ionDistances and optimizer.target.conditions. See Section 5.5 and Section 5.5.6 for details.

  • Optionally specify optimizer.target.cellUtility.cellVectors or optimizer.target.cellUtility.cellParameters if you want to run calculation in fixed cell. See Section 5.5.2 for details.

  • Specify feature to be optimized in optimizer.optType (fitness). See Section 5.4 for details.

  • Additionally and optionally specify optimizer.selection.optType. This feature if specified will be used in selection procedure instead of optimizer.optType. Usually you will want to specify here the same quality as in optimizer.optType but with aging procedure involved. In case of single parameter optimization this is trivial, but if yo do pareto optimization you will have choice what features should be aged. See Section 5.4 for details.

  • Specify population size in optimizer.selection.popSize and optionally initial population size in optimizer.selection.initialPopSize. See Section 5.6 for details.

  • Assign fraction ranges to the variation operators to be used in the calculation in optimizer.selection.fractions. See Section 5.6 for details.

  • Define all needed ab initio calculation sections and use them in stages. See Section 5.7 for details.

  • Specify numParallelCalcs, numGenerations and stopCrit parameters. See Section 5.2 for details.

4.2. Crystal structure prediction (3D): variable-composition

4.2.1. Highlights

Most of input is the same as in previous case. Here we draw your attention to differences.

compositionSpace: {
   symbols: [Mg Al O]
   blocks: [[1 0 1] [0 2 3]]
   minAt: 30 maxAt 42
}

The first major difference is in definition of composition space. Now we have \(\text{MgO}-\text{Al}_2\text{O}_3\) variable-composition system and we reflect it in the blocks parameter. Additionally we set up minimum and maximum number of atoms in structure.

optType: enthalpyCCH

The second major difference is the property to be optimized. Unlike in fixed-composition case we need a property which can be meaningfully compared for systems with different number of atoms. This is the enthalpyCCH or height above enthalpy derived composition convex hull.

popSize: 80
initPopSize: 200
optType: (aging enthalpyCCH)

The same transition form enthalpy to enthalpyCCH should be done in selection section. Also in this section we provide initPopSize besides usual popSize. This parameter allows to set up size of initial generation different from size of all subsequent.

4.2.2. Example

{
   optimizer: {
      type : GlobalOptimizer
      target: {
         type : Atomistic
         compositionSpace: {
            symbols: [Mg Al O]
            blocks: [[1 0 1] [0 2 3]]
            minAt: 30 maxAt 42
         }
      }
      optType: enthalpyCCH
      selection: {
         type: USPEXClassic
         popSize: 80
         initPopSize: 200
         optType: (aging enthalpyCCH)
         fractions: {
            heredity: (0.1 1.0 0.5)
            softModeMutation: (0.1 1.0 0.2)
            transmutation: (0.5 1.0 0.1)
            randSym: (0.05 1.0 0.1)
            randTop: (0.05 1.0 0.1)
         }
      }
   }
   stages: [glp glp glp]
   numParallelCalcs: 10
   numGenerations: 60
   stopCrit: 20
}

#define glp
{type : gulp commandExecutable : 'gulp'}

4.2.3. Checklist

To predict crystal structure with for a known constituent elements, you need to:

  • Specify optimizer.type: GlobalOptimizer, optimizer.target.type: Atomistic and optimizer.selection.type: USPEXClassic.

  • Specify composition in optimizer.target.compositionSpace block. Besides symbols and blocks either minAt, maxAt or range required there. See Section 5.5.1 for details.

  • Optionally specify optimizer.target.ionDistances and optimizer.target.conditions. See Section 5.5 and Section 5.5.6 for details.

  • Specify feature to be optimized in optimizer.optType (fitness). Be sure to provide here intensive property. If you want to do stable structures prediction it should be enthalpyCCH (height above enthalpy derived composition convex hull) rather than enthalpy. See Section 5.4 for details.

  • Additionally and optionally specify optimizer.selection.optType. This feature if specified will be used in selection procedure instead of optimizer.optType. Usually you will want to specify here the same quality as in optimizer.optType but with aging procedure involved. In case of single parameter optimization this is trivial, but if yo do pareto optimization you will have choice what features should be aged. See Section 5.4 for details.

  • Specify population size in optimizer.selection.popSize and optionally initial population size in optimizer.selection.initialPopSize. See Section 5.6 for details.

  • Assign fraction ranges to the variation operators to be used in the calculation in optimizer.selection.fractions. See Section 5.6 for details.

  • Define all needed ab initio calculation sections and use them in stages. See Section 5.7 for details.

  • Specify numParallelCalcs, numGenerations and stopCrit parameters. See Section 5.2 fro details.

4.3. Crystal structure prediction (3D): molecular crystals

4.3.1. Highlights

Here we highlight differences from previous cases.

compositionSpace: {symbols: [mol_h2o] blocks: [[4]]}

#define mol_h2o
{filename: 'MOL_H2O'}

When we do molecular crystal optimization we provide molecules rather then pure atoms as building units. To do so we define molecules in our definition sections and use introduced molecule names in compositionSpace instead of element symbols.

4.3.2. Example

{
   optimizer : {
      type : GlobalOptimizer
      target: {
         type: Atomistic
         compositionSpace: {symbols: [mol_h2o] blocks: [[4]]}
      }
      optType: enthalpy
      selection: {
         type: USPEXClassic
         popSize: 50
         optType: (aging enthalpy)
         fractions: {
            heredity: (0.1 1.0 0.5)
            softmodemutation: (0.1 1.0 0.3)
            randSym: (0.1 1.0 0.1)
            randTop: (0.1 1.0 0.1)
         }
      }
   }
   stages : [glp glp]
   numParallelCalcs : 10
   numGenerations : 50
   stopCrit: 10
}

#define glp
{
   type : gulp
   commandExecutable : gulp
   libs : ['./Specific/dreiding.lib']
}

#define mol_h2o
{filename: 'MOL_H2O'}

4.3.3. Checklist

To predict crystal structure for a certain composition, you need to:

  • Specify optimizer.type: GlobalOptimizer, optimizer.target.type: Atomistic and optimizer.selection.type: USPEXClassic.

  • Define molecules in corresponding sections. Provide files describing molecules. See Section 5.9 for details.

  • Specify composition in optimizer.target.compositionSpace block using molecule names from previous step. See Section 5.5.1 for details.

  • Optionally specify optimizer.target.ionDistances and optimizer.target.conditions. See Section 5.5 and Section 5.5.6 for details.

  • Optionally specify optimizer.target.cellUtility.cellVectors or optimizer.target.cellUtility.cellParameters if you want to run calculation in fixed cell. See Section 5.5.2 for details.

  • Specify feature to be optimized in optimizer.optType (fitness). See Section 5.4 for details.

  • Additionally and optionally specify optimizer.selection.optType. This feature if specified will be used in selection procedure instead of optimizer.optType. Usually you will want to specify here the same quality as in optimizer.optType but with aging procedure involved. In case of single parameter optimization this is trivial, but if yo do pareto optimization you will have choice what features should be aged. See Section 5.4 for details.

  • Specify population size in optimizer.selection.popSize and optionally initial population size in optimizer.selection.initialPopSize. See Section 5.6 for details.

  • Assign fraction ranges to the variation operators to be used in the calculation in optimizer.selection.fractions. See Section 5.6 for details.

  • Define all needed ab initio calculation sections and use them in stages. See Section 5.7 for details.

  • Specify numParallelCalcs, numGenerations and stopCrit parameters. See Section 5.2 fro details.

4.4. Thin films (2D)

4.4.1. Highlights

Here we highlight differences from previous cases.

cellUtility: {dim : 2 thickness: 5.0}

The code block determining dimensionality is cellUtility. To switch 2D regime you need to set cellUtility.dim to 2. The other property required for thin film prediction is the thickness of the film cellUtility.thickness.

radialDistributionUtility: {tolerance: 0.0002}

Our algorithm for determining individual duplicates is clibrated for 3D systems. For it to working properly for lesser dimensional systems, you need to adjust tolerance. We developing new approach to tackle this problem so users will no need to specify it in future.

randSymPyXtal: (0.1 1.0 0.2)

For lesser dimensional structures we use randSymPyxXtal random structure generator instead of RandSym and RandTop.

stages: [glp10 glp15]

#define glp10
{type : gulp commandExecutable : 'gulp' vacuumSize: 10}

#define glp15
{type : gulp commandExecutable : 'gulp' vacuumSize: 15}

This will tell program to use different vaccume sizes for different stages of relaxation. The vacuum layer is necessary as we emulate uperiodicity by dividing structure layers with vacuum.

4.4.2. Example

{
   optimizer: {
      type: GlobalOptimizer
      target: {
         type: Atomistic
         conditions: {externalPressure: 0.0}
         compositionSpace: {symbols: [Mg O] blocks: [[16 16]]}
         cellUtility: {dim : 2 thickness: 5.0}
         radialDistributionUtility: {tolerance: 0.0002}
      }
      optType: enthalpy
      selection: {
         type: USPEXClassic
         popSize: 30
         initialPopSize: 40
         optType: (aging enthalpy)
         fractions: {
            heredity: (0.3 0.7 0.5)
            softmodemutation: (0.1 0.5 0.2)
            permutation: (0.1 0.5 0.1)
            randSymPyXtal: (0.1 1.0 0.2)
         }
      }
   }
   stages: [glp10 glp15]
   numParallelCalcs: 10
   numGenerations: 30
   stopCrit: 15
}

#define glp10
{type : gulp commandExecutable : 'gulp' vacuumSize: 10}

#define glp15
{type : gulp commandExecutable : 'gulp' vacuumSize: 15}

4.4.3. Checklist

To predict film (2D crystal) structure, you need to:

  • Specify optimizer.type: GlobalOptimizer, optimizer.target.type: Atomistic and optimizer.selection.type: USPEXClassic.

  • Specify composition in optimizer.target.compositionSpace block. See Section 5.5.1 for details.

  • Optionally specify optimizer.target.ionDistances and optimizer.target.conditions. See Section 5.5 and Section 5.5.6 for details.

  • Specify cellUtility.dim: 2.

  • Specify film thickness in cellUtility.thickness.

  • Optionally specify optimizer.target.cellUtility.cellVectors or optimizer.target.cellUtility.cellParameters if you want to run calculation in fixed cell. See Section 5.5.2 for details.

  • Specify feature to be optimized in optimizer.optType (fitness). For variable-composition calculation provide an intensive property (enthalpyCCH instead of enthalpy). See Section 5.4 for details.

  • Additionally and optionally specify optimizer.selection.optType. This feature if specified will be used in selection procedure instead of optimizer.optType. Usually you will want to specify here the same quality as in optimizer.optType but with aging procedure involved. In case of single parameter optimization this is trivial, but if yo do pareto optimization you will have choice what features should be aged. See Section 5.4 for details.

  • Specify population size in optimizer.selection.popSize and optionally initial population size in optimizer.selection.initialPopSize. See Section 5.6 for details.

  • Assign fraction ranges to the variation operators to be used in the calculation in optimizer.selection.fractions. See Section 5.6 for details.

  • Define all needed ab initio calculation sections and use them in stages. Do not forget to specify vacuumSize which should be sufficiently large to prevent interaction between periodic images of slabs. See Section 5.7 for details.

  • Specify numParallelCalcs, numGenerations and stopCrit parameters. See Section 5.2 fro details.

4.5. Surface reconstructions (2D): fixed-composition

Variable-composition calculation is possible but input is messy right now. It will be documented in the nex release.

4.5.1. Highlights

Here we highlight differences from previous cases.

cellUtility: {
   dim : 2
   thickness: 5.0
   supercellDegree: 4
}

Here we tell program that we want 2D cells constructed from 4 tiles.

environmentUtility: {environments: [substrate]}

#define substrate
{
   type: substrate
   file: './POSCAR_SUBSTRATE'
   pbc: (1 1 0)
   bufferThickness: 3.0
}

Here we set up substrate. The structure is read from file ‘./POSCAR_SUBSTRATE’. It has buffer layer of size 3.0Å.

4.5.2. Example

{
   optimizer: {
      type: GlobalOptimizer
      target: {
         type: Atomistic
         conditions: {externalPressure: 0.0}
         compositionSpace: {symbols: [Mg O] blocks: [[16 16]]}
         cellUtility: {
            dim : 2
            thickness: 5.0
            supercellDegree: 4
         }
         radialDistributionUtility: {tolerance: 0.0002}
         environmentUtility: {environments: [substrate]}
      }
      optType: enthalpy
      selection: {
         type: USPEXClassic
         popSize: 30
         initialPopSize: 40
         optType: (aging enthalpy)
         fractions: {
            heredity: (0.3 0.7 0.5)
            softmodemutation: (0.1 0.5 0.2)
            permutation: (0.1 0.5 0.1)
            randSymPyXtal: (0.1 1.0 0.2)
         }
      }
   }
   stages: [glp10 glp15]
   numParallelCalcs: 10
   numGenerations: 30
   stopCrit: 15
}


 #define glp10
 {type : gulp commandExecutable : 'gulp' vacuumSize: 10}

 #define glp15
 {type : gulp commandExecutable : 'gulp' vacuumSize: 15}

 #define substrate
 {
    type: substrate
    file: './POSCAR_SUBSTRATE'
    pbc: (1 1 0)
    bufferThickness: 3.0
 }

4.5.3. Checklist

To predict surface reconstructions, you need to:

  • Specify optimizer.type: GlobalOptimizer, optimizer.target.type: Atomistic and optimizer.selection.type: USPEXClassic.

  • Specify composition in optimizer.target.compositionSpace block. See Section 5.5.1 for details.

  • Optionally specify optimizer.target.ionDistances and optimizer.target.conditions. See Section 5.5 and Section 5.5.6 for details.

  • Specify cellUtility.dim: 2.

  • Specify surface region thickness in cellUtility.thickness.

  • Specify feature to be optimized in optimizer.optType (fitness). For variable-composition calculation provide intensive property (enthalpyCCH instead of enthalpy). See Section 5.4 for details.

  • Additionally and optionally specify optimizer.selection.optType. This feature if specified will be used in selection procedure instead of optimizer.optType. Usually you will want to specify here the same quality as in optimizer.optType but with aging procedure involved. In case of single parameter optimization this is trivial, but if yo do pareto optimization you will have choice what features should be aged. See Section 5.4 for details.

  • Specify population size in optimizer.selection.popSize and optionally initial population size in optimizer.selection.initialPopSize. See Section 5.6 for details.

  • Assign fraction ranges to the variation operators to be used in the calculation in optimizer.selection.fractions. See Section 5.6 for details.

  • Define all needed ab initio calculation sections and use them in stages. Do not forget to specify vacuumSize which should be sufficiently large to prevent interaction between periodic images of slabs. See Section 5.7 for details.

  • Define substrate in corresponding section and use it in optimizer.target.environmentUtility.environments. Provide a file containing substrate in VASP5 POSCAR format, specify pbc and bufferThickness. The file can be constructed using online utility: Substrate.

  • Specify numParallelCalcs, numGenerations and stopCrit parameters. See Section 5.2 fro details.

4.6. Nanoparticles prediction (0D)

4.6.1. Highlights

Here we highlight differences from previous cases.

cellUtility: {dim : 0}

The dimension of the problem here is 0.

4.6.2. Example

{
   optimizer: {
      type: GlobalOptimizer
      target: {
         type: Atomistic
         conditions: {externalPressure: 0.0}
         compositionSpace: {symbols: [Mo] blocks: [[36]]}
         cellUtility: {dim : 0}
      }
      optType: enthalpy
      selection: {
         type: USPEXClassic
         popSize: 40
         optType: (aging enthalpy)
         fractions: {
            heredity: (0.3 0.7 0.5)
            softmodemutation: (0.1 0.5 0.3)
            randSymPyXtal: (0.1 1.0 0.2)
         }
      }
   }
   stages: [glp10 glp11 glp12]
   numParallelCalcs: 20
   numGenerations: 60
   stopCrit: 20
}

#define glp10
{type : gulp commandExecutable : 'gulp' vacuumSize: 10}

#define glp11
{type : gulp commandExecutable : 'gulp' vacuumSize: 11}

#define glp12
{type : gulp commandExecutable : 'gulp' vacuumSize: 12}

4.6.3. Checklist

To predict structure of nanoparticles (clusters), you need to:

  • Specify optimizer.type: GlobalOptimizer, optimizer.target.type: Atomistic and optimizer.selection.type: USPEXClassic.

  • Specify composition in optimizer.target.compositionSpace block. See Section 5.5.1 for details.

  • Optionally specify optimizer.target.ionDistances. See Section 5.5 for details.

  • Specify cellUtility.dim: 0.

  • Specify feature to be optimized in optimizer.optType (fitness). See Section 5.4 for details.

  • Additionally and optionally specify optimizer.selection.optType. This feature if specified will be used in selection procedure instead of optimizer.optType. Usually you will want to specify here the same quality as in optimizer.optType but with aging procedure involved. In case of single parameter optimization this is trivial, but if yo do pareto optimization you will have choice what features should be aged. See Section 5.4 for details.

  • Specify population size in optimizer.selection.popSize and optionally initial population size in optimizer.selection.initialPopSize. See Section 5.6 for details.

  • Assign fraction ranges to the variation operators to be used in the calculation in optimizer.selection.fractions. See Section 5.6 for details.

  • Define all needed ab initio calculation sections and use them in stages. Do not forget to specify vacuumSize which should be sufficiently large to prevent interaction between periodic images of slabs. See Section 5.7 for details.

  • Specify numParallelCalcs, numGenerations and stopCrit parameters. See Section 5.2 fro details.