Cluster analysis

Input:Output:

This modifier decomposes the particles into disconnected groups (so-called clusters) based on the selected neighboring criterion. The neighboring criterion can be distance-based (cutoff range) or topology-based (bond network).

A cluster is defined as a set of connected particles, each of which is within the (indirect) reach of the other particles in the same cluster. Thus, any two particles from the same cluster are connected by a continuous path consisting of steps that fulfill the selected neighboring criterion. Conversely, two particles will belong to different clusters if there is no such continuous path connecting the two particles on the neighbor graph.

Connectivity criterion

You can choose between two clustering modes: In case of the distance-based mode, two particles are considered connected if they are within a specified proximity range of each other. In case of the bond-based mode, two particles are considered connected if there exists a bond between them. Note that particles not connected to any other particle will each form a single-particle cluster by itself.

Cluster numbering

The clusters identified by the modifier are numbered from 1 to N, the total number of clusters. The algorithm assigns each input particle to one of these clusters and outputs this information as a new particle property named Cluster. Note that the ordering of clusters is arbitrary by default and can depend on the storage order of input particles. You can activate the Sort clusters by size option to request the ordering of cluster IDs by descending particle count. This guarantees that the first cluster (ID 1) will be the one having the largest number of particles.

Center of mass calculation

The modifier can optionally compute the center of mass of each cluster and output this information as an additional column in the generated clusters list (see below). Note that the current program version does not take the particle masses into account in the calculation but uses the same uniform weight for every particle. The center of mass of a cluster cut by a periodic simulation cell boundary will be correctly computed. However, if a cluster is infinite in the sense that it reconnects to itself through the periodic boundaries of the simulation domain, the results will be undefined.

Unwrapping of particle coordinates

The modifier provides the option to "unwrap" the coordinates of particles belonging to the same cluster, mapping them from inside the periodic simulation domain to outside in order for the cluster to appear as a contiguous object. Note that the unwrapping will yield meaningful results only for finite clusters. It will lead to undefined results for infinite clusters that are connected to themselves through a periodic cell boundary.

Coloring option

The modifier option Color particles by cluster gives each identified cluster a unique random color and colors the particles according to the clusters they belong to. It can be used to quickly visualize the results of the clustering algorithm.

Restriction to selected particles

The option Use only selected particles restricts the clustering algorithm to the set of currently selected particles. Unselected particles will be treated as if they do not exist and will be assigned the special cluster ID 0.

Exporting computation results

Total number of clusters

To export the total number of clusters found by the modifier to a text file (possibly as a function of time), use OVITO's standard file export function. Choose "Table of values" as output format and make sure that the ClusterAnalysis.cluster_count global attribute is selected for export.

Size of the largest clusters

The modifier also outputs the global attribute ClusterAnalysis.largest_size to report the number of particles in the largest cluster (only if the sort-by-size option is used). This information can be exported from OVITO in the same way as explained above.

Particle assignment to clusters

To export the list of particles belonging to each cluster to a text file, use OVITO's file export function. Choose the XYZ output file format and select the Particle Identifier and the Cluster properties for export. This will yield a text file containing each particle's cluster ID.

Cluster size list and centers of mass

The modifiers outputs the list of identified clusters as a data table named Clusters, which includes each cluster's size (number of particles) and center of mass (if calculation is enabled). You can view this table in the data inspector panel of OVITO by pressing the Show list of clusters button of the modifier. The data inspector panel provides functions for exporting the table to a text file.

Cluster size distribution

Since the cluster table generated by the modifier contains each cluster's size, you can subsequently apply OVITO's Histogram modifier to the Cluster Size column of that table to calculate the cluster size distribution.