gmx-bar(1) GROMACS Manual gmx-bar(1)NAMEgmx-bar - Calculate free energy difference estimates through Bennett's
acceptance ratio
SYNOPSIS
gmx bar [-f [<.xvg> [...]]] [-g [<.edr> [...]]] [-o [<.xvg>]]
[-oi [<.xvg>]] [-oh [<.xvg>]] [-nice <int>] [-[no]w]
[-xvg <enum>] [-b <real>] [-e <real>] [-temp <real>]
[-prec <int>] [-nbmin <int>] [-nbmax <int>] [-nbin <int>]
[-[no]extp]
DESCRIPTION
gmx bar calculates free energy difference estimates through Bennett's
acceptance ratio method (BAR). It also automatically adds series of
individual free energies obtained with BAR into a combined free energy
estimate.
Every individual BAR free energy difference relies on two simulations
at different states: say state A and state B, as controlled by a param‐
eter, lambda (see the .mdp parameter init_lambda). The BAR method cal‐
culates a ratio of weighted average of the Hamiltonian difference of
state B given state A and vice versa. The energy differences to the
other state must be calculated explicitly during the simulation. This
can be done with the .mdp option foreign_lambda.
Input option -f expects multiple dhdl.xvg files. Two types of input
files are supported: * Files with more than one y-value. The files
should have columns with dH/dlambda and Deltalambda. The lambda values
are inferred from the legends: lambda of the simulation from the legend
of dH/dlambda and the foreign lambda values from the legends of Delta H
* Files with only one y-value. Using the -extp option for these files,
it is assumed that the y-value is dH/dlambda and that the Hamiltonian
depends linearly on lambda. The lambda value of the simulation is
inferred from the subtitle (if present), otherwise from a number in the
subdirectory in the file name.
The lambda of the simulation is parsed from dhdl.xvg file's legend con‐
taining the string 'dH', the foreign lambda values from the legend con‐
taining the capitalized letters 'D' and 'H'. The temperature is parsed
from the legend line containing 'T ='.
The input option -g expects multiple .edr files. These can contain
either lists of energy differences (see the .mdp option sepa‐
rate_dhdl_file), or a series of histograms (see the .mdp options
dh_hist_size and dh_hist_spacing). The temperature and lambda values
are automatically deduced from the ener.edr file.
In addition to the .mdp option foreign_lambda, the energy difference
can also be extrapolated from the dH/dlambda values. This is done with
the-extp option, which assumes that the system's Hamiltonian depends
linearly on lambda, which is not normally the case.
The free energy estimates are determined using BAR with bisection, with
the precision of the output set with -prec. An error estimate taking
into account time correlations is made by splitting the data into
blocks and determining the free energy differences over those blocks
and assuming the blocks are independent. The final error estimate is
determined from the average variance over 5 blocks. A range of block
numbers for error estimation can be provided with the options -nbmin
and -nbmax.
gmx bar tries to aggregate samples with the same 'native' and 'foreign'
lambda values, but always assumes independent samples. Note that when
aggregating energy differences/derivatives with different sampling
intervals, this is almost certainly not correct. Usually subsequent
energies are correlated and different time intervals mean different
degrees of correlation between samples.
The results are split in two parts: the last part contains the final
results in kJ/mol, together with the error estimate for each part and
the total. The first part contains detailed free energy difference
estimates and phase space overlap measures in units of kT (together
with their computed error estimate). The printed values are: * lam_A:
the lambda values for point A. * lam_B: the lambda values for point
B. * DG: the free energy estimate. * s_A: an estimate of the
relative entropy of B in A. * s_B: an estimate of the relative
entropy of A in B. * stdev: an estimate expected per-sample standard
deviation.
The relative entropy of both states in each other's ensemble can be
interpreted as a measure of phase space overlap: the relative entropy
s_A of the work samples of lambda_B in the ensemble of lambda_A (and
vice versa for s_B), is a measure of the 'distance' between Boltzmann
distributions of the two states, that goes to zero for identical dis‐
tributions. See Wu & Kofke, J. Chem. Phys. 123 084109 (2005) for more
information.
The estimate of the expected per-sample standard deviation, as given in
Bennett's original BAR paper: Bennett, J. Comp. Phys. 22, p 245 (1976).
Eq. 10 therein gives an estimate of the quality of sampling (not
directly of the actual statistical error, because it assumes indepen‐
dent samples).
To get a visual estimate of the phase space overlap, use the -oh option
to write series of histograms, together with the -nbin option.
OPTIONS
Options to specify input and output files:
-f [<.xvg> [...]] (dhdl.xvg) (Input, Optional)
xvgr/xmgr file
-g [<.edr> [...]] (ener.edr) (Input, Optional)
Energy file
-o [<.xvg>] (bar.xvg) (Output, Optional)
xvgr/xmgr file
-oi [<.xvg>] (barint.xvg) (Output, Optional)
xvgr/xmgr file
-oh [<.xvg>] (histogram.xvg) (Output, Optional)
xvgr/xmgr file
Other options:
-nice <int> (0)
Set the nicelevel
-[no]w (no)
View output .xvg, .xpm, .eps and .pdb files
-xvg <enum> (xmgrace)
xvg plot formatting: xmgrace, xmgr, none
-b <real> (0)
Begin time for BAR
-e <real> (-1)
End time for BAR
-temp <real> (-1)
Temperature (K)
-prec <int> (2)
The number of digits after the decimal point
-nbmin <int> (5)
Minimum number of blocks for error estimation
-nbmax <int> (5)
Maximum number of blocks for error estimation
-nbin <int> (100)
Number of bins for histogram output
-[no]extp (no)
Whether to linearly extrapolate dH/dl values to use as energies
SEE ALSOgromacs(7)
More information about GROMACS is available at <http://www.gro‐
macs.org/>.
VERSION 5.0.6gmx-bar(1)
