Locality Module

Overview

freud.locality.NeighborList Class representing a certain number of “bonds” between particles.
freud.locality.IteratorLinkCell Iterates over the particles in a cell.
freud.locality.LinkCell Supports efficiently finding all points in a set within a certain distance from a given point.
freud.locality.NearestNeighbors Supports efficiently finding the \(N\) nearest neighbors of each point in a set for some fixed integer \(N\).

Details

The locality module contains data structures to efficiently locate points based on their proximity to other points.

class freud.locality.NeighborList

Class representing a certain number of “bonds” between particles. Computation methods will iterate over these bonds when searching for neighboring particles.

NeighborList objects are constructed for two sets of position arrays A (alternatively reference points; of length \(n_A\)) and B (alternatively target points; of length \(n_B\)) and hold a set of \(\left(i, j\right): i < n_A, j < n_B\) index pairs corresponding to near-neighbor points in A and B, respectively.

For efficiency, all bonds for a particular reference particle \(i\) are contiguous and bonds are stored in order based on reference particle index \(i\). The first bond index corresponding to a given particle can be found in \(\log(n_{bonds})\) time using find_first_index().

Module author: Matthew Spellings <mspells@umich.edu>

New in version 0.6.4.

Note

Typically, there is no need to instantiate this class directly. In most cases, users should manipulate freud.locality.NeighborList objects received from a neighbor search algorithm, such as freud.locality.LinkCell, freud.locality.NearestNeighbors, or freud.voronoi.Voronoi.

Variables:
  • index_i (np.ndarray) – The reference point indices from the last set of points this object was evaluated with. This array is read-only to prevent breakage of find_first_index().
  • index_j (np.ndarray) – The reference point indices from the last set of points this object was evaluated with. This array is read-only to prevent breakage of find_first_index().
  • weights ((\(N_{bonds}\)) np.ndarray) – The per-bond weights from the last set of points this object was evaluated with.
  • segments ((\(N_{ref\_points}\)) np.ndarray) – A segment array, which is an array of length \(N_{ref}\) indicating the first bond index for each reference particle from the last set of points this object was evaluated with.
  • neighbor_counts ((\(N_{ref\_points}\)) np.ndarray) – A neighbor count array, which is an array of length \(N_{ref}\) indicating the number of neighbors for each reference particle from the last set of points this object was evaluated with.

Example:

# Assume we have position as Nx3 array
lc = LinkCell(box, 1.5).compute(box, positions)
nlist = lc.nlist

# Get all vectors from central particles to their neighbors
rijs = positions[nlist.index_j] - positions[nlist.index_i]
box.wrap(rijs)
copy(self, other=None)

Create a copy. If other is given, copy its contents into this object. Otherwise, return a copy of this object.

Parameters:other (freud.locality.NeighborList, optional) – A Neighborlist to copy into this object (Default value = None).
filter(self, filt)

Removes bonds that satisfy a boolean criterion.

Parameters:filt (np.ndarray) – Boolean-like array of bonds to keep (True means the bond will not be removed).

Note

This method modifies this object in-place.

Example:

# Keep only the bonds between particles of type A and type B
nlist.filter(types[nlist.index_i] != types[nlist.index_j])
filter_r(self, box, ref_points, points, float rmax, float rmin=0)

Removes bonds that are outside of a given radius range.

Parameters:
  • box (freud.box.Box) – Simulation box.
  • ref_points ((\(N_{particles}\), 3) numpy.ndarray) – Reference points to use for filtering.
  • points ((\(N_{particles}\), 3) numpy.ndarray) – Target points to use for filtering.
  • rmax (float) – Maximum bond distance in the resulting neighbor list.
  • rmin (float, optional) – Minimum bond distance in the resulting neighbor list (Default value = 0).
find_first_index(self, unsigned int i)

Returns the lowest bond index corresponding to a reference particle with an index \(\geq i\).

Parameters:i (unsigned int) – The particle index.
from_arrays(type cls, Nref, Ntarget, index_i, index_j, weights=None)

Create a NeighborList from a set of bond information arrays.

Parameters:
  • Nref (int) – Number of reference points (corresponding to index_i).
  • Ntarget (int) – Number of target points (corresponding to index_j).
  • index_i (np.array) – Array of integers corresponding to indices in the set of reference points.
  • index_j (np.array) – Array of integers corresponding to indices in the set of target points.
  • weights (np.array, optional) – Array of per-bond weights (if None is given, use a value of 1 for each weight) (Default value = None).
