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., 59 Temple Place, Suite 330, Boston, MA 02111-1307 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)