g_wham

Langue: en

Version: 371405 (fedora - 01/12/10)

Section: 1 (Commandes utilisateur)

NAME

g_wham - weighted histogram analysis after umbrella sampling

VERSION 4.5

SYNOPSIS

g_wham -ix pullx-files.dat -if pullf-files.dat -it tpr-files.dat -ip pdo-files.dat -o profile.xvg -hist histo.xvg -bsres bsResult.xvg -bsprof bsProfs.xvg -tab umb-pot.dat -wcorr cycl-corr.xvg -[no]h -[no]version -nice int -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 -cycl enum -alpha real -[no]flip -[no]hist-eq -nBootstrap int -bs-dt real -bs-seed int -[no]histbs -histbs-block int -[no]vbs

DESCRIPTION

This 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).

At present, three input modes are supported:

* With option -it, the user provides a file which contains the filenames of the umbrella simulation run-input files (tpr files), AND, with option -ix, a file which contains filenames 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 the user provides the pull force ouput file names (pullf.xvg) with option -if. From the pull force the position in the ubrella potential is computed. This does not work with tabulated umbrella potentials. * With option -ip, the user provides filenames 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 -ip option into to g_wham. The pdo file header must be similar to the folowing:

UMBRELLA 3.0

Component selection: 0 0 1

nSkip 1

Ref. Group 'TestAtom'

Nr. of pull groups 2

Group 1 'GR1' Umb. Pos. 5.0 Umb. Cons. 1000.0

Group 2 'GR2' Umb. Pos. 2.0 Umb. Cons. 500.0

Nr 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 follow (i.e. the displacement with respect to the umbrella center). Up to four pull groups are possible at present.

By default, the output files are

-o PMF output file

-hist histograms output file

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 provied with -tab.

WHAM OPTIONS

-bins Nr of bins used in analysis

-temp Temperature in the simulations

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

-auto Automatic determination of boudndaries

-min,-max Boundaries of the profile

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

With -log (default) the profile is written in energy units, otherwise (-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, choose with -zprof0 (useful with bootstrapping, see below).

For cyclic (or periodic) reaction coordinates (dihedral angle, channel PMF without osmotic gradient), -cycl is useful.

-cycl yes min and max are assumed to be neighboring points and histogram points outside min and max are mapped into the interval [min,max] (compare histogram output).

-cycl weighted First, a non-cyclic profile is computed. Subsequently, periodicity is enforced by adding corrections dG(i) between neighboring bins i and i+1. The correction is chosen proportional to 1/[n(i)*n(i+1)]alpha, where n(i) denotes the total nr of data points in bin i as collected from all histograms. alpha is defined with -alpha. The corrections are written to the file defined by -wcorr. (Compare Hub and de Groot, PNAS 105:1198 (2008))

ERROR ANALYSIS

Statistical errors may be estimated with bootstrap analysis. Use it with care, otherwise the statistical error may be substantially undererstimated !!

-nBootstrap defines the nr of bootstraps. Two bootstrapping modes are supported.

-histbs Complete histograms are considered as independent data points (default). For each bootstrap, N histograms are randomly chosen from the N given histograms (allowing duplication). 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 undererstimated!

-nohistbs The given histograms are used to generate new random histograms, such that the generated data points are distributed according the given histograms. The number of points generated for each bootstrap histogram can be controlled with -bs-dt. Note that one data point should be generated for each *independent* point in the given histograms. With the long autocorrelations in MD simulations, this procedure may easily understimate the error!

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 -nohistBS, the cummulants of the histogram.

FILES

-ix pullx-files.dat Input, Opt.
 Generic data file 

-if pullf-files.dat Input, Opt.
 Generic data file 

-it tpr-files.dat Input, Opt.
 Generic data file 

-ip pdo-files.dat Input, Opt.
 Generic data file 

-o profile.xvg Output
 xvgr/xmgr file 

-hist histo.xvg Output
 xvgr/xmgr file 

-bsres bsResult.xvg Output, Opt.
 xvgr/xmgr file 

-bsprof bsProfs.xvg Output, Opt.
 xvgr/xmgr file 

-tab umb-pot.dat Input, Opt.
 Generic data file 

-wcorr cycl-corr.xvg Input, Opt.
 xvgr/xmgr file 

OTHER OPTIONS

-[no]hno
 Print help info and quit

-[no]versionno
 Print version info and quit

-nice int 19
 Set the nicelevel

-xvg enum xmgrace
 xvg plot formatting:  xmgrace xmgr or  none

-min real 0
 Minimum coordinate in profile

-max real 0
 Maximum coordinate in profile

-[no]autoyes
 determine min and max automatically

-bins int 200
 Number of bins in profile

-temp real 298
 Temperature

-tol real 1e-06
 Tolerance

-[no]vno
 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]histonlyno
 Write histograms and exit

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

-[no]logyes
 Calculate the log of the profile before printing

-unit enum kJ
 energy unit in case of log output:  kJ kCal or  kT

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

-cycl enum no
 Create cyclic/periodic profile. Assumes min and max are the same point.:  no yes or  weighted

-alpha real 2
 for '-cycl weighted', set parameter alpha

-[no]flipno
 Combine halves of profile (not supported)

-[no]hist-eqno
 Enforce equal weight for all histograms. (Non-Weighed-HAM)

-nBootstrap int 0
 nr of bootstraps to estimate statistical uncertainty

-bs-dt real 0
 timestep for synthetic bootstrap histograms (ps). Ensure independent data points!

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

-[no]histbsyes
 In bootstrapping, consider complete histograms as one data point. Accounts better for long autocorrelations.

-histbs-block int 8
 when mixin histograms only mix within blocks of -histBS_block.

-[no]vbsno
 verbose bootstrapping. Print the cummulants and a histogram file for each bootstrap.

SEE ALSO

gromacs(7)

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