"""Crystal symmetry analysis without retaining or modifying input Atoms."""
from __future__ import annotations
import copy
import warnings
import numpy as np
from ase import Atoms
from ..bindings.spglib import (
idealize_cell, primitive_site_groups, symmetry_dataset, transform_cell,
)
from .occupations import Occupation
from .site_equivalence import site_equivalence_tags, refine_partial_site_tags
from .sites import Site, SiteType
from .sprkkr_atoms import SPRKKRAtoms
[docs]
class SymmetryError(ValueError):
"""Unable to analyse or transform a crystal."""
[docs]
def _validate(atoms):
if not isinstance(atoms, Atoms):
raise TypeError("Expected an ASE Atoms object")
if len(atoms) == 0 or not np.all(atoms.pbc):
raise SymmetryError("Expected a nonempty, fully periodic 3D structure")
cell = atoms.cell.array
if not np.isfinite(cell).all() or np.linalg.matrix_rank(cell) != 3:
raise SymmetryError("The cell must have three independent finite vectors")
if isinstance(atoms, SPRKKRAtoms) and atoms.regions:
raise SymmetryError("Structures with AtomsRegion are not supported")
[docs]
def _classify_sites(atoms, equivalence, cell, positions, *, symprec, angle_tolerance):
"""Determine spglib species tags without creating or modifying Site objects."""
tags = site_equivalence_tags(atoms, equivalence=equivalence)
source_sites = atoms.arrays.get(SPRKKRAtoms.sites_array_name)
if (
equivalence == "site-types" and source_sites is not None
and any(not site for site in source_sites)
):
preliminary = symmetry_dataset(
cell, positions, tags,
symprec=symprec, angle_tolerance=angle_tolerance,
)
tags = refine_partial_site_tags(tags, preliminary, source_sites)
return tags
[docs]
def _electronic_data_present(atoms):
sites = atoms.arrays.get(SPRKKRAtoms.sites_array_name)
if sites is None:
return False
return any(
atomic_type.potential is not None
or atomic_type.charge is not None
or atomic_type.moments is not None
for site in sites if site
for atomic_type in site.site_type.occupation.atomic_types()
)
[docs]
def _warn_electronic_data():
warnings.warn(
"Idealization changed the geometry; copied SPR-KKR electronic data "
"may require a new SCF calculation.",
RuntimeWarning, stacklevel=3,
)
[docs]
def _make_sites(atoms, result, source_indices, dataset):
"""Copy existing SPR-KKR sites, or create new sites for ordinary ASE atoms.
This function only reads the source. It never initializes source.sites.
Symmetry-equivalent output atoms share their new SiteType.
"""
source_sites = atoms.arrays.get(SPRKKRAtoms.sites_array_name)
known_by_orbit = {}
if source_sites is not None:
for i, site in enumerate(source_sites):
if site:
known_by_orbit.setdefault(int(dataset.equivalent_atoms[i]), site)
site_types = {}
sites = []
for index in source_indices:
old_site = (
source_sites[index]
if source_sites is not None and source_sites[index]
else known_by_orbit.get(int(dataset.equivalent_atoms[index]))
)
if old_site:
key = ("site-type", old_site.site_type)
if key not in site_types:
site_types[key] = old_site.site_type.copy(atoms=result)
sites.append(old_site.copy(site_type=site_types[key]))
else:
key = ("symmetry-orbit", int(dataset.equivalent_atoms[index]))
if key not in site_types:
occupation = Occupation.for_atom_from_ase_atoms(atoms, int(index))
site_types[key] = SiteType(result, occupation)
sites.append(Site(site_types[key]))
return np.asarray(sites, dtype=object)
[docs]
class SymmetryAnalysis:
"""Symmetry dataset plus small geometry arrays, never a retained Atoms.
Calling methods on atoms with changed positions, lattice, or site classes
raises SymmetryError; recompute the analysis for the new structure.
"""
[docs]
def __init__(
self, cell, positions, site_tags, dataset, *,
equivalence, symprec, angle_tolerance,
):
self._cell = cell.copy()
self._positions = positions.copy()
self.site_tags = site_tags.copy()
self.dataset = dataset
self.equivalence = equivalence
self.symprec = symprec
self.angle_tolerance = angle_tolerance
[docs]
def _check_atoms(self, atoms):
_validate(atoms)
if (
len(atoms) != len(self.site_tags)
or not np.array_equal(atoms.cell.array, self._cell)
or not np.allclose(
atoms.get_scaled_positions(wrap=True), self._positions,
rtol=0, atol=1e-12,
)
):
raise SymmetryError(
"Geometry changed since analysis; call analyze_symmetry(atoms) again"
)
try:
tags = _classify_sites(
atoms, self.equivalence, self._cell, self._positions,
symprec=self.symprec, angle_tolerance=self.angle_tolerance,
)
except ValueError as exc:
raise SymmetryError(str(exc)) from exc
if not np.array_equal(tags, self.site_tags):
raise SymmetryError(
"Site classification changed since analysis; "
"call analyze_symmetry(atoms) again"
)
[docs]
def idealize(self, atoms):
"""Idealize a copy in the original basis without modifying atoms."""
self._check_atoms(atoms)
if atoms.constraints:
raise SymmetryError("Idealization with ASE constraints is not supported")
geometry, changed = idealize_cell(
self._cell, self._positions, self.site_tags,
self.dataset, symprec=self.symprec,
)
result = atoms.copy()
result.set_cell(geometry.cell, scale_atoms=False)
result.set_scaled_positions(geometry.scaled_positions)
if isinstance(result, SPRKKRAtoms):
result.spacegroup_info._dataset = None
if changed and _electronic_data_present(atoms):
_warn_electronic_data()
return result
[docs]
def find_primitive(self, atoms, *, idealize=False, ase_arrays="require-equal"):
"""Build a primitive cell from explicitly supplied atoms."""
return self._converted(
atoms, to_primitive=True, idealize=idealize, ase_arrays=ase_arrays,
)
[docs]
def standardize(self, atoms, *, idealize=False, ase_arrays="require-equal"):
"""Build a standard conventional cell from explicitly supplied atoms."""
return self._converted(
atoms, to_primitive=False, idealize=idealize, ase_arrays=ase_arrays,
)
[docs]
def _converted(self, atoms, *, to_primitive, idealize, ase_arrays):
self._check_atoms(atoms)
if idealize:
idealized = self.idealize(atoms)
updated = analyze_symmetry(
idealized, equivalence=self.equivalence,
symprec=self.symprec, angle_tolerance=self.angle_tolerance,
)
return updated._converted(
idealized, to_primitive=to_primitive,
idealize=False, ase_arrays=ase_arrays,
)
if ase_arrays not in ("require-equal", "discard", "choose-first"):
raise ValueError("ase_arrays must be require-equal, discard, or choose-first")
if atoms.constraints:
raise SymmetryError("Cell conversion with ASE constraints is not supported")
try:
transformed = transform_cell(
self._cell, self._positions, self.site_tags,
to_primitive=to_primitive,
symprec=self.symprec, angle_tolerance=self.angle_tolerance,
)
groups = primitive_site_groups(
self._cell, self._positions, self.site_tags,
self.dataset, transformed, symprec=self.symprec,
)
except ValueError as exc:
raise SymmetryError(str(exc)) from exc
source_sites = atoms.arrays.get(SPRKKRAtoms.sites_array_name)
source_indices = np.array([
next(
(i for i in group if source_sites is not None and source_sites[i]),
group[0],
)
for group in groups
], dtype=int)
result = SPRKKRAtoms(
numbers=atoms.numbers[source_indices],
scaled_positions=transformed.scaled_positions,
cell=transformed.cell, pbc=True,
symmetry=atoms.symmetry if isinstance(atoms, SPRKKRAtoms) else True,
)
result.set_sites(
_make_sites(atoms, result, source_indices, self.dataset),
spacegroup_info=True,
)
result.spacegroup_info._dataset = None
result.info.update({
key: copy.deepcopy(value)
for key, value in atoms.info.items()
if key not in ("spacegroup_info", "occupancy")
})
reserved = {"numbers", "positions", "sprkkr_sites_data", "spacegroup_kinds"}
names = set(atoms.arrays) - reserved
if ase_arrays == "discard":
if names:
warnings.warn(
"Discarded ASE arrays: " + ", ".join(sorted(names)),
RuntimeWarning, stacklevel=2,
)
else:
for name in sorted(names):
array = atoms.arrays[name]
if ase_arrays == "require-equal":
for indices in groups:
if not all(
np.array_equal(array[i], array[indices[0]])
for i in indices[1:]
):
raise SymmetryError(
f"ASE array {name!r} differs within a primitive "
"translation class; use ase_arrays='choose-first' "
"or 'discard'."
)
result.set_array(name, array[source_indices].copy())
if ase_arrays == "choose-first":
lossy = [
name for name in names
if any(
not all(
np.array_equal(
atoms.arrays[name][i],
atoms.arrays[name][indices[0]],
)
for i in indices[1:]
)
for indices in groups
)
]
if lossy:
warnings.warn(
"Chose the first representative for differing ASE arrays: "
+ ", ".join(sorted(lossy)),
RuntimeWarning, stacklevel=2,
)
if self.equivalence == "occupation" and source_sites is not None:
original = {site.site_type for site in source_sites if site}
retained = {
source_sites[int(i)].site_type
for i in source_indices if source_sites[int(i)]
}
if original - retained:
warnings.warn(
f"Occupation equivalence discarded {len(original - retained)} "
"source SiteType(s) and their SPR-KKR data.",
RuntimeWarning, stacklevel=2,
)
return result
[docs]
def analyze_symmetry(
atoms: Atoms, *, equivalence="site-types",
symprec=1e-5, angle_tolerance=-1.0,
) -> SymmetryAnalysis:
"""Analyse the supplied atoms read-only, without copying or retaining it."""
_validate(atoms)
if not np.isfinite(symprec) or symprec <= 0:
raise ValueError("symprec must be a positive finite length")
cell = atoms.cell.array
positions = atoms.get_scaled_positions(wrap=True)
try:
tags = _classify_sites(
atoms, equivalence, cell, positions,
symprec=symprec, angle_tolerance=angle_tolerance,
)
dataset = symmetry_dataset(
cell, positions, tags,
symprec=symprec, angle_tolerance=angle_tolerance,
)
except ValueError as exc:
raise SymmetryError(str(exc)) from exc
return SymmetryAnalysis(
cell, positions, tags, dataset, equivalence=equivalence,
symprec=symprec, angle_tolerance=angle_tolerance,
)