GMX-BAR(1)

📦
version 2026.4 · 8 versions
, in nixpkgs unstable, ubuntu stonking

💖 GMX-BAR(1) 💖

okay bestie, sit down, hydrate, because we're doing gmx-bar from the GROMACS manual and honestly? it's giving thermodynamics royalty 👑

✨ 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]

like yes, that's a lot of brackets. she's known for her brackets. 💅

🦋 DESCRIPTION 🦋

so gmx bar calculates free energy difference estimates through Bennett's acceptance ratio method (BAR, iconic behavior). And it doesn't just do one — it automatically adds series of individual free energies obtained with BAR into a combined free energy estimate. she's an overachiever, we love that for her 🫶

Every single individual BAR free energy difference is built on two simulations at different states: let's say state A and state B, both controlled by a parameter, lambda (peep the .mdp parameter init_lambda). The BAR method computes 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 — you can do that with the .mdp option foreign_lambda. no vibes-based guessing here, bestie.

The input option -f expects multiple dhdl.xvg files. Two types of input files are supported, and they are not the same vibe:

  • Files with more than one y-value. These files should have columns with dH/dlambda and Deltalambda. The lambda values are inferred from the legends: the lambda of the simulation comes from the legend of dH/dlambda, and the foreign lambda values come from the legends of Delta H. 📖
  • Files with only one y-value. If you use 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 the dhdl.xvg file's legend containing the string 'dH', and the foreign lambda values come from the legend containing the capitalized letters 'D' and 'H'. The temperature is parsed from the legend line containing 'T ='. she reads the legends, she parses the legends, she is that girl 💅

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. auto-deduction, no cap 🧠✨

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. 🚨 read that twice. it's an assumption, and it's a bold one.

The free energy estimates are determined using BAR with bisection, and the precision of the output is set with -prec. An error estimate that takes time correlations into account is made by splitting the data into blocks, 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. so like… be careful babe 😭

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, and it 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 is 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. pretty pictures of physics, obsessed 🌈📈

🎀 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 👀

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

2026, GROMACS development team 💜

okay that's the whole page bestie, every flag accounted for, nothing skipped, she's thorough AND she's cute 💅

this was GROMACS version 2026.4, dated Oct 02, 2026 — thanks for reading, mwah, go run your free energy calculations responsibly 🫶✨

📦 where this page comes from