site_analysis.spherical_site_collection

Collection manager for spherical sites in crystal structures.

This module provides the SphericalSiteCollection class, which manages a collection of SphericalSite objects and implements methods for assigning atoms to these sites based on their positions in a crystal structure.

The SphericalSiteCollection extends the base SiteCollection class with specific functionality for spherical sites. Optimised atom assignment is provided by the PriorityAssignmentMixin, which leverages recent site history, learned transition patterns, and precomputed distance-ranked site ordering.

This handles overlapping spherical sites in a consistent way – if an atom is in a region where multiple sites overlap, it will remain assigned to its original site as long as it stays within that site’s volume. This persistence can be useful for tracking atoms through small oscillations without generating spurious site transitions.

class SphericalSiteCollection(sites: list[SphericalSite])

Bases: PriorityAssignmentMixin[SphericalSite], SiteCollection

analyse_structure(atoms: list[Atom], structure: Structure) → None

Analyse a structure to assign atoms to spherical sites.

Assigns fractional coordinates to each atom, then delegates to assign_site_occupations to determine site membership.

Parameters:

• atoms – List of Atom objects to be assigned to sites.

• structure – Pymatgen Structure containing the atom positions.

assign_site_occupations(atoms: list[Atom], lattice_matrix: ndarray) → None

Assign atoms to spherical sites based on their positions.

Uses the priority-based site checking approach from PriorityAssignmentMixin to check sites in an optimised order.

Parameters:

• atoms – List of Atom objects to be assigned to sites.

• lattice_matrix – (3, 3) lattice matrix where rows are lattice vectors.