Shortcut: COMBINE

Module	function
Description	Usage
Calculate a polynomial combination of a set of other variables.
output value	type
a linear compbination	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

Calculate a polynomial combination of a set of other variables.

This action takes in $N_{arg}$ arguments ($x_i$) and computes the following function of them:

\f[ C=\sum_{i=1}^{N_{arg}} c_i (x_i-a_i)^{p_i} \f]

The $c_i$, $a_i$ and $p_i$ values in this expression are provided through the COEFFICIENTS, PARAMETERS and POWERS keywords respectively. The following example illustrates how this action can be used to calculate and print the square of the distance between atom 1 and atom 2.

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.x
scalar
the x-component of the vector connecting the two atoms
d.y
scalar
the y-component of the vector connecting the two atoms
d.z
scalar
the z-component of the vector connecting the two atoms: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=1,2 COMPONENTS calculate the x, y and z components of the distance separately and store them as label
cThe COMBINE action with label c calculates the following quantities:
 Quantity   
 Type   
 Description  
c
scalar
a linear compbination: COMBINECalculate a polynomial combination of a set of other variables. More details ARGthe values input to this function=d.x,d.y,d.z COEFFICIENTS the coefficients of the arguments in your function=1,1,1 PARAMETERS the parameters of the arguments in your function=0,0,0 POWERS the powers to which you are raising each of the arguments in your function=2,2,2 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=c FILEthe name of the file on which to output these quantities=colvar

Notice that if the COEFFICIENTS keyword is absent all the $c_i$ values are set equal to 1. Furthermore, if the PARAMETERS keyword is absent all the $a_i$ values are set equal to 0. We can thus make use of these defaults and rewrite the input above as:

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.x
scalar
the x-component of the vector connecting the two atoms
d.y
scalar
the y-component of the vector connecting the two atoms
d.z
scalar
the z-component of the vector connecting the two atoms: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=1,2 COMPONENTS calculate the x, y and z components of the distance separately and store them as label
cThe COMBINE action with label c calculates the following quantities:
 Quantity   
 Type   
 Description  
c
scalar
a linear compbination: COMBINECalculate a polynomial combination of a set of other variables. More details ARGthe values input to this function=d.x,d.y,d.z POWERS the powers to which you are raising each of the arguments in your function=2,2,2 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=c FILEthe name of the file on which to output these quantities=colvar

Notice that we cannot remove the POWERS keyword here as if it is absent all the $p_i$ values are set equal to 1.

Periodic arguments

The COMBINE action is not able to predict the periodic domain for the function that is computed from the arguments automatically. The user is thus forced to specify it explicitly. Use PERIODIC=NO if the resulting variable is not periodic, and PERIODIC=A,B where A and B are the two boundaries for the periodic domain if the resulting variable is periodic. The following provides an example where the output from combine has a periodic domain. In this input we are taking the cube of a dihedral angle. The dihedral angle has a periodic domain that runs from $-\pi$ to $\pi$. The cube of this variable thus has a periodic domain that runs from $-\pi^3$ to $\pi^3$ as indicated in the following input.

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

tThe TORSION action with label t calculates the following quantities:
 Quantity   
 Type   
 Description  
t
scalar
the TORSION involving these atoms: TORSIONCalculate one or multiple torsional angles. More details ATOMSthe four atoms involved in the torsional angle=1,3,5,7
#c: COMBINE ARG=t POWERS=3 PERIODIC=-31.0062766802998,31.0062766802998
cThe COMBINE action with label c calculates the following quantities:
 Quantity   
 Type   
 Description  
c
scalar
a linear compbination: COMBINECalculate a polynomial combination of a set of other variables. More details ARGthe values input to this function=t POWERS the powers to which you are raising each of the arguments in your function=3 PERIODICif the output of your function is periodic then you should specify the periodicity of the function=-pi^3,pi^3
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=c FILEthe name of the file on which to output these quantities=colvar

Vector arguments

The two examples in the previous section demonstrate how to use the COMBINE action with scalar arguments. However, you can also pass arguments to this action that have a rank greater than zero. For example, in the example below COMBINE accepts three vectors with 4 elements in 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.x
vector
the x-component of the vector connecting the two atoms
d.y
vector
the y-component of the vector connecting the two atoms
d.z
vector
the z-component of the vector connecting the two 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 COMPONENTS calculate the x, y and z components of the distance separately and store them as label
cThe COMBINE action with label c calculates the following quantities:
 Quantity   
 Type   
 Description  
c
vector
the vector obtained by doing an element-wise application of a linear compbination to the input vectors: COMBINECalculate a polynomial combination of a set of other variables. More details ARGthe values input to this function=d.x,d.y,d.z POWERS the powers to which you are raising each of the arguments in your function=2,2,2 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=c FILEthe name of the file on which to output these quantities=colvar

