----------------------------------------------------------
HOPPET: Higher Order Perturbative Parton Evolution Toolkit
----------------------------------------------------------

HOPPET is a Fortran 95 package for carrying out DGLAP evolution and
other common manipulations of parton distribution functions (PDFs).

Within HOPPET, PDFs are represented on a grid in x-space so as to
avoid limitations on the functional form of input
distributions. Decent speed and accuracy are obtained through the
representation of splitting functions in terms of their convolution
with a set of piecewise polynomial basis functions, and Runge-Kutta
techniques are used for the evolution in Q.

Unpolarised evolution is provided in the MSbar scheme to NNLO in the
coupling, including heavy-quark thresholds, and polarised evolution to
NLO. The code is structured so as to provide simple access to the
objects representing splitting function and PDFs, making it possible
for a user to extend the facilities already provided.

The latest version can always be obtained from

    svn checkout http://svn.hepforge.org/hoppet/trunk hoppet

Details of changes are to be found in the file ChangeLog, while
summaries of changes between releases are in ReleaseNotes.


----------------------------------------------------------------------
F95 compilers
-------------

You will need a Fortran 95 compiler to compile this package. 

The free g95 (www.g95.org) compiler is one option, though its
executables are fairly slow. It is easy to install if you don't
already have a recent version on your system. At the time of writing
(April 2007) the free gfortran compiler produced executables that
crash and so is not currently recommended.

The intel (ifort) compiler (versions 8.1.033 upwards) exists in a
semi-free version for non-commercial use under linux and produces fast
executables.

The release has also been tested with the lahey lf95 commercial
compiler, which also generates fast code.


----------------------------------------------------------------------
Compilation
-----------

Makefiles for f90/95 are generated automatically using the perl script
scripts/makef95makefile, called from scripts "mkmk" in each
directory. To generate the full set of makefiles for your compiler,
type (from the main directory)

     ./mkmk compiler-name   

where compiler-name can be g95,lf95,ifort,gfortran (the latter may
give executables that crash though). This will run subsiduary mkmk
files and also set files .compiler in each directory which store the
information about the compiler being used. If you add new programs to
a directory, they will automatically be taken into account when you
rerun mkmk.

To compile the hoppet library

     cd src/
     # compile the library
     make

To compile the f90 example program 

     cd ../example_f90
     # compile the program
     make tabulation_example
     # run the program
     ./tabulation_example

The output should be compared to the file
"tabulation_example.default_output", which contains the correct
results. 

An equivalent program with the startup, pdf initialisation and
evolution spread across different subroutines is given as
tabulation_example_2.

Compiling f77 example programs (using g77) is a little trickier
because of the need to include the correct f95 libraries. Accordingly
the Makefile is not generated automatically -- look inside the
suppplied Makefile to see what needs doing.

     cd ../example_f77
     # <edit the Makefile directly>
     # compile
     make tabulation_example
     # run the program should give output identical to that from
     # example_f90/tabulation_example
     ./tabulation_example

In the same directory there is a C++ example

     make cpp_tabulation_example
     ./cpp_tabulation_example

which again does the same things (though in this case it uses the
simpler of the two vanilla initialization calls).

Other programs provided in the example_f77/ directory illustrate the
use of the vanilla interface in conjunction with LHAPDF
(compare_lhapdf_hoppet.f), and show how use the feature of getting
convolutions with splitting functions (convolution_example.f).

----------------------------------------------------------------------
Documentation
-------------

Draft documentation is available as doc/HOPPET-v1-doc.tex .


----------------------------------------------------------------------
Benchmarking
------------

The benchmarking/ directory contains the programs used for the full
benchmarking, accuracy and precision testing.