Skip to content

Shortcut: LOCAL_Q3

Module symfunc
Description Usage
Calculate the local degree of order around an atoms by taking the average dot product between the q_3 vector on the central atom and the q_3 vector on the atoms in the first coordination sphere. used in 0 tutorialsused in 1 eggs
output value type
the values of the local steinhardt parameters for the input atoms vector

Details and examples

Calculate the local degree of order around an atoms by taking the average dot product between the q_3 vector on the central atom and the q_3 vector on the atoms in the first coordination sphere.

The Q3 command allows one to calculate one complex vectors for each of the atoms in your system that describe the degree of order in the coordination sphere around a particular atom. The difficulty with these vectors comes when combining the order parameters from all of the individual atoms/molecules so as to get a measure of the global degree of order for the system. The simplest way of doing this - calculating the average Steinhardt parameter - can be problematic. If one is examining nucleation say only the order parameters for those atoms in the nucleus will change significantly when the nucleus forms. The order parameters for the atoms in the surrounding liquid will remain pretty much the same. As such if one models a small nucleus embedded in a very large amount of solution/melt any change in the average order parameter will be negligible. Substantial changes in the value of this average can be observed in simulations of nucleation but only because the number of atoms is relatively small.

When the average Q3 parameter is used to bias the dynamics a problems can occur. These averaged coordinates cannot distinguish between the correct, single-nucleus pathway and a concerted pathway in which all the atoms rearrange themselves into their solid-like configuration simultaneously. This second type of pathway would be impossible in reality because there is a large entropic barrier that prevents concerted processes like this from happening. However, in the finite sized systems that are commonly simulated this barrier is reduced substantially. As a result in simulations where average Steinhardt parameters are biased there are often quite dramatic system size effects

If one wants to simulate nucleation using some form on biased dynamics what is really required is an order parameter that measures:

  • Whether or not the coordination spheres around atoms are ordered
  • Whether or not the atoms that are ordered are clustered together in a crystalline nucleus

As discussed on this page a variety of variations on the Steinhardt parameters have been introduced to better describe nucleation. That page also shows how PLUMED provides you with flexibility that you can use to implement new combinations of the Steinhardt parameters. However, the inputs that you would need to write to implement common symmetry functions are rather complex so we also provide shortcuts like this one to help you compute CVs that have been widely used in the literature easily.

This particular shortcut allows you to compute the LOCAL_Q3 parameter for a particular atom, which is a number that measures the extent to which the orientation of the atoms in the first coordination sphere of an atom match the orientation of the central atom. It does this by calculating the following quantity for each of the atoms in the system:

where and are the 3rd order Steinhardt vectors calculated for atom and atom respectively and the asterisk denotes complex conjugation. The function is a switching function that acts on the distance between atoms and . The parameters of this function should be set so that it the function is equal to one when atom is in the first coordination sphere of atom and is zero otherwise. The sum in the numerator of this expression is the dot product of the Steinhardt parameters for atoms and and thus measures the degree to which the orientations of these adjacent atoms are correlated.

The following input shows how this works in practice. This input calculates the average value of the LOCAL_Q3 parameter for the 64 Lennard Jones atoms in the system under study and prints this quantity to a file called colvar.

Click on the labels of the actions for more information on what each action computes
tested on2.11
q3: Q3Calculate 3rd order Steinhardt parameters. This action is a shortcut and it has hidden defaults. More details SPECIESthe list of atoms for which the symmetry function is being calculated and the atoms that can be in the environments=1-64 D_0 The d_0 parameter of the switching function=1.3 R_0The r_0 parameter of the switching function=0.2
lq3: LOCAL_Q3Calculate the local degree of order around an atoms by taking the average dot product between the q_3 vector on the central atom and the q_3 vector on the atoms in the first coordination sphere. This action is a shortcut. More details SPECIESthe label of the action that computes the Steinhardt parameters for which you would like to calculate local steinhardt parameters=q3 SWITCHThis keyword is used if you want to employ an alternative to the continuous swiching function defined above={RATIONAL D_0=1.3 R_0=0.2}
lq3_mean: MEANCalculate the arithmetic mean of the elements in a vector More details ARGthe vector/matrix/grid whose elements shuld be added together=lq3 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=lq3.mean FILEthe name of the file on which to output these quantities=colvar

