Action: MATRIX_PRODUCT

Module	matrixtools
Description	Usage
Calculate the product of two matrices
output value	type
the product of the two input matrices	matrix

Details and examples

Calculate the product of two matrices

This action allows you to multiply two matrices. The following input shows an example where two contact matrices are multiplied together.

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

c1The CONTACT_MATRIX action with label c1 calculates the following quantities: Quantity    Type    Description  
c1 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.={RATIONAL R_0=0.1}
c2The CONTACT_MATRIX action with label c2 calculates the following quantities: Quantity    Type    Description  
c2 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.={RATIONAL R_0=0.2}
mThe MATRIX_PRODUCT action with label m calculates the following quantities: Quantity    Type    Description  
m matrix the product of the two input matrices: MATRIX_PRODUCTCalculate the product of two matrices More details ARGthe label of the two matrices from which the product is calculated=c1,c2
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=m FILEthe name of the file on which to output these quantities=colvar

The functionality in this action is useful for claculating the relative orientations of large numbers of molecules. For example in his input the DISTANCE command is used to calculate the orientation of a collection of molecules. We then can then use the VSTACK, TRANSPOSE and the MATRIX_PRODUCT commands to calculate the dot products between all these vectors

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

# Calculate the vectors connecting these three pairs of atoms
dThe DISTANCE action with label d calculates the following quantities: Quantity    Type    Description  
d.x vector the x-component of the vector connecting the two atoms
d.y vector the y-component of the vector connecting the two atoms
d.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
# Construct a matrix that contains all the components of the vectors calculated
vThe VSTACK action with label v calculates the following quantities: Quantity    Type    Description  
v 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=d.x,d.y,d.z
# Transpose v
vTThe TRANSPOSE action with label vT calculates the following quantities: Quantity    Type    Description  
vT 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=v
# And now calculate the 3x3 matrix of dot products
mThe MATRIX_PRODUCT action with label m calculates the following quantities: Quantity    Type    Description  
m matrix the product of the two input matrices: MATRIX_PRODUCTCalculate the product of two matrices More details ARGthe label of the two matrices from which the product is calculated=v,vT
# And output the matrix product to a file
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=m FILEthe name of the file on which to output these quantities=colvar

The MASK keyword

We can use MATRIX_PRODUCT to calculate a measure of local order as shown below:

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

# Calculate the vectors connecting these three pairs of atoms
dThe DISTANCE action with label d calculates the following quantities: Quantity    Type    Description  
d.x vector the x-component of the vector connecting the two atoms
d.y vector the y-component of the vector connecting the two atoms
d.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
# Normalize the distance vectors
dmThe DISTANCE action with label dm calculates the following quantities: Quantity    Type    Description  
dm vector the DISTANCE for each set of specified atoms: DISTANCECalculate the distance/s between pairs of atoms. More details 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
dxThe CUSTOM action with label dx calculates the following quantities: Quantity    Type    Description  
dx 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=d.x,dm 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
dyThe CUSTOM action with label dy calculates the following quantities: Quantity    Type    Description  
dy 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=d.y,dm 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
dzThe CUSTOM action with label dz calculates the following quantities: Quantity    Type    Description  
dz 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=d.z,dm 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
# Construct a matrix that contains all the directors of the vectors calculated
vThe VSTACK action with label v calculates the following quantities: Quantity    Type    Description  
v 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=dx,dy,dz
# Transpose v
vTThe TRANSPOSE action with label vT calculates the following quantities: Quantity    Type    Description  
vT 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=v
# Calculate a contact matrix between pairs of atoms
cmapThe CONTACT_MATRIX action with label cmap calculates the following quantities: Quantity    Type    Description  
cmap 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,3,5 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.={RATIONAL R_0=0.2 D_MAX=0.5}
# Calculate the matrix of dot products
prodThe MATRIX_PRODUCT action with label prod calculates the following quantities: Quantity    Type    Description  
prod matrix the product of the two input matrices: MATRIX_PRODUCTCalculate the product of two matrices More details ARGthe label of the two matrices from which the product is calculated=v,vT MASKa matrix that is used to used to determine which elements of the output matrix to compute=cmap
# Take the product of the two matrices we computed above
pThe CUSTOM action with label p calculates the following quantities: Quantity    Type    Description  
p 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=cmap,prod 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 of the dot product for the molecules in the
# first coordination sphere around each of the atoms
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=3
# PLUMED interprets the command:
# ones: ONES SIZE=3
# 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
# --- End of included input --- numerThe MATRIX_VECTOR_PRODUCT action with label numer calculates the following quantities: Quantity    Type    Description  
numer 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=p,ones
denomThe MATRIX_VECTOR_PRODUCT action with label denom calculates the following quantities: Quantity    Type    Description  
denom 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=cmap,ones
orderThe CUSTOM action with label order calculates the following quantities: Quantity    Type    Description  
order 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=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
# Print the order parameter values
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=order FILEthe name of the file on which to output these quantities=colvar

