Shortcut: OUTER_PRODUCT

Module	matrixtools
Description	Usage
Calculate the outer product matrix of two vectors
output value	type
a matrix containing the outer product of the two input vectors that was obtained using the function that was input	matrix

Details and examples

Calculate the outer product matrix of two vectors

This action can be used to calculate the outer product of two vectors. As a (useless) example of what can be done with this action consider the following simple input:

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 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
d2The DISTANCE action with label d2 calculates the following quantities: Quantity    Type    Description  
d2 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=5,6 ATOMS2the pair of atom that we are calculating the distance between=7,8 ATOMS3the pair of atom that we are calculating the distance between=9,10
ppThe OUTER_PRODUCT action with label pp calculates the following quantities: Quantity    Type    Description  
pp 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=d1,d2
pp: 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=d1,d2  FUNC the function of the input vectors that should be put in the elements of the outer product=x*y
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=pp FILEthe name of the file on which to output these quantities=colvar

This input outputs a $2 \times 3$ matrix. If we call the 2 dimensional vector output by the first DISTANCE action $d$ and the 3 dimensional vector output by the second DISTANCE action $h$ then the $(i,j)$ element of the matrix output by the action with the label pp is given by:

$p_{ij} = d_i h_j$

These outer product matrices are useful if you are trying to calculate an adjacency matrix that says atoms are connected if they are within a certain distance of each other and if they satisfy a certain criterion. For example, consider the following input:

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

# Determine if atoms are within 5.3 nm of each other
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.={GAUSSIAN D_0=5.29 R_0=0.01 D_MAX=5.3}
# Calculate the coordination numbers
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 --- ccThe MATRIX_VECTOR_PRODUCT action with label cc calculates the following quantities: Quantity    Type    Description  
cc 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=c1,ones
# Now use MORE_THAN to work out which atoms have a coordination number that is bigger than six
cfThe MORE_THAN action with label cf calculates the following quantities: Quantity    Type    Description  
cf vector the vector obtained by doing an element-wise application of a function that is one if the if the input is more than a threshold to the input vectors: MORE_THANUse a switching function to determine how many of the input variables are more than a certain cutoff. More details ARGthe values input to this function=cc SWITCHThis keyword is used if you want to employ an alternative to the continuous swiching function defined above={RATIONAL D_0=5.5 R_0=0.5}
# Now recalculate the contact matrix above as first step towards calculating adjacency matrix that measures if
# atoms are close to each other and both have a coordination number that is bigger than six
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.={GAUSSIAN D_0=5.29 R_0=0.01 D_MAX=5.3}
# Now make a matrix in which element i,j is one if atom i and atom j both have a coordination number that is greater than 6
cfmThe OUTER_PRODUCT action with label cfm calculates the following quantities: Quantity    Type    Description  
cfm 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=cf,cf MASKa matrix that is used to used to determine which elements of the output matrix to compute=c2
cfm: 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=cf,cf MASKa matrix that is used to used to determine which elements of the output matrix to compute=c2  FUNC the function of the input vectors that should be put in the elements of the outer product=x*y
# And multiply this by our contact matrix to determine the desired adjacency matrix
mThe CUSTOM action with label m calculates the following quantities: Quantity    Type    Description  
m 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=c2,cfm 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
fThe SUM action with label f calculates the following quantities: Quantity    Type    Description  
f 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=m 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=f FILEthe name of the file on which to output these quantities=colvar

This input calculates a adjacency matrix which has element $(i,j)$ equal to one if atoms $i$ and $j$ have coordination numbers that are greater than 6 and if they are within 5.3 nm of each other. Notice how the MASK keyword is used in the input to the OUTER_PRODUCT action here to ensure that do not calculate elements of the cfm matrix that will be mulitplied by elements of the matrix c2 that are zero. The final quantity output is equal to two times the number of pairs of atoms that are within 5.3 nm of each and which both have coordination numbers of six.

Notice that you can specify the function of the two input vectors that is to be calculated by using the FUNC keyword which accepts mathematical expressions of $x$ and $y$ . In other words, the elements of the outer product are calculated using the lepton library that is used in the CUSTOM action. In addition, you can set FUNC=min or FUNC=max to set the elements of the outer product equal to the minimum of the two input variables or the maximum respectively.

Calculating angles in the first coordination sphere

We can use OUTER_PRODUCT 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
# Transform the distances by a switching functions to determine pairs of atoms that are bonded
swThe LESS_THAN action with label sw calculates the following quantities: Quantity    Type    Description  
sw 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=dm SWITCHThis keyword is used if you want to employ an alternative to the continuous swiching function defined above={RATIONAL R_0=0.2}
# 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
# Use the transformed distances to determine which triples of atoms are bonded
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 ELEMENTS_ON_DIAGONAL_ARE_ZERO set all diagonal elements to zero ARGthe labels of the two vectors from which the outer product is being computed=sw,sw
swmat: OUTER_PRODUCTCalculate the outer product matrix of two vectors This action uses the defaults shown here. More details ELEMENTS_ON_DIAGONAL_ARE_ZERO set all diagonal elements to zero ARGthe labels of the two vectors from which the outer product is being computed=sw,sw  FUNC the function of the input vectors that should be put in the elements of the outer product=x*y
# 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=swmat,dpmat FUNCthe function you wish to evaluate=x*acos(y) 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
ARG	vector	the labels of the two vectors from which the outer product is being computed
MASK	matrix	a matrix that is used to used to determine which elements of the output matrix to compute

Full list of keywords

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

Keyword	Type	Default	Description
ARG	input	none	the labels of the two vectors from which the outer product is being computed
MASK	input	none	a matrix that is used to used to determine which elements of the output matrix to compute
FUNC	compulsory	x*y	the function of the input vectors that should be put in the elements of the outer product
ELEMENTS_ON_DIAGONAL_ARE_ZERO	optional	false	set all diagonal elements to zero

Quantity	Type	Description
d1	vector	the DISTANCE for each set of specified atoms