Shortcut: CAVITY

Module	volumes
Description	Usage
This quantity can be used to calculate functions of the distribution of collective variables for the atoms that lie in a box defined by the positions of four atoms.
output value	type
sum of values of input CVs in regin of interest	scalar

Details and examples

This quantity can be used to calculate functions of the distribution of collective variables for the atoms that lie in a box defined by the positions of four atoms.

This action can be used similarly to the way AROUND is used. Like AROUND this action returns a vector with elements that tell you whether an input atom is within a part of the box that is of particular interest or not. However, for this action the elements of this vector are calculated using:

$w(u_i,v_i,w_i) = \int_{0}^{u'} \int_{0}^{v'} \int_{0}^{w'} \textrm{d}u\textrm{d}v\textrm{d}w K\left( \frac{u - u_i}{\sigma} \right)K\left( \frac{v - v_i}{\sigma} \right)K\left( \frac{w - w_i}{\sigma} \right)$

with $u_i,v_i,w_i$ being calculated from the positon of the $i$ th atom, $(x_i,y_i,z_i)$ , by performing the following transformation.

$\left( \begin{matrix} u_i \\ v_i \\ w_i \end{matrix} \right) = R \left( \begin{matrix} x_i - x_o \\ y_i - y_o \\ z_i - z_o \end{matrix} \right)$

In this expression $R$ is a rotation matrix that is calculated by constructing a set of three orthonormal vectors from the reference positions specified by the user. The first of these unit vectors points from the first reference atom to the second. The second is then the normal to the plane containing atoms 1,2 and 3 and the the third is the unit vector orthogonal to these first two vectors. $(x_o,y_o,z_o)$ , meanwhile, specifies the position of the first reference atom.

In the first expression above $K$ is one of the kernel functions described in the documentation for the action BETWEEN and $\sigma$ is a bandwidth parameter. Furthermore, The vector connecting atom 1 to atom 4 is used to define the extent of the box in each of the $u$ , $v$ and $w$ directions. This vector connecting atom 1 to atom 4 is projected onto the three unit vectors described above and the resulting projections determine the $u'$ , $v'$ and $w'$ parameters in the above expression.

The following commands illustrate how this works in practise. We are using PLUMED here to calculate the number of atoms from the group specified using the ATOMS keyword below are in an ion channel in a protein. The extent of the channel is calculated from the positions of atoms 1, 4, 5 and 11.

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

cavThe CAVITY action with label cav calculates the following quantities: Quantity    Type    Description  
cav vector vector of numbers between 0 and 1 that measure the degree to which each atom is within the volume of interest: CAVITYThis quantity can be used to calculate functions of the distribution of collective variables for the atoms that lie in a box defined by the positions of four atoms. More details ...
  ATOMSthe group of atoms that you would like to investigate=20-500 BOXthe positions of four atoms that define spatial extent of the cavity=1,4,5,11
  SIGMAthe width of the function to be used for kernel density estimation=0.1 KERNEL the type of kernel function to be used=gaussian
...
sThe SUM action with label s calculates the following quantities: Quantity    Type    Description  
s 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=cav 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=s FILEthe name of the file on which to output these quantities=colvar

If you want to calculate the number of atoms that are not inthe protein chanel you can use the OUTSIDE flag as shown below:

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

cavThe CAVITY action with label cav calculates the following quantities: Quantity    Type    Description  
cav vector vector of numbers between 0 and 1 that measure the degree to which each atom is within the volume of interest: CAVITYThis quantity can be used to calculate functions of the distribution of collective variables for the atoms that lie in a box defined by the positions of four atoms. More details ...
  ATOMSthe group of atoms that you would like to investigate=20-500 BOXthe positions of four atoms that define spatial extent of the cavity=1,4,5,11
  SIGMAthe width of the function to be used for kernel density estimation=0.1 KERNEL the type of kernel function to be used=gaussian
  OUTSIDE calculate quantities for colvars that are on atoms outside the region of interest
...
sThe SUM action with label s calculates the following quantities: Quantity    Type    Description  
s 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=cav 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=s FILEthe name of the file on which to output these quantities=colvar

By contrast the following command tells plumed to calculate the coordination numbers (with other water molecules) for the water molecules in the protein channel described above. The average coordination number and the number of coordination numbers more than 4 is then calculated for those molecules that are in the region of interest.

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

# Calculate the atoms that are in the cavity
cavThe CAVITY action with label cav calculates the following quantities: Quantity    Type    Description  
cav vector vector of numbers between 0 and 1 that measure the degree to which each atom is within the volume of interest: CAVITYThis quantity can be used to calculate functions of the distribution of collective variables for the atoms that lie in a box defined by the positions of four atoms. More details ATOMSthe group of atoms that you would like to investigate=20-500 BOXthe positions of four atoms that define spatial extent of the cavity=1,4,5,11 SIGMAthe width of the function to be used for kernel density estimation=0.1
# Calculate the coordination numbers of all the atoms
d1The COORDINATIONNUMBER action with label d1 calculates the following quantities: Quantity    Type    Description  
d1 vector the coordination numbers of the specified atoms: COORDINATIONNUMBERCalculate the coordination numbers of atoms so that you can then calculate functions of the distribution of 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=20-500 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 R_0=0.1}
# PLUMED interprets the command:
# d1: COORDINATIONNUMBER SPECIES=20-500 SWITCH={RATIONAL R_0=0.1}
# as follows (Click the red comment above to revert to the short version of the input):
d1_grpThe GROUP action with label d1_grp calculates the following quantities: Quantity    Type    Description  
d1_grp atoms indices of atoms specified in GROUP: GROUPDefine a group of atoms so that a particular list of atoms can be referenced with a single label in definitions of CVs or virtual atoms. More details ATOMSthe numerical indexes for the set of atoms in the group=20-500
d1_matThe CONTACT_MATRIX action with label d1_mat calculates the following quantities: Quantity    Type    Description  
d1_mat 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=20-500 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.1}
d1_onesThe CONSTANT action with label d1_ones calculates the following quantities: Quantity    Type    Description  
d1_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=481
d1The MATRIX_VECTOR_PRODUCT action with label d1 calculates the following quantities: Quantity    Type    Description  
d1 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=d1_mat,d1_ones
# --- End of included input --- # Do atoms have a coordination number that is greater than 4
fd1The MORE_THAN action with label fd1 calculates the following quantities: Quantity    Type    Description  
fd1 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=d1 SWITCHThis keyword is used if you want to employ an alternative to the continuous swiching function defined above={RATIONAL R_0=4}
# Calculate the mean coordination number in the channel
nnnThe CUSTOM action with label nnn calculates the following quantities: Quantity    Type    Description  
nnn 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=cav,d1 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
numerThe SUM action with label numer calculates the following quantities: Quantity    Type    Description  
numer 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=nnn PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
denomThe SUM action with label denom calculates the following quantities: Quantity    Type    Description  
denom 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=cav PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
meanThe CUSTOM action with label mean calculates the following quantities: Quantity    Type    Description  
mean scalar an arbitrary function: 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
# Calculate the number of atoms that are in the channel and that
# have a coordination number that is greater than 4
sssThe CUSTOM action with label sss calculates the following quantities: Quantity    Type    Description  
sss 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=fd1,cav 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
mtThe SUM action with label mt calculates the following quantities: Quantity    Type    Description  
mt 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=sss PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
# And print these two quantities to a file
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=mean,mt FILEthe name of the file on which to output these quantities=colvar

