Registry / data / vesin
library0.5.8pypypi✓ verified 87d ago

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.

pip install vesin
INSTALL
IMPORT
SIG · VESIN
V
vesin
datapythonv0.5.8
Install
36.9s avg
Import
3197ms
Disk
85MB
Pass rate
4/ 10
Env Coverage4 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.5.8 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
✕ build_error
✓ 40.84s
py 3.11
✕ build_error
✓ 37.95s
py 3.12
✕ build_error
✓ 34.6s
py 3.13
✕ build_error
✓ 34.09s
py 3.9
✕ build_error
6/8 runs
85MB installed
● package 85MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

NeighborList
from vesin import NeighborList
ase_neighbor_list
from vesin import ase_neighbor_list

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.")
Debug
Known issues
gotchaThe `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.
affects: All versions
gotchaUsing `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.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'vesin'
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)
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'
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.
Upgrade
Version history
0.5.8latest on PyPI · released May 26, 2026
Audit
Dependencies
numpyrequiredRequired for array handling in Python interface.
aseoptionalOptional dependency for `ase_neighbor_list` compatibility. Not required for core functionality.
torchoptionalRequired for TorchScript bindings, installed with `vesin[torch]`.
Agent activity
50 hits · last 30 days
node
42
Amazon
1
OpenAI (training)
1
Resources
vesin — pip install vesin · libregistry