Shortcut: BOPS

Module	crystdistrib
Description	Usage
Calculate Bond orientational order parameters for molecules.
output value	type
the values of the bops order parameters	vector

Details and examples

Calculate Bond orientational order parameters for molecules.

BOPS is a shortcut to calculate the Bond-orientational Order Parameters detailed that are described in the paper cited below. As arguments, BOPS takes a list of atoms (corresponding to molecules), a vector of quaternions, a cutoff distance, and two kernel files detailing the means, variances, and normalization factors of probability distributions. BOPS returns a vector of order parameters.

The DOPS kernel file has FIELDS height, mu, and sigma corresponding to the normalization factor, mean, and variance of the gaussian distributions used in the order parameters. The SET kerneltype is gaussian.

The BOPS kernel file has FIELDS height, kappa, mu_i, mu_j, and mu_k, which correspond to the normalization factor, reciprocal variance, and imaginary components of the mean quaternion frame of the fisher distribution used in the order parameters. The SET kerneltype is gaussian.

BOPS returns one order parameter per atom given, evaluated over each atom's neighbors within the cutoff given. The distribution defined by the kernel files, analogous to a radial distribution function, is defined over all possible unit vectors which could be drawn between two atoms. The order parameter is obtained by evaluating the distribution at each unit vector pointing to all neighbors within the cutoff, and summing them up.

This example file calculates the BOPS for a system of 3 molecules.

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

#SETTINGS INPUTFILES=regtest/crystdistrib/rt-bops-shortcut/kernels.dat,regtest/crystdistrib/rt-bops-shortcut/kernels2.dat
quatThe QUATERNION action with label quat calculates the following quantities: Quantity    Type    Description  
quat.w vector the real component of quaternion
quat.i vector the i component of the quaternion
quat.j vector the j component of the quaternion
quat.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
bopsThe BOPS action with label bops calculates the following quantities: Quantity    Type    Description  
bops vector the values of the bops order parameters: BOPSCalculate Bond orientational order parameters for molecules. This action is a shortcut. More details ...
   SPECIESthe list of atoms for which the BOPS are being calculated and the atoms that can be in the environments=1,4,7 QUATERNIONSthe label of the action that computes the quaternions that should be used=quat CUTOFFcutoff for the distance matrix=100.0
   KERNELFILE_DOPSthe file containing the list of kernel parameters=regtest/crystdistrib/rt-bops-shortcut/kernels.dat Click here to see an extract from this file.
    ×  FILE: regtest/crystdistrib/rt-bops-shortcut/kernels.dat
    #! FIELDS height mu sigma
#! SET kerneltype gaussian
2.26628554234 6.37235632777 0.17603354605920524374
2.26598891932 6.37243472055 0.17605658924421270294
2.83246817245 6.94118069019 0.14084616529226330342
2.23141032403 6.87945090447 0.178784814297  
2.26563347801 6.81645001966 0.17608420968
2.26829869206 6.37245683771 0.1758773136
2.26856314184 6.37237895273 0.175856811319
2.84313122015 6.94216988399 0.140317927493
2.21827805142 6.87753705648 0.17984322576
2.27474509536 6.81810643390 0.175378894635

  
   KERNELFILE_BOPSthe second file containing the list of kernel parameters=regtest/crystdistrib/rt-bops-shortcut/kernels2.dat Click here to see an extract from this file.
    ×  FILE: regtest/crystdistrib/rt-bops-shortcut/kernels2.dat
    #! FIELDS height kappa mu_i mu_j mu_k
#! SET kerneltype gaussian
 3.8829243099e-18  41.9894852862 -0.348283942052 0.524758480496 -0.776741162072    
 3.43814557322e-18 42.1141050811 0.348733460765 -0.524528707287 0.776694668821  
 0.00154170375415  6.51039194933 0.424981437646 -0.297987050518 -0.854748205836 
 0.00503593591682  5.07829278001 0.490875761357 -0.838880031696 -0.23520476044  
 0.000460252362407 7.91456317429 -0.664588066199 -0.747014059121 0.0171084114137
 1.98361770876e-18 42.6774018539 0.348941708009 -0.525224891263 -0.776130464554
 2.75571521921e-18 42.3407270276 -0.348703675624 0.525485712398 0.776060894951 
 0.001568955927    6.48968397136 0.424895911761 -0.296072398134 0.855455784499 
 0.0049759205175   5.09321471523 0.485757599732 -0.841908207588 0.23501090251  
 0.000463852264493 7.90564452226 -0.667481506462 -0.74446245095 -0.0156236249692






  
