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

Input

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

Further 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 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 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$$

The Gaussian kernel in this 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 all the elements in the input vector: SUMCalculate the sum of the arguments More details ARGthe values input to this function=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 all the elements in the input matrix: SUMCalculate the sum of the arguments More details ARGthe values input to this function=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.

Syntax

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