spglib.spg module

SpaceGroup operations.

class spglib.spg.SpaceGroupType(number, international_short, international_full, international, schoenflies, hall_number, hall_symbol, choice, pointgroup_international, pointgroup_schoenflies, arithmetic_crystal_class_number, arithmetic_crystal_class_symbol)

Bases: DictInterface

Space group type information.

More details are found at Spglib dataset.

Changed in version 2.0: hall_number member is added.

Added in version 2.5.0.

_abc_impl = <_abc._abc_data object>

arithmetic_crystal_class_number: int

Arithmetic crystal class number

arithmetic_crystal_class_symbol: str

Arithmetic crystal class symbol

choice: str

Centring, origin, basis vector setting

hall_number: int

Hall symbol serial number

hall_symbol: str

Hall symbol

international: str

International symbol

international_full: str

International full symbol

international_short: str

International short symbol

number: int

International space group number

pointgroup_international: str

International symbol of crystallographic point group

pointgroup_schoenflies: str

Schoenflies symbol of crystallographic point group

schoenflies: str

Schoenflies symbol

spglib.spg.SpgCell

Crystal structure represented by a tuple of (spglib.utils.Lattice, spglib.utils.Positions, spglib.utils.Numbers).

alias of tuple[Sequence[Sequence[float]], Sequence[Sequence[float]], Sequence[int]]

class spglib.spg.SpglibDataset(number, hall_number, international, hall, choice, transformation_matrix, origin_shift, rotations, translations, wyckoffs, site_symmetry_symbols, crystallographic_orbits, equivalent_atoms, primitive_lattice, mapping_to_primitive, std_lattice, std_positions, std_types, std_rotation_matrix, std_mapping_to_primitive, pointgroup)

Bases: DictInterface

Spglib dataset information.

Added in version 1.9.4: The member ‘choice’ is added.

Added in version 2.5.0.

_abc_impl = <_abc._abc_data object>

choice: str

Centring, origin, basis vector setting

crystallographic_orbits: ndarray[tuple[Any, ...], dtype[int32]]

Symmetrically equivalent atoms, where ‘symmetrically’ means the space group operations corresponding to the space group type.

This is very similar to equivalent_atoms. See the difference explained in equivalent_atoms

shape=(n_atoms,), dtype=’intc’

equivalent_atoms: ndarray[tuple[Any, ...], dtype[int32]]

Symmetrically equivalent atoms, where ‘symmetrically’ means found symmetry operations.

shape=(n_atoms,), dtype=’intc’

In spglib, symmetry operations are given for the input cell. When a non-primitive cell is inputted and the lattice made by the non-primitive basis vectors breaks its point group, the found symmetry operations may not correspond to the crystallographic space group type.

hall: str

Hall symbol

hall_number: int

Hall number.

This number is used in

get_symmetry_from_database() and get_spacegroup_type().

international: str

International symbol

mapping_to_primitive: ndarray[tuple[Any, ...], dtype[int32]]

Atom index mapping from original cell to the primitive cell of primitive_lattice.

shape=(n_atoms), dtype=’intc’

number: int

International space group number

origin_shift: ndarray[tuple[Any, ...], dtype[float64]]

Origin shift from standardized to input origin.

shape=(3,), dtype=’double’

See the detail at Transformation matrix and origin shift.

pointgroup: str

Pointgroup symbol in Hermann-Mauguin notation.

primitive_lattice: ndarray[tuple[Any, ...], dtype[float64]]

Basis vectors a, b, c of a primitive cell in row vectors.

shape=(3, 3), order=’C’, dtype=’double’

This is the primitive cell found inside spglib before applying standardization. Therefore, the values are distorted with respect to found space group type.

rotations: ndarray[tuple[Any, ...], dtype[int32]]

Matrix (rotation) parts of space group operations.

shape=(n_operations, 3, 3), order=’C’, dtype=’intc’

Note

Space group operations are obtained by

[(r,t) for r, t in zip(rotations, translations)]

See also get_symmetry().

site_symmetry_symbols: list[str]

Site symmetry symbols corresponding to the space group type.

std_lattice: ndarray[tuple[Any, ...], dtype[float64]]

Basis vectors a, b, c of an idealized standardized cell in row vectors.

shape=(3, 3), order=’C’, dtype=’double’

std_mapping_to_primitive: ndarray[tuple[Any, ...], dtype[int32]]

