1GMX-BAR(1)                          GROMACS                         GMX-BAR(1)
2
3
4

NAME

6       gmx-bar  - Calculate free energy difference estimates through Bennett's
7       acceptance ratio
8

SYNOPSIS

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

DESCRIPTION

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
21       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
29       Input  option  -f  expects multiple dhdl.xvg files.  Two types of input
30       files are supported:
31
32          • 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
38          • 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
44       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
49       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
55       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
60       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
69       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
76       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
82          • lam_A: the lambda values for point A.
83
84          • lam_B: the lambda values for point B.
85
86          • DG: the free energy estimate.
87
88          • s_A: an estimate of the relative entropy of B in A.
89
90          • s_B: an estimate of the relative entropy of A in B.
91
92          • stdev: an estimate expected per-sample standard deviation.
93
94       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
102       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
108       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

OPTIONS

112       Options to specify input files:
113
114       -f [<.xvg> [...]] (dhdl.xvg) (Optional)
115              xvgr/xmgr file
116
117       -g [<.edr> [...]] (ener.edr) (Optional)
118              Energy file
119
120       Options to specify output files:
121
122       -o [<.xvg>] (bar.xvg) (Optional)
123              xvgr/xmgr file
124
125       -oi [<.xvg>] (barint.xvg) (Optional)
126              xvgr/xmgr file
127
128       -oh [<.xvg>] (histogram.xvg) (Optional)
129              xvgr/xmgr file
130
131       Other options:
132
133       -[no]w (no)
134              View output .xvg, .xpm, .eps and .pdb files
135
136       -xvg <enum> (xmgrace)
137              xvg plot formatting: xmgrace, xmgr, none
138
139       -b <real> (0)
140              Begin time for BAR
141
142       -e <real> (-1)
143              End time for BAR
144
145       -temp <real> (-1)
146              Temperature (K)
147
148       -prec <int> (2)
149              The number of digits after the decimal point
150
151       -nbmin <int> (5)
152              Minimum number of blocks for error estimation
153
154       -nbmax <int> (5)
155              Maximum number of blocks for error estimation
156
157       -nbin <int> (100)
158              Number of bins for histogram output
159
160       -[no]extp (no)
161              Whether to linearly extrapolate dH/dl values to use as energies
162

SEE ALSO

164       gmx(1)
165
166       More     information    about    GROMACS    is    available    at    <‐
167       http://www.gromacs.org/>.
168
170       2022, GROMACS development team
171
172
173
174
1752022.3                           Sep 02, 2022                       GMX-BAR(1)
Impressum