...
# PLUMED interprets the command:
# bops: BOPS ...
#    SPECIES=1,4,7 QUATERNIONS=quat CUTOFF=100.0
#    KERNELFILE_DOPS=regtest/crystdistrib/rt-bops-shortcut/kernels.dat
#    KERNELFILE_BOPS=regtest/crystdistrib/rt-bops-shortcut/kernels2.dat
# ...
# as follows (Click the red comment above to revert to the short version of the input):
bops_cmatThe DISTANCE_MATRIX action with label bops_cmat calculates the following quantities: Quantity    Type    Description  
bops_cmat.w matrix a matrix containing the weights for the bonds between each pair of atoms
bops_cmat.x matrix the projection of the bond on the x axis
bops_cmat.y matrix the projection of the bond on the y axis
bops_cmat.z matrix the projection of the bond on the z axis: DISTANCE_MATRIXCalculate a matrix of distances between atoms. More details  GROUPthe atoms for which you would like to calculate the adjacency matrix=1,4,7 CUTOFF ignore distances that have a value larger than this cutoff=100 COMPONENTS also calculate the components of the vector connecting the atoms in the contact matrix
bops_quatprodThe QUATERNION_BOND_PRODUCT_MATRIX action with label bops_quatprod calculates the following quantities: Quantity    Type    Description  
bops_quatprod.w matrix the real component of quaternion
bops_quatprod.i matrix the i component of the quaternion
bops_quatprod.j matrix the j component of the quaternion
bops_quatprod.k matrix the k component of the quaternion: QUATERNION_BOND_PRODUCT_MATRIXCalculate the product between a matrix of quaternions and the bonds connecting molecules More details ARGthis action takes 8 arguments=quat.*,bops_cmat.*
bops_distThe CUSTOM action with label bops_dist calculates the following quantities: Quantity    Type    Description  
bops_dist 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=bops_cmat.x,bops_cmat.y,bops_cmat.z FUNCthe function you wish to evaluate=sqrt((x^2)+(y^2)+(z^2)) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
bops_kfuncThe CUSTOM action with label bops_kfunc calculates the following quantities: Quantity    Type    Description  
bops_kfunc 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=bops_quatprod.i,bops_quatprod.j,bops_quatprod.k,bops_dist VARthe names to give each of the arguments in the function=i,j,k,x FUNCthe function you wish to evaluate=2.26629*exp(-(x-6.37236)^2/(2*0.176034*0.176034))*3.88292e-18*exp(41.9895*(i*-0.348284+j*0.524758+k*-0.776741))+2.26599*exp(-(x-6.37243)^2/(2*0.176057*0.176057))*3.43815e-18*exp(42.1141*(i*0.348733+j*-0.524529+k*0.776695))+2.83247*exp(-(x-6.94118)^2/(2*0.140846*0.140846))*0.0015417*exp(6.51039*(i*0.424981+j*-0.297987+k*-0.854748))+2.23141*exp(-(x-6.87945)^2/(2*0.178785*0.178785))*0.00503594*exp(5.07829*(i*0.490876+j*-0.83888+k*-0.235205))+2.26563*exp(-(x-6.81645)^2/(2*0.176084*0.176084))*0.000460252*exp(7.91456*(i*-0.664588+j*-0.747014+k*0.0171084))+2.2683*exp(-(x-6.37246)^2/(2*0.175877*0.175877))*1.98362e-18*exp(42.6774*(i*0.348942+j*-0.525225+k*-0.77613))+2.26856*exp(-(x-6.37238)^2/(2*0.175857*0.175857))*2.75572e-18*exp(42.3407*(i*-0.348704+j*0.525486+k*0.776061))+2.84313*exp(-(x-6.94217)^2/(2*0.140318*0.140318))*0.00156896*exp(6.48968*(i*0.424896+j*-0.296072+k*0.855456))+2.21828*exp(-(x-6.87754)^2/(2*0.179843*0.179843))*0.00497592*exp(5.09321*(i*0.485758+j*-0.841908+k*0.235011))+2.27475*exp(-(x-6.81811)^2/(2*0.175379*0.175379))*0.000463852*exp(7.90564*(i*-0.667482+j*-0.744462+k*-0.0156236)) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
bops_onesThe CONSTANT action with label bops_ones calculates the following quantities: Quantity    Type    Description  
bops_ones vector the constant value that was read from the plumed input: ONESCreate a constant vector with all elements equal to one More details SIZEthe number of ones that you would like to create=3
bopsThe MATRIX_VECTOR_PRODUCT action with label bops calculates the following quantities: Quantity    Type    Description  
bops 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=bops_kfunc,bops_ones
# --- End of included input ---

To calculate the BOPS between the orientation of the molecules in GROUPA and the bonds to the atoms in GROUPB you use an input like the one shown below:

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

