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 2c909747b9d5e26528144064574c003c9f40b51d..59bdb695161523d55a42f6b528d2772033d63ecb 100644 (file)
--- 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]",
         "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]",
         "[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]",
         "# 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 ",
         "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]",
         "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]",
         "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]",
         "  [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",
         "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]",
         "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, ",
         "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 ",
         "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]",
         "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 ",
         "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 ",
         "  (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]",
         "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};
     };
 
     const char *en_unit[]={NULL,"kJ","kCal","kT",NULL};