Locality Module

Overview

freud.locality.AABBQuery

Use an AABB tree to find neighbors.

freud.locality.LinkCell

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

freud.locality.NeighborList

Class representing bonds between two sets of points.

freud.locality.NeighborQuery

Class representing a set of points along with the ability to query for neighbors of these points.

freud.locality.NeighborQueryResult

Class encapsulating the output of queries of NeighborQuery objects.

freud.locality.PeriodicBuffer

Replicate periodic images of points inside a box.

freud.locality.Voronoi

Computes Voronoi diagrams using voro++.

Details

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

class freud.locality.AABBQuery

Bases: freud.locality.NeighborQuery

Use an AABB tree to find neighbors.

Also available as freud.AABBQuery.

box

The box object used by this data structure.

Type

freud.box.Box

classmethod from_system(type cls, system)

Create a NeighborQuery from any system-like object.

The standard concept of a system in freud is any object that provides a way to access a box-like object (anything that can be coerced to a box by freud.box.Box.from_box()) and an array-like (according to NumPy’s definition) object that turns into a \(N\times 3\) array.

Supported types for system include:

Parameters

system (system-like object) – Any object that can be converted to a NeighborQuery.

Returns

The same NeighborQuery object if one is given, or an instance of NeighborQuery built from an inferred box and points.

Return type

freud.locality.NeighborQuery

plot

Plot system box and points.

Parameters
Returns

Axis with the plot.

Return type

matplotlib.axes.Axes

points

The array of points in this data structure.

Type

np.ndarray

query

Query for nearest neighbors of the provided point.

Parameters
  • query_points ((\(N\), 3) numpy.ndarray) – Points to query for.

  • query_args (dict) – Query arguments determining how to find neighbors. For information on valid query argument, see the Query API.

Returns

Results object containing the output of this query.

Return type

NeighborQueryResult

class freud.locality.LinkCell

Bases: freud.locality.NeighborQuery

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

Also available as freud.LinkCell.

Parameters
  • box (freud.box.Box) – Simulation box.

  • points (np.ndarray) – The points to bin into the cell list.

  • cell_width (float, optional) – Width of cells. If not provided, ~.LinkCell will estimate a cell width based on the number of points and the box size assuming constant density of points throughout the box.

box

The box object used by this data structure.

Type

freud.box.Box

cell_width

Cell width.

Type

float

classmethod from_system(type cls, system)

Create a NeighborQuery from any system-like object.

The standard concept of a system in freud is any object that provides a way to access a box-like object (anything that can be coerced to a box by freud.box.Box.from_box()) and an array-like (according to NumPy’s definition) object that turns into a \(N\times 3\) array.

Supported types for system include:

Parameters

system (system-like object) – Any object that can be converted to a NeighborQuery.

Returns

The same NeighborQuery object if one is given, or an instance of NeighborQuery built from an inferred box and points.

Return type

freud.locality.NeighborQuery

plot

Plot system box and points.

Parameters
Returns

Axis with the plot.

Return type

matplotlib.axes.Axes

points

The array of points in this data structure.

Type

np.ndarray

query

Query for nearest neighbors of the provided point.

Parameters
  • query_points ((\(N\), 3) numpy.ndarray) – Points to query for.

  • query_args (dict) –

    Query arguments determining how to find neighbors. For information on valid query argument, see the Query API.

Returns

Results object containing the output of this query.

Return type

NeighborQueryResult

class freud.locality.NeighborList

Bases: object

Class representing bonds between two sets of points.

Compute classes contain a set of bonds between two sets of position arrays (“query points” and “points”) and hold a list of index pairs \(\left(i, j\right)\) where \(i < N_{query\_points}, j < N_{points}\) corresponding to neighbor pairs between the two sets.

For efficiency, all bonds must be sorted by the query point index, from least to greatest. Bonds have an query point index \(i\) and a point index \(j\). The first bond index corresponding to a given query point can be found in \(\log(N_{bonds})\) time using find_first_index(), because bonds are ordered by the query point index.

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.AABBQuery, or freud.locality.Voronoi.

