Shortcut: BETWEEN

Module	function
Description	Usage
Use a switching function to determine how many of the input variables are within a certain range.
output value	type
a function that is one if the input falls within a particular range and zero otherwise	scalar/vector/matrix

Details and examples

Use a switching function to determine how many of the input variables are within a certain range.

This action takes one argument, $s$ and evaluates the following function:

$w(s) = \int_a^b K\left( \frac{x - s}{\sigma} \right) \textrm{d}x$

In this equation $K$ is a symmetric function that must integrate to one and that is often called a kernel function and $\sigma$ is a smearing parameter. The above function can be used to evaluate whether $s$ is between $a$ and $b$ . The advantage of using the function above is that the resulting quantity has continuous derivatives. It can thus be used when calculating a collective variable upon which a simulation bias will be applied.

The following example, shows how we can apply the function above on the instantaneous value of the distance between atom 1 and 2. The BETWEEN action here is used to determine whether the input distance is between 0.1 and 0.2 nm.

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

dThe DISTANCE action with label d calculates the following quantities: Quantity    Type    Description  
d scalar the DISTANCE between this pair of atoms: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=1,2
bThe BETWEEN action with label b calculates the following quantities: Quantity    Type    Description  
b scalar a function that is one if the input falls within a particular range and zero otherwise: BETWEENUse a switching function to determine how many of the input variables are within a certain range. More details ARGthe values input to this function=d LOWERthe lower boundary for this particular bin=0.1 UPPERthe upper boundary for this particular bin=0.2 SMEAR the ammount to smear the Gaussian for each value in the distribution=0.5

The Kernel function

The $\sigma$ values in the expressions above is calculated from the parameters $a$ , $b$ and $s$ that are provided using the LOWER, UPPER and SMEAR parameters respectively using the following function:

$\sigma = s(b-a)$

Also note that the Kernel function $K$ that is used in the first example is a Gaussian. The actual integral that is evaluated is thus:

$w(s) = \frac{1}{\sqrt{2\pi}\sigma} \int_a^b \exp\left( -\frac{(x-s)^2}{2\sigma^2}\right) \textrm{d}x$

You can achieve the same result as the first example input by using the following input:

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

dThe DISTANCE action with label d calculates the following quantities: Quantity    Type    Description  
d scalar the DISTANCE between this pair of atoms: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=1,2
bThe BETWEEN action with label b calculates the following quantities: Quantity    Type    Description  
b scalar a function that is one if the input falls within a particular range and zero otherwise: BETWEENUse a switching function to determine how many of the input variables are within a certain range. More details ARGthe values input to this function=d SWITCHThis keyword is used if you want to employ an alternative to the continuous function defined above={GAUSSIAN LOWER=0.1 UPPER=0.2 SMEAR=0.5}

The advantage of this syntax, however, is that you can replace the Gaussian kernel in the expression can be replaced by a triangular Kernel by changing the input to:

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

dThe DISTANCE action with label d calculates the following quantities: Quantity    Type    Description  
d scalar the DISTANCE between this pair of atoms: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=1,2
bThe BETWEEN action with label b calculates the following quantities: Quantity    Type    Description  
b scalar a function that is one if the input falls within a particular range and zero otherwise: BETWEENUse a switching function to determine how many of the input variables are within a certain range. More details ARGthe values input to this function=d SWITCHThis keyword is used if you want to employ an alternative to the continuous function defined above={TRIANGULAR LOWER=0.1 UPPER=0.2 SMEAR=0.5}

With this input the integral is then evaluated using:

$w(s) = \frac{1}{2\sigma} \int_a^b 1 - H\left( \frac{x-s}{\sigma} \right) \textrm{d}x$

where:

$H(x) = \begin{cases} x & \textrm{if} \quad x<1 \\ 0 & \textrm{otherwise} \end{cases}$

Non rank zero arguments

Instead of passing a single scalar in the input to the BETWEEN action you can pass a single vector as shown here:

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

