PLUMED-TUTORIALS by plumed-school

# Clustering

When studying nucleation it is often useful to use a clustering atoms to determine how many atoms are in the largest crystalline nucleus. The implementation of this approach in PLUMED is detailed in this paper. A typical input in that paper for calcluating the number of atoms in the largest cluster is shown below:

Click on the labels of the actions for more information on what each action computes

# Ccalculate the coordination numbers of the atoms
lq: COORDINATIONNUMBERCalculate the coordination numbers of atoms so that you can then calculate functions of the distribution of This action is a shortcut. More details
 SPECIESthis keyword is used for colvars such as coordination number
=1-100 SWITCHthe switching function that it used in the construction of the contact matrix={CUBIC D_0=0.45 D_MAX=0.55}
# PLUMED interprets the command:
# lq: COORDINATIONNUMBER SPECIES=1-100 SWITCH={CUBIC D_0=0.45 D_MAX=0.55}
# as follows (Click the red comment above to revert to the short version of the input):
The COORDINATIONNUMBER action with label lq calculates the following quantities: Quantity    Type    Description  
lq vector the vector that is obtained by taking the product between the matrix and the vector that were inputlq_grp: GROUPDefine a group of atoms so that a particular list of atoms can be referenced with a single label in definitions of CVs or virtual atoms. More details
 ATOMSthe numerical indexes for the set of atoms in the group=1-100
The GROUP action with label lq_grp calculates the following quantities: Quantity    Type    Description  
lq_grp atoms indices of atoms specified in GROUPlq_mat: CONTACT_MATRIXAdjacency matrix in which two atoms are adjacent if they are within a certain cutoff. More details
 GROUPspecifies the list of atoms that should be assumed indistinguishable
=1-100 SWITCHspecify the switching function to use between two sets of indistinguishable atoms={CUBIC D_0=0.45 D_MAX=0.55}
The CONTACT_MATRIX action with label lq_mat calculates the following quantities: Quantity    Type    Description  
lq_mat matrix a matrix containing the weights for the bonds between each pair of atomslq_ones: ONESCreate a constant vector with all elements equal to one More details
 SIZEthe number of ones that you would like to create=100
The ONES action with label lq_ones calculates the following quantities: Quantity    Type    Description  
lq_ones vector the constant value that was read from the plumed inputlq: MATRIX_VECTOR_PRODUCTCalculate the product of the matrix and the vector More details
  ARGthe input for this action is the scalar output from one or more other actions
=lq_mat,lq_ones
lq_caverage: MEANCalculate the arithmetic mean of the elements in a vector More details
 ARGthe input to this function
=lq PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
# --- End of included input --- # Calculate the contact matrix for the atoms for which we calculated the coordinaion numbers
The MEAN action with label lq_caverage calculates the following quantities: Quantity    Type    Description  
lq_caverage scalar the mean of all the elements in the input vectorcm: CONTACT_MATRIXAdjacency matrix in which two atoms are adjacent if they are within a certain cutoff. More details
 GROUPspecifies the list of atoms that should be assumed indistinguishable
=lq SWITCHspecify the switching function to use between two sets of indistinguishable atoms={CUBIC D_0=0.45 D_MAX=0.55}
# Do a clustering using the contact matrix above
The CONTACT_MATRIX action with label cm calculates the following quantities: Quantity    Type    Description  
cm matrix a matrix containing the weights for the bonds between each pair of atomsdfs: DFSCLUSTERINGFind the connected components of the matrix using the depth first search clustering algorithm. More details
 MATRIXthe input matrix (can use ARG instead)
=cm
# Sum the coordination numbers for the atoms in the largest cluster
The DFSCLUSTERING action with label dfs calculates the following quantities: Quantity    Type    Description  
dfs vector vector with length that is equal to the number of rows in the input matrix.  Elements of this vector are equal to the cluster that each node is a part ofclust1: CLUSTER_PROPERTIESCalculate properties of the distribution of some quantities that are part of a connected component This action is a shortcut. More details
 CLUSTERSthe label of the action that does the clustering
