Shortcut: PAIRENTROPIES

Module	gridtools
Description	Usage
Calculate the KL entropy from the RDF around each of the atoms
output value	type
the KL-entropy that is computed from the radial distribution function	scalar

Details and examples

Calculate the KL entropy from the RDF around each of the atoms

This shortcut can be used to calculate the descriptors of local structure that are described in the paper that is cited below. This is not the implementation that was used when that paper was written. However, the values that this implementation generates were tested against the values that the implementation that was used in the paper, which can be found here. If you want to use this implementation for a production application we would recommend further testing.

The following example illustrates how this shortcut can be used to calculate and print the descriptor for a set of 64 atoms:

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

ppThe PAIRENTROPIES action with label pp calculates the following quantities: Quantity    Type    Description  
pp grid the KL-entropy that is computed from the radial distribution function: PAIRENTROPIESCalculate the KL entropy from the RDF around each of the atoms This action is a shortcut. More details ...
   GROUPthe atoms that are being used to calculate the RDF=1-64 MAXRthe maximum distance to use for the rdf=2
   GRID_BINthe number of bins to use when computing the RDF=20 BANDWIDTHthe bandwidths for kernel density esimtation=0.13
   KERNEL the type of kernel to use for computing the histograms for the RDF=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
   DENSITYthe reference density to use when normalizing the RDF=1.0
...
# PLUMED interprets the command:
# pp: PAIRENTROPIES ...
#    GROUP=1-64 MAXR=2
#    GRID_BIN=20 BANDWIDTH=0.13
#    KERNEL=gaussian CUTOFF=6.25
#    DENSITY=1.0
# ...
# as follows (Click the red comment above to revert to the short version of the input):
pp_rdfThe CUSTOM action with label pp_rdf calculates the following quantities: Quantity    Type    Description  
pp_rdf grid the grid obtained by doing an element-wise application of an arbitrary function to the input grid: RDFCalculate the radial distribution function More details GROUPthe atoms that are being used to calculate the RDF=1-64 KERNEL the type of kernel to use for computing the histograms for the RDF=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 GRID_BINthe number of bins to use when computing the RDF=20 MAXRthe maximum distance to use for the rdf=2 DENSITYthe reference density to use when normalizing the RDF=1.0 BANDWIDTHthe bandwidths for kernel density esimtation=0.13  NO_AVERAGE output a two-dimensional grid with separate RDF functions for each of the central atoms
pp_conv_t1The CUSTOM action with label pp_conv_t1 calculates the following quantities: Quantity    Type    Description  
pp_conv_t1 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=pp_rdf,pp_rdf_x2 FUNCthe function you wish to evaluate=x*y*log(x) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
pp_conv_t2The CUSTOM action with label pp_conv_t2 calculates the following quantities: Quantity    Type    Description  
pp_conv_t2 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=pp_rdf,pp_rdf_x2 FUNCthe function you wish to evaluate=(1-x)*y PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
pp_convThe CUSTOM action with label pp_conv calculates the following quantities: Quantity    Type    Description  
pp_conv 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=pp_conv_t1,pp_conv_t2 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
pp_midpThe INTERPOLATE_GRID action with label pp_midp calculates the following quantities: Quantity    Type    Description  
pp_midp grid the function evaluated onto the interpolated grid: INTERPOLATE_GRIDInterpolate a smooth function stored on a grid onto a grid with a smaller grid spacing. More details ARGthe label for function on the grid that you would like to interpolate=pp_conv INTERPOLATION_TYPE the method to use for interpolation=linear GRID_MIN the lower bounds for the grid=0.05,0 GRID_MAX the upper bounds for the grid=1.95,63 GRID_BINthe number of bins for the grid=19,63
pp_intThe MARGINAL action with label pp_int calculates the following quantities: Quantity    Type    Description  
pp_int grid the function evaluated onto the interpolated grid: MARGINALCompute a marginal from the input multi-dimensional function More details ARGthe label for function on the grid that you would like to interpolate=pp_midp DIRthe direction along which the marginal is being computed=2
ppThe CUSTOM action with label pp calculates the following quantities: Quantity    Type    Description  
pp 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 PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO ARGthe values input to this function=pp_int FUNCthe function you wish to evaluate=-2*pi*x*1.0
# --- End of included input --- DUMPATOMSDump selected atoms on a file. More details ATOMSthe atom indices whose positions you would like to print out=1-64 ARGthe labels of vectors that should be output in the xyz file=pp FILEfile on which to output coordinates; extension is automatically detected=p_entropies.xyz

If you expand the shortcut you will notice that this shortcut creates a lot of actions. It is thus likely to be considerably slower than the implementation here. However, we hope that the implementation here is a useful reference implementation that anyone interested in using this method can use to test their implementations of it. In addition, we hope that the shortcut illustrates how the calculation of this complex descriptor can be broken down into a set of simpler calculations.

Notice also that you do not need to use the DENSITY keyword to set the density as has been done above. You can instead use an input like the one below:

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

ppThe PAIRENTROPIES action with label pp calculates the following quantities: Quantity    Type    Description  
pp grid the KL-entropy that is computed from the radial distribution function: PAIRENTROPIESCalculate the KL entropy from the RDF around each of the atoms This action is a shortcut. More details ...
   GROUPthe atoms that are being used to calculate the RDF=1-64 MAXRthe maximum distance to use for the rdf=2
   GRID_BINthe number of bins to use when computing the RDF=20 BANDWIDTHthe bandwidths for kernel density esimtation=0.13
   KERNEL the type of kernel to use for computing the histograms for the RDF=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
