site_analysis.dynamic_voronoi_site

Dynamic Voronoi site representation for crystal structure analysis.

This module provides the DynamicVoronoiSite class, which represents a site with a centre that is dynamically calculated from the positions of a set of reference atoms.

class DynamicVoronoiSite(reference_indices: list[int], label: str | None = None, reference_center: ndarray | None = None)[source]

Bases: Site

Site subclass corresponding to Voronoi cells with centres dynamically calculated from the positions of sets of reference atoms.

Unlike standard VoronoiSite objects, which have fixed centres, the positions of DynamicVoronoiSite objects adapt to structural changes as the reference atoms move. The site centre is calculated as the mean position of the reference atoms, with special handling for periodic boundary conditions.

This makes DynamicVoronoiSite particularly useful for tracking sites in mobile frameworks where the crystal structure deforms during simulation.

Similar to standard Voronoi sites, a single DynamicVoronoiSite cannot determine whether an atom is contained within it, as this depends on the positions of all other sites. The coordination number of a DynamicVoronoiSite is defined as the number of reference atoms used to calculate its centre.

reference_indices

Indices of atoms used as reference to calculate the dynamic centre of the site.

Type:: list[int]

centre_coords

Fractional coordinates of the dynamically calculated site centre. This is None initially and calculated on demand.

Type:: np.ndarray or None

See also

Site: Parent class documenting inherited attributes: (index, label, contains_atoms, trajectory, points, transitions, average_occupation).

Important

This class is designed to be used with DynamicVoronoiSiteCollection, which handles the Voronoi tessellation logic.

as_dict() → dict[source]

Json-serializable dict representation of this DynamicVoronoiSite.

Parameters:: None –
Returns:: dictionary representation of this site.
Return type:: dict

calculate_centre(all_frac_coords: ndarray, lattice_matrix: ndarray) → None[source]

Calculate the centre of this site from reference atom positions.

Handles periodic boundary conditions and wraps the result into [0, 1).

Parameters:

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.

property centre: ndarray

Returns the centre position of this site.

This method returns the cached centre coordinates or raises an error if they haven’t been calculated yet.

Parameters:: None –
Returns:: Fractional coordinates of the site centre.
Return type:: np.ndarray
Raises:: RuntimeError – If the centre coordinates have not been calculated yet.

property cn: int

Coordination number for this site, defined as the number of reference atoms.

Convenience property for coordination_number()

Returns:: int

contains_point(x: ndarray) → bool[source]

A single dynamic Voronoi site cannot determine whether it contains a given point, because the site boundaries are defined by the set of all dynamic Voronoi sites.

Use DynamicVoronoiSiteCollection.assign_site_occupations() instead.

property coordination_number: int

Returns the coordination number of this site.

For a DynamicVoronoiSite, the “coordination number” is the number of reference atoms.

Parameters:: None –
Returns:: The number of reference atoms.
Return type:: int

classmethod from_dict(d: dict) → DynamicVoronoiSite[source]

Create a DynamicVoronoiSite object from a dict representation.

Parameters:: d (dict) – The dict representation of this Site.
Returns:: A new DynamicVoronoiSite instance.
Return type:: DynamicVoronoiSite

reset() → None[source]

Reset the site state.

Clears the calculated centre coordinates and resets the site occupation data.

Parameters:: None –
Returns:: None

classmethod sites_from_reference_indices(reference_indices_list: list[list[int]], label: str | None = None) → list[DynamicVoronoiSite][source]

Create a list of DynamicVoronoiSite objects from a list of reference indices.

Parameters:

reference_indices_list – List of lists, where each inner list contains reference indices for a site.
label – Optional label for all sites. Default is None.

Returns:

A list of DynamicVoronoiSite objects.