vesin_nl

torch_sim.neighbors.vesin_nl(*, positions, cell, pbc, cutoff, sort_id=False)[source]

Compute neighbor lists using the standard Vesin implementation.

This function provides an interface to the standard Vesin neighbor list algorithm using VesinNeighborList. It handles both periodic and non-periodic systems and returns neighbor pairs along with their periodic shifts.

Parameters:

  • positions (Tensor) – Atomic positions tensor of shape (num_atoms, 3)

  • cell (Tensor) – Unit cell vectors according to the row vector convention, i.e. [[a1, a2, a3], [b1, b2, b3], [c1, c2, c3]].

  • pbc (bool) – Whether to use periodic boundary conditions (applied to all directions)

  • cutoff (Tensor) – Maximum distance (scalar tensor) for considering atoms as neighbors

  • sort_id (bool) – If True, sort neighbors by first atom index for better memory access patterns

Returns:

  • mapping: Tensor of shape (2, num_neighbors) containing pairs of atom indices that are neighbors. Each column (i,j) represents a neighbor pair.

  • shifts: Tensor of shape (num_neighbors, 3) containing the periodic shift vectors needed to get the correct periodic image for each neighbor pair.

Return type:

tuple containing

Notes

  • Uses standard VesinNeighborList implementation

  • Requires CPU tensors in float64 precision internally

  • Returns tensors on the same device as input with original precision

  • For non-periodic systems (pbc=False), shifts will be zero vectors

  • The neighbor list includes both (i,j) and (j,i) pairs

  • Supports pre-sorting through the VesinNeighborList constructor

References