=======================================================================
H3: Description of the FORTRAN program to evaluate the H3 PES of BKMP2:
=======================================================================

  h3prog.tar.gz  (size 21 kb)  is a gzip-compressed tar-file archive.

To extract the four files that it contains (total size about 80 kb) requires
the gzip utility to decompress the archive, and the tar utility to extract the
files.  For example, on a Unix or Linux system, to extract all the files and
delete the archive:
  gunzip -v h3prog.tar.gz
  tar xvf h3prog.tar
  rm h3prog.tar

The resulting four files are listed below; they comprise the FORTRAN routines
to evaluate the BKMP2 H3 Potential Energy Surface (PES) described in the paper:
A. I. Boothroyd, W. J. Keogh, P. G. Martin, and M. R. Peterson (1996),
"A Refined H3 Potential Energy Surface", J. Chem. Phys., 104, 7139-7152.

   File Name    Size(bytes)                 Description
   ------------- --------- ----------------------------------------------------
1. bkmp2.f        (62760): Subroutine to calculate total H3 potential of BKMP2.
                             To invoke this surface, define the arrays
                                   double precision r(3), dVtot(3), Vtot
                             and set r to the three interatomic distances of H3
                             (in bohrs, in any order); set the flag id = 0 if
                             derivatives are not wanted, or set id = 1 if they
                             are wanted.  Then to evaluate the surface,
                                   call bkmp2( r, Vtot, dVtot, id )
                             which returns the total H3 energy Vtot relative to
                             three separated H atoms, and if (id.gt.0) also
                             returns the three dV/dr derivatives in dVtot.
                             Distances are in bohrs, and energies in hartrees.
2. bkmp2test.f     (8020): FORTRAN test program to invoke the subroutine bkmp2
                             in bkmp2.f and test that it is working correctly.
3. bkmp2test.out   (2666): Output file produced by bkmp2test; use this for
                             verification (the output of bkmp2test on your
                             machine should be identical to that contained in
                             the file bkmp2test.out).
4. h3progREADME.txt (3957): This README file describing the H3 BKMP2 surface.

How to compile, link, run, and check the test program:
------------------------------------------------------

  f77 -c bkmp2.f
  f77 bkmp2test.f bkmp2.o -o bkmp2test
  ./bkmp2test > output
  diff output bkmp2test.out

The final diff command should yield no differences; this has been tested on
DEC alpha, SGI R4000, and SUN Sparcstation, BUT SEE BELOW:

**** NOTE: THERE MAY BE INACCURACIES with EARLIER versions of the programs.
     As of 28 Oct 1999, the programs bkmp2.f and bkmp2test.f have been updated
     to have all constants be explicitly double precision, which is necessary
     for some compilers to avoid truncating the constants to single precision
     (which can reduce the accuracy enough that the test program does not work
     correctly).

**** THERE MAY STILL BE MINOR DIFFERENCES IN VALUES OF NUMERICAL DERIVATIVES,
     i.e., the line 
      -0.524470119 -0.271445938 -0.108650497   numerical 
     in the file  bkmp2test.out  and in the test progam output.
  THIS IS O.K.!  Note that the numerical derivatives are computed in the
  =============  program  bkmp2test.f  using  dr = 1.d-7  bohr; thus if
     values of the numerical derivatives agree to 7 decimal places, this
     indicates the surace values are accurate to 14 decimal places (and the
     analytic derivatives should be similarly accurate --- note that the test
     program does not bother to check them to more than 9 decimal places, nor
     the energy to more than 11 decimal places).