Welcome to documentation of SeeK-path¶
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.
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: A. Togo, I. Tanaka, “Spglib: a software library for crystal symmetry search”, arXiv:1808.01590 (2018) (spglib arXiv link).
How to install¶
To install, use pip install seekpath
. It works both in python 2.7 and
in python 3.5.
In some distributions (e.g. OpenSuse Leap 42.2), some additional libraries might be needed, like python3-devel and openblas-devel.
If you want to start everything with Docker, you can use the Dockerfile
provided,
or directly the images on docker hub.
How to use¶
The main interface of the code is the get_path()
python function:
seekpath.get_path(structure, with_time_reversal, recipe, threshold, symprec, angle_tolerance)
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 a3x3
list of floats (cell[0]
is the first lattice vector, …);positions
is aNx3
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. (Note that the threshold
is the one used by seekpath to identify
e.g. the order of axes in an orthorhombic cell; instead symprec
and angle_tolerance
are just passed to spglib).
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:
- 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
- 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.
Explicit k path¶
You might also be interested in the get_explicit_k_path()
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 of get_explicit_k_path()
.
AiiDA integration¶
If you use AiiDA, you might be interested to use the wrappers that are provided in AiiDA.
The documentation of the methods can be found at http://aiida-core.readthedocs.io/en/latest/datatypes/kpoints.html
Legacy wrappers¶
Deprecated since version 1.8: This section describes deprecated methods for back-compatibility reasons. Until seekpath version 1.7, AiiDA wrappers were included into seekpath itself. They have now been included in AiiDA.
These methods will be removed in future versions of seekpath.
If you use AiiDA, you might be interested in replacing the above
functions with the following wrappers, instead: get_path()
,
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.