cg_descent is a conjugate gradient algorithm for solving
an unconstrained minimization problem of the form:

                    min f (x)

The algorithm is developed in the following papers
(see www.math.ufl.edu/~hager/papers/CG):

[1] W. W. Hager and H. Zhang, A new conjugate gradient method
    with guaranteed descent and an efficient line search,
    SIAM Journal on Optimization, 16 (2005), 170-192.

[2] W. W. Hager and H. Zhang, Algorithm 851: CG_DESCENT,
    A conjugate gradient method with guaranteed descent,
    ACM Transactions on Mathematical Software, 32 (2006), 113-137.

[3] W. W. Hager and H. Zhang, A survey of nonlinear conjugate
    gradient methods, Pacific Journal of Optimization,
    2 (2006), pp. 35-58.

This directory provides a C implementation of cg_descent and
the codes needed to run cg_descent in the CUTEr testing
environment (http://hsl.rl.ac.uk/cuter-www/).  The program
which calls cg_descent should include the header file cg_user.h.
Examples showing how to call cg_descent are given in driver1.c
through driver5.c.  The user must provide routines to evaluate
the objective function and its gradient.  Performance is often
improved if the user also provides a routine to simultaneously
evaluate the objective function and its gradient (see drive1.c).
In the simplest case, cg_descent is invoked with a statement
of the form:

cg_descent (x, n, NULL, NULL, tol, myvalue, mygrad, NULL, NULL) ;

where x is a pointer to an array which contains the starting
guess on input and the solution on output, n is the problem
dimension, tol is the computing tolerance (max norm of the
gradient), myvalue is a routine to evaluate the user's
objective function, and mygrad is a routine to evaluate
the gradient of the user's objective function. The 4 NULL
arguments could be replaced by the following (in order):
a structure to store execution statistics, a structure containing
algorithm parameters, a pointer to a routine which evaluates the
objective function and its gradient, and a pointer to a work
array. It the work array is not provided, then the code
allocates and frees memory. If the routine to simultaneously evaluate
objective function and its gradient is not provided, then the
code will use myvalue and mygrad to compute the value and
gradient independently. When the algorithm parameters are not
provided, then the default parameter values will be used
(see cg_default for their values).

We also provide codes to interface cg_descent to the CUTEr
testing environment. The procedure for incorporating cg_descent
in CUTEr is as follows:

1. Put cg_user.h into $CUTER/common/include
2. Put cg_descentma.c into $CUTER/common/src/tools
3. In $CUTER/common/src/tools, "gcc -lm -O3 -c cg_descentma.c"
4. "cp cg_descentma.o $MYCUTER/double/bin"
5. In the directory where you put cg_descent, type "make" and then
   "cp cg_descent.o $MYCUTER/double/bin"
6. "cp cg_descent.pro $CUTER/build/prototypes"
   "cp sdcg_descent.pro $CUTER/build/prototypes"
7. "cd $MYCUTER/bin"
8. type the following command twice:

sed -f $MYCUTER/double/config/script.sed $CUTER/build/prototypes/pack.pro > pack

where "pack" is first "cg_descent" and then "sdcg_descent"

9. "chmod a+x cg_descent" and "chmod a+x sdcg_descent"

You can run a problem by cd'ing to the directory where the sif files
are stored and typing, for example, "sdcg_descent BRYBND"

NOTE: to run valgrind with the code, edit the program "runpackage"
found in "$MYCUTER/bin" as follows:
near the end of the program, change "$EXEC/${PAC}min" to
"valgrind $EXEC/${PAC}min"