=dfs ARGcalculate the sum of the arguments calculated by this action for the cluster
=lq CLUSTER which cluster would you like to look at 1 is the largest cluster, 2 is the second largest, 3 is the the third largest and so on
=1 SUM calculate the sum of all the quantities
# PLUMED interprets the command:
# clust1: CLUSTER_PROPERTIES CLUSTERS=dfs ARG=lq CLUSTER=1 SUM
# as follows (Click the red comment above to revert to the short version of the input):
The CLUSTER_PROPERTIES action with label clust1 calculates the following quantities: Quantity    Type    Description  
clust1 vector vector with elements that are one if the atom of interest is part of the required cluster and zero otherwiseclust1: CLUSTER_WEIGHTSSetup a vector that has one for all the atoms that form part of the cluster of interest and that has zero for all other atoms. More details
  CLUSTERSthe label of the action that does the clustering
=dfs CLUSTER which cluster would you like to look at 1 is the largest cluster, 2 is the second largest, 3 is the the third largest and so on=1
clust1_wsum: CUSTOMCalculate a combination of variables using a custom expression. More details
 ARGthe input to this function
=clust1,lq FUNCthe function you wish to evaluate
=x*y PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
The CUSTOM action with label clust1_wsum calculates the following quantities: Quantity    Type    Description  
clust1_wsum vector the vector obtained by doing an element-wise application of an arbitrary function to the input vectorsclust1_sum: SUMCalculate the sum of the arguments More details
 ARGthe input to this function
=clust1_wsum PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
# --- End of included input --- The SUM action with label clust1_sum calculates the following quantities: Quantity    Type    Description  
clust1_sum scalar the sum of all the elements in the input vector

This input is fine but it is also somewhat unweildy and a little confusing. The problem is that you have to calculate the coordination numbers of all the atoms in order to do the clustering and (unless you have a deep understanding of the way the code is implemented) it is not clear why. With the new sytax you can achieve the same result as follows:

Click on the labels of the actions for more information on what each action computes

# Calculate the contact matrix.  This action computes a 100x100 matrix
cm: CONTACT_MATRIXAdjacency matrix in which two atoms are adjacent if they are within a certain cutoff. More details
 GROUPspecifies the list of atoms that should be assumed indistinguishable
=1-100 SWITCHspecify the switching function to use between two sets of indistinguishable atoms={CUBIC D_0=0.45 D_MAX=0.55}
# Do a clustering using the contact matrix that was computed above as input
# This action returns a 100 dimensional vector. If element i of this matrix
# is equal to 5 this means that atom i in the input to the contact matrix above
# is part of the 5th largest cluster.  
The CONTACT_MATRIX action with label cm calculates the following quantities: Quantity    Type    Description  
cm matrix a matrix containing the weights for the bonds between each pair of atomsdfs: DFSCLUSTERINGFind the connected components of the matrix using the depth first search clustering algorithm. More details
 ARGthe input for this action is the scalar output from one or more other actions
=cm
# This next action returns a vector with 100 elements. If element i is equal to 1 then atom 
# i is part of the largest cluster.  If it is equal to zero then it is part of some 
# other cluster.
The DFSCLUSTERING action with label dfs calculates the following quantities: Quantity    Type    Description  
dfs vector vector with length that is equal to the number of rows in the input matrix.  Elements of this vector are equal to the cluster that each node is a part ofc1: CLUSTER_WEIGHTSSetup a vector that has one for all the atoms that form part of the cluster of interest and that has zero for all other atoms. More details
 CLUSTERSthe label of the action that does the clustering
=dfs CLUSTER which cluster would you like to look at 1 is the largest cluster, 2 is the second largest, 3 is the the third largest and so on=1
# Now calculate the coordination numbers using the usual matrix multiplication trick
The CLUSTER_WEIGHTS action with label c1 calculates the following quantities: Quantity    Type    Description  
c1 vector vector with elements that are one if the atom of interest is part of the required cluster and zero otherwiseones: ONESCreate a constant vector with all elements equal to one This action is a shortcut. More details
 SIZEthe number of ones that you would like to create=100
