Shortcut: RDF

Module	gridtools
Description	Usage
Calculate the radial distribution function
output value	type
the radial distribution function	grid

Details and examples

Calculate the radial distribution function

This shortcut can be used to evaluate the radial distribution function for a collection of atoms. The following example illustrates how it can be used to compute the average radial distribution from a trajectory:

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

rdfThe RDF action with label rdf calculates the following quantities: Quantity    Type    Description  
rdf grid the radial distribution function: RDFCalculate the radial distribution function This action is a shortcut. More details GROUPthe atoms that are being used to calculate the RDF=1-108 MAXRthe maximum distance to use for the rdf=2.5 GRID_BINthe number of bins to use when computing the RDF=25 KERNEL the type of kernel to use for computing the histograms for the RDF=DISCRETE STRIDE the frequency with which to compute the rdf and accumulate averages=1 CLEAR the frequency with which to clear the estimate of the rdf=0
# PLUMED interprets the command:
# rdf: RDF GROUP=1-108 MAXR=2.5 GRID_BIN=25 KERNEL=DISCRETE STRIDE=1 CLEAR=0
# as follows (Click the red comment above to revert to the short version of the input):
rdf_matThe DISTANCE_MATRIX action with label rdf_mat calculates the following quantities: Quantity    Type    Description  
rdf_mat matrix a matrix containing the weights for the bonds between each pair of atoms: DISTANCE_MATRIXCalculate a matrix of distances between atoms. More details CUTOFF ignore distances that have a value larger than this cutoff=2.5 GROUPthe atoms for which you would like to calculate the adjacency matrix=1-108
rdf_x2The REFERENCE_GRID action with label rdf_x2 calculates the following quantities: Quantity    Type    Description  
rdf_x2 grid the constant function on the grid that was specified in input: REFERENCE_GRIDSetup a constant grid by either reading values from a file or definining a function in input More details PERIODICare the grid directions periodic=NO FUNCthe function to compute on the grid=x*x GRID_MIN the lower bounds for the grid=0 GRID_MAX the upper bounds for the grid=2.5 GRID_BINthe number of bins for the grid=25
rdf_volThe VOLUME action with label rdf_vol calculates the following quantities: Quantity    Type    Description  
rdf_vol scalar the volume of simulation box: VOLUMECalculate the volume the simulation box. More details
rdf_wmatThe CUSTOM action with label rdf_wmat calculates the following quantities: Quantity    Type    Description  
rdf_wmat 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=rdf_mat FUNCthe function you wish to evaluate=step(2.5-x) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
rdf_okdeThe KDE action with label rdf_okde calculates the following quantities: Quantity    Type    Description  
rdf_okde 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 ARGthe label for the value that should be used to construct the histogram=rdf_mat HEIGHTSthis keyword takes the label of an action that calculates a vector of values=rdf_wmat GRID_MIN the lower bounds for the grid=0 GRID_MAX the upper bounds for the grid=2.5 GRID_BINthe number of bins for the grid=25 KERNEL the kernel function you are using=DISCRETE
rdf_kdeThe ACCUMULATE action with label rdf_kde calculates the following quantities: Quantity    Type    Description  
rdf_kde 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=rdf_okde 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=0
rdf_oneThe CONSTANT action with label rdf_one calculates the following quantities: Quantity    Type    Description  
rdf_one scalar the constant value that was read from the plumed input: CONSTANTCreate a constant value that can be passed to actions More details VALUEthe single number that you would like to store=1
rdf_normThe ACCUMULATE action with label rdf_norm calculates the following quantities: Quantity    Type    Description  
rdf_norm scalar 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=rdf_one 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=0
rdf_vrdfThe CUSTOM action with label rdf_vrdf calculates the following quantities: Quantity    Type    Description  
rdf_vrdf 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=rdf_kde,rdf_x2 FUNCthe function you wish to evaluate=x/(4*pi*y) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
rdfThe CUSTOM action with label rdf calculates the following quantities: Quantity    Type    Description  
rdf 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=rdf_vrdf,rdf_vol,rdf_norm FUNCthe function you wish to evaluate=x*y/(z*108*108)
# --- End of included input --- 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=rdf FILE the file on which to write the grid=rdf.dat

