Vesin: fast neighbor lists for atomistic systems

English 🇺🇸⁠/⁠🇬🇧	Occitan	Arpitan	French 🇫🇷	Gallo‑Italic	Catalan	Spanish 🇪🇸	Italian 🇮🇹
neighbo(u)r	vesin	vesin	voisin	visin	veí	vecino	vicino

Vesin is a fast and easy to use library computing neighbor lists for atomistic system. We provide an interface for the following programing languages:

• C (also compatible with C++). The project can be installed and used as a library with your own build system, or included as a single file and built directly by your own build system;
• Python;
• TorchScript, with both a C++ and Python interface;

Installation

To use the code from Python, you can install it with pip:

pip install vesin

See the documentation for more information on how to install the code to use it from C or C++.

Usage instruction

You can either use the NeighborList calculator class:

import numpy as np
from vesin import NeighborList

# positions can be anything compatible with numpy's ndarray
positions = [
    (0, 0, 0),
    (0, 1.3, 1.3),
]
box = 3.2 * np.eye(3)

calculator = NeighborList(cutoff=4.2, full_list=True)
i, j, S, d = calculator.compute(
    points=positions,
    box=box,
    periodic=True,
    quantities="ijSd",
)

We also provide a function with drop-in compatibility to ASE's neighbor list:

import ase
from vesin import ase_neighbor_list

atoms = ase.Atoms(...)

i, j, S, d = ase_neighbor_list("ijSd", atoms, cutoff=4.2)

See the documentation for more information on how to use the code from C or C++.

Benchmarks

You can find below benchmark result computing neighbor lists for increasingly large diamond supercells, using an AMD EPYC 9334 CPU and an NVIDIA H100 GPU. You can run this benchmark on your system with the script at benchmarks/benchmark.py. Cross on points indicate that a specific code could not run the calculation after or before the cross (for example, NNPOps requires the cell to be twice the cutoff in size, and can't run with large cutoffs and small cells).

License

Vesin is is distributed under the 3 clauses BSD license. By contributing to this code, you agree to distribute your contributions under the same license.

Citation

If you found vesin useful, you can cite the pre-print where it was presented (https://doi.org/10.48550/arXiv.2508.15704) as

@misc{metatensor-and-metatomic,
    title = {Metatensor and Metatomic: Foundational Libraries for Interoperable Atomistic
    Machine Learning},
    shorttitle = {Metatensor and Metatomic},
    author = {Bigi, Filippo and Abbott, Joseph W. and Loche, Philip and Mazitov, Arslan
    and Tisi, Davide and Langer, Marcel F. and Goscinski, Alexander and Pegolo, Paolo
    and Chong, Sanggyu and Goswami, Rohit and Chorna, Sofiia and Kellner, Matthias and
    Ceriotti, Michele and Fraux, Guillaume},
    year = {2025},
    month = aug,
    publisher = {arXiv},
    doi = {10.48550/arXiv.2508.15704},
}