#SETTINGS INPUTFILES=regtest/crystdistrib/rt-bops-shortcut/kernels.dat,regtest/crystdistrib/rt-bops-shortcut/kernels2.dat
quatThe QUATERNION action with label quat calculates the following quantities: Quantity    Type    Description  
quat.w vector the real component of quaternion
quat.i vector the i component of the quaternion
quat.j vector the j component of the quaternion
quat.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
bopsThe BOPS action with label bops calculates the following quantities: Quantity    Type    Description  
bops vector the values of the bops order parameters: BOPSCalculate Bond orientational order parameters for molecules. This action is a shortcut. More details ...
   QUATERNIONSthe label of the action that computes the quaternions that should be used=quat CUTOFFcutoff for the distance matrix=100.0
   SPECIESAthe list of atoms for which BOPS are being calculated=1,4,7 SPECIESBthe list of atoms that can be in the environments of each of the atoms for which the BOPS are being calculated=10,11,12,13,14
   KERNELFILE_DOPSthe file containing the list of kernel parameters=regtest/crystdistrib/rt-bops-shortcut/kernels.dat Click here to see an extract from this file.
    ×  FILE: regtest/crystdistrib/rt-bops-shortcut/kernels.dat
    #! FIELDS height mu sigma
#! SET kerneltype gaussian
2.26628554234 6.37235632777 0.17603354605920524374
2.26598891932 6.37243472055 0.17605658924421270294
2.83246817245 6.94118069019 0.14084616529226330342
2.23141032403 6.87945090447 0.178784814297  
2.26563347801 6.81645001966 0.17608420968
2.26829869206 6.37245683771 0.1758773136
2.26856314184 6.37237895273 0.175856811319
2.84313122015 6.94216988399 0.140317927493
2.21827805142 6.87753705648 0.17984322576
2.27474509536 6.81810643390 0.175378894635

  
   KERNELFILE_BOPSthe second file containing the list of kernel parameters=regtest/crystdistrib/rt-bops-shortcut/kernels2.dat Click here to see an extract from this file.
    ×  FILE: regtest/crystdistrib/rt-bops-shortcut/kernels2.dat
    #! FIELDS height kappa mu_i mu_j mu_k
#! SET kerneltype gaussian
 3.8829243099e-18  41.9894852862 -0.348283942052 0.524758480496 -0.776741162072    
 3.43814557322e-18 42.1141050811 0.348733460765 -0.524528707287 0.776694668821  
 0.00154170375415  6.51039194933 0.424981437646 -0.297987050518 -0.854748205836 
 0.00503593591682  5.07829278001 0.490875761357 -0.838880031696 -0.23520476044  
 0.000460252362407 7.91456317429 -0.664588066199 -0.747014059121 0.0171084114137
 1.98361770876e-18 42.6774018539 0.348941708009 -0.525224891263 -0.776130464554
 2.75571521921e-18 42.3407270276 -0.348703675624 0.525485712398 0.776060894951 
 0.001568955927    6.48968397136 0.424895911761 -0.296072398134 0.855455784499 
 0.0049759205175   5.09321471523 0.485757599732 -0.841908207588 0.23501090251  
 0.000463852264493 7.90564452226 -0.667481506462 -0.74446245095 -0.0156236249692






  
