| Module |
gridtools |
| Description |
Usage |
| Output a three dimensional grid using the Gaussian cube file format. |
  |
| This action outputs data to a file. You can read more about how PLUMED manages output files here |
|
Details and examples
Output a three dimensional grid using the Gaussian cube file format.
Suppose you have calculated the value of a function on a three dimensional grid.
This function might be a HISTOGRAM, KDE or it might be a free energy energy surface
that was calculated from this histogram by using CONVERT_TO_FES. Alternatively,
your function might be a phase-field that was calculated using MULTICOLVARDENS or a series of CUSTOM functions
that had been applied on the input grid.
Whatever the function is, however, you obviously cannot show it using a typical contour
plotting program such as gnuplot as you have three input variables.
Tools like VMD have nice features for plotting these types of three dimensional functions
but typically you are required to use a Gaussian cube file format to input the data. This
action thus allows you to output a function evaluated on a grid to a Gaussian cube file format.
Examples
The input below can be used to post process a trajectory. A histogram as a function of the distance
between atoms 1 and 2, the distance between atom 1 and 3 and the angle between the vector connecting atoms 1 and
2 and 1 and 3 is computed using kernel density estimation. Once all the data contained in the trajectory has been read in and
all the kernels have been added the resulting histogram is output to a file called histoA1.cube. This file has the
Gaussian cube file format. The histogram can thus be visualized using tools such as VMD.
x1The DISTANCE action with label x1 calculates the following quantities:| Quantity | Type | Description |
| x1 | scalar | the DISTANCE between this pair of atoms |
: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=1,2
x2The DISTANCE action with label x2 calculates the following quantities:| Quantity | Type | Description |
| x2 | scalar | the DISTANCE between this pair of atoms |
: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=1,3
x3The ANGLE action with label x3 calculates the following quantities:| Quantity | Type | Description |
| x3 | scalar | the ANGLE involving these atoms |
: ANGLECalculate one or multiple angle/s. More details ATOMSthe list of atoms involved in this collective variable (either 3 or 4 atoms)=1,2,3
hA1The HISTOGRAM action with label hA1 calculates the following quantities:| Quantity | Type | Description |
| hA1 | grid | the estimate of the histogram as a function of the argument that was obtained |
: HISTOGRAMAccumulate the average probability density along a few CVs from a trajectory. This action is a shortcut and it has hidden defaults. More details ARGthe quantities that are being used to construct the histogram=x1,x2,x3 GRID_MIN the lower bounds for the grid=0.0,0.0,0.0 GRID_MAX the upper bounds for the grid=3.0,3.0,3.0 GRID_BINthe number of bins for the grid=10,10,10 BANDWIDTHthe bandwidths for kernel density esimtation=1.0,1.0,1.0
hA1: HISTOGRAMAccumulate the average probability density along a few CVs from a trajectory. This action is a shortcut and uses the defaults shown here. More details ARGthe quantities that are being used to construct the histogram=x1,x2,x3 GRID_MIN the lower bounds for the grid=0.0,0.0,0.0 GRID_MAX the upper bounds for the grid=3.0,3.0,3.0 GRID_BINthe number of bins for the grid=10,10,10 BANDWIDTHthe bandwidths for kernel density esimtation=1.0,1.0,1.0 NORMALIZATION This controls how the data is normalized it can be set equal to true, false or ndata=ndata STRIDE the frequency with which to store data for averaging=1 CLEAR the frequency with whihc to clear the data that is being averaged=0
# hA1: HISTOGRAM ARG=x1,x2,x3 GRID_MIN=0.0,0.0,0.0 GRID_MAX=3.0,3.0,3.0 GRID_BIN=10,10,10 BANDWIDTH=1.0,1.0,1.0
hA1_weightThe CONSTANT action with label hA1_weight calculates the following quantities:| Quantity | Type | Description |
| hA1_weight | scalar | 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=1
hA1_kdeThe KDE action with label hA1_kde calculates the following quantities:| Quantity | Type | Description |
| hA1_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 ARGthe label for the value that should be used to construct the histogram=x1,x2,x3 BANDWIDTHthe bandwidths for kernel density esimtation=1.0,1.0,1.0 GRID_BINthe number of bins for the grid=10,10,10 GRID_MAX the upper bounds for the grid=3.0,3.0,3.0 GRID_MIN the lower bounds for the grid=0.0,0.0,0.0
hA1_kdepThe CUSTOM action with label hA1_kdep calculates the following quantities:| Quantity | Type | Description |
| hA1_kdep | 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=hA1_kde,hA1_weight 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
hA1_uThe ACCUMULATE action with label hA1_u calculates the following quantities:| Quantity | Type | Description |
| hA1_u | 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=hA1_kdep 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
hA1_nsumThe ACCUMULATE action with label hA1_nsum calculates the following quantities:| Quantity | Type | Description |
| hA1_nsum | 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=hA1_weight 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
hA1The CUSTOM action with label hA1 calculates the following quantities:| Quantity | Type | Description |
| hA1 | 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=hA1_u,hA1_nsum 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=hA1 FILE the file on which to write the grid=histoA1.cube
In the input above the cube file is output at the end of the simulation or when the full trajectory has been read.
If you want to output the cube file every 1000 steps you would use an input like the one shown below:
x1The DISTANCE action with label x1 calculates the following quantities:| Quantity | Type | Description |
| x1 | scalar | the DISTANCE between this pair of atoms |
: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=1,2
x2The DISTANCE action with label x2 calculates the following quantities:| Quantity | Type | Description |
| x2 | scalar | the DISTANCE between this pair of atoms |
: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=1,3
x3The ANGLE action with label x3 calculates the following quantities:| Quantity | Type | Description |
| x3 | scalar | the ANGLE involving these atoms |
: ANGLECalculate one or multiple angle/s. More details ATOMSthe list of atoms involved in this collective variable (either 3 or 4 atoms)=1,2,3
hA1The HISTOGRAM action with label hA1 calculates the following quantities:| Quantity | Type | Description |
| hA1 | grid | the estimate of the histogram as a function of the argument that was obtained |
: HISTOGRAMAccumulate the average probability density along a few CVs from a trajectory. This action is a shortcut and it has hidden defaults. More details ARGthe quantities that are being used to construct the histogram=x1,x2,x3 GRID_MIN the lower bounds for the grid=0.0,0.0,0.0 GRID_MAX the upper bounds for the grid=3.0,3.0,3.0 GRID_BINthe number of bins for the grid=10,10,10 BANDWIDTHthe bandwidths for kernel density esimtation=1.0,1.0,1.0
hA1: HISTOGRAMAccumulate the average probability density along a few CVs from a trajectory. This action is a shortcut and uses the defaults shown here. More details ARGthe quantities that are being used to construct the histogram=x1,x2,x3 GRID_MIN the lower bounds for the grid=0.0,0.0,0.0 GRID_MAX the upper bounds for the grid=3.0,3.0,3.0 GRID_BINthe number of bins for the grid=10,10,10 BANDWIDTHthe bandwidths for kernel density esimtation=1.0,1.0,1.0 NORMALIZATION This controls how the data is normalized it can be set equal to true, false or ndata=ndata STRIDE the frequency with which to store data for averaging=1 CLEAR the frequency with whihc to clear the data that is being averaged=0
# hA1: HISTOGRAM ARG=x1,x2,x3 GRID_MIN=0.0,0.0,0.0 GRID_MAX=3.0,3.0,3.0 GRID_BIN=10,10,10 BANDWIDTH=1.0,1.0,1.0
hA1_weightThe CONSTANT action with label hA1_weight calculates the following quantities:| Quantity | Type | Description |
| hA1_weight | scalar | 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=1
hA1_kdeThe KDE action with label hA1_kde calculates the following quantities:| Quantity | Type | Description |
| hA1_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 ARGthe label for the value that should be used to construct the histogram=x1,x2,x3 BANDWIDTHthe bandwidths for kernel density esimtation=1.0,1.0,1.0 GRID_BINthe number of bins for the grid=10,10,10 GRID_MAX the upper bounds for the grid=3.0,3.0,3.0 GRID_MIN the lower bounds for the grid=0.0,0.0,0.0
hA1_kdepThe CUSTOM action with label hA1_kdep calculates the following quantities:| Quantity | Type | Description |
| hA1_kdep | 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=hA1_kde,hA1_weight 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
hA1_uThe ACCUMULATE action with label hA1_u calculates the following quantities:| Quantity | Type | Description |
| hA1_u | 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=hA1_kdep 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
hA1_nsumThe ACCUMULATE action with label hA1_nsum calculates the following quantities:| Quantity | Type | Description |
| hA1_nsum | 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=hA1_weight 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
hA1The CUSTOM action with label hA1 calculates the following quantities:| Quantity | Type | Description |
| hA1 | 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=hA1_u,hA1_nsum 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=hA1 FILE the file on which to write the grid=histoA1.cube STRIDE the frequency with which the grid should be output to the file=1000
The default option is used here and thus multiple cube files are output. The cube file that is obtained from the
first 1000 steps of the trajectory will be named analysis.0.histoA1.cube, the one from the second 1000 steps of
trajectory is named analysis.1.histoA1.cube and so on until the final histogram output, which will called
histoA1.cube. If you would like to output the data from all these cube files in a single file you use the
PRINT_ONE_FILE flag as shown below:
x1The DISTANCE action with label x1 calculates the following quantities:| Quantity | Type | Description |
| x1 | scalar | the DISTANCE between this pair of atoms |
: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=1,2
x2The DISTANCE action with label x2 calculates the following quantities:| Quantity | Type | Description |
| x2 | scalar | the DISTANCE between this pair of atoms |
: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=1,3
x3The ANGLE action with label x3 calculates the following quantities:| Quantity | Type | Description |
| x3 | scalar | the ANGLE involving these atoms |
: ANGLECalculate one or multiple angle/s. More details ATOMSthe list of atoms involved in this collective variable (either 3 or 4 atoms)=1,2,3
hA1The HISTOGRAM action with label hA1 calculates the following quantities:| Quantity | Type | Description |
| hA1 | grid | the estimate of the histogram as a function of the argument that was obtained |
: HISTOGRAMAccumulate the average probability density along a few CVs from a trajectory. This action is a shortcut and it has hidden defaults. More details ARGthe quantities that are being used to construct the histogram=x1,x2,x3 GRID_MIN the lower bounds for the grid=0.0,0.0,0.0 GRID_MAX the upper bounds for the grid=3.0,3.0,3.0 GRID_BINthe number of bins for the grid=10,10,10 BANDWIDTHthe bandwidths for kernel density esimtation=1.0,1.0,1.0
hA1: HISTOGRAMAccumulate the average probability density along a few CVs from a trajectory. This action is a shortcut and uses the defaults shown here. More details ARGthe quantities that are being used to construct the histogram=x1,x2,x3 GRID_MIN the lower bounds for the grid=0.0,0.0,0.0 GRID_MAX the upper bounds for the grid=3.0,3.0,3.0 GRID_BINthe number of bins for the grid=10,10,10 BANDWIDTHthe bandwidths for kernel density esimtation=1.0,1.0,1.0 NORMALIZATION This controls how the data is normalized it can be set equal to true, false or ndata=ndata STRIDE the frequency with which to store data for averaging=1 CLEAR the frequency with whihc to clear the data that is being averaged=0
# hA1: HISTOGRAM ARG=x1,x2,x3 GRID_MIN=0.0,0.0,0.0 GRID_MAX=3.0,3.0,3.0 GRID_BIN=10,10,10 BANDWIDTH=1.0,1.0,1.0
hA1_weightThe CONSTANT action with label hA1_weight calculates the following quantities:| Quantity | Type | Description |
| hA1_weight | scalar | 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=1
hA1_kdeThe KDE action with label hA1_kde calculates the following quantities:| Quantity | Type | Description |
| hA1_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 ARGthe label for the value that should be used to construct the histogram=x1,x2,x3 BANDWIDTHthe bandwidths for kernel density esimtation=1.0,1.0,1.0 GRID_BINthe number of bins for the grid=10,10,10 GRID_MAX the upper bounds for the grid=3.0,3.0,3.0 GRID_MIN the lower bounds for the grid=0.0,0.0,0.0
hA1_kdepThe CUSTOM action with label hA1_kdep calculates the following quantities:| Quantity | Type | Description |
| hA1_kdep | 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=hA1_kde,hA1_weight 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
hA1_uThe ACCUMULATE action with label hA1_u calculates the following quantities:| Quantity | Type | Description |
| hA1_u | 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=hA1_kdep 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
hA1_nsumThe ACCUMULATE action with label hA1_nsum calculates the following quantities:| Quantity | Type | Description |
| hA1_nsum | 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=hA1_weight 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
hA1The CUSTOM action with label hA1 calculates the following quantities:| Quantity | Type | Description |
| hA1 | 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=hA1_u,hA1_nsum 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=hA1 FILE the file on which to write the grid=histoA1.cube STRIDE the frequency with which the grid should be output to the file=1000 FMTthe format that should be used to output real numbers=%10.6f PRINT_ONE_FILE output grids one after the other in a single file
Notice that we have also used the FMT keyword here to control the format of the numbers in our output cube file.
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 label for the grid that you would like to output |
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 for the grid that you would like to output |
| STRIDE |
compulsory |
0 |
the frequency with which the grid should be output to the file |
| FILE |
compulsory |
density |
the file on which to write the grid |
| FMT |
optional |
not used |
the format that should be used to output real numbers |
| PRINT_ONE_FILE |
optional |
false |
output grids one after the other in a single file |
deprecated keywords
The keywords in the following table can still be used with this action but have been deprecated
| Keyword |
Description |
| GRID |
You should use ARG instead of this keyword which was used in older versions of PLUMED and is provided for back compatibility only |