The following input calculates the distribution of LOCAL_Q3 parameters at any given time and outputs this information to a file.

Click on the labels of the actions for more information on what each action computes
tested on2.11
q3: Q3Calculate 3rd order Steinhardt parameters. This action is a shortcut and it has hidden defaults. More details SPECIESthe list of atoms for which the symmetry function is being calculated and the atoms that can be in the environments=1-64 D_0 The d_0 parameter of the switching function=1.3 R_0The r_0 parameter of the switching function=0.2
lq3: LOCAL_Q3Calculate the local degree of order around an atoms by taking the average dot product between the q_3 vector on the central atom and the q_3 vector on the atoms in the first coordination sphere. This action is a shortcut. More details SPECIESthe label of the action that computes the Steinhardt parameters for which you would like to calculate local steinhardt parameters=q3 SWITCHThis keyword is used if you want to employ an alternative to the continuous swiching function defined above={RATIONAL D_0=1.3 R_0=0.2} HISTOGRAMcalculate a discretized histogram of the distribution of values={GAUSSIAN LOWER=0.0 UPPER=1.0 NBINS=20 SMEAR=0.1}
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=lq3.* FILEthe name of the file on which to output these quantities=colvar

The following calculates the LOCAL_Q3 parameters for atoms 1-5 only. For each of these atoms comparisons of the geometry of the coordination sphere are done with those of all the other atoms in the system. The final quantity is the average and is outputted to a file

Click on the labels of the actions for more information on what each action computes
tested on2.11
q3a: Q3Calculate 3rd order Steinhardt parameters. This action is a shortcut and it has hidden defaults. More details SPECIESAthe list of atoms for which the symmetry function is being calculated=1-5 SPECIESBthe list of atoms that can be in the environments of each of the atoms for which the symmetry function is being calculated=1-64 D_0 The d_0 parameter of the switching function=1.3 R_0The r_0 parameter of the switching function=0.2
q3b: Q3Calculate 3rd order Steinhardt parameters. This action is a shortcut and it has hidden defaults. More details SPECIESAthe list of atoms for which the symmetry function is being calculated=6-64 SPECIESBthe list of atoms that can be in the environments of each of the atoms for which the symmetry function is being calculated=1-64 D_0 The d_0 parameter of the switching function=1.3 R_0The r_0 parameter of the switching function=0.2
w3: LOCAL_Q3Calculate the local degree of order around an atoms by taking the average dot product between the q_3 vector on the central atom and the q_3 vector on the atoms in the first coordination sphere. This action is a shortcut. More details SPECIESAthe label of the action that computes the Steinhardt parameters for which you would like to calculate local steinhardt parameters=q3a SPECIESBthe label of the action that computes the Steinhardt parameters that you would like to use when calculating the loal steinhardt parameters=q3b SWITCHThis keyword is used if you want to employ an alternative to the continuous swiching function defined above={RATIONAL D_0=1.3 R_0=0.2} MEAN calculate the mean of all the quantities
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=w3.* FILEthe name of the file on which to output these quantities=colvar

The MASK keyword

You can use the MASK keyword with this action in the same way that it is used with COORDINATIONNUMBER. This keyword thus expects a vector in input, which tells PLUMED the atoms for which you do not need to calculate the function. As illustrated below, this is useful if you are using functionality from the volumes module to calculate the average value of the parameter that is defined by the equation above for only those atoms that lie in a certain part of the simulation box.