In the above input the DISTANCE action is used to calculate the orientations of some molecules (you would normally use more distances than the three that are used in this input when doing this sort of calculation). We then construct a matrix called v that contains the directors of the vectors that define the orientation of these molecules. The final vector of values order that is output here measures the average for the dot product between the orientations of the molecules and the molecules in their first coordination sphere.

Ideass similar to this are used in the calculation of LOCAL_Q3, LOCAL_Q4 and LOCAL_Q6. Notice, that it is very important to use MASK keyword in the MATRIX_PRODUCT action when you are doing this type calculation. Using this keyword ensures that PLUMED does not calculate the $(i,j)$ matrix of the matrix prod if the corresponding element in cmap is zero. Using this keyword thus ensures that we can avoid a large number of unecessary calculations and improves the performance of the calculation considerably.

Calculating angles

MATRIX_PRODUCT can also be used to calculate a matrix of angles between bonds as shown below:

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

# Calculate the directors for a set of vectors
dThe DISTANCE action with label d calculates the following quantities: Quantity    Type    Description  
d.x vector the x-component of the vector connecting the two atoms
d.y vector the y-component of the vector connecting the two atoms
d.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=1,3 ATOMS3the pair of atom that we are calculating the distance between=1,4 ATOMS4the pair of atom that we are calculating the distance between=1,5 ATOMS5the pair of atom that we are calculating the distance between=1,6
dmThe DISTANCE action with label dm calculates the following quantities: Quantity    Type    Description  
dm vector the DISTANCE for each set of specified atoms: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMS1the pair of atom that we are calculating the distance between=1,2 ATOMS2the pair of atom that we are calculating the distance between=1,3 ATOMS3the pair of atom that we are calculating the distance between=1,4 ATOMS4the pair of atom that we are calculating the distance between=1,5 ATOMS5the pair of atom that we are calculating the distance between=1,6
dxThe CUSTOM action with label dx calculates the following quantities: Quantity    Type    Description  
dx 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=d.x,dm 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
dyThe CUSTOM action with label dy calculates the following quantities: Quantity    Type    Description  
dy 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=d.y,dm 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
dzThe CUSTOM action with label dz calculates the following quantities: Quantity    Type    Description  
dz 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=d.z,dm 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
# Construct a matrix that contains all the directors of the vectors calculated
vThe VSTACK action with label v calculates the following quantities: Quantity    Type    Description  
v 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=dx,dy,dz
# Transpose v
vTThe TRANSPOSE action with label vT calculates the following quantities: Quantity    Type    Description  
vT 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=v
# Calculate the matrix of dot products between the input directors
dpmatThe MATRIX_PRODUCT action with label dpmat calculates the following quantities: Quantity    Type    Description  
dpmat matrix the product of the two input matrices: MATRIX_PRODUCTCalculate the product of two matrices More details ELEMENTS_ON_DIAGONAL_ARE_ZERO set all diagonal elements to zero ARGthe label of the two matrices from which the product is calculated=v,vT
# And calculate the angles
anglesThe CUSTOM action with label angles calculates the following quantities: Quantity    Type    Description  
angles 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=dpmat FUNCthe function you wish to evaluate=acos(x) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
# Print the matrix of angles
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=angles FILEthe name of the file on which to output these quantities=colvar

Notice that we have to use the ELEMENTS_ON_DIAGONAL_ARE_ZERO flag here to avoid numerical issues in the calculation.

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
ELEMENTS_ON_DIAGONAL_ARE_ZERO	optional	false	set all diagonal elements to zero
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
c1	matrix	a matrix containing the weights for the bonds between each pair of atoms