Also available as freud.NeighborList.

Example:

# Assume we have position as Nx3 array
aq = freud.locality.AABBQuery(box, positions)
nlist = aq.query(positions, {'r_max': 3}).toNeighborList()

# Get all vectors from central particles to their neighbors
rijs = (positions[nlist.point_indices] -
       positions[nlist.query_point_indices])
rijs = box.wrap(rijs)

The NeighborList can be indexed to access bond particle indices. Example:

for i, j in nlist[:]:
    print(i, j)
copy

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

distances

The distances for each bond.

Type

(\(N_{bonds}\)) np.ndarray

filter

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.query_point_indices] != types[nlist.point_indices])
filter_r

Removes bonds that are outside of a given radius range.

Parameters
  • r_max (float) – Maximum bond distance in the resulting neighbor list.

  • r_min (float, optional) – Minimum bond distance in the resulting neighbor list (Default value = 0).

find_first_index

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

Parameters

i (unsigned int) – The particle index.

classmethod from_arrays(type cls, num_query_points, num_points, query_point_indices, point_indices, distances, weights=None)

Create a NeighborList from a set of bond information arrays.

Parameters
  • num_query_points (int) – Number of query points (corresponding to query_point_indices).

  • num_points (int) – Number of points (corresponding to point_indices).

  • query_point_indices (np.ndarray) – Array of integers corresponding to indices in the set of query points.

  • point_indices (np.ndarray) – Array of integers corresponding to indices in the set of points.

  • distances (np.ndarray) – Array of distances between corresponding query points and points.

  • weights (np.ndarray, optional) – Array of per-bond weights (if None is given, use a value of 1 for each weight) (Default value = None).

neighbor_counts

A neighbor count array indicating the number of neighbors for each query point.

Type

(\(N_{query\_points}\)) np.ndarray

point_indices

The point indices for each bond. This array is read-only to prevent breakage of find_first_index(). Equivalent to indexing with [:, 1].

Type

(\(N_{bonds}\)) np.ndarray

query_point_indices

The query point indices for each bond. This array is read-only to prevent breakage of find_first_index(). Equivalent to indexing with [:, 0].

Type

(\(N_{bonds}\)) np.ndarray

segments

A segment array indicating the first bond index for each query point.

Type

(\(N_{query\_points}\)) np.ndarray

weights

The weights for each bond. By default, bonds have a weight of 1.

Type

(\(N_{bonds}\)) np.ndarray

class freud.locality.NeighborQuery

Bases: object

Class representing a set of points along with the ability to query for neighbors of these points.

Warning

This class should not be instantiated directly. The subclasses AABBQuery and LinkCell provide the intended interfaces.

The NeighborQuery class represents the abstract interface for neighbor finding. The class contains a set of points and a simulation box, the latter of which is used to define the system and the periodic boundary conditions required for finding neighbors of these points. The primary mode of interacting with the NeighborQuery is through the query() and queryBall() functions, which enable finding either the nearest neighbors of a point or all points within a distance cutoff, respectively. Subclasses of NeighborQuery implement these methods based on the nature of the underlying data structure.

Parameters
box

The box object used by this data structure.

Type

freud.box.Box

classmethod from_system(type cls, system)

Create a NeighborQuery from any system-like object.

The standard concept of a system in freud is any object that provides a way to access a box-like object (anything that can be coerced to a box by freud.box.Box.from_box()) and an array-like (according to NumPy’s definition) object that turns into a \(N\times 3\) array.

Supported types for system include:

Parameters

system (system-like object) – Any object that can be converted to a NeighborQuery.

Returns

The same NeighborQuery object if one is given, or an instance of NeighborQuery built from an inferred box and points.

Return type

freud.locality.NeighborQuery

plot

Plot system box and points.

Parameters
Returns

Axis with the plot.

