Cluster Module¶
Overview
Finds clusters using a network of neighbors. 

Routines for computing properties of point clusters. 
Details
The freud.cluster
module aids in finding and computing the properties
of clusters of points in a system.

class
freud.cluster.
Cluster
¶ Bases:
freud.locality._PairCompute
Finds clusters using a network of neighbors.
Given a set of points and their neighbors,
freud.cluster.Cluster
will determine all of the connected components of the network formed by those neighbor bonds. That is, two points are in the same cluster if and only if a path exists between them on the network of bonds. The class attributecluster_idx
holds an array of cluster indices for each point. By the definition of a cluster, points that are not bonded to any other point end up in their own 1point cluster.Identifying micelles is one usecase for finding clusters. This operation is somewhat different, though. In a cluster of points, each and every point belongs to one and only one cluster. However, because a string of points belongs to a polymer, that single polymer may be present in more than one cluster. To handle this situation, an optional layer is presented on top of the
cluster_idx
array. Given a key value per point (e.g. the polymer id), the compute function will process clusters with the key values in mind and provide a list of keys that are present in each cluster in the attributecluster_keys
, as a list of lists. If keys are not provided, every point is assigned a key corresponding to its index, andcluster_keys
contains the point ids present in each cluster.
property
cluster_idx
¶ The cluster index for each point.
 Type
(\(N_{points}\))
numpy.ndarray

compute
(self, system, keys=None, neighbors=None)¶ Compute the clusters for the given set of points.
 Parameters
system – Any object that is a valid argument to
freud.locality.NeighborQuery.from_system
.keys ((\(N_{points}\))
numpy.ndarray
) – Membership keys, one for each point.neighbors (
freud.locality.NeighborList
or dict, optional) – Either aNeighborList
of neighbor pairs to use in the calculation, or a dictionary of query arguments (Default value: None).

default_query_args
¶ No default query arguments.

plot
(self, ax=None)¶ Plot cluster distribution.
 Parameters
ax (
matplotlib.axes.Axes
, optional) – Axis to plot on. IfNone
, make a new figure and axis. (Default value =None
) Returns
Axis with the plot.
 Return type

property

class
freud.cluster.
ClusterProperties
¶ Bases:
freud.util._Compute
Routines for computing properties of point clusters.
Given a set of points and cluster ids (from
Cluster
or another source), this class determines the following properties for each cluster:Center of mass
Gyration tensor
Size (number of points)
The center of mass for each cluster (properly handling periodic boundary conditions) can be accessed with
centers
attribute. The \(3 \times 3\) symmetric gyration tensors \(G\) can be accessed withgyrations
attribute.
property
centers
¶ The centers of mass of the clusters.
 Type
(\(N_{clusters}\), 3)
numpy.ndarray

compute
(self, system, cluster_idx)¶ Compute properties of the point clusters. Loops over all points in the given array and determines the center of mass of the cluster as well as the gyration tensor. After calling this method, these properties can be accessed with the
centers
andgyrations
attributes.Example:
>>> import freud >>> # Compute clusters using box, positions, and nlist data >>> box, points = freud.data.make_random_system(10, 100) >>> cl = freud.cluster.Cluster() >>> cl.compute((box, points), neighbors={'r_max': 1.0}) freud.cluster.Cluster() >>> # Compute cluster properties based on identified clusters >>> cl_props = freud.cluster.ClusterProperties() >>> cl_props.compute((box, points), cl.cluster_idx) freud.cluster.ClusterProperties()
 Parameters
system – Any object that is a valid argument to
freud.locality.NeighborQuery.from_system
.cluster_idx ((\(N_{points}\),)
np.ndarray
) – Cluster indexes for each point.

property
gyrations
¶ The gyration tensors of the clusters.
 Type
(\(N_{clusters}\), 3, 3)
numpy.ndarray

property
radii_of_gyration
¶ The radius of gyration of each cluster.
 Type
(\(N_{clusters}\),)
numpy.ndarray

property
sizes
¶ The cluster sizes.
 Type
(\(N_{clusters}\))
numpy.ndarray