=======
                 ITERATE
                 =======

These routines demonstrate the use of ITERATE, 
an extension to the CERNLIB routine MINUIT.

ITERATE calculates the Hessian matrix of a 
function of many variables at a local minimum, 
using a procedure that is more stable than the 
MINUIT routine HESSE.

The algorithm is described in hep-ph/0008191, 
which should be cited in all publications that 
use this code.  

Some description appears directly in the fortran.  
For further information, you can write to the author.

The subdirectory /minuit/ contains the new routines, 
along with a recent version of the standard MINUIT 
routines, which have been slightly modified to 
interface with the new routines, as described in 
the code.

The subdirectory /model/ contains a sample 
application.  The function supplied has a single 
minimum value of zero, which is achieved when all 
of the fit parameters are zero.  The minuit routine 
HESSE fails for this function -- it produces a 
warning message that the eigenvalues found are 
not positive definite.  The new routine ITERATE 
correctly finds the Hessian and its eigenvalues.

By uncommenting a line in /model/fcnc.F as 
indicated, the function being minimized can be 
changed in such a way that both ITERATE and HESSE 
are successful. Information appearing in the output 
file fit.min then shows that the two methods agree 
on their values for the error matrix, when a 
difference in normalizations is allowed for:  
ITERATE defines the error matrix as simply the 
inverse of the Hessian, while HESSE includes a 
factor of 2*UP, where UP is the quantity set by 
the MINUIT command ERRDEF nn.


On the local linux machine, these routines can 
be compiled and run using the command
   f77 -o test.x */*.F ; test.x >& test.log 
Some output appears in test.log, but the output 
from minuit appears in test.min

The results I get are given here in the files 
test.log~ and test.min~

ITERATE is invoked by a new Minuit command, e.g.
     ITERATE 15
which causes 15 iterations to be performed -- 

It is analogous to the traditional command 
     MIGRAD 1000
 
After ITERATE has been called, two useful utility 
routines can be invoked by further new Minuit commands:

     MYSTUFF 1000 
 invokes xrange.F to explore the allowed range for 
 each fit parameter according to the constraint of 
 FCN increasing by no more than the value set by errdef.

     MYSTUFF 2000 
 invokes evplot.F to print the eigenvalues, the 
 eigenvectors, and the error matrix.

Both of these utility routines write their output
to the .min file.

ITERATE was written by 
     Jon Pumplin (pumplin@pa.msu.edu)
     Michigan State University 

First public version: August 2000
Minor revisions: November 2001