Cluster analysis

This modifier groups particles into sets, referred to as clusters, based on the selected connectivity criterion. The criterion can be either distance-based (cutoff range) or topology-based (bond connectivity).

A cluster is defined as a set of connected particles, where each particle is within the (indirect) reach of the others in the same cluster. In other words, any two particles within a cluster are connected by a continuous path of steps that satisfy the selected connectivity criterion. Conversely, two particles belong to different clusters if no such continuous path exists between them on the neighbor graph.

../../../_images/cluster_analysis_example_input.png — Input

../../../_images/cluster_analysis_example_output.png — Output

Connectivity criterion

You can choose between two clustering modes:

Distance-based mode:: Two particles are considered connected if they are within a specified proximity range of each other.
Bond-based mode:: Two particles are considered connected if there is a bond between them.

Particles not connected to any other particle in the system will each form their own single-particle cluster.

Cluster by property

Optionally, you can select a particle property in the Cluster by field to restrict the formation of clusters further. In this case, two neighboring particles are only considered connected if they also have exactly the same value of the selected property. Consequently, all particles of a cluster share the same property value, and touching groups of particles with different values end up in separate clusters. You can use this option, for example, to decompose a system into separate clusters for each grain (Grain), structure type (Structure Type), etc.

Sorting of clusters

The clusters identified by the modifier are assigned numeric identifiers ranging from 0 to N-1, where N is the total number of clusters formed. The algorithm assigns each input particle to one of these clusters and outputs this information as a new integer particle property named Cluster. The cluster ID of a particle is the index of the corresponding particle in the cluster particle system generated by the modifier (see below), and OVITO keeps the two in sync: if clusters are deleted later on in the pipeline, the Cluster values of the particles are updated accordingly.

By default, the ordering of clusters is arbitrary and generally depends on the storage order of the input particles. However, you can enable the option Sort clusters by size to sort the cluster IDs in descending order of particle count. This ensures that the first cluster (ID 0) is the largest in the system, containing the most particles.

Note

Prior to OVITO 3.17, cluster IDs were 1-based and the special ID 0 was assigned to particles not belonging to any cluster. Cluster IDs are now 0-based, and particles not belonging to any cluster are assigned the ID -1.

Cluster particles

../../../_images/cluster_analysis_clusters_system.png — The identified clusters are represented as separate ellipsoidal particles, making it easy to independently visualize and analyze them.

The modifier outputs the identified clusters as a second, independent particle system named clusters, which contains one particle per cluster. Each cluster particle is located at the center of mass of the cluster and carries the cluster’s properties, e.g. Cluster Size (the number of particles in the cluster). Particle i of this system represents the cluster with ID i.

The cluster particles are rendered by a separate Particles visual element named Clusters, which is turned off by default. To show the clusters in the 3d scene, tick the checkbox next to the Clusters entry in the “Visual elements” section of the pipeline editor. You can then control the size and appearance of the cluster particles like for regular particles.

Since the clusters are regular particles, you can process them further with modifiers downstream in the pipeline. Modifiers such as Compute property, Expression selection or Color coding let you pick the Clusters particle system as input. Geometric modifiers such as Slice or Affine transformation act on all particle systems by default, including the cluster particles. Deleting a cluster particle sets the Cluster property of its member particles to -1. Use the data inspector to view the list of clusters by pressing the Show list of clusters button.

Calculation of centers of mass

The modifier computes the center of mass of each cluster, which is used as position of the corresponding cluster particle. Finite clusters that span across periodic cell boundaries are correctly handled using the minimum image convention when necessary.

However, if a cluster is infinite (reconnecting to itself through periodic cell boundaries), the computed center will have some arbitrary value, because the center of mass of an infinite cluster is not well-defined.

The algorithm calculates the center of mass using the particle masses as weights. Mass information is taken from the Mass property of individual particles if present or from the masses set at the level of particle types.

Note

If no per-particle masses have been specified, and if none of the particle types has a mass value, the algorithm assumes uniform weights for all particles in the calculation.

Calculation of gyration radius and gyration tensor

The modifier can optionally compute the radius of gyration of each cluster as well as its gyration tensor. Both quantities will be output as additional properties Radius of Gyration and Gyration Tensor of the cluster particles. The symmetric gyration tensor has six independent components: xx, yy, zz, xy, xz, yz (in simulation units of length squared).

Additionally, the modifier derives a gyration ellipsoid from the tensor of each cluster and assigns it to the cluster particle as Aspherical Shape and Orientation properties. The semi-axes of the ellipsoid are the square roots of three times the eigenvalues of the gyration tensor, which means an isotropic cluster is depicted as a sphere whose radius equals the cluster’s radius of gyration. Clusters consisting of a single particle are rendered as spheres using the default radius of the Clusters visual element.

The calculation of the radius of gyration and the gyration tensor in OVITO follows the compute gyration command of the LAMMPS simulation code. It takes into account the per-particle masses (if present) or the masses specified for the particle types.

Unwrapping of particle coordinates

The modifier includes an option to “unwrap” the coordinates of particles within the same cluster. This operation may map particles outside the primary image of the periodic simulation cell to ensure that each cluster appears as a contiguous object.

Important: Unwrapping is meaningful only for finite clusters. For infinite clusters —those that reconnect to themselves through periodic cell boundaries— the results will be undefined.

Coloring option

The Color particles by cluster option assigns a unique random color to each identified cluster. Particles are colored based on the cluster to which they belong. The cluster particles get the same colors as their member particles. This visualization feature provides a quick and intuitive way to see the results of the clustering algorithm.

To visualize other properties of the clusters, for example their sizes (particle counts), you can use the Color coding modifier. Either apply it to the Clusters particle system directly, or first copy the desired cluster property over to the individual particles using the Compute property modifier and the expression Cluster.ClusterSize, which looks up the Cluster Size property of the cluster particle referenced by each particle’s Cluster property.

Restriction to selected particles

The Use only selected particles option limits the clustering algorithm to the currently selected particles. Any unselected particles are treated as nonexistent and are assigned the special cluster ID -1. This option is useful for clustering only a subset of particles in the system.

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. Select the output format Table of Global Attributes and make sure that the ClusterAnalysis.cluster_count global attribute is selected for export.
Size of the largest cluster: 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 output file format XYZ and mark 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 list of identified clusters, including their sizes (number of particles), centers of mass and radii of gyration (if their calculation is enabled), is available as the Clusters particle system. You can open it in the data inspector panel of OVITO by pressing the button Show list of clusters. To export the cluster list to a text file, use OVITO’s file export function, choose a column-based output format such as XYZ, and select the Clusters particle system in the Data object box of the export settings dialog. Then mark the cluster properties to be exported, e.g. Cluster Size and Position.
Cluster size distribution: You can apply OVITO’s Histogram to the Cluster Size property of the Clusters particle system to calculate the cluster size distribution.
Legacy cluster table: OVITO 3.16 and earlier output the list of clusters as a data table named clusters. Activate the option Output cluster list as data table to let the modifier additionally generate this table, for example if your existing workflow exports it to a text file using the data inspector. The option is turned on automatically for modifiers loaded from session state files written by older program versions.