Action: DISTANCE_FROM_CONTOUR

Module	contour
Description	Usage
Calculate the perpendicular distance from a Willard-Chandler dividing surface.

Details and examples

Calculate the perpendicular distance from a Willard-Chandler dividing surface.

As discussed in the documentation for the contour module, you can generate a continuous representation for the density as a function of positions for a set of $N$ atoms with positions $(x_i,y_i,z_i)$ using:

$$p(x,y,x) = \sum_{i=1}^N K\left[\frac{x-x_i}{\sigma_x},\frac{y-y_i}{\sigma_y},\frac{z-z_i}{\sigma_z} \right]$$

In this expression $\sigma_x, \sigma_y$ and $\sigma_z$ are bandwidth parameters and $K$ is one of a Gaussian kernel function.

The Willard-Chandler surface is defined a surface of constant density in the above field $p(x,y,z)$. In other words, it is a set of points, $(x',y',z')$, in your box which have:

$$p(x',y',z') = \rho$$

where $\rho$ is some target density. This action calculates the distance projected on the $x, y$ or $z$ axis between the position of some test particle and this surface of constant field density.

Examples

In this example atoms 2-100 are assumed to be concentrated along some part of the $z$ axis so that you an interface between a liquid/solid and the vapor. The quantity dc.dist1 measures the projection on $z$ of the distance between the position of atom 1 and the nearest point at which density of atoms 2-100 is equal to 0.2.

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

dcThe DISTANCE_FROM_CONTOUR action with label dc calculates the following quantities:
 Quantity   
 Type   
 Description  
dc.thickness
scalar
the distance between the two contours on the line from the reference atom
dc.dist1
scalar
the distance between the reference atom and the nearest contour
dc.dist2
scalar
the distance between the reference atom and the other contour
dc.qdist
scalar
the differentiable (squared) distance between the two contours (see above): DISTANCE_FROM_CONTOURCalculate the perpendicular distance from a Willard-Chandler dividing surface. This action has hidden defaults. More details POSITIONSthe positions of the atoms that we are calculating the contour from=2-100 ATOMThe atom whose perpendicular distance we are calculating from the contour=1 BANDWIDTHthe bandwidths for kernel density esimtation=0.5,0.5,0.5 DIRthe direction perpendicular to the contour that you are looking for=z CONTOURthe value we would like for the contour=0.2
dc: DISTANCE_FROM_CONTOURCalculate the perpendicular distance from a Willard-Chandler dividing surface. This action uses the defaults shown here. More details POSITIONSthe positions of the atoms that we are calculating the contour from=2-100 ATOMThe atom whose perpendicular distance we are calculating from the contour=1 BANDWIDTHthe bandwidths for kernel density esimtation=0.5,0.5,0.5 DIRthe direction perpendicular to the contour that you are looking for=z CONTOURthe value we would like for the contour=0.2  KERNEL the kernel function you are using=GAUSSIAN CUTOFF the cutoff at which to stop evaluating the kernel functions is set equal to sqrt(2*x)*bandwidth in each direction where x is this number=6.25 TOLERANCE this parameter is used to manage periodic boundary conditions=0.1
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=dc.dist1 FILEthe name of the file on which to output these quantities=colvar

Notice that, as discussed in the paper cited below, if you are running with periodic boundary conditions there will be two isocontours in the box where the density is equal to 0.2. If you wish to find the distance betwene atom 1 and the second closest of these two contours you would print dc.dist2. dc.thickness tells you the difference between dc.dist1 and dc.dist2 and dc.qdist is the quantity with continuous derivatives that is introduced in the paper cited below.

PLUMED also contains an experimental implementation that allows you to find the density from a isosurface in a density that is calculated using:

$$p(x,y,x) = \sum_{i=1}^N w_i K\left[\frac{x-x_i}{\sigma_x},\frac{y-y_i}{\sigma_y},\frac{z-z_i}{\sigma_z} \right]$$

where $w_i$ is a non-constant weight that is ascribed to each of the points. The following illustrates how this functionality can be used to find the distance from an isocontour in a phase field that describes the average value of the coordination number at each point in the box:

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

matThe CONTACT_MATRIX action with label mat calculates the following quantities:
 Quantity   
 Type   
 Description  
mat
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 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=2-100 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=101-1000 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.2}
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=900
# PLUMED interprets the command:
# ones: ONES SIZE=900
# 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,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,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 --- ccThe MATRIX_VECTOR_PRODUCT action with label cc calculates the following quantities:
 Quantity   
 Type   
 Description  
cc
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=mat,ones
dcThe DISTANCE_FROM_CONTOUR action with label dc calculates the following quantities:
 Quantity   
 Type   
 Description  
dc.thickness
scalar
the distance between the two contours on the line from the reference atom
dc.dist1
scalar
the distance between the reference atom and the nearest contour
dc.dist2
scalar
the distance between the reference atom and the other contour
dc.qdist
scalar
the differentiable (squared) distance between the two contours (see above): DISTANCE_FROM_CONTOURCalculate the perpendicular distance from a Willard-Chandler dividing surface. This action has hidden defaults. More details ARGthe label of the weights to use when constructing the density=cc POSITIONSthe positions of the atoms that we are calculating the contour from=2-100 ATOMThe atom whose perpendicular distance we are calculating from the contour=1 BANDWIDTHthe bandwidths for kernel density esimtation=0.5,0.5,0.5 DIRthe direction perpendicular to the contour that you are looking for=z CONTOURthe value we would like for the contour=0.2
dc: DISTANCE_FROM_CONTOURCalculate the perpendicular distance from a Willard-Chandler dividing surface. This action uses the defaults shown here. More details ARGthe label of the weights to use when constructing the density=cc POSITIONSthe positions of the atoms that we are calculating the contour from=2-100 ATOMThe atom whose perpendicular distance we are calculating from the contour=1 BANDWIDTHthe bandwidths for kernel density esimtation=0.5,0.5,0.5 DIRthe direction perpendicular to the contour that you are looking for=z CONTOURthe value we would like for the contour=0.2  KERNEL the kernel function you are using=GAUSSIAN CUTOFF the cutoff at which to stop evaluating the kernel functions is set equal to sqrt(2*x)*bandwidth in each direction where x is this number=6.25 TOLERANCE this parameter is used to manage periodic boundary conditions=0.1
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=dc.dist1 FILEthe name of the file on which to output these quantities=colvar

Notice that, although you can calculate derivatives for the first example input above, you cannot calculate derivatives if you use the ARG keyword that appears in the second example input above.

Input

The arguments and atoms 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	vector	the label of the weights to use when constructing the density
POSITIONS	atoms	the positions of the atoms that we are calculating the contour from
ATOM	atoms	The atom whose perpendicular distance we are calculating from the contour

Output components

This action calculates the values in the following table. These values can be referenced elsewhere in the input by using this Action's label followed by a dot and the name of the value required from the list below.

Name	Type	Description
dist1	scalar	the distance between the reference atom and the nearest contour
dist2	scalar	the distance between the reference atom and the other contour
qdist	scalar	the differentiable (squared) distance between the two contours (see above)
thickness	scalar	the distance between the two contours on the line from the reference atom

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 label of the weights to use when constructing the density
POSITIONS	input	none	the positions of the atoms that we are calculating the contour from
ATOM	input	none	The atom whose perpendicular distance we are calculating from the contour
BANDWIDTH	compulsory	none	the bandwidths for kernel density esimtation
KERNEL	compulsory	GAUSSIAN	the kernel function you are using
CUTOFF	compulsory	6.25	the cutoff at which to stop evaluating the kernel functions is set equal to sqrt(2x)bandwidth in each direction where x is this number
CONTOUR	compulsory	none	the value we would like for the contour
DIR	compulsory	none	the direction perpendicular to the contour that you are looking for
TOLERANCE	compulsory	0.1	this parameter is used to manage periodic boundary conditions

References

More information about how this action can be used is available in the following articles:

• J. Klug, C. Triguero, M. G. Del Pópolo, G. A. Tribello, Using Intrinsic Surfaces To Calculate the Free-Energy Change When Nanoparticles Adsorb on Membranes. The Journal of Physical Chemistry B. 122, 6417–6422 (2018)