Provided by: gromacs-data_2023.1-2ubuntu1_all bug

NAME

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

SYNOPSIS

          gmx bar [-f [<.xvg> [...]]] [-g [<.edr> [...]]] [-o [<.xvg>]]
                  [-oi [<.xvg>]] [-oh [<.xvg>]] [-[no]w] [-xvg <enum>]
                  [-b <real>] [-e <real>] [-temp <real>] [-prec <int>]
                  [-nbmin <int>] [-nbmax <int>] [-nbin <int>] [-[no]extp]

DESCRIPTION

       gmx  bar  calculates  free  energy difference estimates through Bennett's acceptance ratio
       method (BAR). It also automatically adds series of individual free energies obtained  with
       BAR into a combined free energy estimate.

       Every individual BAR free energy difference relies on two simulations at different states:
       say state A and state B, as controlled by a parameter,  lambda  (see  the  .mdp  parameter
       init_lambda).  The  BAR  method  calculates a ratio of weighted average of the Hamiltonian
       difference of state B given state A and vice versa.  The energy differences to  the  other
       state  must be calculated explicitly during the simulation. This can be done with the .mdp
       option foreign_lambda.

       Input option -f expects multiple dhdl.xvg files.  Two types of input files are supported:

          • Files with more than one y-value.  The files should have columns with dH/dlambda  and
            Deltalambda.   The  lambda  values  are  inferred  from  the  legends:  lambda of the
            simulation from the legend of dH/dlambda and  the  foreign  lambda  values  from  the
            legends of Delta H

          • Files  with  only  one y-value. Using the -extp option for these files, it is assumed
            that the y-value is dH/dlambda and that the Hamiltonian depends linearly  on  lambda.
            The  lambda  value  of  the  simulation  is  inferred from the subtitle (if present),
            otherwise from a number in the subdirectory in the file name.

       The lambda of the simulation is parsed from dhdl.xvg file's legend containing  the  string
       'dH', the foreign lambda values from the legend containing the capitalized letters 'D' and
       'H'. The temperature is parsed from the legend line containing 'T ='.

       The input option -g expects multiple .edr files.  These can contain either lists of energy
       differences  (see  the .mdp option separate_dhdl_file), or a series of histograms (see the
       .mdp options dh_hist_size and dh_hist_spacing).  The temperature  and  lambda  values  are
       automatically deduced from the ener.edr file.

       In  addition  to  the  .mdp  option  foreign_lambda,  the  energy  difference  can also be
       extrapolated from the dH/dlambda values. This is  done  with  the``-extp``  option,  which
       assumes  that  the  system's Hamiltonian depends linearly on lambda, which is not normally
       the case.

       The free energy estimates are determined using BAR with bisection, with the  precision  of
       the  output  set  with  -prec.  An error estimate taking into account time correlations is
       made by splitting the data into blocks and determining the free  energy  differences  over
       those  blocks  and  assuming  the  blocks  are  independent.   The final error estimate is
       determined from the average variance over 5 blocks. A range of  block  numbers  for  error
       estimation can be provided with the options -nbmin and -nbmax.

       gmx bar tries to aggregate samples with the same 'native' and 'foreign' lambda values, but
       always   assumes   independent   samples.    Note    that    when    aggregating    energy
       differences/derivatives  with  different  sampling intervals, this is almost certainly not
       correct. Usually subsequent energies are correlated  and  different  time  intervals  mean
       different degrees of correlation between samples.

       The  results  are  split in two parts: the last part contains the final results in kJ/mol,
       together with the error estimate for each part and the  total.  The  first  part  contains
       detailed  free energy difference estimates and phase space overlap measures in units of kT
       (together with their computed error estimate). The printed values are:

          • lam_A: the lambda values for point A.

          • lam_B: the lambda values for point B.

          • DG: the free energy estimate.

          • s_A: an estimate of the relative entropy of B in A.

          • s_B: an estimate of the relative entropy of A in B.

          • stdev: an estimate expected per-sample standard deviation.

       The relative entropy of both states in each other's  ensemble  can  be  interpreted  as  a
       measure  of  phase space overlap: the relative entropy s_A of the work samples of lambda_B
       in the ensemble of lambda_A (and vice versa for s_B),  is  a  measure  of  the  'distance'
       between  Boltzmann  distributions  of  the  two  states,  that  goes to zero for identical
       distributions. See Wu & Kofke, J. Chem. Phys. 123 084109 (2005) for more information.

       The estimate of the expected per-sample standard deviation, as given in Bennett's original
       BAR  paper: Bennett, J. Comp. Phys. 22, p 245 (1976).  Eq. 10 therein gives an estimate of
       the quality of sampling (not directly of the actual statistical error, because it  assumes
       independent samples).

       To get a visual estimate of the phase space overlap, use the -oh option to write series of
       histograms, together with the -nbin option.

OPTIONS

       Options to specify input files:

       -f [<.xvg> [...]] (dhdl.xvg) (Optional)
              xvgr/xmgr file

       -g [<.edr> [...]] (ener.edr) (Optional)
              Energy file

       Options to specify output files:

       -o [<.xvg>] (bar.xvg) (Optional)
              xvgr/xmgr file

       -oi [<.xvg>] (barint.xvg) (Optional)
              xvgr/xmgr file

       -oh [<.xvg>] (histogram.xvg) (Optional)
              xvgr/xmgr file

       Other options:

       -[no]w (no)
              View output .xvg, .xpm, .eps and .pdb files

       -xvg <enum> (xmgrace)
              xvg plot formatting: xmgrace, xmgr, none

       -b <real> (0)
              Begin time for BAR

       -e <real> (-1)
              End time for BAR

       -temp <real> (-1)
              Temperature (K)

       -prec <int> (2)
              The number of digits after the decimal point

       -nbmin <int> (5)
              Minimum number of blocks for error estimation

       -nbmax <int> (5)
              Maximum number of blocks for error estimation

       -nbin <int> (100)
              Number of bins for histogram output

       -[no]extp (no)
              Whether to linearly extrapolate dH/dl values to use as energies

SEE ALSO

       gmx(1)

       More information about GROMACS is available at <http://www.gromacs.org/>.

COPYRIGHT

       2023, GROMACS development team