{"id":5492,"library":"spglib","title":"Spglib","description":"Spglib is a C library for finding and handling crystal symmetries, exposed as a Python module. It is widely used in materials science and solid-state physics for tasks such as space group determination, primitive cell reduction, and irreducible k-point generation. The current stable version is 2.7.0, with regular updates and maintenance.","status":"active","version":"2.7.0","language":"en","source_language":"en","source_url":"https://github.com/spglib/spglib","tags":["crystallography","materials science","symmetry","solid state physics","space group"],"install":[{"cmd":"pip install spglib","lang":"bash","label":"Install Spglib"}],"dependencies":[{"reason":"Required for array manipulation in the Python interface.","package":"numpy","optional":false}],"imports":[{"symbol":"spglib","correct":"import spglib"},{"note":"While functional, direct import is discouraged to keep a clear namespace, as many functions exist within the spglib module.","wrong":"from spglib import get_spacegroup","symbol":"get_spacegroup","correct":"spglib.get_spacegroup(cell, symprec=1e-5)"},{"symbol":"get_symmetry_dataset","correct":"spglib.get_symmetry_dataset(cell, symprec=1e-5)"}],"quickstart":{"code":"import spglib\nimport numpy as np\n\n# Define a simple cubic cell\n# Lattice vectors as rows of a 3x3 matrix\nlattice = np.array([[1.0, 0.0, 0.0],\n                    [0.0, 1.0, 0.0],\n                    [0.0, 0.0, 1.0]])\n\n# Fractional coordinates of atoms\npositions = np.array([[0.0, 0.0, 0.0]])\n\n# Integer atom types (e.g., atomic number, or arbitrary unique integers)\nnumbers = [1]\n\n# Combine into a cell tuple: (lattice, positions, numbers)\ncell = (lattice, positions, numbers)\n\n# Determine the space group using a symmetry precision\nspacegroup_data = spglib.get_spacegroup(cell, symprec=1e-5)\nprint(f\"Spacegroup: {spacegroup_data}\")\n\n# Get a full dataset of symmetry information\ndataset = spglib.get_symmetry_dataset(cell, symprec=1e-5)\nprint(f\"Spacegroup number: {dataset['number']}\")\nprint(f\"International short symbol: {dataset['international_short']}\")","lang":"python","description":"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`."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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).","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}