dThe DISTANCE action with label d calculates the following quantities: Quantity    Type    Description  
d vector the DISTANCE for each set of specified atoms: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMS1the pair of atom that we are calculating the distance between=1,2 ATOMS2the pair of atom that we are calculating the distance between=3,4 ATOMS3the pair of atom that we are calculating the distance between=5,6 ATOMS4the pair of atom that we are calculating the distance between=7,8
bThe BETWEEN action with label b calculates the following quantities: Quantity    Type    Description  
b vector the vector obtained by doing an element-wise application of a function that is one if the input falls within a particular range and zero otherwise to the input vectors: BETWEENUse a switching function to determine how many of the input variables are within a certain range. More details ARGthe values input to this function=d SWITCHThis keyword is used if you want to employ an alternative to the continuous function defined above={GAUSSIAN LOWER=0.1 UPPER=0.2 SMEAR=0.5}

The input to the BETWEEN action here is a vector with four elements. The output from the action b is similarly a vector with four elements. In calculating the elements of this vector PLUMED applies the function described in the previous section on each of the distances in turn. The first element of b thus tells you if the distance between atoms 1 and 2 is between 0.1 and 0.2 nm, the second element tells you if the distance between atoms 3 and 4 is between 0.1 and 0.2 nm and so on.

You can use the commands in the above example input to evaluate the number of distances that are within the range of interest as follows:

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

dThe DISTANCE action with label d calculates the following quantities: Quantity    Type    Description  
d vector the DISTANCE for each set of specified atoms: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMS1the pair of atom that we are calculating the distance between=1,2 ATOMS2the pair of atom that we are calculating the distance between=3,4 ATOMS3the pair of atom that we are calculating the distance between=5,6 ATOMS4the pair of atom that we are calculating the distance between=7,8
bThe BETWEEN action with label b calculates the following quantities: Quantity    Type    Description  
b vector the vector obtained by doing an element-wise application of a function that is one if the input falls within a particular range and zero otherwise to the input vectors: BETWEENUse a switching function to determine how many of the input variables are within a certain range. More details ARGthe values input to this function=d SWITCHThis keyword is used if you want to employ an alternative to the continuous function defined above={GAUSSIAN LOWER=0.1 UPPER=0.2 SMEAR=0.5}
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=b 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

The final scalar that is output here is evaluated using the following summation:

$s = \sum_i \int_a^b \left( \frac{x - d_i}{\sigma} \right) \textrm{d}x$

where the sum over $i$ here runs over the four distances in the above expression. This scalar tells you the number of distances that are between 0.1 and 0.2.

Notice that you can do something similar with a matrix as input as shown below:

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

dThe DISTANCE_MATRIX action with label d calculates the following quantities: Quantity    Type    Description  
d matrix a matrix containing the weights for the bonds between each pair of atoms: DISTANCE_MATRIXCalculate a matrix of distances between atoms. This action has hidden defaults. More details GROUPAwhen you are calculating the adjacency matrix between two sets of atoms this keyword is used to specify the atoms along with the keyword GROUPB=1-10 GROUPBwhen you are calculating the adjacency matrix between two sets of atoms this keyword is used to specify the atoms along with the keyword GROUPA=11-20
d: DISTANCE_MATRIXCalculate a matrix of distances between atoms. This action uses the defaults shown here. More details GROUPAwhen you are calculating the adjacency matrix between two sets of atoms this keyword is used to specify the atoms along with the keyword GROUPB=1-10 GROUPBwhen you are calculating the adjacency matrix between two sets of atoms this keyword is used to specify the atoms along with the keyword GROUPA=11-20  NL_CUTOFF The cutoff for the neighbor list=0.0 NL_STRIDE The frequency with which we are updating the atoms in the neighbor list=1 CUTOFF ignore distances that have a value larger than this cutoff=-1
bThe BETWEEN action with label b calculates the following quantities: Quantity    Type    Description  
b matrix the matrix obtained by doing an element-wise application of a function that is one if the input falls within a particular range and zero otherwise to the input matrix: BETWEENUse a switching function to determine how many of the input variables are within a certain range. More details ARGthe values input to this function=d SWITCHThis keyword is used if you want to employ an alternative to the continuous function defined above={GAUSSIAN LOWER=0.1 UPPER=0.2 SMEAR=0.5}
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=b 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

This input tells PLUMED to calculate the 100 distances between the atoms in the two input groups. The final value that is printed to the colvar file then tells you how many of these distances are between 0.1 and 0.2 nm.

The MASK keyword

Consider the following input:

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

