Source code for ase2sprkkr.bindings.spglib

"""Small, single-purpose spglib binding used by SPR-KKR symmetry workflows."""

from dataclasses import dataclass

import numpy as np
import spglib
from ase.geometry import find_mic

try:
    from spglib.error import SpglibError
except ImportError:
    # Before spglib 2.7 the public API returned None on symmetry-search
    # failure rather than raising SpglibError.
    class SpglibError(Exception):
        pass


[docs] class _SpglibCompatibilityWrapper: """Provide attribute access to datasets returned as dicts by old spglib."""
[docs] def __init__(self, dataset): self.dataset = dataset
def __getattr__(self, name): # Avoid recursion if an unpickled instance is not initialized yet. try: dataset = self.__dict__["dataset"] except KeyError: raise AttributeError(name) from None try: return dataset[name] except KeyError: raise AttributeError(name) from None
[docs] @classmethod def create_if_needed(cls, dataset): if dataset is None or hasattr(dataset, "equivalent_atoms"): return dataset return cls(dataset)
[docs] @dataclass(frozen=True) class TransformedCell: """Geometry and species labels in the order supplied by spglib.""" cell: np.ndarray scaled_positions: np.ndarray tags: np.ndarray
[docs] def symmetry_dataset(cell, scaled_positions, site_tags, *, symprec=1e-5, angle_tolerance=-1.0): """Find a space-group dataset for explicitly classified atomic sites.""" try: dataset = spglib.get_symmetry_dataset( (cell, scaled_positions, site_tags), symprec=symprec, angle_tolerance=angle_tolerance, ) except SpglibError as exc: raise ValueError(f"spglib symmetry search failed: {exc}") from exc if dataset is None: raise ValueError("spglib could not determine the space-group symmetry") return _SpglibCompatibilityWrapper.create_if_needed(dataset)
[docs] def transform_cell( cell, scaled_positions, tags, *, to_primitive=False, symprec=1e-5, angle_tolerance=-1.0, ): """Standardize without idealization, retaining the spglib species labels. Every output tag identifies the source SiteType/occupation class. Site metadata transfer is independent of origin, orientation, and atom order. """ try: result = spglib.standardize_cell( (cell, scaled_positions, tags), to_primitive=to_primitive, no_idealize=True, symprec=symprec, angle_tolerance=angle_tolerance, ) except SpglibError as exc: raise ValueError(f"spglib cell standardization failed: {exc}") from exc if result is None: raise ValueError("spglib could not standardize the unit cell") # spglib already returns NumPy arrays with the required numeric dtypes. return TransformedCell(*result)
[docs] def primitive_site_groups(cell, scaled_positions, tags, dataset, transformed, *, symprec=1e-5): """Relate each output atom to its input primitive translation class. mapping_to_primitive distinguishes inequivalent primitive sites, unlike the chemical-species tags. Match in Cartesian coordinates modulo the primitive lattice, without assuming that numeric primitive IDs of independently generated cells have identical meaning. The no_idealize=True output retains the input Cartesian origin and orientation. """ # Only normalize caller-provided inputs; dataset fields are ndarrays. cell = np.asarray(cell, dtype=float) positions = np.asarray(scaled_positions, dtype=float) tags = np.asarray(tags) primitive_ids = dataset.mapping_to_primitive if len(primitive_ids) != len(tags): raise ValueError("Invalid spglib mapping_to_primitive length") classes = {} for i, primitive_id in enumerate(primitive_ids): classes.setdefault(int(primitive_id), []).append(i) input_cart = positions @ cell output_cart = transformed.scaled_positions @ transformed.cell primitive_cell = dataset.primitive_lattice by_tag = {} for group in classes.values(): values = {int(tags[i]) for i in group} if len(values) != 1: raise ValueError("A primitive site contains multiple species") by_tag.setdefault(values.pop(), []).append(group) output_groups = [] tolerance = max(5 * symprec, 1e-7) for output_index, (point, tag) in enumerate(zip(output_cart, transformed.tags)): possible = by_tag.get(int(tag), []) if not possible: raise ValueError(f"Unknown output species tag {tag}") representatives = [group[0] for group in possible] _, distances = find_mic( input_cart[representatives] - point, cell=primitive_cell, pbc=True ) best = int(np.argmin(distances)) if distances[best] > tolerance: raise ValueError( f"Cannot map transformed atom {output_index} to a primitive site: " f"nearest distance {distances[best]:g} Å" ) if np.count_nonzero(distances <= tolerance) != 1: raise ValueError(f"Ambiguous primitive class for transformed atom {output_index}") output_groups.append(possible[best]) return output_groups
[docs] def symmetry_site_permutations( cell, scaled_positions, tags, rotations, translations, *, symprec=1e-5 ): """Return the atomic permutation for each space-group operation. The same periodic, species-aware matching is used by both metric/site idealization and SpacegroupInfo.kto_kyda_table. """ cell = np.asarray(cell, dtype=float) positions = np.asarray(scaled_positions, dtype=float) tags = np.asarray(tags) by_tag = {tag: np.flatnonzero(tags == tag) for tag in np.unique(tags)} table = np.empty((len(rotations), len(positions)), dtype=int) tolerance = max(2 * symprec, 1e-8) for g, (rotation, translation) in enumerate(zip(rotations, translations)): for i, (position, tag) in enumerate(zip(positions, tags)): transformed = position @ rotation.T + translation candidates = by_tag[tag] _, distances = find_mic( (positions[candidates] - transformed) @ cell, cell=cell, pbc=True ) j = int(np.argmin(distances)) if distances[j] > tolerance: raise ValueError( f"Cannot map operation {g}, site {i} within {tolerance:g} Å" ) table[g, i] = candidates[j] if len(set(table[g])) != len(positions): raise ValueError(f"Operation {g} does not permute all sites") return table
[docs] def idealize_cell(cell, scaled_positions, tags, dataset, *, symprec=1e-5): """Symmetrize lattice metric and atomic positions in the ORIGINAL basis. The metric is projected onto the point-group-invariant subspace. For each atomic image, the inverse symmetry operation maps it back near its source site; minimum-image displacements are then averaged. This keeps the incoming basis setting, atom count, and ordering. """ cell = np.asarray(cell, dtype=float) positions = np.asarray(scaled_positions, dtype=float) tags = np.asarray(tags) rotations = dataset.rotations translations = dataset.translations metric = cell @ cell.T sym_metric = np.mean( [rotation.T @ metric @ rotation for rotation in rotations], axis=0 ) sym_metric = 0.5 * (sym_metric + sym_metric.T) def symmetric_root(matrix, inverse=False): eigenvalues, eigenvectors = np.linalg.eigh(matrix) if np.any(eigenvalues <= 0): raise ValueError("A positive-definite lattice metric is required") powers = eigenvalues ** (-0.5 if inverse else 0.5) return (eigenvectors * powers) @ eigenvectors.T metric_change = not np.allclose( metric, sym_metric, rtol=1e-10, atol=1e-10 ) # Preserve an already symmetric lattice exactly, avoiding round-off from # reconstructing it through two eigendecompositions. new_cell = ( symmetric_root(sym_metric) @ symmetric_root(metric, inverse=True) @ cell if metric_change else cell.copy() ) inverse_cell = np.linalg.inv(cell) delta_sum = np.zeros_like(positions) permutations = symmetry_site_permutations( cell, positions, tags, rotations, translations, symprec=symprec ) for rotation, translation, mapping in zip(rotations, translations, permutations): inverse_rotation = np.linalg.inv(rotation.T) for i, j in enumerate(mapping): back = (positions[j] - translation) @ inverse_rotation correction, _ = find_mic( (back - positions[i]) @ cell, cell=cell, pbc=True ) delta_sum[i] += correction @ inverse_cell ideal_positions = (positions + delta_sum / len(rotations)) % 1.0 # Compare displacement, not modulo-wrapped coordinates. displacement = np.linalg.norm((delta_sum / len(rotations)) @ cell, axis=1) geometry_changed = metric_change or bool(np.any(displacement > 1e-8)) return TransformedCell(new_cell, ideal_positions, tags.copy()), geometry_changed