PaperlayerView exact revision on arXiv

Source-linked AI summary

$\texttt{Spglib}$: a software library for crystal symmetry search

Atsushi Togo, Kohei Shinohara, Isao Tanaka

arXiv:1808.01590v2cond-mat.mtrl-sci

TL;DR

Crystal-symmetry identification is difficult when structures use non-standard settings or contain slight distortions. The paper describes spglib’s iterative tolerance-based algorithm, which searches operations, identifies space-group types, and validates them against crystallographic constraints. The implementation is designed to identify and symmetrize distorted crystal structures while clarifying the current codebase for developers.

  • Problem

    Space-group identification becomes challenging for non-standard basis choices, arbitrary origin shifts, and slightly distorted crystal structures.

  • Method

    spglib iteratively searches translations and space-group operations, identifies the space-group type, and adjusts tolerance until crystallographic constraints are satisfied.

  • Results

    The code identifies and symmetrizes crystal structures from basis vectors, atomic coordinates, and atomic types while tolerating slight distortion.

  • Takeaways & Limitations

    The paper provides a detailed account of spglib’s implementation strategy to support understanding and continued maintenance of a widely used symmetry library.

Abstract

from arXiv · show

A computer algorithm to search symmetries of crystal structures as implemented in the \texttt{spglib} code is described. An iterative algorithm is employed to robustly identify space group types tolerating a certain amount of distortion in the crystal structures. The source code is distributed under the 3-Clause BSD License, a permissive open-source software license. This paper focuses on the algorithm for identifying the space group symmetry of the crystal structures.

I. INTRODUCTION

Crystal symmetry assigns each periodic crystal structure to one of 230 space-group types, but identifying it is difficult for non-standard settings and distorted coordinates. spglib addresses this with an iterative, tolerance-based algorithm for searching operations and identifying space-group types.

  • Motivation: Crystal symmetry comprises operations mapping a crystal structure onto itself, forming a space group with 230 possible types.Each crystal structure is uniquely assigned to one space-group type.
  • Motivation: Non-standard basis choices, arbitrary origin shifts, and slight structural distortions make computational space-group identification challenging.spglib was developed to address these representation and distortion difficulties.
  • Related software: spglib is open-source software distributed under the permissive 3-clause BSD license.The paper positions spglib alongside existing crystal-symmetry codes and libraries.
  • Contribution: The algorithm searches space-group operations while tolerating small deviations of atomic positions from ideal locations.It also derives coset representatives of the space group relative to the translation group and other crystal-symmetry information.
  • Algorithm overview: An iterative procedure uses a distance tolerance and proceeds through primitive-cell search, operation search, space-group-type identification, and finalization.The process continues until crystallographic constraints are satisfied with minimum adjustment of the tolerance.
  • Scope: The paper focuses on algorithms for searching space-group operations and identifying space-group types, excluding the magnetic-space-group algorithm.The magnetic-space-group algorithm is described as building upon the space-group framework.

IV. PRIMITIVE CELL SEARCH

The primitive cell search identifies pure translations, selects a right-handed primitive basis, transforms coordinates, and averages translationally equivalent atoms while adjusting tolerance for distortions.

  • Pure translation search: The algorithm first searches pure translation operations to determine lattice points and identify whether the input cell is primitive.A primitive input cell should yield only the identity translation; otherwise, multiple pure translations are obtained.
  • Pure translation search: Candidate translations are generated from vectors between same-type atomic sites, using an atom type with the fewest occurrences to reduce computational demand.Each candidate is tested against the atomic equivalence condition across the relevant sites.
  • Pure translation search: O(N^3) brute-force translation search is empirically reduced to O(N^2 log N) by sorting atoms, although this step remains the most computationally demanding.Here, N denotes the number of atoms of the selected type.
  • Primitive basis selection: Primitive-cell basis candidates are selected from input-cell basis vectors and pure translations, constrained to form a right-handed cell with volume approximately Vi divided by |Tp|.The number of pure translations determines the expected volume relationship between the input and primitive cells.
  • Primitive-cell finalization: The selected primitive basis is Delaunay-reduced, coordinates are mapped into the primitive cell with tolerance-adjusted multiplicity checks, and equivalent positions are averaged.If verification fails, the procedure tightens the tolerance and restarts; successful verification produces the primitive cell.

