gmx wham [-ix [<.dat>]] [-if [<.dat>]] [-it [<.dat>]] [-ip [<.dat>]]
[-is [<.dat>]] [-iiact [<.dat>]] [-tab [<.dat>]]
[-o [<.xvg>]] [-hist [<.xvg>]] [-oiact [<.xvg>]]
[-bsres [<.xvg>]] [-bsprof [<.xvg>]] [-xvg <enum>]
[-min <real>] [-max <real>] [-[no]auto] [-bins <int>]
[-temp <real>] [-tol <real>] [-[no]v] [-b <real>]
[-e <real>] [-dt <real>] [-[no]histonly] [-[no]boundsonly]
[-[no]log] [-unit <enum>] [-zprof0 <real>] [-[no]cycl]
[-[no]sym] [-[no]ac] [-acsig <real>] [-ac-trestart <real>]
[-nBootstrap <int>] [-bs-method <enum>] [-bs-tau <real>]
[-bs-seed <int>] [-histbs-block <int>] [-[no]vbs]
gmx wham is an analysis program that implements the Weighted Histogram Analysis Method (WHAM). It is intended to analyze output files generated by umbrella sampling simulations to compute a potential of mean force (PMF).
gmx wham is currently not fully up to date. It only supports pull setups where the first pull coordinate(s) is/are umbrella pull coordinates and, if multiple coordinates need to be analyzed, all used the same geometry and dimensions. In most cases this is not an issue.
At present, three input modes are supported.
With option -it, the user provides a file which contains the file names of the umbrella simulation run-input files (.tpr files), AND, with option -ix, a file which contains file names of the pullx mdrun output files. The .tpr and pullx files must be in corresponding order, i.e. the first .tpr created the first pullx, etc.
Same as the previous input mode, except that the the user provides the pull force output file names (pullf.xvg) with option -if. From the pull force the position in the umbrella potential is computed. This does not work with tabulated umbrella potentials.
With option -ip, the user provides file names of (gzipped) .pdo files, i.e. the GROMACS 3.3 umbrella output files. If you have some unusual reaction coordinate you may also generate your own .pdo files and feed them with the -ip option into to gmx wham. The .pdo file header must be similar to the following:
# UMBRELLA 3.0
# Component selection: 0 0 1
# nSkip 1
# Ref. Group 'TestAtom'
# Nr. of pull groups 2
# Group 1 'GR1' Umb. Pos. 5.0 Umb. Cons. 1000.0
# Group 2 'GR2' Umb. Pos. 2.0 Umb. Cons. 500.0
#####
The number of pull groups, umbrella positions, force constants, and names may (of course) differ. Following the header, a time column and a data column for each pull group follows (i.e. the displacement with respect to the umbrella center). Up to four pull groups are possible per .pdo file at present.
By default, all pull groups found in all pullx/pullf files are used in WHAM. If only some of the pull groups should be used, a pull group selection file (option -is) can be provided. The selection file must contain one line for each tpr file in tpr-files.dat. Each of these lines must contain one digit (0 or 1) for each pull group in the tpr file. Here, 1 indicates that the pull group is used in WHAM, and 0 means it is omitted. Example: If you have three tpr files, each containing 4 pull groups, but only pull group 1 and 2 should be used, groupsel.dat looks like this:
1 1 0 0
1 1 0 0
1 1 0 0
By default, the output files are
Always check whether the histograms sufficiently overlap.
The umbrella potential is assumed to be harmonic and the force constants are read from the .tpr or .pdo files. If a non-harmonic umbrella force was applied a tabulated potential can be provided with -tab.
The data points that are used to compute the profile can be restricted with options -b, -e, and -dt. Adjust -b to ensure sufficient equilibration in each umbrella window.
With -log (default) the profile is written in energy units, otherwise (with -nolog) as probability. The unit can be specified with -unit. With energy output, the energy in the first bin is defined to be zero. If you want the free energy at a different position to be zero, set -zprof0 (useful with bootstrapping, see below).
For cyclic or periodic reaction coordinates (dihedral angle, channel PMF without osmotic gradient), the option -cycl is useful. gmx wham will make use of the periodicity of the system and generate a periodic PMF. The first and the last bin of the reaction coordinate will assumed be be neighbors.
Option -sym symmetrizes the profile around z=0 before output, which may be useful for, e.g. membranes.
If available, the number of OpenMP threads used by g_wham is controlled with -nt.
With -ac, gmx wham estimates the integrated autocorrelation time (IACT) tau for each umbrella window and weights the respective window with 1/[1+2*tau/dt]. The IACTs are written to the file defined with -oiact. In verbose mode, all autocorrelation functions (ACFs) are written to hist_autocorr.xvg. Because the IACTs can be severely underestimated in case of limited sampling, option -acsig allows one to smooth the IACTs along the reaction coordinate with a Gaussian (sigma provided with -acsig, see output in iact.xvg). Note that the IACTs are estimated by simple integration of the ACFs while the ACFs are larger 0.05. If you prefer to compute the IACTs by a more sophisticated (but possibly less robust) method such as fitting to a double exponential, you can compute the IACTs with gmx analyze and provide them to gmx wham with the file iact-in.dat (option -iiact), which should contain one line per input file (.pdo or pullx/f file) and one column per pull group in the respective file.
Statistical errors may be estimated with bootstrap analysis. Use it with care, otherwise the statistical error may be substantially underestimated. More background and examples for the bootstrap technique can be found in Hub, de Groot and Van der Spoel, JCTC (2010) 6: 3713-3720. -nBootstrap defines the number of bootstraps (use, e.g., 100). Four bootstrapping methods are supported and selected with -bs-method.
Bootstrapping output:
With -vbs (verbose bootstrapping), the histograms of each bootstrap are written, and, with bootstrap method traj, the cumulative distribution functions of the histograms.
Options to specify input files:
Options to specify output files:
Other options: