.. _gmx bar:

gmx bar
=======

Synopsis
--------

.. parsed-literal::

    gmx bar [:strong:`-f` :emphasis:`[<.xvg> [...]]`] [:strong:`-g` :emphasis:`[<.edr> [...]]`] [:strong:`-o` :emphasis:`[<.xvg>]`]
            [:strong:`-oi` :emphasis:`[<.xvg>]`] [:strong:`-oh` :emphasis:`[<.xvg>]`] [:strong:`-[no]w`] [:strong:`-xvg` :emphasis:`<enum>`]
            [:strong:`-b` :emphasis:`<real>`] [:strong:`-e` :emphasis:`<real>`] [:strong:`-temp` :emphasis:`<real>`] [:strong:`-prec` :emphasis:`<int>`]
            [:strong:`-nbmin` :emphasis:`<int>`] [:strong:`-nbmax` :emphasis:`<int>`] [:strong:`-nbin` :emphasis:`<int>`] [:strong:`-[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 :ref:`.mdp <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 :ref:`.mdp <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 :ref:`.edr <edr>` files.
These can contain either lists of energy differences (see the
:ref:`.mdp <mdp>` option ``separate_dhdl_file``), or a series of
histograms (see the :ref:`.mdp <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 :ref:`.mdp <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 :ref:`.xvg <xvg>`, :ref:`.xpm <xpm>`, :ref:`.eps <eps>` and :ref:`.pdb <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

.. only:: man

   See also
   --------

   :manpage:`gmx(1)`

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