amep.order.nearest_neighbors#

amep.order.nearest_neighbors(coords: ndarray, box_boundary: ndarray, other_coords: ndarray | None = None, rmax: float = 1.0, pbc: bool = True, exclude: bool = True, enforce_nd: int | None = None) → ndarray#

Calculates the nearest neighbors within a distance cutoff and returns the number of nearest neighbors, the nearest-neighbor distances, and the nearest-neighbor indices.

Parameters:

coords (np.ndarray of shape (N,3)) – Array of coordinates/points to search for neighbors.
box_boundary (np.ndarray of shape (3,2)) – Boundary of the simulation box in the form of np.array([[xmin, xmax], [ymin, ymax], [zmin, zmax]]).
other_coords (np.ndarray of shape (M,3) or None, optional) – Array of points to search for neighbors of. The default is None (use coords).
rmax (float, optional) – Distance cutoff. Only neighbors with distance smaller than the cutoff are returned. The default is 1.0.
pbc (boolean, optional) – If True, periodic boundary conditions are used. The default is True.
exclude (boolean, optional) – If True, the particle itself is excluded in the neighbor counting. The default is True.
enforce_nd (int, None, optional) – enforces the number of dimensions. 2 for 2d, 3 for 3d. If None is supplied, a best guess is used by checking if all particles have the same dimension in the last coordinate. See utils.dimension()

Returns:

nnn (np.ndarray of shape (N,)) – Number of nearest neighbors.
distances (np.ndarray of shape (N,)) – Array of lists containing the nearest-neighbor distances.
neighbors (np.ndarray of shape (N,)) – Array of lists containing the nearest-neighbor indices.

Examples

Create a test setup of a box and some particles at certain positions:

>>> import amep
>>> import numpy as np
>>> coords = np.array([[0,0,0],[1,0,0],[0,1,0],[-1,0,0],[0,-2,0]])
>>> box_boundary = np.array([[-4,4],[-4,4],[-0.5,0.5]])
>>> fig, axs = amep.plot.new(figsize=(3,3))
>>> amep.plot.box(axs, box_boundary, ls='--')
>>> axs.plot(coords[:,0], coords[:,1], "x", c="k")
>>> axs.set_xlabel(r'$x$')
>>> axs.set_ylabel(r'$y$')
>>> fig.savefig('./figures/order/order-nearest_neighbors.png')
>>>

Calculate nearest neighbors without periodic boundary conditions:

>>> nnn, distances, neighbors = amep.order.nearest_neighbors(
...     coords, box_boundary, rmax=5, pbc=False
... )
>>> print(nnn) # number of nearest neighbors
[4 4 4 4 4]
>>> print(distances) # nearest-neighbor distances
[[1.0 1.0 1.0 2.0]
 [1.0 1.4142135623730951 2.0 2.23606797749979]
 [1.0 1.4142135623730951 1.4142135623730951 3.0]
 [1.0 2.0 1.4142135623730951 2.23606797749979]
 [2.0 2.23606797749979 3.0 2.23606797749979]]
>>> print(neighbors) # nearest neighbor ids
[[1 2 3 4]
 [0 2 3 4]
 [0 1 3 4]
 [0 1 2 4]
 [0 1 2 3]]
>>>

Calculate nearest neighbors with periodic boundary conditions:

>>> nnn, distances, neighbors = amep.order.nearest_neighbors(
...     coords, box_boundary, rmax=5, pbc=True
... )
>>> print(nnn) # number of nearest neighbors
[4 4 5 4 5]
>>> print(distances) # nearest-neighbor distances
[list([1.0, 1.0, 1.0, 2.0])
 list([1.0, 1.4142135623730951, 2.0, 2.23606797749979])
 list([1.0, 1.4142135623730951, 1.4142135623730951, 3.0, 5.0])
 list([1.0, 2.0, 1.4142135623730951, 2.23606797749979])
 list([2.0, 2.23606797749979, 3.0, 2.23606797749979, 5.0])]
>>> print(neighbors) # nearest neighbor ids
[list([1, 2, 3, 4]) list([0, 2, 3, 4]) list([0, 1, 3, 4, 4])
 list([0, 1, 2, 4]) list([0, 1, 2, 3, 2])]
>>>

Calculate nearest neighbors of all coords in other_coords:

>>> nnn, distances, neighbors = amep.order.nearest_neighbors(
...     coords[1:], box_boundary, rmax=5,
...     pbc=False, other_coords=coords[0:1]
... )
>>> print(nnn) # number of nearest neighbors
[1 1 1 1]
>>> print(distances) # nearest-neighbor distances
[[1.0]
 [1.0]
 [1.0]
 [2.0]]
>>> print(neighbors) # nearest neighbor ids
[[0]
 [0]
 [0]
 [0]]
>>>