std_positions index mapping to those of atoms of the primitive cell in the standardized cell.

std_positions: ndarray[tuple[Any, ...], dtype[float64]]

Positions of atoms in the standardized cell in fractional coordinates.

shape=(n_atoms, 3), order=’C’, dtype=’double’

std_rotation_matrix: ndarray[tuple[Any, ...], dtype[float64]]

Rigid rotation matrix to rotate from standardized basis vectors to idealized standardized orthonormal basis vectors.

shape=(3, 3), order=’C’, dtype=’double’

L^idealized = R * L^standardized.

See the detail at Standardized crystal structure after idealization.

std_types: ndarray[tuple[Any, ...], dtype[int32]]

Identity numbers of atoms in the standardized cell.

shape=(n_atoms,), dtype=’intc’

transformation_matrix: ndarray[tuple[Any, ...], dtype[float64]]

Transformation matrix from input lattice to standardized lattice.

shape=(3, 3), order=’C’, dtype=’double’

L^original = L^standardized * Tmat.

See the detail at Transformation matrix and origin shift.

translations: ndarray[tuple[Any, ...], dtype[float64]]

Vector (translation) parts of space group operations.

shape=(n_operations, 3), order=’C’, dtype=’double’

Note

Space group operations are obtained by

[(r,t) for r, t in zip(rotations, translations)]

See also get_symmetry().

wyckoffs: list[str]

Wyckoff letters corresponding to the space group type.

spglib.spg.get_hall_number_from_symmetry(rotations, translations, symprec=1e-05)

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.

spglib.spg.get_spacegroup(cell, symprec=1e-05, angle_tolerance=-1.0, symbol_type=0)

Return space group in international table symbol and number as a string.

With symbol_type=1, Schoenflies symbol is given instead of international symbol.

Return type:

str | None

Returns:

If it fails, None is returned.

spglib.spg.get_spacegroup_type(hall_number, _throw=False)

Translate Hall number to space group type information. If it fails, return None.

This function allows to directly access to the space-group-type database in spglib (spg_database.c). To specify the space group type with a specific choice, hall_number is used. The definition of hall_number is found at Space group type.

Parameters:

hall_number (int) – Serial number for Hall symbol

Return type:

SpaceGroupType | None

Returns:

SpaceGroupType or None

Added in version 1.9.4.

spglib.spg.get_spacegroup_type_from_symmetry(rotations, translations, lattice=None, symprec=1e-05)

Return space-group type information from symmetry operations.

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.

Parameters

rotationsarray_like

Matrix parts of space group operations. shape=(n_operations, 3, 3), order=’C’, dtype=’intc’

translationsarray_like

Vector parts of space group operations. shape=(n_operations, 3), order=’C’, dtype=’double’

latticearray_like, optional

Basis vectors a, b, c given in row vectors. Default is None, which gives unit matrix. This should be the same as that used to find rotations and translations. If it is unknown, the cubic basis vector may be a possible choice unless the rotations and translations were obtained for an unusual (very oblique) choice of basis vectors. shape=(3, 3), order=’C’, dtype=’double’

symprec: float

See get_symmetry().

Returns

spacegroup_type : SpaceGroupType or None

Notes

Added in version 2.0.

This is the replacement of get_hall_number_from_symmetry().

spglib.spg.get_symmetry(cell, symprec=1e-05, angle_tolerance=-1.0, mag_symprec=-1.0, is_magnetic=True)

Find symmetry operations from a crystal structure and site tensors.

Warning

get_symmetry() with is_magnetic=True is deprecated at version 2.0.

Use get_magnetic_symmetry() for magnetic symmetry search.

Parameters

celltuple

Crystal structure given in tuple. It has to follow the following form, (basis vectors, atomic points, types in integer numbers, …)

• basis vectorsarray_like

  shape=(3, 3), order=’C’, dtype=’double’

  [[a_x, a_y, a_z],
  [b_x, b_y, b_z],
  [c_x, c_y, c_z]]
  

• atomic pointsarray_like

  shape=(num_atom, 3), order=’C’, dtype=’double’

  Atomic position vectors with respect to basis vectors, i.e., given in fractional coordinates.

• typesarray_like

  shape=(num_atom, ), dtype=’intc’

  Integer numbers to distinguish species.

