Cluster Module¶

Cluster Functions¶

class freud.cluster.Cluster(box, rcut)¶

Finds clusters in a set of points.

Given a set of coordinates and a cutoff, Cluster will determine all of the clusters of points that are made up of points that are closer than the cutoff. Clusters are labelled from 0 to the number of clusters-1 and an index array is returned where cluster_idx[i] is the cluster index in which particle i is found. By the definition of a cluster, points that are not within the cutoff of another point end up in their own 1-particle cluster.

Identifying micelles is one primary 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 particle (i.e. the polymer id), the computeClusterMembership function will process cluster_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`) – `freud.box.Box` rcut (float) – Particle distance cutoff

Note

2D: Cluster properly handles 2D boxes. As with everything else in freud, 2D points must be passed in as 3 component vectors \(\left(x,y,0\right)\). Failing to set 0 in the third component will lead to undefined behavior.

box¶

Return the stored freud Box

Returns:	freud Box
Return type:	`freud.box.Box`

cluster_idx¶

Returns 1D array of Cluster idx for each particle

Returns:	1D array of cluster idx
Return type:	`numpy.ndarray`, shape=(\(N_{particles}\)), dtype= `numpy.uint32`

cluster_keys¶

Returns the keys contained in each cluster

Returns:	list of lists of each key contained in clusters
Return type:	list

computeClusterMembership(self, keys)¶

Compute the clusters with key membership

Loops overa 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 getClusterKeys().

Parameters:	keys (`numpy.ndarray`, shape=(\(N_{particles}\)), dtype= `numpy.uint32`) – Membership keys, one for each particle

computeClusters(self, points, nlist=None)¶

Compute the clusters for the given set of points

Parameters:	points (`numpy.ndarray`, shape=(\(N_{particles}\), 3), dtype= `numpy.float32`) – particle coordinates nlist (`freud.locality.NeighborList`) – `freud.locality.NeighborList` object to use to find bonds

getBox(self)¶

Return the stored freud Box

Returns:	freud Box
Return type:	`freud.box.Box`

getClusterIdx(self)¶

Returns 1D array of Cluster idx for each particle

Returns:	1D array of cluster idx
Return type:	`numpy.ndarray`, shape=(\(N_{particles}\)), dtype= `numpy.uint32`

getClusterKeys(self)¶

Returns the keys contained in each cluster

Returns:	list of lists of each key contained in clusters
Return type:	list

getNumClusters(self)¶

Returns the number of clusters

Returns:	number of clusters
Return type:	int

getNumParticles(self)¶: Returns the number of particles :return: number of particles :rtype: int

num_clusters¶

Returns the number of clusters

Returns:	number of clusters
Return type:	int

num_particles¶

Returns the number of particles

Returns:	number of particles
Return type:	int

class freud.cluster.ClusterProperties(box)¶

Routines for computing properties of point clusters

Given a set of points and cluster_idx (from Cluster, or another source), ClusterProperties determines the following properties for each cluster:

Center of mass

Gyration radius tensor

m_cluster_com stores the computed center of mass for each cluster (properly handling periodic boundary conditions, of course) as a numpy.ndarray, shape= \(\left(N_{clusters}, 3 \right)\).

m_cluster_G stores a \(3 \times 3\) G tensor for each cluster. Index cluster c, element j, i with the following: m_cluster_G[c*9 + j*3 + i]. The tensor is symmetric, so the choice of i and j are irrelevant. This is passed back to python as a \(N_{clusters} \times 3 \times 3\) numpy array.

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

Parameters:	box (`freud.box.Box`) – simulation box

box¶

Return the stored freud Box

Returns:	freud Box
Return type:	`freud.box.Box`

cluster_COM¶

Returns the center of mass of the last computed cluster

Returns:	numpy array of cluster center of mass coordinates \(\left(x,y,z\right)\)
Return type:	`numpy.ndarray`, shape=(\(N_{clusters}\), 3), dtype= `numpy.float32`

cluster_G¶

Returns the cluster G tensors computed by the last call to computeProperties

Returns:	numpy array of cluster center of mass coordinates \(\left(x,y,z\right)\)
Return type:	`numpy.ndarray`, shape=(\(N_{clusters}\), 3, 3), dtype= `numpy.float32`

cluster_sizes¶

Returns the cluster sizes computed by the last call to computeProperties

Returns:	numpy array of sizes of each cluster
Return type:	`numpy.ndarray`, shape=(\(N_{clusters}\)), dtype= `numpy.uint32`

computeProperties(self, points, 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 G tensor. These can be accessed after the call to compute with getClusterCOM() and getClusterG().

Parameters:	points (`numpy.ndarray`, shape=(\(N_{particles}\), 3), dtype= `numpy.float32`) – Positions of the particles making up the clusters cluster_idx (`numpy.ndarray`, shape=(\(N_{particles}\)), dtype= `numpy.uint32`) – Index of which cluster each point belongs to

getBox(self)¶

Return the stored freud.box.Box object

Returns:	freud Box
Return type:	`freud.box.Box`

getClusterCOM(self)¶

Returns the center of mass of the last computed cluster

Returns:	numpy array of cluster center of mass coordinates \(\left(x,y,z\right)\)
Return type:	`numpy.ndarray`, shape=(\(N_{clusters}\), 3), dtype= `numpy.float32`

getClusterG(self)¶

Returns the cluster G tensors computed by the last call to computeProperties

Returns:	numpy array of cluster center of mass coordinates \(\left(x,y,z\right)\)
Return type:	`numpy.ndarray`, shape=(\(N_{clusters}\), 3, 3), dtype= `numpy.float32`

getClusterSizes(self)¶

Returns the cluster sizes computed by the last call to computeProperties

Returns:	numpy array of sizes of each cluster
Return type:	`numpy.ndarray`, shape=(\(N_{clusters}\)), dtype= `numpy.uint32`

getNumClusters(self)¶

Count the number of clusters found in the last call to computeProperties()

Returns:	number of clusters
Return type:	int

num_clusters¶

Returns the number of clusters

Returns:	number of clusters
Return type:	int