class freud.locality.IteratorLinkCell

Iterates over the particles in a cell.

Module author: Joshua Anderson <joaander@umich.edu>

Example:

# Grab particles in cell 0
for j in linkcell.itercell(0):
    print(positions[j])
next(self)

Implements iterator interface

class freud.locality.LinkCell(box, cell_width)

Supports efficiently finding all points in a set within a certain distance from a given point.

Module author: Joshua Anderson <joaander@umich.edu>

Parameters:
  • box (freud.box.Box) – Simulation box.
  • cell_width (float) – Maximum distance to find particles within.
Variables:
  • box (freud.box.Box) – Simulation box.
  • num_cells (unsigned int) – The number of cells in the box.
  • nlist (freud.locality.NeighborList) – The neighbor list stored by this object, generated by compute().
  • index_i (np.ndarray) – The reference point indices from the last set of points this object was evaluated with. This array is read-only to prevent breakage of find_first_index().
  • index_j (np.ndarray) – The reference point indices from the last set of points this object was evaluated with. This array is read-only to prevent breakage of find_first_index().
  • weights ((\(N_{bonds}\)) np.ndarray) – The per-bond weights from the last set of points this object was evaluated with.

Note

2D: freud.locality.LinkCell properly handles 2D boxes. The points must be passed in as [x, y, 0]. Failing to set z=0 will lead to undefined behavior.

Example:

# Assume positions are an Nx3 array
lc = LinkCell(box, 1.5)
lc.computeCellList(box, positions)
for i in range(positions.shape[0]):
    # Cell containing particle i
    cell = lc.getCell(positions[0])
    # List of cell's neighboring cells
    cellNeighbors = lc.getCellNeighbors(cell)
    # Iterate over neighboring cells (including our own)
    for neighborCell in cellNeighbors:
        # Iterate over particles in each neighboring cell
        for neighbor in lc.itercell(neighborCell):
            pass # Do something with neighbor index

# Using NeighborList API
dens = density.LocalDensity(1.5, 1, 1)
dens.compute(box, positions, nlist=lc.nlist)
compute(self, box, ref_points, points=None, exclude_ii=None)

Update the data structure for the given set of points and compute a NeighborList.

Parameters:
  • box (freud.box.Box) – Simulation box.
  • ref_points ((\(N_{particles}\), 3) numpy.ndarray) – Reference point coordinates.
  • points ((\(N_{particles}\), 3) numpy.ndarray, optional) – Point coordinates (Default value = None).
  • exclude_ii (bool, optional) – True if pairs of points with identical indices should be excluded; if None, is set to True if points is None or the same object as ref_points (Default value = None).
computeCellList(self, box, ref_points, points=None, exclude_ii=None)

Update the data structure for the given set of points and compute a NeighborList.

Parameters:
  • box (freud.box.Box) – Simulation box.
  • ref_points ((\(N_{particles}\), 3) numpy.ndarray) – Reference point coordinates.
  • points ((\(N_{particles}\), 3) numpy.ndarray, optional) – Point coordinates (Default value = None).
  • exclude_ii (bool, optional) – True if pairs of points with identical indices should be excluded; if None, is set to True if points is None or the same object as ref_points (Default value = None).
getBox(self)

Get the freud Box.

Returns:freud Box.
Return type:freud.box.Box
getCell(self, point)

Returns the index of the cell containing the given point.

Parameters:point (\(\left(3\right)\) numpy.ndarray) – Point coordinates \(\left(x,y,z\right)\).
Returns:Cell index.
Return type:unsigned int
getCellNeighbors(self, cell)

Returns the neighboring cell indices of the given cell.

Parameters:cell (unsigned int) – Cell index.
Returns:Array of cell neighbors.
Return type:\(\left(N_{neighbors}\right)\) numpy.ndarray
getNumCells(self)

Get the number of cells in this box.

Returns:The number of cells in this box.
Return type:unsigned int
itercell(self, unsigned int cell)

Return an iterator over all particles in the given cell.

Parameters:cell (unsigned int) – Cell index.
Returns:Iterator to particle indices in specified cell.
Return type:iter
class freud.locality.NearestNeighbors(rmax, n_neigh, scale=1.1, strict_cut=False)

Supports efficiently finding the \(N\) nearest neighbors of each point in a set for some fixed integer \(N\).

  • strict_cut == True: rmax will be strictly obeyed, and any particle which has fewer than \(N\) neighbors will have values of UINT_MAX assigned.
  • strict_cut == False (default): rmax will be expanded to find the requested number of neighbors. If rmax increases to the point that a cell list cannot be constructed, a warning will be raised and the neighbors already found will be returned.

