Shortcut: INENVELOPE

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 region where the density of a certain type of atom is high.
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 region where the density of a certain type of atom is high.

This collective variable can be used to determine whether atoms are within region where the density of a particular atom type is high. This is achieved by calculating the following function at the point where each atom is located $(x_i,y_i,z_i)$ :

$w_i = 1 - \sigma\left[ \sum_{i=1}^N K\left( \frac{x-x_i}{\sigma_x},\frac{y-y_i}{\sigma_y},\frac{z-z_i}{\sigma_z} \right) \right]$

Here $\sigma$ is one of the switching functions that is discussed in the documentation for the action LESS_THAN and $K$ is one of the kernel functions that is discussed in the documentation for the action BETWEEN. The sum runs over the atoms specified using the FIELD_ATOMS keyword and a $w_j$ value is calculated for each of the central atoms of the input multicolvar.

The input below shows how this action works in practise. This input calculates a density field from the positions of atoms 1-14400. A vector which has as many elements as atoms that were specified using the ATOMS keyword. The $i$ th element of this vector is calculated using the expression above with $(x_i,y_i,z_i)$ being the position of the $i$ th atom that was specified using that ATOMS keyword.

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

fiThe INENVELOPE action with label fi calculates the following quantities: Quantity    Type    Description  
fi vector vector of numbers between 0 and 1 that measure the degree to which each atom is within the volume of interest: INENVELOPEThis quantity can be used to calculate functions of the distribution of collective variables for the atoms that lie in a region where the density of a certain type of atom is high. More details ...
  ATOMSthe group of atoms that you would like to investigate=14401-74134:3 FIELD_ATOMSthe atom whose positions we are constructing a field from=1-14400
  CONTOURa switching funciton that tells PLUMED how large the density should be={RATIONAL D_0=2.0 R_0=1.0}
  KERNEL the type of kernel function to be used=gaussian BANDWIDTHthe bandwidths for kernel density esimtation=0.1,0.1,0.1
  CUTOFF the cutoff at which to stop evaluating the kernel functions is set equal to sqrt(2*x)*bandwidth in each direction where x is this number=6.25
...
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=fi FILEthe name of the file on which to output these quantities=colvar

This particular action was developed with the intention of determining whether water molecules had penetrated a membrane or not. The FIELD_ATOMS were thus the atoms of the lipid molecules that made up the membrane and the ATOMS were the oxygens of the water molecules. The vector that is output by this action can be used in all the ways that the vector that is output by the AROUND action is used. In other words, this action can be used to calculate the number of water molecules in the membrane or the average values for a symmetry function for those atoms that are within the membrane. You can also use this action to calculate the number of atoms that are not in the membrane by using an input like the one shown below:

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

fiThe INENVELOPE action with label fi calculates the following quantities: Quantity    Type    Description  
fi vector vector of numbers between 0 and 1 that measure the degree to which each atom is within the volume of interest: INENVELOPEThis quantity can be used to calculate functions of the distribution of collective variables for the atoms that lie in a region where the density of a certain type of atom is high. More details ...
  ATOMSthe group of atoms that you would like to investigate=14401-74134:3 FIELD_ATOMSthe atom whose positions we are constructing a field from=1-14400
  CONTOURa switching funciton that tells PLUMED how large the density should be={RATIONAL D_0=2.0 R_0=1.0}
  BANDWIDTHthe bandwidths for kernel density esimtation=0.1,0.1,0.1
  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=fi 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

As with AROUND there was syntax for caclulating the average values of order parameters for those atoms that are inside/outside the membrane, which can still be used with this new version of the command. However, the same calculations can be performed in later versions of the code with a better syntax. 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. The documentation for that action tells you how that old syntax worked and how you can achieve the same results using the new syntax.

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
FIELD_ATOMS	atoms	the atom whose positions we are constructing a field from

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
FIELD_ATOMS	input	none	the atom whose positions we are constructing a field from
KERNEL	compulsory	gaussian	the type of kernel function to be used
BANDWIDTH	compulsory	none	the bandwidths for kernel density esimtation
CONTOUR	compulsory	none	a switching funciton that tells PLUMED how large the density should be
CUTOFF	compulsory	6.25	the cutoff at which to stop evaluating the kernel functions is set equal to sqrt(2x)bandwidth in each direction where x is this number
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
fi	vector	vector of numbers between 0 and 1 that measure the degree to which each atom is within the volume of interest