torchsim_nl

torch_sim.neighbors.torchsim_nl(positions, cell, pbc, cutoff, system_idx, self_interaction=False)[source]

Compute neighbor lists with automatic selection of best available implementation.

This function automatically selects the best available neighbor list implementation based on what’s installed. Priority order: 1. Alchemiops (NVIDIA CUDA optimized) if available 2. Vesin (fast, cross-platform) if available 3. torch_nl_linked_cell (pure PyTorch fallback)

Parameters:

  • positions (Tensor) – Atomic positions tensor [n_atoms, 3]

  • cell (Tensor) – Unit cell vectors [n_systems, 3, 3] or [3, 3]

  • pbc (Tensor) – Boolean tensor [n_systems, 3] or [3]

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

  • system_idx (Tensor) – Tensor [n_atoms] indicating which system each atom belongs to

  • self_interaction (bool) – If True, include self-pairs. Default: False

Returns:

  • mapping: Tensor [2, num_neighbors] - pairs of atom indices

  • system_mapping: Tensor [num_neighbors] - system assignment for each pair

  • shifts_idx: Tensor [num_neighbors, 3] - periodic shift indices

Return type:

tuple containing

Notes

  • Automatically uses best available implementation

  • Priority: Alchemiops > Vesin > torch_nl_linked_cell

  • Fallback works on NVIDIA CUDA, AMD ROCm, and CPU

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

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

  • Accepts both single-system [3, 3] or batched [n_systems, 3, 3] cell formats

  • Accepts both single [3] or batched [n_systems, 3] PBC formats