                 readme for nonlin directory
/*D
     NLIntro - This is the introductory manual page for the iterative
nonlinear solvers package. We intend to support various iterative 
methods for the solution of nonlinear systems of equations including
Newton's method with line searches, Newton's method with the Trust
region approach.

    The routines are intended to be data structure independent. That is 
the routines should work as written without change on serial and parallel
machines independent of how the vectors, matrices, etc. are stored.

    The vector independence is achieved by using the VE* vector package
for all the vector operations, the user must proved routines which 
perform the function evaluations and Jacobian evaluations, also for the 
Newton type methods the user must provide functions to calculate 
the application of approximate inverses of Jacobians.

   To provide complete flexibility, the NL* routines use two context
variables. The iterative context, NLCntx, and a user context where the
user would store information on the particular problem class. 

  User provided parameters:

.    NLSetIterations -  maximum number of nonlinear iterations (optional)
.    NLSetFunctionTolerance - tolerance in norm of function (optional)
.    NLSetFunctionTolerance - tolerance in norm of solution (optional)

.    NLSetSolution - location where solution is to be stored (required)
.    NLSetResidualHistory - location to store norm of function at 
.                           each iteration (optional)
.    NLSetVectorOps - vector operations context VECtx (required)

  User provided functions:

.    NLSetMonitor - function which monitors convergence (optional)
.    NLSetFunction - function which calculates nonlinear function (required)
.    NLSetInitialGuess - function which gives intial guess (optional)
. 

.    NLSetInverseJacobianSetUp - function to be called before a series of 
.                                applications of the Jacobian are needed
.    NLSetInverseJacobianApply - function to apply Jacobian to vector
.    NLSetInverseJacobianDestroy - function to be called before a new 
.                                  JacobianSetUp is called
.
 
   
D*/