Return type

matplotlib.axes.Axes

points

The array of points in this data structure.

Type

np.ndarray

query

Query for nearest neighbors of the provided point.

Parameters
  • query_points ((\(N\), 3) numpy.ndarray) – Points to query for.

  • query_args (dict) –

    Query arguments determining how to find neighbors. For information on valid query argument, see the Query API.

Returns

Results object containing the output of this query.

Return type

NeighborQueryResult

class freud.locality.NeighborQueryResult

Bases: object

Class encapsulating the output of queries of NeighborQuery objects.

Warning

This class should not be instantiated directly, it is the return value of all query* functions of NeighborQuery. The class provides a convenient interface for iterating over query results, and can be transparently converted into a list or a NeighborList object.

The NeighborQueryResult makes it easy to work with the results of queries and convert them to various natural objects. Additionally, the result is a generator, making it easy for users to lazily iterate over the object.

toNeighborList

Convert query result to a freud NeighborList.

Returns

A freud NeighborList containing all neighbor pairs found by the query generating this result object.

Return type

NeighborList

class freud.locality.PeriodicBuffer

Bases: freud.util._Compute

Replicate periodic images of points inside a box.

property buffer_box

The buffer box, expanded to hold the replicated points.

Type

freud.box.Box

property buffer_ids

The buffer point ids.

Type

\(\left(N_{buffer}\right)\) numpy.ndarray

property buffer_points

The buffer point positions.

Type

\(\left(N_{buffer}, 3\right)\) numpy.ndarray

compute

Compute the periodic buffer.

Parameters
  • system – Any object that is a valid argument to freud.locality.NeighborQuery.from_system.

  • buffer (float or list of 3 floats) – Buffer distance for replication outside the box.

  • images (bool, optional) – If False, buffer is a distance. If True, buffer is a number of images to replicate in each dimension. Note that one image adds half of a box length to each side, meaning that one image doubles the box side lengths, two images triples the box side lengths, and so on. (Default value = False).

class freud.locality.Voronoi

Bases: freud.util._Compute

Computes Voronoi diagrams using voro++.

Voronoi diagrams (Wikipedia) are composed of convex polytopes (polyhedra in 3D, polygons in 2D) called cells, corresponding to each input point. The cells bound a region of Euclidean space for which all contained points are closer to a corresponding input point than any other input point. A ridge is defined as a boundary between cells, which contains points equally close to two or more input points.

The voro++ library [Ryc09] is used for fast computations of the Voronoi diagram.

compute

Compute Voronoi diagram.

Parameters

system – Any object that is a valid argument to freud.locality.NeighborQuery.from_system.

property nlist

Returns the computed NeighborList.

The NeighborList computed by this class is weighted. In 2D systems, the bond weight is the length of the ridge (boundary line) between the neighboring points’ Voronoi cells. In 3D systems, the bond weight is the area of the ridge (boundary polygon) between the neighboring points’ Voronoi cells. The weights are not normalized, and the weights for each query point sum to the surface area (perimeter in 2D) of the polytope.

It is possible for pairs of points to appear multiple times in the neighbor list. For example, in a small unit cell, points may neighbor one another on multiple sides because of periodic boundary conditions.

Returns

Neighbor list.

Return type

NeighborList

plot

Plot Voronoi diagram.

Parameters

ax (matplotlib.axes.Axes) – Axis to plot on. If None, make a new figure and axis. (Default value = None)

color_by_sides (bool):

If True, color cells by the number of sides. If False, random colors are used for each cell. (Default value = True)

cmap (str):

Colormap name to use (Default value = None).

Returns

Axis with the plot.

Return type

matplotlib.axes.Axes

property polytopes

A list of numpy.ndarray defining Voronoi polytope vertices for each cell.

Type

list[numpy.ndarray]

property volumes

Returns an array of Voronoi cell volumes (areas in 2D).

Type

\(\left(N_{points} \right)\) numpy.ndarray