Description of Input Files - Trebonius91/utils4VASP GitHub Wiki

Here, a short introduction is given to the general contents and layouts of the four main input files that are needed for every VASP calculation (depending on the type of the calculation, other files might be needed as well, see below). These are INCAR (containing keywords), POSCAR (containing the atomic coordinates and unit cell geometry of the system), POTCAR´ (containing the PAW potentials for the description of atomic cores) and KPOINTS` (containing the setup for the integration of recriprocal space). The given files are for an example single point of calculation of a liquid metal surface system with an ethylene molecule adsorbed at the surface, their general structure can however be translated to most other systems. Many of the setups can be eased by the scripts of utils4VASP.

1. INCAR

The keywords for the calculation must be given as upper case identifiers, followed by a space, an equal sign, a space and the value of the variable: WORD = VALUE. It is advisable to add most of the following keywords to each calculation (although there exist default values for most of them, if they are not listed in the INCAR file) and think about their values for the current system. The gen_incar.py script can be used to generate INCAR files for all types of calculations presented in this wiki.

  • SYSTEM = [name] Identifying name for the calculation
  • PREC = Normal Sufficient for molecular dynamics trajectories and most geometry optimizations. For energy or property calculations (DOS, band structure, STM, ...), PREC = Accurate should be used.
  • GGA = PE The usual PBE GGA DFT functional (used for most of our applications)
  • NCORE = [number] Number of CPUs per orbital, should always be a divider of the available number of CPUs per node on which you do the calculation (e.g., the node has 72 cores, NCORE = 18 could be a good choice). For very small systems, strange convergence issues (such as subspace is not hermitian! or no DFT gridpoints available!. This is mostly due to a too large number of CPUs. Decrease the total CPU number (and NCORE) in such a case!
  • ISPIN = 1 or 2 If the calculation shall be done with spin polarization (ISPIN = 2) or without (ISPIN = 1). For systems with magnetic elements (e.g., metal surfaces) or open shell structures (during reaction paths or radicals), spin polarization must be used. If the electronic properties of the current system are now known well, spin polarization should be applied first as a test. If in the standard output mag= 0.0000 appears, the spin polarization is zero and the cheaper ISPIN = 1 mode should be used.
  • MAGMOM = [natoms]*[value] If ISPIN = 2 is set, for each atom, an initial magnetic moment should be given. The format must be written with explicit * sign, where the atoms in the POSCAR must be covered all (e.g.,40*2.0 for 40 atoms). The default value, is the keyword is not given, is always 1.0 for each atom. For more complicated setups, the magnetic moments might be either deduced from chemical knowledge or from literature references.
  • NELM = 300 Maximum number of electronic SCF steps, 300 should be sufficient for most cases (the default value of 60 is sometimes not sufficient for larger or electronically challenging systems).
  • NELMIN = 4 The minimum number of electronic SCF steps; might be raised if geometry optimizations cause problems (which can sometimes be mitigated by this increase), e.g., to 8.
  • ENCUT = [value] The plane wave cutoff in eV. For static calculations, it is sufficient to choose the largest ENMAX value of all elements in the POTCAR file. If cell parameters are relaxed, the ENCUT value should be 25-30% higher. For geometry optimizations of complicated surface adsorbates, it proved be useful as well to raise the ENCUT value, e.g., to 600 eV. For calculation of adsorption energies, all three systems (substrate, adsorbate, adsorbate+substrate) need to have the same ENCUT value!
  • EDIFF = 1E-07 The electronic convergence criterion, energy difference in eV between two cycles. (1E-05 is VASP default, but we are mostly using stricter values)
  • LREAL = Auto Evaluation of projection operators in real or reciprocal space. The given option should be the best for systems with more than approx. 30 atoms. For small systems, LREAL = .FALSE. can be used. VASP will give a warning, if the used scheme is not optimal for the chosen system.
  • ALGO = Fast Which kind of SCF algorithm is used (Davidson or DIIS). For molecular dynamics of many systems, Very Fast (only DIIS) will be enough, in most other cases, Fast (Davidson for the first few SCF cycles, then switching to DIIS) is well suited. If convergence issues Normal (only Davison) often helps, although being slower.
  • ISMEAR The choosen smearing method to enable the integration of electronic bands. The choice of the currect smearing scheme is not trivial, details can be found in the VASP Wiki. Methfessel-Paxton smearing (first order): (ISMEAR = 1) should be used for metallic systems (with or without nonmetallic compounds such as adsorbates into them). Gaussian smearing (ISMEAR = 0) should be used for insulators or molecules or systems with unclear electronic properties. Tetrahedron smearing with Blöchl corrections (ISMEAR = -5) should be used for single point calculations with high accuracy (e.g., for DOS, but not for band structures!). Fermi smearing (ISMEAR = -1) can be used for molecular dynamics trajectories at a certain temperature.
  • SIGMA = [value] Width of the electronic smearing in eV, depends on the smearing method. Methfessel-Paxton: 0.1-0.2; Gaussian: 0.03-0.05; Tetrahedron: no SIGMA needed; Fermi: 0.05-0.7 (depends on the temperature during the MD).
  • IVDW = 12 Grimme D3 dispersion correction, should be turned on for surface-adsorbate interactions etc., essentially no overhead. Note: For adsorption energy calculations, the dispersion correction need to be turned on also for the clean metal surface, even if there is chemically no dispersion relevant! Else, the energy scale is not the same!
  • LWAVE = .FALSE. No wavefunctions written to WAVECAR. Should be the default in order to limit memory pollution. WAVECAR files are needed, e.g., for STM simulations and implicit solvent calculations.
  • LCHARG = .FALSE. No charge densities are written to CHGCAR or CHG. Also default for memory saving, only needed for band structures, Bader charges, STM pictures, charge densities, etc.
  • ISYM = [number] Which kind of symmetry will be used in the calculation. For molecular dynamics simulations, ISYM = -1 should be set in order to explore the full possible configuration space and for frequency calculations to avoid strange errors.

2. POSCAR

In the following, a POSCAR file for a liquid surface + adsorbate system is shown.

  Ethylene on GaxNi
   1.00000000000000
    16.8000000000000007    0.0000000000000000    0.0000000000000000
     0.0000000000000000   16.8000000000000007    0.0000000000000000
     0.0000000000000000    0.0000000000000000   32.0000000000000000
   Ni   Ga   H    C
    1   179     4     2  
Selective
Direct
  0.4401850720183311  0.5238825428341128  0.3521766561531592  T T T
  0.1937295231910164  0.9105475427435126  0.1288196838077396  F F F
  0.9672328401478797  0.0562122444305433  0.0952092871570915  F F F
  0.9877192681027167  0.0507876003911017  0.1908843125036520  F F F
 ....
  0.5432764891825791  0.5384129105162143  0.4704130883460799  T T T
  0.5431780772189526  0.4585775872518857  0.4708784724342397  T T T

The first line is always a comment, which can be chosen arbitrarily.

The second line contains a global scaling factor, which will be automatically applied on the unit cell vectors and cartesian coordinates. It is advisable to keep it always at 1.0, since the coordinates can be read and interpreted much harder with a scaling applied. All scripts in this repository assume a scaling factor of 1.0.

The unit cell coordinate system given in the next three lines defines the periodicity of the system and the shape of its unit cell.

Then, the list of elements follows. Atoms always should be ordered by element. For each symbol, one entry in the POTCAR file is needed (see below). The numbers in the next line indiecate how many atoms of each element in the list are present in the POSCAR file. Here, one Ni atom is followed by 179 Ga atoms, 4 H and 2 atoms.

If selective dynamcs is activated, the keyword Selective must follow in line eight. Withz this, each degree of freedom in the system can either be frozen or movable. Frozen degrees of freedom (a, b or c axis) are indicated with a False flag (F), movable ones with a True flag (T). The flags must then follow the coordinates of each atom, with three flags per atom. If no selective dynamics is desired, simply remove this line completely (or set all flags to T).

The Direct keyword indicates that direct coordinates are used, i.e., the coordinates are expressed as fractions of the unit cell vectors given in lines 3 to 5. The cartesian coordinates can be obtained by multiplying the coordinate vector of each atom by the 3x3 matrix containing the unit cell vector entries as written in the lines 3 to 5. Alternatively, the Cartesian keyword can be given, where all atomic coordinates are expressed in Angstroms in the actual Cartesian Coordinates. The direct coordinates of the atoms can in this case be obtained by multiplying each coordinate vector with the inverse unit cell matrix.

Finally, the coordinates of all atoms follow, where the elements are allocated based on lines 6 and 7. They are either given in Angstroms (Cartesian) or in values between 0 and 1 (Direct). In both cases, the atoms can also move outside the initial unit cell (e.g., during a molecular dynamics trajectory), and reach direct values of 10 or 20 (image flags). In this case, the modify_poscar.py script can be used to wrap the atoms back into the initial unit cell.

For the setup or modification of POSCAR files, several of the scripts and programs presented here can be used: gen_poscar.py, build_adsorb.py, and modify_poscar.py.

3. POTCAR

The POTCAR file contains the precomputed PAW potentials describing the areas near the atomic cores. It is closely connected to the INCAR file, the elements appearing in the sixth line of the POSCAR file must be in the same ordering as in the POTCAR file.

The default method of setting up a POTCAR is to concatenate the POTCAR files of the different elements, which are shipped in a folder with the VASP program package itself. If, for example, the POTCAR folder is located in ~/Software/potcar, a POTCAR file for the system shown in the POSCAR section can be set up as follows:

touch POTCAR
cat ~/Software/potcar/PAW_PBE.52/Ni/POTCAR >> POTCAR
cat ~/Software/potcar/PAW_PBE.52/Ga/POTCAR >> POTCAR
cat ~/Software/potcar/PAW_PBE.52/H/POTCAR >> POTCAR
cat ~/Software/potcar/PAW_PBE.52/C/POTCAR >> POTCAR

The cat command is better than a direct copying (also in the case of just one element), since problems with write-protection etc. of the files can appear. You can use the analyze_poscar.py script to automatically generate a POTCAR file for a given POSCAR file.

For each element, several different POTCAR files can exist! A full list of the POTCAR files can be found in the VASP wiki. For gallium, according to the VASP wiki, there exist three different POTCARs: Ga, Ga_d, Ga_h. The first one (Ga) only contains the outer p electrons, where Ga_d also contains the d-electrons of the shell below. This leads to a larger number of explicit elections (and of bands to calculate) and to a larger cutoff (283 eV instead of 135 eV), since regions nearer to the core with larger fluctuations of the wave function need to be described by the plane waves. In our calculations, we mostly use the variant with the smallest number of electrons.

A once generated POTCAR file can be mostly treated black-box. There are two exceptions:

  • Check the ENMAX values to control that the correct ENCUT is chosen in the INCAR file. The ENCUT must at least be equal to the largest ENMAX value within the whole POTCAR file! If unit cell relaxations are done, the ENCUT value should be 25-30% higher than the largest ENMAX value.
  • Change the POMASS value if different isotopes of an element shall be calculated during a molecular dynamics calculation. If, for example, a machine learning force field for gaseous hydrogen shall be trained, it is useful to change the given POMASS = 1.000 in the 12th line of the H POTCAR file to, e.g., POMASS = 5.000, leading to a mass of 5 u and a slower vibration of the H-H modes.

KPOINTS

The file with information about the reciprocal space integration in periodic lattices. First, one should consider, in which direction the electronic structure of the system is actually periodic. For single molecules in an empty cell, only the Γ point must be sampled. Then, the KPOINTS has the following appearance:

K-Points
0
Gamma
1 1 1
0 0 0

If an adsorbate molecule on a metal surface shall be treated (where the surface usually is parallel to the x-y (or a-b) plane), no explicit consideration of the periodicity in z (or c) direction is needed, leading to, e.g., a 3x3x1 grid:

K-Points
0
Gamma
3 3 1
0 0 0

For most applications, the k-point grid should be centered at the Γ point (keyword Gamma in the third line). The number of k-points in each coordinate should be thoroughly benchmarked if a completely new system is treated (e.g., by comparing energies or band structures of calculations with increasing k-point numbers). In general, the number of k-points per axis is inversely proportional to the length of this axis. If, e.g., the a axis is 20 Å long and the b-axis is only 7 Å long and we are handling with a surface-slab, a good choice might be 2x6x1 k-points. The analyze_poscar.py script can be used to generate a KPOINTS file for a given POSCAR.