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
18       individual 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
50       either  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
58       depends 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
72       intervals, this is almost certainly  not  correct.  Usually  subsequent
73       energies  are  correlated  and  different time intervals mean different
74       degrees 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
79       estimates  and  phase  space  overlap measures in units of kT (together
80       with 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
95       interpreted  as  a measure of phase space overlap: the relative entropy
96       s_A of the work samples of lambda_B in the ensemble  of  lambda_A  (and
97       vice  versa  for s_B), is a measure of the ‘distance’ between Boltzmann
98       distributions of the two states, that goes to zero for  identical  dis‐
99       tributions.  See  Wu & Kofke, J. Chem. Phys. 123 084109 (2005) for more
100       information.
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
105       directly  of  the actual statistical error, because it assumes indepen‐
106       dent 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       2019, GROMACS development team
171
172
173
174
1752018.7                           May 29, 2019                       GMX-BAR(1)
Impressum