Seekpath: Brillouin Zone Paths

2.2.1 · active · verified Thu Apr 16

Seekpath is a Python module designed to obtain and visualize k-vector coefficients and automatically generate high-symmetry band paths in the Brillouin zone of crystal structures. It integrates with spglib for symmetry analysis and is widely used in materials science for electronic structure calculations. The current version is 2.2.1, with minor releases typically occurring every few months to address bug fixes and improve compatibility.

Common errors

```
ImportError: No module named 'spglib'
```
cause The `spglib` library, a fundamental dependency for `seekpath`'s symmetry operations, is not installed in your environment.

fix Install `spglib` using pip: `pip install spglib`.
```
TypeError: object of type 'list' has no len()
```
cause This typically occurs when `lattice` or `positions` are passed as standard Python lists instead of NumPy arrays, or their dimensions are incorrect for numerical operations.

fix Convert list inputs to `numpy.ndarray` and verify their shapes. For example: `lattice = np.array([[...]])` and `positions = np.array([[...]])`.
```
AttributeError: module 'spglib' has no attribute 'get_symmetry_dataset'
```
cause This error points to a version incompatibility between `seekpath` and `spglib`. Your `seekpath` version is trying to call an `spglib` function (`get_symmetry_dataset`) that does not exist in the installed `spglib` version (likely `spglib < 2.0`).

fix Upgrade your `spglib` library to a compatible version (e.g., `spglib >= 2.0`). It's recommended to use `seekpath >= 2.2.0` with `spglib >= 2.0`. Command: `pip install --upgrade spglib`.
```
seekpath.seekpath.SeekpathError: Could not find any high-symmetry path for the given structure.
```
cause The input crystal structure might be invalid, trivial (e.g., a single atom, a disordered system), or too complex/non-standard for `spglib` to unambiguously determine its space group symmetry and thus a standard high-symmetry path.

fix Carefully verify the input `lattice`, `positions`, and `numbers` to ensure they represent a valid and sufficiently symmetric crystal structure. For structures with very low symmetry or disorder, automatic path generation may not be feasible, and manual path definition might be required.

Warnings

gotcha Older versions of `seekpath` (prior to 2.2.0) may emit `DeprecationWarning`s or encounter issues when used with `spglib` versions 2.5.0 or later due to internal API changes in `spglib`.
Fix: Upgrade `seekpath` to version 2.2.0 or newer: `pip install --upgrade seekpath`.
gotcha Versions of `seekpath` prior to 2.2.1 might emit `UserWarning`s related to the internal `get_BZ()` function when processing certain crystal structures, indicating sub-optimal Brillouin zone sampling.
Fix: Upgrade `seekpath` to version 2.2.1 or newer to resolve these warnings: `pip install --upgrade seekpath`.
gotcha `seekpath` expects crystal structure data in a specific format: `(lattice, positions, numbers)`. `lattice` must be a 3x3 array of lattice vectors, `positions` an Nx3 array of fractional coordinates, and `numbers` a list/array of atomic numbers. Incorrect shapes, types (e.g., Python lists instead of NumPy arrays), or non-numeric values can lead to cryptic errors.
Fix: Ensure `lattice` and `positions` are `numpy.ndarray` with correct 3D shapes and `numbers` is a list or array of integers. Validate your input data before passing it to `get_path`.

Install

pip install seekpath Install stable release

Imports

get_path
```
from seekpath import get_path
```

Quickstart

This example demonstrates how to define a simple crystal structure (Silicon) and use `seekpath.get_path` to obtain the high-symmetry k-point path and coordinates in the Brillouin zone. The output `path_data` dictionary contains essential information for band structure calculations.

import numpy as np
from seekpath import get_path

# Define a crystal structure (e.g., Silicon)
# lattice: Bravais lattice vectors in Angstrom
lattice = np.array([
    [0.0, 2.715, 2.715],
    [2.715, 0.0, 2.715],
    [2.715, 2.715, 0.0],
])
# positions: fractional coordinates of atoms in the unit cell
positions = np.array([
    [0.0, 0.0, 0.0],
    [0.25, 0.25, 0.25],
])
# numbers: atomic numbers
numbers = [14, 14] # Silicon

# Get the recommended path and high-symmetry k-points
path_data = get_path(lattice, positions, numbers)

print(f"Points in reciprocal space: {path_data['point_coords'].keys()}")
print(f"Path segments: {path_data['path']}")

# Example: Accessing coordinates of a specific high-symmetry point
print(f"Gamma point coordinates: {path_data['point_coords'].get('GAMMA')}")

view raw JSON →