Spglib

Warnings

• gotcha The `symprec` parameter (symmetry precision) is crucial for accurate results. It defines the maximum displacement or distance for atoms to be considered symmetrically equivalent. An incorrect `symprec` (too large or too small) can lead to incorrect symmetry detection, especially for structures with small distortions or specific computational precisions.
  Fix: Adjust `symprec` based on the precision of your input structure data. Common values range from 1e-1 to 1e-8. For structures from DFT, 1e-3 to 1e-5 is often suitable. Experiment with different values if unexpected results occur.
• gotcha Input cell format requires strict adherence: `(lattice, positions, numbers)`. `lattice` must be a 3x3 NumPy array where rows are the lattice vectors. `positions` must be an Nx3 NumPy array of *fractional* coordinates. `numbers` must be a list or array of *integer* atom types (not elemental symbols).
  Fix: Ensure lattice vectors are rows, positions are fractional, and atom types are integers. Many common errors arise from incorrect coordinate systems (e.g., Cartesian instead of fractional for positions) or misinterpreting lattice matrix orientation.
• gotcha The behavior of `spglib.get_primitive` and `spglib.find_primitive` regarding the primitive cell origin changed significantly with v2.0.0 (and C library v1.16). From v2.0.0, these functions accept an optional `cell_origin` parameter. If not provided, a default origin is used, which might differ from the implicit behavior of older versions, potentially affecting consistency for users relying on a specific primitive cell definition.
  Fix: When using `get_primitive` or `find_primitive` with spglib >= 2.0.0, explicitly set the `cell_origin` (e.g., `(0, 0, 0)`) if you require a specific origin, especially when comparing results with those obtained from older spglib versions.

Install

• pip install spglib Install Spglib

Imports

• spglib

  import spglib

• get_spacegroup

  spglib.get_spacegroup(cell, symprec=1e-5)

  While functional, direct import is discouraged to keep a clear namespace, as many functions exist within the spglib module.
• get_symmetry_dataset

  spglib.get_symmetry_dataset(cell, symprec=1e-5)

Quickstart

This example demonstrates how to define a simple cubic unit cell and use `spglib.get_spacegroup` to identify its space group symmetry, as well as `spglib.get_symmetry_dataset` for more detailed information. Note the specific input format for the cell and the use of `symprec`.

import spglib
import numpy as np

# Define a simple cubic cell
# Lattice vectors as rows of a 3x3 matrix
lattice = np.array([[1.0, 0.0, 0.0],
                    [0.0, 1.0, 0.0],
                    [0.0, 0.0, 1.0]])

# Fractional coordinates of atoms
positions = np.array([[0.0, 0.0, 0.0]])

# Integer atom types (e.g., atomic number, or arbitrary unique integers)
numbers = [1]

# Combine into a cell tuple: (lattice, positions, numbers)
cell = (lattice, positions, numbers)

# Determine the space group using a symmetry precision
spacegroup_data = spglib.get_spacegroup(cell, symprec=1e-5)
print(f"Spacegroup: {spacegroup_data}")

# Get a full dataset of symmetry information
dataset = spglib.get_symmetry_dataset(cell, symprec=1e-5)
print(f"Spacegroup number: {dataset['number']}")
print(f"International short symbol: {dataset['international_short']}")