MultiColvar

Oftentimes, when you do not need one of the collective variables described elsewhere in the manual, what you want instead is a function of a distribution of collective variables of a particular type. In other words, you would like to calculate a function something like this:

\[ s = \sum_i g[f(\{X\}_i)] \]

In this expression \(g\) is a function that takes in one argument and \(f\) is a function that takes a set of atomic positions as argument. The symbol \(\{X\}_i\) is used to indicate the fact that the function \(f\) is evaluated for a number of different sets of atoms. If you would just like to output the values of all the various \(f\) functions you should use the command DUMPMULTICOLVAR

This functionality is useful if you need to calculate a minimum distance or the number of coordination numbers greater than a 3.0.
To avoid duplicating the code to calculate an angle or distance many times and to make it easier to implement very complex collective variables PLUMED provides these sort of collective variables using so-called MultiColvars. MultiColvars are named in this way because a single PLUMED action can be used to calculate a number of different collective variables. For instance the DISTANCES action can be used to calculate the minimum distance, the number of distances less than a certain value, the number of distances within a certain range... A more detailed introduction to multicolvars is provided in this 10-minute video. Descriptions of the various multicolvars that are implemented in PLUMED 2 are given below:

ANGLES Calculate functions of the distribution of angles .
BOND_DIRECTIONS Calculate the vectors connecting atoms that are within cutoff defined using a switching function.
BRIDGE Calculate the number of atoms that bridge two parts of a structure
COORDINATIONNUMBER Calculate the coordination numbers of atoms so that you can then calculate functions of the distribution of coordination numbers such as the minimum, the number less than a certain quantity and so on.
DENSITY Calculate functions of the density of atoms as a function of the box. This allows one to calculate the number of atoms in half the box.
DISTANCES Calculate the distances between one or many pairs of atoms. You can then calculate functions of the distribution of distances such as the minimum, the number less than a certain quantity and so on.
ENVIRONMENTSIMILARITY Measure how similar the environment around atoms is to that found in some reference crystal structure.
FCCUBIC Measure how similar the environment around atoms is to that found in a FCC structure.
HBPAMM_SH Number of HBPAMM hydrogen bonds formed by each hydrogen atom in the system
INPLANEDISTANCES Calculate distances in the plane perpendicular to an axis
MOLECULES Calculate the vectors connecting a pair of atoms in order to represent the orientation of a molecule.
PLANES Calculate the plane perpendicular to two vectors in order to represent the orientation of a planar molecule.
Q3 Calculate 3rd order Steinhardt parameters.
Q4 Calculate fourth order Steinhardt parameters.
Q6 Calculate sixth order Steinhardt parameters.
SIMPLECUBIC Calculate whether or not the coordination spheres of atoms are arranged as they would be in a simple cubic structure.
TETRAHEDRAL Calculate the degree to which the environment about ions has a tetrahedral order.
TORSIONS Calculate whether or not a set of torsional angles are within a particular range.
XANGLES Calculate the angles between the vector connecting two atoms and the x axis.
XDISTANCES Calculate the x components of the vectors connecting one or many pairs of atoms.You can then calculate functions of the distribution of values such as the minimum, the number less than a certain quantity and so on.
XYDISTANCES Calculate distance between a pair of atoms neglecting the z-component.
XYTORSIONS Calculate the torsional angle around the x axis from the positive y direction.
XZDISTANCES Calculate distance between a pair of atoms neglecting the y-component.
XZTORSIONS Calculate the torsional angle around the x axis from the positive z direction.
YANGLES Calculate the angles between the vector connecting two atoms and the y axis.
YDISTANCES Calculate the y components of the vectors connecting one or many pairs of atoms.You can then calculate functions of the distribution of values such as the minimum, the number less than a certain quantity and so on.
YXTORSIONS Calculate the torsional angle around the y axis from the positive x direction.
YZDISTANCES Calculate distance between a pair of atoms neglecting the x-component.
YZTORSIONS Calculate the torsional angle around the y axis from the positive z direction.
ZANGLES Calculate the angles between the vector connecting two atoms and the z axis.
ZDISTANCES Calculate the z components of the vectors connecting one or many pairs of atoms.You can then calculate functions of the distribution of values such as the minimum, the number less than a certain quantity and so on.
ZXTORSIONS Calculate the torsional angle around the z axis from the positive x direction.
ZYTORSIONS Calculate the torsional angle around the z axis from the positive y direction.

