1GMX-WHAM(1) GROMACS GMX-WHAM(1)
2
6 gmx-wham - Perform weighted histogram analysis after umbrella sampling
7
9 gmx wham [-ix [<.dat>]] [-if [<.dat>]] [-it [<.dat>]] [-is [<.dat>]]
10 [-iiact [<.dat>]] [-tab [<.dat>]] [-o [<.xvg>]]
11 [-hist [<.xvg>]] [-oiact [<.xvg>]] [-bsres [<.xvg>]]
12 [-bsprof [<.xvg>]] [-xvg <enum>] [-min <real>] [-max <real>]
13 [-[no]auto] [-bins <int>] [-temp <real>] [-tol <real>]
14 [-[no]v] [-b <real>] [-e <real>] [-dt <real>]
15 [-[no]histonly] [-[no]boundsonly] [-[no]log] [-unit <enum>]
16 [-zprof0 <real>] [-[no]cycl] [-[no]sym] [-[no]ac]
17 [-acsig <real>] [-ac-trestart <real>] [-nBootstrap <int>]
18 [-bs-method <enum>] [-bs-tau <real>] [-bs-seed <int>]
19 [-histbs-block <int>] [-[no]vbs]
20
22 gmx wham is an analysis program that implements the Weighted Histogram
23 Analysis Method (WHAM). It is intended to analyze output files gener‐
24 ated by umbrella sampling simulations to compute a potential of mean
25 force (PMF).
26 gmx wham is currently not fully up to date. It only supports pull set‐
28 ups where the first pull coordinate(s) is/are umbrella pull coordinates
29 and, if multiple coordinates need to be analyzed, all used the same ge‐
30 ometry and dimensions. In most cases this is not an issue.
31 At present, three input modes are supported.
33 • With option -it, the user provides a file which contains the file
35 names of the umbrella simulation run-input files (.tpr files), AND,
36 with option -ix, a file which contains file names of the pullx mdrun
37 output files. The .tpr and pullx files must be in corresponding or‐
38 der, i.e. the first .tpr created the first pullx, etc.
39 • Same as the previous input mode, except that the user provides the
41 pull force output file names (pullf.xvg) with option -if. From the
42 pull force the position in the umbrella potential is computed. This
43 does not work with tabulated umbrella potentials.
44 By default, all pull coordinates found in all pullx/pullf files are
46 used in WHAM. If only some of the pull coordinates should be used, a
47 pull coordinate selection file (option -is) can be provided. The selec‐
48 tion file must contain one line for each tpr file in tpr-files.dat.
49 Each of these lines must contain one digit (0 or 1) for each pull coor‐
50 dinate in the tpr file. Here, 1 indicates that the pull coordinate is
51 used in WHAM, and 0 means it is omitted. Example: If you have three
52 tpr files, each containing 4 pull coordinates, but only pull coordi‐
53 nates 1 and 2 should be used, coordsel.dat looks like this:
54 1 1 0 0
56 1 1 0 0
57 1 1 0 0
58 By default, the output files are:
60 ``-o`` PMF output file
62 ``-hist`` Histograms output file
63 Always check whether the histograms sufficiently overlap.
65 The umbrella potential is assumed to be harmonic and the force con‐
67 stants are read from the .tpr files. If a non-harmonic umbrella force
68 was applied a tabulated potential can be provided with -tab.
69 WHAM options
71 • -bins Number of bins used in analysis
72 • -temp Temperature in the simulations
74 • -tol Stop iteration if profile (probability) changed less than
76 tolerance
77 • -auto Automatic determination of boundaries
79 • -min,-max Boundaries of the profile
81 The data points that are used to compute the profile can be restricted
83 with options -b, -e, and -dt. Adjust -b to ensure sufficient equili‐
84 bration in each umbrella window.
85 With -log (default) the profile is written in energy units, otherwise
87 (with -nolog) as probability. The unit can be specified with -unit.
88 With energy output, the energy in the first bin is defined to be zero.
89 If you want the free energy at a different position to be zero, set
90 -zprof0 (useful with bootstrapping, see below).
91 For cyclic or periodic reaction coordinates (dihedral angle, channel
93 PMF without osmotic gradient), the option -cycl is useful. gmx wham
94 will make use of the periodicity of the system and generate a periodic
95 PMF. The first and the last bin of the reaction coordinate will assumed
96 be be neighbors.
97 Option -sym symmetrizes the profile around z=0 before output, which may
99 be useful for, e.g. membranes.
100 Parallelization
102 If available, the number of OpenMP threads used by gmx wham can be con‐
103 trolled by setting the OMP_NUM_THREADS environment variable.
104 Autocorrelations
106 With -ac, gmx wham estimates the integrated autocorrelation time (IACT)
107 tau for each umbrella window and weights the respective window with
108 1/[1+2*tau/dt]. The IACTs are written to the file defined with -oiact.
109 In verbose mode, all autocorrelation functions (ACFs) are written to
110 hist_autocorr.xvg. Because the IACTs can be severely underestimated in
111 case of limited sampling, option -acsig allows one to smooth the IACTs
112 along the reaction coordinate with a Gaussian (sigma provided with -ac‐
113 sig, see output in iact.xvg). Note that the IACTs are estimated by sim‐
114 ple integration of the ACFs while the ACFs are larger 0.05. If you
115 prefer to compute the IACTs by a more sophisticated (but possibly less
116 robust) method such as fitting to a double exponential, you can compute
117 the IACTs with gmx analyze and provide them to gmx wham with the file
118 iact-in.dat (option -iiact), which should contain one line per input
119 file (pullx/pullf file) and one column per pull coordinate in the re‐
120 spective file.
121 Error analysis
123 Statistical errors may be estimated with bootstrap analysis. Use it
124 with care, otherwise the statistical error may be substantially under‐
125 estimated. More background and examples for the bootstrap technique
126 can be found in Hub, de Groot and Van der Spoel, JCTC (2010) 6:
127 3713-3720. -nBootstrap defines the number of bootstraps (use, e.g.,
128 100). Four bootstrapping methods are supported and selected with
129 -bs-method.
130 • b-hist Default: complete histograms are considered as independent
132 data points, and the bootstrap is carried out by assigning random
133 weights to the histograms ("Bayesian bootstrap"). Note that each
134 point along the reaction coordinate must be covered by multiple inde‐
135 pendent histograms (e.g. 10 histograms), otherwise the statistical
136 error is underestimated.
137 • hist Complete histograms are considered as independent data
139 points. For each bootstrap, N histograms are randomly chosen from
140 the N given histograms (allowing duplication, i.e. sampling with re‐
141 placement). To avoid gaps without data along the reaction coordinate
142 blocks of histograms (-histbs-block) may be defined. In that case,
143 the given histograms are divided into blocks and only histograms
144 within each block are mixed. Note that the histograms within each
145 block must be representative for all possible histograms, otherwise
146 the statistical error is underestimated.
147 • traj The given histograms are used to generate new random trajecto‐
149 ries, such that the generated data points are distributed according
150 the given histograms and properly autocorrelated. The autocorrelation
151 time (ACT) for each window must be known, so use -ac or provide the
152 ACT with -iiact. If the ACT of all windows are identical (and known),
153 you can also provide them with -bs-tau. Note that this method may
154 severely underestimate the error in case of limited sampling, that is
155 if individual histograms do not represent the complete phase space at
156 the respective positions.
157 • traj-gauss The same as method traj, but the trajectories are not
159 bootstrapped from the umbrella histograms but from Gaussians with the
160 average and width of the umbrella histograms. That method yields sim‐
161 ilar error estimates like method traj.
162 Bootstrapping output:
164 • -bsres Average profile and standard deviations
166 • -bsprof All bootstrapping profiles
168 With -vbs (verbose bootstrapping), the histograms of each bootstrap are
170 written, and, with bootstrap method traj, the cumulative distribution
171 functions of the histograms.
172
174 Options to specify input files:
175 -ix [<.dat>] (pullx-files.dat) (Optional)
177 Generic data file
178 -if [<.dat>] (pullf-files.dat) (Optional)
180 Generic data file
181 -it [<.dat>] (tpr-files.dat) (Optional)
183 Generic data file
184 -is [<.dat>] (coordsel.dat) (Optional)
186 Generic data file
187 -iiact [<.dat>] (iact-in.dat) (Optional)
189 Generic data file
190 -tab [<.dat>] (umb-pot.dat) (Optional)
192 Generic data file
193 Options to specify output files:
195 -o [<.xvg>] (profile.xvg)
197 xvgr/xmgr file
198 -hist [<.xvg>] (histo.xvg)
200 xvgr/xmgr file
201 -oiact [<.xvg>] (iact.xvg) (Optional)
203 xvgr/xmgr file
204 -bsres [<.xvg>] (bsResult.xvg) (Optional)
206 xvgr/xmgr file
207 -bsprof [<.xvg>] (bsProfs.xvg) (Optional)
209 xvgr/xmgr file
210 Other options:
212 -xvg <enum> (xmgrace)
214 xvg plot formatting: xmgrace, xmgr, none
215 -min <real> (0)
217 Minimum coordinate in profile
218 -max <real> (0)
220 Maximum coordinate in profile
221 -[no]auto (yes)
223 Determine min and max automatically
224 -bins <int> (200)
226 Number of bins in profile
227 -temp <real> (298)
229 Temperature
230 -tol <real> (1e-06)
232 Tolerance
233 -[no]v (no)
235 Verbose mode
236 -b <real> (50)
238 First time to analyse (ps)
239 -e <real> (1e+20)
241 Last time to analyse (ps)
242 -dt <real> (0)
244 Analyse only every dt ps
245 -[no]histonly (no)
247 Write histograms and exit
248 -[no]boundsonly (no)
250 Determine min and max and exit (with -auto)
251 -[no]log (yes)
253 Calculate the log of the profile before printing
254 -unit <enum> (kJ)
256 Energy unit in case of log output: kJ, kCal, kT
257 -zprof0 <real> (0)
259 Define profile to 0.0 at this position (with -log)
260 -[no]cycl (no)
262 Create cyclic/periodic profile. Assumes min and max are the same
263 point.
264 -[no]sym (no)
266 Symmetrize profile around z=0
267 -[no]ac (no)
269 Calculate integrated autocorrelation times and use in wham
270 -acsig <real> (0)
272 Smooth autocorrelation times along reaction coordinate with
273 Gaussian of this sigma
274 -ac-trestart <real> (1)
276 When computing autocorrelation functions, restart computing ev‐
277 ery .. (ps)
278 -nBootstrap <int> (0)
280 nr of bootstraps to estimate statistical uncertainty (e.g., 200)
281 -bs-method <enum> (b-hist)
283 Bootstrap method: b-hist, hist, traj, traj-gauss
284 -bs-tau <real> (0)
286 Autocorrelation time (ACT) assumed for all histograms. Use op‐
287 tion -ac if ACT is unknown.
288 -bs-seed <int> (-1)
290 Seed for bootstrapping. (-1 = use time)
291 -histbs-block <int> (8)
293 When mixing histograms only mix within blocks of -histbs-block.
294 -[no]vbs (no)
296 Verbose bootstrapping. Print the CDFs and a histogram file for
297 each bootstrap.
298
300 gmx(1)
301 More information about GROMACS is available at <‐
303 http://www.gromacs.org/>.
304
306 2022, GROMACS development team
3072022.3 Sep 02, 2022 GMX-WHAM(1)