                 readme for iter directory
/*D
     ITIntro - This is the introductory manual page for the iterative
solvers package. The iterative solver package consists of lower level
routines which implement various iterative accelerators for the solution
of linear systems. For a simple interface, see the solvers directory.

Description:
    It includes support for Richardson, Conjugate Gradient, Chebychev,
GMRES, a transpose free QMR, etc.

    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 matrix multiplies and preconditioner. Particular
implementations of those are availible in other parts of this package,
but the IT* routines are intended just for the accelerators, not the 
preconditioners.

   To provide complete flexibility, the IT* routines use two context
variables. The iterative context, ITCntx, and a user context where the
user would store information on the matrix multiplier, preconditioner, etc. 

     
$ ------------------Sample Calling Seqences-----------------

$ Example 1: a single solve.

$   ITCntx     *itP;
$   UsrContext *usrP;
$   ... put stuff in usrP ...
$   itP = ITCreateContext(ITCG);
$   ... use ITSet*() to set user parameters and functions ...
$   ITSetUp(itP,usrP);
$   ITSolve(itP,usrP);
$   ITDestroy(itP,usrP);

$ Example 2: inside a nonlinear problem 

$   ITCntx     *itP;
$   UsrContext *usrP;
$   ... put stuff in usrP ...
$   itP = ITCreateContext(ITGMRES);
$   ... use ITSet*() to set user parameters and functions ...
$   ITSetUp(itP,usrP);
$   LOOP
$        ... linearize  and set matrix multiply and rhs ....
$        ITSolve(itP,usrP);
$   ENDLOOP
$   ITDestroy(itP,usrP);

$ Example 3: domain decomposition 

$   ITCntx     *itP,*itPLocal;
$   UsrContext *usrP,*usrPlocal[n];
$   ... put stuff in usrP and usrPlocal[]...
$   itP = ITCreateContext(ITGMRES);
$   itPLocal = ITCreateContext(ITGMRES);
$   ... use SetIT*() to set user parameters and functions ...
$   ITSetUp(itP,usrP);
$   ITSetUp(itPLocal,usrPlocal[]);
$   ITSetBinv(itP,a_domain_decomposition_preconditioner);
$   ITSolve(itP,usrP); 
$   ITDestroy(itP,usrP);

$   where  the routine a_domain_decomposition_preconditioner is of the form

$        LOOP i=0; i<n;
$            ... change  usrPlocal[i] ...
$            ITSolve(itPLocal,usrPlocal[i]);
$            ... put solution into appropriate place ....
$        ENDLOOP
D*/
  
   
