Cluster Module



Finds clusters using a network of neighbors.


Routines for computing properties of point clusters.


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

class freud.cluster.Cluster

Bases: _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 attribute cluster_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 1-point cluster.

Identifying micelles is one use-case 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 attribute cluster_keys, as a list of lists. If keys are not provided, every point is assigned a key corresponding to its index, and cluster_keys contains the point ids present in each cluster.

property cluster_idx

The cluster index for each point.


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

property cluster_keys

A list of lists of the keys contained in each cluster.



compute(self, system, keys=None, neighbors=None)

Compute the clusters for the given set of points.


No default query arguments.

property num_clusters

The number of clusters.



plot(self, ax=None)

Plot cluster distribution.


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


Axis with the plot.

Return type:


class freud.cluster.ClusterProperties

Bases: _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:

  • Geometric center

  • Center of mass

  • Gyration tensor

  • Moment of inertia tensor

  • Size (number of points)

  • Mass (total mass of each cluster)


The center of mass and geometric center for each cluster are computed using the minimum image convention

property centers

The geometric centers of the clusters, independent of mass and defined as

\[\mathbf{C}_g^k = \frac{1}{N_k} \sum_{i=0}^{N_k} \mathbf{r_i}\]

where \(\mathbf{C}_g^k\) is the center of the \(k\) th cluster, \(N_k\) is the number of particles in the \(k\) th cluster and \(\mathbf{r_i}\) are their positions.


(\(N_{clusters}\), 3) numpy.ndarray

property centers_of_mass

The centers of mass of the clusters:

\[\mathbf{C}_m^k = \frac{1}{M_k} \sum_{i=0}^{N_k} m_i \mathbf{r_i}\]

where \(\mathbf{C}_m^k\) is the center of mass of the \(k\) th cluster, \(M_k\) is the total mass of particles in the \(k\) th cluster, \(\mathbf{r_i}\) are their positions and \(m_i\) are their masses.


(\(N_{clusters}\), 3) numpy.ndarray

property cluster_masses

The total mass of particles in each cluster.


(\(N_{clusters}\)) numpy.ndarray

compute(self, system, cluster_idx, masses=None)

Compute properties of the point clusters. Loops over all points in the given array and determines the geometric center, center of mass, moment of inertia, gyration tensors, and radius of gyration [VymvetalVondravsek11] of each cluster. After calling this method, properties can be accessed via their attributes.


>>> import freud
>>> # Compute clusters using box, positions, and nlist data
>>> box, points =, 100)
>>> cl = freud.cluster.Cluster()
>>> cl.compute((box, points), neighbors={'r_max': 1.0})
>>> # Compute cluster properties based on identified clusters
>>> cl_props = freud.cluster.ClusterProperties()
>>> cl_props.compute((box, points), cl.cluster_idx)
  • 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.

  • masses ((\(N_{points}\), ) numpy.ndarray) – Masses corresponding to each point, defaulting to 1 if not provided or None (Default value = None).

property gyrations

The gyration tensors of the clusters. Normalized by particle number:

\[\begin{split}\mathbf{S}_k = \frac{1}{N_k} \begin{bmatrix} \sum_i x_i^2 & \sum_i x_i y_i & \sum_i x_i z_i \\ \sum_i y_i x_i & \sum_i y_i^2 & \sum_i y_i z_i \\ \sum_i z_i x_i & \sum_i z_i y_i & \sum_i z_i^2 \\ \end{bmatrix}\end{split}\]

where \(\mathbf{S}_k\) is the gyration tensor of the \(k\) th cluster.


(\(N_{clusters}\), 3, 3) numpy.ndarray

property inertia_tensors

The inertia tensors of the clusters. Neither normalized by mass nor number:

\[\begin{split}\mathbf{I}_k = \begin{bmatrix} \sum_i m_i(y_i^2+z_i^2)& \sum_i -m_i(x_iy_i)& \sum_i -m_i(x_iz_i)\\ \sum_i -m_i(y_ix_i)& \sum_i m_i(x_i^2+z_i^2)& \sum_i -m_i(y_iz_i)\\ \sum_i -m_i(z_ix_i)& \sum_i -m_i(z_iy_i)& \sum_i m_i(y_i^2+x_i^2)\\ \end{bmatrix}\end{split}\]

where \(\mathbf{I}_k\) is the inertia tensor of the \(k\) th cluster.


(\(N_{clusters}\), 3, 3) numpy.ndarray

property radii_of_gyration

The radius of gyration of each cluster. Defined by IUPAP as

\[R_g^k = \left(\frac{1}{M} \sum_{i=0}^{N_k} m_i s_i^2 \right)^{1/2}\]

where \(s_i\) is the distance of particle \(i\) from the center of mass.


(\(N_{clusters}\),) numpy.ndarray

property sizes

The cluster sizes.


(\(N_{clusters}\)) numpy.ndarray