DOCSEARCHbyAlgolia
Submit Docs

SeeK-path

repository·main·Indexed 41 days ago

https://github.com/materialscloud-org/seekpath

A Python-based tool for determining and visualizing Brillouin zone band paths for crystal structures. It utilizes spacegroup symmetry to provide standardized k-point paths following the HPKOT paper conventions. Key features include automatic Bravais lattice detection, support for systems lacking time-reversal or inversion symmetry, and functions like get_path and get_explicit_k_path to retrieve k-vector coefficients and coordinates.

Tokens
3.3K
Snippets
11
Records
16
Agent score
51%

What's inside SeeK-path

  1. Overview of SeeK-path

    main

    SeeK-path is a Python module designed to obtain band paths in the Brillouin zone of crystal structures. It follows crystallographic conventions for k-point labels as defined in the HPKOT paper.

    Key features include:

    • Automatic detection of the Bravais lattice using spacegroup symmetry.
    • Provision of suggested band paths based on the HPKOT paper.
    • Support for systems lacking time-reversal and inversion symmetry.

  2. Get k-point paths for non-standard unit cells

    main

    If you have already performed calculations with a non-standardized cell (e.g., a supercell or a non-primitive cell) and need a compatible k-point path, use the get_path_orig_cell function.

    Key Behaviors

    • Non-standard primitive cells: If the input is a non-standard primitive cell, the returned k-path is equivalent to the path for the standard cell.
    • Supercells: If the input is a supercell, the returned k-path is that of the associated primitive cell, expressed in the basis of the supercell reciprocal lattice. The k-points correspond to the high-symmetry points of the primitive cell's Brillouin zone, not the supercell's.
    • Symmetry: Unlike get_path, get_path_orig_cell calculates the k-path based on a symmetrized structure but does not symmetrize the input structure itself. If the input structure's symmetry is broken below the symprec threshold, the resulting k-points may not lie exactly on high-symmetry points.

    Functions

    • seekpath.get_path_orig_cell(...): Returns path metadata and coefficients.
    • seekpath.get_explicit_k_path_orig_cell(...): Returns an explicit list of k-points.
    # Use this when you cannot change your existing calculation cell
path_data = seekpath.get_path_orig_cell(structure, with_time_reversal, recipe, threshold, symprec, angle_tolerance)

  3. Best practices for crystal structure standardization

    main

    The get_path and get_explicit_k_path functions automatically standardize the crystal structure (e.g., rotating a tetragonal system so the c axis is along z). To ensure consistency between your k-point path and your physical calculations, follow this workflow:

    1. Identify the standard cell: Use seekpath.get_path with your current structure. This returns the standardized primitive cell and the suggested band path.
    2. Store the standard cell: Save the standardized primitive cell returned in the output.
    3. Run calculations: Perform all your electronic structure calculations using this standardized primitive cell rather than your original input cell.

    If you must use a non-standardized cell for your calculations, use the _orig_cell variants of the functions to avoid coordinate mismatches.

  4. Install SeeK-path via pip or Docker

    main

    To install SeeK-path, use the standard Python package manager:

    pip install seekpath

    Note that it supports Python 2.7 and Python 3.5+. On some Linux distributions (like OpenSuse Leap 42.2), you may need to install python3-devel and openblas-devel as dependencies.

    Alternatively, you can use Docker by using the provided Dockerfile or pulling images directly from Docker Hub.

  5. Access the SeeK-path online service

    main
    If you prefer a web-based interface over a local Python installation, you can use the SeeK-path online tool hosted on the Materials Cloud web portal. This service allows for the visualization of band paths and primitive cells of crystal structures, showing the Brillouin zone, primitive crystal structure, k-point coordinates, and suggested band paths.

  7. How to handle path segments and break points

    main

    When using explicit k-paths (from get_explicit_k_path or get_explicit_k_path_orig_cell), the explicit_segments and explicit_kpoints_labels allow you to distinguish between continuous paths and 'break' points.

    • Continuous Path: If explicit_segments[i-1][1] == explicit_segments[i][0] + 1, the point was calculated only once and belongs to both segments.
    • Break Point: If explicit_segments[i-1][1] == explicit_segments[i][0], it is a 'break' point (e.g., a transition from an X point to an R point). In graphical representations, these are often shown at the same coordinate with a combined label like R|X.

  8. Use get_path to obtain band paths and standardized structures

    main

    The seekpath.get_path function is the primary interface for obtaining k-point paths and standardized crystal structures. It detects the Bravais lattice using spacegroup symmetry and returns the suggested band path based on crystallographic conventions.

    Input Structure Format

    The structure argument must be a tuple in the following format: (cell, positions, numbers)

    • cell: A 3x3 list of floats representing the lattice vectors.
    • positions: A Nx3 list of floats representing atomic coordinates in scaled coordinates (w.r.t. the cell vectors).
    • numbers: A list of length N containing integers that uniquely identify the atoms in the cell.

    Function Signature

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

    Parameters

    • structure: The tuple described above.
    • with_time_reversal: Boolean flag indicating if time-reversal symmetry is present.
    • recipe: String specifying the path recipe (currently only 'hpkot' is supported).
    • threshold: Numerical threshold used to identify properties like the order of axes in an orthorhombic cell.
    • symprec: Symmetry precision passed to spglib.
    • angle_tolerance: Angle tolerance passed to spglib.

    Output

    The function returns a dictionary containing k-vector coefficients, the suggested band path, inversion symmetry information, and the crystallographic/reciprocal primitive lattices.

    # Example usage pattern
