Shortcut: MULTICOLVARDENS

Module	gridtools
Description	Usage
Evaluate the average value of a multicolvar on a grid.
output value	type
the average value of the order parameters at each point on the grid	grid

Deprecated

This action has been deprecated and is no longer supported. Use KDE instead.

Details and examples

Evaluate the average value of a multicolvar on a grid.

As you can see if you expand the inputs below, you can achieve what this shortcut action does by using KDE and ACCUMULATE. This new syntax provides you with much greater control over what is being calculated and is also easier to understand. If you are using this shortcut we strongly encourage you to change to using this new syntax.

This shortcut allows one to construct a phase field representation for a symmetry function from an atomistic description. If each atom has an associated order parameter, $\phi_i$ then a smooth phase field function $\phi(r)$ can be computed using:

$$\phi(\mathbf{r}) = \frac{\sum_i K(\mathbf{r}-\mathbf{r}_i) \phi_i }{ \sum_i K(\mathbf{r} - \mathbf{r}_i )}$$

where $\mathbf{r}_i$ is the position of atom $i$, the sums run over all the atoms input and $K(\mathbf{r} - \mathbf{r}_i)$ is a Gaussian function. This action calculates the above function on a grid, which can then be used in the input to further actions.

Examples

The following example shows perhaps the simplest way that a phase field can be computed. The following input computes the density of atoms at each point on the grid and outputs this quantity to a file. In other words this input instructs plumed to calculate $\rho(\mathbf{r}) = \sum_i K(\mathbf{r} - \mathbf{r}_i )$

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

densThe DISTANCE action with label dens calculates the following quantities:
 Quantity   
 Type   
 Description  
dens.x
vector
the x-component of the vector connecting the two atoms
dens.y
vector
the y-component of the vector connecting the two atoms
dens.z
vector
the z-component of the vector connecting the two atoms: DISTANCESCalculate the distances between multiple piars of atoms This action is a shortcut. More details ATOMSthe pairs of atoms that you would like to calculate the angles for=1-100 ORIGINcalculate the distance of all the atoms specified using the ATOMS keyword from this point=1 COMPONENTS calculate the x, y and z components of the distance separately and store them as label
# PLUMED interprets the command:
# dens: DISTANCES ATOMS=1-100 ORIGIN=1 COMPONENTS
# as follows (Click the red comment above to revert to the short version of the input):
dens: DISTANCECalculate the distance/s between pairs of atoms. More details COMPONENTS calculate the x, y and z components of the distance separately and store them as label ATOMS1the pair of atom that we are calculating the distance between=1,1 ATOMS2the pair of atom that we are calculating the distance between=1,2 ATOMS3the pair of atom that we are calculating the distance between=1,3 ATOMS4the pair of atom that we are calculating the distance between=1,4 ATOMS5the pair of atom that we are calculating the distance between=1,5     # Action input conctinues with 95 further ATOMSn keywords, 
# --- End of included input --- kdeThe KDE action with label kde calculates the following quantities:
 Quantity   
 Type   
 Description  
kde
grid
a function on a grid that was obtained by doing a Kernel Density Estimation using the input arguments: KDECreate a histogram from the input scalar/vector/matrix using KDE This action has hidden defaults. More details ARGthe label for the value that should be used to construct the histogram=dens.x,dens.y,dens.z GRID_BINthe number of bins for the grid=100,100,100 BANDWIDTHthe bandwidths for kernel density esimtation=0.05,0.05,0.05
kde: KDECreate a histogram from the input scalar/vector/matrix using KDE This action uses the defaults shown here. More details ARGthe label for the value that should be used to construct the histogram=dens.x,dens.y,dens.z GRID_BINthe number of bins for the grid=100,100,100 BANDWIDTHthe bandwidths for kernel density esimtation=0.05,0.05,0.05  KERNEL the kernel function you are using=GAUSSIAN
gridThe ACCUMULATE action with label grid calculates the following quantities:
 Quantity   
 Type   
 Description  
grid
grid
a sum calculated from the time series of the input quantity: ACCUMULATESum the elements of this value over the course of the trajectory This action has hidden defaults. More details ARGthe label of the argument that is being added to on each timestep=kde STRIDE the frequency with which the data should be collected and added to the quantity being averaged=10
grid: ACCUMULATESum the elements of this value over the course of the trajectory This action uses the defaults shown here. More details ARGthe label of the argument that is being added to on each timestep=kde STRIDE the frequency with which the data should be collected and added to the quantity being averaged=10  CLEAR the frequency with which to clear all the accumulated data=0
DUMPGRIDOutput the function on the grid to a file with the PLUMED grid format. More details ARGthe label for the grid that you would like to output=grid STRIDE the frequency with which the grid should be output to the file=500 FILE the file on which to write the grid=density

In the above example density is added to the grid on every step. The DUMPGRID instruction thus tells PLUMED to output the average density at each point on the grid every 500 steps of simulation.

Understanding the commands in the input above provides a window into understand how MULTICOLVARDENS works. This second example computes an order parameter (in this case FCCUBIC) and constructs a phase field model for this order parameter using the equation above.

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

