Action: DISSIMILARITIES

Module	matrixtools
Description	Usage
Calculate the matrix of dissimilarities between a trajectory of atomic configurations.
output value	type
the dissimilarity matrix	matrix

Details and examples

Calculate the matrix of dissimilarities between a trajectory of atomic configurations.

This action allows you to calculate a dissimilarity matrix, which is a square matrix tht describes the pairwise distinction between a set of objects. This action is routinely used in dimensionality reduction calculations. The example shown below shows how we might get a matrix of dissimilarities upon which we can run a dimensionality reduction calculation.

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

d1The DISTANCE action with label d1 calculates the following quantities: Quantity    Type    Description  
d1 scalar the DISTANCE between this pair of atoms: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=1,2
d2The DISTANCE action with label d2 calculates the following quantities: Quantity    Type    Description  
d2 scalar the DISTANCE between this pair of atoms: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=3,4
# Collect the values of the two distances and store them for later analysis
ffThe COLLECT_FRAMES action with label ff calculates the following quantities: Quantity    Type    Description  
ff_data matrix the data that is being collected by this action
ff_logweights vector the logarithms of the weights of the data points: COLLECT_FRAMESCollect atomic positions or argument values from the trajectory for later analysis This action is a shortcut and it has hidden defaults. More details ARGthe labels of the values whose time series you would like to collect for later analysis=d1,d2 STRIDE the frequency with which data should be stored for analysis=1
The COLLECT_FRAMES action with label ff calculates the following quantities: Quantity    Description  
ff.data the data that is being collected by this action
ff.logweights the logarithms of the weights of the data pointsff: COLLECT_FRAMESCollect atomic positions or argument values from the trajectory for later analysis This action is a shortcut and uses the defaults shown here. More details ARGthe labels of the values whose time series you would like to collect for later analysis=d1,d2 STRIDE the frequency with which data should be stored for analysis=1  CLEAR the frequency with which data should all be deleted and restarted=0
# PLUMED interprets the command:
# ff: COLLECT_FRAMES ARG=d1,d2 STRIDE=1
# as follows (Click the red comment above to revert to the short version of the input):
ff_d1The COLLECT action with label ff_d1 calculates the following quantities: Quantity    Type    Description  
ff_d1 vector the time series for the input quantity: COLLECTCollect data from the trajectory for later analysis More details ARGthe label of the value whose time series is being stored for later analysis=d1 STRIDE the frequency with which the data should be collected and added to the quantity being averaged=1 CLEAR the frequency with which to clear all the accumulated data=0
ff_d2The COLLECT action with label ff_d2 calculates the following quantities: Quantity    Type    Description  
ff_d2 vector the time series for the input quantity: COLLECTCollect data from the trajectory for later analysis More details ARGthe label of the value whose time series is being stored for later analysis=d2 STRIDE the frequency with which the data should be collected and added to the quantity being averaged=1 CLEAR the frequency with which to clear all the accumulated data=0
ff_dataThe VSTACK action with label ff_data calculates the following quantities: Quantity    Type    Description  
ff_data matrix a matrix that contains the input vectors in its columns: VSTACKCreate a matrix by stacking vectors together More details ARGthe values that you would like to stack together to construct the output matrix=ff_d1,ff_d2
ff_cweightThe CONSTANT action with label ff_cweight calculates the following quantities: Quantity    Type    Description  
ff_cweight scalar the constant value that was read from the plumed input: CONSTANTCreate a constant value that can be passed to actions More details VALUEthe single number that you would like to store=0
ff_logweightsThe COLLECT action with label ff_logweights calculates the following quantities: Quantity    Type    Description  
ff_logweights vector the time series for the input quantity: COLLECTCollect data from the trajectory for later analysis More details ARGthe label of the value whose time series is being stored for later analysis=ff_cweight STRIDE the frequency with which the data should be collected and added to the quantity being averaged=1 CLEAR the frequency with which to clear all the accumulated data=0
ff_oneThe CONSTANT action with label ff_one calculates the following quantities: Quantity    Type    Description  
ff_one scalar the constant value that was read from the plumed input: CONSTANTCreate a constant value that can be passed to actions More details VALUEthe single number that you would like to store=1
ff_onesThe COLLECT action with label ff_ones calculates the following quantities: Quantity    Type    Description  
ff_ones vector the time series for the input quantity: COLLECTCollect data from the trajectory for later analysis More details ARGthe label of the value whose time series is being stored for later analysis=ff_one STRIDE the frequency with which the data should be collected and added to the quantity being averaged=1 CLEAR the frequency with which to clear all the accumulated data=0
# --- End of included input --- # Transpose the matrix that is collected above
ff_dataTThe TRANSPOSE action with label ff_dataT calculates the following quantities: Quantity    Type    Description  
ff_dataT matrix the transpose of the input matrix: TRANSPOSECalculate the transpose of a matrix More details ARGthe label of the vector or matrix that should be transposed=ff_data
# Now compute all the dissimilarities between the collected frames
ss1The DISSIMILARITIES action with label ss1 calculates the following quantities: Quantity    Type    Description  
ss1 matrix the dissimilarity matrix: DISSIMILARITIESCalculate the matrix of dissimilarities between a trajectory of atomic configurations. More details ARGthe label of the two matrices from which the product is calculated=ff_data,ff_dataT
DUMPVECTORPrint a vector to a file More details ARGthe labels of vectors/matrices that should be output in the file=ss1 FILE the file on which to write the vetors=mymatrix.dat

