KPOINTS (`cusp.kpoints`)¶

Using the VaspKpointData the KPOINT parameters of a calculation can be passed to the VASP calculation object. This data class is published by the plugin using the cusp.kpoints entry point and can be loaded via AiiDA’s DataFactory() function. To simplify the setup of different k-point grids (i.e. Monkhorst, Gamma, Automatic, etc.), the class is closely connected to Pymatgen’s Kpoints class supporting multiple initialization modes. Which of the implemented initialization mode is used to generate the k-point data is decided by the plugin based on the type and set of parameters passed to the constructor (see the following section)

Initializing the class¶

In general the constructor of the VaspKpointData class accepts k-point settings (defining the k-point grid) and an optional structure input required for density based on k-point grid definition:

VaspKpointData(kpoints=None, structure=None)

Arguments:

kpoints (dict or pymatgen.io.vasp.inputs.Kpoints) – The KPOINT parameters used to run a VASP calculation. May be given as pymatgen.io.vasp.inputs.Kpoints object which is useful if k-points parameters defined by a pymatgen set should be used. Alternatively (i.e. no pre-defined pymatgen set should be used) the desired k-point grid may also be set using a parameter dict. In that case the grid is generated using the class-internal methods depending on the type of parameters passed by the dict (See the following section for more details on the possible parameters and corresponding generation modes) kpoint parameters
structure (optional, pymatgen.core.structure.Structure, pymatgen.io.vasp.inputs.Poscar or aiida.orm.StructureData) – Optional structure input for initialization modes that are based on a k-point density. This is only required if the KPOINT grid is initialized using the internal methods based on a passed kpoint density. (See the initialization modes discussed in the following section for more details)

Available initialization modes and their corresponding parameters¶

Passing a parameters dictionary to the VaspKpointData the passed dictionary may only contain the following keys:

mode (str) – The initialization mode to be used for the KPOINT generation. In general the VaspKpointData class supports the four distinct initialization modes: auto, monkhorst, gamma and line
kpoints (int, float or list) – Defining the actual KPOINT grid

Note

The expected type passed for the kpoints depends on the initialization mode defined by the mode key.
shift (list) – Shift the kpoint grid by the defined amount
sympath (HighSymmKpath) – Path along high symmetry lines used in band structure calculations (i.e. only required if mode is set to line)

In the following the different initialization modes and expected parameters are discussed in more detail.

Mode: auto¶

Setting the mode to auto the KPOINT grid initialized automatically using a single integer. This corresponds to setting Auto in the KPOINT file. In this mode the expected input parameters passed in the input dictionary are:

mode (str) – auto
kpoints (int) – Integer used to automatically determine the grid’s subdivisions
shift (None) – Unused by this mode
sympath (None) – Unused by this mode

Example:

>>> auto_mode_params = {
...    'mode': 'auto',
...    'kpoints': 100,
... }
>>> kpoints = VaspKpointData(kpoints=auto_mode_params)
>>> print(kpoints.get_kpoints())
Fully automatic kpoint scheme
0
Automatic
100

Mode: monkhorst¶

Setting the mode to monkhorst calls the internal KPOINT grid initialization for Monkhorst grids. In this mode the expected input parameters passed in the input dictionary are:

mode (str) – monkhorst
kpoints (list or float) – Explicit 3x1 list of int defining the grid’s subdivisions or a kpoint density of type:class:float

Note

In case the kpoint grid is initialized from density the structure has to be passed to the constructor as well. However, the structure is not required for the initialization using an explicit kpoint grid.
shift (list) – 3x1 list of float defining the kpoint grid shift applied to the grid

Note

If the grid is initialized from a density (i.e. kpoints is of type float) any defined shift is ignored.
sympath (None) – Unused by this mode

Example for explicit kpoint grid:

>>> monkhorst_mode_params = {
...    'mode': 'monkhorst',
...    'kpoints': [2, 2, 2],
... }
>>> kpoints = VaspKpointData(kpoints=monkhorst_mode_params)
>>> print(kpoints.get_kpoints())
Automatic kpoint scheme
0
Monkhorst
2 2 2

Example for kpoint density

>>> from pymatgen import Structure, Lattice
>>> lattice = Lattice.cubic(1.0)
>>> structure = Structure(lattice, ['H'], [[.0, .0, .0]])
>>> monkhorst_mode_params = {
...    'mode': 'monkhorst',
...    'kpoints': 10.0,
... }
>>> kpoints = VaspKpointData(kpoints=monkhorst_mode_params, structure=structure)
>>> print(kpoints.get_kpoints())
pymatgen v2020.4.29 with grid density = 10 / atom
0
Monkhorst
2 2 2

Mode: gamma¶

Setting the mode to gamma calls the internal KPOINT grid initialization for Gamma grids. This initialization is basically equivalent to the previously discussed Monkhorst initialization mode but generates a Gamma grid In this mode the expected input parameters passed in the input dictionary are:

mode (str) – gamma
kpoints (list or float) – Explicit 3x1 list of int defining the grid’s subdivisions or a kpoint density of type:class:float

Note

In case the kpoint grid is initialized from density the structure has to be passed to the constructor as well. However, the structure is not required for the initialization using an explicit kpoint grid.
shift (list) – 3x1 list of float defining the kpoint grid shift applied to the grid

Note

If the grid is initialized from a density (i.e. kpoints is of type float) any defined shift is ignored.
sympath (None) – Unused by this mode

Example for explicit kpoint grid:

>>> gamma_mode_params = {
...    'mode': 'gamma',
...    'kpoints': [2, 2, 2],
... }
>>> kpoints = VaspKpointData(kpoints=gamma_mode_params)
>>> print(kpoints.get_kpoints())
Automatic kpoint scheme
0
Gamma
2 2 2

Example for kpoint density

>>> from pymatgen import Structure, Lattice
>>> lattice = Lattice.cubic(1.0)
>>> structure = Structure(lattice, ['H'], [[.0, .0, .0]])
>>> gamma_mode_params = {
...    'mode': 'gamma',
...    'kpoints': 10.0,
... }
>>> kpoints = VaspKpointData(kpoints=gamma_mode_params, structure=structure)
>>> print(kpoints.get_kpoints())
pymatgen v2020.4.29 with grid density = 10 / atom
0
Gamma
2 2 2

Mode: line¶

Kpoint grids for bandstructure calculations can be generated by setting the mode to line Using line mode the expected input parameters passed in the input dictionary are:

mode (str) – line
kpoints (int) – Integer value defining the number of kpoints for each path segment
shift (None) – Unused by this mode
sympath (HighSymmKpath) – HighSymmKpath object defining a path along high symmetry lines in the Brillouin zone