Action: QUATERNION_PRODUCT_MATRIX

Module	crystdistrib
Description	Usage
Calculate the outer product matrix from two vectors of quaternions

Details and examples

Calculate the outer product matrix from two vectors of quaternions

Calculate the outer product matrix from two vectors of quaternions. Quaternions are made of four numbers, one real number, and three imaginary numbers \textit{i}, \textit{j}, and \textit{k}. The imaginary numbers are not commutative:

$$ij =k$$ $$jk=i$$ $$ki=j$$ $$ji = -k$$ $$ik = -j$$ $$kj = -i$$ $$ii = jj = kk = -1$$

Thus multiplying two quaternions $\mathbf{q_1} = w_1 + x_1i + y_1j + z_1k$ and $\mathbf{q_2} = w_2 + x_2i + y_2j + z_2k$ yields the following four components:

$$w_{12} = w_1w_2 - x_1x_2 - y_1y_2 -z_1z_2$$ $$x_{12}i = (w_1x_2 + x_1w_2 + y_1z_2 - z_1y_2 )i$$ $$y_{12}j = (w_1y_2 - x_1z_2 + y_1w_2 + z_1x_2)j$$ $$z_{12}k = (w_1z_2 + x_1y_2 - y_1x_2 + z_1w_2)k$$

Quaternions can also be multiplied by a real number, and the conjugate $\mathbf{\overline{q}} = w -xi - yj - zk$ is analogous to complex numbers.

This action takes two equal sized vectors of quaternions of length $n$, and returns four $n\times n$ outer product matrices, corresponding to components w, x, y, and z in the above example. These matrices are real numbers, and will not behave with the usual nuances of quaternion algebra in any CUSTOMS, or other actions, that will need to be accounted for manually. The vectors of quaternions can be the same vectors, or different. Note, since the QUATERNION action returns unit quaternions, all quaternions returned here will also be unit quaternions.

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

#in a system of 4 molecules, each with 3 atoms
#define quaternions 1-4
quats12The QUATERNION action with label quats12 calculates the following quantities:
 Quantity   
 Type   
 Description  
quats12.w
vector
the real component of quaternion
quats12.i
vector
the i component of the quaternion
quats12.j
vector
the j component of the quaternion
quats12.k
vector
the k component of the quaternion: QUATERNIONCalculate unit quaternions for molecules. More details ATOMS1the three atom that we are using to calculate the quaternion=1,2,3 ATOMS2the three atom that we are using to calculate the quaternion=4,5,6
quats34The QUATERNION action with label quats34 calculates the following quantities:
 Quantity   
 Type   
 Description  
quats34.w
vector
the real component of quaternion
quats34.i
vector
the i component of the quaternion
quats34.j
vector
the j component of the quaternion
quats34.k
vector
the k component of the quaternion: QUATERNIONCalculate unit quaternions for molecules. More details ATOMS1the three atom that we are using to calculate the quaternion=7,8,9 ATOMS2the three atom that we are using to calculate the quaternion=10,11,12

#take the outer product of 1,2 and 3,4
qpThe QUATERNION_PRODUCT_MATRIX action with label qp calculates the following quantities:
 Quantity   
 Type   
 Description  
qp.w
matrix
the real component of quaternion
qp.i
matrix
the i component of the quaternion
qp.j
matrix
the j component of the quaternion
qp.k
matrix
the k component of the quaternion: QUATERNION_PRODUCT_MATRIXCalculate the outer product matrix from two vectors of quaternions More details ARGthe labels of the quaternion vectors that you are outer product of=quats12.*,quats34.* #notice the asterisk
#the components need to be passed in the order w1,x1,y1,z1,w2,x2,y2,z2
#now use in an order parameter
bpwThe CUSTOM action with label bpw calculates the following quantities:
 Quantity   
 Type   
 Description  
bpw
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=qp.* VARthe names to give each of the arguments in the function=w,x,y,z FUNCthe function you wish to evaluate=exp(w/2+x/2+y/2+z/2) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO

A common strategy when using this action is to multiply a function of elements of the quaternion product matrix by a contact matrix as shown below:

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

# Calculate some quaternions
quats12The QUATERNION action with label quats12 calculates the following quantities:
 Quantity   
 Type   
 Description  
quats12.w
vector
the real component of quaternion
quats12.i
vector
the i component of the quaternion
quats12.j
vector
the j component of the quaternion
quats12.k
vector
the k component of the quaternion: QUATERNIONCalculate unit quaternions for molecules. More details ATOMS1the three atom that we are using to calculate the quaternion=1,2,3 ATOMS2the three atom that we are using to calculate the quaternion=4,5,6 ATOMS3the three atom that we are using to calculate the quaternion=7,8,9 ATOMS4the three atom that we are using to calculate the quaternion=10,11,12
# Calculate a contact matrix
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,4,7,10 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.7}
# Calculate the quaternion product matrix
qpThe QUATERNION_PRODUCT_MATRIX action with label qp calculates the following quantities:
 Quantity   
 Type   
 Description  
qp.w
matrix
the real component of quaternion
qp.i
matrix
the i component of the quaternion
qp.j
matrix
the j component of the quaternion
qp.k
matrix
the k component of the quaternion: QUATERNION_PRODUCT_MATRIXCalculate the outer product matrix from two vectors of quaternions More details ARGthe labels of the quaternion vectors that you are outer product of=quats12.*,quats12.* MASKa matrix that is used to used to determine which elements of the output matrix to compute=cmap
# Now calculate a function of the quaternion elements (normally something more complicated than the following is performed
funcThe CUSTOM action with label func calculates the following quantities:
 Quantity   
 Type   
 Description  
func
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,qp.* VARthe names to give each of the arguments in the function=x,w,i,j,k FUNCthe function you wish to evaluate=x*(w+i+j+k) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
# Now sum the rows of the above matrix
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=4
# PLUMED interprets the command:
# ones: ONES SIZE=4
# 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
# --- End of included input --- opThe MATRIX_VECTOR_PRODUCT action with label op calculates the following quantities:
 Quantity   
 Type   
 Description  
op
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=func,ones
# And output the values of the order parameter
DUMPATOMSDump selected atoms on a file. More details ATOMSthe atom indices whose positions you would like to print out=1,4,7,10 ARGthe labels of vectors that should be output in the xyz file=op FILEfile on which to output coordinates; extension is automatically detected=func.yxz

Notice how the MASK keyword is used in the CUSTOM in the input to QUATERNION_PRODUCT_MATRIX to prevent PLUMED from calculating the elements of the QUATERNION_PRODUCT_MATRIX that will be multiplied by the elements of that matrix cmap that is calculated in the CONTACT_MATRIX action when the calculations in the CUSTOM action with label func are performed. This is the same procedure that is performed in TORSIONS_MATRIX and MATRIX_PRODUCT to avoid computational expense. This procedure is automatically performed when you use the ROPS shortcut.

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 quaternion vectors that you are outer product of
MASK	matrix	a matrix that is used to used to determine which elements of the output matrix to compute

Output components

This action calculates the values in the following table. These values can be referenced elsewhere in the input by using this Action's label followed by a dot and the name of the value required from the list below.

Name	Type	Description
w	matrix	the real component of quaternion
i	matrix	the i component of the quaternion
j	matrix	the j component of the quaternion
k	matrix	the k component of the quaternion

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 quaternion vectors that you are outer product of
MASK	input	none	a matrix that is used to used to determine which elements of the output matrix to compute
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.