=======================================================================
 --> Version 1.0  Latest changes made on: Tue Sep 16 18:32:57 CDT 2008
+======================================================================+
|--------------- Complex Iterative Solvers Package --------------------|
+======================================================================+

Note: ILUC has been removed for a fix..

This is  part of  the ITSOL extention  to the SPARSKIT  package.  This
particular  sub-package provides  preconditioners for  solving general
sparse * complex * linear systems of equations.

Main Contributors: Brian Suchomel, Na Li, Zhongze Li, Daniel Osei-Kuffuor, 
     and Yousef Saad.

Current contacts: Daniel Osei Kuffuor ([email protected])
                  Yousef Saad         ([email protected]) 

Apr. 2008 

=======================================================================

This  library contains a  number of  classic and  new preconditioners.
There are several ways in  which you can use these preconditioners for
solving a complex  linear system.  The easiest way  is probably to use
the sample drivers provided  in the directories TESTS_COO and TESTS_HB
as templates. TESTS_COO contains test codes for matrices in coordinate
or  matrix-market format  while TESTS_HB  is for  matrices in  the old
Harwell- Boeing format.  Each if these  drivers has a name of the form
mainPRECONhb.c or mainPRECONcoo where PRECON is one of

 ILUK     standard ILU preconditioner with level of fill 
 ILUT     standard ILU preconditioner with threshold 
 ILUC     standard ILU preconditioner with threshold - Crout version
 ARMS     Algebraic Multilevel Solvers == This includes both the 
          standard ARMS and a version with nonsymmetric permutations
          which reorders the matrix by diagonal dominance 

For  example, mainILUThb.c  is  a driver  which  reads a  matrix in  a
Harwell-Boeing format (or a  sequence of such matrices for consecutive
tests  --  see below),  then  constructs  an  ILUT preconditioner  and
proceeds to  solve the system  with the accelerator fgmres.   There is
only  one accelerator  used  for the  iteration  phase, namely  FGMRES
(zfgmres.c).  This uses two wrapper structs

 MAT for the matrix [for matvecs] 
 PRE for the preconditoner (preconditioning operation). 

These  structs  include substructs  for  each  of the  data-structures
required by the above  preconditioners and pointers to functions. Only
one of these, along with  one matvec function needs to be instantiated
(set) for  the MAT  struct. Similarly one  member and  a corresponding
function  pointer of  PRE needs  to  be instantiated.  Thus, a  driver
mainPREC (resp mainPRECcoo) does the following steps

 1/ read the matrix in Harwell-Boeing (resp. coo) format
 2/ convert it to any required format 
 3/ construct the preconditioner -- get its struct -- say LU
 4/ set MAT, PRE [by filling the appropriate members] 
 5/ call zfgmres(MAT, PRE, + other parameters).
 6/ output various results in OUT/PRECON.out 

Once you  are familiar with  the preconditioners and  various structs,
you should  be able to  bypass the wrapper  structs MAT and  PREC.  In
fact a second way of using  the preconditioner is to build it directly
by  a  call  to  the  appropriate  function and  then  call  your  own
accelerator.  For example,  zfgmres  can be  easily  modified to  pass
directly the  structs needed for  the iteration.  For example  if your
preconditioner is ILUK and you have  the luptr struct LU and the csptr
struct CSMAT  for the preconditioner and matrix  respectively, you can
simply issue the call

    call zfgmres(CSRmat, LU, + other parameters).

and  replace  the matvec  routines  and  preconditioner  calls by  the
appropriate ones == These are available in LIB/MatOps.c

-------------------------------------------------------------------------
---------------- DETAILS ON THE PRECONDITIONERS -------------------------
-------------------------------------------------------------------------

ILU*       These are the standard ILU(k), ILUT, preconditioners and the
           new, Crout-based ILU preconditoner. ILUT and ILUK are simple
           translations of the corresonding version in the old sparskit.
           ILUC is new and it is written in an "experimental" version
           which allows various dropping strategies [5 different ones] 

	   drivers: mainILUThb,  mainILUKhb,  mainILUChb    and
                    mainILUTcoo, mainILUKcoo, mainILUCcoo	
           these produce the executables
                    zilut.ex     ziluk.ex     zilutc.ex 
          
        [** mainILUCcoo and the related preconditioner have been removed]

ARMS       Algebraic Multilevel Solvers.  This includes both the 
           standard ARMS and a version with nonsymmetric permutations
           which reorders the matrix by diagonal dominance. 
                      
           drivers mainARMS and mainARMScoo
           which produce the executable   zarms.ex

-------------------------------------------------------------------------
---------------- DETAILS ON THE DRIVERS ---------------------------------
-------------------------------------------------------------------------

Each main driver does reads input parameters from the file 
	
 inputs

This is done with the  function "read_inputs". The parameters that are
read are the same for all drivers  - though some of these are not used
by the drivers.  For example  droptol is not used by the level-of-fill
techniques  [iluk].  Note  that   the  arms  drivers  set  some  other
parameters to a default via the `set_arms_params' function -- which is
in the 'auxill.c' file.

The execution  of the driver consists  of looping through  a number of
matrices  in harwell-boeing  format and  for  each of  them, a  preset
number of tests is done. The list  of matrices used for the test is in
the file:
 
matfile_coo (coordinate format) and matfile_hb (harwell-Boeing format)

These files begin with a number "nmat" of matrices to be read followed
by  nmat lines  each  consisting of  a  pathname for  the matrix  file
followed by a short name that will be used for creating out filenames.
The other major  loop in the driver will  loop through parameters. The
parameters for  dropping are tightened  at each loop as  instructed by
the choice of lfilInc (how  to increase the lfil parameter) and tolMul
(scalar by which to multiply the drop tolerance at each new loop). 

SAMPLE_MATRICES: two sample matrices are in this subdirectory of
                 both TESTS_COO and TESTS_HB  for testing  

-----------------------------------------------------------------------
------------ porting itsol solvers into packages----------------------- 
-----------------------------------------------------------------------

It is recommended  to test the various solvers  with different options
to see what  works best. For this it is useful  to imitate the general
framework of the  drivers provided.  You can for  example generate the
matrix in  coordinate format and then  convert it to  the internal csr
format (called  SparRow) by  the function zCOOcs.   Then you  can call
whatever  preconditioner set-up  function (e.g.  zilut) to  obtain the
desired preconditioner- The pointers in MAT and PRE can then be set --
for example when using ILUT:

      MAT->n = n;                         matrix size
      MAT->CSR = csmat;                   matrix A itself [for matvecs]
      MAT->zmatvec = zmatvecCSR;          ptr to matvec routine 
      PRE->ILU = lu;                      preconditioner struct
      PRE->zprecon = zpreconILU;          ptr to corresponding precon oper.

You are now ready to call the accelerator:

      zfgmres(MAT, PRE, rhs, sol, tol, krydim, itmax, outputs);

-------------------------------------------------- updated Apr. 7th, 2008