...
# PLUMED interprets the command:
# bops: BOPS ...
#    QUATERNIONS=quat CUTOFF=100.0
#    SPECIESA=1,4,7 SPECIESB=10,11,12,13,14
#    KERNELFILE_DOPS=regtest/crystdistrib/rt-bops-shortcut/kernels.dat
#    KERNELFILE_BOPS=regtest/crystdistrib/rt-bops-shortcut/kernels2.dat
# ...
# as follows (Click the red comment above to revert to the short version of the input):
bops_cmatThe DISTANCE_MATRIX action with label bops_cmat calculates the following quantities: Quantity    Type    Description  
bops_cmat.w matrix a matrix containing the weights for the bonds between each pair of atoms
bops_cmat.x matrix the projection of the bond on the x axis
bops_cmat.y matrix the projection of the bond on the y axis
bops_cmat.z matrix the projection of the bond on the z axis: DISTANCE_MATRIXCalculate a matrix of distances between atoms. More details  GROUPAwhen you are calculating the adjacency matrix between two sets of atoms this keyword is used to specify the atoms along with the keyword GROUPB=1,4,7 GROUPBwhen you are calculating the adjacency matrix between two sets of atoms this keyword is used to specify the atoms along with the keyword GROUPA=10,11,12,13,14 CUTOFF ignore distances that have a value larger than this cutoff=100 COMPONENTS also calculate the components of the vector connecting the atoms in the contact matrix
bops_quatprodThe QUATERNION_BOND_PRODUCT_MATRIX action with label bops_quatprod calculates the following quantities: Quantity    Type    Description  
bops_quatprod.w matrix the real component of quaternion
bops_quatprod.i matrix the i component of the quaternion
bops_quatprod.j matrix the j component of the quaternion
bops_quatprod.k matrix the k component of the quaternion: QUATERNION_BOND_PRODUCT_MATRIXCalculate the product between a matrix of quaternions and the bonds connecting molecules More details ARGthis action takes 8 arguments=quat.*,bops_cmat.*
bops_distThe CUSTOM action with label bops_dist calculates the following quantities: Quantity    Type    Description  
bops_dist 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=bops_cmat.x,bops_cmat.y,bops_cmat.z FUNCthe function you wish to evaluate=sqrt((x^2)+(y^2)+(z^2)) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
bops_kfuncThe CUSTOM action with label bops_kfunc calculates the following quantities: Quantity    Type    Description  
bops_kfunc 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=bops_quatprod.i,bops_quatprod.j,bops_quatprod.k,bops_dist VARthe names to give each of the arguments in the function=i,j,k,x FUNCthe function you wish to evaluate=2.26629*exp(-(x-6.37236)^2/(2*0.176034*0.176034))*3.88292e-18*exp(41.9895*(i*-0.348284+j*0.524758+k*-0.776741))+2.26599*exp(-(x-6.37243)^2/(2*0.176057*0.176057))*3.43815e-18*exp(42.1141*(i*0.348733+j*-0.524529+k*0.776695))+2.83247*exp(-(x-6.94118)^2/(2*0.140846*0.140846))*0.0015417*exp(6.51039*(i*0.424981+j*-0.297987+k*-0.854748))+2.23141*exp(-(x-6.87945)^2/(2*0.178785*0.178785))*0.00503594*exp(5.07829*(i*0.490876+j*-0.83888+k*-0.235205))+2.26563*exp(-(x-6.81645)^2/(2*0.176084*0.176084))*0.000460252*exp(7.91456*(i*-0.664588+j*-0.747014+k*0.0171084))+2.2683*exp(-(x-6.37246)^2/(2*0.175877*0.175877))*1.98362e-18*exp(42.6774*(i*0.348942+j*-0.525225+k*-0.77613))+2.26856*exp(-(x-6.37238)^2/(2*0.175857*0.175857))*2.75572e-18*exp(42.3407*(i*-0.348704+j*0.525486+k*0.776061))+2.84313*exp(-(x-6.94217)^2/(2*0.140318*0.140318))*0.00156896*exp(6.48968*(i*0.424896+j*-0.296072+k*0.855456))+2.21828*exp(-(x-6.87754)^2/(2*0.179843*0.179843))*0.00497592*exp(5.09321*(i*0.485758+j*-0.841908+k*0.235011))+2.27475*exp(-(x-6.81811)^2/(2*0.175379*0.175379))*0.000463852*exp(7.90564*(i*-0.667482+j*-0.744462+k*-0.0156236)) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
bops_onesThe CONSTANT action with label bops_ones calculates the following quantities: Quantity    Type    Description  
bops_ones vector the constant value that was read from the plumed input: ONESCreate a constant vector with all elements equal to one More details SIZEthe number of ones that you would like to create=5
bopsThe MATRIX_VECTOR_PRODUCT action with label bops calculates the following quantities: Quantity    Type    Description  
bops 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=bops_kfunc,bops_ones
# --- End of included input ---

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
SPECIES	atoms	the list of atoms for which the BOPS are being calculated and the atoms that can be in the environments
SPECIESA	atoms	the list of atoms for which BOPS are being calculated
SPECIESB	atoms	the list of atoms that can be in the environments of each of the atoms for which the BOPS are being calculated

Full list of keywords

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

Keyword	Type	Default	Description
SPECIES	input	none	the list of atoms for which the BOPS are being calculated and the atoms that can be in the environments
SPECIESA	input	none	the list of atoms for which BOPS are being calculated
SPECIESB	input	none	the list of atoms that can be in the environments of each of the atoms for which the BOPS are being calculated
QUATERNIONS	compulsory	none	the label of the action that computes the quaternions that should be used
KERNELFILE_DOPS	compulsory	none	the file containing the list of kernel parameters
KERNELFILE_BOPS	compulsory	none	the second file containing the list of kernel parameters
CUTOFF	compulsory	none	cutoff for the distance matrix

References

More information about how this action can be used is available in the following articles:

E. E. Santiso, B. L. Trout, A general set of order parameters for molecular crystals. The Journal of Chemical Physics. 134 (2011)

Quantity	Type	Description
quat.w	vector	the real component of quaternion
quat.i	vector	the i component of the quaternion
quat.j	vector	the j component of the quaternion
quat.k	vector	the k component of the quaternion