spglib package

Contents

spglib package#

Python bindings for C library for finding and handling crystal.

class spglib.MagneticSpaceGroupType(uni_number, litvin_number, bns_number, og_number, number, type)[source]#

Bases: DictInterface

Magnetic space group type information.

Added in version 2.5.0.

_abc_impl = <_abc._abc_data object>#
bns_number: str#

BNS number e.g. ‘151.32’

litvin_number: int#

Serial number in Litvin’s [Magnetic group tables](https://www.iucr.org/publ/978-0-9553602-2-0)

number: int#

ITA’s serial number of space group for reference setting

og_number: str#

OG number e.g. ‘153.4.1270’

type: int#

Type of MSG from 1 to 4

uni_number: int#

Serial number of UNI (or BNS) symbols

class spglib.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)[source]#

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

class spglib.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)[source]#

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.

exception spglib.SpglibError[source]#

Bases: Exception

Base exception type for all errors raised by spglib.

Use this error type in a try ... except to process any physical or other spglib defined errors, such as the number of atom types not matching the positions or the distance between atoms being too close. For example:

symprec = 1e-10
while (symprec<1):
    try:
        dataset = spglib.get_symmetry(cell, symprec)
    except spglib.SpglibError as exc:
        # Expected issues by spglib
        # Try again if the symprec was too tight
        if str(exc) == "too close distance between atoms":
            symprec *= 10
            continue
        # Otherwise fail gracefully
        print(f"Failed to calculate symmetry:\n{exc}")
        break
    except Exception:
        # Unexpected issues, raise as an unexpected exception
        raise

Note

More fine-grained exceptions are not defined yet. Please provide feedback on what kind of exception separation would be desired.

class spglib.SpglibMagneticDataset(uni_number, msg_type, hall_number, tensor_rank, n_operations, rotations, translations, time_reversals, n_atoms, equivalent_atoms, transformation_matrix, origin_shift, n_std_atoms, std_lattice, std_types, std_positions, std_tensors, std_rotation_matrix, primitive_lattice)[source]#

Bases: DictInterface

Spglib magnetic dataset information.

See Magnetic Spglib dataset (Experimental) in detail.

Added in version 2.5.0.

_abc_impl = <_abc._abc_data object>#
equivalent_atoms: ndarray[tuple[Any, ...], dtype[int32]]#

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

hall_number: int#

For type-I, II, III, Hall number of FSG; for type-IV, that of XSG

msg_type: int#

Magnetic space groups (MSG) is classified by its family space group (FSG) and maximal space subgroup (XSG).

FSG is a non-magnetic space group obtained by ignoring time-reversal term in MSG. XSG is a space group obtained by picking out non time-reversal operations in MSG.

  • msg_type==1 (type-I):

    MSG, XSG, FSG are all isomorphic.

  • msg_type==2 (type-II):

    XSG and FSG are isomorphic, and MSG is generated from XSG and pure time reversal operations.

  • msg_type==3 (type-III):

    XSG is a proper subgroup of MSG with isomorphic translational subgroups.

  • msg_type==4 (type-IV):

    XSG is a proper subgroup of MSG with isomorphic point group.

n_atoms: int#

Number of atoms in the input cell

n_operations: int#

Number of magnetic symmetry operations

n_std_atoms: int#

Number of atoms in standardized unit cell

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

Origin shift from standardized to input origin

shape: (3, )

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

Basis vectors of primitive lattice.

shape: (3, 3)

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

Rotation (matrix) parts of symmetry operations

shape: (n_operations, 3, 3)

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

Row-wise lattice vectors of the standardized unit cell

shape: (3, 3)

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

Fractional coordinates of atoms in the standardized unit cell

shape: (n_std_atoms, 3)

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

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

std_tensors: ndarray[tuple[Any, ...], dtype[float64]]#
shape:

(n_std_atoms, ) for collinear magnetic moments. (n_std_atoms, 3) for vector non-collinear magnetic moments.

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

Identity numbers of atoms in the standardized unit cell

shape: (n_std_atoms, )

tensor_rank: int#

Rank of magmoms.

time_reversals: ndarray[tuple[Any, ...], dtype[int32]]#

Time reversal part of magnetic symmetry operations.