As with AROUND earlier version of PLUMED used a different syntax for doing these types of calculations, which can still be used with this new version of the command. We strongly recommend using the newer syntax but if you are interested in the old syntax you can find more information in the old syntax section of the documentation for AROUND.

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 group of atoms that you would like to investigate
BOX	atoms	the positions of four atoms that define spatial extent of the cavity

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 cvs in the region of interest that are less than a certain threshold
morethan	scalar	MORE_THAN	the number of cvs in the region of interest that are more than a certain threshold
between	scalar	BETWEEN	the number of cvs in the region of interest that are within a certain range
sum	scalar	SUM	the sum of all the colvars weighted by the function that determines if we are in the region
mean	scalar	MEAN	the average values of the colvar in the region of interest

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 group of atoms that you would like to investigate
BOX	input	none	the positions of four atoms that define spatial extent of the cavity
SIGMA	compulsory	none	the width of the function to be used for kernel density estimation
KERNEL	compulsory	gaussian	the type of kernel function to be used
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.
OUTSIDE	optional	false	calculate quantities for colvars that are on atoms outside the region of interest

deprecated keywords

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

Keyword	Description
DATA	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	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
MORE_THAN	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
BETWEEN	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
SUM	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
MEAN	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

Quantity	Type	Description
cav	vector	vector of numbers between 0 and 1 that measure the degree to which each atom is within the volume of interest