Spglib for Python

Spglib for Python#

Usage note#

The python binding will first try to use your system installed version of spglib. This can be controlled by setting an appropriate LD_LIBRARY_PATH (linux) or DYLD_LIBRAY_PATH (macos) to the appropriate location of the libsymspg.so library file. If no suitable version is found, it will default to using the bundled version.

Installation#

The main installation method we support are using pip and conda. Additionally, you can build and install from source.

The following pip and conda packages are made and maintained by Paweł T. Jochym, which is of great help to keeping spglib handy and useful.

Using pip#

You can find all the spglib release versions on our PyPI project page. To install it use the standard pip install commands:

$ pip install spglib

Using conda#

We also maintain a conda package which you can install:

$ conda install -c conda-forge spglib

Building from source#

For this section we are assuming you have cloned or downloaded the spglib source code, and we are working from the top-level directory.

$ git clone https://github.com/spglib/spglib
$ cd spglib

To manually install spglib you will need cmake with any make tool like make, a C compiler (e.g. gcc, clang), and python development files (python-dev), including numpy ones.

There are two ways of building spglib with the python bindings using either a python-centric or cmake-centric approach

Python controlled#

This is the primary installation method suitable for production that we use to distribute the spglib package.

$ pip install .

All build configurations are defined in the top-level pyproject.toml file. We are using scikit-build-core to build both the main spglib C library and the python apis. You can thus further configure your local installation, e.g. to use OpenMP:

$ pip install . --config-settings=cmake.define.SPGLIB_USE_OMP=ON

Currently scikit-build-core does not support editable installs for development.

Cmake controlled#

This method is not suitable for production, and it is only meant for quick development

$ cmake -B ./build -DSPGLIB_WITH_Fortran=ON
$ cmake --build ./build
$ cmake --install ./build

This will detect and install the python manually in the currently activated virtual environment’s site-package folder (e.g. venv/lib64/python3.11/site-packages), otherwise defaulting to the system (/usr/lib64/python3.11/site-packages). You may edit this location by passing a Python_INSTALL_DIR option.

Test#

You may execute the python tests locally from the git repository root:

$ pytest

How to import spglib module#

Change in version 1.9.0!

For versions 1.9.x or later:

For versions 1.8.x or before:

from pyspglib import spglib

If the version is not sure:

try:
    import spglib as spg
except ImportError:
    from pyspglib import spglib as spg

Version number#

In version 1.8.3 or later, the version number is obtained by spglib.__version__ or spglib.spglib.get_version().

Example#

Examples are found in example/python_api directory.

Variables#

Crystal structure (cell)#

A crystal structure is given by a tuple. This tuple format is supported at version 1.9.1 or later.

The tuple format is shown as follows. There are three or four elements in the tuple: cell = (lattice, positions, numbers) or cell = (lattice, positions, numbers, magmoms) where magmoms represents magnetic moments on atoms and is optional.

Lattice parameters lattice are given by a 3x3 matrix with floating point values, where \(\mathbf{a}, \mathbf{b}, \mathbf{c}\) are given as rows, which results in the transpose of the definition for C-API (lattice). Fractional atomic positions positions are given by a Nx3 matrix with floating point values, where N is the number of atoms. Numbers to distinguish atomic species numbers are given by a list of N integers. The magnetic moments magmoms can be specified with get_magnetic_symmetry. magmoms is a list of N floating-point values for collinear cases and a list of Nx3 in cartesian coordinates for non-collinear cases.

lattice = [[a_x, a_y, a_z],
            [b_x, b_y, b_z],
            [c_x, c_y, c_z]]
positions = [[a_1, b_1, c_1],
               [a_2, b_2, c_2],
               [a_3, b_3, c_3],
               ...]
numbers = [n_1, n_2, n_3, ...]
magmoms = [m_1, m_2, m_3, ...]  # Works with get_magnetic_symmetry for a collinear case
# magmoms = [[m_1x, m_1y, m_1z], ...]  # For a non-collinear case

For example, the crystal structure (cell) of L1\(_{2}\)-type AlNi\(_{3}\) is:

lattice = [[1.0, 0.0, 0.0],
            [0.0, 1.0, 0.0],
            [0.0, 0.0, 1.0]]