True indicates time reversal operation, and False indicates an ordinary operation.

shape: (n_operations, )

transformation_matrix: ndarray[tuple[Any, ...], dtype[int32]]#

Transformation matrix from input lattice to standardized

shape: (3, 3)

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

Translation (vector) parts of symmetry operations

shape: (n_operations, 3)

uni_number: int#

UNI number between 1 to 1651

spglib.delaunay_reduce(lattice, eps=1e-05)[source]#

Run Delaunay reduction. When the search failed, None is returned.

The transformation from original basis vectors \(( \mathbf{a} \; \mathbf{b} \; \mathbf{c} )\) to final basis vectors \(( \mathbf{a}' \; \mathbf{b}' \; \mathbf{c}' )\) is achieved by linear combination of basis vectors with integer coefficients without rotating coordinates. Therefore the transformation matrix is obtained by \(\mathbf{P} = ( \mathbf{a} \; \mathbf{b} \; \mathbf{c} ) ( \mathbf{a}' \; \mathbf{b}' \; \mathbf{c}' )^{-1}\) and the matrix elements have to be almost integers.

The algorithm is found in the international tables for crystallography volume A.

Parameters#

lattice: ndarray, (3, 3)

Lattice parameters in the form of

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

Tolerance parameter, but unlike symprec the unit is not a length. Tolerance to check if volume is close to zero or not and if two basis vectors are orthogonal by the value of dot product being close to zero or not.

Returns#

delaunay_lattice: ndarray, (3, 3)

Reduced lattice parameters are given as a numpy ‘double’ array:

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

Notes#

Added in version 1.9.4.

spglib.find_primitive(cell, symprec=1e-05, angle_tolerance=-1.0)[source]#

Primitive cell is searched in the input cell. If it fails, None is returned.

The primitive cell is returned by a tuple of (lattice, positions, numbers).

Return type:

tuple[Sequence[Sequence[float]], Sequence[Sequence[float]], Sequence[int]] | None

Notes#

Changed in version 1.8.

The detailed control of standardization of unit cell can be done using standardize_cell().

spglib.get_BZ_grid_points_by_rotations(address_orig, reciprocal_rotations, mesh, bz_map, is_shift=None, is_dense=False)[source]#

Return grid points obtained after rotating input grid address.

Parameters#

address_origarray_like

Grid point address to be rotated. dtype=’intc’, shape=(3,)

reciprocal_rotationsarray_like

Rotation matrices {R} with respect to reciprocal basis vectors. Defined by q’=Rq. dtype=’intc’, shape=(rotations, 3, 3)

mesharray_like

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

bz_maparray_like

TODO

is_shiftarray_like, optional

With (1) or without (0) half grid shifts with respect to grid intervals sampled along reciprocal basis vectors. Default is None, which gives [0, 0, 0].

is_densebool, optional

rot_grid_points is returned with dtype=’uintp’ if True. Otherwise its dtype=’intc’. Default is False.

Returns#

rot_grid_pointsndarray

Grid points obtained after rotating input grid address dtype=’intc’ or ‘uintp’, shape=(rotations,)

spglib.get_error_message()[source]#

Return error message why spglib failed.

Warning

This method is not thread safe, i.e., only safely usable when calling one spglib method per process.

Added in version 1.9.5.

Deprecated since version 2.7.0.

Return type:

str

spglib.get_grid_point_from_address(grid_address, mesh)[source]#

Return grid point index by translating grid address.

spglib.get_grid_points_by_rotations(address_orig, reciprocal_rotations, mesh, is_shift=None, is_dense=False)[source]#

Return grid points obtained after rotating input grid address.

Parameters#

address_origarray_like

Grid point address to be rotated. dtype=’intc’, shape=(3,)

reciprocal_rotationsarray_like

Rotation matrices {R} with respect to reciprocal basis vectors. Defined by q’=Rq. dtype=’intc’, shape=(rotations, 3, 3)

mesharray_like

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

is_shiftarray_like, optional

With (1) or without (0) half grid shifts with respect to grid intervals sampled along reciprocal basis vectors. Default is None, which gives [0, 0, 0].

is_densebool, optional

rot_grid_points is returned with dtype=’uintp’ if True. Otherwise its dtype=’intc’. Default is False.

Returns#