V. SPACE GROUP OPERATION SEARCH

The space-group operation search exhaustively generates lattice point-group candidates, tests metric compatibility and atomic mappings, and retains operations that satisfy the symmetry condition.

  • Lattice point-group search: A candidate lattice operation is accepted when rotating the metric tensor preserves basis-vector lengths and angles within the distance tolerance.The diagonal metric elements encode lengths, while off-diagonal elements encode angles; angle tolerance can be approximated from the distance tolerance.
  • Space-group operation search: For each retained rotation, translation candidates are formed from mappings between same-type atoms and tested against the atomic equivalence condition.For a fixed atom, candidate targets are restricted to atoms of the same type to limit the search space.
  • Space-group operation search: A rotation is discarded if no valid translation part is found; otherwise, the resulting rotation-translation pair is adopted as a space-group operation.The procedure repeats over all lattice point-group rotations and then verifies that the operations form coset representatives of S/T.

VI. IDENTIFICATION OF SPACE GROUP TYPE

The algorithm identifies a space-group type by matching searched operations to Hall-symbol representations after transforming the primitive cell into a conventional setting and determining the origin shift.

  • Hall-symbol matching: The searched space-group operations are compared with Hall-symbol representations after transforming the primitive cell to a specified conventional setting.The matching process simultaneously determines the origin shift.
  • Point-group identification: The crystallographic point-group type is identified from the traces and determinants of the rotation parts of the searched space-group operations.If identification fails, the algorithm tightens the tolerance and restarts the procedure from primitive-cell search.
  • Conventional-cell transformation: The Laue class, obtained from the crystal class, supplies the information needed to transform primitive-cell basis vectors into conventional-cell basis vectors.The transformation is further adjusted to a specified centering type using correction matrices.
  • Conventional-cell transformation: Axis directions for conventional-cell construction are determined from characteristic rotation axes and their rotation orders for each Laue class.The primary, secondary, and ternary axes are selected according to the class-specific conditions summarized in Table I.
  • Conventional-cell transformation: Correction matrices standardize centering, including conversions among I, A, B, and C settings and the obverse or reverse rhombohedral settings.For the rhombohedral system, the integer transformation is selected between the obverse and reverse alternatives.

C. Step (j): Identification of Hall symbol

Step (j) identifies the Hall symbol by transforming the numerically found space-group operations into a matching conventional-cell representation and comparing them with predecoded datasets. The procedure determines the origin shift and verifies the operation mapping before reconstructing the input-cell representation.

  • C. Step (j): Identification of Hall symbol: The 530 predecoded Hall-symbol matrix-representation sets provide the reference datasets for identifying the space group.Hall symbols encode explicit-origin space-group notation, and the datasets are stored in the spglib source code.
  • C. Step (j): Identification of Hall symbol: Space-group operations are transformed into a specific conventional unit-cell setting so their rotation matrices can be compared directly with the datasets.The transformation uses M′M and, when needed, an additional change-of-basis matrix Q′ to select compatible axis settings.
  • C. Step (j): Identification of Hall symbol: For centered systems, operations are further transformed with P_X, whose subscript denotes the centering type, before comparison with the Hall-symbol data.The transformation matrices cover A, B, C, I, F, and R centering types.
  • C. Step (j): Identification of Hall symbol: The origin shift is determined from generator operations by solving the corresponding matrix equation, using at most three generator representations.The solution set is obtained through the Smith normal form of the resulting matrix system.
  • C. Step (j): Identification of Hall symbol: The Hall symbol is identified by verifying that the transformed operations, including their translation parts, map onto the dataset operations.After identification, the primitive-cell basis vectors and origin shift are transformed for subsequent use.

D. Step (k): Failure of identification of space group type

