Provided by: gromacs-data_2023.1-2ubuntu1_all bug

NAME

       gmx-wham - Perform weighted histogram analysis after umbrella sampling

SYNOPSIS

          gmx wham [-ix [<.dat>]] [-if [<.dat>]] [-it [<.dat>]] [-is [<.dat>]]
                   [-iiact [<.dat>]] [-tab [<.dat>]] [-o [<.xvg>]]
                   [-hist [<.xvg>]] [-oiact [<.xvg>]] [-bsres [<.xvg>]]
                   [-bsprof [<.xvg>]] [-xvg <enum>] [-min <real>] [-max <real>]
                   [-[no]auto] [-bins <int>] [-temp <real>] [-tol <real>]
                   [-[no]v] [-b <real>] [-e <real>] [-dt <real>]
                   [-[no]histonly] [-[no]boundsonly] [-[no]log] [-unit <enum>]
                   [-zprof0 <real>] [-[no]cycl] [-[no]sym] [-[no]ac]
                   [-acsig <real>] [-ac-trestart <real>] [-nBootstrap <int>]
                   [-bs-method <enum>] [-bs-tau <real>] [-bs-seed <int>]
                   [-histbs-block <int>] [-[no]vbs]

DESCRIPTION

       gmx  wham  is  an  analysis program that implements the Weighted Histogram Analysis Method
       (WHAM). It is intended to analyze output files generated by umbrella sampling  simulations
       to compute a potential of mean force (PMF).

       gmx  wham  is currently not fully up to date. It only supports pull setups where the first
       pull coordinate(s) is/are umbrella pull coordinates and, if multiple coordinates  need  to
       be  analyzed,  all  used  the  same  geometry and dimensions. In most cases this is not an
       issue.

       At present, three input modes are supported.

       • With option -it, the user provides a file which contains the file names of the  umbrella
         simulation  run-input  files  (.tpr  files), AND, with option -ix, 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.

       • Same  as  the  previous  input mode, except that the user provides the pull force output
         file names (pullf.xvg) with option -if.   From  the  pull  force  the  position  in  the
         umbrella potential is computed. This does not work with tabulated umbrella potentials.

       By  default, all pull coordinates found in all pullx/pullf files are used in WHAM. If only
       some of the pull coordinates should be used, a pull coordinate selection file (option -is)
       can  be  provided.  The  selection  file  must  contain  one  line  for  each  tpr file in
       tpr-files.dat.  Each of these lines must  contain  one  digit  (0  or  1)  for  each  pull
       coordinate  in  the tpr file.  Here, 1 indicates that the pull coordinate is used in WHAM,
       and 0 means it is omitted.  Example: If you have three tpr files, each containing  4  pull
       coordinates,  but  only  pull  coordinates 1 and 2 should be used, coordsel.dat looks like
       this:

          1 1 0 0
          1 1 0 0
          1 1 0 0

       By default, the output files are:

          ``-o``      PMF output file
          ``-hist``   Histograms output file

       Always check whether the histograms sufficiently overlap.

       The umbrella potential is assumed to be harmonic and the force constants are read from the
       .tpr  files.  If  a  non-harmonic  umbrella force was applied a tabulated potential can be
       provided with -tab.

   WHAM options-bins   Number of bins used in analysis

       • -temp   Temperature in the simulations

       • -tol    Stop iteration if profile (probability) changed less than tolerance

       • -auto   Automatic determination of boundaries

       • -min,-max   Boundaries of the profile

       The data points that are used to compute the profile can be restricted  with  options  -b,
       -e, and -dt.  Adjust -b to ensure sufficient equilibration in each umbrella window.

       With  -log  (default)  the  profile is written in energy units, otherwise (with -nolog) as
       probability. The unit can be specified with -unit.  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 -zprof0 (useful with bootstrapping, see below).

       For cyclic or periodic reaction coordinates (dihedral angle, channel PMF  without  osmotic
       gradient),  the  option -cycl is useful.  gmx 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.

       Option  -sym  symmetrizes  the  profile around z=0 before output, which may be useful for,
       e.g. membranes.

   Parallelization
       If available, the number of OpenMP threads used by gmx wham can be controlled  by  setting
       the OMP_NUM_THREADS environment variable.

   Autocorrelations
       With  -ac,  gmx  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 -oiact. 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  -acsig  allows one to smooth the IACTs along the
       reaction coordinate with a Gaussian (sigma provided with -acsig, 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 gmx analyze and provide them to gmx wham with the file iact-in.dat  (option  -iiact),
       which  should  contain  one line per input file (pullx/pullf file) and one column per pull
       coordinate in the respective file.

   Error analysis
       Statistical errors may be estimated with bootstrap analysis. Use it with  care,  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)
       6:  3713-3720.   -nBootstrap  defines  the  number  of  bootstraps (use, e.g., 100).  Four
       bootstrapping methods are supported and selected with -bs-method.

       • b-hist   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.

       • hist    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 (-histbs-block) 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.

       • traj  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 -ac
         or provide the ACT with -iiact. If the ACT of all windows are identical (and known), you
         can also provide them with -bs-tau.  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.

       • traj-gauss  The same as method traj, 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 traj.

       Bootstrapping output:

       • -bsres   Average profile and standard deviations

       • -bsprof  All bootstrapping profiles

       With -vbs (verbose bootstrapping), the histograms of each bootstrap are written, and, with
       bootstrap method traj, the cumulative distribution functions of the histograms.

