site_analysis.polyhedral_site

Polyhedral site representation for crystal structure analysis.

This module provides the PolyhedralSite class, which represents a site defined by a polyhedron formed by a set of vertex atoms. These sites are commonly used to represent coordination environments in crystal structures, such as tetrahedral or octahedral sites.

class FaceTopologyCache(vertex_coords: ndarray)

Bases: object

Cached face topology and surface normal data for polyhedral containment.

The face topology (which vertex triples form each face) is computed once from an initial ConvexHull and cached permanently – it depends only on vertex connectivity, not on coordinates. Per-timestep, the face normals, reference points, and centre signs are recomputed from new vertex coordinates using the cached topology.

face_simplices

(N_faces, 3) array of vertex indices per face.

contains_point(x_pbc_points: ndarray) → bool

Test whether any PBC image point is inside the polyhedron.

Parameters:

x_pbc_points – (N, 3) array of periodic boundary images.

Returns:

True if any point is inside the polyhedron.

update(vertex_coords: ndarray) → None

Recompute face normals from cached topology and new coordinates.

Called once per timestep after vertex coordinates are assigned.

Parameters:

vertex_coords – (N_vertices, 3) array of current vertex positions.

class PolyhedralSite(vertex_indices: list[int], label: str | None = None, reference_center: ndarray | None = None)

Bases: Site

Describes a site defined by the polyhedral volume enclosed by a set of vertex atoms.

A PolyhedralSite determines whether atoms are inside the site volume by constructing a convex polyhedron from the vertex atoms and checking whether points lie within this polyhedron. The containment algorithm is selected automatically: when numba is available, a JIT-compiled surface normal method with cached face topology is used; otherwise, falls back to Delaunay tessellation via scipy.

The polyhedron vertices are defined using atom indices in a structure, and their coordinates are assigned from the structure when needed. This allows the polyhedron shape to adapt to changes in the crystal structure.

vertex_indices

List of integer indices for the vertex atoms (counting from 0).

Type:

list[int]

vertex_coords

Fractional coordinates of the vertices. Set using assign_vertex_coords() or notify_structure_changed().

Type:

np.ndarray or None

reference_center

Optional reference centre for PBC handling.

Type:

np.ndarray or None

See also

Site: Parent class documenting inherited attributes

(index, label, contains_atoms, trajectory, points, transitions).

as_dict() → dict

Json-serializable dict representation of this Site.

Parameters:

None –

Returns:

(dict)

assign_vertex_coords(all_frac_coords: ndarray, lattice_matrix: ndarray) → None

Assign fractional coordinates to the polyhedra vertices.

Resets the cached Delaunay tessellation, so the next contains_point call will recompute it.

Parameters:

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

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

Note

For bulk analysis prefer notify_structure_changed, which pre-extracts coordinates once and defers PBC correction until the site is actually queried.

property centre: ndarray

Returns the fractional coordinates of the centre point of this polyhedral site.

Parameters:

None –

Returns:

(3,) numpy array.

Return type:

(np.array)

property cn: int

Coordination number for this site, defined as the number of vertices

Convenience property for coordination_number()

Returns:

int

contains_atom(atom: Atom, *, algo: str | None = None, pbc_images: ndarray | None = None) → bool

Test whether an atom is inside this polyhedron.

Parameters:

• atom – The atom to test.

• algo – Deprecated. Previously selected the algorithm. Now ignored; the best available method is used automatically.

• pbc_images – Optional pre-computed PBC images of the atom’s fractional coordinates. If provided, passed through to contains_point to avoid redundant computation.

Returns:

True if the atom is inside the polyhedron.

contains_point(x: ndarray, *, algo: str | None = None, pbc_images: ndarray | None = None) → bool

Test whether a specific point is enclosed by this polyhedral site.

The containment algorithm is selected automatically based on available dependencies. When numba is installed, uses a JIT-compiled surface normal method. Otherwise, falls back to Delaunay tessellation.

Parameters:

• x – Fractional coordinates of the point to test (length 3 array).

• algo – Deprecated. Previously selected the algorithm. Now ignored; the best available method is used automatically.

• pbc_images – Optional pre-computed PBC images of x, shape (N, 3). If provided, skips the internal x_pbc call.

Returns:

True if the point is inside the polyhedron.

property coordination_number: int

Coordination number for this site, defined as the number of vertices

Returns:

int

property delaunay: Delaunay

Delaunay tessellation of the vertex coordinates for this site.

This is calculated the first time the attribute is requested, and then stored for reuse, unless the site is reset.

Returns:

scipy.spatial.Delaunay

classmethod from_dict(d)

Create a Site object from a dict representation.

Parameters:

d (dict) – The dict representation of this Site.

Returns:

(Site)

get_vertex_species(species: list[str]) → list[str]

Return species strings for this site’s vertex atoms.

Parameters:

species – List of species strings for all atoms in the structure, indexed by atom index.

Returns:

Species strings for this site’s vertex atoms.

notify_structure_changed(all_frac_coords: ndarray, lattice_matrix: ndarray) → None

Mark vertex coordinates as stale for lazy reassignment.

Stores a reference to the full coordinate array so that PBC-corrected vertex coordinates can be computed on demand when contains_point is next called.

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.

reset() → None

Reset the trajectory for this site.

Resets the contains_atoms and trajectory attributes to empty lists. Vertex coordinates, Delaunay tessellation, and PBC shift caches are unset. The face topology cache is preserved as it depends only on vertex indices, which are immutable.

classmethod sites_from_vertex_indices(vertex_indices: list[list[int]], label: str | None = None) → list[PolyhedralSite]