• optional data :

  case-I: Scalar

  shape=(num_atom, ), dtype=’double’

  Each atomic site has a scalar value. With is_magnetic=True, values are included in the symmetry search in a way of collinear magnetic moments.

  case-II: Vectors

  shape=(num_atom, 3), order=’C’, dtype=’double’

  Each atomic site has a vector. With is_magnetic=True, vectors are included in the symmetry search in a way of non-collinear magnetic moments.

symprecfloat

Symmetry search tolerance in the unit of length.

angle_tolerancefloat

Symmetry search tolerance in the unit of angle deg. Normally it is not recommended to use this argument. See a bit more detail at angle_tolerance. If the value is negative, an internally optimized routine is used to judge symmetry.

mag_symprecfloat

Tolerance for magnetic symmetry search in the unit of magnetic moments. If not specified, use the same value as symprec.

is_magneticbool

When optional data (4th element of cell tuple) is given in case-II, the symmetry search is performed considering magnetic symmetry, which may be corresponding to that for non-collinear calculation. Default is True, but this does nothing unless optional data is supplied.

Returns

symmetry: dict

Rotation parts and translation parts of symmetry operations are represented with respect to basis vectors. When the search failed, None is returned.

• ‘rotations’ndarray

  shape=(num_operations, 3, 3), order=’C’, dtype=’intc’

  Rotation (matrix) parts of symmetry operations

• ‘translations’ndarray

  shape=(num_operations, 3), dtype=’double’

  Translation (vector) parts of symmetry operations

• ‘time_reversals’: ndarray (exists when the optional data is given)

  shape=(num_operations, ), dtype=’bool_’

  Time reversal part of magnetic symmetry operations. True indicates time reversal operation, and False indicates an ordinary operation.

• ‘equivalent_atoms’ndarray

  shape=(num_atoms, ), dtype=’intc’

  A mapping table of atoms to symmetrically independent atoms. This is used to find symmetrically equivalent atoms. The numbers contained are the indices of atoms starting from 0, i.e., the first atom is numbered as 0, and then 1, 2, 3, … np.unique(equivalent_atoms) gives representative symmetrically independent atoms. A list of atoms that are symmetrically equivalent to some independent atom (here for example 1 is in equivalent_atom) is found by np.where(equivalent_atom=1)[0].

Notes

The orders of the rotation matrices and the translation vectors correspond with each other, e.g. , the second symmetry operation is organized by the set of the second rotation matrix and second translation vector in the respective arrays. Therefore a set of symmetry operations may obtained by

[(r, t) for r, t in zip(dataset['rotations'], dataset['translations'])]

The operations are given with respect to the fractional coordinates (not for Cartesian coordinates). The rotation matrix and translation vector are used as follows:

new_vector[3x1] = rotation[3x3] * vector[3x1] + translation[3x1]

The three values in the vector are given for the a, b, and c axes, respectively.

rtype:

dict[str, Any] | None

spglib.spg.get_symmetry_dataset(cell, symprec=1e-05, angle_tolerance=-1.0, hall_number=0, _throw=False)

Search symmetry dataset from an input cell.

Return type:

SpglibDataset | None

Parameters

cell, symprec, angle_tolerance:

See get_symmetry().

hall_numberint

If a serial number of Hall symbol (>0) is given, the database corresponding to the Hall symbol is made.

The mapping from Hall symbols to a space-group-type is the many-to-one mapping. Without specifying this option (i.e., in the case of hall_number=0), always the first one (the smallest serial number corresponding to the space-group-type in [list of space groups (Seto’s web site)](https://yseto.net/en/sg/sg1)) among possible choices and settings is chosen as default. This argument is useful when the other choice (or setting) is expected to be hooked.

This affects to the obtained values of international, hall, choice, transformation_matrix, origin shift, wyckoffs, std_lattice, std_positions, std_types and std_rotation_matrix, but not to rotations and translations since the later set is defined with respect to the basis vectors of user’s input (the cell argument).

See also Space group type.

Returns

dataset: SpglibDataset | None

If it fails, None is returned. Otherwise a dictionary is returned. More details are found at Spglib dataset.

spglib.spg.get_symmetry_from_database(hall_number)

Return symmetry operations corresponding to a Hall symbol. If fails, return None.

Return type:

dict[str, Any] | None

Parameters

hall_numberint

The Hall symbol is given by the serial number in between 1 and 530. The definition of hall_number is found at Space group type.

Returns

symmetrydict

• rotations

  Rotation parts of symmetry operations corresponding to hall_number.

• translations

  Translation parts of symmetry operations corresponding to hall_number.