aiida.tools.data.array.kpoints package#

Various utilities to deal with KpointsData instances or create new ones (e.g. band paths, kpoints from a parsed input text file, …)

Submodules#

Tool to automatically determine k-points for a given structure using legacy custom implementation.

aiida.tools.data.array.kpoints.legacy.analyze_cell(cell=None, pbc=None)[源代码]#

A function executed by the __init__ or by set_cell. If a cell is set, properties like a1, a2, a3, cosalpha, reciprocal_cell are set as well, although they are not stored in the DB. :note: units are Angstrom for the cell parameters, 1/Angstrom for the reciprocal cell parameters.

aiida.tools.data.array.kpoints.legacy.change_reference(reciprocal_cell, kpoints, to_cartesian=True)[源代码]#

Change reference system, from cartesian to crystal coordinates (units of b1,b2,b3) or viceversa.

参数:
  • reciprocal_cell – a 3x3 array representing the cell lattice vectors in reciprocal space

  • kpoints – a list of (3) point coordinates

Return kpoints:

a list of (3) point coordinates in the new reference

aiida.tools.data.array.kpoints.legacy.find_bravais_info(cell, pbc, epsilon_length=1e-05, epsilon_angle=1e-05)[源代码]#

Finds the Bravais lattice of the cell passed in input to the Kpoint class :note: We assume that the cell given by the cell property is the primitive unit cell.

备注

in 3D, this implementation expects that the structure is already standardized according to the Setyawan paper. If this is not the case, the kpoints and band structure returned will be incorrect. The only case that is dealt correctly by the library is the case when axes are swapped, where the library correctly takes this swapping/rotation into account to assign kpoint labels and coordinates.

参数:
  • cell – 3x3 array representing the structure cell lattice vectors

  • pbc – 3-dimensional array of booleans signifying the periodic boundary conditions along each lattice vector passed in value as cartesian coordinates. Default: False.

  • epsilon_length (float) – threshold on lengths comparison, used to get the bravais lattice info. It has to be used if the user wants to be sure the right symmetries are recognized.

  • epsilon_angle (float) – threshold on angles comparison, used to get the bravais lattice info. It has to be used if the user wants to be sure the right symmetries are recognized.

返回:

a dictionary, with keys short_name, extended_name, index (index of the Bravais lattice), and sometimes variation (name of the variation of the Bravais lattice) and extra (a dictionary with extra parameters used by the get_kpoints_path method)

aiida.tools.data.array.kpoints.legacy.get_explicit_kpoints_path(value=None, cell=None, pbc=None, kpoint_distance=None, cartesian=False, epsilon_length=1e-05, epsilon_angle=1e-05)[源代码]#

Set a path of kpoints in the Brillouin zone.

参数:
  • value

    description of the path, in various possible formats.

    None: automatically sets all irreducible high symmetry paths. Requires that a cell was set

    or:

    [('G','M'), (...), ...]
    [('G','M',30), (...), ...]
    [('G',(0,0,0),'M',(1,1,1)), (...), ...]
    [('G',(0,0,0),'M',(1,1,1),30), (...), ...]
    

  • cell – 3x3 array representing the structure cell lattice vectors

  • pbc – 3-dimensional array of booleans signifying the periodic boundary conditions along each lattice vector

  • kpoint_distance (float) – parameter controlling the distance between kpoints. Distance is given in crystal coordinates, i.e. the distance is computed in the space of b1,b2,b3. The distance set will be the closest possible to this value, compatible with the requirement of putting equispaced points between two special points (since extrema are included).

  • cartesian (bool) – if set to true, reads the coordinates eventually passed in value as cartesian coordinates. Default: False.

  • epsilon_length (float) – threshold on lengths comparison, used to get the bravais lattice info. It has to be used if the user wants to be sure the right symmetries are recognized.

  • epsilon_angle (float) – threshold on angles comparison, used to get the bravais lattice info. It has to be used if the user wants to be sure the right symmetries are recognized.

返回:

point_coordinates, path, bravais_info, explicit_kpoints, labels

aiida.tools.data.array.kpoints.legacy.get_kpoints_path(cell, pbc=None, cartesian=False, epsilon_length=1e-05, epsilon_angle=1e-05)[源代码]#

Get the special point and path of a given structure.

备注

in 3D, this implementation expects that the structure is already standardized according to the Setyawan paper. If this is not the case, the kpoints and band structure returned will be incorrect. The only case that is dealt correctly by the library is the case when axes are swapped, where the library correctly takes this swapping/rotation into account to assign kpoint labels and coordinates.

  • In 2D, coordinates are based on the paper: R. Ramirez and M. C. Bohm, Int. J. Quant. Chem., XXX, pp. 391-411 (1986)

  • In 3D, coordinates are based on the paper: W. Setyawan, S. Curtarolo, Comp. Mat. Sci. 49, 299 (2010)