fccThe FCCUBIC action with label fcc calculates the following quantities:
 Quantity   
 Type   
 Description  
fcc
vector
the symmetry function for each of the specified atoms: FCCUBICMeasure how similar the environment around atoms is to that found in a FCC structure. This action is a shortcut and it has hidden defaults. More details SPECIESthe list of atoms for which the symmetry function is being calculated and the atoms that can be in the environments=1-5184 SWITCHthe switching function that it used in the construction of the contact matrix. Options for this keyword are explained in the documentation for LESS_THAN.={CUBIC D_0=1.2 D_MAX=1.5} ALPHA The alpha parameter of the angular function that is used for FCCUBIC=27
fcc: FCCUBICMeasure how similar the environment around atoms is to that found in a FCC structure. This action is a shortcut and uses the defaults shown here. More details SPECIESthe list of atoms for which the symmetry function is being calculated and the atoms that can be in the environments=1-5184 SWITCHthe switching function that it used in the construction of the contact matrix. Options for this keyword are explained in the documentation for LESS_THAN.={CUBIC D_0=1.2 D_MAX=1.5} ALPHA The alpha parameter of the angular function that is used for FCCUBIC=27  PHI The Euler rotational angle phi=0.0 THETA The Euler rotational angle theta=0.0 PSI The Euler rotational angle psi=0.0
# PLUMED interprets the command:
# fcc: FCCUBIC SPECIES=1-5184 SWITCH={CUBIC D_0=1.2 D_MAX=1.5} ALPHA=27
# as follows (Click the red comment above to revert to the short version of the input):
fcc_grpThe GROUP action with label fcc_grp calculates the following quantities:
 Quantity   
 Type   
 Description  
fcc_grp
atoms
indices of atoms specified in GROUP: GROUPDefine a group of atoms so that a particular list of atoms can be referenced with a single label in definitions of CVs or virtual atoms. More details ATOMSthe numerical indexes for the set of atoms in the group=1-5184
fcc_matThe CONTACT_MATRIX action with label fcc_mat calculates the following quantities:
 Quantity   
 Type   
 Description  
fcc_mat.w
matrix
a matrix containing the weights for the bonds between each pair of atoms
fcc_mat.x
matrix
the projection of the bond on the x axis
fcc_mat.y
matrix
the projection of the bond on the y axis
fcc_mat.z
matrix
the projection of the bond on the z axis: 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-5184 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.={CUBIC D_0=1.2 D_MAX=1.5} COMPONENTS also calculate the components of the vector connecting the atoms in the contact matrix
fcc_vfuncThe FCCUBIC_FUNC action with label fcc_vfunc calculates the following quantities:
 Quantity   
 Type   
 Description  
fcc_vfunc
matrix
the matrix obtained by doing an element-wise application of a function that measures the similarity with an fcc environment to the input matrix: FCCUBIC_FUNCMeasure how similar the environment around atoms is to that found in a FCC structure. More details ARGthe values input to this function=fcc_mat.x,fcc_mat.y,fcc_mat.z ALPHA The alpha parameter of the angular function=27
fcc_wvfuncThe CUSTOM action with label fcc_wvfunc calculates the following quantities:
 Quantity   
 Type   
 Description  
fcc_wvfunc
matrix
the matrix obtained by doing an element-wise application of an arbitrary function to the input matrix: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=fcc_vfunc,fcc_mat.w 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
fcc_onesThe CONSTANT action with label fcc_ones calculates the following quantities:
 Quantity   
 Type   
 Description  
fcc_ones
vector
the constant value that was read from the plumed input: ONESCreate a constant vector with all elements equal to one More details SIZEthe number of ones that you would like to create=5184
fccThe MATRIX_VECTOR_PRODUCT action with label fcc calculates the following quantities:
 Quantity   
 Type   
 Description  
fcc
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=fcc_wvfunc,fcc_ones
fcc_denomThe MATRIX_VECTOR_PRODUCT action with label fcc_denom calculates the following quantities:
 Quantity   
 Type   
 Description  
fcc_denom
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=fcc_mat.w,fcc_ones
fcc_nThe CUSTOM action with label fcc_n calculates the following quantities:
 Quantity   
 Type   
 Description  
fcc_n
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=fcc,fcc_denom 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
# --- End of included input --- densThe MULTICOLVARDENS action with label dens calculates the following quantities:
 Quantity   
 Type   
 Description  
dens
grid
the average value of the order parameters at each point on the grid: MULTICOLVARDENSEvaluate the average value of a multicolvar on a grid. This action is a shortcut. More details DATAthe multicolvar which you would like to calculate the density profile for=fcc ORIGINwe will use the position of this atom as the origin=1 DIRthe direction in which to calculate the density profile=xyz NBINSthe number of bins to use in each direction (alternative to GRID_NBIN)=14,14,28 BANDWIDTHthe bandwidths for kernel density esimtation=1.0,1.0,1.0 STRIDE the frequency with which to accumulate the densities=1 CLEAR the frequency with which to clear the density=1
# PLUMED interprets the command:
# dens: MULTICOLVARDENS DATA=fcc ORIGIN=1 DIR=xyz NBINS=14,14,28 BANDWIDTH=1.0,1.0,1.0 STRIDE=1 CLEAR=1
# as follows (Click the red comment above to revert to the short version of the input):
dens_distThe DISTANCE action with label dens_dist calculates the following quantities:
 Quantity   
 Type   
 Description  
