Shortcut: WHAM_HISTOGRAM

Module	wham
Description	Usage
This can be used to output the a histogram using the weighted histogram technique
output value	type
the histogram that was generated using the WHAM weights	grid

Details and examples

This can be used to output the a histogram using the weighted histogram technique

This shortcut action allows you to calculate a histogram using the weighted histogram analysis technique. The following input illustrates how this is used in practise to analyze the output from a series of umbrella sampling calculations. The trajectory from each of the simulations run with the different biases should be concatenated into a single trajectory before running the following analysis script on the concatenated trajectory using PLUMED driver. The umbrella sampling simulations that will be analyzed using the script below applied a harmonic restraint that restrained the torsional angle involving atoms 5, 7, 9 and 15 to particular values. The script below calculates the reweighting weights for each of the trajectories and then applies the binless WHAM algorithm to determine a weight for each configuration in the concatenated trajectory. A histogram is then constructed from the configurations visited and their weights. This histogram is then converted into a free energy surface and output to a file called fes.dat

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

#SETTINGS NREPLICAS=4
phiThe TORSION action with label phi calculates the following quantities: Quantity    Type    Description  
phi scalar the TORSION involving these atoms: TORSIONCalculate one or multiple torsional angles. More details ATOMSthe four atoms involved in the torsional angle=5,7,9,15
psiThe TORSION action with label psi calculates the following quantities: Quantity    Type    Description  
psi scalar the TORSION involving these atoms: TORSIONCalculate one or multiple torsional angles. More details ATOMSthe four atoms involved in the torsional angle=7,9,15,17
rpThe RESTRAINT action with label rp calculates the following quantities: Quantity    Type    Description  
rp.bias scalar the instantaneous value of the bias potential
rp.force2 scalar the instantaneous value of the squared force due to this bias potential: RESTRAINTAdds harmonic and/or linear restraints on one or more variables. This action has hidden defaults. More details ARGthe values the harmonic restraint acts upon=phi KAPPA specifies that the restraint is harmonic and what the values of the force constants on each of the variables are=50.0 ATthe position of the restraint=@replicas:This keyword specifies that different replicas have different values for this quantity.  See here for more details.{-3.00,-1.45,0.10,1.65}
rp: RESTRAINTAdds harmonic and/or linear restraints on one or more variables. This action uses the defaults shown here. More details ARGthe values the harmonic restraint acts upon=phi KAPPA specifies that the restraint is harmonic and what the values of the force constants on each of the variables are=50.0 ATthe position of the restraint=@replicas:This keyword specifies that different replicas have different values for this quantity.  See here for more details.{-3.00,-1.45,0.10,1.65}  SLOPE specifies that the restraint is linear and what the values of the force constants on each of the variables are=0.0
hhThe WHAM_HISTOGRAM action with label hh calculates the following quantities: Quantity    Type    Description  
hh grid the histogram that was generated using the WHAM weights: WHAM_HISTOGRAMThis can be used to output the a histogram using the weighted histogram technique This action is a shortcut and it has hidden defaults. More details ARGthe arguments that you would like to make the histogram for=phi BIAS the value of the biases to use when performing WHAM=rp.bias TEMPthe temperature at which the simulation was run=300 GRID_MINthe minimum to use for the grid=-pi GRID_MAXthe maximum to use for the grid=pi GRID_BINthe number of bins to use for the grid=50
hh: WHAM_HISTOGRAMThis can be used to output the a histogram using the weighted histogram technique This action is a shortcut and uses the defaults shown here. More details ARGthe arguments that you would like to make the histogram for=phi BIAS the value of the biases to use when performing WHAM=rp.bias TEMPthe temperature at which the simulation was run=300 GRID_MINthe minimum to use for the grid=-pi GRID_MAXthe maximum to use for the grid=pi GRID_BINthe number of bins to use for the grid=50  STRIDE the frequency with which the data should be stored to perform WHAM=1
# PLUMED interprets the command:
# hh: WHAM_HISTOGRAM ARG=phi BIAS=rp.bias TEMP=300 GRID_MIN=-pi GRID_MAX=pi GRID_BIN=50
# as follows (Click the red comment above to revert to the short version of the input):
hh_gatherThe GATHER_REPLICAS action with label hh_gather calculates the following quantities: Quantity    Type    Description  
hh_gather.rep-1 scalar the input arguments for each of the replicas  This is the 1th of these quantities
hh_gather.rep-2 scalar the input arguments for each of the replicas  This is the 2th of these quantities
hh_gather.rep-3 scalar the input arguments for each of the replicas  This is the 3th of these quantities
hh_gather.rep-4 scalar the input arguments for each of the replicas  This is the 4th of these quantities: GATHER_REPLICASCreate a vector that contains the copies of the input quantities from all replicas More details ARGthe argument from the various replicas that you would like to gather=rp.bias
hh_gathervThe CONCATENATE action with label hh_gatherv calculates the following quantities: Quantity    Type    Description  
hh_gatherv vector the concatenated vector/matrix that was constructed from the input values: CONCATENATEJoin vectors or matrices together More details ARGthe values that should be concatenated together to form the output vector=hh_gather.*
hh_collectThe COLLECT action with label hh_collect calculates the following quantities: Quantity    Type    Description  
hh_collect vector the time series for the input quantity: COLLECTCollect data from the trajectory for later analysis More details TYPE required if you are collecting an object with rank>0=vector ARGthe label of the value whose time series is being stored for later analysis=hh_gatherv STRIDE the frequency with which the data should be collected and added to the quantity being averaged=1
hh_whamThe WHAM action with label hh_wham calculates the following quantities: Quantity    Type    Description  
hh_wham vector the vector of WHAM weights to use for reweighting the elements in a time series: WHAMCalculate the weights for configurations using the weighted histogram analysis method. More details ARGthe stored values for the bias=hh_collect TEMPthe system temperature=300
hh_data_phiThe COLLECT action with label hh_data_phi calculates the following quantities: Quantity    Type    Description  
hh_data_phi vector the time series for the input quantity: COLLECTCollect data from the trajectory for later analysis More details ARGthe label of the value whose time series is being stored for later analysis=phi
hhThe KDE action with label hh calculates the following quantities: Quantity    Type    Description  
hh 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=hh_data_phi HEIGHTSthis keyword takes the label of an action that calculates a vector of values=hh_wham KERNEL the kernel function you are using=DISCRETE GRID_MIN the lower bounds for the grid=-pi GRID_MAX the upper bounds for the grid=pi GRID_BINthe number of bins for the grid=50
# --- End of included input --- fesThe CONVERT_TO_FES action with label fes calculates the following quantities: Quantity    Type    Description  
fes grid the free energy surface: CONVERT_TO_FESConvert a histogram to a free energy surface. This action is a shortcut. More details ARGthe histogram that you would like to convert into a free energy surface=hh TEMPthe temperature at which you are operating=300
# PLUMED interprets the command:
# fes: CONVERT_TO_FES ARG=hh TEMP=300
# as follows (Click the red comment above to revert to the short version of the input):
fesThe CUSTOM action with label fes calculates the following quantities: Quantity    Type    Description  
fes 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=hh FUNCthe function you wish to evaluate=-2.49434*log(x) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
# --- 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=fes FILE the file on which to write the grid=fes.dat