Click on the labels of the actions for more information on what each action computes
tested on2.11
# Calculate the Q3 parameters for all the atoms
q3: Q3Calculate 3rd order Steinhardt parameters. This action is a shortcut. More details SPECIESthe list of atoms for which the symmetry function is being calculated and the atoms that can be in the environments=1-400 SWITCHthe switching function that it used in the construction of the contact matrix. Options for this keyword are explained in the documentation for LESS_THAN.={RATIONAL D_0=1.3 R_0=0.2 D_MAX=3.0}
# Fixed virtual atom which serves as the probe volume's center (pos. in nm)
center: FIXEDATOMAdd a virtual atom in a fixed position. This action has hidden defaults. More details ATcoordinates of the virtual atom=2.5,2.5,2.5
# Vector in which element i is one if atom i is in sphere of interest and zero otherwise
sphere: INSPHEREThis quantity can be used to calculate functions of the distribution of collective variables for the atoms that lie in a particular, user-specified part of of the cell. More details ATOMSthe group of atoms that you would like to investigate=1-400 CENTERthe atom whose vicinity we are interested in examining=center RADIUSthe switching function that tells us the extent of the sphereical region of interest. Options for this keyword are explained in the documentation for LESS_THAN.={GAUSSIAN D_0=0.5 R_0=0.01 D_MAX=0.52}
# Calculate the local_q3 parameters
lq3: LOCAL_Q3Calculate the local degree of order around an atoms by taking the average dot product between the q_3 vector on the central atom and the q_3 vector on the atoms in the first coordination sphere. This action is a shortcut. More details SPECIESthe label of the action that computes the Steinhardt parameters for which you would like to calculate local steinhardt parameters=q3 SWITCHThis keyword is used if you want to employ an alternative to the continuous swiching function defined above={RATIONAL D_0=1.3 R_0=0.2 D_MAX=3.0} MASKthe label/s for vectors that are used to determine which local steinhardt parameters to compute=sphere
# Multiply fccubic parameters numbers by sphere vector
prod: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=lq3,sphere 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
# Sum of coordination numbers for atoms that are in the sphere of interest
numer: SUMCalculate the sum of the arguments More details ARGthe vector/matrix/grid whose elements shuld be added together=prod PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
# Number of atoms that are in sphere of interest
denom: SUMCalculate the sum of the arguments More details ARGthe vector/matrix/grid whose elements shuld be added together=sphere PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
# Average coordination number for atoms in sphere of interest
av: 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
# And print out final CV to a file
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=av FILEthe name of the file on which to output these quantities=colvar STRIDE the frequency with which the quantities of interest should be output=1

This input calculates the average parameter for those atoms that are within a spherical region that is centered on the point . By including the MASK keyword in the LOCAL_Q3 line we reduce the number of values we have to compute using the expression above. However, we are still asking PLUMED to calculate the vectors for many atoms that will not contribute to the final averaged quantity. The documentation for LOCAL_AVERAGE discusses how you can create a mask vector that can act upon the Q3 action here that will ensure that you are not calculating vectors that are not required.

Output components

This action can calculate the values in the following table when the associated keyword is included in the input for the action. 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 Keyword Description
lessthan scalar LESS_THAN the number of colvars that have a value less than a threshold
morethan scalar MORE_THAN the number of colvars that have a value more than a threshold
altmin scalar ALT_MIN the minimum value of the cv
min scalar MIN the minimum colvar
max scalar MAX the maximum colvar
between scalar BETWEEN the number of colvars that have a value that lies in a particular interval
highest scalar HIGHEST the largest of the colvars
lowest scalar LOWEST the smallest of the colvars
sum scalar SUM the sum of the colvars
mean scalar MEAN the mean of the colvars

Full list of keywords

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

Keyword Type Default Description
SPECIES optional not used the label of the action that computes the Steinhardt parameters for which you would like to calculate local steinhardt parameters
SPECIESA optional not used the label of the action that computes the Steinhardt parameters for which you would like to calculate local steinhardt parameters
SPECIESB optional not used the label of the action that computes the Steinhardt parameters that you would like to use when calculating the loal steinhardt parameters
SWITCH optional not used This keyword is used if you want to employ an alternative to the continuous swiching function defined above
MASK optional not used the label/s for vectors that are used to determine which local steinhardt parameters to compute
USEGPUThis keyword do not have examples optional false run part of this calculation on the GPU

deprecated keywords

The keywords in the following table can still be used with this action but have been deprecated

Keyword Description
LOWMEM Including this keyword in the input to this action makes no difference to the calculation performed it was used in older versions of PLUMED and is provided here for back compatibility only
LESS_THAN calculate the number of variables that are less than a certain target value
MORE_THAN calculate the number of variables that are more than a certain target value
ALT_MIN calculate the minimum value
MIN calculate the minimum value
MAX calculate the maximum value
BETWEEN calculate the number of values that are within a certain range
HIGHEST this flag allows you to recover the highest of these variables
HISTOGRAM calculate a discretized histogram of the distribution of values
LOWEST this flag allows you to recover the lowest of these variables
SUM calculate the sum of all the quantities
MEAN calculate the mean of all the quantities