Command line tool: sum_hills

Module	cltools
Description	Input
sum the hills with plumed	command line args

Details

sum_hills is a tool that allows one to to use plumed to post-process an existing hills/colvar file

This tool is most frequently used as shown below after a METAD simulation has been performed to sum all the Gaussians in the hills file and output the free energy surface.

plumed sum_hillssum the hills with  plumed More details  --hillsspecify the name of the hills file PATHTOMYHILLSFILE
The sum_hills action with label plumed calculates something

The default name for the output file will be fes.dat Note that plumed automatically detects the number of the variables you have and their periodicity. Additionally, if you use flexible hills (multivariate Gaussian kernels), plumed will understand it from the HILLS file.

The sum_hills tool can also accept multiple files that will be integrated one after the other as shown below

plumed sum_hillssum the hills with  plumed More details  --hillsspecify the name of the hills file PATHTOMYHILLSFILE1,PATHTOMYHILLSFILE2,PATHTOMYHILLSFILE3
The sum_hills action with label plumed calculates something

if you want to integrate out some variable from your output free energy surface you do

plumed sum_hillssum the hills with  plumed More details  --hillsspecify the name of the hills file PATHTOMYHILLSFILE   --idwspecify the variables to be used for the free-energy/histogram (default is all) t1 --ktspecify temperature in energy units for integrating out variables 0.6
The sum_hills action with label plumed calculates something

where with --idw you define the variables that you want in the output free energy surface. All other variables in the hills file will be integrated out. --kt defines the temperature of the system in energy units. (be consistent with the units you have in your hills: plumed will not check this for you) If you need more variables then you may use a comma separated syntax shown below:

plumed sum_hillssum the hills with  plumed More details  --hillsspecify the name of the hills file PATHTOMYHILLSFILE   --idwspecify the variables to be used for the free-energy/histogram (default is all) t1,t2 --ktspecify temperature in energy units for integrating out variables 0.6
The sum_hills action with label plumed calculates something

You can define the output grid with the number of bins you want by using a command like this one

plumed sum_hillssum the hills with  plumed More details --binthe number of bins for the grid 99,99 --hillsspecify the name of the hills file PATHTOMYHILLSFILE
The sum_hills action with label plumed calculates something

In the command above the min/max to use are detected for you. If you want to specify the min/max yourself you can do so by using a command like the one shown below:

plumed sum_hillssum the hills with  plumed More details --binthe number of bins for the grid 99,99 --minthe lower bounds for the grid  --maxthe upper bounds for the grid pi,pi --hillsspecify the name of the hills file PATHTOMYHILLSFILE
The sum_hills action with label plumed calculates something

You can of course use numbers instead of -pi/pi.

You can use a --stride keyword to have a dump of the free energy estimate after each bunch of hills you read as shown in the following command:

plumed sum_hillssum the hills with  plumed More details --stridespecify the stride for integrating hills file (default 0=never) 300 --hillsspecify the name of the hills file PATHTOMYHILLSFILE
The sum_hills action with label plumed calculates something

If you have run well tempered metadynamics you can also ask sum_hills to output the negative bias instead of the free energy by using the keyword --negbias as shown below

plumed sum_hillssum the hills with  plumed More details --negbias  print the negative bias instead of the free energy (only needed with well tempered runs and flexible hills)  --hillsspecify the name of the hills file PATHTOMYHILLSFILE
The sum_hills action with label plumed calculates something

Here the default output file name will be negativebias.dat

From time to time you might need to use HILLS or a COLVAR file as it was just a simple set of points from which you want to build a free energy by using -(1/beta)log(P). If you want to do this operation then you use the --histo option as shown below:

plumed sum_hillssum the hills with  plumed More details --histospecify the name of the file for histogram a colvar/hills file is good PATHTOMYCOLVARORHILLSFILE  --sigma a vector that specify the sigma for binning (only needed when doing histogram  0.2,0.2 --ktspecify temperature in energy units for integrating out variables 0.6
The sum_hills action with label plumed calculates something

in this case you need a --kt to do the reweighting and you need to set bandwidth parameters using the --sigma option for the histogram calculation as this histogram is computed using Gaussian kernels, so it will be a continuous histogram.

For the command above the default output is called histo.dat. Note that also here you can have multiple input files separated by a comma.

Additionally, if you want to compute the histogram and sum of the hills from the same file you can do this by using a command like this one:

plumed sum_hillssum the hills with  plumed More details --hillsspecify the name of the hills file --histospecify the name of the file for histogram a colvar/hills file is good PATHTOMYCOLVARORHILLSFILE  --sigma a vector that specify the sigma for binning (only needed when doing histogram  0.2,0.2 --ktspecify temperature in energy units for integrating out variables 0.6
The sum_hills action with label plumed calculates something

The two files can be eventually the same

Another interesting thing one can do is monitor the difference in blocks as a metadynamics goes on. When the bias deposited is constant over the whole domain one can consider to be at convergence. This can be done with the --nohistory keyword

plumed sum_hillssum the hills with  plumed More details --stridespecify the stride for integrating hills file (default 0=never) 300 --hillsspecify the name of the hills file PATHTOMYHILLSFILE  --nohistory  to be used with --stride:  it splits the bias/histogram in pieces without previous history 
The sum_hills action with label plumed calculates something

and similarly one can do the same for an histogram file

plumed sum_hillssum the hills with  plumed More details --histospecify the name of the file for histogram a colvar/hills file is good PATHTOMYCOLVARORHILLSFILE  --sigma a vector that specify the sigma for binning (only needed when doing histogram  0.2,0.2 --ktspecify temperature in energy units for integrating out variables 0.6 --nohistory  to be used with --stride:  it splits the bias/histogram in pieces without previous history 
The sum_hills action with label plumed calculates something

just to check the hypothetical free energy calculated in single blocks of time during a simulation and not in a cumulative way

The output format can be controlled by using the --fmt option as shown below

plumed sum_hillssum the hills with  plumed More details --hillsspecify the name of the hills file PATHTOMYHILLSFILE  --fmtspecify the output format %8.3f
The sum_hills action with label plumed calculates something

where here we chose a float with length of 8 and 3 digits

The output can be named in a arbitrary way by using the --output option as shown below:

plumed sum_hillssum the hills with  plumed More details --hillsspecify the name of the hills file PATHTOMYHILLSFILE  --outfilespecify the output file for sumhills myfes.dat
The sum_hills action with label plumed calculates something

This command produces a file myfes.dat which contains the free energy surface.

If you use stride, the name specied with --output is the suffix so this command:

plumed sum_hillssum the hills with  plumed More details --hillsspecify the name of the hills file PATHTOMYHILLSFILE  --outfilespecify the output file for sumhills myfes_ --stridespecify the stride for integrating hills file (default 0=never) 100
The sum_hills action with label plumed calculates something

produces output files called myfes_0.dat, myfes_1.dat, myfes_2.dat etc.

The same is true for the output coming from histogram that is used. So this example

plumed sum_hillssum the hills with  plumed More details --histospecify the name of the file for histogram a colvar/hills file is good HILLS --ktspecify temperature in energy units for integrating out variables 2.5 --sigma a vector that specify the sigma for binning (only needed when doing histogram  0.01 --outhistospecify the output file for the histogram myhisto.dat
The sum_hills action with label plumed calculates something

produces a file myhisto.dat, while this input

plumed sum_hillssum the hills with  plumed More details --histospecify the name of the file for histogram a colvar/hills file is good HILLS --ktspecify temperature in energy units for integrating out variables 2.5 --sigma a vector that specify the sigma for binning (only needed when doing histogram  0.01 --outhistospecify the output file for the histogram myhisto_ --stridespecify the stride for integrating hills file (default 0=never) 100
The sum_hills action with label plumed calculates something

produces output files called myhisto_0.dat, myhisto_1.dat, myhisto_3.dat etc..

Syntax

The following table describes the command line options that are available for this tool

Keyword	Description
--help/-h	print this help
--help-debug	print special options that can be used to create regtests
--hills	specify the name of the hills file
--histo	specify the name of the file for histogram a colvar/hills file is good
--stride	specify the stride for integrating hills file (default 0=never)
--min	the lower bounds for the grid
--max	the upper bounds for the grid
--bin	the number of bins for the grid
--spacing	grid spacing, alternative to the number of bins
--idw	specify the variables to be used for the free-energy/histogram (default is all)
--outfile	specify the output file for sumhills
--outhisto	specify the output file for the histogram
--kt	specify temperature in energy units for integrating out variables
--sigma	a vector that specify the sigma for binning (only needed when doing histogram
--negbias	print the negative bias instead of the free energy (only needed with well tempered runs and flexible hills)
--nohistory	to be used with --stride: it splits the bias/histogram in pieces without previous history
--mintozero	it translate all the minimum value in bias/histogram to zero (useful to compare results)
--fmt	specify the output format