# structure = (cell, positions, numbers)
path_data = seekpath.get_path(structure, True, 'hpkot', 0.01, 1e-5, 1e-5)

  9. Get an explicit list of k-points with get_explicit_k_path

    main

    If you need a specific list of k-points along a suggested band path rather than just the path coefficients, use get_explicit_k_path (or get_explicit_k_path_orig_cell for non-standard cells).

    Function Signature

    seekpath.get_explicit_k_path(structure, with_time_reversal, recipe, threshold, symprec, angle_tolerance, reference_distance=None)

    Parameters

    • reference_distance: An optional parameter used as a target distance between neighboring k-points along the path.

    This function is useful for generating the actual coordinates needed for band structure plotting or calculation input files.

    # Returns an explicit list of k-points
k_points = seekpath.get_explicit_k_path(structure, True, 'hpkot', 0.01, 1e-5, 1e-5, reference_distance=0.1)

  10. Get Brillouin zone paths with seekpath

    main

    The seekpath module provides routines to automatically determine paths in a 3D Brillouin zone, which are used for plotting band structures. The primary functions for retrieving these paths are get_path and get_explicit_k_path.

    from seekpath import get_path

# Example usage (requires appropriate input data structures from the module)
# path = get_path(data)

  11. Obtain k-point path for the original unit cell with get_path_orig_cell

    main

    Use get_path_orig_cell (or get_explicit_k_path_orig_cell for full paths) when you want the k-point path information expressed in the basis of the original unit cell provided by the user, rather than the standardized primitive cell.

    Important Notes:

    • Standardization: No standardization or symmetrization of the input unit cell is performed.
    • Supercells: If the input is a supercell, the function returns the standard k-path of the associated primitive cell in the basis of the supercell reciprocal lattice. A seekpath.SupercellWarning is issued, and k-point labels may lose their standard meaning.
    • Output: The returned dictionary contains the same keys as get_path, but point_coords are transformed to the scaled coordinates of the original lattice.
    from seekpath import get_path_orig_cell

# structure = (cell, positions, numbers)
res = get_path_orig_cell(structure, recipe='hpkot')
print(res['point_coords'])

  12. Obtain k-point path information with get_path

    main

    Use get_path to return k-point path information for band structures based on a crystal structure. This function uses a standardized primitive cell.

    Input Structure Format: The structure parameter must be a tuple accepted by spglib: (cell, positions, numbers):

    • cell: A $3 \times 3$ list of floats representing the lattice vectors.
    • positions: An $N \times 3$ list of floats representing atomic coordinates in scaled (fractional) coordinates.
    • numbers: A list of length $N$ containing integers identifying the atoms (e.g., atomic numbers).

    Key Parameters:

    • recipe: The reference publication for special points. Currently, only 'hpkot' is supported.
    • with_time_reversal: If False and the group lacks inversion symmetry, additional lines are returned.
    • symprec: Symmetry precision used by SPGLIB.
    • threshold: Threshold for detecting edge cases (e.g., distinguishing tetragonal from cubic).

    Return Dictionary Keys:

    • point_coords: Dictionary mapping labels to float coordinates.
    • path: List of length-2 tuples (start_label, stop_label) for each segment.
    • bravais_lattice: String describing the lattice (e.g., 'cP', 'tI').
    • primitive_lattice: Real-space vectors for the primitive cell.
    • reciprocal_primitive_lattice: Reciprocal-cell vectors for the primitive cell.
    from seekpath import get_path

# structure = (cell, positions, numbers)
res = get_path(structure, recipe='hpkot')
print(res['path'])