When Hall-symbol identification fails, spglib reduces the tolerance and re-examines the operations, repeating the matching procedure until identification succeeds. Later stages reconstruct and regularize the crystal representation using the accepted symmetry.

  • D. Step (k): Failure of identification of space group type: A failed Hall-symbol match triggers tolerance reduction and re-examination of the current space-group operations.If repeated retries fail, the full procedure restarts from step (a) with a shorter tolerance.
  • D. Step (k): Failure of identification of space group type: The shortened-tolerance re-examination is cheaper than the full search because the existing translation parts are reused.Some operations may be excluded before the procedure returns to the matching stage.
  • D. Step (k): Failure of identification of space group type: The algorithm reconstructs input-unit-cell operations and determines Wyckoff positions and a distortion-free conventional-cell structure after the preceding stages.The reconstruction uses the transformation matrix, origin shift, and Hall-symbol dataset while minimizing translational distortions.
  • D. Step (k): Failure of identification of space group type: Symmetry-equivalent basis-vector lengths are averaged to remove tolerance-induced distortion and align the conventional cell with the expected lattice-system conditions.The adjusted basis vectors represent the idealized conventional unit cell.
  • D. Step (k): Failure of identification of space group type: Hall-symbol operations are transformed between dataset, primitive-cell, and input-cell representations, with non-integer input-cell rotation matrices excluded.For nonprimitive input cells, the operation set is extended using the input cell’s lattice-point vectors.
  • D. Step (k): Failure of identification of space group type: The method may replace the conventional basis by an equivalent rotated choice and select the one minimizing the relevant coordinate-system expression.For centered conventional cells, the choice yielding the shortest transformed origin shift is employed.

C. Step (o): Removal of distortion from point coordinates and determination of Wyckoff positions

Step (o) converts primitive-cell coordinates into the conventional cell, identifies symmetrically independent sites and their equivalent points, and assigns Wyckoff positions. It also corrects slightly displaced coordinates using the detected site symmetry.

  • C. Step (o): Removal of distortion from point coordinates and determination of Wyckoff positions: Primitive-cell point coordinates are transformed into conventional-cell coordinates before symmetry-equivalent point sets are generated.Applying the Hall-symbol operations yields symmetrically independent points and their equivalent sets.
  • C. Step (o): Removal of distortion from point coordinates and determination of Wyckoff positions: Site symmetry operations are the space-group operations that leave a conventional-cell point coordinate unchanged.These operations are expected to form the finite site symmetry group S_x.
  • C. Step (o): Removal of distortion from point coordinates and determination of Wyckoff positions: The exact position x_S of a slightly displaced point is obtained from the site-symmetry-based special position operator.The implementation derives site symmetry operations from the coset representatives of the conventional-cell translation group.
  • C. Step (o): Removal of distortion from point coordinates and determination of Wyckoff positions: Multiplicity M_x counts the symmetrically equivalent points in the conventional unit cell, not the primitive cell.The independent points are expanded to their symmetrically equivalent points after the corrected positions are obtained.
  • C. Step (o): Removal of distortion from point coordinates and determination of Wyckoff positions: The Wyckoff letter is assigned by matching the corrected independent point against stored Wyckoff-position coordinates for the identified Hall symbol.The dataset also stores the multiplicity used to verify the assignment.

VIII. SUMMARY

The paper explains the current spglib implementation for identifying and symmetrizing slightly distorted crystal structures. It also notes that accumulated technical debt has made maintenance harder and motivates future major updates.

  • VIII. SUMMARY: spglib identifies and symmetrizes crystal structures from basis vectors, point coordinates, and atomic types while tolerating slight distortion.Its numerical symmetry search validates operations and adjusts the input tolerance to match a space-group type.
  • VIII. SUMMARY: The paper aims to clarify the implementation strategy of the current spglib version because incremental improvements have reduced source-code readability.It therefore describes the implementation in detail for readers seeking to understand the framework.
  • VIII. SUMMARY: Accumulated technical debt has complicated code maintenance and necessitates periodic major updates.The stated response is to select suitable programming languages for different situations while keeping the core concise and efficient.

Appendix A: Notations and conventions