To instruct PLUMED to calculate a multicolvar you give an instruction that looks something like this:

NAME <atoms involved> <parameters> <what am I calculating> TOL=0.001 LABEL=label

Oftentimes the simplest way to specify the atoms involved is to use multiple instances of the ATOMS keyword i.e. ATOMS1, ATOMS2, ATOMS3,... Separate instances of the quantity specified by NAME are then calculated for each of the sets of atoms. For example if the command issued contains the following:

Click on the labels of the actions for more information on what each action computes
tested on master
DISTANCES 
ATOMS1
the atoms involved in each of the distances you wish to calculate.
=1,2
ATOMS2
the atoms involved in each of the distances you wish to calculate.
=3,4
ATOMS3
the atoms involved in each of the distances you wish to calculate.
=5,6

The distances between atoms 1 and 2, atoms 3 and 4, and atoms 5 and 6 are calculated. Obviously, generating this sort of input is rather tedious so short cuts are also available many of the collective variables. These are described on the manual pages for the actions.

After specifying the atoms involved you sometimes need to specify some parameters that required in the calculation. For instance, for COORDINATIONNUMBER - the number of atoms in the first coordination sphere of each of the atoms in the system - you need to specify the parameters for a switchingfunction that will tell us whether or not an atom is in the first coordination sphere. Details as to how to do this are provided on the manual pages.

One of the most important keywords for multicolvars is the TOL keyword. This specifies that terms in sums that contribute less than a certain value can be ignored. In addition, it is assumed that the derivative with respect to these terms are essentially zero. By increasing the TOL parameter you can increase the speed of the calculation. Be aware, however, that this increase in speed is only possible because you are lowering the accuracy with which you are computing the quantity of interest.

Once you have specified the base quantities that are to be calculated from the atoms involved and any parameters you need to specify what function of these base quantities is to be calculated. For most multicolvars you can calculate the minimum, the number less than a target value, the number within a certain range, the number more than a target value and the average value directly.

MultiColvar functions

It is possible to use multicolvars to calculate complicated collective variables by exploiting the fact that the output from one multicolvar can be used as input to a second multicolvar. One simple way of exploiting this functionality is to filter the atoms based on the value they have for a symmetry function. For example you might want to consider only those atoms that with a COORDINATIONNUMBER higher that a certain threshold when calculating some particularly expensive symmetry function such as Q6. The following methods can thus all be used to filter the values of multicolvars in this way:

MFILTER_BETWEEN This action can be used to filter the colvar values calculated by a mcolvso that one can compute the mean and so on for only those multicolvars within a certain range.
MFILTER_LESS This action can be used to filter the distribution of colvar values in a mcolvso that one can compute the mean and so on for only those multicolvars less than a tolerance.
MFILTER_MORE This action can be used to filter the distribution of colvar values in a mcolvso that one can compute the mean and so on for only those multicolvars more than a tolerance.

An alternative way of filtering atoms is to consider only those atoms in a particular part of the simulation box. This can be done by exploiting the following methods

AROUND 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.
CAVITY This quantity can be used to calculate functions of the distribution of collective variables for the atoms that lie in a box defined by the positions of four atoms.
INCYLINDER 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.
INENVELOPE 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.
INSPHERE 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.
TETRAHEDRALPORE This quantity can be used to calculate functions of the distribution of collective variables for the atoms lie that lie in a box defined by the positions of four atoms at the corners of a tetrahedron.

The idea with these methods is that function of the form:

\[ s = \sum_i w(\{X\}_i) g[f(\{X\}_i)] \]

can be evaluated where once again \(g\) is a function with one argument and \(g\) is a function of a set of atomic positions.
The difference from the more general function described earlier is that we now have a weight \(w\) which is again a function of the atomic positions. This weight varies between zero and one and it is this weight that is calculated in the list of filtering methods and volume methods described in the lists above.

