Shortcut: AROUND

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 particular, user-specified part of of the cell.
output value	type
sum of values of input CVs in regin of interest	scalar

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

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
ORIGIN	atoms	the atom whose vicinity we are interested in examining
ATOM	atoms	an alternative to ORIGIN

Further details and examples

This 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.

This action can be used to calculate whether each of the atoms are within a particular part of the simulation box or not as illustrated by the following example:

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

fThe FIXEDATOM action with label f calculates the following quantities: Quantity    Type    Description  
f atoms virtual atom calculated by FIXEDATOM action: FIXEDATOMAdd a virtual atom in a fixed position. This action has hidden defaults. More details ATcoordinates of the virtual atom=0,0,0
f: FIXEDATOMAdd a virtual atom in a fixed position. This action uses the defaults shown here. More details ATcoordinates of the virtual atom=0,0,0  SET_MASS mass of the virtual atom=1 SET_CHARGE charge of the virtual atom=0
aThe AROUND action with label a calculates the following quantities: Quantity    Type    Description  
a vector vector of numbers between 0 and 1 that measure the degree to which each atom is within the volume of interest: AROUNDThis 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-100 ORIGINthe atom whose vicinity we are interested in examining=f SIGMAthe width of the function to be used for kernel density estimation=0.2 XLOWER the lower boundary in x relative to the x coordinate of the atom (0 indicates use full extent of box)=-1.0 XUPPER the upper boundary in x relative to the x coordinate of the atom (0 indicates use full extent of box)=1.0 YLOWER the lower boundary in y relative to the y coordinate of the atom (0 indicates use full extent of box)=-1.0 YUPPER the upper boundary in y relative to the y coordinate of the atom (0 indicates use full extent of box)=1.0 ZLOWER the lower boundary in z relative to the z coordinate of the atom (0 indicates use full extent of box)=-1.0 ZUPPER the upper boundary in z relative to the z coordinate of the atom (0 indicates use full extent of box)=1.0
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=a FILEthe name of the file on which to output these quantities=colvar

The 100 elements of the vector a that is returned from the AROUND action in the above input are calculated using:

$w(x_i,y_i,z_i) = \int_{xl}^{xu} \int_{yl}^{yu} \int_{zl}^{zu} \textrm{d}x\textrm{d}y\textrm{d}z K\left( \frac{x - x_i}{\sigma} \right)K\left( \frac{y - y_i}{\sigma} \right)K\left( \frac{z - z_i}{\sigma} \right)$

where $K$ is one of the kernel functions described in the documentation for the function BETWEEN, $\sigma$ is a bandwidth parameter and the limits for the integrals are the values specified using the keywords XLOWER, XUPPER, YLOWER, YUPPER, YUPPER, ZLOWER and ZUPPER. $x_i$ , $y_i$ and $z_i$ are then the components of the vector that connects the $i$ th atom that was specified using the ATOMS keyword to the atom that was specified using the ORIGIN keyword. In other words, $w(x_i,y_i,z_i)$ is 1 if the atom is within a rectangular box that is centered on the atom that is specified as the origin and zero otherwise.

Calculating the number of atoms in a particular part of the box

Lets suppose that you want to calculate how many atoms are in have an $x$ coordinate that is between -1.0 and 1.0. You can do this using the following PLUMED input:

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

fThe FIXEDATOM action with label f calculates the following quantities: Quantity    Type    Description  
f atoms virtual atom calculated by FIXEDATOM action: FIXEDATOMAdd a virtual atom in a fixed position. This action has hidden defaults. More details ATcoordinates of the virtual atom=0,0,0
f: FIXEDATOMAdd a virtual atom in a fixed position. This action uses the defaults shown here. More details ATcoordinates of the virtual atom=0,0,0  SET_MASS mass of the virtual atom=1 SET_CHARGE charge of the virtual atom=0
aThe AROUND action with label a calculates the following quantities: Quantity    Type    Description  
a vector vector of numbers between 0 and 1 that measure the degree to which each atom is within the volume of interest: AROUNDThis 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-100 ORIGINthe atom whose vicinity we are interested in examining=f SIGMAthe width of the function to be used for kernel density estimation=0.2 XLOWER the lower boundary in x relative to the x coordinate of the atom (0 indicates use full extent of box)=-1.0 XUPPER the upper boundary in x relative to the x coordinate of the atom (0 indicates use full extent of box)=1.0
sThe SUM action with label s calculates the following quantities: Quantity    Type    Description  
s scalar the sum of all the elements in the input vector: SUMCalculate the sum of the arguments More details ARGthe values input to this function=a 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

In this example the components of a are calculated as:

$w(x_i,y_i,z_i) = \int_{xl}^{xu} \textrm{d}x K\left( \frac{x - x_i}{\sigma} \right)$

as the YLOWER, YUPPER, YUPPER, ZLOWER and ZUPPER flags have not been included. The SUM command then adds together all the elements of the vector a to calculate the total number of atoms in the region of the box that is of interest.

