README

Welcome to ML, the multilevel preconditioning package of Trilinos.

Contents of this README file are:

0) where you should look for ML documentation
1) configuring and compiling ML
2) testing ML
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 ML
9) copyright notice

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

You can find the latest ML User's Guide in the subdirectory

   ml/doc/mlguide.pdf.

This address also contains up-to-date doxygen documentation. 
You can create a local Doxygen documentation as follows:

   $ cd Trilinos/ml/doc
   $ doxygen

Doxygen files mainly refer to the C++ interface of ML, and discuss several
examples in detail.

An history of ML changes is contained in the file ChangeLog.


------------------------------------------------------------------------------
section 1: configuring and compiling ML
------------------------------------------------------------------------------


------------------------------------------------------------------------------
section 2: testing ML
------------------------------------------------------------------------------

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

   $ cd <your-ml-build-directory>
   $ cd examples
   $ ../test/scripts/daily/mpi/TestExamples.exe

The test will execute a subset of the examples and save the results to a log
file in ml/examples.

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

doc/                        ML documentation
etc/                        various scripts and utilities for developers
examples/                   ML examples
ChangeLog-ML                an (incomplete) history of ML changes
README-ML                   this file
src/                        ML source files
util/                       various utility programs, such as file converters


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

Please refer to the README files in the examples subdirectories.


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

The subdirectory ml/test contains several test harness source files.
These files are meant primarily for ML developers.


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


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

Users are encouraged to subscribe to the following mailing lists:

*) ml-announce@software.sandia.gov
*) ml-users@software.sandia.gov

Please refer to the ML web page for more details.


------------------------------------------------------------------------------
section 8: how to cite ML
------------------------------------------------------------------------------

ML can be cited using the following BiBTeX entry:

@TechReport{ml_users_guide,
  AUTHOR = {M. Sala and J.J. Hu and R.S. Tuminaro},
  TITLE = "{ML}3.1 {S}moothed {A}ggregation {U}ser's {G}uide",
  INSTITUTION =  "Sandia National Laboratories",
  NUMBER = "SAND2004-4821",
  ADDRESS = "Albuquerque, NM (USA)",
  YEAR = "2004"
}


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

               ML: A Multilevel Preconditioner Package
                 Copyright (2001) 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 Jonathan Hu or Ray Tuminaro ({jhu|rstumin}@sandia.gov).

Please submit ML bugs with at software.sandia.gov/buzgilla, or
report bugs to {jhu|rstumin}@sandia.gov.