| VERSION 4.5 |
This 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).
At present, three input modes are supported:
* With option -it, the user provides a file which contains the
filenames of the umbrella simulation run-input files (tpr files),
AND, with option -ix, a file which contains filenames 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 ouput file names (pullf.xvg) with option -if.
From the pull force the position in the ubrella potential is
computed. This does not work with tabulated umbrella potentials.
* With option -ip, the user provides filenames 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 g_wham. The pdo file header
must be similar to the folowing:
# 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
#####
Nr of pull groups, umbrella positions, force constants, and names
may (of course) differ. Following the header, a time column and
a data columns for each pull group follow (i.e. the displacement
with respect to the umbrella center). Up to four pull groups are possible
at present.
By default, the output files are
-o PMF output file
-hist histograms output file
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 provied with -tab.
WHAM OPTIONS
-bins Nr of bins used in analysis
-temp Temperature in the simulations
-tol Stop iteration if profile (probability) changed less than tolerance
-auto Automatic determination of boudndaries
-min,-max Boundaries of the profile
The data points which are used
to compute the profile can be restricted with options -b, -e, and -dt.
Play particularly with -b to ensure sufficient equilibration in each
umbrella window!
With -log (default) the profile is written in energy units, otherwise (-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, choose with -zprof0 (useful with bootstrapping, see below).
For cyclic (or periodic) reaction coordinates (dihedral angle, channel PMF
without osmotic gradient), -cycl is useful.
-cycl yes min and max are assumed to
be neighboring points and histogram points outside min and max are mapped into
the interval [min,max] (compare histogram output).
-cycl weighted First, a non-cyclic profile is computed. Subsequently,
periodicity is enforced by adding corrections dG(i) between neighboring bins
i and i+1. The correction is chosen proportional to 1/[n(i)*n(i+1)]^alpha, where
n(i) denotes the total nr of data points in bin i as collected from all histograms.
alpha is defined with -alpha. The corrections are written to the file defined by -wcorr.
(Compare Hub and de Groot, PNAS 105:1198 (2008))
ERROR ANALYSIS
Statistical errors may be estimated with bootstrap analysis. Use it with care,
otherwise the statistical error may be substantially undererstimated !!
-nBootstrap defines the nr of bootstraps. Two bootstrapping modes are supported.
-histbs Complete histograms are considered as independent data points (default). For each
bootstrap, N histograms are randomly chosen from the N given histograms (allowing duplication).
To avoid gaps without data along the reaction coordinate blocks of histograms (-histbs-block)
may be defined. In that case, the given histograms are divided into blocks and
only histograms within each block are mixed. Note that the histograms
within each block must be representative for all possible histograms, otherwise the
statistical error is undererstimated!
-nohistbs The given histograms are used to generate new random histograms,
such that the generated data points are distributed according the given histograms. The number
of points generated for each bootstrap histogram can be controlled with -bs-dt.
Note that one data point should be generated for each *independent* point in the given
histograms. With the long autocorrelations in MD simulations, this procedure may
easily understimate the error!
Bootstrapping output:
-bsres Average profile and standard deviations
-bsprof All bootstrapping profiles
With -vbs (verbose bootstrapping), the histograms of each bootstrap are written, and,
with -nohistBS, the cummulants of the histogram.
option | filename | type | description |
---|---|---|---|
-ix | pullx-files.dat | Input, Opt. | Generic data file |
-if | pullf-files.dat | Input, Opt. | Generic data file |
-it | tpr-files.dat | Input, Opt. | Generic data file |
-ip | pdo-files.dat | Input, Opt. | Generic data file |
-o | profile.xvg | Output | xvgr/xmgr file |
-hist | histo.xvg | Output | xvgr/xmgr file |
-bsres | bsResult.xvg | Output, Opt. | xvgr/xmgr file |
-bsprof | bsProfs.xvg | Output, Opt. | xvgr/xmgr file |
-tab | umb-pot.dat | Input, Opt. | Generic data file |
-wcorr | cycl-corr.xvg | Input, Opt. | xvgr/xmgr file |
option | type | default | description |
---|---|---|---|
-[no]h | gmx_bool | no | Print help info and quit |
-[no]version | gmx_bool | no | Print version info and quit |
-nice | int | 19 | Set the nicelevel |
-xvg | enum | xmgrace | xvg plot formatting: xmgrace, xmgr or none |
-min | real | 0 | Minimum coordinate in profile |
-max | real | 0 | Maximum coordinate in profile |
-[no]auto | gmx_bool | yes | determine min and max automatically |
-bins | int | 200 | Number of bins in profile |
-temp | real | 298 | Temperature |
-tol | real | 1e-06 | Tolerance |
-[no]v | gmx_bool | no | verbose mode |
-b | real | 50 | first time to analyse (ps) |
-e | real | 1e+20 | last time to analyse (ps) |
-dt | real | 0 | Analyse only every dt ps |
-[no]histonly | gmx_bool | no | Write histograms and exit |
-[no]boundsonly | gmx_bool | no | Determine min and max and exit (with -auto) |
-[no]log | gmx_bool | yes | Calculate the log of the profile before printing |
-unit | enum | kJ | energy unit in case of log output: kJ, kCal or kT |
-zprof0 | real | 0 | Define profile to 0.0 at this position (with -log) |
-cycl | enum | no | Create cyclic/periodic profile. Assumes min and max are the same point.: no, yes or weighted |
-alpha | real | 2 | for '-cycl weighted', set parameter alpha |
-[no]flip | gmx_bool | no | Combine halves of profile (not supported) |
-[no]hist-eq | gmx_bool | no | Enforce equal weight for all histograms. (Non-Weighed-HAM) |
-nBootstrap | int | 0 | nr of bootstraps to estimate statistical uncertainty |
-bs-dt | real | 0 | timestep for synthetic bootstrap histograms (ps). Ensure independent data points! |
-bs-seed | int | -1 | seed for bootstrapping. (-1 = use time) |
-[no]histbs | gmx_bool | yes | In bootstrapping, consider complete histograms as one data point. Accounts better for long autocorrelations. |
-histbs-block | int | 8 | when mixin histograms only mix within blocks of -histBS_block. |
-[no]vbs | gmx_bool | no | verbose bootstrapping. Print the cummulants and a histogram file for each bootstrap. |