soprano.properties.symmetry.backend

soprano.properties.symmetry.backend#

backend.py

Backend-agnostic symmetry analysis for ase.Atoms structures.

Two backends are supported: spglib (the original dependency) and moyo (moyopy, a faster Rust-based successor to spglib). The active backend is chosen with the backend keyword argument accepted by every public function:

  • "auto" – use moyopy if installed, else spglib (default)

  • "moyo" – always use moyopy (raises ImportError if not installed)

  • "spglib" – always use spglib (raises ImportError if not installed)

The two public entry points are:

Functions

get_symmetry_dataset(atoms, *[, symprec, ...])

Return a SpacegroupDataset for atoms.

get_symmetry_ops_from_hall(hall_no, *[, backend])

Return (rotations, translations) for a given Hall number.

resolve_backend(backend)

Resolve "auto" to the best available concrete backend.

Classes

SpacegroupDataset(international, ...[, ...])

Backend-agnostic symmetry dataset for a periodic structure.
class soprano.properties.symmetry.backend.SpacegroupDataset(international, hall_number, std_lattice, transformation_matrix, origin_shift, rotations, translations, equivalent_atoms=<factory>, _raw=None)[source]#

Bases: object

Backend-agnostic symmetry dataset for a periodic structure.

All fields mirror the subset of the spglib symmetry dataset that is used inside Soprano. The _raw attribute holds the native backend object (spglib.SpglibDataset or moyopy.MoyoDataset) for callers that need backend-specific fields.

Parameters:

  • international (str) – Hermann-Mauguin space-group symbol (no spaces), e.g. "P-1".

  • hall_number (int) – Hall symbol number (1–530).

  • std_lattice (numpy.ndarray) – Lattice vectors of the standardised conventional cell, shape (3, 3), each row is a lattice vector (same convention as spglib).

  • transformation_matrix (numpy.ndarray) – Linear part of the transformation from the input cell to the standardised cell (spglib transformation_matrix / moyopy std_linear), shape (3, 3).

  • origin_shift (numpy.ndarray) – Origin shift of the transformation, shape (3,).

  • rotations (numpy.ndarray) – Rotation matrices of all symmetry operations in the input cell, shape (N, 3, 3).

  • translations (numpy.ndarray) – Translation vectors of all symmetry operations in the input cell, shape (N, 3).

  • _raw (object) – The raw dataset object returned by the backend. Not included in repr.

  • equivalent_atoms (ndarray)

soprano.properties.symmetry.backend.get_symmetry_dataset(atoms, *, symprec=1e-05, backend='auto')[source]#

Return a SpacegroupDataset for atoms.

Parameters:

  • atoms – An ase.Atoms object representing a periodic structure.

  • symprec (float) – Distance tolerance in Ångströms for symmetry search.

  • backend (Literal['auto', 'spglib', 'moyo']) – Symmetry backend to use: "auto" (default), "spglib", or "moyo".

Return type:

SpacegroupDataset

soprano.properties.symmetry.backend.get_symmetry_ops_from_hall(hall_no, *, backend='auto')[source]#

Return (rotations, translations) for a given Hall number.

The operations are those of the conventional cell for the space group identified by hall_no.

Parameters:

  • hall_no (int) – Hall symbol number (1–530).

  • backend (Literal['auto', 'spglib', 'moyo']) – Symmetry backend to use: "auto" (default), "spglib", or "moyo".

Returns:

  • rotations (np.ndarray, shape (N, 3, 3))

  • translations (np.ndarray, shape (N, 3))

Return type:

tuple[ndarray, ndarray]

soprano.properties.symmetry.backend.resolve_backend(backend)[source]#

Resolve "auto" to the best available concrete backend.

Parameters:

backend (Literal['auto', 'spglib', 'moyo']) – One of "auto", "spglib", "moyo".

Returns:

Either "spglib" or "moyo".

Return type:

str

Raises:

  • ValueError – If backend is not one of the recognised values.

  • ImportError – If the requested backend (or any backend, when "auto") is not installed.

Contents