site_analysis.site_collection

Base classes for collections of sites in crystal structures.

This module defines:

  • SiteCollection: abstract base class that all site collection types must inherit from. Provides the interface for site-atom assignment and common functionality for managing site occupations.

  • PriorityAssignmentMixin: mixin providing priority-based site assignment ordering. Used by collection types that check sites one at a time (polyhedral, spherical) but not by those that use global distance-matrix assignment (Voronoi, dynamic Voronoi).

  • _NearestSiteLookup: precomputed lookup for finding the nearest site to a given position.

class PriorityAssignmentMixin(*args, **kwargs)[source]

Bases: Generic[SiteT]

Mixin providing priority-based site assignment ordering.

Provides _get_priority_sites(atom), a generator that yields sites in an optimised order based on recent site history, learned transitions, and precomputed distance ranking.

Subclasses call _init_priority_ranking(centres, site_indices) from their __init__ to enable distance-ranked ordering. If not called, the generator falls back to neighbouring_sites then arbitrary order (used by PolyhedralSiteCollection when reference centres are unavailable).

Note: distance ranking uses minimum-image convention in fractional space, which is only geometrically exact for orthogonal cells. For non-orthogonal cells the ranking is approximate, but correctness is unaffected since all sites are eventually checked.

Expects to be mixed with SiteCollection which provides site_by_index, neighbouring_sites, and sites.

class SiteCollection(sites: Sequence[Site])[source]

Bases: ABC

Parent class for collections of sites.

Collections of specific site types should inherit from this class.

sites

List of Site-like objects.

Type:

list

abstract analyse_structure(atoms, structure)[source]

Perform a site analysis for a set of atoms on a specific structure.

This method should be implemented in the derived subclass.

Parameters:

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

  • struture (pymatgen.Structure) – Pymatgen Structure object used to specificy the atomic coordinates.

Returns:

None

abstract assign_site_occupations(atoms, lattice_matrix)[source]

Assign atoms to sites.

Parameters:

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

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

Note

The atom coordinates should already be consistent with the structure. Recommended usage is via analyse_structure().

neighbouring_sites(site_index)[source]

If implemented, returns a list of sites that neighbour a given site.

This method should be implemented in the derived subclass.

Parameters:

site_index (int) – Index of the site to return a list of neighbours for.

reset() → None[source]

Reset the collection and all its sites for a fresh analysis run.

Resets per-site state (occupations, trajectories, caches) via Site.reset(). Subclasses may override to also clear collection-level caches, but should call super().reset().

reset_site_occupations()[source]

Occupations of all sites in this site collection are set as empty.

Parameters:

None –

Returns:

None

site_by_index(index)[source]

Returns the site with a specific index.

Parameters:

index (int) – index for the site to be returned.

Returns:

(Site)

Raises:

ValueError – If a site with the specified index is not contained in this SiteCollection.

sites_contain_points(points: ndarray, all_frac_coords: ndarray, lattice_matrix: ndarray) → bool[source]

Check whether the set of sites contain corresponding points.

Parameters:

  • points – (N, 3) array of fractional coordinates. One coordinate per site being checked.

  • all_frac_coords – Full fractional coordinate array, shape (n_atoms, 3).

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

Returns:

True if every point is contained by its corresponding site.

summaries(metrics: list[str] | None = None) → list[dict][source]

Generate summary statistics for all sites in the collection.

Parameters:

metrics – List of metrics to include for each site. None returns default metrics for each site.

Returns:

List of summary dicts, one per site, in site order.

update_occupation(site, atom)[source]

Updates site and atom attributes for this atom occupying this site.

Parameters:

  • site (Site) – The site to be updated.

  • atom (Atom) – The atom to be updated.

Returns:

None

Notes

This method does the following:

  1. If the atom has moved to a new site, record a old_site –> new_site transition.

  2. Add this atom’s index to the list of atoms occupying this site.

  3. Add this atom’s fractional coordinates to the list of coordinates observed occupying this site.

  4. Assign this atom this site index.