Some dimensionality reduction algorithms take the squares of the dissimilarities rather than the dissimilarities. To calculate these quantities using PLUMED you use the SQUARED keyword as shown below:

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

d1The DISTANCE action with label d1 calculates the following quantities: Quantity    Type    Description  
d1 scalar the DISTANCE between this pair of atoms: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=1,2
d2The DISTANCE action with label d2 calculates the following quantities: Quantity    Type    Description  
d2 scalar the DISTANCE between this pair of atoms: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=3,4
# Collect the values of the two distances and store them for later analysis
ffThe COLLECT_FRAMES action with label ff calculates the following quantities: Quantity    Type    Description  
ff_data matrix the data that is being collected by this action
ff_logweights vector the logarithms of the weights of the data points: COLLECT_FRAMESCollect atomic positions or argument values from the trajectory for later analysis This action is a shortcut and it has hidden defaults. More details ARGthe labels of the values whose time series you would like to collect for later analysis=d1,d2 STRIDE the frequency with which data should be stored for analysis=1
The COLLECT_FRAMES action with label ff calculates the following quantities: Quantity    Description  
ff.data the data that is being collected by this action
ff.logweights the logarithms of the weights of the data pointsff: COLLECT_FRAMESCollect atomic positions or argument values from the trajectory for later analysis This action is a shortcut and uses the defaults shown here. More details ARGthe labels of the values whose time series you would like to collect for later analysis=d1,d2 STRIDE the frequency with which data should be stored for analysis=1  CLEAR the frequency with which data should all be deleted and restarted=0
# PLUMED interprets the command:
# ff: COLLECT_FRAMES ARG=d1,d2 STRIDE=1
# as follows (Click the red comment above to revert to the short version of the input):
ff_d1The COLLECT action with label ff_d1 calculates the following quantities: Quantity    Type    Description  
ff_d1 vector the time series for the input quantity: COLLECTCollect data from the trajectory for later analysis More details ARGthe label of the value whose time series is being stored for later analysis=d1 STRIDE the frequency with which the data should be collected and added to the quantity being averaged=1 CLEAR the frequency with which to clear all the accumulated data=0
ff_d2The COLLECT action with label ff_d2 calculates the following quantities: Quantity    Type    Description  
ff_d2 vector the time series for the input quantity: COLLECTCollect data from the trajectory for later analysis More details ARGthe label of the value whose time series is being stored for later analysis=d2 STRIDE the frequency with which the data should be collected and added to the quantity being averaged=1 CLEAR the frequency with which to clear all the accumulated data=0
ff_dataThe VSTACK action with label ff_data calculates the following quantities: Quantity    Type    Description  
ff_data matrix a matrix that contains the input vectors in its columns: VSTACKCreate a matrix by stacking vectors together More details ARGthe values that you would like to stack together to construct the output matrix=ff_d1,ff_d2
ff_cweightThe CONSTANT action with label ff_cweight calculates the following quantities: Quantity    Type    Description  
ff_cweight scalar the constant value that was read from the plumed input: CONSTANTCreate a constant value that can be passed to actions More details VALUEthe single number that you would like to store=0
ff_logweightsThe COLLECT action with label ff_logweights calculates the following quantities: Quantity    Type    Description  
ff_logweights vector the time series for the input quantity: COLLECTCollect data from the trajectory for later analysis More details ARGthe label of the value whose time series is being stored for later analysis=ff_cweight STRIDE the frequency with which the data should be collected and added to the quantity being averaged=1 CLEAR the frequency with which to clear all the accumulated data=0
ff_oneThe CONSTANT action with label ff_one calculates the following quantities: Quantity    Type    Description  
ff_one scalar the constant value that was read from the plumed input: CONSTANTCreate a constant value that can be passed to actions More details VALUEthe single number that you would like to store=1
ff_onesThe COLLECT action with label ff_ones calculates the following quantities: Quantity    Type    Description  
ff_ones vector the time series for the input quantity: COLLECTCollect data from the trajectory for later analysis More details ARGthe label of the value whose time series is being stored for later analysis=ff_one STRIDE the frequency with which the data should be collected and added to the quantity being averaged=1 CLEAR the frequency with which to clear all the accumulated data=0
# --- End of included input --- # Transpose the matrix that is collected above
ff_dataTThe TRANSPOSE action with label ff_dataT calculates the following quantities: Quantity    Type    Description  
ff_dataT matrix the transpose of the input matrix: TRANSPOSECalculate the transpose of a matrix More details ARGthe label of the vector or matrix that should be transposed=ff_data
# Now compute all the dissimilarities between the collected frames
ss1The DISSIMILARITIES action with label ss1 calculates the following quantities: Quantity    Type    Description  
ss1 matrix the dissimilarity matrix: DISSIMILARITIESCalculate the matrix of dissimilarities between a trajectory of atomic configurations. More details ARGthe label of the two matrices from which the product is calculated=ff_data,ff_dataT SQUARED calculate the squares of the dissimilarities (this option cannot be used with MATRIX_PRODUCT)
DUMPVECTORPrint a vector to a file More details ARGthe labels of vectors/matrices that should be output in the file=ss1 FILE the file on which to write the vetors=mymatrix.dat