dens_dist.x
vector
the x-component of the vector connecting the two atoms
dens_dist.y
vector
the y-component of the vector connecting the two atoms
dens_dist.z
vector
the z-component of the vector connecting the two atoms: DISTANCESCalculate the distances between multiple piars of atoms More details COMPONENTS calculate the x, y and z components of the distance separately and store them as label ORIGINcalculate the distance of all the atoms specified using the ATOMS keyword from this point=1 ATOMSthe pairs of atoms that you would like to calculate the angles for=fcc
dens_inumerThe KDE action with label dens_inumer calculates the following quantities:
 Quantity   
 Type   
 Description  
dens_inumer
grid
a function on a grid that was obtained by doing a Kernel Density Estimation using the input arguments: KDECreate a histogram from the input scalar/vector/matrix using KDE More details VOLUMESthis keyword take the label of an action that calculates a vector of values=fcc ARGthe label for the value that should be used to construct the histogram=dens_dist.x,dens_dist.y,dens_dist.z  GRID_BINthe number of bins for the grid=14,14,28  BANDWIDTHthe bandwidths for kernel density esimtation=1.0,1.0,1.0
dens_numerThe ACCUMULATE action with label dens_numer calculates the following quantities:
 Quantity   
 Type   
 Description  
dens_numer
grid
a sum calculated from the time series of the input quantity: ACCUMULATESum the elements of this value over the course of the trajectory More details ARGthe label of the argument that is being added to on each timestep=dens_inumer STRIDE the frequency with which the data should be collected and added to the quantity being averaged=1 CLEAR the frequency with which to clear all the accumulated data=1
dens_kdeThe KDE action with label dens_kde calculates the following quantities:
 Quantity   
 Type   
 Description  
dens_kde
grid
a function on a grid that was obtained by doing a Kernel Density Estimation using the input arguments: KDECreate a histogram from the input scalar/vector/matrix using KDE More details  BANDWIDTHthe bandwidths for kernel density esimtation=1.0,1.0,1.0 ARGthe label for the value that should be used to construct the histogram=dens_dist.x,dens_dist.y,dens_dist.z  GRID_BINthe number of bins for the grid=14,14,28
dens_denomThe ACCUMULATE action with label dens_denom calculates the following quantities:
 Quantity   
 Type   
 Description  
dens_denom
grid
a sum calculated from the time series of the input quantity: ACCUMULATESum the elements of this value over the course of the trajectory More details ARGthe label of the argument that is being added to on each timestep=dens_kde STRIDE the frequency with which the data should be collected and added to the quantity being averaged=1 CLEAR the frequency with which to clear all the accumulated data=1
densThe CUSTOM action with label dens calculates the following quantities:
 Quantity   
 Type   
 Description  
dens
grid
the grid obtained by doing an element-wise application of an arbitrary function to the input grid: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=dens_numer,dens_denom 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
# --- End of included input --- DUMPCUBEOutput a three dimensional grid using the Gaussian cube file format. More details ARGthe label for the grid that you would like to output=dens STRIDE the frequency with which the grid should be output to the file=1 FILE the file on which to write the grid=dens.cube

In this example the phase field model is computed and output to a file on every step of the simulation. Furthermore, because the CLEAR=1 keyword is set on the MULTICOLVARDENS line each Gaussian cube file output is a phase field model for a particular trajectory frame. The average value accumulated thus far is cleared at the start of every single timestep and there is no averaging over trajectory frames in this case.

If you expand the shortcuts in the input above you can see that the average phase field is calculated using CUSTOM commands. We hope that this makes it easy to understand the meaning of the phase field that is computed.

Full list of keywords

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

Keyword	Type	Default	Description
STRIDE	compulsory	1	the frequency with which to accumulate the densities
CLEAR	compulsory	0	the frequency with which to clear the density
ORIGIN	compulsory	none	we will use the position of this atom as the origin
DIR	compulsory	none	the direction in which to calculate the density profile
KERNEL	compulsory	GAUSSIAN	the kernel function you are using
BANDWIDTH	optional	not used	the bandwidths for kernel density esimtation
NBINS	optional	not used	the number of bins to use in each direction (alternative to GRID_NBIN)
GRID_MIN	optional	not used	the lower bounds for the grid (default boxlengths)
GRID_MAX	optional	not used	the upper bounds for the grid (default boxlengths)
DATA	optional	not used	the multicolvar which you would like to calculate the density profile for
ATOMS	optional	not used	if you are calculating a atomic density you use this keyword to specify the atoms that are involved
UNORMALIZED	optional	false	do not divide by the density
NORMALIZATION	optional	not used	set true/false to determine how to the data is normalised