From: Justin Lemkul Date: Wed, 19 Jan 2011 18:45:57 +0000 (-0500) Subject: Fixes to g_wham documentation. X-Git-Url: http://biod.pnpi.spb.ru/gitweb/?a=commitdiff_plain;h=e5b71c34ba904354fc5038a415b034bd0a00d17d;p=alexxy%2Fgromacs.git Fixes to g_wham documentation. Mostly formatting issues in the source code, making it (hopefully) a bit easier to read and keep track of. The help info ate up a lot of space in the manual, so the changes I made should make it a bit more compact. IssueID #671 --- diff --git a/src/tools/gmx_wham.c b/src/tools/gmx_wham.c index 2c909747b9..59bdb69516 100644 --- a/src/tools/gmx_wham.c +++ b/src/tools/gmx_wham.c @@ -2491,21 +2491,21 @@ int gmx_wham(int argc,char *argv[]) "output files generated by umbrella sampling simulations to ", "compute a potential of mean force (PMF). [PAR] ", "At present, three input modes are supported.[BR]", - "[TT]*[tt] With option [TT]-it[tt], the user provides a file which contains the[BR]", - " file names of the umbrella simulation run-input files (tpr files),[BR]", - " AND, with option [TT]-ix[tt], a file which contains file names of [BR]", - " the pullx mdrun output files. The tpr and pullx files must [BR]", - " be in corresponding order, i.e. the first tpr created the [BR]", - " first pullx, etc.[BR]", - "[TT]*[tt] Same as the previous input mode, except that the the user [BR]", - " provides the pull force output file names (pullf.xvg) with option [TT]-if[tt].[BR]", - " From the pull force the position in the umbrella potential is [BR]", - " computed. This does not work with tabulated umbrella potentials.[BR]" - "[TT]*[tt] With option [TT]-ip[tt], the user provides file names of (gzipped) pdo files, i.e.[BR]", - " the gromacs 3.3 umbrella output files. If you have some unusual[BR]" - " reaction coordinate you may also generate your own pdo files and [BR]", - " feed them with the [TT]-ip[tt] option into to g_wham. The pdo file header [BR]", - " must be similar to the following:[BR]", + "[TT]*[tt] With option [TT]-it[tt], the user provides a file which contains the", + " file names of the umbrella simulation run-input files (tpr files),", + " AND, with option [TT]-ix[tt], a file which contains file names of", + " the pullx mdrun output files. The tpr and pullx files must", + " be in corresponding order, i.e. the first tpr created the", + " first pullx, etc.[BR]", + "[TT]*[tt] Same as the previous input mode, except that the the user", + " provides the pull force output file names (pullf.xvg) with option [TT]-if[tt].", + " From the pull force the position in the umbrella potential is", + " computed. This does not work with tabulated umbrella potentials.[BR]" + "[TT]*[tt] With option [TT]-ip[tt], the user provides file names of (gzipped) pdo files, i.e.", + " the GROMACS 3.3 umbrella output files. If you have some unusual" + " reaction coordinate you may also generate your own pdo files and", + " feed them with the [TT]-ip[tt] option into to g_wham. The pdo file header", + " must be similar to the following:[PAR]", "[TT]# UMBRELLA 3.0[BR]", "# Component selection: 0 0 1[BR]", "# nSkip 1[BR]", @@ -2513,86 +2513,95 @@ int gmx_wham(int argc,char *argv[]) "# Nr. of pull groups 2[BR]", "# Group 1 'GR1' Umb. Pos. 5.0 Umb. Cons. 1000.0[BR]", "# Group 2 'GR2' Umb. Pos. 2.0 Umb. Cons. 500.0[BR]", - "#####[tt][BR]", - "Nr of pull groups, umbrella positions, force constants, and names ", + "#####[tt][PAR]", + "The number of pull groups, umbrella positions, force constants, and names ", "may (of course) differ. Following the header, a time column and ", - "a data columns for each pull group follows (i.e. the displacement", + "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 pdo file at present.[PAR]", "By default, the output files are[BR]", " [TT]-o[tt] PMF output file[BR]", - " [TT]-hist[tt] histograms output file[BR]", - "Always check whether the histograms sufficiently overlap![PAR]", + " [TT]-hist[tt] Histograms output file[BR]", + "Always check whether the histograms sufficiently overlap.[PAR]", "The umbrella potential is assumed to be harmonic and the force constants are ", "read from the tpr or pdo files. If a non-harmonic umbrella force was applied ", "a tabulated potential can be provided with [TT]-tab[tt].[PAR]", "WHAM OPTIONS[BR]------------[BR]", - " [TT]-bins[tt] Nr of bins used in analysis[BR]", + " [TT]-bins[tt] Number of bins used in analysis[BR]", " [TT]-temp[tt] Temperature in the simulations[BR]", " [TT]-tol[tt] Stop iteration if profile (probability) changed less than tolerance[BR]", " [TT]-auto[tt] Automatic determination of boundaries[BR]", " [TT]-min,-max[tt] Boundaries of the profile [BR]", - "The data points which are used ", - "to compute the profile can be restricted with options [TT]-b[tt], [TT]-e[tt], and [TT]-dt[tt]. ", - "Play particularly with [TT]-b[tt] to ensure sufficient equilibration in each ", - "umbrella window![PAR]", - "With [TT]-log[tt] (default) the profile is written in energy units, otherwise ([TT]-nolog[tt]) as ", - "probability. The unit can be specified with [TT]-unit[tt]. 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, choose with [TT]-zprof0[tt] (useful with bootstrapping, see below).[PAR]", - "For cyclic (or periodic) reaction coordinates (dihedral angle, channel PMF", + "The data points that are used to compute the profile", + "can be restricted with options [TT]-b[tt], [TT]-e[tt], and [TT]-dt[tt]. ", + "Adjust [TT]-b[tt] to ensure sufficient equilibration in each ", + "umbrella window.[PAR]", + "With [TT]-log[tt] (default) the profile is written in energy units, otherwise ", + "(with [TT]-nolog[tt]) as probability. The unit can be specified with [TT]-unit[tt]. ", + "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 [TT]-zprof0[tt] (useful with bootstrapping, see below).[PAR]", + "For cyclic or periodic reaction coordinates (dihedral angle, channel PMF", "without osmotic gradient), the option [TT]-cycl[tt] is useful. g_wham 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[PAR]", - "Option [TT]-sym[tt] symmetrizes the profile around z=0 before output (useful for membrane etc.)[PAR]", + "reaction coordinate will assumed be be neighbors.[PAR]", + "Option [TT]-sym[tt] symmetrizes the profile around z=0 before output, ", + "which may be useful for, e.g. membranes.[PAR]", "AUTOCORRELATIONS[BR]----------------[BR]", - "With [TT]-ac[tt], g_wham 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 [TT]-oiact[tt]. In verbose mode, all autocorrelation functions (ACFs) are", - "written to hist_autocorr.xvg. Because the IACTs can be severely underestimated in case of ", - "limited sampling, option [TT]-acsig[tt] allows to smooth the IACTs along the reaction coordinate ", - "with a Gaussian (sigma provided with [TT]-acsig[tt], see output in iact.xvg). 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 g_analyze and provide", - "them to g_wham with the file iact-in.dat (option [TT]-iiact[tt]). iact-in.dat should contain ", - "one line per input file (pdo or pullx/f file) and one column per pull group in the respective file.[PAR]" + "With [TT]-ac[tt], g_wham 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 [TT]-oiact[tt]. In verbose mode, all ", + "autocorrelation functions (ACFs) are written to hist_autocorr.xvg. ", + "Because the IACTs can be severely underestimated in case of limited ", + "sampling, option [TT]-acsig[tt] allows to smooth the IACTs along the ", + "reaction coordinate with a Gaussian (sigma provided with [TT]-acsig[tt], ", + "see output in iact.xvg). 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 g_analyze and provide them to g_wham with the file ", + "iact-in.dat (option [TT]-iiact[tt]), which should contain one line per ", + "input file (pdo or pullx/f file) and one column per pull group in the respective file.[PAR]", "ERROR ANALYSIS[BR]--------------[BR]", "Statistical errors may be estimated with bootstrap analysis. Use it with care, ", - "otherwise the statistical error may be substantially underestimated !![BR]", + "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)[BR]", - "-nBootstrap defines the nr of bootstraps (use, e.g., 100). Four bootstrapping methods are supported and ", + "Hub, de Groot and Van der Spoel, JCTC (2010) 6: 3713-3720.[BR]", + "[TT]-nBootstrap[tt] defines the number of bootstraps (use, e.g., 100). ", + "Four bootstrapping methods are supported and ", "selected with [TT]-bs-method[tt].[BR]", - " (1) [TT]b-hist[tt] 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", + " (1) [TT]b-hist[tt] 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![BR]", - " (2) [TT]hist[tt] 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 ([TT]-histbs-block[tt])", - "may be defined. In that case, the given histograms are divided 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![BR]", + "statistical error is underestimated.[BR]", + " (2) [TT]hist[tt] 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 ", + "([TT]-histbs-block[tt]) may be defined. In that case, the given histograms are ", + "divided 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.[BR]", " (3) [TT]traj[tt] 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 [TT]-ac[tt] or provide the ACT", - "with [TT]-iiact[tt]. If the ACT of all windows are identical (and known), you can also ", - "provide them with [TT]-bs-tau[tt]. 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.[BR]", - " (4) [TT]traj-gauss[tt] The same as Method [TT]traj[tt], but the trajectories are not 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 [TT]traj[tt].[BR]" + "and properly autocorrelated. The autocorrelation time (ACT) for each window must be ", + "known, so use [TT]-ac[tt] or provide the ACT with [TT]-iiact[tt]. If the ACT of all ", + "windows are identical (and known), you can also provide them with [TT]-bs-tau[tt]. ", + "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.[BR]", + " (4) [TT]traj-gauss[tt] The same as method [TT]traj[tt], but the trajectories are ", + "not 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 [TT]traj[tt].[PAR]" "Bootstrapping output:[BR]", " [TT]-bsres[tt] Average profile and standard deviations[BR]", " [TT]-bsprof[tt] All bootstrapping profiles[BR]", - "With [TT]-vbs[tt] (verbose bootstrapping), the histograms of each bootstrap are written, and, ", - "with bootstrap method [TT]traj[tt], the cumulative distribution functions of the histograms.", + "With [TT]-vbs[tt] (verbose bootstrapping), the histograms of each bootstrap are written, ", + "and, with bootstrap method [TT]traj[tt], the cumulative distribution functions of ", + "the histograms." }; const char *en_unit[]={NULL,"kJ","kCal","kT",NULL};