Calculating the average value for an order parameter in a particular part of the box

Suppose that you have calculated a vector of order parameters that can be assigned to a particular point in three dimensional space. The symmetry functions in the symfunc module are examples of order parameters that satisfy this criteria. You can use the AROUND command to calculate the average value of the symmetry function in a particular part of the box as follows:

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

cThe COORDINATIONNUMBER action with label c calculates the following quantities: Quantity    Type    Description  
c 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=1-100 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=1.0}
# PLUMED interprets the command:
# c: COORDINATIONNUMBER SPECIES=1-100 SWITCH={RATIONAL R_0=1.0}
# as follows (Click the red comment above to revert to the short version of the input):
c_grpThe GROUP action with label c_grp calculates the following quantities: Quantity    Type    Description  
c_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=1-100
c_matThe CONTACT_MATRIX action with label c_mat calculates the following quantities: Quantity    Type    Description  
c_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=1-100 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=1.0}
c_onesThe CONSTANT action with label c_ones calculates the following quantities: Quantity    Type    Description  
c_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=100
cThe MATRIX_VECTOR_PRODUCT action with label c calculates the following quantities: Quantity    Type    Description  
c 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=c_mat,c_ones
c_caverageThe MEAN action with label c_caverage calculates the following quantities: Quantity    Type    Description  
c_caverage scalar the mean of all the elements in the input vector: MEANCalculate the arithmetic mean of the elements in a vector More details ARGthe values input to this function=c PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
# --- End of included input --- fThe FIXEDATOM action with label f calculates the following quantities: Quantity    Type    Description  
f atoms virtual atom calculated by FIXEDATOM action: FIXEDATOMAdd a virtual atom in a fixed position. This action has hidden defaults. More details ATcoordinates of the virtual atom=0,0,0
f: FIXEDATOMAdd a virtual atom in a fixed position. This action uses the defaults shown here. More details ATcoordinates of the virtual atom=0,0,0  SET_MASS mass of the virtual atom=1 SET_CHARGE charge of the virtual atom=0
aThe AROUND action with label a calculates the following quantities: Quantity    Type    Description  
a vector vector of numbers between 0 and 1 that measure the degree to which each atom is within the volume of interest: AROUNDThis 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-100 ORIGINthe atom whose vicinity we are interested in examining=f SIGMAthe width of the function to be used for kernel density estimation=0.2 XLOWER the lower boundary in x relative to the x coordinate of the atom (0 indicates use full extent of box)=-1.0 XUPPER the upper boundary in x relative to the x coordinate of the atom (0 indicates use full extent of box)=1.0 YLOWER the lower boundary in y relative to the y coordinate of the atom (0 indicates use full extent of box)=-1.0 YUPPER the upper boundary in y relative to the y coordinate of the atom (0 indicates use full extent of box)=1.0
pThe CUSTOM action with label p calculates the following quantities: Quantity    Type    Description  
p 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=c,a 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
nThe SUM action with label n calculates the following quantities: Quantity    Type    Description  
n scalar the sum of all the elements in the input vector: SUMCalculate the sum of the arguments More details ARGthe values input to this function=p PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
dThe SUM action with label d calculates the following quantities: Quantity    Type    Description  
d scalar the sum of all the elements in the input vector: SUMCalculate the sum of the arguments More details ARGthe values input to this function=a PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
avThe CUSTOM action with label av calculates the following quantities: Quantity    Type    Description  
av scalar an arbitrary function: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=n,d 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
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

The final quantity av here is:

$\overline{s}_{\tau} = \frac{ \sum_i c_i w(x_i,y_i,z_i) }{ \sum_i w(x_i,y_i,z_i) }$

where $c_i$ are the coordination numbers and $w_i$ is:

$w(x_i,y_i,z_i) = \int_{xl}^{xu} \int_{yl}^{yu} \textrm{d}x \textrm{d}y K\left( \frac{x - x_i}{\sigma} \right) K\left( \frac{y - y_i}{\sigma} \right)$

Old syntax

In earlier versions of PLUMED the syntax for the calculation in the previous section is as follows:

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

