share/html/online/g_wham.html

   1 <HTML>
   2 <HEAD>
   3 <TITLE>g_wham</TITLE>
   4 <LINK rel=stylesheet href="style.css" type="text/css">
   5 <BODY text="#000000" bgcolor="#FFFFFF" link="#0000FF" vlink="#990000" alink="#FF0000">
   6 <TABLE WIDTH="98%" NOBORDER >
   7 <TR><TD WIDTH=400>
   8 <TABLE WIDTH=400 NOBORDER>
   9 <TD WIDTH=116>
  10 <a href="http://www.gromacs.org/"><img SRC="../images/gmxlogo_small.png"BORDER=0 </a></td>
  11 <td ALIGN=LEFT VALIGN=TOP WIDTH=280><br><h2>g_wham</h2><font size=-1><A HREF="../online.html">Main Table of Contents</A></font><br><br></td>
  12 </TABLE></TD><TD WIDTH="*" ALIGN=RIGHT VALIGN=BOTTOM><p><B>VERSION 4.5<br>
  13 Thu 26 Aug 2010</B></td></tr></TABLE>
  14 <HR>
  15 <H3>Description</H3>
  16 <p>
  17 This is an analysis program that implements the Weighted
  18 Histogram Analysis Method (WHAM). It is intended to analyze
  19 output files generated by umbrella sampling simulations to
  20 compute a potential of mean force (PMF). <p>
  21 At present, three input modes are supported:<br>
  22 <tt>*</tt> With option <tt>-it</tt>, the user provides a file which contains the
  23   filenames of the umbrella simulation run-input files (<a href="tpr.html">tpr</a> files),
  24   AND, with option -ix, a file which contains filenames of
  25   the pullx <a href="mdrun.html">mdrun</a> output files. The <a href="tpr.html">tpr</a> and pullx files must
  26   be in corresponding order, i.e. the first <a href="tpr.html">tpr</a> created the
  27   first pullx, etc.<br>
  28 <tt>*</tt> Same as the previous input mode, except that the the user
  29   provides the pull force ouput file names (pullf.<a href="xvg.html">xvg</a>) with option -if.
  30   From the pull force the position in the ubrella potential is
  31   computed. This does not work with tabulated umbrella potentials.
  32 <tt>*</tt> With option <tt>-ip</tt>, the user provides filenames of (gzipped) pdo files, i.e.
  33   the gromacs 3.3 umbrella output files. If you have some unusual
  34   reaction coordinate you may also generate your own pdo files and
  35   feed them with the -ip option into to g_wham. The pdo file header
  36   must be similar to the folowing:<br>
  37 <tt># UMBRELLA      3.0<br>
  38 # Component selection: 0 0 1<br>
  39 # nSkip 1<br>
  40 # Ref. Group 'TestAtom'<br>
  41 # Nr. of pull groups 2<br>
  42 # Group 1 'GR1'  Umb. Pos. 5.0 Umb. Cons. 1000.0<br>
  43 # Group 2 'GR2'  Umb. Pos. 2.0 Umb. Cons. 500.0<br>
  44 #####</tt><br>
  45   Nr of pull groups, umbrella positions, force constants, and names
  46   may (of course) differ. Following the header, a time column and
  47   a data columns for each pull group follow (i.e. the displacement
  48   with respect to the umbrella center). Up to four pull groups are possible
  49   at present.<p>
  50 By default, the output files are<br>
  51   <tt>-o</tt>      PMF output file<br>
  52   <tt>-hist</tt>   histograms output file<p>
  53 The umbrella potential is assumed to be harmonic and the force constants are
  54 read from the <a href="tpr.html">tpr</a> or pdo files. If a non-harmonic umbrella force was applied
  55 a tabulated potential can be provied with -tab.<p>
  56 WHAM OPTIONS<p>
  57   <tt>-bins</tt>   Nr of bins used in analysis<br>
  58   <tt>-temp</tt>   Temperature in the simulations<br>
  59   <tt>-tol</tt>    Stop iteration if profile (probability) changed less than tolerance<br>
  60   <tt>-auto</tt>   Automatic determination of boudndaries<br>
  61   <tt>-min,-max</tt>   Boundaries of the profile <br>
  62 The data points which are used
  63 to compute the profile can be restricted with options -b, -e, and -dt.
  64 Play particularly with -b to ensure sufficient equilibration in each
  65 umbrella window!<p>
  66 With -<a href="log.html">log</a> (default) the profile is written in energy units, otherwise (-nolog) as
  67 probability. The unit can be specified with -unit. With energy output,
  68 the energy in the first bin is defined to be zero. If you want the free energy at a different
  69 position to be zero, choose with -zprof0 (useful with bootstrapping, see below).<p>
  70 For cyclic (or periodic) reaction coordinates (dihedral angle, channel PMF
  71 without osmotic gradient), -cycl is useful.<br>
  72 <tt>-cycl yes</tt>        min and max are assumed to
  73 be neighboring points and histogram points outside min and max are mapped into
  74 the interval [min,max] (compare histogram output). <br>
  75 <tt>-cycl weighted</tt>   First, a non-cyclic profile is computed. Subsequently,
  76 periodicity is enforced by adding corrections dG(i) between neighboring bins
  77 i and i+1. The correction is chosen proportional to 1/[n(i)*n(i+1)]^alpha, where
  78 n(i) denotes the total nr of data points in bin i as collected from all histograms.
  79 alpha is defined with -alpha. The corrections are written to the file defined by -wcorr.
  80  (Compare Hub and de Groot, PNAS 105:1198 (2008))<p>
  81 ERROR ANALYSIS<br>
  82 Statistical errors may be estimated with bootstrap analysis. Use it with care,
  83 otherwise the statistical error may be substantially undererstimated !!<br>
  84 <tt>-nBootstrap</tt> defines the nr of bootstraps. Two bootstrapping modes are supported.<br>
  85 <tt>-histbs</tt>    Complete histograms are considered as independent data points (default). For each
  86 bootstrap, N histograms are randomly chosen from the N given histograms (allowing duplication).
  87 To avoid gaps without data along the reaction coordinate blocks of histograms (-histbs-block)
  88 may be defined. In that case, the given histograms are divided into blocks and
  89 only histograms within each block are mixed. Note that the histograms
  90 within each block must be representative for all possible histograms, otherwise the
  91 statistical error is undererstimated!<br>
  92 <tt>-nohistbs</tt>  The given histograms are used to generate new random histograms,
  93 such that the generated data points are distributed according the given histograms. The number
  94 of points generated for each bootstrap histogram can be controlled with -bs-dt.
  95 Note that one data point should be generated for each *independent* point in the given
  96 histograms. With the long autocorrelations in MD simulations, this procedure may
  97 easily understimate the error!<br>
  98 Bootstrapping output:<br>
  99 <tt>-bsres</tt>   Average profile and standard deviations<br>
 100 <tt>-bsprof</tt>  All bootstrapping profiles<br>
 101 With <tt>-vbs</tt> (verbose bootstrapping), the histograms of each bootstrap are written, and,
 102 with <tt>-nohistBS</tt>, the cummulants of the histogram.
 103 <P>
 104 <H3>Files</H3>
 105 <TABLE BORDER=1 CELLSPACING=0 CELLPADDING=2>
 106 <TR><TH>option</TH><TH>filename</TH><TH>type</TH><TH>description</TH></TR>
 107 <TR><TD ALIGN=RIGHT> <b><tt>-ix</tt></b> </TD><TD ALIGN=RIGHT> <tt><a href="dat.html">pullx-files.dat</a></tt> </TD><TD> Input, Opt. </TD><TD> Generic data file </TD></TR>
 108 <TR><TD ALIGN=RIGHT> <b><tt>-if</tt></b> </TD><TD ALIGN=RIGHT> <tt><a href="dat.html">pullf-files.dat</a></tt> </TD><TD> Input, Opt. </TD><TD> Generic data file </TD></TR>
 109 <TR><TD ALIGN=RIGHT> <b><tt>-it</tt></b> </TD><TD ALIGN=RIGHT> <tt><a href="dat.html">tpr-files.dat</a></tt> </TD><TD> Input, Opt. </TD><TD> Generic data file </TD></TR>
 110 <TR><TD ALIGN=RIGHT> <b><tt>-ip</tt></b> </TD><TD ALIGN=RIGHT> <tt><a href="dat.html">pdo-files.dat</a></tt> </TD><TD> Input, Opt. </TD><TD> Generic data file </TD></TR>
 111 <TR><TD ALIGN=RIGHT> <b><tt>-o</tt></b> </TD><TD ALIGN=RIGHT> <tt><a href="xvg.html"> profile.xvg</a></tt> </TD><TD> Output </TD><TD> xvgr/xmgr file </TD></TR>
 112 <TR><TD ALIGN=RIGHT> <b><tt>-hist</tt></b> </TD><TD ALIGN=RIGHT> <tt><a href="xvg.html">   histo.xvg</a></tt> </TD><TD> Output </TD><TD> xvgr/xmgr file </TD></TR>
 113 <TR><TD ALIGN=RIGHT> <b><tt>-bsres</tt></b> </TD><TD ALIGN=RIGHT> <tt><a href="xvg.html">bsResult.xvg</a></tt> </TD><TD> Output, Opt. </TD><TD> xvgr/xmgr file </TD></TR>
 114 <TR><TD ALIGN=RIGHT> <b><tt>-bsprof</tt></b> </TD><TD ALIGN=RIGHT> <tt><a href="xvg.html"> bsProfs.xvg</a></tt> </TD><TD> Output, Opt. </TD><TD> xvgr/xmgr file </TD></TR>
 115 <TR><TD ALIGN=RIGHT> <b><tt>-tab</tt></b> </TD><TD ALIGN=RIGHT> <tt><a href="dat.html"> umb-pot.dat</a></tt> </TD><TD> Input, Opt. </TD><TD> Generic data file </TD></TR>
 116 <TR><TD ALIGN=RIGHT> <b><tt>-wcorr</tt></b> </TD><TD ALIGN=RIGHT> <tt><a href="xvg.html">cycl-corr.xvg</a></tt> </TD><TD> Input, Opt. </TD><TD> xvgr/xmgr file </TD></TR>
 117 </TABLE>
 118 <P>
 119 <H3>Other options</H3>
 120 <TABLE BORDER=1 CELLSPACING=0 CELLPADDING=2>
 121 <TR><TH>option</TH><TH>type</TH><TH>default</TH><TH>description</TH></TR>
 122 <TR><TD ALIGN=RIGHT> <b><tt>-[no]h</tt></b> </TD><TD ALIGN=RIGHT> gmx_bool </TD><TD ALIGN=RIGHT> <tt>no    </tt> </TD><TD> Print help info and quit </TD></TD>
 123 <TR><TD ALIGN=RIGHT> <b><tt>-[no]version</tt></b> </TD><TD ALIGN=RIGHT> gmx_bool </TD><TD ALIGN=RIGHT> <tt>no    </tt> </TD><TD> Print version info and quit </TD></TD>
 124 <TR><TD ALIGN=RIGHT> <b><tt>-nice</tt></b> </TD><TD ALIGN=RIGHT> int </TD><TD ALIGN=RIGHT> <tt>19</tt> </TD><TD> Set the nicelevel </TD></TD>
 125 <TR><TD ALIGN=RIGHT> <b><tt>-xvg</tt></b> </TD><TD ALIGN=RIGHT> enum </TD><TD ALIGN=RIGHT> <tt>xmgrace</tt> </TD><TD> <a href="xvg.html">xvg</a> plot formatting: <tt>xmgrace</tt>, <tt>xmgr</tt> or <tt>none</tt> </TD></TD>
 126 <TR><TD ALIGN=RIGHT> <b><tt>-min</tt></b> </TD><TD ALIGN=RIGHT> real </TD><TD ALIGN=RIGHT> <tt>0     </tt> </TD><TD> Minimum coordinate in profile </TD></TD>
 127 <TR><TD ALIGN=RIGHT> <b><tt>-max</tt></b> </TD><TD ALIGN=RIGHT> real </TD><TD ALIGN=RIGHT> <tt>0     </tt> </TD><TD> Maximum coordinate in profile </TD></TD>
 128 <TR><TD ALIGN=RIGHT> <b><tt>-[no]auto</tt></b> </TD><TD ALIGN=RIGHT> gmx_bool </TD><TD ALIGN=RIGHT> <tt>yes   </tt> </TD><TD> determine min and max automatically </TD></TD>
 129 <TR><TD ALIGN=RIGHT> <b><tt>-bins</tt></b> </TD><TD ALIGN=RIGHT> int </TD><TD ALIGN=RIGHT> <tt>200</tt> </TD><TD> Number of bins in profile </TD></TD>
 130 <TR><TD ALIGN=RIGHT> <b><tt>-temp</tt></b> </TD><TD ALIGN=RIGHT> real </TD><TD ALIGN=RIGHT> <tt>298   </tt> </TD><TD> Temperature </TD></TD>
 131 <TR><TD ALIGN=RIGHT> <b><tt>-tol</tt></b> </TD><TD ALIGN=RIGHT> real </TD><TD ALIGN=RIGHT> <tt>1e-06 </tt> </TD><TD> Tolerance </TD></TD>
 132 <TR><TD ALIGN=RIGHT> <b><tt>-[no]v</tt></b> </TD><TD ALIGN=RIGHT> gmx_bool </TD><TD ALIGN=RIGHT> <tt>no    </tt> </TD><TD> verbose mode </TD></TD>
 133 <TR><TD ALIGN=RIGHT> <b><tt>-b</tt></b> </TD><TD ALIGN=RIGHT> real </TD><TD ALIGN=RIGHT> <tt>50    </tt> </TD><TD> first time to analyse (ps) </TD></TD>
 134 <TR><TD ALIGN=RIGHT> <b><tt>-e</tt></b> </TD><TD ALIGN=RIGHT> real </TD><TD ALIGN=RIGHT> <tt>1e+20 </tt> </TD><TD> last time to analyse (ps) </TD></TD>
 135 <TR><TD ALIGN=RIGHT> <b><tt>-dt</tt></b> </TD><TD ALIGN=RIGHT> real </TD><TD ALIGN=RIGHT> <tt>0     </tt> </TD><TD> Analyse only every dt ps </TD></TD>
 136 <TR><TD ALIGN=RIGHT> <b><tt>-[no]histonly</tt></b> </TD><TD ALIGN=RIGHT> gmx_bool </TD><TD ALIGN=RIGHT> <tt>no    </tt> </TD><TD> Write histograms and exit </TD></TD>
 137 <TR><TD ALIGN=RIGHT> <b><tt>-[no]boundsonly</tt></b> </TD><TD ALIGN=RIGHT> gmx_bool </TD><TD ALIGN=RIGHT> <tt>no    </tt> </TD><TD> Determine min and max and exit (with -auto) </TD></TD>
 138 <TR><TD ALIGN=RIGHT> <b><tt>-[no]log</tt></b> </TD><TD ALIGN=RIGHT> gmx_bool </TD><TD ALIGN=RIGHT> <tt>yes   </tt> </TD><TD> Calculate the <a href="log.html">log</a> of the profile before printing </TD></TD>
 139 <TR><TD ALIGN=RIGHT> <b><tt>-unit</tt></b> </TD><TD ALIGN=RIGHT> enum </TD><TD ALIGN=RIGHT> <tt>kJ</tt> </TD><TD> energy unit in case of <a href="log.html">log</a> output: <tt>kJ</tt>, <tt>kCal</tt> or <tt>kT</tt> </TD></TD>
 140 <TR><TD ALIGN=RIGHT> <b><tt>-zprof0</tt></b> </TD><TD ALIGN=RIGHT> real </TD><TD ALIGN=RIGHT> <tt>0     </tt> </TD><TD> Define profile to 0.0 at this position (with -<a href="log.html">log</a>) </TD></TD>
 141 <TR><TD ALIGN=RIGHT> <b><tt>-cycl</tt></b> </TD><TD ALIGN=RIGHT> enum </TD><TD ALIGN=RIGHT> <tt>no</tt> </TD><TD> Create cyclic/periodic profile. Assumes min and max are the same point.: <tt>no</tt>, <tt>yes</tt> or <tt>weighted</tt> </TD></TD>
 142 <TR><TD ALIGN=RIGHT> <b><tt>-alpha</tt></b> </TD><TD ALIGN=RIGHT> real </TD><TD ALIGN=RIGHT> <tt>2     </tt> </TD><TD> for '-cycl weighted', set parameter alpha </TD></TD>
 143 <TR><TD ALIGN=RIGHT> <b><tt>-[no]flip</tt></b> </TD><TD ALIGN=RIGHT> gmx_bool </TD><TD ALIGN=RIGHT> <tt>no    </tt> </TD><TD> Combine halves of profile (not supported) </TD></TD>
 144 <TR><TD ALIGN=RIGHT> <b><tt>-[no]hist-eq</tt></b> </TD><TD ALIGN=RIGHT> gmx_bool </TD><TD ALIGN=RIGHT> <tt>no    </tt> </TD><TD> Enforce equal weight for all histograms. (Non-Weighed-HAM) </TD></TD>
 145 <TR><TD ALIGN=RIGHT> <b><tt>-nBootstrap</tt></b> </TD><TD ALIGN=RIGHT> int </TD><TD ALIGN=RIGHT> <tt>0</tt> </TD><TD> nr of bootstraps to estimate statistical uncertainty </TD></TD>
 146 <TR><TD ALIGN=RIGHT> <b><tt>-bs-dt</tt></b> </TD><TD ALIGN=RIGHT> real </TD><TD ALIGN=RIGHT> <tt>0     </tt> </TD><TD> timestep for synthetic bootstrap histograms (ps). Ensure independent data points! </TD></TD>
 147 <TR><TD ALIGN=RIGHT> <b><tt>-bs-seed</tt></b> </TD><TD ALIGN=RIGHT> int </TD><TD ALIGN=RIGHT> <tt>-1</tt> </TD><TD> seed for bootstrapping. (-1 = use time) </TD></TD>
 148 <TR><TD ALIGN=RIGHT> <b><tt>-[no]histbs</tt></b> </TD><TD ALIGN=RIGHT> gmx_bool </TD><TD ALIGN=RIGHT> <tt>yes   </tt> </TD><TD> In bootstrapping, consider complete histograms as one data point. Accounts better for long autocorrelations. </TD></TD>
 149 <TR><TD ALIGN=RIGHT> <b><tt>-histbs-block</tt></b> </TD><TD ALIGN=RIGHT> int </TD><TD ALIGN=RIGHT> <tt>8</tt> </TD><TD> when mixin histograms only mix within blocks of -histBS_block. </TD></TD>
 150 <TR><TD ALIGN=RIGHT> <b><tt>-[no]vbs</tt></b> </TD><TD ALIGN=RIGHT> gmx_bool </TD><TD ALIGN=RIGHT> <tt>no    </tt> </TD><TD> verbose bootstrapping. Print the cummulants and a histogram file for each bootstrap. </TD></TD>
 151 </TABLE>
 152 <P>
 153 <hr>
 154 <div ALIGN=RIGHT>
 155 <font size="-1"><a href="http://www.gromacs.org">http://www.gromacs.org</a></font><br>
 156 <font size="-1"><a href="mailto:gromacs@gromacs.org">gromacs@gromacs.org</a></font><br>
 157 </div>
 158 </BODY>