Skip to content

Action: FIND_CONTOUR

Module contour
Description Usage
Find an isocontour in a smooth function. used in 0 tutorialsused in 0 eggs

Details and examples

Find an isocontour in a smooth function.

As discussed in the documentation for the gridtools, PLUMED contains a number of tools that allow you to calculate a function on a grid. The function on this grid might be a HISTOGRAM or it might be one of the phase fields that are discussed here. If this function has one or two input arguments it is relatively straightforward to plot the function. If by contrast the data has a three dimensions it can be difficult to visualize.

This action provides one tool for visualizing these functions. It can be used to search for a set of points on a contour where the function takes a particular values. In other words, for the function this action would find a set of points that have:

where is some constant value that is specified by the user. The points on this contour are detected using a variant on the marching squares or marching cubes algorithm. As such, and unlike FIND_CONTOUR_SURFACE or FIND_SPHERICAL_CONTOUR, the function input to this action is not required to have three arguments. You can find a contour in any function with 2 or more arguments. Furthermore, the topology of the contour will be determined by the algorithm and does not need to be specified by the user.

Examples

The input shown below was used to analyze the results from a simulation of an interface between solid and molten Lennard Jones. The interface between the solid and the liquid was set up in the plane perpendicular to the direction of the simulation cell. The input below calculates something akin to a Willard-Chandler dividing surface (see contour) between the solid phase and the liquid phase. There are two of these interfaces within the simulation box because of the periodic boundary conditions but we were able to determine that one of these two surfaces lies in a particular part of the simulation box. The input below detects the height profile of one of these two interfaces. It does so by computing a phase field average from the transformed values, , of the FCCUBIC symmetry functions for each of the atoms using the following expression.

where is the position of atom relative to the position of atom 1, is a switching function, is a Gaussian kernel function and .

The virtual atom that is computed using CENTER is located in the center of the region where the atoms are solid like and the positions of the atoms are given relative to this position when computing the phase field in the expression above. This phase field provides a continuous function that gives a measure of the average degree of solidness at each point in the simulation cell. The Willard-Chandler dividing surface is calculated by finding a a set of points at which the value of this phase field is equal to 0.5. This set of points is output to file called mycontour.dat. A new contour is found on every single step for each frame that is read in.

Click on the labels of the actions for more information on what each action computes
tested on2.11
UNITSThis command sets the internal units for the code. More details NATURAL use natural units

# This calculates the value of a set of symmetry functions for the atoms of interest
fcc: FCCUBICMeasure how similar the environment around atoms is to that found in a FCC structure. This action is a shortcut. More details ...
  SPECIESthe list of atoms for which the symmetry function is being calculated and the atoms that can be in the environments=1-96000 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=-1.5708 PSI The Euler rotational angle psi=-2.35619
...

# Transform the symmetry functions with a switching function
tfcc: LESS_THANUse a switching function to determine how many of the input variables are less than a certain cutoff. More details ARGthe values input to this function=fcc SWITCHThis keyword is used if you want to employ an alternative to the continuous swiching function defined above={SMAP R_0=0.5 A=8 B=8}

# Now compute the center of the solid like region
center: CENTERCalculate the center for a group of atoms, with arbitrary weights. This action is a shortcut. More details ATOMSthe group of atoms that appear in the definition of this center=1-96000 WEIGHTSwhat weights should be used when calculating the center=tfcc

# This determines the positions of the atoms of interest relative to the center of the solid region
dens_dist: DISTANCESCalculate the distances between multiple piars of atoms This action is a shortcut. More details ORIGINcalculate the distance of all the atoms specified using the ATOMS keyword from this point=center ATOMSthe pairs of atoms that you would like to calculate the angles for=1-96000 COMPONENTS calculate the x, y and z components of the distance separately and store them as label
# This computes the numerator in the expression above for the phase field
dens_numer: KDECreate a histogram from the input scalar/vector/matrix using KDE This action has hidden defaults. More details ...
   VOLUMESthis keyword take the label of an action that calculates a vector of values=tfcc 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=80,80,80 BANDWIDTHthe bandwidths for kernel density esimtation=1.0,1.0,1.0
...
# This computes the denominator
dens_denom: 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_dist.x,dens_dist.y,dens_dist.z
   GRID_BINthe number of bins for the grid=80,80,80 BANDWIDTHthe bandwidths for kernel density esimtation=1.0,1.0,1.0
...
# This computes the final phase field
dens: 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

# Find the isocontour
cont: FIND_CONTOURFind an isocontour in a smooth function. This action has hidden defaults. More details ARGthe labels of the grid in which the contour will be found=dens CONTOURthe value we would like to draw the contour at in the space=0.5
# Use the special method for outputting the contour to a file
DUMPCONTOURPrint the contour More details ARGthe labels of the FIND_CONTOUR action that you would like to output=cont FILE the file on which to write the grid=surface.xyz

Notice that with this method you have to use the DUMPCONTOUR action to output any contour you find to a file.

Input

The arguments 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 grid the labels of the grid in which the contour will be found

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 labels of the grid in which the contour will be found
CONTOUR compulsory none the value we would like to draw the contour at in the space
INTERPOLATION_TYPE compulsory spline the method to use for interpolation
BUFFER compulsory 0 number of buffer grid points around location where grid was found on last step
SERIAL optional false do the calculation in serial. Further information about this flag can be found here.
USEGPU optional false run this calculation on the GPU. Further information about this flag can be found here.

References

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