If you expand the shortcut in this input you can see how the radial distribution function is computed using KDE actions and that the average is obtained by using ACCUMULATE actions. By using expanded versions of this shortcut you can thus calculate and print the instantaneous value of the radial distribution function. Alternatively, if you use the CLEAR option in the ACCUMULATE commands you can calculate radial distribution functions from various parts of the trajectory.

The following example shows how you can use this function to calculate the radial distribution for the atoms in GROUPB around the atoms in GROUPA. Notice that the DISCRETE keyword has been removed here so we are using kernel density estimation to compute the radial distribution function.

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

rdfThe RDF action with label rdf calculates the following quantities: Quantity    Type    Description  
rdf grid the radial distribution function: RDFCalculate the radial distribution function This action is a shortcut and it has hidden defaults. More details GROUPAthe atoms that you would like to compute the RDF about=1-108 GROUPBthe atoms that you would like to to use when computing the RDF around the atoms that were specified with GROUPA=109-300 MAXRthe maximum distance to use for the rdf=2.5 GRID_BINthe number of bins to use when computing the RDF=25 BANDWIDTHthe bandwidths for kernel density esimtation=0.01 DENSITYthe reference density to use when normalizing the RDF=1 STRIDE the frequency with which to compute the rdf and accumulate averages=1 CLEAR the frequency with which to clear the estimate of the rdf=0
rdf: RDFCalculate the radial distribution function This action is a shortcut and uses the defaults shown here. More details GROUPAthe atoms that you would like to compute the RDF about=1-108 GROUPBthe atoms that you would like to to use when computing the RDF around the atoms that were specified with GROUPA=109-300 MAXRthe maximum distance to use for the rdf=2.5 GRID_BINthe number of bins to use when computing the RDF=25 BANDWIDTHthe bandwidths for kernel density esimtation=0.01 DENSITYthe reference density to use when normalizing the RDF=1 STRIDE the frequency with which to compute the rdf and accumulate averages=1 CLEAR the frequency with which to clear the estimate of the rdf=0  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:
# rdf: RDF GROUPA=1-108 GROUPB=109-300 MAXR=2.5 GRID_BIN=25 BANDWIDTH=0.01 DENSITY=1 STRIDE=1 CLEAR=0
# as follows (Click the red comment above to revert to the short version of the input):
rdf_matThe DISTANCE_MATRIX action with label rdf_mat calculates the following quantities: Quantity    Type    Description  
rdf_mat matrix a matrix containing the weights for the bonds between each pair of atoms: DISTANCE_MATRIXCalculate a matrix of distances between atoms. More details CUTOFF ignore distances that have a value larger than this cutoff=2.53536 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=1-108 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=109-300
rdf_x2The REFERENCE_GRID action with label rdf_x2 calculates the following quantities: Quantity    Type    Description  
rdf_x2 grid the constant function on the grid that was specified in input: REFERENCE_GRIDSetup a constant grid by either reading values from a file or definining a function in input More details PERIODICare the grid directions periodic=NO FUNCthe function to compute on the grid=x*x GRID_MIN the lower bounds for the grid=0 GRID_MAX the upper bounds for the grid=2.5 GRID_BINthe number of bins for the grid=25
rdf_wmatThe CUSTOM action with label rdf_wmat calculates the following quantities: Quantity    Type    Description  
rdf_wmat 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=rdf_mat FUNCthe function you wish to evaluate=step(2.53536-x) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
rdf_okdeThe KDE action with label rdf_okde calculates the following quantities: Quantity    Type    Description  
rdf_okde 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 ARGthe label for the value that should be used to construct the histogram=rdf_mat HEIGHTSthis keyword takes the label of an action that calculates a vector of values=rdf_wmat GRID_MIN the lower bounds for the grid=0 GRID_MAX the upper bounds for the grid=2.5 GRID_BINthe number of bins for the grid=25 KERNEL the kernel function you are using=GAUSSIAN BANDWIDTHthe bandwidths for kernel density esimtation=0.01
rdf_kdeThe ACCUMULATE action with label rdf_kde calculates the following quantities: Quantity    Type    Description  
rdf_kde 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=rdf_okde 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=0
rdf_oneThe CONSTANT action with label rdf_one calculates the following quantities: Quantity    Type    Description  
rdf_one scalar the constant value that was read from the plumed input: CONSTANTCreate a constant value that can be passed to actions More details VALUEthe single number that you would like to store=1
rdf_normThe ACCUMULATE action with label rdf_norm calculates the following quantities: Quantity    Type    Description  
rdf_norm scalar 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=rdf_one 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=0
rdf_vrdfThe CUSTOM action with label rdf_vrdf calculates the following quantities: Quantity    Type    Description  
rdf_vrdf 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=rdf_kde,rdf_x2 FUNCthe function you wish to evaluate=x/(4*pi*y) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
rdfThe CUSTOM action with label rdf calculates the following quantities: Quantity    Type    Description  
rdf 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=rdf_vrdf,rdf_norm FUNCthe function you wish to evaluate=x/(y*1*108)
# --- End of included input --- 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=rdf FILE the file on which to write the grid=rdf.dat