Module author: Eric Harper <harperic@umich.edu>

Parameters:
  • rmax (float) – Initial guess of a distance to search within to find N neighbors.
  • n_neigh (unsigned int) – Number of neighbors to find for each point.
  • scale (float) – Multiplier by which to automatically increase rmax value if the requested number of neighbors is not found. Only utilized if strict_cut is False. Scale must be greater than 1.
  • strict_cut (bool) – Whether to use a strict rmax or allow for automatic expansion, default is False.
Variables:
  • UINTMAX (unsigned int) – Value of C++ UINTMAX used to pad the arrays.
  • box (freud.box.Box) – Simulation box.
  • num_neighbors (unsigned int) – The number of neighbors this object will find.
  • n_ref (unsigned int) – The number of particles this object found neighbors of.
  • r_max (float) – Current nearest neighbors search radius guess.
  • wrapped_vectors (\(\left(N_{particles}\right)\) numpy.ndarray) – The wrapped vectors padded with -1 for empty neighbors.
  • r_sq_list (\(\left(N_{particles}, N_{neighbors}\right)\) numpy.ndarray) – The Rsq values list.
  • nlist (freud.locality.NeighborList) – The neighbor list stored by this object, generated by compute().

Example:

nn = NearestNeighbors(2, 6)
nn.compute(box, positions, positions)
hexatic = order.HexOrderParameter(2)
hexatic.compute(box, positions, nlist=nn.nlist)
compute(self, box, ref_points, points=None, exclude_ii=None)

Update the data structure for the given set of points.

Parameters:
  • box (freud.box.Box) – Simulation box.
  • ref_points ((\(N_{particles}\), 3) numpy.ndarray) – Reference point coordinates.
  • points ((\(N_{particles}\), 3) numpy.ndarray, optional) – Point coordinates (Default value = None).
  • exclude_ii (bool, optional) – True if pairs of points with identical indices should be excluded; if None, is set to True if points is None or the same object as ref_points (Default value = None).
getBox(self)

Get the freud Box.

Returns:freud Box.
Return type:freud.box.Box
getNRef(self)

Get the number of particles this object found neighbors of.

Returns:The number of particles this object found neighbors of.
Return type:unsigned int
getNeighborList(self)

Return the entire neighbor list.

Returns:Neighbor List.
Return type:\(\left(N_{particles}, N_{neighbors}\right)\) numpy.ndarray
getNeighbors(self, unsigned int i)

Return the \(N\) nearest neighbors of the reference point with index \(i\).

Parameters:i (unsigned int) – Index of the reference point whose neighbors will be returned.
getNumNeighbors(self)

The number of neighbors this object will find.

Returns:The number of neighbors this object will find.
Return type:unsigned int
getRMax(self)

Return the current neighbor search distance guess.

Returns:Nearest neighbors search radius.
Return type:float
getRsq(self, unsigned int i)

Return the squared distances to the \(N\) nearest neighbors of the reference point with index \(i\).

Parameters:i (unsigned int) – Index of the reference point of which to fetch the neighboring point distances.
Returns:Squared distances to the \(N\) nearest neighbors.
Return type:\(\left(N_{particles}\right)\) numpy.ndarray
getRsqList(self)

Return the entire Rsq values list.

Returns:Rsq list.
Return type:\(\left(N_{particles}, N_{neighbors}\right)\) numpy.ndarray
getUINTMAX(self)
Returns:Value of C++ UINTMAX used to pad the arrays.
Return type:unsigned int
getWrappedVectors(self)

Return the wrapped vectors for computed neighbors. Array padded with -1 for empty neighbors.

Returns:Wrapped vectors.
Return type:\(\left(N_{particles}\right)\) numpy.ndarray
setCutMode(self, strict_cut)

Set mode to handle rmax by Nearest Neighbors.

  • strict_cut == True: rmax will be strictly obeyed, and any particle which has fewer than \(N\) neighbors will have values of UINT_MAX assigned.
  • strict_cut == False: rmax will be expanded to find the requested number of neighbors. If rmax increases to the point that a cell list cannot be constructed, a warning will be raised and the neighbors already found will be returned.
Parameters:strict_cut (bool) – Whether to use a strict rmax or allow for automatic expansion.
setRMax(self, float rmax)

Update the neighbor search distance guess.

Parameters:rmax (float) – Nearest neighbors search radius.