xnn.common.data.neighborlist.build_neighbor_list#

xnn.common.data.neighborlist.build_neighbor_list(pos, cutoff, cell=None, pbc=None, self_interaction=False)[source]#

Build a periodic-boundary-aware neighbor list for a single structure.

Uses vesin’s cell list when it is installed and applicable, and otherwise enumerates the minimal set of periodic image shifts covering cutoff and brute-forces all pairwise distances to select edges within the cutoff. Both produce the same edges, in the same order convention, with the same shifts. For molecular systems (cell or pbc is None, or no periodicity) image enumeration is skipped. Edges follow the convention dst = i (receiver) and src = j (sender), and the returned cell_shifts are negated so that AtomicGraph.edge_vectors() reproduces the selecting displacement.

Positions need not lie inside the cell: along periodic axes they are wrapped internally (image enumeration assumes in-cell positions) and the removed integer offsets are folded back into the returned cell_shifts, so the shifts remain consistent with the original positions. Unwrapped trajectories (e.g. from MD) therefore work as-is.

Parameters:

pos (Tensor) – Cartesian positions of shape (N, 3).
cutoff (float) – Neighbor cutoff radius; pairs with distance below this are kept.
cell (Tensor, optional) – Lattice vectors as rows, of shape (3, 3). None for molecular systems.
pbc (Tensor, optional) – Boolean periodicity flags of shape (3,). None for molecular systems.
self_interaction (bool, default False) – If False, drop self-edges (an atom to itself in the zero-shift image).

Returns:

edge_index (Tensor) – Edge list of shape (2, E) holding [src, dst] node indices.
cell_shifts (Tensor) – Integer periodic image shift per edge, of shape (E, 3).

Return type:

tuple[Tensor, Tensor]