# Fixed virtual atom which serves as the probe volume's center (pos. in nm)
centerThe FIXEDATOM action with label center calculates the following quantities: Quantity    Type    Description  
center 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=2.5,2.5,2.5
center: FIXEDATOMAdd a virtual atom in a fixed position. This action uses the defaults shown here. More details ATcoordinates of the virtual atom=2.5,2.5,2.5  SET_MASS mass of the virtual atom=1 SET_CHARGE charge of the virtual atom=0
# Vector in which element i is one if atom i is in sphere of interest and zero otherwise
sphereThe INSPHERE action with label sphere calculates the following quantities: Quantity    Type    Description  
sphere vector vector of numbers between 0 and 1 that measure the degree to which each atom is within the volume of interest: 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}
# Compute the coordination numbers
adjThe CONTACT_MATRIX action with label adj calculates the following quantities: Quantity    Type    Description  
adj 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-400 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.3 D_MAX=1.0} MASKa vector that is used to used to determine which rows of the adjancency matrix to compute=sphere
onesThe ONES action with label ones calculates the following quantities: Quantity    Type    Description  
ones vector a vector of ones with the required number of elements: ONESCreate a constant vector with all elements equal to one This action is a shortcut. More details SIZEthe number of ones that you would like to create=400
# PLUMED interprets the command:
# ones: ONES SIZE=400
# as follows (Click the red comment above to revert to the short version of the input):
onesThe CONSTANT action with label ones calculates the following quantities: Quantity    Type    Description  
ones vector the constant value that was read from the plumed input: CONSTANTCreate a constant value that can be passed to actions More details NOLOG do not report all the read in scalars in the log VALUESthe numbers that are in your constant value=1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1
# --- End of included input --- coordThe MATRIX_VECTOR_PRODUCT action with label coord calculates the following quantities: Quantity    Type    Description  
coord 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=adj,ones
# Determine if coordination numbers are less than 4 or not
ltThe BETWEEN action with label lt calculates the following quantities: Quantity    Type    Description  
lt vector the vector obtained by doing an element-wise application of a function that is one if the input falls within a particular range and zero otherwise to the input vectors: BETWEENUse a switching function to determine how many of the input variables are within a certain range. More details ARGthe values input to this function=coord MASKthe label for a sparse vector/matrix that should be used to determine which elements of the vector/matrix should be computed=sphere SWITCHThis keyword is used if you want to employ an alternative to the continuous function defined above={GAUSSIAN LOWER=4.0 UPPER=6 SMEAR=0.5}
# And calculate how many atoms in the region of interst have a coordination number that is less than four
ltsphereThe CUSTOM action with label ltsphere calculates the following quantities: Quantity    Type    Description  
ltsphere 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=lt,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
cvThe SUM action with label cv calculates the following quantities: Quantity    Type    Description  
cv 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=ltsphere 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=cv FILEthe name of the file on which to output these quantities=colvar

This input calculates the total number of atoms that are within a spherical region that is centered on the point $(2.5,2.5,2.5)$ and have a coordination number that is between 4 and 6. Notice that to reduce the computational expense we use the MASK keyword in the input to CONTACT_MATRIX so PLUMED knows to not bother calculating the coordination numbers of atoms that are not within the spherical region of interest. Further notice that we have also used this MASK keyword in the input to BETWEEN to prevent PLUMED from transforming the coordination numbers that have not been calculated with the switching function to get a further speed up.

Using the MASK keyword in this way is necessary if the input argument is a vector. If the input argument is a matrix then you should never need to use the MASK keyword. PLUMED will use the sparsity pattern for the input matrix to reduce the number of transformations that are performed within BETWEEN.

Input

The arguments that serve as the input for this action are specified using one or more of the keywords in the following table.

Keyword	Type	Description
ARG	scalar/vector/matrix	the values input to this function
MASK	vector/matrix	the label for a sparse vector/matrix that should be used to determine which elements of the vector/matrix should be computed

Full list of keywords

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

Keyword	Type	Default	Description
ARG	input	none	the values input to this function
MASK	input	none	the label for a sparse vector/matrix that should be used to determine which elements of the vector/matrix should be computed
LOWER	compulsory	none	the lower boundary for this particular bin
UPPER	compulsory	none	the upper boundary for this particular bin
SMEAR	compulsory	0.5	the ammount to smear the Gaussian for each value in the distribution
SWITCH	optional	not used	This keyword is used if you want to employ an alternative to the continuous function defined above

Quantity	Type	Description
d	scalar	the DISTANCE between this pair of atoms