Cluster Module¶
Overview
Finds clusters in a set of points. 

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.
Cluster¶

class
freud.cluster.
Cluster
(box, rcut)¶ Finds clusters in a set of points.
Given a set of coordinates and a cutoff,
freud.cluster.Cluster
will determine all of the clusters of points that are made up of points that are closer than the cutoff. Clusters are 0indexed. The class contains an index array, thecluster_idx
attribute, which can be used to identify which cluster a particle is associated with:cluster_obj.cluster_idx[i]
is the cluster index in which particlei
is found. By the definition of a cluster, points that are not within the cutoff of another point end up in their own 1particle cluster.Identifying micelles is one primary 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 particle (i.e. the polymer id), the computeClusterMembership function will processcluster_idx
with the key values in mind and provide a list of keys that are present in each cluster.Module author: Joshua Anderson <joaander@umich.edu>
 Parameters
box (
freud.box.Box
) – The simulation box.rcut (float) – Particle distance cutoff.
Note
2D:
freud.cluster.Cluster
properly handles 2D boxes. The points must be passed in as[x, y, 0]
. Failing to set z=0 will lead to undefined behavior. Variables
box (
freud.box.Box
) – Box used in the calculation.num_clusters (int) – The number of clusters.
num_particles (int) – The number of particles.
cluster_idx ((\(N_{particles}\))
numpy.ndarray
) – The cluster index for each particle.cluster_keys (list(list)) – A list of lists of the keys contained in each cluster.

computeClusterMembership
¶ Compute the clusters with key membership. Loops over all particles and adds them to a list of sets. Each set contains all the keys that are part of that cluster. Get the computed list with
cluster_keys
. Parameters
keys ((\(N_{particles}\))
numpy.ndarray
) – Membership keys, one for each particle.

computeClusters
¶ Compute the clusters for the given set of points.
 Parameters
points ((\(N_{particles}\), 3)
np.ndarray
) – Particle coordinates.nlist (
freud.locality.NeighborList
, optional) – Object to use to find bonds (Default value = None).box (
freud.box.Box
, optional) – Simulation box (Default value = None).

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

class
freud.cluster.
ClusterProperties
(box)¶ Routines for computing properties of point clusters.
Given a set of points and cluster ids (from
Cluster
, or another source), ClusterProperties determines the following properties for each cluster:Center of mass
Gyration tensor
The computed center of mass for each cluster (properly handling periodic boundary conditions) can be accessed with
cluster_COM
attribute. The \(3 \times 3\) gyration tensor \(G\) can be accessed withcluster_G
attribute. The tensor is symmetric for each cluster.Module author: Joshua Anderson <joaander@umich.edu>
 Parameters
box (
freud.box.Box
) – Simulation box. Variables
box (
freud.box.Box
) – Box used in the calculation.num_clusters (int) – The number of clusters.
cluster_COM ((\(N_{clusters}\), 3)
numpy.ndarray
) – The center of mass of the last computed cluster.cluster_G ((\(N_{clusters}\), 3, 3)
numpy.ndarray
) – The cluster \(G\) tensors computed by the last call tocomputeProperties()
.cluster_sizes ((\(N_{clusters}\))
numpy.ndarray
) – The cluster sizes computed by the last call tocomputeProperties()
.

computeProperties
¶ 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 \(G\) tensor. These can be accessed after the call to
computeProperties()
with thecluster_COM
andcluster_G
attributes. Parameters
points ((\(N_{particles}\), 3)
np.ndarray
) – Positions of the particles making up the clusters.cluster_idx (
np.ndarray
) – List of cluster indexes for each particle.box (
freud.box.Box
, optional) – Simulation box (Default value = None).