Vesin: Fast Neighbor Lists for Atomistic Systems

0.5.4 · active · verified Thu Apr 16

Vesin is a fast and easy-to-use Python library for computing neighbor lists in atomistic systems. It provides interfaces for Python, C, C++, and TorchScript, leveraging highly optimized C++ and CUDA code for performance. The library focuses on efficient calculation of inter-atomic distances and periodic shifts, crucial for molecular simulations and materials science. The current version is 0.5.4, released on April 2, 2026, indicating an active development and release cadence.

Common errors

```
ModuleNotFoundError: No module named 'vesin'
```
cause The 'vesin' library has not been installed in your Python environment.

fix Install the library using pip: `pip install vesin`.
```
TypeError: compute() got an unexpected keyword argument 'positions' (or similar unexpected keyword argument)
```
cause You are calling `NeighborList.compute()` with an incorrect or misspelled keyword argument. The method expects `points`, `box`, `periodic`, and `quantities` as its main arguments.

fix Review the `NeighborList.compute()` signature in the official documentation or the quickstart example. Ensure you are using `points` instead of `positions`.
```
ValueError: quantities can only contain 'i', 'j', 'P', 'S', 'd', 'D'
```
cause The `quantities` string passed to `compute()` contains an unrecognized character or is malformed.

fix Ensure the `quantities` string consists only of valid characters: 'i', 'j', 'P', 'S', 'd', 'D'. For example, `quantities="ijSd"` is valid, but `quantities="xyz"` is not.

Warnings

gotcha The `ase_neighbor_list` function, while providing API compatibility with ASE, does not support all features of `ase.neighborlist.neighbor_list()`, notably `self_interaction=True` and mixed periodic boundary conditions in `ase.Atoms` objects.
Fix: Consult the `vesin` documentation for the exact subset of `ase` functionality supported when using `ase_neighbor_list`. For full functionality, consider `NeighborList` or direct `ASE` calls.
gotcha Using `NeighborList.compute(copy=False)` can lead to unexpected behavior. When `copy=False`, the returned arrays are direct views into `vesin`'s internal data structures. These views become invalid if the `NeighborList` object is garbage collected or used for a subsequent computation.
Fix: Unless performance is absolutely critical and you manage object lifetimes carefully, it is recommended to either use the default `copy=True` or ensure that you process the returned arrays immediately after the `compute` call and before any other operation on the `NeighborList` object. If `copy=False` is used, consider making a deep copy of the results if they need to persist or be modified.

Install

pip install vesin Basic Installation
pip install vesin[torch] Installation with TorchScript bindings

Imports

NeighborList
```
from vesin import NeighborList
```
ase_neighbor_list
```
from vesin import ase_neighbor_list
```

Quickstart

This quickstart demonstrates how to initialize the `NeighborList` calculator, define an atomistic system with positions and a simulation box, and compute neighbor lists including indices, periodic shifts, and distances. It also shows the basic structure for using the ASE-compatible `ase_neighbor_list` function.

import numpy as np
from vesin import NeighborList

# Define positions and box (example for a 2-atom system in a cubic box)
positions = np.array([
    (0.0, 0.0, 0.0),
    (0.5, 0.0, 0.0)
])
box = 3.0 * np.eye(3) # 3x3 Angstrom cubic box
cutoff = 1.0 # Angstroms

# Initialize the NeighborList calculator
calculator = NeighborList(cutoff=cutoff, full_list=True)

# Compute the neighbor list, requesting indices (i, j), periodic shifts (S), and distances (d)
i, j, S, d = calculator.compute(
    points=positions,
    box=box,
    periodic=True, # Enable periodic boundary conditions
    quantities="ijSd"
)

print(f"Neighbor indices (i): {i}")
print(f"Neighbor indices (j): {j}")
print(f"Periodic shifts (S): {S}")
print(f"Distances (d): {d}")

# Example with ASE (requires 'ase' to be installed)
# try:
#     import ase
#     from vesin import ase_neighbor_list
#     atoms = ase.Atoms('H2', positions=[(0,0,0), (0,0,0.74)], cell=[10,10,10], pbc=True)
#     i_ase, j_ase, S_ase, d_ase = ase_neighbor_list("ijSd", atoms, cutoff=1.0)
#     print(f"\nASE-compatible Neighbor indices (i): {i_ase}")
# except ImportError:
#     print("\nASE not installed, skipping ase_neighbor_list example.")

view raw JSON →