...
# PLUMED interprets the command:
# pp: PAIRENTROPIES ...
#    GROUP=1-64 MAXR=2
#    GRID_BIN=20 BANDWIDTH=0.13
#    KERNEL=gaussian CUTOFF=6.25
# ...
# as follows (Click the red comment above to revert to the short version of the input):
pp_rdfThe CUSTOM action with label pp_rdf calculates the following quantities: Quantity    Type    Description  
pp_rdf grid the grid obtained by doing an element-wise application of an arbitrary function to the input grid: RDFCalculate the radial distribution function More details GROUPthe atoms that are being used to calculate the RDF=1-64 KERNEL the type of kernel to use for computing the histograms for the RDF=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 GRID_BINthe number of bins to use when computing the RDF=20 MAXRthe maximum distance to use for the rdf=2 BANDWIDTHthe bandwidths for kernel density esimtation=0.13  NO_AVERAGE output a two-dimensional grid with separate RDF functions for each of the central atoms
pp_conv_t1The CUSTOM action with label pp_conv_t1 calculates the following quantities: Quantity    Type    Description  
pp_conv_t1 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=pp_rdf,pp_rdf_x2 FUNCthe function you wish to evaluate=x*y*log(x) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
pp_conv_t2The CUSTOM action with label pp_conv_t2 calculates the following quantities: Quantity    Type    Description  
pp_conv_t2 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=pp_rdf,pp_rdf_x2 FUNCthe function you wish to evaluate=(1-x)*y PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
pp_convThe CUSTOM action with label pp_conv calculates the following quantities: Quantity    Type    Description  
pp_conv 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=pp_conv_t1,pp_conv_t2 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
pp_midpThe INTERPOLATE_GRID action with label pp_midp calculates the following quantities: Quantity    Type    Description  
pp_midp grid the function evaluated onto the interpolated grid: INTERPOLATE_GRIDInterpolate a smooth function stored on a grid onto a grid with a smaller grid spacing. More details ARGthe label for function on the grid that you would like to interpolate=pp_conv INTERPOLATION_TYPE the method to use for interpolation=linear GRID_MIN the lower bounds for the grid=0.05,0 GRID_MAX the upper bounds for the grid=1.95,63 GRID_BINthe number of bins for the grid=19,63
pp_intThe MARGINAL action with label pp_int calculates the following quantities: Quantity    Type    Description  
pp_int grid the function evaluated onto the interpolated grid: MARGINALCompute a marginal from the input multi-dimensional function More details ARGthe label for function on the grid that you would like to interpolate=pp_midp DIRthe direction along which the marginal is being computed=2
ppThe CUSTOM action with label pp calculates the following quantities: Quantity    Type    Description  
pp 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 PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO ARGthe values input to this function=pp_int,pp_rdf_vol FUNCthe function you wish to evaluate=-(2*pi*x/y)*64
# --- End of included input --- DUMPATOMSDump selected atoms on a file. More details ATOMSthe atom indices whose positions you would like to print out=1-64 ARGthe labels of vectors that should be output in the xyz file=pp FILEfile on which to output coordinates; extension is automatically detected=p_entropies.xyz

As you can see, if you expand the shortcut in the above input, the density in this case is calculated by dividing the number of atoms by the volume of the box.

Input

The 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
GROUP	atoms	the atoms that are being used to calculate the RDF
GROUPA	atoms	the atoms that you would like to compute the RDF about
GROUPB	atoms	the atoms that you would like to to use when computing the RDF around the atoms that were specified with GROUPA

Full list of keywords

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

Keyword	Type	Default	Description
GROUP	input	none	the atoms that are being used to calculate the RDF
GROUPAThis keyword do not have examples	input	none	the atoms that you would like to compute the RDF about
GROUPBThis keyword do not have examples	input	none	the atoms that you would like to to use when computing the RDF around the atoms that were specified with GROUPA
GRID_BIN	compulsory	none	the number of bins to use when computing the RDF
KERNEL	compulsory	GAUSSIAN	the type of kernel to use for computing the histograms for the RDF
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
MAXR	compulsory	none	the maximum distance to use for the rdf
BANDWIDTH	compulsory	none	the bandwidths for kernel density esimtation
DENSITY	optional	not used	the reference density to use when normalizing the RDF
NO_AVERAGEThis keyword do not have examples	optional	false	output a two-dimensional grid with separate RDF functions for each of the central atoms

deprecated keywords

The keywords in the following table can still be used with this action but have been deprecated

Keyword	Description
ATOMS	You should use GROUP instead of this keyword which was used in older versions of PLUMED and is provided for back compatibility only
SIGMA	You should use BANDWIDTH instead of this keyword which was used in older versions of PLUMED and is provided for back compatibility only

References

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

P. M. Piaggi, O. Valsson, M. Parrinello, Enhancing Entropy and Enthalpy Fluctuations to Drive Crystallization in Atomistic Simulations. Physical Review Letters. 119 (2017)

Quantity	Type	Description
pp	grid	the KL-entropy that is computed from the radial distribution function