# PLUMED interprets the command:
# ones: ONES SIZE=100
# as follows (Click the red comment above to revert to the short version of the input):
The ONES action with label ones calculates the following quantities: Quantity    Type    Description  
ones vector the constant value that was read from the plumed inputones: CONSTANTCreate a constant value that can be passed to actions More details
 NOLOG do not report all the read in scalars in the log
 VALUESthe numbers that are in your constant value=1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1
# --- End of included input --- coords: MATRIX_VECTOR_PRODUCTCalculate the product of the matrix and the vector More details
 ARGthe input for this action is the scalar output from one or more other actions
=cm,ones
# Multiply the coordination numbers by c1.  We now have a vector where element i is equal to the 
# coordiation number of atom i if atom i is part of the largest cluster and zero otherwise.
The MATRIX_VECTOR_PRODUCT action with label coords calculates the following quantities: Quantity    Type    Description  
coords vector the vector that is obtained by taking the product between the matrix and the vector that were inputfcoords: CUSTOMCalculate a combination of variables using a custom expression. More details
 ARGthe input to this function
=coords,c1 FUNCthe function you wish to evaluate
=x*y PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
# And lastly sum the coordination numbers of the atoms in the largest cluster
The CUSTOM action with label fcoords calculates the following quantities: Quantity    Type    Description  
fcoords vector the vector obtained by doing an element-wise application of an arbitrary function to the input vectorscoordsum: SUMCalculate the sum of the arguments More details
 ARGthe input to this function
=fcoords PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
The SUM action with label coordsum calculates the following quantities: Quantity    Type    Description  
coordsum scalar the sum of all the elements in the input vector

This new syntax is much more clear as the clustering operation is performed on the CONTACT_MATRIX directly. The vector returned by the DFSCLUSTERING object then tells you which cluster each atom belongs to. You can thus use simple logical operations on this vector to determine the properties for all your clusters. Furthermore, you don’t even need to use the coordination numbers. If you simply want to calculate the number of atoms in the largest cluster you can use the following input:

Click on the labels of the actions for more information on what each action computes

# Calculate the contact matrix.  This action computes a 100x100 matrix
cm: CONTACT_MATRIXAdjacency matrix in which two atoms are adjacent if they are within a certain cutoff. More details
 GROUPspecifies the list of atoms that should be assumed indistinguishable
=1-100 SWITCHspecify the switching function to use between two sets of indistinguishable atoms={CUBIC D_0=0.45 D_MAX=0.55}
# Do the clustering
The CONTACT_MATRIX action with label cm calculates the following quantities: Quantity    Type    Description  
cm matrix a matrix containing the weights for the bonds between each pair of atomsdfs: DFSCLUSTERINGFind the connected components of the matrix using the depth first search clustering algorithm. More details
 ARGthe input for this action is the scalar output from one or more other actions
=cm
# Get a 100 element vector that has ones for those atoms that are part of the largest cluster
The DFSCLUSTERING action with label dfs calculates the following quantities: Quantity    Type    Description  
dfs vector vector with length that is equal to the number of rows in the input matrix.  Elements of this vector are equal to the cluster that each node is a part ofc1: CLUSTER_WEIGHTSSetup a vector that has one for all the atoms that form part of the cluster of interest and that has zero for all other atoms. More details
 CLUSTERSthe label of the action that does the clustering
=dfs CLUSTER which cluster would you like to look at 1 is the largest cluster, 2 is the second largest, 3 is the the third largest and so on=1   
# Sum the vector above to get the number of atoms in the largest cluster
The CLUSTER_WEIGHTS action with label c1 calculates the following quantities: Quantity    Type    Description  
c1 vector vector with elements that are one if the atom of interest is part of the required cluster and zero otherwisesuml: SUMCalculate the sum of the arguments More details
 ARGthe input to this function
=c1 PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
The SUM action with label suml calculates the following quantities: Quantity    Type    Description  
suml scalar the sum of all the elements in the input vector

Quantity	Type	Description
lq	vector	the vector that is obtained by taking the product between the matrix and the vector that were input

PLUMED-TUTORIALS

A living textbook for and by the PLUMED consortium