1GMX-BAR(1) GROMACS GMX-BAR(1)
2
6 gmx-bar - Calculate free energy difference estimates through Bennett's
7 acceptance ratio
8
10 gmx bar [-f [<.xvg> [...]]] [-g [<.edr> [...]]] [-o [<.xvg>]]
11 [-oi [<.xvg>]] [-oh [<.xvg>]] [-[no]w] [-xvg <enum>]
12 [-b <real>] [-e <real>] [-temp <real>] [-prec <int>]
13 [-nbmin <int>] [-nbmax <int>] [-nbin <int>] [-[no]extp]
14
16 gmx bar calculates free energy difference estimates through Bennett's
17 acceptance ratio method (BAR). It also automatically adds series of in‐
18 dividual free energies obtained with BAR into a combined free energy
19 estimate.
20 Every individual BAR free energy difference relies on two simulations
22 at different states: say state A and state B, as controlled by a param‐
23 eter, lambda (see the .mdp parameter init_lambda). The BAR method cal‐
24 culates a ratio of weighted average of the Hamiltonian difference of
25 state B given state A and vice versa. The energy differences to the
26 other state must be calculated explicitly during the simulation. This
27 can be done with the .mdp option foreign_lambda.
28 Input option -f expects multiple dhdl.xvg files. Two types of input
30 files are supported:
31 • Files with more than one y-value. The files should have columns
33 with dH/dlambda and Deltalambda. The lambda values are inferred
34 from the legends: lambda of the simulation from the legend of
35 dH/dlambda and the foreign lambda values from the legends of Delta
36 H
37 • Files with only one y-value. Using the -extp option for these
39 files, it is assumed that the y-value is dH/dlambda and that the
40 Hamiltonian depends linearly on lambda. The lambda value of the
41 simulation is inferred from the subtitle (if present), otherwise
42 from a number in the subdirectory in the file name.
43 The lambda of the simulation is parsed from dhdl.xvg file's legend con‐
45 taining the string 'dH', the foreign lambda values from the legend con‐
46 taining the capitalized letters 'D' and 'H'. The temperature is parsed
47 from the legend line containing 'T ='.
48 The input option -g expects multiple .edr files. These can contain ei‐
50 ther lists of energy differences (see the .mdp option sepa‐
51 rate_dhdl_file), or a series of histograms (see the .mdp options
52 dh_hist_size and dh_hist_spacing). The temperature and lambda values
53 are automatically deduced from the ener.edr file.
54 In addition to the .mdp option foreign_lambda, the energy difference
56 can also be extrapolated from the dH/dlambda values. This is done with
57 the``-extp`` option, which assumes that the system's Hamiltonian de‐
58 pends linearly on lambda, which is not normally the case.
59 The free energy estimates are determined using BAR with bisection, with
61 the precision of the output set with -prec. An error estimate taking
62 into account time correlations is made by splitting the data into
63 blocks and determining the free energy differences over those blocks
64 and assuming the blocks are independent. The final error estimate is
65 determined from the average variance over 5 blocks. A range of block
66 numbers for error estimation can be provided with the options -nbmin
67 and -nbmax.
68 gmx bar tries to aggregate samples with the same 'native' and 'foreign'
70 lambda values, but always assumes independent samples. Note that when
71 aggregating energy differences/derivatives with different sampling in‐
72 tervals, this is almost certainly not correct. Usually subsequent ener‐
73 gies are correlated and different time intervals mean different degrees
74 of correlation between samples.
75 The results are split in two parts: the last part contains the final
77 results in kJ/mol, together with the error estimate for each part and
78 the total. The first part contains detailed free energy difference es‐
79 timates and phase space overlap measures in units of kT (together with
80 their computed error estimate). The printed values are:
81 • lam_A: the lambda values for point A.
83 • lam_B: the lambda values for point B.
85 • DG: the free energy estimate.
87 • s_A: an estimate of the relative entropy of B in A.
89 • s_B: an estimate of the relative entropy of A in B.
91 • stdev: an estimate expected per-sample standard deviation.
93 The relative entropy of both states in each other's ensemble can be in‐
95 terpreted as a measure of phase space overlap: the relative entropy s_A
96 of the work samples of lambda_B in the ensemble of lambda_A (and vice
97 versa for s_B), is a measure of the 'distance' between Boltzmann dis‐
98 tributions of the two states, that goes to zero for identical distribu‐
99 tions. See Wu & Kofke, J. Chem. Phys. 123 084109 (2005) for more infor‐
100 mation.
101 The estimate of the expected per-sample standard deviation, as given in
103 Bennett's original BAR paper: Bennett, J. Comp. Phys. 22, p 245 (1976).
104 Eq. 10 therein gives an estimate of the quality of sampling (not di‐
105 rectly of the actual statistical error, because it assumes independent
106 samples).
107 To get a visual estimate of the phase space overlap, use the -oh option
109 to write series of histograms, together with the -nbin option.
110
112 Options to specify input files:
113 -f [<.xvg> [...]] (dhdl.xvg) (Optional)
115 xvgr/xmgr file
116 -g [<.edr> [...]] (ener.edr) (Optional)
118 Energy file
119 Options to specify output files:
121 -o [<.xvg>] (bar.xvg) (Optional)
123 xvgr/xmgr file
124 -oi [<.xvg>] (barint.xvg) (Optional)
126 xvgr/xmgr file
127 -oh [<.xvg>] (histogram.xvg) (Optional)
129 xvgr/xmgr file
130 Other options:
132 -[no]w (no)
134 View output .xvg, .xpm, .eps and .pdb files
135 -xvg <enum> (xmgrace)
137 xvg plot formatting: xmgrace, xmgr, none
138 -b <real> (0)
140 Begin time for BAR
141 -e <real> (-1)
143 End time for BAR
144 -temp <real> (-1)
146 Temperature (K)
147 -prec <int> (2)
149 The number of digits after the decimal point
150 -nbmin <int> (5)
152 Minimum number of blocks for error estimation
153 -nbmax <int> (5)
155 Maximum number of blocks for error estimation
156 -nbin <int> (100)
158 Number of bins for histogram output
159 -[no]extp (no)
161 Whether to linearly extrapolate dH/dl values to use as energies
162
164 gmx(1)
165 More information about GROMACS is available at <‐
167 http://www.gromacs.org/>.
168
170 2022, GROMACS development team
1712022.3 Sep 02, 2022 GMX-BAR(1)