OPTIONS

       Options to specify input files:

       -ix [<.dat>] (pullx-files.dat) (Optional)
              Generic data file

       -if [<.dat>] (pullf-files.dat) (Optional)
              Generic data file

       -it [<.dat>] (tpr-files.dat) (Optional)
              Generic data file

       -is [<.dat>] (coordsel.dat) (Optional)
              Generic data file

       -iiact [<.dat>] (iact-in.dat) (Optional)
              Generic data file

       -tab [<.dat>] (umb-pot.dat) (Optional)
              Generic data file

       Options to specify output files:

       -o [<.xvg>] (profile.xvg)
              xvgr/xmgr file

       -hist [<.xvg>] (histo.xvg)
              xvgr/xmgr file

       -oiact [<.xvg>] (iact.xvg) (Optional)
              xvgr/xmgr file

       -bsres [<.xvg>] (bsResult.xvg) (Optional)
              xvgr/xmgr file

       -bsprof [<.xvg>] (bsProfs.xvg) (Optional)
              xvgr/xmgr file

       Other options:

       -xvg <enum> (xmgrace)
              xvg plot formatting: xmgrace, xmgr, none

       -min <real> (0)
              Minimum coordinate in profile

       -max <real> (0)
              Maximum coordinate in profile

       -[no]auto (yes)
              Determine min and max automatically

       -bins <int> (200)
              Number of bins in profile

       -temp <real> (298)
              Temperature

       -tol <real> (1e-06)
              Tolerance

       -[no]v (no)
              Verbose mode

       -b <real> (50)
              First time to analyse (ps)

       -e <real> (1e+20)
              Last time to analyse (ps)

       -dt <real> (0)
              Analyse only every dt ps

       -[no]histonly (no)
              Write histograms and exit

       -[no]boundsonly (no)
              Determine min and max and exit (with -auto)

       -[no]log (yes)
              Calculate the log of the profile before printing

       -unit <enum> (kJ)
              Energy unit in case of log output: kJ, kCal, kT

       -zprof0 <real> (0)
              Define profile to 0.0 at this position (with -log)

       -[no]cycl (no)
              Create cyclic/periodic profile. Assumes min and max are the same point.

       -[no]sym (no)
              Symmetrize profile around z=0

       -[no]ac (no)
              Calculate integrated autocorrelation times and use in wham

       -acsig <real> (0)
              Smooth autocorrelation times along reaction coordinate with Gaussian of this sigma

       -ac-trestart <real> (1)
              When computing autocorrelation functions, restart computing every .. (ps)

       -nBootstrap <int> (0)
              nr of bootstraps to estimate statistical uncertainty (e.g., 200)

       -bs-method <enum> (b-hist)
              Bootstrap method: b-hist, hist, traj, traj-gauss

       -bs-tau <real> (0)
              Autocorrelation  time  (ACT)  assumed  for all histograms. Use option -ac if ACT is
              unknown.

       -bs-seed <int> (-1)
              Seed for bootstrapping. (-1 = use time)

       -histbs-block <int> (8)
              When mixing histograms only mix within blocks of -histbs-block.

       -[no]vbs (no)
              Verbose bootstrapping. Print the CDFs and a histogram file for each bootstrap.

SEE ALSO

       gmx(1)

       More information about GROMACS is available at <http://www.gromacs.org/>.

COPYRIGHT

       2023, GROMACS development team