Shortcut: INCYLINDER

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

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 INCYLINDER 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: INCYLINDERThis 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 CENTERthe atom whose vicinity we are interested in examining=f DIRECTIONthe direction of the long axis of the cylinder=Z
   RADIUSa switching function that gives the extent of the cylinder in the plane perpendicular to the direction. Options for this keyword are explained in the documentation for LESS_THAN.={TANH R_0=1.5} SIGMAthe width of the function to be used for kernel density estimation=0.1
   LOWER the lower boundary on the direction parallel to the long axis of the cylinder=-1.0 UPPER the upper boundary on the direction parallel to the long axis of the cylinder=1.0
   KERNEL the type of kernel function to be used=gaussian
...
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 INCYLINDER action in the above input are calculated using:

$w(x_i,y_i,z_i) = s\left( r_{xy} \right) \int_{zl}^{zu} \textrm{d}z K\left( \frac{z - z_i}{\sigma} \right)$

where

$r_{xy} = \sqrt{ x_i^2 + y_i^2 }$

In these expressions $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 LOWER and UPPER. $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 CENTER keyword. In other words, $w(x_i,y_i,z_i)$ is 1 if the atom is within a cylinder that is centered on the $z$ axis that has an extent along the $z$ direction around the position of atom f that is determined by the values specified by LOWER and UPPER keywords. The radial extent of this cylinder is determined by the parameters of the switching function that is specified using the RADIUS keyword.

If you want to caluclate and print the number of atoms in the cylinder of interest you can use an input like the one shown below:

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 INCYLINDER 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: INCYLINDERThis 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 CENTERthe atom whose vicinity we are interested in examining=f DIRECTIONthe direction of the long axis of the cylinder=X
  RADIUSa switching function that gives the extent of the cylinder in the plane perpendicular to the direction. Options for this keyword are explained in the documentation for LESS_THAN.={TANH R_0=1.5} SIGMAthe width of the function to be used for kernel density estimation=0.1
  LOWER the lower boundary on the direction parallel to the long axis of the cylinder=-1.0 UPPER the upper boundary on the direction parallel to the long axis of the cylinder=1.0
...
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=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

Alternatively, if you want to calculate an print the number of atoms that are not in the cylinder of interest you can use the OUTSIDE flag as shown below:

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 INCYLINDER 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: INCYLINDERThis 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 CENTERthe atom whose vicinity we are interested in examining=f DIRECTIONthe direction of the long axis of the cylinder=X
  RADIUSa switching function that gives the extent of the cylinder in the plane perpendicular to the direction. Options for this keyword are explained in the documentation for LESS_THAN.={TANH R_0=1.5} SIGMAthe width of the function to be used for kernel density estimation=0.1
  LOWER the lower boundary on the direction parallel to the long axis of the cylinder=-1.0 UPPER the upper boundary on the direction parallel to the long axis of the cylinder=1.0
  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=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

Notice that now the cylinder is centered on the x axis rather than the z axis as we have changed the input for the DIRECTION keyword.

You can also calculate the average values of symmetry functions in the cylinder of interest by using inputs similar to those described the documentation for the AROUND action. In other words, you can swap out AROUND actions for an INCLYLINDER actions. Also as with AROUND, earlier versions 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
CENTER	atoms	the atom whose vicinity we are interested in examining

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
CENTER	input	none	the atom whose vicinity we are interested in examining
KERNEL	compulsory	gaussian	the type of kernel function to be used
DIRECTION	compulsory	none	the direction of the long axis of the cylinder
RADIUS	compulsory	none	a switching function that gives the extent of the cylinder in the plane perpendicular to the direction. Options for this keyword are explained in the documentation for LESS_THAN.
LOWER	compulsory	0.0	the lower boundary on the direction parallel to the long axis of the cylinder
UPPER	compulsory	0.0	the upper boundary on the direction parallel to the long axis of the cylinder
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
SIGMA	optional	not used	the width of the function to be used for kernel density estimation

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
f	atoms	virtual atom calculated by FIXEDATOM action