rot_grid_pointsndarray

Grid points obtained after rotating input grid address dtype=’intc’ or ‘uintp’, shape=(rotations,)

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.

spglib.get_ir_reciprocal_mesh(mesh, cell, is_shift=None, is_time_reversal=True, symprec=1e-05, is_dense=False)[source]#

Return k-points mesh and k-point map to the irreducible k-points.

The symmetry is searched from the input cell.

Parameters#

mesharray_like

Uniform sampling mesh numbers. dtype=’intc’, shape=(3,)

cellspglib cell tuple

Crystal structure.

is_shiftarray_like, optional

[0, 0, 0] gives Gamma center mesh and value 1 gives half mesh shift. Default is None which equals to [0, 0, 0]. dtype=’intc’, shape=(3,)

is_time_reversalbool, optional

Whether time reversal symmetry is included or not. Default is True.

symprecfloat, optional

Symmetry tolerance in distance. Default is 1e-5.

is_densebool, optional

grid_mapping_table is returned with dtype=’uintp’ if True. Otherwise its dtype=’intc’. Default is False.

Returns#

grid_mapping_tablendarray

Grid point mapping table to ir-gird-points. dtype=’intc’ or ‘uintp’, shape=(prod(mesh),)

grid_addressndarray

Address of all grid points. dtype=’intc’, shape=(prod(mesh), 3)

spglib.get_layergroup(cell, aperiodic_dir=2, symprec=1e-05)[source]#

Return layer group in ….

If it fails, None is returned.

Return type:

SpglibDataset | None

spglib.get_magnetic_spacegroup_type(uni_number)[source]#

Translate UNI number to magnetic space group type information.

If fails, return None.

Return type:

MagneticSpaceGroupType | None

Parameters#

uni_numberint

UNI number between 1 to 1651

Returns#

magnetic_spacegroup_type: MagneticSpaceGroupType | None

Notes#

Added in version 2.0.

spglib.get_magnetic_spacegroup_type_from_symmetry(rotations, translations, time_reversals, lattice=None, symprec=1e-05)[source]#

Return magnetic space-group type information from symmetry operations.

Parameters#

rotations, translations, time_reversals:

See returns of get_magnetic_symmetry().

lattice(Optional) array_like (3, 3)

Basis vectors a, b, c given in row vectors. This is used as the measure of distance. Default is None, which gives unit matrix.

symprec: float

See get_symmetry().

Returns#

magnetic_spacegroup_type: MagneticSpaceGroupType | None

spglib.get_magnetic_symmetry(cell, symprec=1e-05, angle_tolerance=-1.0, mag_symprec=-1.0, is_axial=None, with_time_reversal=True, _throw=False)[source]#

Find magnetic symmetry operations from a crystal structure and site tensors.

Return type:

dict[str, Any] | None

Parameters#

celltuple

Crystal structure given either in tuple. In the case given by a tuple, it has to follow the form below,

(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.

  • magmoms:
    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_axial: None or bool

Set is_axial=True if magmoms does not change their sign by improper rotations. If not specified, set is_axial=False when magmoms.shape==(num_atoms, ), and set is_axial=True when magmoms.shape==(num_atoms, 3). These default settings correspond to collinear and non-collinear spins.

with_time_reversal: bool

Set with_time_reversal=True if magmoms change their sign by time-reversal operations. Default is True.

Returns#

symmetry: dict or None

Rotation parts and translation parts of symmetry operations represented with respect to basis vectors and atom index mapping by symmetry operations.

  • ‘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

    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’

  • ‘primitive_lattice’: ndarray

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

Notes#

Added in version 2.0.

spglib.get_magnetic_symmetry_dataset(cell, is_axial=None, symprec=1e-05, angle_tolerance=-1.0, mag_symprec=-1.0)[source]#

Search magnetic symmetry dataset from an input cell. If it fails, return None.

Return type:

SpglibMagneticDataset | None

Parameters#

cell, is_axial, symprec, angle_tolerance, mag_symprec:

See get_magnetic_symmetry().

Returns#

dataset : SpglibMagneticDataset or None

Notes#

Added in version 2.0.

spglib.get_magnetic_symmetry_from_database(uni_number, hall_number=0)[source]#

Return magnetic symmetry operations from UNI number between 1 and 1651.

If fails, return None.

Optionally alternative settings can be specified with Hall number.

Return type:

dict[str, Any] | None

Parameters#

uni_numberint

UNI number between 1 and 1651.

hall_numberint, optional

The Hall symbol is given by the serial number in between 1 and 530.

Returns#

symmetrydict

  • ‘rotations’

  • ‘translations’

  • ‘time_reversals’

    0 and 1 indicate ordinary and anti-time-reversal operations, respectively.

Notes#

Added in version 2.0.

spglib.get_pointgroup(rotations)[source]#

Return point group in international table symbol and number.

The symbols are mapped to the numbers as follows: 1 “1 ” 2 “-1 ” 3 “2 ” 4 “m ” 5 “2/m ” 6 “222 ” 7 “mm2 ” 8 “mmm ” 9 “4 ” 10 “-4 ” 11 “4/m ” 12 “422 ” 13 “4mm ” 14 “-42m ” 15 “4/mmm” 16 “3 ” 17 “-3 ” 18 “32 ” 19 “3m ” 20 “-3m ” 21 “6 ” 22 “-6 ” 23 “6/m ” 24 “622 ” 25 “6mm ” 26 “-62m ” 27 “6/mmm” 28 “23 ” 29 “m-3 ” 30 “432 ” 31 “-43m ” 32 “m-3m “

spglib.get_spacegroup(cell, symprec=1e-05, angle_tolerance=-1.0, symbol_type=0)[source]#

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.get_spacegroup_type(hall_number, _throw=False)[source]#

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.get_spacegroup_type_from_symmetry(rotations, translations, lattice=None, symprec=1e-05)[source]#

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.get_stabilized_reciprocal_mesh(mesh, rotations, is_shift=None, is_time_reversal=True, qpoints=None, is_dense=False)[source]#

Return k-point map to the irreducible k-points and k-point grid points.

The symmetry is searched from the input rotation matrices in real space.

Parameters#

mesharray_like

Uniform sampling mesh numbers. dtype=’intc’, shape=(3,)

rotationsarray_like

Rotation matrices with respect to real space basis vectors. dtype=’intc’, shape=(rotations, 3)

is_shiftarray_like

[0, 0, 0] gives Gamma center mesh and value 1 gives half mesh shift. dtype=’intc’, shape=(3,)

is_time_reversalbool

Time reversal symmetry is included or not.

qpointsarray_like

q-points used as stabilizer(s) given in reciprocal space with respect to reciprocal basis vectors. dtype=’double’, shape=(qpoints ,3) or (3,)

is_densebool, optional

grid_mapping_table is returned with dtype=’uintp’ if True. Otherwise its dtype=’intc’. Default is False.

Returns#

grid_mapping_tablendarray

Grid point mapping table to ir-gird-points. dtype=’intc’, shape=(prod(mesh),)

grid_addressndarray

Address of all grid points. Each address is given by three unsigned integers. dtype=’intc’, shape=(prod(mesh), 3)

spglib.get_symmetry(cell, symprec=1e-05, angle_tolerance=-1.0, mag_symprec=-1.0, is_magnetic=True)[source]#

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.get_symmetry_dataset(cell, symprec=1e-05, angle_tolerance=-1.0, hall_number=0, _throw=False)[source]#

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.get_symmetry_from_database(hall_number)[source]#

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.

spglib.get_symmetry_layerdataset(cell, aperiodic_dir=2, symprec=1e-05, _throw=False)[source]#

TODO: Add comments.

Return type:

SpglibDataset | None

spglib.get_version()[source]#

Return version number of spglib with tuple of three numbers.

Added in version 1.8.3.

Deprecated since version 2.3.0: Use spg_get_version() and spglib.__version__ instead

Return type:

tuple[int, int, int]

spglib.niggli_reduce(lattice, eps=1e-05)[source]#

Run Niggli reduction. When the search failed, None is returned.

The transformation from original basis vectors \(( \mathbf{a} \; \mathbf{b} \; \mathbf{c} )\) to final basis vectors \(( \mathbf{a}' \; \mathbf{b}' \; \mathbf{c}' )\) is achieved by linear combination of basis vectors with integer coefficients without rotating coordinates. Therefore the transformation matrix is obtained by \(\mathbf{P} = ( \mathbf{a} \; \mathbf{b} \; \mathbf{c} ) ( \mathbf{a}' \; \mathbf{b}' \; \mathbf{c}' )^{-1}\) and the matrix elements have to be almost integers.

The algorithm detail is found at https://atztogo.github.io/niggli/ and the references are there in.

Parameters#

lattice: ndarray

Lattice parameters in the form of

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

Tolerance parameter, but unlike symprec the unit is not a length. This is used to check if difference of norms of two basis vectors is close to zero or not and if two basis vectors are orthogonal by the value of dot product being close to zero or not. The detail is shown at https://atztogo.github.io/niggli/.

Returns#

niggli_lattice: ndarray, (3, 3)
if the Niggli reduction succeeded:

Reduced lattice parameters are given as a numpy ‘double’ array:

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

otherwise None is returned.

Notes#

Added in version 1.9.4.

spglib.refine_cell(cell, symprec=1e-05, angle_tolerance=-1.0)[source]#

Return refined cell. When the search failed, None is returned.

The standardized unit cell is returned by a tuple of (lattice, positions, numbers).

Return type:

tuple[Sequence[Sequence[float]], Sequence[Sequence[float]], Sequence[int]] | None

Notes#

Changed in version 1.8.

The detailed control of standardization of unit cell can be done using standardize_cell().

spglib.relocate_BZ_grid_address(grid_address, mesh, reciprocal_lattice, is_shift=None, is_dense=False)[source]#

Grid addresses are relocated to be inside first Brillouin zone.

Number of ir-grid-points inside Brillouin zone is returned. It is assumed that the following arrays have the shapes of

Note that the shape of grid_address is (prod(mesh), 3) and the addresses in grid_address are arranged to be in parallelepiped made of reciprocal basis vectors. The addresses in bz_grid_address are inside the first Brillouin zone or on its surface. Each address in grid_address is mapped to one of those in bz_grid_address by a reciprocal lattice vector (including zero vector) with keeping element order. For those inside first Brillouin zone, the mapping is one-to-one. For those on the first Brillouin zone surface, more than one addresses in bz_grid_address that are equivalent by the reciprocal lattice translations are mapped to one address in grid_address. In this case, those grid points except for one of them are appended to the tail of this array, for which bz_grid_address has the following data storing:

|------------------array size of bz_grid_address-------------------------|
|--those equivalent to grid_address--|--those on surface except for one--|
|-----array size of grid_address-----|

Number of grid points stored in bz_grid_address is returned. bz_map is used to recover grid point index expanded to include BZ surface from grid address. The grid point indices are mapped to (mesh[0] * 2) x (mesh[1] * 2) x (mesh[2] * 2) space (bz_map).

spglib.spg_get_commit()[source]#

Get the commit of the detected spglib C library.

Added in version 2.3.0.

Return type:

str

Returns:

commit string

spglib.spg_get_version()[source]#

Get the X.Y.Z version of the detected spglib C library.

Added in version 2.3.0.

Return type:

str

Returns:

version string

spglib.spg_get_version_full()[source]#

Get the full version of the detected spglib C library.

Added in version 2.3.0.

Return type:

str

Returns:

full version string

spglib.standardize_cell(cell, to_primitive=False, no_idealize=False, symprec=1e-05, angle_tolerance=-1.0)[source]#

Return standardized cell. When the search failed, None is returned.

Return type:

tuple[Sequence[Sequence[float]], Sequence[Sequence[float]], Sequence[int]] | None

Parameters#

cell, symprec, angle_tolerance:

See the docstring of get_symmetry.

to_primitivebool

If True, the standardized primitive cell is created.

no_idealizebool

If True, it is disabled to idealize lengths and angles of basis vectors and positions of atoms according to crystal symmetry.

Returns#

The standardized unit cell or primitive cell is returned by a tuple of (lattice, positions, numbers). If it fails, None is returned.

Notes#

Added in version 1.8.

Now refine_cell() and find_primitive() are shorthands of this method with combinations of these options. About the default choice of the setting, see the documentation of hall_number argument of get_symmetry_dataset(). More detailed explanation is shown in the spglib (C-API) document.

Submodules#

Contents