The MASK keyword

The MASK keyword for DISSIMILARITIES works in the same way that it does for MATRIX_PRODUCT. This keyword thus expects a matrix in input and will only evaluate elements the elements of the dissimilarity matrix whose corresponding elements in the matrix that was input to MASK are non-zero. The following input shows an example of how this might be used in an example input that has not been used in any production calculation.

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

# Calculate and store three vectors connecting three pairs of atoms
d1The DISTANCE action with label d1 calculates the following quantities: Quantity    Type    Description  
d1.x vector the x-component of the vector connecting the two atoms
d1.y vector the y-component of the vector connecting the two atoms
d1.z vector the z-component of the vector connecting the two atoms: DISTANCECalculate the distance/s between pairs of atoms. More details COMPONENTS calculate the x, y and z components of the distance separately and store them as label ATOMS1the pair of atom that we are calculating the distance between=1,2 ATOMS2the pair of atom that we are calculating the distance between=3,4 ATOMS3the pair of atom that we are calculating the distance between=5,6
ff1The VSTACK action with label ff1 calculates the following quantities: Quantity    Type    Description  
ff1 matrix a matrix that contains the input vectors in its columns: VSTACKCreate a matrix by stacking vectors together More details ARGthe values that you would like to stack together to construct the output matrix=d1.x,d1.y,d1.z
# Calculate the magnitude of the vector and transform this magnitude using a
# switching function
d1mThe CUSTOM action with label d1m calculates the following quantities: Quantity    Type    Description  
d1m 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=d1.x,d1.y,d1.z FUNCthe function you wish to evaluate=sqrt(x*x+y*y+z*z) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
sw1The LESS_THAN action with label sw1 calculates the following quantities: Quantity    Type    Description  
sw1 vector the vector obtained by doing an element-wise application of a function that is one if the input is less than a threshold to the input vectors: LESS_THANUse a switching function to determine how many of the input variables are less than a certain cutoff. More details ARGthe values input to this function=d1m SWITCHThis keyword is used if you want to employ an alternative to the continuous swiching function defined above={RATIONAL R_0=0.2 D_MAX=0.5}
# Now perform the same operations for a different set of three atoms
d2The DISTANCE action with label d2 calculates the following quantities: Quantity    Type    Description  
d2.x vector the x-component of the vector connecting the two atoms
d2.y vector the y-component of the vector connecting the two atoms
d2.z vector the z-component of the vector connecting the two atoms: DISTANCECalculate the distance/s between pairs of atoms. More details COMPONENTS calculate the x, y and z components of the distance separately and store them as label ATOMS1the pair of atom that we are calculating the distance between=7,8 ATOMS2the pair of atom that we are calculating the distance between=9,10 ATOMS3the pair of atom that we are calculating the distance between=11,12
ff2The VSTACK action with label ff2 calculates the following quantities: Quantity    Type    Description  
ff2 matrix a matrix that contains the input vectors in its columns: VSTACKCreate a matrix by stacking vectors together More details ARGthe values that you would like to stack together to construct the output matrix=d2.x,d2.y,d2.z
ff2TThe TRANSPOSE action with label ff2T calculates the following quantities: Quantity    Type    Description  
ff2T matrix the transpose of the input matrix: TRANSPOSECalculate the transpose of a matrix More details ARGthe label of the vector or matrix that should be transposed=ff2
d2mThe CUSTOM action with label d2m calculates the following quantities: Quantity    Type    Description  
d2m 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=d2.x,d2.y,d2.z FUNCthe function you wish to evaluate=sqrt(x*x+y*y+z*z) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
sw2The LESS_THAN action with label sw2 calculates the following quantities: Quantity    Type    Description  
sw2 vector the vector obtained by doing an element-wise application of a function that is one if the input is less than a threshold to the input vectors: LESS_THANUse a switching function to determine how many of the input variables are less than a certain cutoff. More details ARGthe values input to this function=d2m SWITCHThis keyword is used if you want to employ an alternative to the continuous swiching function defined above={RATIONAL R_0=0.2 D_MAX=0.5}
# Use OUTER_PRODUCT to work out which pairs of atoms are less than a certain cutoff
swmatThe OUTER_PRODUCT action with label swmat calculates the following quantities: Quantity    Type    Description  
swmat matrix a matrix containing the outer product of the two input vectors that was obtained using the function that was input: OUTER_PRODUCTCalculate the outer product matrix of two vectors This action has hidden defaults. More details ARGthe labels of the two vectors from which the outer product is being computed=sw1,sw2
swmat: OUTER_PRODUCTCalculate the outer product matrix of two vectors This action uses the defaults shown here. More details ARGthe labels of the two vectors from which the outer product is being computed=sw1,sw2  FUNC the function of the input vectors that should be put in the elements of the outer product=x*y
# Now calculate the dissimilarities between the two sets of vectors for those pairs of atoms that are within a certain cutoff
dThe DISSIMILARITIES action with label d calculates the following quantities: Quantity    Type    Description  
d matrix the dissimilarity matrix: DISSIMILARITIESCalculate the matrix of dissimilarities between a trajectory of atomic configurations. More details ARGthe label of the two matrices from which the product is calculated=ff1,ff2T MASKa matrix that is used to used to determine which elements of the output matrix to compute=swmat
matThe CUSTOM action with label mat calculates the following quantities: Quantity    Type    Description  
mat matrix the matrix obtained by doing an element-wise application of an arbitrary function to the input matrix: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=swmat,d 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 compute the average dissimilarity
numerThe SUM action with label numer calculates the following quantities: Quantity    Type    Description  
numer 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=mat PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
denomThe SUM action with label denom calculates the following quantities: Quantity    Type    Description  
denom 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=swmat PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
vThe CUSTOM action with label v calculates the following quantities: Quantity    Type    Description  
v scalar an arbitrary function: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=numer,denom 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
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=v FILEthe name of the file on which to output these quantities=colvar

We have not provided a more relevant example because we haven't really used this functionality for anything. If you have a better example for a way of using this functionality please get in touch so we can update this part of the manual with your example.

Input

The arguments that serve as the input for this action are specified using one or more of the keywords in the following table.

Keyword	Type	Description
MASK	matrix	a matrix that is used to used to determine which elements of the output matrix to compute
ARG	matrix	the label of the two matrices from which the product is calculated

Full list of keywords

The following table describes the keywords and options that can be used with this action

Keyword	Type	Default	Description
MASK	input	none	a matrix that is used to used to determine which elements of the output matrix to compute
ARG	input	none	the label of the two matrices from which the product is calculated
SQUARED	optional	false	calculate the squares of the dissimilarities (this option cannot be used with MATRIX_PRODUCT)
SERIAL	optional	false	do the calculation in serial. Further information about this flag can be found here.
USEGPU	optional	false	run this calculation on the GPU. Further information about this flag can be found here.

Quantity	Type	Description
d1	scalar	the DISTANCE between this pair of atoms

Quantity	Description
ff.data	the data that is being collected by this action
ff.logweights	the logarithms of the weights of the data points