The output from the COMBINE action here is also a vector with four elements. The first element of this vector is the square of the distance betwen atoms 1 and 2, the secton is the square of the distance between atoms 3 and 4 and so on.

The COMBINE action can also take a mixture of scalars and vectors in input. The following input illustrates an COMBINE action that takes vectors and scalars in input.

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

pThe CONSTANT action with label p calculates the following quantities:
 Quantity   
 Type   
 Description  
p
scalar
the constant value that was read from the plumed input: CONSTANTCreate a constant value that can be passed to actions This action has hidden defaults. More details VALUEthe single number that you would like to store=2
p: CONSTANTCreate a constant value that can be passed to actions This action uses the defaults shown here. More details VALUEthe single number that you would like to store=2  NROWS the number of rows in your input matrix=0 NCOLS the number of columns in your matrix=0
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
cThe COMBINE action with label c calculates the following quantities:
 Quantity   
 Type   
 Description  
c
vector
the vector obtained by doing an element-wise application of a linear compbination to the input vectors: COMBINECalculate a polynomial combination of a set of other variables. More details ARGthe values input to this function=d,p COEFFICIENTS the coefficients of the arguments in your function=4,-1 POWERS the powers to which you are raising each of the arguments in your function=2.5,1 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=c FILEthe name of the file on which to output these quantities=colvar

The elements of the vector that is calculated by the COMBINE action here are given by:

$$c_i = 4d_i^{2.5} - 2$$

The $d_i$ in this expression are the distances that were calculated by the DISTANCE action. The 2 comes from the scalar p that passed to the ARG action in input. As a single scalar is passed the same number is used when calculating all 4 elements of the output vector. In other words, the scalar behaves as if it is a vector with four components that all have the same value.

Lastly, notice that if you pass a single vector in input to COMBINE as in the following example, the output is still a vector:

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
cThe COMBINE action with label c calculates the following quantities:
 Quantity   
 Type   
 Description  
c
vector
the vector obtained by doing an element-wise application of a linear compbination to the input vectors: COMBINECalculate a polynomial combination of a set of other variables. More details ARGthe values input to this function=d COEFFICIENTS the coefficients of the arguments in your function=4 POWERS the powers to which you are raising each of the arguments in your function=2.5 PARAMETERS the parameters of the arguments in your function=0.5 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=c FILEthe name of the file on which to output these quantities=colvar

To calculate the 4-dimensional output by the COMBINE action here we subtract 0.5 from each of the input distances, raise the result from this subtraction to the power 2.5 and then multiply the result by 4.

If you want to calculate a linear combination of the elements of a vector using the formula at the top of the page you should use the CUSTOM action to transform all the components of the input vector. You can then add all the results from these transformations together using SUM.

Matrix arguments

You can also use matrices in the input to the COMBINE action as illustrated 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.w
matrix
a matrix containing the weights for the bonds between each pair of atoms
d.x
matrix
the projection of the bond on the x axis
d.y
matrix
the projection of the bond on the y axis
d.z
matrix
the projection of the bond on the z axis: 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,2 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=3,4,5 COMPONENTS also calculate the components of the vectors connecting the atoms in the contact matrix
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,2 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=3,4,5 COMPONENTS also calculate the components of the vectors connecting the atoms in the contact matrix  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
cThe COMBINE action with label c calculates the following quantities:
 Quantity   
 Type   
 Description  
c
matrix
the matrix obtained by doing an element-wise application of a linear compbination to the input matrix: COMBINECalculate a polynomial combination of a set of other variables. More details ARGthe values input to this function=d.x,d.y,d.z POWERS the powers to which you are raising each of the arguments in your function=2,2,2 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=c FILEthe name of the file on which to output these quantities=colvar

The input to the combine action here consists of three $2\times3$ matrices. The output is thus a $2\times3$ matrix that contains the squares of the distances between the atoms in GROUPA and the atoms in GROUPB. Notice that all the input matrices must have the same size as the elements of the final matrix are calculated by applying the formula in the first section of this input to each set of elements to the input matrices in turn.

The input to this action can be a combination of matrices and scalars. If your input arguments are an $N\times M$ matrix and a scalar the scalar is treated as if it is a $N\times M$ matrix which has all its elements equal to the input scalar. You cannot use a mixture of vectors and matrices in the input to this action.

Furthermore, if you pass a single matrix to COMBINE the output is a matrix. To calculate a linear combination of all the elements in a matrix using the formula at the top of the page you should use the CUSTOM action to transform all the components of the input vector. You can then add all the results from these transformations together using SUM.

Syntax

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