PLUMED-TUTORIALS by plumed-tutorials

# 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 More details SPECIESthe list of atoms for which the symmetry function is being calculated and the atoms that can be in the environments=1-100 SWITCHthe switching function that it used in the construction of the contact matrix. Options for this keyword are explained in the documentation for LESS_THAN.={CUBIC D_0=0.45 D_MAX=0.55}
# Calculate the contact matrix for the atoms for which we calculated the coordinaion numbers
The COORDINATIONNUMBER action with label lq calculates the following quantities: Quantity    Description  
lq.value the coordination numbers of the specified atomscm: 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 SWITCHthe input for the switching function that acts upon the distance between each pair of atoms. Options for this keyword are explained in the documentation for LESS_THAN.={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    Description  
cm.value 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 MATRIXYou should use ARG instead of this keyword which was used in older versions of PLUMED and is provided for back compatibility only=cm
# Sum the coordination numbers for the atoms in the largest cluster
The DFSCLUSTERING action with label dfs calculates the following quantities: Quantity    Description  
dfs.value vector with length that is equal to the number of rows in the input matrixclust1: CLUSTER_PROPERTIESCalculate properties of the distribution of some quantities that are part of a connected component 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
The CLUSTER_PROPERTIES action with label clust1 calculates the following quantities: Quantity    Description  
clust1.value a vector that is one if the atom is part of the cluster or interest and zero otherwise
clust1.sum the sum of the colvars

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
cmThe 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 atoms: 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 SWITCHthe input for the switching function that acts upon the distance between each pair of atoms. Options for this keyword are explained in the documentation for LESS_THAN.={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.  
dfsThe 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 of: DFSCLUSTERINGFind the connected components of the matrix using the depth first search clustering algorithm. More details ARGthe input matrix=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.
c1The 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 otherwise: 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
onesThe ONES action with label ones calculates the following quantities: Quantity    Type    Description  
ones vector a vector of ones with the required number of elements: 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):
onesThe CONSTANT action with label ones calculates the following quantities: Quantity    Type    Description  
ones vector the constant value that was read from the plumed input: 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 --- coordsThe 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 input: MATRIX_VECTOR_PRODUCTCalculate the product of the matrix and the vector More details ARGthe label for the matrix and the vector/scalar that are being multiplied=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.
fcoordsThe 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 vectors: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values 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
coordsumThe SUM action with label coordsum calculates the following quantities: Quantity    Type    Description  
coordsum scalar the SUM of the elements in the input value: SUMCalculate the sum of the arguments More details ARGthe vector/matrix/grid whose elements shuld be added together=fcoords PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO

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
cmThe 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 atoms: 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 SWITCHthe input for the switching function that acts upon the distance between each pair of atoms. Options for this keyword are explained in the documentation for LESS_THAN.={CUBIC D_0=0.45 D_MAX=0.55}
# Do the clustering
dfsThe 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 of: DFSCLUSTERINGFind the connected components of the matrix using the depth first search clustering algorithm. More details ARGthe input matrix=cm
# Get a 100 element vector that has ones for those atoms that are part of the largest cluster
c1The 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 otherwise: 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
sumlThe SUM action with label suml calculates the following quantities: Quantity    Type    Description  
suml scalar the SUM of the elements in the input value: SUMCalculate the sum of the arguments More details ARGthe vector/matrix/grid whose elements shuld be added together=c1 PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO

Quantity	Description
lq.value	the coordination numbers of the specified atoms

Quantity	Description
cm.value	a matrix containing the weights for the bonds between each pair of atoms

Quantity	Description
dfs.value	vector with length that is equal to the number of rows in the input matrix

Quantity	Description
clust1.value	a vector that is one if the atom is part of the cluster or interest and zero otherwise
clust1.sum	the sum of the colvars

Quantity	Type	Description
cm	matrix	a matrix containing the weights for the bonds between each pair of atoms

PLUMED-TUTORIALS

A collaborative, community-driven learning ecosystem