man/man1/g_bar.1

   1 .TH g_bar 1 "Thu 26 Aug 2010" "" "GROMACS suite, VERSION 4.5"
   2 .SH NAME
   3 g_bar - calculates free energy difference estimates through Bennett's acceptance ratio
   4
   5 .B VERSION 4.5
   6 .SH SYNOPSIS
   7 \f3g_bar\fP
   8 .BI "\-f" " dhdl.xvg "
   9 .BI "\-o" " bar.xvg "
  10 .BI "\-oi" " barint.xvg "
  11 .BI "\-oh" " histogram.xvg "
  12 .BI "\-g" " energy.edr "
  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 \&g_bar calculates free energy difference estimates through
  27 \&Bennett's acceptance ratio method.
  28 \&Input option \fB \-f\fR expects multiple dhdl files.
  29 \&Two types of input files are supported:
  30
  31 \&* Files with only one y\-value, for such files it is assumed
  32 \&that the y\-value is dH/dlambda and that the Hamiltonian depends
  33 \&linearly on lambda. The lambda value of the simulation is inferred
  34 \&from the subtitle if present, otherwise from a number in the
  35 \&subdirectory in the file name.
  36 \&
  37
  38 \&* Files with more than one y\-value. The files should have columns
  39 \&with dH/dlambda and Delta lambda. The lambda values are inferred
  40 \&from the legends:
  41 \&lambda of the simulation from the legend of dH/dlambda
  42 \&and the foreign lambda's from the legends of Delta H.
  43
  44
  45 \&The lambda of the simulation is parsed from dhdl.xvg file's legend
  46 \&containing the string 'dH', the foreign lambda's from the legend
  47 \&containing the capitalized letters 'D' and 'H'. The temperature
  48 \&is parsed from the legend line containing 'T ='.
  49
  50
  51 \&The free energy estimates are determined using BAR with bisection,
  52 \&the precision of the output is set with \fB \-prec\fR.
  53 \&An error estimate taking into account time correlations
  54 \&is made by splitting the data into blocks and determining
  55 \&the free energy differences over those blocks and assuming
  56 \&the blocks are independent.
  57 \&The final error estimate is determined from the average variance
  58 \&over 5 blocks. A range of blocks numbers for error estimation can
  59 \&be provided with the options \fB \-nbmin\fR and \fB \-nbmax\fR.
  60
  61
  62 \&The results are split in two parts: the last part contains the final
  63 \&results in kJ/mol, together with the error estimate for each part
  64 \&and the total. The first part contains detailed free energy
  65 \&difference estimates and phase space overlap measures in units of
  66 \&kT (together with their computed error estimate). The printed
  67 \&values are:
  68
  69 \&*  lam_A: the lambda values for point A.
  70
  71 \&*  lam_B: the lambda values for point B.
  72
  73 \&*     DG: the free energy estimate.
  74
  75 \&*    s_A: an estimate of the relative entropy of B in A.
  76
  77 \&*    s_A: an estimate of the relative entropy of A in B.
  78
  79 \&*  stdev: an estimate expected per\-sample standard deviation.
  80
  81
  82 \&The relative entropy of both states in each other's ensemble can be
  83 \&interpreted as a measure of phase space overlap:
  84 \&the relative entropy s_A of the work samples of lambda_B in the
  85 \&ensemble of lambda_A (and vice versa for s_B), is a
  86 \&measure of the 'distance' between Boltzmann distributions of
  87 \&the two states, that goes to zero for identical distributions. See
  88 \&Wu & Kofke, J. Chem. Phys. 123 084109 (2009) for more information.
  89 \&
  90
  91
  92 \&The estimate of the expected per\-sample standard deviation, as given
  93 \&in Bennett's original BAR paper:
  94 \&Bennett, J. Comp. Phys. 22, p 245 (1976), Eq. 10 gives an estimate
  95 \&of the quality of sampling (not directly of the actual statistical
  96 \&error, because it assumes independent samples).
  97
  98
  99 .SH FILES
 100 .BI "\-f" " dhdl.xvg"
 101 .B Input, Opt., Mult.
 102  xvgr/xmgr file
 103
 104 .BI "\-o" " bar.xvg"
 105 .B Output, Opt.
 106  xvgr/xmgr file
 107
 108 .BI "\-oi" " barint.xvg"
 109 .B Output, Opt.
 110  xvgr/xmgr file
 111
 112 .BI "\-oh" " histogram.xvg"
 113 .B Output, Opt.
 114  xvgr/xmgr file
 115
 116 .BI "\-g" " energy.edr"
 117 .B Input, Opt., Mult.
 118  Energy file
 119
 120 .SH OTHER OPTIONS
 121 .BI "\-[no]h"  "no    "
 122  Print help info and quit
 123
 124 .BI "\-[no]version"  "no    "
 125  Print version info and quit
 126
 127 .BI "\-nice"  " int" " 0"
 128  Set the nicelevel
 129
 130 .BI "\-[no]w"  "no    "
 131  View output xvg, xpm, eps and pdb files
 132
 133 .BI "\-xvg"  " enum" " xmgrace"
 134  xvg plot formatting: \fB xmgrace\fR, \fB xmgr\fR or \fB none\fR
 135
 136 .BI "\-b"  " real" " 0     "
 137  Begin time for BAR
 138
 139 .BI "\-e"  " real" " \-1    "
 140  End time for BAR
 141
 142 .BI "\-temp"  " real" " \-1    "
 143  Temperature (K)
 144
 145 .BI "\-prec"  " int" " 2"
 146  The number of digits after the decimal point
 147
 148 .BI "\-nbmin"  " int" " 5"
 149  Minimum number of blocks for error estimation
 150
 151 .BI "\-nbmax"  " int" " 5"
 152  Maximum number of blocks for error estimation
 153
 154 .BI "\-nbin"  " int" " 100"
 155  Number of bins for histogram output
 156
 157 .SH SEE ALSO
 158 .BR gromacs(7)
 159
 160 More information about \fBGROMACS\fR is available at <\fIhttp://www.gromacs.org/\fR>.