Action: QUATERNION

Module	crystdistrib
Description	Usage
Calculate unit quaternions for molecules.

Details and examples

Calculate unit quaternions for molecules.

This action calculates a unit quaternion to define an internal coordinate frame for a molecule. The reference frame for the molecule is user-defined using the positions of three (non-collinear) atoms. The vectors which will define the frame are calculated as follows from atomic coordinates, all vectors in $\mathbb{R}^3$, $x_1, x_2, x_3$:

The first axis is the normalized difference of $x_1$ and $x_2$:

$$\mathbf{\hat{v_1}} = x_2 - x_1 / \|x_2 - x_1\|$$

In general, the vector $\mathbf{v'_2} = x_3 - x_1$ will not be orthogonal to $\mathbf{\hat{v_1}}$. This is fixed by taking the difference between the projection of $\mathbf{v'_2}$ onto $\mathbf{\hat{v_1}}$ and $\mathbf{\hat{v_1}}$.

$$\mathbf{v_2} = \mathbf{v'_2} - Proj_{\mathbf{\hat{v}_1}}(\mathbf{v'_2}) = \mathbf{v'_2} - \mathbf{\hat{v}_1} \cdot \mathbf{v'_2}$$

This is then normalized to form the second axis.

$$\mathbf{\hat{v_2}} = \mathbf{v_2} / \|\mathbf{v_2}\|$$

Finally, the third axis is the cross product between the first two.

$$\mathbf{\hat{v_3}} = \mathbf{\hat{v_1}} \times \mathbf{\hat{v_2}}$$

The above 9 components form an orthonormal basis, centered on the molecule provided. The rotation matrix is generally the inverse of this matrix, and in this case since the matrix is orthogonal and its determinant is 1, the inverse is simply the transpose. The rotation matrix is then converted to a quaternion. The resulting quaternion has 4 real numbers attached to it, and they can be called as w, i , j ,and k. Note the quaternions are not unique e.g. q and -q perform the same rotation, so take care when using the results. Take care that the components are simply 4 real numbers, and the usual non-commutativity of quaternions, and any other algebraic difference will need to be accounted for manually in later usage. No checks are made for co-linearity, or if the atoms are a part of the same molecule.

An example input file, in a system of 12 atoms. It calculates four molecular frames, then uses them in an order parameter.

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

q1The QUATERNION action with label q1 calculates the following quantities:
 Quantity   
 Type   
 Description  
q1.w
vector
the real component of quaternion
q1.i
vector
the i component of the quaternion
q1.j
vector
the j component of the quaternion
q1.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,3,2 ATOMS2the three atom that we are using to calculate the quaternion=4,6,5
q2The QUATERNION action with label q2 calculates the following quantities:
 Quantity   
 Type   
 Description  
q2.w
vector
the real component of quaternion
q2.i
vector
the i component of the quaternion
q2.j
vector
the j component of the quaternion
q2.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,9,8 ATOMS2the three atom that we are using to calculate the quaternion=10,12,11
#There are no checks to make sure the atoms belong to the same molecule

fakeThe CUSTOM action with label fake calculates the following quantities:
 Quantity   
 Type   
 Description  
fake
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=q1.w,q1.i,q1.j,q1.k,q2.w,q2.i,q2.j,q2.k VARthe names to give each of the arguments in the function=w1,i1,j1,k1,w2,i2,j2,k2 FUNCthe function you wish to evaluate=w1*w2+i1*i2+j1*j2+k1*k2 PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
#this isn’t a real order parameter, for the record
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=fake FILEthe name of the file on which to output these quantities=fakeout

The last thing to note is that by default a procedure akin to that used in WHOLEMOLECULES is used to ensure that the sets of atoms that are specified to each ATOMS keyword are not broken by the periodic boundary conditions. If you would like to turn this off for any reason you add the NOPBC in your input file as shown below:

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

dThe QUATERNION action with label d calculates the following quantities:
 Quantity   
 Type   
 Description  
d.w
scalar
the real component of quaternion
d.i
scalar
the i component of the quaternion
d.j
scalar
the j component of the quaternion
d.k
scalar
the k component of the quaternion: QUATERNIONCalculate unit quaternions for molecules. More details ATOMSthe three atom that we are using to calculate the quaternion=1,2,3 NOPBC ignore the periodic boundary conditions when calculating distances

Input

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

Keyword	Type	Description
ATOMS	atoms	the three atom that we are using to calculate the quaternion

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	scalar/vector	the real component of quaternion
i	scalar/vector	the i component of the quaternion
j	scalar/vector	the j component of the quaternion
k	scalar/vector	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
ATOMS	input	none	the three atom that we are using to calculate the quaternion
NOPBC	optional	false	ignore the periodic boundary conditions when calculating distances