We have also used the DENSITY keyword to set the background density that is used when normalizing the radial distribution function explicity to 1 atom $/nm^{3}$ . When this keyword is not used, this density is calculated by dividing the number of atoms by the volume of the box as you can see if you expand the shortcut in the first input above.

Notice that you can also use the NO_AVERAGE keyword as shown below to calculate an independent RDF around each of the atoms:

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

rdfThe RDF action with label rdf calculates the following quantities: Quantity    Type    Description  
rdf grid the radial distribution function: RDFCalculate the radial distribution function This action is a shortcut and it has hidden defaults. More details GROUPAthe atoms that you would like to compute the RDF about=1-3 GROUPBthe atoms that you would like to to use when computing the RDF around the atoms that were specified with GROUPA=4-108 MAXRthe maximum distance to use for the rdf=2.5 GRID_BINthe number of bins to use when computing the RDF=25 BANDWIDTHthe bandwidths for kernel density esimtation=0.01 DENSITYthe reference density to use when normalizing the RDF=1 STRIDE the frequency with which to compute the rdf and accumulate averages=1 NO_AVERAGE output a two-dimensional grid with separate RDF functions for each of the central atoms CLEAR the frequency with which to clear the estimate of the rdf=0
rdf: RDFCalculate the radial distribution function This action is a shortcut and uses the defaults shown here. More details GROUPAthe atoms that you would like to compute the RDF about=1-3 GROUPBthe atoms that you would like to to use when computing the RDF around the atoms that were specified with GROUPA=4-108 MAXRthe maximum distance to use for the rdf=2.5 GRID_BINthe number of bins to use when computing the RDF=25 BANDWIDTHthe bandwidths for kernel density esimtation=0.01 DENSITYthe reference density to use when normalizing the RDF=1 STRIDE the frequency with which to compute the rdf and accumulate averages=1 NO_AVERAGE output a two-dimensional grid with separate RDF functions for each of the central atoms CLEAR the frequency with which to clear the estimate of the rdf=0  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:
# rdf: RDF GROUPA=1-3 GROUPB=4-108 MAXR=2.5 GRID_BIN=25 BANDWIDTH=0.01 DENSITY=1 STRIDE=1 NO_AVERAGE CLEAR=0
# as follows (Click the red comment above to revert to the short version of the input):
rdf_matThe DISTANCE_MATRIX action with label rdf_mat calculates the following quantities: Quantity    Type    Description  
rdf_mat matrix a matrix containing the weights for the bonds between each pair of atoms: DISTANCE_MATRIXCalculate a matrix of distances between atoms. More details CUTOFF ignore distances that have a value larger than this cutoff=2.53536 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=1-3 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=4-108
rdf_onesThe CONSTANT action with label rdf_ones calculates the following quantities: Quantity    Type    Description  
rdf_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=105
rdf_indexThe CONSTANT action with label rdf_index calculates the following quantities: Quantity    Type    Description  
rdf_index vector the constant value that was read from the plumed input: CONSTANTCreate a constant value that can be passed to actions More details VALUESthe numbers that are in your constant value=0,1,2
rdf_atnoThe OUTER_PRODUCT action with label rdf_atno calculates the following quantities: Quantity    Type    Description  
rdf_atno matrix a matrix containing the outer product of the two input vectors that was obtained using the function that was input: OUTER_PRODUCTCalculate the outer product matrix of two vectors More details ARGthe labels of the two vectors from which the outer product is being computed=rdf_index,rdf_ones
rdf_x2The REFERENCE_GRID action with label rdf_x2 calculates the following quantities: Quantity    Type    Description  
rdf_x2 grid the constant function on the grid that was specified in input: REFERENCE_GRIDSetup a constant grid by either reading values from a file or definining a function in input More details PERIODICare the grid directions periodic=NO,NO FUNCthe function to compute on the grid=x*x+0*y GRID_MIN the lower bounds for the grid=0,0 GRID_MAX the upper bounds for the grid=2.5,2 GRID_BINthe number of bins for the grid=25,2
rdf_wmatThe CUSTOM action with label rdf_wmat calculates the following quantities: Quantity    Type    Description  
rdf_wmat 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=rdf_mat FUNCthe function you wish to evaluate=step(2.53536-x) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
rdf_okdeThe KDE action with label rdf_okde calculates the following quantities: Quantity    Type    Description  
rdf_okde 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 ARGthe label for the value that should be used to construct the histogram=rdf_mat,rdf_atno HEIGHTSthis keyword takes the label of an action that calculates a vector of values=rdf_wmat GRID_MIN the lower bounds for the grid=0,0 GRID_MAX the upper bounds for the grid=2.5,2 GRID_BINthe number of bins for the grid=25,2 KERNEL the kernel function you are using=GAUSSIAN BANDWIDTHthe bandwidths for kernel density esimtation=0.01,0
rdf_kdeThe ACCUMULATE action with label rdf_kde calculates the following quantities: Quantity    Type    Description  
rdf_kde 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=rdf_okde 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=0
rdf_oneThe CONSTANT action with label rdf_one calculates the following quantities: Quantity    Type    Description  
rdf_one scalar the constant value that was read from the plumed input: CONSTANTCreate a constant value that can be passed to actions More details VALUEthe single number that you would like to store=1
rdf_normThe ACCUMULATE action with label rdf_norm calculates the following quantities: Quantity    Type    Description  
rdf_norm scalar 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=rdf_one 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=0
rdf_vrdfThe CUSTOM action with label rdf_vrdf calculates the following quantities: Quantity    Type    Description  
rdf_vrdf 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=rdf_kde,rdf_x2 FUNCthe function you wish to evaluate=x/(4*pi*y) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
rdfThe CUSTOM action with label rdf calculates the following quantities: Quantity    Type    Description  
rdf 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=rdf_vrdf,rdf_norm FUNCthe function you wish to evaluate=x/(y*1*1)
# --- End of included input --- 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=rdf FILE the file on which to write the grid=rdf.dat

This command will output a function on a $25 \times 3$ grid. The first coordinate is the distance between atoms. The second coordinate is then then an index that tells you, which central atom. In other words, the input above will output three radial distribution functions. The first of these is the radial distribution function around atom 1, the second is the radial distribution function around atom 2 and the last is the radial distribution function around atom 3.

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
GROUPA	input	none	the atoms that you would like to compute the RDF about
GROUPB	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
CLEAR	compulsory	1	the frequency with which to clear the estimate of the rdf
STRIDE	compulsory	1	the frequency with which to compute the rdf and accumulate averages
DENSITY	optional	not used	the reference density to use when normalizing the RDF
NO_AVERAGE	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

Quantity	Type	Description
rdf	grid	the radial distribution function