Python API reference

class vesin.NeighborList(cutoff: float, full_list: bool, sorted: bool = False, algorithm: str = 'auto', skin: float = 0.0)

A neighbor list calculator.

Parameters:

  • cutoff – spherical cutoff for this neighbor list

  • full_list – should we return each pair twice (as i-j and j-i) or only once

  • sorted – Should the neighbor list be sorted? If True, the returned pairs will be sorted by the first point index (i). The order of the second point index (j) and shifts in the list of pairs is unspecified.

  • algorithm – algorithm to use when computing the neighbor list. One of "auto", "brute_force", or "cell_list".

  • skin – skin size for Verlet caching. A positive value enables caching the neighbor list until any atom moves farther than skin/2 from its reference coordinates.

property algorithm: str

Get the current algorithm used for NL computation.

compute(points: numpy.typing.ArrayLike, box: numpy.typing.ArrayLike, periodic: bool | Sequence[bool] | TypeAliasForwardRef('numpy.typing.ArrayLike'), quantities: str = 'ij', copy=True) → List[ndarray]

Compute the neighbor list for the system defined by positions, box, and periodic; returning the requested quantities.

quantities can contain any combination of the following values:

  • "i" to get the index of the first point in the pair

  • "j" to get the index of the second point in the pair

  • "P" to get the indexes of the two points in the pair simultaneously

  • "S" to get the periodic shift of the pair

  • "d" to get the distance between points in the pair

  • "D" to get the distance vector between points in the pair

Parameters:

  • points – positions of all points in the system (this can be anything that can be converted to a numpy or cupy array)

  • box – bounding box of the system (this can be anything that can be converted to a numpy or cupy array)

  • periodic – should we use periodic boundary conditions? This can be a single boolean to enable/disable periodic boundary conditions in all directions, or a sequence of three booleans (one for each direction).

  • quantities – quantities to return, defaults to “ij”

  • copy – should we copy the returned quantities, defaults to True. Setting this to False might be a bit faster, but the returned arrays are view inside this class, and will be invalidated whenever this class is garbage collected or used to run a new calculation.

Returns:

tuple of arrays as indicated by quantities.

vesin.ase_neighbor_list(quantities, a, cutoff, self_interaction=False, max_nbins=0)

This is a thin wrapper around NeighborList, providing the same API as ase.neighborlist.neighbor_list().

It is intended as a drop-in replacement for the ASE function, but only supports a subset of the functionality. Notably, the following is not supported:

  • self_interaction=True

  • ase.Atoms with mixed periodic boundary conditions

  • giving cutoff as a dictionary

Note

The returned neighbor list will be sorted by the first point index (i) since this is what ASE does. This takes some time, so if you don’t need the neighbor list to be sorted, you can get better performance by using NeighborList directly.

Parameters:

  • quantities – quantities to output from the neighbor list. Supported are "i", "j", "d", "D", and "S" with the same meaning as in ASE.

  • a – ase.Atoms instance

  • cutoff – cutoff radius for the neighbor list

  • self_interaction – Should an atom be considered its own neighbor? Default: False

  • max_nbins – for ASE compatibility, ignored by this implementation