README-IFPACK

Welcome to IFPACK, the Robust Algebraic Preconditioning Package of Trilinos

Contents of this README file are:

0) where you should look for IFPACK documentation
1) configuring and compiling IFPACK
2) testing IFPACK
3) directory organization
4) organization of the examples
5) organization and scope of the tests
6) how to submit bugs
7) mailing lists
8) how to cite IFPACK
9) copyright notice

------------------------------------------------------------------------------
section 0: where you should look for IFPACK documentation
------------------------------------------------------------------------------

You can download the IFPACK User's Guide at the web address

   http://trilinos.sandia.gov/packages/ml/

This address also contains up-to-date doxygen documentation. 
You can create a local Doxygen documentation by simply typing 

   $ doxygen

in the ml/doc subdirectory. Doxygen files mainly refer to the C++ interface
of IFPACK, and discuss in some details several examples.

An (incomplete) history of IFPACK changes is contained in file ChangeLog.


------------------------------------------------------------------------------
section 1: configuring and compiling IFPACK
------------------------------------------------------------------------------

We suggest to configure and compile IFPACK through the Trilinos configure
script. For instance, you might need something like
 
   $ cd Trilinos
   $ mkdir LINUX_SERIAL
   $ cd LINUX_SERIAL
   $ ../configure
   $ make
   
On most machines, an MPI configuration can be configured by simply
typing

   $ cd Trilinos
   $ mkdir LINUX_MPI
   $ cd LINUX_MPI
   $ ../configure --with-mpi-compilers
   $ make


------------------------------------------------------------------------------
section 2: testing IFPACK
------------------------------------------------------------------------------

Once IFPACK is compiled, a simple sanity check can be performed as follows:

   $ cd <your-ml-build-directory>
   $ cd example
   $ ./test.exe

The BASH script test will execute most of the examples, and verify that the exit
code of all of them.


------------------------------------------------------------------------------
section 3: directory organization
------------------------------------------------------------------------------

aclocal.m4                  autoconf file
autom4te.cache/             autoconf directory
bootstrap                   autoconf/automake file
config/                     autoconf m4 macros
configure                   autoconf file
configure.ac                autoconf file
CVS/
doc/                        IFPACK documentation
examples/                   IFPACK examples
Makefile.am                 automake file
Makefile.in                 automake file
Changelog                   an (incomplete) history of IFPACK changes
README                      this file
src/                        IFPACK source files


------------------------------------------------------------------------------
section 4: organization of the examples
------------------------------------------------------------------------------

The following files, located in Trilinos/packages/ifpack/examples, can be
used to understand the basic usage of IFPACK:

*) Ifpack_ex_Factory: explains how to define IFPACK preconditioners using
                      the Factory class. This is probably the easiest way
                      to use IFPACK. Beginners should start from this file.

*) Ifpack_ex_ICT.exe: explains how to define incomplete Cholesky
                      preconditioners.

*) Ifpack_ex_MatrixMarket.exe: explains how to read a matrix in matrix-market
                      format, distribute it among the available processes,
                      and use IFPACK preconditioners to solve the
                      corresponding linear system.

*) Ifpack_ex_Amesos.exe: explains how to use complete (exact) LU
                      factorizations on each subdomain, using the Amesos package.

*) Ifpack_ex_BlockRelaxation.exe: explains how to define block relaxation
                      methods.

*) Ifpack_ex_Filtering.exe: explains how to modify the linear system matrix,
                      in order to improve the quality of the incomplete
                      factors (for IC, ICT, ILU and ILUT).

*) Ifpack_ex_Test.exe: explains how to test several IFPACK parameters,
                      on a matrix read from file using EpetraExt.

*) Ifpack_ex_Reordering.exe: details how reordering works within IFPACK. Only
                      for advanced users.

*) Ifpack_ex_SingletonFilter.exe: details how singleton filtering works with
                      IFPACK. Only for advanced users.


------------------------------------------------------------------------------
section 5: organization and scope of the tests
------------------------------------------------------------------------------

Subdirectory test contains several test harness source files.
These files are meant for developers and not for users. A simple script,
located in the examples subdirectory, can be adopted by users to perform
a basic and quick sanity check of IFPACK.


------------------------------------------------------------------------------
section 6: how to submit bugs
------------------------------------------------------------------------------

Bugs and enhancements can be submitted through bugzilla at the web page

   http://software.sandia.gov/bugzilla

(select IFPACK in the list of packages).
You will need to create a bugzilla account. Otherwise, simply e-mail
to one of the developers.


------------------------------------------------------------------------------
section 7: mailing lists
------------------------------------------------------------------------------

Users can subscribe to the following mailing lists:
*) ifpack-announce@software.sandia.gov
*) ifpack-users@software.sandia.gov

Please refer to the IFPACK web page for more details.


------------------------------------------------------------------------------
section 8: how to cite IFPACK
------------------------------------------------------------------------------

IFPACK can be cited using the following BiBTeX entry:

@TechReport{ifpack_users_guide,
  AUTHOR = {M. Sala and M.A. Heroux}
  TITLE = "{IFPACK} 3.0 {U}ser's {G}uide",
  INSTITUTION =  "Sandia National Laboratories",
  NUMBER = "SAND2005-XXX",
  ADDRESS = "Albuquerque, NM (USA)",
  YEAR = "2005"
}


------------------------------------------------------------------------------
section 9: copyright
------------------------------------------------------------------------------

               IFPACK: Robust Algebraic Preconditioning Package
                 Copyright (2005) Sandia Corporation

Under terms of Contract DE-AC04-94AL85000, there is a non-exclusive
license for use of this work by or on behalf of the U.S. Government.

This library is free software; you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as
published by the Free Software Foundation; either version 2.1 of the
License, or (at your option) any later version.
 
This library is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Lesser General Public License for more details.
 
You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301
USA
Questions? Contact Michael A. Heroux (maherou@sandia.gov) 

Please submit IFPACK bugs with at software.sandia.gov/buzgilla, or
report bugs to maherou@sandia.gov
	
------------------------------------------------------------------------------
(This file was last updated on 22-Jan-05)