In addition to these volume and filtering methods it is also possible to calculate the local average of a quantities in the manner described in [69] using the LOCAL_AVERAGE method. Furthermore, in many cases Q6, MOLECULES and PLANES the symmetry function being evaluated is a vector. You can thus construct a variety of novel collective variables by taking dot products of vectors on adjacent atoms as described below:

GRADIENT Calculate the gradient of the average value of a multicolvar value
INTERMOLECULARTORSIONS Calculate torsion angles between vectors on adjacent molecules
LOCAL_AVERAGE Calculate averages over spherical regions centered on atoms
LOCAL_Q3 Calculate the local degree of order around an atoms by taking the average dot product between the \(q_3\) vector on the central atom and the \(q_3\) vector on the atoms in the first coordination sphere.
LOCAL_Q4 Calculate the local degree of order around an atoms by taking the average dot product between the \(q_4\) vector on the central atom and the \(q_4\) vector on the atoms in the first coordination sphere.
LOCAL_Q6 Calculate the local degree of order around an atoms by taking the average dot product between the \(q_6\) vector on the central atom and the \(q_6\) vector on the atoms in the first coordination sphere.
MCOLV_COMBINE Calculate linear combinations of multiple multicolvars
MCOLV_PRODUCT Calculate a product of multiple multicolvars
NLINKS Calculate number of pairs of atoms/molecules that are "linked"
PAMM Probabilistic analysis of molecular motifs.
POLYMER_ANGLES Calculate a function to investigate the relative orientations of polymer angles
SMAC Calculate a variant on the SMAC collective variable discussed in [50]

The final set of functions that you can apply on multicolvars are functions that transform all the colvars calculated using a multicolvar using a function. This can be useful if you are calculating some complicated derived quantity of some simpler quantity. It is also useful if you are calculating a Willard Chandler surface or a histogram. The actions that you can use to perform these transforms are:

MTRANSFORM_BETWEEN This action can be used to transform the colvar values calculated by a MultiColvar using a histogrambead
MTRANSFORM_LESS This action can be used to transform the colvar values calculated by a MultiColvar using a switchingfunction
MTRANSFORM_MORE This action can be used to transform the colvar values calculated by a MultiColvar using one minus a switchingfunction

MultiColvar bias

There may be occasions when you want add restraints on many collective variables. For instance if you are studying a cluster you might want to add a wall on the distances between each of the atoms and the center of mass of the cluster in order to prevent the cluster subliming. Alternatively, you may wish to insist that a particular set of atoms in your system all have a coordination number greater than 2. You can add these sorts of restraints by employing the following biases, which all act on the set of collective variable values calculated by a multicolvar. So for example the following set of commands:

Click on the labels of the actions for more information on what each action computes
tested on master
c1: COM 
ATOMS
the list of atoms which are involved the virtual atom's definition.
=1-20 d1: DISTANCES
GROUPA
Calculate the distances between all the atoms in GROUPA and all the atoms in GROUPB.
=c1
GROUPB
Calculate the distances between all the atoms in GROUPA and all the atoms in GROUPB.
=1-20 sr: UWALLS
DATA
compulsory keyword certain actions in plumed work by calculating a list of variables and summing over them.
=d1
AT
compulsory keyword the radius of the sphere
=2.5
KAPPA
compulsory keyword the force constant for the wall.
=0.2

creates the aforementioned set of restraints on the distances between the 20 atoms in a cluster and the center of mass of the cluster.

The list of biases of this type are as follows:

LWALLS Add LOWER_WALLS restraints on all the multicolvar values
UWALLS Add UPPER_WALLS restraints on all the multicolvar values

Notice that (in theory) you could also use this functionality to add additional terms to your force field or to implement your force field.

Extracting all the base quantities

There may be occasions where you want to get information on all the individual colvar values that you have calculated. For example you might want to output the values of all the coordination numbers calculated by a COORDINATIONNUMBER action. You can thus use the following command to extract this sort of information, DUMPMULTICOLVAR.