paulatz/seekpath

A module to obtain and visualize k-vector coefficients and obtain band paths in the Brillouin zone of crystal structures

SeeK-path

Test status: branch master: ; branch develop:

SeeK-path is a python module to obtain and visualize band paths in the Brillouin zone of crystal structures.

The definition of k-point labels follows crystallographic convention, as defined and discussed in the HPKOT paper. Moreover, the Bravais lattice is detected properly using the spacegroup symmetry. Also the suggested band path provided in the HPKOT paper is returned. Systems without time-reversal and inversion-symmetry are also properly taken into account.

Contents

• 1   How to cite
• 2   How to install
• 3   How to use
  • 3.1   A warning on how to use (and crystal structure standardization)
  • 3.2   Explicit k path
• 4   AiiDA integration
• 5   License
• 6   Online service/tool

1   How to cite

If you use this tool, please cite the following work:

• Y. Hinuma, G. Pizzi, Y. Kumagai, F. Oba, I. Tanaka, Band structure diagram paths based on crystallography, Comp. Mat. Sci. 128, 140 (2017) (JOURNAL LINK, arXiv link).
• You should also cite spglib that is an essential library used in the implementation.

2   How to install

To install, use pip install seekpath. It works both in python 2.7 and in python 3.5.

If you want to start everything with Docker, follow the instructions on the docker hub page.

3   How to use

The main interface of the code is the python function

seekpath.get_path(structure, with_time_reversal, recipe, threshold)

You need to pass a crystal structure, a boolean flag (with_time_reversal) to say if time-reversal symmetry is present or not, and optionally, a recipe (currently only the string "HPKOT" is supported) and a numerical threshold.

The format of the structure is described in the function docstring. In particular, It should be a tuple in the format

(cell, positions, numbers)

where (if N is the number of atoms):

• cell is a 3x3 list of floats (cell[0] is the first lattice vector, ...);
• positions is a Nx3 list of floats with the atomic coordinates in scaled coordinates (i.e., w.r.t. the cell vectors);
• numbers is a length-N list with integers identifying uniquely the atoms in the cell.

The output of the function is a dictionary containing, among other quantities, the k-vector coefficients, the suggested band path, whether the system has inversion symmetry, the crystallographic primitive lattice, the reciprocal primitive lattice. A detailed description of all output information and their format can be found in the function docstring.

3.1   A warning on how to use (and crystal structure standardization)

SeeK-path standardizes the crystal structure (e.g., rotates the tetragonal system so that the c axis is along z, etc.) and can compute the suggested band paths only of standardized (crystallographic) primitive cells. Therefore, the correct approach to use this tool is the following:

1. You first find the standardized primitive cell with SeeK-path (returned in output) and store it somewhere, together with the k-point coordinates and suggested band path
2. You then run all your calculations using the standardized primitive cell

If you already have done calculations with a non-standardized cell, you will then need to figure out how to remap the labeled k-points in the choice of cell you did.

3.2   Explicit k path

You might also be interested in the function

seekpath.get_explicit_k_path

that has a very similar interface, that produces an explicit list of k-points along the suggested band path. The function has the same interface as get_path, but has also an additional optional parameter reference_distance, that is used as a reference target distance between neighboring k-points along the path. More detailed information can be found in the docstrings.

4   AiiDA integration

If you use AiiDA (www.aiida.net), you might be interested in replacing the above functions with the following wrappers, instead:

seekpath.aiidawrappers.get_path

seekpath.aiidawrappers.get_explicit_k_path

The function interfaces are very similar, but the advantage is that these functions expect an AiiDA structure as input (instead of a tuple) and return AiiDA structures and KpointsData classes instead of lists and tuples, where appropriate. Also in this case, additional information is found in the docstrings.

5   License

The code is open-source (licensed with a MIT license, see LICENSE.txt).

6   Online service/tool

In this repository we also provide the code to deploy a online service for the visualization of the band paths and primitive cells of the crystal structures. A live demo is currently hosted on the MaterialsCloud web portal.

The following is a screenshot of the selection window:

And the following is a screenshot of the main output window, showing the Brillouin zone, the primitive crystal structure, the coordinates of the k-points and the suggested band path.