1 .TH g_wham 1 "Mon 4 Apr 2011" "" "GROMACS suite, VERSION 4.5.4-dev-20110404-bc5695c"
3 g_wham - weighted histogram analysis after umbrella sampling
5 .B VERSION 4.5.4-dev-20110404-bc5695c
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 "
20 .BI "\-[no]version" ""
33 .BI "\-[no]histonly" ""
34 .BI "\-[no]boundsonly" ""
37 .BI "\-zprof0" " real "
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 "
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).
56 \&At present, three input modes are supported.
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
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:
77 \& Component selection: 0 0 1
81 \& Ref. Group 'TestAtom'
83 \& Nr. of pull groups 2
85 \& Group 1 'GR1' Umb. Pos. 5.0 Umb. Cons. 1000.0
87 \& Group 2 'GR2' Umb. Pos. 2.0 Umb. Cons. 500.0
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.
99 \&By default, the output files are
101 \& \fB \-o\fR PMF output file
103 \& \fB \-hist\fR Histograms output file
105 \&Always check whether the histograms sufficiently overlap.
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.
114 \-\-\-\-\-\-\-\-\-\-\-\-
116 \& \fB \-bins\fR Number of bins used in analysis
118 \& \fB \-temp\fR Temperature in the simulations
120 \& \fB \-tol\fR Stop iteration if profile (probability) changed less than tolerance
122 \& \fB \-auto\fR Automatic determination of boundaries
124 \& \fB \-min,\-max\fR Boundaries of the profile
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
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).
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.
145 \&Option \fB \-sym\fR symmetrizes the profile around z=0 before output,
146 \&which may be useful for, e.g. membranes.
150 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
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.
170 \-\-\-\-\-\-\-\-\-\-\-\-\-\-
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.
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.
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.
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 \÷d 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.
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.
205 \& (4) \fB traj\-gauss\fR The same as method \fB traj\fR, but the trajectories are
206 \¬ 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.
210 Bootstrapping output:
212 \& \fB \-bsres\fR Average profile and standard deviations
214 \& \fB \-bsprof\fR All bootstrapping profiles
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
220 .BI "\-ix" " pullx\-files.dat"
224 .BI "\-if" " pullf\-files.dat"
228 .BI "\-it" " tpr\-files.dat"
232 .BI "\-ip" " pdo\-files.dat"
236 .BI "\-o" " profile.xvg"
240 .BI "\-hist" " histo.xvg"
244 .BI "\-oiact" " iact.xvg"
248 .BI "\-iiact" " iact\-in.dat"
252 .BI "\-bsres" " bsResult.xvg"
256 .BI "\-bsprof" " bsProfs.xvg"
260 .BI "\-tab" " umb\-pot.dat"
266 Print help info and quit
268 .BI "\-[no]version" "no "
269 Print version info and quit
271 .BI "\-nice" " int" " 19"
274 .BI "\-xvg" " enum" " xmgrace"
275 xvg plot formatting: \fB xmgrace\fR, \fB xmgr\fR or \fB none\fR
277 .BI "\-min" " real" " 0 "
278 Minimum coordinate in profile
280 .BI "\-max" " real" " 0 "
281 Maximum coordinate in profile
283 .BI "\-[no]auto" "yes "
284 Determine min and max automatically
286 .BI "\-bins" " int" " 200"
287 Number of bins in profile
289 .BI "\-temp" " real" " 298 "
292 .BI "\-tol" " real" " 1e\-06 "
298 .BI "\-b" " real" " 50 "
299 First time to analyse (ps)
301 .BI "\-e" " real" " 1e+20 "
302 Last time to analyse (ps)
304 .BI "\-dt" " real" " 0 "
305 Analyse only every dt ps
307 .BI "\-[no]histonly" "no "
308 Write histograms and exit
310 .BI "\-[no]boundsonly" "no "
311 Determine min and max and exit (with \fB \-auto\fR)
313 .BI "\-[no]log" "yes "
314 Calculate the log of the profile before printing
316 .BI "\-unit" " enum" " kJ"
317 Energy unit in case of log output: \fB kJ\fR, \fB kCal\fR or \fB kT\fR
319 .BI "\-zprof0" " real" " 0 "
320 Define profile to 0.0 at this position (with \fB \-log\fR)
322 .BI "\-[no]cycl" "no "
323 Create cyclic/periodic profile. Assumes min and max are the same point.
325 .BI "\-[no]sym" "no "
326 Symmetrize profile around z=0
329 Calculate integrated autocorrelation times and use in wham
331 .BI "\-acsig" " real" " 0 "
332 Smooth autocorrelation times along reaction coordinate with Gaussian of this sigma
334 .BI "\-ac\-trestart" " real" " 1 "
335 When computing autocorrelation functions, restart computing every .. (ps)
337 .BI "\-nBootstrap" " int" " 0"
338 nr of bootstraps to estimate statistical uncertainty (e.g., 200)
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
343 .BI "\-bs\-tau" " real" " 0 "
344 Autocorrelation time (ACT) assumed for all histograms. Use option \fB \-ac\fR if ACT is unknown.
346 .BI "\-bs\-seed" " int" " \-1"
347 Seed for bootstrapping. (\-1 = use time)
349 .BI "\-histbs\-block" " int" " 8"
350 When mixing histograms only mix within blocks of \fB \-histbs\-block\fR.
352 .BI "\-[no]vbs" "no "
353 Verbose bootstrapping. Print the CDFs and a histogram file for each bootstrap.
358 More information about \fBGROMACS\fR is available at <\fIhttp://www.gromacs.org/\fR>.