Source code for ase2sprkkr.sprkkr.site_equivalence
"""Define the exact equivalence classes of sites passed to spglib."""
import numpy as np
from ..common.unique_values import UniqueValuesMapping
from .occupations import Occupation
[docs]
def occupation_key(occupation):
"""Exact chemical composition, including vacancies and independent of order."""
return tuple(sorted(
(symbol, float(amount)) for symbol, amount in occupation.to_dict(True).items()
))
[docs]
def site_equivalence_tags(
atoms, *, equivalence="site-types", atomic_kinds=None,
assigned_sites=None, region_memberships=None,
):
"""Classify sites once, before the symmetry search.
Uninitialized sites use ASE occupations. Initialized sites in strict mode
retain their SiteType identities and independent per-site magnetisations.
ASE/CIF spacegroup_kinds index occupancy metadata, not independent SiteTypes.
Explicit atomic_kinds override the species classification.
assigned_sites preserves SiteType sharing established by earlier region
calculations. region_memberships distinguishes atoms in different regions
even if they otherwise have identical SiteTypes.
"""
if equivalence not in ("site-types", "occupation"):
raise ValueError("equivalence must be 'site-types' or 'occupation'")
arrays = atoms.arrays
sites = arrays["sprkkr_sites_data"] if "sprkkr_sites_data" in arrays else None
initial_magmoms = (
arrays["initial_magmoms"] if "initial_magmoms" in arrays else None
)
if atomic_kinds is not None and len(atomic_kinds) != len(atoms):
raise ValueError("atomic_kinds must contain one value per site")
if assigned_sites is not None and len(assigned_sites) != len(atoms):
raise ValueError("assigned_sites must contain one value per site")
if region_memberships is not None and len(region_memberships) != len(atoms):
raise ValueError("region_memberships must contain one value per site")
partial = sites is not None and any(not s for s in sites)
keys = []
for i in range(len(atoms)):
site = sites[i] if sites is not None and sites[i] else None
if atomic_kinds is not None:
# Explicit atomic kinds completely replace implicit site classes.
kind = atomic_kinds[i]
key = tuple(kind.tolist()) if isinstance(kind, np.ndarray) else kind
elif site is not None and equivalence == "site-types" and not partial:
key = ("site-type", site.site_type, tuple(site.magnetisation))
else:
occ = site.occupation if site is not None else Occupation.for_atom_from_ase_atoms(atoms, i)
key = ("occupation", occupation_key(occ))
if (atomic_kinds is None and equivalence == "site-types"
and initial_magmoms is not None):
moment = np.asarray(initial_magmoms[i]).reshape(-1)
key = (key, tuple(float(component) for component in moment))
if assigned_sites is not None:
# Group by the shared SiteType, not by each distinct Site object.
site = assigned_sites[i]
key = (key, site.site_type if site else None)
if region_memberships is not None:
key = (key, tuple(region_memberships[i]))
keys.append(key)
return UniqueValuesMapping.from_values(keys).mapping.astype(np.intc, copy=False)
[docs]
def refine_partial_site_tags(tags, dataset, sites):
"""Refine chemical symmetry using known SiteTypes of partially set sites.
Uninitialized sites inherit the known identity of their preliminary
symmetry orbit. Distinct known SiteTypes or site magnetisations split
an orbit; no Site objects are created or changed.
"""
known = {}
for i, site in enumerate(sites):
if site:
known.setdefault(
int(dataset.equivalent_atoms[i]),
(site.site_type, tuple(site.magnetisation)),
)
keys = [
(
int(tag),
(site.site_type, tuple(site.magnetisation))
if site else known.get(int(dataset.equivalent_atoms[i])),
)
for i, (tag, site) in enumerate(zip(tags, sites))
]
refined = UniqueValuesMapping.from_values(keys).mapping
if UniqueValuesMapping.are_equivalent(tags, refined):
return tags
return refined