Site Collections

What is a Site Collection?

A site collection manages a group of related sites and handles the assignment of atoms to these sites based on their positions in a crystal structure. While individual sites define bounded volumes, site collections orchestrate how atoms are assigned to sites at each timestep.

Users rarely interact directly with site collection classes — the TrajectoryBuilder creates the appropriate collection automatically when you call methods like .with_spherical_sites() or .with_polyhedral_sites(). This page explains the assignment logic that happens behind the scenes, which is useful for understanding how your results are produced.

Assignment Strategies

Each site collection type implements a different strategy for assigning atoms to sites. The choice of strategy is determined by the spatial properties of the corresponding site type.

Priority-Based Assignment (Spherical and Polyhedral)

Spherical sites can overlap or leave gaps between them; polyhedral sites can leave gaps between them but must not overlap. These collections check sites one at a time and assign the atom to the first containing site found. To avoid unnecessary containment checks, a priority heuristic determines the order in which sites are tested:

  1. Recent history: the atom’s most recently occupied site(s) are checked first

  2. Learned transitions: sites that atoms have previously transitioned to from the atom’s most recent site, ordered by frequency

  3. Distance ranking: remaining sites ordered by the distance of their centres from the atom

If the atom has no recent sites (e.g. at the first timestep), the search starts with the distance ranking.

Polyhedral sites are ranked by their reference centres. If any polyhedral site has no reference centre (deprecated), the remaining sites are instead checked starting with the neighbours of the most recent site, then in list order (or only in list order, for an atom with no recent site).

For spherical sites, the distance ranking stops at the largest site radius, since no site whose centre is further from the atom can contain it.

Where spherical sites overlap, or an atom is exactly on a face shared by two polyhedral sites, the first containing site in this order claims the atom: an atom stays in a recent site if one contains it, otherwise goes to a learned transition destination that contains it, and otherwise goes to the containing site whose centre is nearest the atom (when sites are ranked by distance).

This ordering means atoms that remain in or near their current site are resolved in a single check, and common transitions are tested early. In practice, this eliminates the majority of containment checks compared to a naive sequential scan.

If no site contains the atom, it is left unassigned (None).

Polyhedral sites can share faces, and the trajectory can report which sites do; see Shared Faces and Adjacency.

Each polyhedral site is bounded by triangles over its vertex atoms, and sites that share a face triangulate it identically, so face-sharing sites fill the space between them. Overlapping polyhedral sites are not supported; coincident sites, and a site whose vertex atoms are all vertices of another site under one lattice translation, raise ValueError when shared faces are found; see Site Boundaries.

Nearest-Centre Assignment (Voronoi and Dynamic Voronoi)

Voronoi-based sites partition space completely, so there are no gaps or overlaps. Assignment is straightforward: each atom is assigned to whichever site centre is nearest, using the lattice to correctly handle periodic boundary conditions.

For dynamic Voronoi sites, the collection first updates each site’s centre from the current positions of its reference atoms, then applies the same nearest-centre logic.

Overlaps and Gaps

The handling of spatial ambiguity is the key difference between collection types:

Scenario

Spherical / Polyhedral

Voronoi / Dynamic Voronoi

Overlapping sites

Spherical: priority-based: atom stays in previous site if possible; otherwise, after learned transitions, it goes to the containing site with the nearest centre (see above). Polyhedral: not supported

Cannot occur (space is partitioned)

Gaps between sites

Atom is unassigned (None)

Cannot occur (space is partitioned)

See the sites concepts page for guidance on choosing a site type based on these trade-offs.