参数:
  • cell – 3x3 array representing the structure cell lattice vectors

  • pbc – 3-dimensional array of booleans signifying the periodic boundary conditions along each lattice vector

  • cartesian – If true, returns points in cartesian coordinates. Crystal coordinates otherwise. Default=False

  • epsilon_length – threshold on lengths comparison, used to get the bravais lattice info

  • epsilon_angle – threshold on angles comparison, used to get the bravais lattice info

Return special_points,path:

special_points: a dictionary of point_name:point_coords key,values.

path: the suggested path which goes through all high symmetry lines. A list of lists for all path segments. e.g. [('G','X'),('X','M'),...] It’s not necessarily a continuous line.

Note:

We assume that the cell given by the cell property is the primitive unit cell

Various utilities to deal with KpointsData instances or create new ones (e.g. band paths, kpoints from a parsed input text file, …)

aiida.tools.data.array.kpoints.main._legacy_get_explicit_kpoints_path(structure, **kwargs)[源代码]#

Call the get_explicit_kpoints_path of the legacy implementation

参数:
  • structure – a StructureData node

  • kpoint_distance (float) – parameter controlling the distance between kpoints. Distance is given in crystal coordinates, i.e. the distance is computed in the space of b1, b2, b3. The distance set will be the closest possible to this value, compatible with the requirement of putting equispaced points between two special points (since extrema are included).

  • cartesian (bool) – if set to true, reads the coordinates eventually passed in value as cartesian coordinates

  • epsilon_length (float) – threshold on lengths comparison, used to get the bravais lattice info

  • epsilon_angle (float) – threshold on angles comparison, used to get the bravais lattice info

aiida.tools.data.array.kpoints.main._legacy_get_kpoints_path(structure, **kwargs)[源代码]#

Call the get_kpoints_path of the legacy implementation

参数:
  • structure – a StructureData node

  • cartesian (bool) – if set to true, reads the coordinates eventually passed in value as cartesian coordinates

  • epsilon_length – threshold on lengths comparison, used to get the bravais lattice info

  • epsilon_angle – threshold on angles comparison, used to get the bravais lattice info

aiida.tools.data.array.kpoints.main._seekpath_get_explicit_kpoints_path(structure, **kwargs)[源代码]#

Call the get_explicit_kpoints_path wrapper function for Seekpath

参数:
  • structure – a StructureData node

  • with_time_reversal – if False, and the group has no inversion symmetry, additional lines are returned

  • reference_distance – a reference target distance between neighboring k-points in the path, in units of 1/ang. The actual value will be as close as possible to this value, to have an integer number of points in each path

  • recipe

    choose the reference publication that defines the special points and paths. Currently, the following value is implemented:

    • hpkot: HPKOT paper: Y. Hinuma, G. Pizzi, Y. Kumagai, F. Oba, I. Tanaka, Band structure diagram paths based on crystallography, Comp. Mat. Sci. 128, 140 (2017). DOI: 10.1016/j.commatsci.2016.10.015

  • threshold – the threshold to use to verify if we are in and edge case (e.g., a tetragonal cell, but a==c). For instance, in the tI lattice, if abs(a-c) < threshold, a EdgeCaseWarning is issued. Note that depending on the bravais lattice, the meaning of the threshold is different (angle, length, …)

  • symprec – the symmetry precision used internally by SPGLIB

  • angle_tolerance – the angle_tolerance used internally by SPGLIB

aiida.tools.data.array.kpoints.main._seekpath_get_kpoints_path(structure, **kwargs)[源代码]#

Call the get_kpoints_path wrapper function for Seekpath

参数:
  • structure – a StructureData node

  • with_time_reversal – if False, and the group has no inversion symmetry, additional lines are returned

  • recipe

    choose the reference publication that defines the special points and paths. Currently, the following value is implemented:

    • hpkot: HPKOT paper: Y. Hinuma, G. Pizzi, Y. Kumagai, F. Oba, I. Tanaka, Band structure diagram paths based on crystallography, Comp. Mat. Sci. 128, 140 (2017). DOI: 10.1016/j.commatsci.2016.10.015

  • threshold – the threshold to use to verify if we are in and edge case (e.g., a tetragonal cell, but a==c). For instance, in the tI lattice, if abs(a-c) < threshold, a EdgeCaseWarning is issued. Note that depending on the bravais lattice, the meaning of the threshold is different (angle, length, …)

  • symprec – the symmetry precision used internally by SPGLIB

  • angle_tolerance – the angle_tolerance used internally by SPGLIB

aiida.tools.data.array.kpoints.main.get_explicit_kpoints_path(structure, method='seekpath', **kwargs)[源代码]#