The script above must be run with multiple replicas using the following command:

mpirun -np 4 plumed driver --mf_xtc alltraj.xtc --multi 4

Notice that if you use the BANDWIDTH keyword, as in the example below, PLUMED will estimate the histogram using kernel density estimation.

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

#SETTINGS NREPLICAS=4
phiThe TORSION action with label phi calculates the following quantities: Quantity    Type    Description  
phi scalar the TORSION involving these atoms: TORSIONCalculate one or multiple torsional angles. More details ATOMSthe four atoms involved in the torsional angle=5,7,9,15
psiThe TORSION action with label psi calculates the following quantities: Quantity    Type    Description  
psi scalar the TORSION involving these atoms: TORSIONCalculate one or multiple torsional angles. More details ATOMSthe four atoms involved in the torsional angle=7,9,15,17
rpThe RESTRAINT action with label rp calculates the following quantities: Quantity    Type    Description  
rp.bias scalar the instantaneous value of the bias potential
rp.force2 scalar the instantaneous value of the squared force due to this bias potential: RESTRAINTAdds harmonic and/or linear restraints on one or more variables. This action has hidden defaults. More details ARGthe values the harmonic restraint acts upon=phi KAPPA specifies that the restraint is harmonic and what the values of the force constants on each of the variables are=50.0 ATthe position of the restraint=@replicas:This keyword specifies that different replicas have different values for this quantity.  See here for more details.{-3.00,-1.45,0.10,1.65}
rp: RESTRAINTAdds harmonic and/or linear restraints on one or more variables. This action uses the defaults shown here. More details ARGthe values the harmonic restraint acts upon=phi KAPPA specifies that the restraint is harmonic and what the values of the force constants on each of the variables are=50.0 ATthe position of the restraint=@replicas:This keyword specifies that different replicas have different values for this quantity.  See here for more details.{-3.00,-1.45,0.10,1.65}  SLOPE specifies that the restraint is linear and what the values of the force constants on each of the variables are=0.0
hhThe WHAM_HISTOGRAM action with label hh calculates the following quantities: Quantity    Type    Description  
hh grid the histogram that was generated using the WHAM weights: WHAM_HISTOGRAMThis can be used to output the a histogram using the weighted histogram technique This action is a shortcut and it has hidden defaults. More details ARGthe arguments that you would like to make the histogram for=phi BIAS the value of the biases to use when performing WHAM=rp.bias TEMPthe temperature at which the simulation was run=300 GRID_MINthe minimum to use for the grid=-pi GRID_MAXthe maximum to use for the grid=pi GRID_BINthe number of bins to use for the grid=50 BANDWIDTHthe bandwidth for kernel density estimation=0.1
hh: WHAM_HISTOGRAMThis can be used to output the a histogram using the weighted histogram technique This action is a shortcut and uses the defaults shown here. More details ARGthe arguments that you would like to make the histogram for=phi BIAS the value of the biases to use when performing WHAM=rp.bias TEMPthe temperature at which the simulation was run=300 GRID_MINthe minimum to use for the grid=-pi GRID_MAXthe maximum to use for the grid=pi GRID_BINthe number of bins to use for the grid=50 BANDWIDTHthe bandwidth for kernel density estimation=0.1  STRIDE the frequency with which the data should be stored to perform WHAM=1
# PLUMED interprets the command:
# hh: WHAM_HISTOGRAM ARG=phi BIAS=rp.bias TEMP=300 GRID_MIN=-pi GRID_MAX=pi GRID_BIN=50 BANDWIDTH=0.1
# as follows (Click the red comment above to revert to the short version of the input):
hh_gatherThe GATHER_REPLICAS action with label hh_gather calculates the following quantities: Quantity    Type    Description  
hh_gather.rep-1 scalar the input arguments for each of the replicas  This is the 1th of these quantities
hh_gather.rep-2 scalar the input arguments for each of the replicas  This is the 2th of these quantities
hh_gather.rep-3 scalar the input arguments for each of the replicas  This is the 3th of these quantities
hh_gather.rep-4 scalar the input arguments for each of the replicas  This is the 4th of these quantities: GATHER_REPLICASCreate a vector that contains the copies of the input quantities from all replicas More details ARGthe argument from the various replicas that you would like to gather=rp.bias
hh_gathervThe CONCATENATE action with label hh_gatherv calculates the following quantities: Quantity    Type    Description  
hh_gatherv vector the concatenated vector/matrix that was constructed from the input values: CONCATENATEJoin vectors or matrices together More details ARGthe values that should be concatenated together to form the output vector=hh_gather.*
hh_collectThe COLLECT action with label hh_collect calculates the following quantities: Quantity    Type    Description  
hh_collect vector the time series for the input quantity: COLLECTCollect data from the trajectory for later analysis More details TYPE required if you are collecting an object with rank>0=vector ARGthe label of the value whose time series is being stored for later analysis=hh_gatherv STRIDE the frequency with which the data should be collected and added to the quantity being averaged=1
hh_whamThe WHAM action with label hh_wham calculates the following quantities: Quantity    Type    Description  
hh_wham vector the vector of WHAM weights to use for reweighting the elements in a time series: WHAMCalculate the weights for configurations using the weighted histogram analysis method. More details ARGthe stored values for the bias=hh_collect TEMPthe system temperature=300
hh_data_phiThe COLLECT action with label hh_data_phi calculates the following quantities: Quantity    Type    Description  
hh_data_phi vector the time series for the input quantity: COLLECTCollect data from the trajectory for later analysis More details ARGthe label of the value whose time series is being stored for later analysis=phi
hhThe KDE action with label hh calculates the following quantities: Quantity    Type    Description  
hh 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=hh_data_phi HEIGHTSthis keyword takes the label of an action that calculates a vector of values=hh_wham BANDWIDTHthe bandwidths for kernel density esimtation=0.1 GRID_MIN the lower bounds for the grid=-pi GRID_MAX the upper bounds for the grid=pi GRID_BINthe number of bins for the grid=50
# --- End of included input --- fesThe CONVERT_TO_FES action with label fes calculates the following quantities: Quantity    Type    Description  
fes grid the free energy surface: CONVERT_TO_FESConvert a histogram to a free energy surface. This action is a shortcut. More details ARGthe histogram that you would like to convert into a free energy surface=hh TEMPthe temperature at which you are operating=300
# PLUMED interprets the command:
# fes: CONVERT_TO_FES ARG=hh TEMP=300
# as follows (Click the red comment above to revert to the short version of the input):
fesThe CUSTOM action with label fes calculates the following quantities: Quantity    Type    Description  
fes 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=hh FUNCthe function you wish to evaluate=-2.49434*log(x) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
# --- 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=fes FILE the file on which to write the grid=fes.dat

For more details on how the weights for configurations are determined using the wham method see the documentation for the WHAM action.

Full list of keywords

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

Keyword	Type	Default	Description
ARG	compulsory	none	the arguments that you would like to make the histogram for
BIAS	compulsory	*.bias	the value of the biases to use when performing WHAM
TEMP	compulsory	none	the temperature at which the simulation was run
STRIDE	compulsory	1	the frequency with which the data should be stored to perform WHAM
GRID_MIN	compulsory	none	the minimum to use for the grid
GRID_MAX	compulsory	none	the maximum to use for the grid
GRID_BIN	compulsory	none	the number of bins to use for the grid
BANDWIDTH	optional	not used	the bandwidth for kernel density estimation

Quantity	Type	Description
phi	scalar	the TORSION involving these atoms