positions = [[0.0, 0.0, 0.0], # Al
            [0.5, 0.5, 0.0], # Ni
            [0.0, 0.5, 0.5], # Ni
            [0.5, 0.0, 0.5]] # Ni
numbers = [1, 2, 2, 2]        # Al, Ni, Ni, Ni

Note

When a crystal structure is not properly given, TypeError will be raised. For previous versions between 1.9.5 and 2.3.1, None will be returned for the invalid input.

Symmetry tolerance (symprec, angle_tolerance, mag_symprec)#

Distance tolerance in Cartesian coordinates to find crystal symmetry. For more details, see symprec, angle_tolerance, and mag_symprec.

API summary#

Version#

Error#

Standardization and finding primitive cell#

Space-group dataset access#

Magnetic symmetry#

Lattice reduction#

Kpoints#

mapping, grid = get_ir_reciprocal_mesh(mesh, cell, is_shift=[0, 0, 0])

Irreducible k-points are obtained from a sampling mesh of k-points. mesh is given by three integers by array and specifies mesh numbers along reciprocal primitive axis. is_shift is given by the three integers by array. When is_shift is set for each reciprocal primitive axis, the mesh is shifted along the axis in half of adjacent mesh points irrespective of the mesh numbers. When the value is not 0, is_shift is set.

mapping and grid are returned. grid gives the mesh points in fractional coordinates in reciprocal space. mapping gives mapping to the irreducible k-point indices that are obtained by

np.unique(mapping)

Here np means the numpy module. The grid point is accessed by grid[index].

When the search failed, None is returned.

An example is shown below:

import numpy as np
import spglib

lattice = np.array([[0.0, 0.5, 0.5],
                    [0.5, 0.0, 0.5],
                    [0.5, 0.5, 0.0]]) * 5.4
positions = [[0.875, 0.875, 0.875],
            [0.125, 0.125, 0.125]]
numbers= [1,] * 2
cell = (lattice, positions, numbers)
print(spglib.get_spacegroup(cell, symprec=1e-5))
mesh = [8, 8, 8]

#
# Gamma centre mesh
#
mapping, grid = spglib.get_ir_reciprocal_mesh(mesh, cell, is_shift=[0, 0, 0])

# All k-points and mapping to ir-grid points
for i, (ir_gp_id, gp) in enumerate(zip(mapping, grid)):
    print("%3d ->%3d %s" % (i, ir_gp_id, gp.astype(float) / mesh))

# Irreducible k-points
print("Number of ir-kpoints: %d" % len(np.unique(mapping)))
print(grid[np.unique(mapping)] / np.array(mesh, dtype=float))

#
# With shift
#
mapping, grid = spglib.get_ir_reciprocal_mesh(mesh, cell, is_shift=[1, 1, 1])

# All k-points and mapping to ir-grid points
for i, (ir_gp_id, gp) in enumerate(zip(mapping, grid)):
    print("%3d ->%3d %s" % (i, ir_gp_id, (gp + [0.5, 0.5, 0.5]) / mesh))

# Irreducible k-points
print("Number of ir-kpoints: %d" % len(np.unique(mapping)))
print((grid[np.unique(mapping)] + [0.5, 0.5, 0.5]) / mesh)

Deprecated#

Caution

Following functions are deprecated!

spglib.spglib.get_hall_number_from_symmetry(rotations, translations, symprec=1e-05)[source]#

Hall number is obtained from a set of symmetry operations. If fails, return None.

Deprecated since version 2.0: Replaced by {func}`get_spacegroup_type_from_symmetry`.

Return one of hall_number corresponding to a space-group type of the given set of symmetry operations. When multiple hall_number exist for the space-group type, the smallest one (the first description of the space-group type in International Tables for Crystallography) is chosen. The definition of hall_number is found at Space group type and the corresponding space-group-type information is obtained through {func}`get_spacegroup_type`.

This is expected to work well for the set of symmetry operations whose distortion is small. The aim of making this feature is to find space-group-type for the set of symmetry operations given by the other source than spglib.

Note that the definition of symprec is different from usual one, but is given in the fractional coordinates and so it should be small like 1e-5.