C API reference

Vesin’s C API is defined in the vesin.h header. The main function is vesin_neighbors(), which runs a neighbors list calculation.

int vesin_neighbors(const double (*points)[3], size_t n_points, const double box[3][3], const bool periodic[3], VesinDevice device, struct VesinOptions options, struct VesinNeighborList *neighbors, const char **error_message)

Compute a neighbor list.

The data is returned in a VesinNeighborList. For an initial call, the VesinNeighborList should be zero-initialized (or default-initalized in C++). The VesinNeighborList can be re-used across calls to this functions to re-use memory allocations, and once it is no longer needed, users should call vesin_free to release the corresponding memory.

Parameters:

  • points – positions of all points in the system;

  • n_points – number of elements in the points array

  • box – bounding box for the system. If the system is non-periodic, this is ignored. This should contain the three vectors of the bounding box, one vector per row of the matrix.

  • periodic – is the system using periodic boundary conditions? This

  • device – device where the points and box data is allocated.

  • options – options for the calculation

  • neighbors – non-NULL pointer to VesinNeighborList that will be used to store the computed list of neighbors.

  • error_message – Pointer to a char* that wil be set to the error message if this function fails. This does not need to be freed when no longer needed.

void vesin_free(struct VesinNeighborList *neighbors)

Free all allocated memory inside a VesinNeighborList, according the it’s device.

struct VesinNeighborList

The actual neighbor list

This is organized as a list of pairs, where each pair can contain the following data:

  • indices of the points in the pair;

  • distance between points in the pair, accounting for periodic boundary conditions;

  • vector between points in the pair, accounting for periodic boundary conditions;

  • periodic shift that created the pair. This is only relevant when using periodic boundary conditions, and contains the number of bounding box we need to cross to create the pair. If the positions of the points are r_i and r_j, the bounding box is described by a matrix of three vectors H, and the periodic shift is S, the distance vector for a given pair will be given by r_ij = r_j - r_i + S @ H.

Under periodic boundary conditions, two atoms can be part of multiple pairs, each pair having a different periodic shift.

Public Members

size_t length

Number of pairs in this neighbor list.

VesinDevice device

Device used for the data allocations.

size_t (*pairs)[2]

Array of pairs (storing the indices of the first and second point in the pair), containing length elements.

int32_t (*shifts)[3]

Array of box shifts, one for each pair. This is only set if options.return_pairs was true during the calculation.

double *distances

Array of pair distance (i.e. distance between the two points), one for each pair. This is only set if options.return_distances was true during the calculation.

double (*vectors)[3]

Array of pair vector (i.e. vector between the two points), one for each pair. This is only set if options.return_vector was true during the calculation.

void *opaque = nullptr

Private pointer used to hold additional internal data.

struct VesinOptions

Options for a neighbor list calculation.

Public Members

double cutoff

Spherical cutoff, only pairs below this cutoff will be included.

bool full

Should the returned neighbor list be a full list (include both i -> j and j -> i pairs) or a half list (include only i -> j)?

bool sorted

Should the neighbor list be sorted? If yes, the returned pairs will be sorted using lexicographic order.

VesinAlgorithm algorithm

Which algorithm to use for the calculation.

bool return_shifts

Should the returned VesinNeighborList contain shifts?

bool return_distances

Should the returned VesinNeighborList contain distances?

bool return_vectors

Should the returned VesinNeighborList contain vector?

struct VesinDevice

Represents a device on which data can be allocated.

This structure combines the device type (CPU or CUDA) with an optional device index. For CPU allocations, device_id is always 0. For CUDA allocations, device_id specifies which GPU to use (e.g., 0, 1, 2).

Example usage: 

VesinDevice cpu { VesinCPU, 0 };
VesinDevice gpu0 { VesinCUDA, 0 };
VesinDevice gpu1 { VesinCUDA, 1 };

Public Members

VesinDeviceKind type

Type of the device.

int device_id = 0

Device index (0 for CPU, GPU index for CUDA)

enum VesinDeviceKind

Device on which the data can be.

Values:

enumerator VesinUnknownDevice

Unknown device, used for default initialization and to indicate no allocated data.

enumerator VesinCPU

CPU device.

enumerator VesinCUDA
enum VesinAlgorithm

Algorithm to use for neighbor list construction.

Values:

enumerator VesinAutoAlgorithm

Automatically select algorithm based on system characteristics (number of points, size of the box, …), this is the default and recommended option.

enumerator VesinBruteForce

Brute-force O(n^2) algorithm, this requires minimum image convention in CUDA, and is not available on CPU.

enumerator VesinCellList

Cell list algorithm with O(n) scaling.