site_analysis.polyhedral_site_collection

Collection manager for polyhedral sites in crystal structures.

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

The PolyhedralSiteCollection extends the base SiteCollection class with specific functionality for polyhedral sites, including:

• Maintaining a map of neighbouring polyhedral sites that share faces

• Optimised atom assignment via the PriorityAssignmentMixin

• Precomputed distance-ranked site ordering when reference centres are available

The module also includes utility functions:

• construct_neighbouring_sites: analyses polyhedral sites to determine which ones are face-sharing neighbours (sharing three or more vertices).

• _collect_reference_centres: extracts reference centres from polyhedral sites for distance-ranked ordering.

class PolyhedralSiteCollection(sites: list[Site])

Bases: PriorityAssignmentMixin[PolyhedralSite], SiteCollection

A collection of PolyhedralSite objects.

Extends the base SiteCollection class with specific functionality for polyhedral sites, including maintaining a map of neighbouring polyhedral sites that share faces and implementing optimised atom assignment based on spatial relationships and learned transition patterns.

sites

List of PolyhedralSite objects.

Type:

list

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

Analyse a structure to assign atoms to polyhedral sites.

Assigns coordinates to atoms, notifies sites of the new structure, and assigns atoms to sites.

Parameters:

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

• structure – Pymatgen Structure containing atom positions.

assign_site_occupations(atoms, lattice_matrix) → None

Assign atoms to polyhedral sites based on their positions.

This method implements an optimised assignment logic using a priority-based site checking approach.

Parameters:

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

• lattice_matrix – (3, 3) lattice matrix where rows are lattice vectors. Not currently used for polyhedral containment checks, but accepted for interface consistency.

neighbouring_sites(index: int) → list[PolyhedralSite]

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.

sites_contain_points(points: ndarray, all_frac_coords: ndarray, lattice_matrix: ndarray) → bool

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 from the structure, 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.

Raises:

ValueError – If the number of points does not match the number of sites.

construct_neighbouring_sites(sites: list[PolyhedralSite]) → dict[int, list[PolyhedralSite]]

Find all polyhedral sites that are face-sharing neighbours.

Any polyhedral sites that share 3 or more vertices are considered to share a face.

Parameters:

sites – List of PolyhedralSite objects to check for shared faces.

Returns:

Dictionary of int: list entries.

Keys are site indices. Values are lists of PolyhedralSite objects.

Return type:

(dict)