cThe COORDINATIONNUMBER action with label c calculates the following quantities: Quantity    Type    Description  
c 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=1-100 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=1.0}
# PLUMED interprets the command:
# c: COORDINATIONNUMBER SPECIES=1-100 SWITCH={RATIONAL R_0=1.0}
# as follows (Click the red comment above to revert to the short version of the input):
c_grpThe GROUP action with label c_grp calculates the following quantities: Quantity    Type    Description  
c_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=1-100
c_matThe CONTACT_MATRIX action with label c_mat calculates the following quantities: Quantity    Type    Description  
c_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=1-100 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=1.0}
c_onesThe CONSTANT action with label c_ones calculates the following quantities: Quantity    Type    Description  
c_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=100
cThe MATRIX_VECTOR_PRODUCT action with label c calculates the following quantities: Quantity    Type    Description  
c 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=c_mat,c_ones
c_caverageThe MEAN action with label c_caverage calculates the following quantities: Quantity    Type    Description  
c_caverage scalar the mean of all the elements in the input vector: MEANCalculate the arithmetic mean of the elements in a vector More details ARGthe values input to this function=c PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
# --- End of included input --- fThe FIXEDATOM action with label f calculates the following quantities: Quantity    Type    Description  
f atoms virtual atom calculated by FIXEDATOM action: FIXEDATOMAdd a virtual atom in a fixed position. This action has hidden defaults. More details ATcoordinates of the virtual atom=0,0,0
f: FIXEDATOMAdd a virtual atom in a fixed position. This action uses the defaults shown here. More details ATcoordinates of the virtual atom=0,0,0  SET_MASS mass of the virtual atom=1 SET_CHARGE charge of the virtual atom=0
aThe AROUND action with label a calculates the following quantities: Quantity    Type    Description  
a_mean scalar the average values of the colvar in the region of interest: AROUNDThis 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. This action is a shortcut. More details DATAthe label of an action that calculates multicolvars=c ORIGINthe atom whose vicinity we are interested in examining=f SIGMAthe width of the function to be used for kernel density estimation=0.2 XLOWER the lower boundary in x relative to the x coordinate of the atom (0 indicates use full extent of box)=-1.0 XUPPER the upper boundary in x relative to the x coordinate of the atom (0 indicates use full extent of box)=1.0 YLOWER the lower boundary in y relative to the y coordinate of the atom (0 indicates use full extent of box)=-1.0 YUPPER the upper boundary in y relative to the y coordinate of the atom (0 indicates use full extent of box)=1.0 MEAN calculate the average value of the colvar inside the region of interest
# PLUMED interprets the command:
# a: AROUND DATA=c ORIGIN=f SIGMA=0.2 XLOWER=-1.0 XUPPER=1.0 YLOWER=-1.0 YUPPER=1.0 MEAN
# as follows (Click the red comment above to revert to the short version of the input):
a_grpThe GROUP action with label a_grp calculates the following quantities: Quantity    Type    Description  
a_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=c
a_prodThe CUSTOM action with label a_prod calculates the following quantities: Quantity    Type    Description  
a_prod 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=c,a 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
a_numerThe SUM action with label a_numer calculates the following quantities: Quantity    Type    Description  
a_numer scalar the sum of all the elements in the input vector: SUMCalculate the sum of the arguments More details ARGthe values input to this function=a_prod PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
a_normThe SUM action with label a_norm calculates the following quantities: Quantity    Type    Description  
a_norm scalar the sum of all the elements in the input vector: SUMCalculate the sum of the arguments More details ARGthe values input to this function=a PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
a_meanThe CUSTOM action with label a_mean calculates the following quantities: Quantity    Type    Description  
a_mean scalar an arbitrary function: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=a_numer,a_norm 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
# --- End of included input --- PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=a.mean FILEthe name of the file on which to output these quantities=colvar

This old syntax still works but we highly recommend you use the newer syntax as it is easlier to understand and more flexible. You will also notice that AROUND in the input above is a shortcut that expands to the longer input that was given in the previous section.

Syntax

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
ORIGIN	input	none	the atom whose vicinity we are interested in examining
ATOM	input	none	an alternative to ORIGIN
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
XLOWER	compulsory	0.0	the lower boundary in x relative to the x coordinate of the atom (0 indicates use full extent of box)
XUPPER	compulsory	0.0	the upper boundary in x relative to the x coordinate of the atom (0 indicates use full extent of box)
YLOWER	compulsory	0.0	the lower boundary in y relative to the y coordinate of the atom (0 indicates use full extent of box)
YUPPER	compulsory	0.0	the upper boundary in y relative to the y coordinate of the atom (0 indicates use full extent of box)
ZLOWER	compulsory	0.0	the lower boundary in z relative to the z coordinate of the atom (0 indicates use full extent of box)
ZUPPER	compulsory	0.0	the upper boundary in z relative to the z coordinate of the atom (0 indicates use full extent of box)
SERIAL	optional	false	do the calculation in serial
OUTSIDE	optional	false	calculate quantities for colvars that are on atoms outside the region of interest
DATA	optional	not used	the label of an action that calculates multicolvars
LESS_THAN	optional	not used	calcualte the number of colvars that are inside the region of interest and that are less than a certain threshold
MORE_THAN	optional	not used	calcualte the number of colvars that are inside the region of interest and that are greater that a certain threshold
BETWEEN	optional	not used	calculate the number of colvars that are inside the region of interest and that have a CV value that is between a particular set of bounds
SUM	optional	false	calculate the sum of all the quantities
MEAN	optional	false	calculate the average value of the colvar inside the region of interest

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search

Quantity	Type	Description
f	atoms	virtual atom calculated by FIXEDATOM action