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], bool periodic, 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?

  • 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.

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 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?

enum VesinDevice

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.