
Pivoting ILU Preconditioner for PETSc
-------------------------------------

Author: Sivan Toledo, Tel-Aviv University (was at Xerox PARC at the time
        the code was written), 	sivan@math.tau.ac.il
        and 
        John R. Gilbert, Xerox PARC


Installation
------------

You should have PETSC installed. PETSc is available from 
http://www.mcs.anl.gov:80/petsc

We have tested the code with PETSc version 2.0.22. We have also
used the code with PETSc version 2.0.15, but we have updated our
code to work with the most recent version of PETSc (2.0.22) and
it no longer works with the older version.

You should also install the pivoting ILU library, called gp.
It is contained in the subdirectory gp. Installing GP requires
a Fortran Compiler. To install gp, you should
go to the directory gp, update the makefile and type make.
Usually the only things that should be changed in the makefile
are the names of the C and Fortran 77 compilers and their options.
Typing make should generate the library libgp.a, which you will 
later need.

Next, update root directory for PETSc in the makefile in the main 
directory and type 
  make BOPT=g ex1
(the parameter BOPT tells the PETSc makefiles which compiler options
you want, such as -g, -O, etc; you should have specified them when
you built PETSc; an installation of PETSc can have multiple libraries
for multiple compiler settings.) This should make the example program
called ex1. 

The script runexample runs the example program several times
on a matrix called lhr01 without reordering it.

Usage
-----

To use the pivoting ILU preconditioner, you need to:
  1. Call a precondioned linear solver (e.g. GMRES) with a squantial
     AIJ matrix. The preconditioner does not work on distributed matrices.
     The matrix has to be real, but does not need to have any special
     structure (that is, general sparse nonsymmetric matrices are allowed).
  2. Specify an LU preconditioner either using the command line option
     -pc_type lu 
     or using the function call
     ierr = PCSetType(pc,PCLU); 
     where pc is the preconditioner object returned by SLESGetPC.
  3. Modify the matrix object of the coefficient to use the incomplete
     factorization library gp rather than the default LU solver. This
     is done using the call
     ierr = MatUseGP_SeqAIJ(A);
     where A is the matrix object.

As far as your program goes, that's it!

The construction of the preconditioner is controlled using three
command line options (which can also be set using OptionSetValue).
One parameter, -mat_lu_pivotthreshold, controls pivoting. A value
of 1.0 means normal partial pivoting, a value of 0.0 means no pivoting.
Intermediate values allow the code to not pivot in columns in which
the diagonal element is relatively large in absolute value, even
if there are larger elements in the column.

The two other parameters control dropping strategy.  The elements in
the original nonzero pattern of A are never dropped.  

One parameter, called -pc_ilu_col_fill_ratio, allows the number of
nonzeros in each column to increase up to a given factor. For example,
setting the value to 1 allows each column in U and each column in L to
have as many nonzeros as the same column in A. A value of 2 allows
twice as many and so on. The largest elements in the columns of U and
L are retained, small elements are dropped. This option is usefull for
controlling the amount of memory that the factors use.

If the value of -pc_ilu_col_fill_ratio is negative, however, no limit
is set on the number of nonzeros in the columns of U and L. Instead
a parameter called -pc_ilu_use_drop_tolerance is used to control 
dropping. Elements in a  column of U that are larger than this
parameter times the largest element (in absolute value) are retained,
others are dropped. The same process is repeated for L. Thus, a value
of 0.0 means no dropping, a value of 1.0 means dropping everying not
in the nonzero pattern of A. If -pc_ilu_col_fill_ratio is positive,
this parameter is ignored.

The example script demonstrates the use of these parameters.
The matrix lhr01 cannot be solved without pivoting, so all
the solution attempts without pivoting fail. When pivoting is
allowed, the solver still fails when too little fill is allowed
(drop tolerance of 0.1 or fill ratio of 1), but it converges
when more fill is allowed (drop tolerance of 0.01 or fill ratio
of 12).

Support
-------

Drop me a line (sivan@math.tau.ac.il) if you encounter
problems with this code or if you have suggestions for
improvements. I will try to address the issues that you
raise.

Additional Documentation
------------------------

The file ilu.ps.gz contains a technical paper that describes this
preconditioner, its behavior on several matrices, and comparisons
with the performance of a direct solver.

