man/man1/g_wham.1

   1 .TH g_wham 1 "Mon 4 Apr 2011" "" "GROMACS suite, VERSION 4.5.4-dev-20110404-bc5695c"
   2 .SH NAME
   3 g_wham - weighted histogram analysis after umbrella sampling
   4
   5 .B VERSION 4.5.4-dev-20110404-bc5695c
   6 .SH SYNOPSIS
   7 \f3g_wham\fP
   8 .BI "\-ix" " pullx\-files.dat "
   9 .BI "\-if" " pullf\-files.dat "
  10 .BI "\-it" " tpr\-files.dat "
  11 .BI "\-ip" " pdo\-files.dat "
  12 .BI "\-o" " profile.xvg "
  13 .BI "\-hist" " histo.xvg "
  14 .BI "\-oiact" " iact.xvg "
  15 .BI "\-iiact" " iact\-in.dat "
  16 .BI "\-bsres" " bsResult.xvg "
  17 .BI "\-bsprof" " bsProfs.xvg "
  18 .BI "\-tab" " umb\-pot.dat "
  19 .BI "\-[no]h" ""
  20 .BI "\-[no]version" ""
  21 .BI "\-nice" " int "
  22 .BI "\-xvg" " enum "
  23 .BI "\-min" " real "
  24 .BI "\-max" " real "
  25 .BI "\-[no]auto" ""
  26 .BI "\-bins" " int "
  27 .BI "\-temp" " real "
  28 .BI "\-tol" " real "
  29 .BI "\-[no]v" ""
  30 .BI "\-b" " real "
  31 .BI "\-e" " real "
  32 .BI "\-dt" " real "
  33 .BI "\-[no]histonly" ""
  34 .BI "\-[no]boundsonly" ""
  35 .BI "\-[no]log" ""
  36 .BI "\-unit" " enum "
  37 .BI "\-zprof0" " real "
  38 .BI "\-[no]cycl" ""
  39 .BI "\-[no]sym" ""
  40 .BI "\-[no]ac" ""
  41 .BI "\-acsig" " real "
  42 .BI "\-ac\-trestart" " real "
  43 .BI "\-nBootstrap" " int "
  44 .BI "\-bs\-method" " enum "
  45 .BI "\-bs\-tau" " real "
  46 .BI "\-bs\-seed" " int "
  47 .BI "\-histbs\-block" " int "
  48 .BI "\-[no]vbs" ""
  49 .SH DESCRIPTION
  50 \&This is an analysis program that implements the Weighted
  51 \&Histogram Analysis Method (WHAM). It is intended to analyze
  52 \&output files generated by umbrella sampling simulations to
  53 \&compute a potential of mean force (PMF).
  54
  55
  56 \&At present, three input modes are supported.
  57
  58 \&\fB *\fR With option \fB \-it\fR, the user provides a file which contains the
  59 \& file names of the umbrella simulation run\-input files (\fB .tpr\fR files),
  60 \& AND, with option \fB \-ix\fR, a file which contains file names of
  61 \& the pullx \fB mdrun\fR output files. The \fB .tpr\fR and pullx files must
  62 \& be in corresponding order, i.e. the first \fB .tpr\fR created the
  63 \& first pullx, etc.
  64
  65 \&\fB *\fR Same as the previous input mode, except that the the user
  66 \& provides the pull force output file names (\fB pullf.xvg\fR) with option \fB \-if\fR.
  67 \& From the pull force the position in the umbrella potential is
  68 \& computed. This does not work with tabulated umbrella potentials.
  69 \fB *\fR With option \fB \-ip\fR, the user provides file names of (gzipped) \fB .pdo\fR files, i.e.
  70 \& 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
  71 \& feed them with the \fB \-ip\fR option into to \fB g_wham\fR. The \fB .pdo\fR file header
  72 \& must be similar to the following:
  73
  74
  75 \&\fB  UMBRELLA      3.0
  76
  77 \& Component selection: 0 0 1
  78
  79 \& nSkip 1
  80
  81 \& Ref. Group 'TestAtom'
  82
  83 \& Nr. of pull groups 2
  84
  85 \& Group 1 'GR1'  Umb. Pos. 5.0 Umb. Cons. 1000.0
  86
  87 \& Group 2 'GR2'  Umb. Pos. 2.0 Umb. Cons. 500.0
  88
  89 \&\fR
  90
  91
  92 \&The number of pull groups, umbrella positions, force constants, and names
  93 \&may (of course) differ. Following the header, a time column and
  94 \&a data column for each pull group follows (i.e. the displacement
  95 \&with respect to the umbrella center). Up to four pull groups are possible
  96 \&per \fB .pdo\fR file at present.
  97
  98
  99 \&By default, the output files are
 100
 101 \&  \fB \-o\fR      PMF output file
 102
 103 \&  \fB \-hist\fR   Histograms output file
 104
 105 \&Always check whether the histograms sufficiently overlap.
 106
 107
 108 \&The umbrella potential is assumed to be harmonic and the force constants are
 109 \&read from the \fB .tpr\fR or \fB .pdo\fR files. If a non\-harmonic umbrella force was applied
 110 \&a tabulated potential can be provided with \fB \-tab\fR.
 111
 112
 113 \&WHAM OPTIONS
 114 \-\-\-\-\-\-\-\-\-\-\-\-
 115
 116 \&  \fB \-bins\fR   Number of bins used in analysis
 117
 118 \&  \fB \-temp\fR   Temperature in the simulations
 119
 120 \&  \fB \-tol\fR    Stop iteration if profile (probability) changed less than tolerance
 121
 122 \&  \fB \-auto\fR   Automatic determination of boundaries
 123
 124 \&  \fB \-min,\-max\fR   Boundaries of the profile
 125
 126 \&The data points that are used to compute the profile
 127 \&can be restricted with options \fB \-b\fR, \fB \-e\fR, and \fB \-dt\fR.
 128 \&Adjust \fB \-b\fR to ensure sufficient equilibration in each
 129 \&umbrella window.
 130
 131
 132 \&With \fB \-log\fR (default) the profile is written in energy units, otherwise
 133 \&(with \fB \-nolog\fR) as probability. The unit can be specified with \fB \-unit\fR.
 134 \&With energy output, the energy in the first bin is defined to be zero.
 135 \&If you want the free energy at a different
 136 \&position to be zero, set \fB \-zprof0\fR (useful with bootstrapping, see below).
 137
 138
 139 \&For cyclic or periodic reaction coordinates (dihedral angle, channel PMF
 140 \&without osmotic gradient), the option \fB \-cycl\fR is useful. \fB g_wham\fR will make use of the
 141 \&periodicity of the system and generate a periodic PMF. The first and the last bin of the
 142 \&reaction coordinate will assumed be be neighbors.
 143
 144
 145 \&Option \fB \-sym\fR symmetrizes the profile around z=0 before output,
 146 \&which may be useful for, e.g. membranes.
 147
 148
 149 \&AUTOCORRELATIONS
 150 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 151
 152 \&With \fB \-ac\fR, \fB g_wham\fR estimates the integrated autocorrelation
 153 \&time (IACT) tau for each umbrella window and weights the respective
 154 \&window with 1/[1+2*tau/dt]. The IACTs are written
 155 \&to the file defined with \fB \-oiact\fR. In verbose mode, all
 156 \&autocorrelation functions (ACFs) are written to \fB hist_autocorr.xvg\fR.
 157 \&Because the IACTs can be severely underestimated in case of limited
 158 \&sampling, option \fB \-acsig\fR allows to smooth the IACTs along the
 159 \&reaction coordinate with a Gaussian (sigma provided with \fB \-acsig\fR,
 160 \&see output in \fB iact.xvg\fR). Note that the IACTs are estimated by simple
 161 \&integration of the ACFs while the ACFs are larger 0.05.
 162 \&If you prefer to compute the IACTs by a more sophisticated (but possibly
 163 \&less robust) method such as fitting to a double exponential, you can
 164 \&compute the IACTs with \fB g_analyze\fR and provide them to \fB g_wham\fR with the file
 165 \&\fB iact\-in.dat\fR (option \fB \-iiact\fR), which should contain one line per
 166 \&input file (\fB .pdo\fR or pullx/f file) and one column per pull group in the respective file.
 167
 168
 169 \&ERROR ANALYSIS
 170 \-\-\-\-\-\-\-\-\-\-\-\-\-\-
 171
 172 \&Statistical errors may be estimated with bootstrap analysis. Use it with care,
 173 \&otherwise the statistical error may be substantially underestimated.
 174 \&More background and examples for the bootstrap technique can be found in
 175 \&Hub, de Groot and Van der Spoel, JCTC (2010) 6: 3713\-3720.
 176
 177 \&\fB \-nBootstrap\fR defines the number of bootstraps (use, e.g., 100).
 178 \&Four bootstrapping methods are supported and
 179 \&selected with \fB \-bs\-method\fR.
 180
 181 \&  (1) \fB b\-hist\fR   Default: complete histograms are considered as independent
 182 \&data points, and the bootstrap is carried out by assigning random weights to the
 183 \&histograms ("Bayesian bootstrap"). Note that each point along the reaction coordinate
 184 \&must be covered by multiple independent histograms (e.g. 10 histograms), otherwise the
 185 \&statistical error is underestimated.
 186
 187 \&  (2) \fB hist\fR    Complete histograms are considered as independent data points.
 188 \&For each bootstrap, N histograms are randomly chosen from the N given histograms
 189 \&(allowing duplication, i.e. sampling with replacement).
 190 \&To avoid gaps without data along the reaction coordinate blocks of histograms
 191 \&(\fB \-histbs\-block\fR) may be defined. In that case, the given histograms are
 192 \&divided into blocks and only histograms within each block are mixed. Note that
 193 \&the histograms within each block must be representative for all possible histograms,
 194 \&otherwise the statistical error is underestimated.
 195
 196 \&  (3) \fB traj\fR  The given histograms are used to generate new random trajectories,
 197 \&such that the generated data points are distributed according the given histograms
 198 \&and properly autocorrelated. The autocorrelation time (ACT) for each window must be
 199 \&known, so use \fB \-ac\fR or provide the ACT with \fB \-iiact\fR. If the ACT of all
 200 \&windows are identical (and known), you can also provide them with \fB \-bs\-tau\fR.
 201 \&Note that this method may severely underestimate the error in case of limited sampling,
 202 \&that is if individual histograms do not represent the complete phase space at
 203 \&the respective positions.
 204
 205 \&  (4) \fB traj\-gauss\fR  The same as method \fB traj\fR, but the trajectories are
 206 \&not bootstrapped from the umbrella histograms but from Gaussians with the average
 207 \&and width of the umbrella histograms. That method yields similar error estimates
 208 \&like method \fB traj\fR.
 209
 210 Bootstrapping output:
 211
 212 \&  \fB \-bsres\fR   Average profile and standard deviations
 213
 214 \&  \fB \-bsprof\fR  All bootstrapping profiles
 215
 216 \&With \fB \-vbs\fR (verbose bootstrapping), the histograms of each bootstrap are written,
 217 \&and, with bootstrap method \fB traj\fR, the cumulative distribution functions of
 218 \&the histograms.
 219 .SH FILES
 220 .BI "\-ix" " pullx\-files.dat"
 221 .B Input, Opt.
 222  Generic data file
 223
 224 .BI "\-if" " pullf\-files.dat"
 225 .B Input, Opt.
 226  Generic data file
 227
 228 .BI "\-it" " tpr\-files.dat"
 229 .B Input, Opt.
 230  Generic data file
 231
 232 .BI "\-ip" " pdo\-files.dat"
 233 .B Input, Opt.
 234  Generic data file
 235
 236 .BI "\-o" " profile.xvg"
 237 .B Output
 238  xvgr/xmgr file
 239
 240 .BI "\-hist" " histo.xvg"
 241 .B Output
 242  xvgr/xmgr file
 243
 244 .BI "\-oiact" " iact.xvg"
 245 .B Output, Opt.
 246  xvgr/xmgr file
 247
 248 .BI "\-iiact" " iact\-in.dat"
 249 .B Input, Opt.
 250  Generic data file
 251
 252 .BI "\-bsres" " bsResult.xvg"
 253 .B Output, Opt.
 254  xvgr/xmgr file
 255
 256 .BI "\-bsprof" " bsProfs.xvg"
 257 .B Output, Opt.
 258  xvgr/xmgr file
 259
 260 .BI "\-tab" " umb\-pot.dat"
 261 .B Input, Opt.
 262  Generic data file
 263
 264 .SH OTHER OPTIONS
 265 .BI "\-[no]h"  "no    "
 266  Print help info and quit
 267
 268 .BI "\-[no]version"  "no    "
 269  Print version info and quit
 270
 271 .BI "\-nice"  " int" " 19"
 272  Set the nicelevel
 273
 274 .BI "\-xvg"  " enum" " xmgrace"
 275  xvg plot formatting: \fB xmgrace\fR, \fB xmgr\fR or \fB none\fR
 276
 277 .BI "\-min"  " real" " 0     "
 278  Minimum coordinate in profile
 279
 280 .BI "\-max"  " real" " 0     "
 281  Maximum coordinate in profile
 282
 283 .BI "\-[no]auto"  "yes   "
 284  Determine min and max automatically
 285
 286 .BI "\-bins"  " int" " 200"
 287  Number of bins in profile
 288
 289 .BI "\-temp"  " real" " 298   "
 290  Temperature
 291
 292 .BI "\-tol"  " real" " 1e\-06 "
 293  Tolerance
 294
 295 .BI "\-[no]v"  "no    "
 296  Verbose mode
 297
 298 .BI "\-b"  " real" " 50    "
 299  First time to analyse (ps)
 300
 301 .BI "\-e"  " real" " 1e+20 "
 302  Last time to analyse (ps)
 303
 304 .BI "\-dt"  " real" " 0     "
 305  Analyse only every dt ps
 306
 307 .BI "\-[no]histonly"  "no    "
 308  Write histograms and exit
 309
 310 .BI "\-[no]boundsonly"  "no    "
 311  Determine min and max and exit (with \fB \-auto\fR)
 312
 313 .BI "\-[no]log"  "yes   "
 314  Calculate the log of the profile before printing
 315
 316 .BI "\-unit"  " enum" " kJ"
 317  Energy unit in case of log output: \fB kJ\fR, \fB kCal\fR or \fB kT\fR
 318
 319 .BI "\-zprof0"  " real" " 0     "
 320  Define profile to 0.0 at this position (with \fB \-log\fR)
 321
 322 .BI "\-[no]cycl"  "no    "
 323  Create cyclic/periodic profile. Assumes min and max are the same point.
 324
 325 .BI "\-[no]sym"  "no    "
 326  Symmetrize profile around z=0
 327
 328 .BI "\-[no]ac"  "no    "
 329  Calculate integrated autocorrelation times and use in wham
 330
 331 .BI "\-acsig"  " real" " 0     "
 332  Smooth autocorrelation times along reaction coordinate with Gaussian of this sigma
 333
 334 .BI "\-ac\-trestart"  " real" " 1     "
 335  When computing autocorrelation functions, restart computing every .. (ps)
 336
 337 .BI "\-nBootstrap"  " int" " 0"
 338  nr of bootstraps to estimate statistical uncertainty (e.g., 200)
 339
 340 .BI "\-bs\-method"  " enum" " b\-hist"
 341  Bootstrap method: \fB b\-hist\fR, \fB hist\fR, \fB traj\fR or \fB traj\-gauss\fR
 342
 343 .BI "\-bs\-tau"  " real" " 0     "
 344  Autocorrelation time (ACT) assumed for all histograms. Use option \fB \-ac\fR if ACT is unknown.
 345
 346 .BI "\-bs\-seed"  " int" " \-1"
 347  Seed for bootstrapping. (\-1 = use time)
 348
 349 .BI "\-histbs\-block"  " int" " 8"
 350  When mixing histograms only mix within blocks of \fB \-histbs\-block\fR.
 351
 352 .BI "\-[no]vbs"  "no    "
 353  Verbose bootstrapping. Print the CDFs and a histogram file for each bootstrap.
 354
 355 .SH SEE ALSO
 356 .BR gromacs(7)
 357
 358 More information about \fBGROMACS\fR is available at <\fIhttp://www.gromacs.org/\fR>.