Vesin: we are all neighbors¶

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

vesin is a lightweight neighbor list calculator for molecular systems and three-dimensional graphs. It is written in C++ and can be used as a standalone library from C or Python. vesin is designed to be fast and easy to use.

Installation¶

Python

You can install the code with pip:

pip install vesin

C/C++ (CMake)

If you use CMake as your build system, the simplest thing to do is to add https://github.com/Luthaf/vesin to your project.

# assuming the code is in the `vesin/` directory (for example using
# git submodule)
add_subdirectory(vesin)

target_link_libraries(your-target vesin)

Alternatively, you can use CMake’s FetchContent module to automatically download the code:

include(FetchContent)
FetchContent_Declare(
    vesin
    GIT_REPOSITORY https://github.com/Luthaf/vesin.git
)

FetchContent_MakeAvailable(vesin)

target_link_libraries(your-target vesin)

C/C++ (single file build)

We support merging all files in the vesin library to a single one that can then be included in your own project and built with the same build system as the rest of your code.

You can generate this single file to build with the following commands:

git clone https://github.com/Luthaf/vesin.git
cd vesin
python create-single-cpp.py

Then you’ll need to copy both include/vesin.h and vesin-single-build.cpp in your project and configure your build system accordingly.

C/C++ (global installation)

You can build and install vesin in some global location (referred to as $PREFIX below), and then use the right compiler flags to give this location to your compiler. In this case, compilation of vesin and your code happen separately.

git clone https://github.com/Luthaf/vesin.git
cd vesin
mkdir build && cd build
cmake -DCMAKE_INSTALL_PREFIX=$PREFIX <other options> ..
cmake --install .

You can then compile your code, adding $PREFIX/include to the compiler include path, $PREFIX/lib to the linker library path; and linking to vesin (typically with -lvesin). If you are building vesin as a shared library, you’ll also need to define VESIN_SHARED as a preprocessor constant (-DVESIN_SHARED when compiling the code).

Some relevant cmake options you can customize:

Option	Description	Default
`CMAKE_BUILD_TYPE`	Type of build: Debug or Release	Release
`CMAKE_INSTALL_PREFIX`	Prefix where the library will be installed	`/usr/local`
`BUILD_SHARED_LIBS`	Default to building and installing a shared library instead of a static one	OFF

Usage example¶

Python

There are two ways to use vesin from Python, you can use the NeighborList 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=points,
    box=box,
    periodic=True,
    quantities="ijSd"
)

Alternatively, you can use the ase_neighbor_list() function, which mimics the API of ase.neighborlist.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)

C and C++

#include <string.h>
#include <stdio.h>
#include <stdlib.h>

#include <vesin.h>

int main() {
    // points can be any pointer to `double[3]`
    double points[][3] = {
        {0, 0, 0},
        {0, 1.3, 1.3},
    };
    size_t n_points = 2;

    // box can be any `double[3][3]` array
    double box[3][3] = {
        {3.2, 0.0, 0.0},
        {0.0, 3.2, 0.0},
        {0.0, 0.0, 3.2},
    };
    bool periodic = true;

    // calculation setup
    VesinOptions options;
    options.cutoff = 4.2;
    options.full = true;

    // decide what quantities should be computed
    options.return_shifts = true;
    options.return_distances = true;
    options.return_vectors = false;

    VesinNeighborList neighbors;
    memset(&neighbors, 0, sizeof(VesinNeighborList));

    const char* error_message = NULL;
    int status = vesin_neighbors(
        points, n_points, box, periodic,
        VesinCPU, options,
        &neighbors,
        &error_message,
    );

    if (status != EXIT_SUCCESS) {
        fprintf(stderr, "error: %s\n", error_message);
        return 1;
    }

    // use neighbors as needed
    printf("we have %d pairs\n", neighbors.length);

    vesin_free(&neighbors);

    return 0;
}

Vesin: we are all neighbors¶

Installation¶

Usage example¶

API Reference¶