{"id":8761,"library":"vesin","title":"Vesin: Fast Neighbor Lists for Atomistic Systems","description":"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.","status":"active","version":"0.5.4","language":"en","source_language":"en","source_url":"https://github.com/Luthaf/vesin","tags":["atomistic systems","neighbor list","molecular simulation","materials science","scientific computing","chemistry","physics","high-performance computing"],"install":[{"cmd":"pip install vesin","lang":"bash","label":"Basic Installation"},{"cmd":"pip install vesin[torch]","lang":"bash","label":"Installation with TorchScript bindings"}],"dependencies":[{"reason":"Required for array handling in Python interface.","package":"numpy","optional":false},{"reason":"Optional dependency for `ase_neighbor_list` compatibility. Not required for core functionality.","package":"ase","optional":true},{"reason":"Required for TorchScript bindings, installed with `vesin[torch]`.","package":"torch","optional":true}],"imports":[{"symbol":"NeighborList","correct":"from vesin import NeighborList"},{"symbol":"ase_neighbor_list","correct":"from vesin import ase_neighbor_list"}],"quickstart":{"code":"import numpy as np\nfrom vesin import NeighborList\n\n# Define positions and box (example for a 2-atom system in a cubic box)\npositions = np.array([\n    (0.0, 0.0, 0.0),\n    (0.5, 0.0, 0.0)\n])\nbox = 3.0 * np.eye(3) # 3x3 Angstrom cubic box\ncutoff = 1.0 # Angstroms\n\n# Initialize the NeighborList calculator\ncalculator = NeighborList(cutoff=cutoff, full_list=True)\n\n# Compute the neighbor list, requesting indices (i, j), periodic shifts (S), and distances (d)\ni, j, S, d = calculator.compute(\n    points=positions,\n    box=box,\n    periodic=True, # Enable periodic boundary conditions\n    quantities=\"ijSd\"\n)\n\nprint(f\"Neighbor indices (i): {i}\")\nprint(f\"Neighbor indices (j): {j}\")\nprint(f\"Periodic shifts (S): {S}\")\nprint(f\"Distances (d): {d}\")\n\n# Example with ASE (requires 'ase' to be installed)\n# try:\n#     import ase\n#     from vesin import ase_neighbor_list\n#     atoms = ase.Atoms('H2', positions=[(0,0,0), (0,0,0.74)], cell=[10,10,10], pbc=True)\n#     i_ase, j_ase, S_ase, d_ase = ase_neighbor_list(\"ijSd\", atoms, cutoff=1.0)\n#     print(f\"\\nASE-compatible Neighbor indices (i): {i_ase}\")\n# except ImportError:\n#     print(\"\\nASE not installed, skipping ase_neighbor_list example.\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install the library using pip: `pip install vesin`.","cause":"The 'vesin' library has not been installed in your Python environment.","error":"ModuleNotFoundError: No module named 'vesin'"},{"fix":"Review the `NeighborList.compute()` signature in the official documentation or the quickstart example. Ensure you are using `points` instead of `positions`.","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.","error":"TypeError: compute() got an unexpected keyword argument 'positions' (or similar unexpected keyword argument)"},{"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.","cause":"The `quantities` string passed to `compute()` contains an unrecognized character or is malformed.","error":"ValueError: quantities can only contain 'i', 'j', 'P', 'S', 'd', 'D'"}]}