man/man1/g_bar.1

   1 .TH g_bar 1 "Mon 4 Apr 2011" "" "GROMACS suite, VERSION 4.5.4-dev-20110404-3c0e5ec"
   2 .SH NAME
   3 g_bar - calculates free energy difference estimates through Bennett's acceptance ratio
   4
   5 .B VERSION 4.5.4-dev-20110404-3c0e5ec
   6 .SH SYNOPSIS
   7 \f3g_bar\fP
   8 .BI "\-f" " dhdl.xvg "
   9 .BI "\-g" " ener.edr "
  10 .BI "\-o" " bar.xvg "
  11 .BI "\-oi" " barint.xvg "
  12 .BI "\-oh" " histogram.xvg "
  13 .BI "\-[no]h" ""
  14 .BI "\-[no]version" ""
  15 .BI "\-nice" " int "
  16 .BI "\-[no]w" ""
  17 .BI "\-xvg" " enum "
  18 .BI "\-b" " real "
  19 .BI "\-e" " real "
  20 .BI "\-temp" " real "
  21 .BI "\-prec" " int "
  22 .BI "\-nbmin" " int "
  23 .BI "\-nbmax" " int "
  24 .BI "\-nbin" " int "
  25 .SH DESCRIPTION
  26 \&\fB g_bar\fR calculates free energy difference estimates through
  27 \&Bennett's acceptance ratio method (BAR). It also automatically
  28 \&adds series of individual free energies obtained with BAR into
  29 \&a combined free energy estimate.
  30
  31
  32 \&Every individual BAR free energy difference relies on two
  33 \&simulations at different states: say state A and state B, as
  34 \&controlled by a parameter, [GRK]lambda[grk] (see the \fB .mdp\fR parameter
  35 \&\fB init_lambda\fR). The BAR method calculates a ratio of weighted
  36 \&average of the Hamiltonian difference of state B given state A and
  37 \&vice versa. If the Hamiltonian does not depend linearly on [GRK]lambda[grk]
  38 \&(in which case we can extrapolate the derivative of the Hamiltonian
  39 \&with respect to [GRK]lambda[grk], as is the default when \fB free_energy\fR is on),
  40 \&the energy differences to the other state need to be calculated
  41 \&explicitly during the simulation. This can be controlled with
  42 \&the \fB .mdp\fR option \fB foreign_lambda\fR.
  43
  44
  45 \&Input option \fB \-f\fR expects multiple \fB dhdl.xvg\fR files.
  46 \&Two types of input files are supported:
  47
  48 \&\fB *\fR  Files with only one \fI y\fR\-value, for such files it is assumed
  49 \&   that the \fI y\fR\-value is dH/d[GRK]lambda[grk] and that the Hamiltonian depends
  50 \&   linearly on [GRK]lambda[grk]. The [GRK]lambda[grk] value of the simulation is inferred
  51 \&   from the subtitle (if present), otherwise from a number in the
  52 \&   subdirectory in the file name.
  53 \&
  54
  55 \&\fB *\fR  Files with more than one \fI y\fR\-value. The files should have columns
  56 \&   with dH/d[GRK]lambda[grk] and [GRK]Delta[grk][GRK]lambda[grk]. The [GRK]lambda[grk] values are inferred
  57 \&   from the legends: [GRK]lambda[grk] of the simulation from the legend of dH/d[GRK]lambda[grk]
  58 \&   and the foreign [GRK]lambda[grk] values from the legends of Delta H.
  59
  60
  61 \&The [GRK]lambda[grk] of the simulation is parsed from \fB dhdl.xvg\fR file's legend
  62 \&containing the string 'dH', the foreign [GRK]lambda[grk] values from the legend
  63 \&containing the capitalized letters 'D' and 'H'. The temperature
  64 \&is parsed from the legend line containing 'T ='.
  65
  66
  67 \&The input option \fB \-g\fR expects multiple \fB .edr\fR files.
  68 \&These can contain either lists of energy differences (see the
  69 \&\fB .mdp\fR option \fB separate_dhdl_file\fR), or a series of histograms
  70 \&(see the \fB .mdp\fR options \fB dh_hist_size\fR and \fB dh_hist_spacing\fR).
  71 \&The temperature and [GRK]lambda[grk] values are automatically deduced from
  72 \&the \fB ener.edr\fR file.
  73
  74 The free energy estimates are determined using BAR with bisection,
  75 \&with the precision of the output set with \fB \-prec\fR.
  76 \&An error estimate taking into account time correlations
  77 \&is made by splitting the data into blocks and determining
  78 \&the free energy differences over those blocks and assuming
  79 \&the blocks are independent.
  80 \&The final error estimate is determined from the average variance
  81 \&over 5 blocks. A range of block numbers for error estimation can
  82 \&be provided with the options \fB \-nbmin\fR and \fB \-nbmax\fR.
  83
  84
  85 \&\fB g_bar\fR tries to aggregate samples with the same 'native' and 'foreign'
  86 \&[GRK]lambda[grk] values, but always assumes independent samples. \fB Note\fR that
  87 \&when aggregating energy differences/derivatives with different
  88 \&sampling intervals, this is almost certainly not correct. Usually
  89 \&subsequent energies are correlated and different time intervals mean
  90 \&different degrees of correlation between samples.
  91
  92
  93 \&The results are split in two parts: the last part contains the final
  94 \&results in kJ/mol, together with the error estimate for each part
  95 \&and the total. The first part contains detailed free energy
  96 \&difference estimates and phase space overlap measures in units of
  97 \&kT (together with their computed error estimate). The printed
  98 \&values are:
  99
 100 \&\fB *\fR  lam_A: the [GRK]lambda[grk] values for point A.
 101
 102 \&\fB *\fR  lam_B: the [GRK]lambda[grk] values for point B.
 103
 104 \&\fB *\fR     DG: the free energy estimate.
 105
 106 \&\fB *\fR    s_A: an estimate of the relative entropy of B in A.
 107
 108 \&\fB *\fR    s_A: an estimate of the relative entropy of A in B.
 109
 110 \&\fB *\fR  stdev: an estimate expected per\-sample standard deviation.
 111
 112
 113 \&The relative entropy of both states in each other's ensemble can be
 114 \&interpreted as a measure of phase space overlap:
 115 \&the relative entropy s_A of the work samples of lambda_B in the
 116 \&ensemble of lambda_A (and vice versa for s_B), is a
 117 \&measure of the 'distance' between Boltzmann distributions of
 118 \&the two states, that goes to zero for identical distributions. See
 119 \&Wu & Kofke, J. Chem. Phys. 123 084109 (2005) for more information.
 120 \&
 121
 122
 123 \&The estimate of the expected per\-sample standard deviation, as given
 124 \&in Bennett's original BAR paper: Bennett, J. Comp. Phys. 22, p 245 (1976).
 125 \&Eq. 10 therein gives an estimate of the quality of sampling (not directly
 126 \&of the actual statistical error, because it assumes independent samples).
 127
 128
 129 \&To get a visual estimate of the phase space overlap, use the
 130 \&\fB \-oh\fR option to write series of histograms, together with the
 131 \&\fB \-nbin\fR option.
 132
 133
 134 .SH FILES
 135 .BI "\-f" " dhdl.xvg"
 136 .B Input, Opt., Mult.
 137  xvgr/xmgr file
 138
 139 .BI "\-g" " ener.edr"
 140 .B Input, Opt., Mult.
 141  Energy file
 142
 143 .BI "\-o" " bar.xvg"
 144 .B Output, Opt.
 145  xvgr/xmgr file
 146
 147 .BI "\-oi" " barint.xvg"
 148 .B Output, Opt.
 149  xvgr/xmgr file
 150
 151 .BI "\-oh" " histogram.xvg"
 152 .B Output, Opt.
 153  xvgr/xmgr file
 154
 155 .SH OTHER OPTIONS
 156 .BI "\-[no]h"  "no    "
 157  Print help info and quit
 158
 159 .BI "\-[no]version"  "no    "
 160  Print version info and quit
 161
 162 .BI "\-nice"  " int" " 0"
 163  Set the nicelevel
 164
 165 .BI "\-[no]w"  "no    "
 166  View output \fB .xvg\fR, \fB .xpm\fR, \fB .eps\fR and \fB .pdb\fR files
 167
 168 .BI "\-xvg"  " enum" " xmgrace"
 169  xvg plot formatting: \fB xmgrace\fR, \fB xmgr\fR or \fB none\fR
 170
 171 .BI "\-b"  " real" " 0     "
 172  Begin time for BAR
 173
 174 .BI "\-e"  " real" " \-1    "
 175  End time for BAR
 176
 177 .BI "\-temp"  " real" " \-1    "
 178  Temperature (K)
 179
 180 .BI "\-prec"  " int" " 2"
 181  The number of digits after the decimal point
 182
 183 .BI "\-nbmin"  " int" " 5"
 184  Minimum number of blocks for error estimation
 185
 186 .BI "\-nbmax"  " int" " 5"
 187  Maximum number of blocks for error estimation
 188
 189 .BI "\-nbin"  " int" " 100"
 190  Number of bins for histogram output
 191
 192 .SH SEE ALSO
 193 .BR gromacs(7)
 194
 195 More information about \fBGROMACS\fR is available at <\fIhttp://www.gromacs.org/\fR>.