Syntax:
diag_style cluster keyword value keyword value ...
filename value = name
name = name of file to write clustering results to
dump value = style filename
style = standard or opendx
filename = file to write viz data to
site/size
write cluster size to application-specific site dvalue
Examples:
diag_style cluster diag_style cluster stats no delt 1.0 filename cluster.a.0.1.dat dump opendx cluster.a.0.1.dump diag_style cluster delt 1.0 stats no logfreq 9 10.0 filename cluster.dat dump standard dump.cluster site/size
Description:
The cluster diagnostic computes a clustering analysis on all lattice sites in the system, identifying geometric groupings of identical spin values, e.g. a grain in a grain growth model. The total number of clusters is printed as stats output via the stats command.
Clustering uses a connectivity definition provided by the application (e.g. sites are adjacent and have same spin value) to identify the set of connected clusters.
Clustering can only be used with the lattice application, and applications based on it.
The filename keyword allows an output file to be specified. Every time the cluster analysis is performed, the key properties of each cluster are appended to this file. The output format is:
cluster_id is an arbitrary integer assigned uniquely to each cluster. It will be different for different numbers of processors.
ivalue is an application-specific integer associated with each cluster. For lattice applications, it is the spin value of all sites in the cluster. dvalue is an application-specific double associated with each cluster. For most lattice applications it is zero. size is the numbers of sites in the cluster.
Cx, cy, cz are the coordinates of the centroid of the cluster i.e. the average of the x, y, and z coordinate of all the sites in the cluster. For clusters than are of finite extent in a periodic dimension, the average is over the contiguous sites in a single periodic image, and the centroid is shifted by multiples of the period so as to lie inside the box. For clusters of infinite extent in x, y, or z, the centroid is not defined, so the clustering algorithm will produce a result based on some arbitrary splitting of the cluster into finite periodic repeat units. Except for this last case, the calculated cx, cy, or cz will be not be affected by the numbers of processors used in the calculation.
Xlo, xhi, ylo, yhi, zlo, and zhi are the maximum and minimum x, y, and z coordinates of sites in cluster, in other words the extent of the bounding box of the cluster. For clusters that are of finite extent in a periodic dimension, the max and min are taken over the contiguous sites in a single periodic image, and each of the 6 output values are then shifted by multiples of the period so as to lie inside the box. For clusters of infinite extent in x, y, or z, the max and min values in those directions are not defined. The clustering algorithm will produce a result based on some arbitrary splitting of the cluster into finite periodic repeat units. Except for this last case, the max and min values will be not be affected by the numbers of processors used in the calculation.
The dump keyword causes the cluster ID for each site to be printed out in snapshot format which can be used for visualization purposes. The cluster IDs are arbitrary integers such that two sites have the same ID if and only if they belong to the same cluster. The standard setting generates LAMMPS-style. For cluster2d and cluster3d styles only two values are printed for each site: site index and cluster ID. For the cluster style, five additional values are printed: the x, y, and z coordinate of the site (for 2d lattices, z=0), the ivalue of the cluster, and the cluster size. These files can be visualized with various tools in the LAMMPS package and the Pizza.py package.
The opendx keyword generates a set of files that can be read by the OpenDX script called aniso0.net to visualize the clusters in 3D. The filenames are composed of the input filename, followed by a sequential number, followed by '.dx'. Because the OpenDX format assumes a particular ordering of the sites, the opendx style can only be used with square and simple cubic lattices.
The site/size option will write the cluster size to an application-specific dvalue for each site. This can only be allowed if the application has designated a dvalue storage location for each site to hold the cluster size; the application must set the integer value clustersizecol = 'which dvalue' in the constructor to let diag_cluster know which dvalue should be used.
Restrictions:
This diagnostic can only be used for on-lattice applications.
Applications need to provide push_connected_neighbors() and connected_ghosts() functions which are called by this diagnostic. If they are not defined, SPPARKS will print an error message.
Related commands:
Default: none