.TH g_wham 1 "Mon 4 Apr 2011" "" "GROMACS suite, VERSION 4.5.4-dev-20110404-bc5695c" .SH NAME g_wham - weighted histogram analysis after umbrella sampling .B VERSION 4.5.4-dev-20110404-bc5695c .SH SYNOPSIS \f3g_wham\fP .BI "\-ix" " pullx\-files.dat " .BI "\-if" " pullf\-files.dat " .BI "\-it" " tpr\-files.dat " .BI "\-ip" " pdo\-files.dat " .BI "\-o" " profile.xvg " .BI "\-hist" " histo.xvg " .BI "\-oiact" " iact.xvg " .BI "\-iiact" " iact\-in.dat " .BI "\-bsres" " bsResult.xvg " .BI "\-bsprof" " bsProfs.xvg " .BI "\-tab" " umb\-pot.dat " .BI "\-[no]h" "" .BI "\-[no]version" "" .BI "\-nice" " int " .BI "\-xvg" " enum " .BI "\-min" " real " .BI "\-max" " real " .BI "\-[no]auto" "" .BI "\-bins" " int " .BI "\-temp" " real " .BI "\-tol" " real " .BI "\-[no]v" "" .BI "\-b" " real " .BI "\-e" " real " .BI "\-dt" " real " .BI "\-[no]histonly" "" .BI "\-[no]boundsonly" "" .BI "\-[no]log" "" .BI "\-unit" " enum " .BI "\-zprof0" " real " .BI "\-[no]cycl" "" .BI "\-[no]sym" "" .BI "\-[no]ac" "" .BI "\-acsig" " real " .BI "\-ac\-trestart" " real " .BI "\-nBootstrap" " int " .BI "\-bs\-method" " enum " .BI "\-bs\-tau" " real " .BI "\-bs\-seed" " int " .BI "\-histbs\-block" " int " .BI "\-[no]vbs" "" .SH DESCRIPTION \&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. \&\fB *\fR With option \fB \-it\fR, the user provides a file which contains the \& file names of the umbrella simulation run\-input files (\fB .tpr\fR files), \& AND, with option \fB \-ix\fR, a file which contains file names of \& the pullx \fB mdrun\fR output files. The \fB .tpr\fR and pullx files must \& be in corresponding order, i.e. the first \fB .tpr\fR created the \& first pullx, etc. \&\fB *\fR Same as the previous input mode, except that the the user \& provides the pull force output file names (\fB pullf.xvg\fR) with option \fB \-if\fR. \& From the pull force the position in the umbrella potential is \& computed. This does not work with tabulated umbrella potentials. \fB *\fR With option \fB \-ip\fR, the user provides file names of (gzipped) \fB .pdo\fR files, i.e. \& the GROMACS 3.3 umbrella output files. If you have some unusual reaction coordinate you may also generate your own \fB .pdo\fR files and \& feed them with the \fB \-ip\fR option into to \fB g_wham\fR. The \fB .pdo\fR file header \& must be similar to the following: \&\fB 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 \&\fR \&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 \fB .pdo\fR file at present. \&By default, the output files are \& \fB \-o\fR PMF output file \& \fB \-hist\fR Histograms output file \&Always check whether the histograms sufficiently overlap. \&The umbrella potential is assumed to be harmonic and the force constants are \&read from the \fB .tpr\fR or \fB .pdo\fR files. If a non\-harmonic umbrella force was applied \&a tabulated potential can be provided with \fB \-tab\fR. \&WHAM OPTIONS \-\-\-\-\-\-\-\-\-\-\-\- \& \fB \-bins\fR Number of bins used in analysis \& \fB \-temp\fR Temperature in the simulations \& \fB \-tol\fR Stop iteration if profile (probability) changed less than tolerance \& \fB \-auto\fR Automatic determination of boundaries \& \fB \-min,\-max\fR Boundaries of the profile \&The data points that are used to compute the profile \&can be restricted with options \fB \-b\fR, \fB \-e\fR, and \fB \-dt\fR. \&Adjust \fB \-b\fR to ensure sufficient equilibration in each \&umbrella window. \&With \fB \-log\fR (default) the profile is written in energy units, otherwise \&(with \fB \-nolog\fR) as probability. The unit can be specified with \fB \-unit\fR. \&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 \fB \-zprof0\fR (useful with bootstrapping, see below). \&For cyclic or periodic reaction coordinates (dihedral angle, channel PMF \&without osmotic gradient), the option \fB \-cycl\fR is useful. \fB g_wham\fR 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 \fB \-sym\fR symmetrizes the profile around z=0 before output, \&which may be useful for, e.g. membranes. \&AUTOCORRELATIONS \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \&With \fB \-ac\fR, \fB g_wham\fR 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 \fB \-oiact\fR. In verbose mode, all \&autocorrelation functions (ACFs) are written to \fB hist_autocorr.xvg\fR. \&Because the IACTs can be severely underestimated in case of limited \&sampling, option \fB \-acsig\fR allows one to smooth the IACTs along the \&reaction coordinate with a Gaussian (sigma provided with \fB \-acsig\fR, \&see output in \fB iact.xvg\fR). 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 \fB g_analyze\fR and provide them to \fB g_wham\fR with the file \&\fB iact\-in.dat\fR (option \fB \-iiact\fR), which should contain one line per \&input file (\fB .pdo\fR or pullx/f file) and one column per pull group in the respective file. \&ERROR ANALYSIS \-\-\-\-\-\-\-\-\-\-\-\-\-\- \&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. \&\fB \-nBootstrap\fR defines the number of bootstraps (use, e.g., 100). \&Four bootstrapping methods are supported and \&selected with \fB \-bs\-method\fR. \& (1) \fB b\-hist\fR Default: complete histograms are considered as independent \&data points, and the bootstrap is carried out by assigning random weights to the \&histograms ("Bayesian bootstrap"). Note that each point along the reaction coordinate \&must be covered by multiple independent histograms (e.g. 10 histograms), otherwise the \&statistical error is underestimated. \& (2) \fB hist\fR Complete histograms are considered as independent data points. \&For each bootstrap, N histograms are randomly chosen from the N given histograms \&(allowing duplication, i.e. sampling with replacement). \&To avoid gaps without data along the reaction coordinate blocks of histograms \&(\fB \-histbs\-block\fR) may be defined. In that case, the given histograms are \÷d 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 underestimated. \& (3) \fB traj\fR The given histograms are used to generate new random trajectories, \&such that the generated data points are distributed according the given histograms \&and properly autocorrelated. The autocorrelation time (ACT) for each window must be \&known, so use \fB \-ac\fR or provide the ACT with \fB \-iiact\fR. If the ACT of all \&windows are identical (and known), you can also provide them with \fB \-bs\-tau\fR. \&Note that this method may severely underestimate the error in case of limited sampling, \&that is if individual histograms do not represent the complete phase space at \&the respective positions. \& (4) \fB traj\-gauss\fR The same as method \fB traj\fR, but the trajectories are \¬ bootstrapped from the umbrella histograms but from Gaussians with the average \&and width of the umbrella histograms. That method yields similar error estimates \&like method \fB traj\fR. Bootstrapping output: \& \fB \-bsres\fR Average profile and standard deviations \& \fB \-bsprof\fR All bootstrapping profiles \&With \fB \-vbs\fR (verbose bootstrapping), the histograms of each bootstrap are written, \&and, with bootstrap method \fB traj\fR, the cumulative distribution functions of \&the histograms. .SH FILES .BI "\-ix" " pullx\-files.dat" .B Input, Opt. Generic data file .BI "\-if" " pullf\-files.dat" .B Input, Opt. Generic data file .BI "\-it" " tpr\-files.dat" .B Input, Opt. Generic data file .BI "\-ip" " pdo\-files.dat" .B Input, Opt. Generic data file .BI "\-o" " profile.xvg" .B Output xvgr/xmgr file .BI "\-hist" " histo.xvg" .B Output xvgr/xmgr file .BI "\-oiact" " iact.xvg" .B Output, Opt. xvgr/xmgr file .BI "\-iiact" " iact\-in.dat" .B Input, Opt. Generic data file .BI "\-bsres" " bsResult.xvg" .B Output, Opt. xvgr/xmgr file .BI "\-bsprof" " bsProfs.xvg" .B Output, Opt. xvgr/xmgr file .BI "\-tab" " umb\-pot.dat" .B Input, Opt. Generic data file .SH OTHER OPTIONS .BI "\-[no]h" "no " Print help info and quit .BI "\-[no]version" "no " Print version info and quit .BI "\-nice" " int" " 19" Set the nicelevel .BI "\-xvg" " enum" " xmgrace" xvg plot formatting: \fB xmgrace\fR, \fB xmgr\fR or \fB none\fR .BI "\-min" " real" " 0 " Minimum coordinate in profile .BI "\-max" " real" " 0 " Maximum coordinate in profile .BI "\-[no]auto" "yes " Determine min and max automatically .BI "\-bins" " int" " 200" Number of bins in profile .BI "\-temp" " real" " 298 " Temperature .BI "\-tol" " real" " 1e\-06 " Tolerance .BI "\-[no]v" "no " Verbose mode .BI "\-b" " real" " 50 " First time to analyse (ps) .BI "\-e" " real" " 1e+20 " Last time to analyse (ps) .BI "\-dt" " real" " 0 " Analyse only every dt ps .BI "\-[no]histonly" "no " Write histograms and exit .BI "\-[no]boundsonly" "no " Determine min and max and exit (with \fB \-auto\fR) .BI "\-[no]log" "yes " Calculate the log of the profile before printing .BI "\-unit" " enum" " kJ" Energy unit in case of log output: \fB kJ\fR, \fB kCal\fR or \fB kT\fR .BI "\-zprof0" " real" " 0 " Define profile to 0.0 at this position (with \fB \-log\fR) .BI "\-[no]cycl" "no " Create cyclic/periodic profile. Assumes min and max are the same point. .BI "\-[no]sym" "no " Symmetrize profile around z=0 .BI "\-[no]ac" "no " Calculate integrated autocorrelation times and use in wham .BI "\-acsig" " real" " 0 " Smooth autocorrelation times along reaction coordinate with Gaussian of this sigma .BI "\-ac\-trestart" " real" " 1 " When computing autocorrelation functions, restart computing every .. (ps) .BI "\-nBootstrap" " int" " 0" nr of bootstraps to estimate statistical uncertainty (e.g., 200) .BI "\-bs\-method" " enum" " b\-hist" Bootstrap method: \fB b\-hist\fR, \fB hist\fR, \fB traj\fR or \fB traj\-gauss\fR .BI "\-bs\-tau" " real" " 0 " Autocorrelation time (ACT) assumed for all histograms. Use option \fB \-ac\fR if ACT is unknown. .BI "\-bs\-seed" " int" " \-1" Seed for bootstrapping. (\-1 = use time) .BI "\-histbs\-block" " int" " 8" When mixing histograms only mix within blocks of \fB \-histbs\-block\fR. .BI "\-[no]vbs" "no " Verbose bootstrapping. Print the CDFs and a histogram file for each bootstrap. .SH SEE ALSO .BR gromacs(7) More information about \fBGROMACS\fR is available at <\fIhttp://www.gromacs.org/\fR>.