The appendix defines numerical representations for crystal geometry and symmetry operations. It introduces metric-tensor constraints for lattice point-group operations and the rotation–translation form of space-group operations.

  • Representations: Basis vectors and atomic coordinates are represented numerically in Cartesian and unit-cell-relative coordinates.The notation establishes basis vectors, point coordinates, and their Cartesian position vectors.
  • Metric tensor: The metric tensor represents the geometry of the basis vectors and transforms consistently when the basis changes.It is used to express geometric relationships independently of a particular basis representation.
  • Lattice symmetry: Lattice point-group operations are integer matrices W satisfying G = W^T G W with determinant 1 or −1.These matrices preserve the metric tensor while allowing proper and improper operations.
  • Space-group operations: A space-group operation combines an integer rotation matrix W with a translation vector w and maps x to an equivalent point modulo lattice translation.The operation is represented by the Seitz symbol (W, w).

5. Transformation of coordinate system (P , p)

The coordinate-system transformation (P, p) changes the basis and origin used to represent a crystal without rotating or moving the crystal in Cartesian space. The resulting matrix representations can then be transformed and classified using crystallographic conventions.

  • Coordinate transformation: The pair (P, p) changes the basis vectors through P and shifts the coordinate origin through p.The transformation relates primitive and conventional bases as examples of different coordinate choices.
  • Origin shift: Changing the origin changes how point coordinates are measured but does not move the crystal in Cartesian coordinates.The transformed and original coordinate descriptions are related by the coordinate transformation equations.
  • Classification: The crystallographic point-group type is identified from rotation-matrix traces and determinants, then mapped to crystal classes using rotation-type counts.The corresponding lookup procedures use Tables V and VI.
  • Basis transformation: Space-group operation matrices are transformed between basis choices using a change-of-basis matrix Q.This allows operations in primitive and non-primitive settings to be compared in a common representation.
  • Transformation boundary: If a basis transformation breaks the primitive cell’s point-group symmetry, the transformed rotation matrix becomes non-integer.This occurs when the lattice point-group types of the primitive and non-primitive bases are not equivalent.

basis vectors

The spglib convention idealizes crystal structures with fixed basis-vector choices and orientation constraints for each crystal system. These conventions provide standardized representations for subsequent symmetry analysis.

  • Conventions: The spglib code uses crystal-system-specific conventions to idealize input crystal structures.The conventions specify basis lengths, angles, axis choices, and Cartesian orientations.
  • Triclinic: For the triclinic system, a Niggli-reduced cell is chosen, with a along +x and b in the x-y plane.The orientation also ensures a×b aligns with +z.
  • Monoclinic: For the monoclinic system, b is the unique axis, α and γ are 90°, β lies between 90° and 120°, and the axes receive fixed Cartesian orientations.The vector c is positioned in the x-z plane.
  • Orthorhombic: For the orthorhombic system, all angles are 90° and a, b, and c align with the Cartesian x, y, and z axes.This fixes both the cell geometry and its orientation.
  • Trigonal: For the trigonal system, a = b = c and α = β = γ, with projected vectors constrained to specified 120° angular relationships.The projections also have equal lengths and equal z components.
  • Hexagonal: For the hexagonal system, α and β are 90°, γ is 120°, a equals b, and c is aligned with +z.The basal vectors are oriented in the x-y plane.

7. Cubic

The cubic convention uses equal basis lengths and right angles aligned with Cartesian axes, then applies coordinate and origin transformations to preserve equivalent space-group representations. The cited references document related crystallographic software and methods.

  • 7. Cubic: A space-group operation preserves the set of crystal point coordinates up to lattice translation when expressed in the transformed coordinate system.Consequently, the same matrix representations apply to the transformed point set.
  • 7. Cubic: An origin shift is related to the original coordinates through the transformed coordinates, and the new origin shift is obtained by setting the shifted coordinates to zero.This establishes how origin changes are represented after a coordinate transformation.
  • References: The section cites prior work and software resources including crystallographic toolboxes, symmetry codes, and the spglib source repository.The references include cctbx, AFLOW-SYM, and the spglib version 2.3.1 repository.
Loading 1808.01590v2…