-*- text -*-

//=======================================================================
// Copyright (C) 1997-2001
// Authors: Andrew Lumsdaine <lums@osl.iu.edu> 
//          Lie-Quan Lee     <llee@osl.iu.edu>
//
// This file is part of the Iterative Template Library
//
// You should have received a copy of the License Agreement for the
// Iterative Template Library along with the software;  see the
// file LICENSE.  
//
// Permission to modify the code and to distribute modified code is
// granted, provided the text of this NOTICE is retained, a notice that
// the code was modified is included with the above COPYRIGHT NOTICE and
// with the COPYRIGHT NOTICE in the LICENSE file, and that the LICENSE
// file is distributed with the modified code.
//
// LICENSOR MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED.
// By way of example, but not limitation, Licensor MAKES NO
// REPRESENTATIONS OR WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY
// PARTICULAR PURPOSE OR THAT THE USE OF THE LICENSED SOFTWARE COMPONENTS
// OR DOCUMENTATION WILL NOT INFRINGE ANY PATENTS, COPYRIGHTS, TRADEMARKS
// OR OTHER RIGHTS.
//=======================================================================

---------------------------------------------------------------

              The Iterative Template Library Alpha Release

I. Introduction
---------------

The Iterative Template Library (ITL) has two parts, iterative solvers
and precondtioenrs. ITL provides a collection of sophisticated Krylov
subspace iterative solvers that use basic linear algebra packages such
as the Matrix Template Library or Blitz++ for its basic linear algebra
operations. The ITL has extended many of the ideas of the Iterative
Methods Library (IML++), to make the library more flexible.  The
"interface" is to specify basic linear algebra operations. See next
bullet for details. On the other hand, ITL also provides a set of
preconditioners which are designed for Matrix Template Library.

II. Status
----------

a) ITL currently includes the following Krylov supbspace methods: 

  Conjugate Gradient (cg) 
  Conjugate Gradient Squared (cgs) 
  BiConjugate Gradient (bicg) 
  BiConjugate Gradient Stabilized (bicgstab) 
  Chebyshev Iteration (cheby)
  Richardson Iteration (richardson)
  Generalized Conjugate Residual (gcr)
  Generalized Minimal Residual (gmres) 
  Quasi-Minimal Residual Without Lookahead (qmr) 
  Transpose Free Quasi-Minimal Residual Without Lookahead (tfqmr) 

  All algorithms are under itl/krylov directory. Those algorithms are
generic.  And they are not limited to MTL or Blitz++ or BLAS. Users
can use them with their own libraries by creating an interface to
their own libraries which provide basic linear operations.

b) ITL currently includes the following preconditioners: 

  Incomplete Cholesky (cholesky)
  Incomplete LU without fill-in (ILU)
  Incomplete LU with n fill-in and with threshold (ILUT)
  SSOR 
  Diagonal
  Modified Incomplete cholesky
  Sparse approximate inverse (this is experimental)
  
  All preconditioners are under itl/preconditioner directory. Notice
that All precondtioners are designed for MTL matrices only, mostly for
sparse MTL matrices.

c) "Interface" is to provide an interface :-) to a basic linear
algebra package so that ITL algorithms can have basic linear algebra
operations.  ITL includes following interfaces:

   MTL (itl/interface/mtl.h)
     Use MTL matrices and vectors. 

   BLAS (itl/interface/blas.h)
     CSR matrices and std::vector can be used. 
  
   Blitz++ (itl/interface/bltz.h)
     Blitz++ arrays can be used with matrix-free operator.
     
   Mtl parallel (itl/interface/mtl_parallel.h)
     MTL row-wise matrices and vectors can be used. Using this interface with
     ITL provides parallelized Krylov subspace iterative solvers.

   BLAS parallel (itl/interface/blas_parallel.h)
     CSR matrices and std::vector can be used. Using this interface with
     ITL provides parallelized Krylov subspace iterative solvers.
     

III. Tests
----------

The /test directory contains tests for the ITL functions.
The matrix files are from the harwell boeing collection.

The following compilers has been tested to compile ITL:
  MIPSpro 7.3 
  KCC 3.4g 
  KCC 4.0
  gcc-2.95.2 
  gcc-2.96
  gcc-3.01 

IV. Installation
----------------
a)Unpack the tarball and enter the top source directory:

  gzip -cd itl-X.X.X-X.tar.gz | tar xvf -
  cd itl-X.X.X-X 

b)Configure it with options:
 
./configure --with-mtl=MTL_DIR

  Where MTL_DIR is the path to MTL package top directory. Notice that
  blitz example and parallel examples will *NOT* compile since this 
  configuration did not specify blitz package path and mpi. 

or 
./configure --with-mtl=MTL_DIR --with-blitz=BLITZ_DIR

  Where MTL_DIR is the path to MTL package top directory. And BLITZ_DIR
  is the path to Blitz++ package. Notice that parallel examples will
  *NOT* compile since this configuration did not specify mpi.

or

./configure --with-mtl=MTL_DIR --with-mpi=lam --with-blitz=BLITZ_DIR

  Where MTL_DIR is the path to MTL package top directory. And BLITZ_DIR
  is the path to Blitz++ package. For parallel interface, only LAM/MPI
  is tested. 
  

c) The ITL consists only of header files, so you only need include the
proper file.  In regards to compilers, you can use gcc 2.95.x, KCC
v3.3x or VC++ SP5 to compile ITL. 

ITL needs a basic linear algebra package to provide matrix-vector,
vector-vector and vector-scalar operation. Blitz++, MTL or BLAS
interfaces are included in the distribution. MTL is default one. To
use preconditioners, MTL is necessary. MTL release 2.1.2-20 is
recommended. You could download MTL at 
http://www.lsc.nd.edu/research/mtl


V. Documention 
--------------

The latest documentation for ITL can be found on our website:

    http://www.osl.iu.edu/research/itl

VI. Examples
------------

There are also several examples in the distribution, in /examples.  In
addition, /examples/laplacian contains examples to solve laplace
equation.  /examples/blitz contains example to solve bratu problem
using blitz with matrix-free method.  /examples/interface contains an
example interface in which matrix is a vector of vectors while vector
is an stl vector. /exmaples/parallel contains examples to use parallel
interface. LAM/MPI is assumed in the parallel interface.

VII. Contact Information
-----------------------

The Iterative Template Library is available at the main distribution
site:

    http://www.osl.iu.edu/research/itl

Bug reports should be sent to mtl@osl.iu.edu

Questions, comments, suggestions, and requests for additional
information should also be directed to mtl@osl.iu.edu.

