$Id: README_gromacsified_wham.txt,v 1.2 2009/01/27 21:01:32 oliver Exp $

WHAM: An implementation of the Weighted Histogram Analysis Method.
==================================================================

Alan Grossfield <alan_grossfield@urmc.rochester.edu>
http://membrane.urmc.rochester.edu/Software/WHAM/WHAM.html

Documentation is located in the doc/ directory, as doc.dvi and doc.pdf.  If
you prefer html, look at doc/doc/index.html.

If you're too impatient to do that, you can build the software by saying

    cd wham
    make clean
    make 
    make BIN_DIR=/path/to/bin install

The energy unit defaults to kJ/mol in this installation. You can
change this by editing the Makefile and setting 

  CFLAGS = -D KCALMOL


Then, run wham or wham-2d with no arguments to get a summary of the
command line arguments.

Good luck!

Notes on the Gromacs-ified version
==================================

Oliver Beckstein <orbeckst@gmail.com>
http://sbcb.bioch.ox.ac.uk/oliver/

I hacked Alan's wham code to cope with the output of the Gromacs
(www.gromacs.org) umbrella sampling code. This code is based on Alan's
wham 2.0.2 2008-04-14
(http://membrane.urmc.rochester.edu/wham/wham-release-2.0.2.tgz) The
wham2d code was not modified at all.

THIS gromacsified `wham' behaves differently from the one documented
by Alan. The main differences are:

* It can read gzipped (.gz) pdo files. 
* It reads files with _relative_ time series (not absolute z
  coordinates). THIS BREAKS COMPATIBILITY (and should become an option
  once I use proper opt processing).
* The energy unit defaults to kJ/mol; the original used kcal/mol.
* The output file format changed, a new column with the free energy in
  kT was added after the one in absolute energy units and before the
  column containing the probability
* Bad hack: if the environment variable WHAM_TMIN is set then
  all data before WHAM_TMIN is discarded as equilibration.
  

In the scripts directory there is pdo2meta.sh which takes Gromacs >=
3.2.1 (Umbrella file format UMBRELLA 3.0 or my custom UMBRELLA 3.2)
pdo files and creates the meta data files required by this wham
program.


Testing
=======

In the `extras/' directory you can compile the `fakepmf' program which
generates data files for gromacsified wham. These data files simulate
sampling on either a constant (`flat') or a step function (`step')
PMF. Run `fakepmf -h' for help, then run it with your choice of
options and create samples. Process the pdo.gz files with
`scripts/pdo2meta.sh' to obtain a metadata input file for `wham' and
run `wham' on it. You should recover the underlying PMF.

Compile `wham' and `fakepmf' by just runing `make' in the appropriate
directories. Then go to the top directory and set up a testing area:

 mkdir testing && cd testing
 mkdir step && cd step
 ../../extras/fakepmf --zeta 1.5       # create fake run over a step function PMF
 cd ..
 ../scripts/pdo2meta.sh step           # prepare metadata file
 ../wham/wham -1 1 200 1e-5 300 0 pdo.wham free.dat  # unbias fake data

Look at the graph, eg

 xmgrace -block free.dat -bxy 1:4

This should show a nice step function at x=0 with height 1.5 kT.



Notes on trouble shooting
=========================

Please see FAQ.txt if you have problems.