Returns a dictionary whose contents depend on the method but includes at least the following keys

  • parameters: Dict node

  • explicit_kpoints: KpointsData node with explicit kpoints path

The contents of the parameters depends on the method but contains at least the keys

  • ‘point_coords’: a dictionary with ‘kpoints-label’: [float coordinates]

  • ‘path’: a list of length-2 tuples, with the labels of the starting

    and ending point of each label section

The ‘seekpath’ method which is the default also returns the following additional nodes

  • primitive_structure: StructureData with the primitive cell

  • conv_structure: StructureData with the conventional cell

Note that the generated kpoints for the seekpath method only apply on the returned primitive_structure and not on the input structure that was provided

参数:
  • structure – a StructureData node

  • method – the method to use for kpoint generation, options are ‘seekpath’ and ‘legacy’. It is strongly advised to use the default ‘seekpath’ as the ‘legacy’ implementation is known to have bugs for certain structure cells

  • kwargs – optional keyword arguments that depend on the selected method

返回:

dictionary as described above in the docstring

aiida.tools.data.array.kpoints.main.get_kpoints_path(structure, method='seekpath', **kwargs)[源代码]#

Returns a dictionary whose contents depend on the method but includes at least the following keys

  • parameters: Dict node

The contents of the parameters depends on the method but contains at least the keys

  • ‘point_coords’: a dictionary with ‘kpoints-label’: [float coordinates]

  • ‘path’: a list of length-2 tuples, with the labels of the starting

    and ending point of each label section

The ‘seekpath’ method which is the default also returns the following additional nodes

  • primitive_structure: StructureData with the primitive cell

  • conv_structure: StructureData with the conventional cell

Note that the generated kpoints for the seekpath method only apply on the returned primitive_structure and not on the input structure that was provided

参数:
  • structure – a StructureData node

  • method – the method to use for kpoint generation, options are ‘seekpath’ and ‘legacy’. It is strongly advised to use the default ‘seekpath’ as the ‘legacy’ implementation is known to have bugs for certain structure cells

  • kwargs – optional keyword arguments that depend on the selected method

返回:

dictionary as described above in the docstring

Tool to automatically determine k-points for a given structure using SeeK-path.

aiida.tools.data.array.kpoints.seekpath.get_explicit_kpoints_path(structure, parameters)[源代码]#

Return the kpoint path for band structure (in scaled and absolute coordinates), given a crystal structure, using the paths proposed in the various publications (see description of the ‘recipe’ input parameter). The parameters are the same as get get_explicit_k_path in __init__, but here all structures are input and returned as AiiDA structures rather than tuples, and similarly k-points-related information as a AiiDA KpointsData class.

参数:
  • structure – The AiiDA StructureData for which we want to obtain the suggested path.

  • parameters – A dictionary whose key-value pairs are passed as additional kwargs to the seekpath.get_explicit_k_path function.

返回:

A dictionary with four nodes:

  • explicit_kpoints: a KpointsData with the (explicit) kpoints (with labels set).

  • parameters: a Dict, whose content is the same dictionary as returned by the seekpath.get_explicit_k_path function (see seekpath documentation), except that:

    • conv_lattice, conv_positions, conv_types are removed and replaced by the conv_structure output node

    • primitive_lattice, primitive_positions, primitive_types are removed and replaced by the primitive_structure output node

    • reciprocal_primitive_lattice, explicit_kpoints_abs, explicit_kpoints_rel and explicit_kpoints_labels are removed and replaced by the explicit_kpoints output node

  • primitive_structure: A StructureData with the primitive structure

  • conv_structure: A StructureData with the primitive structure

aiida.tools.data.array.kpoints.seekpath.get_kpoints_path(structure, parameters)[源代码]#

Return the kpoint path information for band structure given a crystal structure, using the paths from the chosen recipe/reference. The parameters are the same as get get_path in __init__, but here all structures are input and returned as AiiDA structures rather than tuples.

If you use this module, please cite the paper of the corresponding recipe (see documentation of seekpath).

参数:
  • structure – The crystal structure for which we want to obtain the suggested path. It should be an AiiDA StructureData object.

  • parameters – A dictionary whose key-value pairs are passed as additional kwargs to the seekpath.get_path function.

返回:

A dictionary with three nodes:

  • parameters: a Dict, whose content is the same dictionary as returned by the seekpath.get_path function (see seekpath documentation), except that:

    • conv_lattice, conv_positions, conv_types are removed and replaced by the conv_structure output node

    • primitive_lattice, primitive_positions, primitive_types are removed and replaced by the primitive_structure output node

  • primitive_structure: A StructureData with the primitive structure

  • conv_structure: A StructureData with the primitive structure