Working with Polyhedral Sites
Polyhedral sites are defined by coordination polyhedra formed by sets of vertex atoms. Unlike spherical sites with fixed geometry or Voronoi sites with mathematically determined boundaries, polyhedral sites adapt their shape based on the positions of coordinating atoms, making them ideal for representing crystallographic coordination environments.
For a conceptual overview of polyhedral sites, see the polyhedral sites concepts page.
When to Use Polyhedral Sites
Polyhedral sites are best suited for:
Analysing specific coordination environments (tetrahedral, octahedral, etc.)
Systems where site geometry should match chemical coordination
Materials with well-defined coordination polyhedra
Studies requiring sites that adapt to structural distortions
Close-packed structures where coordination polyhedra fill space
Consider alternative site types when:
You need guaranteed complete spatial coverage (use Voronoi sites)
The structure lacks well-defined coordination environments
Computational efficiency is critical (polyhedral containment tests are expensive)
Site centres should be fixed rather than geometry-dependent
Understanding Polyhedral Site Properties
Polyhedral sites have unique characteristics:
Vertex-based: Defined by sets of atoms forming polyhedron vertices
Adaptive shape: Site geometry follows vertex atom movements
Coordination-specific: Directly represents chemical environments
Structure-dependent: Shape changes with structural distortions
The key concept is that sites are defined by their vertices (coordinating atoms) rather than by a centre and radius. This creates sites that match crystallographic coordination environments and adapt to local structure deformations. Each site is bounded by triangles over its vertices, and neighbouring sites triangulate the faces they share identically (see Site Boundaries).
Creating Polyhedral Sites
Polyhedral sites use the reference-based sites workflow to identify coordination environments.
Basic Setup
from site_analysis import TrajectoryBuilder
trajectory = (TrajectoryBuilder()
.with_structure(target_structure)
.with_reference_structure(reference_structure)
.with_mobile_species("Li")
.with_polyhedral_sites(
centre_species="Li", # Species at polyhedron centres
vertex_species="O", # Species forming vertices
cutoff=2.5, # Distance cutoff for coordination
n_vertices=4, # Number of vertices (4 = tetrahedral)
label="tetrahedral"
)
.build())
With Structure Alignment
When reference and target structures have different origins or orientations:
trajectory = (TrajectoryBuilder()
.with_structure(target)
.with_reference_structure(ideal_structure)
.with_mobile_species("Li")
.with_structure_alignment(
align=True,
align_species=["O"] # Align using framework atoms
)
.with_site_mapping(mapping_species=["O"]) # Map vertex atoms
.with_polyhedral_sites(
centre_species="Li",
vertex_species="O",
cutoff=2.5,
n_vertices=6, # Octahedral coordination
label="octahedral"
)
.build())
Example: Mixed Coordination Environments
Many materials contain multiple types of coordination environments:
# Example: Spinel structure with tetrahedral and octahedral sites
trajectory = (TrajectoryBuilder()
.with_structure(spinel_structure)
.with_reference_structure(ideal_spinel)
.with_mobile_species("Li")
.with_structure_alignment(align=True, align_species=["O"])
# Tetrahedral sites
.with_polyhedral_sites(
centre_species="Li",
vertex_species="O",
cutoff=2.0,
n_vertices=4,
label="tetrahedral"
)
# Octahedral sites
.with_polyhedral_sites(
centre_species="Li",
vertex_species="O",
cutoff=2.5,
n_vertices=6,
label="octahedral"
)
.build())
Advanced Usage: Direct Site Creation
For more control, you can create polyhedral sites directly.
Using ReferenceBasedSites
from site_analysis.reference_workflow import ReferenceBasedSites
# Create reference-based sites instance
rbs = ReferenceBasedSites(
reference_structure=ideal_structure,
target_structure=md_structure,
align=True,
align_species=["O"]
)
# Create polyhedral sites
sites = rbs.create_polyhedral_sites(
center_species="Li",
vertex_species="O",
cutoff=2.5,
n_vertices=4,
label="tetrahedral",
target_species=["O"]
)
# Create trajectory manually
from site_analysis import atoms_from_structure, Trajectory
atoms = atoms_from_structure(md_structure, "Li")
trajectory = Trajectory(sites=sites, atoms=atoms)
Creating Sites from Vertex Indices
For complete control, specify vertex atoms directly, with a reference centre for each site:
from site_analysis.polyhedral_site import PolyhedralSite
# Define vertices for each site (atom indices)
site1_vertices = [10, 15, 22, 28] # Indices of O atoms forming tetrahedron
site2_vertices = [11, 16, 23, 29, 35, 41] # Indices for octahedron
# Reference centres: the fractional coordinates of each site's central atom
site1_centre = md_structure[2].frac_coords # Central atom of the tetrahedron
site2_centre = md_structure[3].frac_coords # Central atom of the octahedron
# Create individual polyhedral sites
site1 = PolyhedralSite(vertex_indices=site1_vertices, label="tet_1",
reference_center=site1_centre)
site2 = PolyhedralSite(vertex_indices=site2_vertices, label="oct_1",
reference_center=site2_centre)
# Use in trajectory
trajectory = Trajectory(sites=[site1, site2], atoms=atoms)
This approach is useful when you have pre-identified coordination environments or need to work with non-standard polyhedra.
Each site’s vertices are unwrapped to their periodic images nearest its reference centre (see Periodic Boundary Conditions). Creating a site without a reference centre is deprecated and issues a FutureWarning; such a site falls back to spread-based detection, and version 2.0 will require reference_center. PolyhedralSite.sites_from_vertex_indices(), which creates sites from vertex indices alone, without reference centres, is deprecated in favour of TrajectoryBuilder.with_polyhedral_sites() (or PolyhedralSite with reference_center), and issues a FutureWarning.
Vertex indices are Python or numpy integers; PolyhedralSite raises TypeError for any other value, including a bool. Every structure the trajectory analyses must have an atom for every vertex index: analyse_structure() (and so append_timestep()) and TrajectoryBuilder.build() raise ValueError (“Site {index} has vertex index {k}, but the structure has {n} atoms”) naming the first such site in index order. PolyhedralSiteCollection.validate_atom_count(n_atoms) makes the same check.
For a comparison of all site types and guidance on choosing between them, see the site selection guide.
Site Boundaries
A polyhedral site is the polyhedron bounded by a fixed set of triangles over its vertex atoms. Each face a site shares with a neighbouring site (see Shared Faces and Adjacency) is triangulated by a rule that depends only on the face’s atoms, so both sites give the face the same triangles, and the faces it shares with no other site keep the triangles of the convex hull of its vertices. Sites that share faces therefore fill the space between them, with no gaps or overlaps at their shared faces, including faces of four or more atoms that are not flat.
The triangles are fixed, as triples of the site’s vertices (positions in its vertex_indices), when the shared faces are found, from the same vertex coordinates: by TrajectoryBuilder.build() from the reference geometry, by trajectory.find_shared_faces(structure), or from the first structure analysed if neither has found them. They are kept for every later frame, while the vertex atoms move. A PolyhedralSite used on its own, outside a collection that has found its shared faces, takes the triangles of the convex hull of its vertices in the first frame it is tested in. Sites restored with PolyhedralSite.from_dict() have no triangles: a collection of them fixes the triangles when it finds its shared faces, on its first analysis or with find_shared_faces.
A point is inside a site when it is inside one of the tetrahedra joining the site’s centre (the mean of its vertex coordinates) to each of its triangles. These tetrahedra bound the site exactly while the centre is strictly on the inner side of the plane of every triangle. When a site is tested in a frame in which it is not, containment raises RuntimeError, naming the site and its vertex atoms and saying that it is too distorted for its triangles to enclose its centre. A site is checked on its first containment test after its vertex coordinates change, so a site that no atom’s search reaches in a frame does not raise in that frame.
Overlapping polyhedral sites are not supported. Sites that interpenetrate may raise one of the errors below when the shared faces are found, or may be analysed without one, in which case an atom inside both goes to the first site the site search tests. Coincident and nested sites raise ValueError (see below).
Containment
A site’s containment test uses the four planes of each of its tetrahedra (see Site Boundaries), recomputed from the current vertex coordinates on the site’s first test after they change. A point may be given in any periodic image: each of its images that can lie inside the site is tested. A point exactly on a face shared by two sites is inside both, since the test includes the boundary, unless rounding in the two sites’ copies of the face puts it just outside one or both; a point inside two sites goes to the first of them that the site search tests. A point that is not three finite numbers raises ValueError.
The test is the same with and without numba, with identical results. When numba is installed, it runs as JIT-compiled code, which makes per-frame analysis of the argyrodite tutorial trajectory about three times faster:
pip install site-analysis[fast] # installs numba