README

Welcome to Amesos, a set of interfaces to third-party direct solvers.

Contents of this README file are:

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

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

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

   Trilinos/packages/amesos/doc/AmesosReferenceGuide/AmesosReferenceGuide.pdf

Alternatively, you can download the Amesos User's Guide at the web address

   http://trilinos.sandia.gov/packages/amesos/AmesosReferenceGuide.pdf

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

   % cd Trilinos/amesos/doc
   % doxygen

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

An history of Amesos changes is contained in the file ChangeLog-Amesos.

An overview of the Python/Amesos interface is available in the PyTrilinos
package.


------------------------------------------------------------------------------
section 1: configuring and compiling Amesos
------------------------------------------------------------------------------

Please refer to the doxygen documentation for more details. Here, we only
report a very basic installation, which simply consists of adding
--enable-amesos to your Trilinos configure script. This will enable the
support for LAPACK and KLU (Amesos' internal serial sparse solver). For
example, you might do
 
   % cd Trilinos
   % mkdir LINUX_SERIAL
   % cd LINUX_SERIAL
   % ../configure --enable-amesos
   % make
   % make install
   
On most machines, an MPI-enabled Trilinos build can be created by simply
typing

   % cd Trilinos
   % mkdir LINUX_MPI
   % cd LINUX_MPI
   % ../configure --enable-amesos --with-mpi-compilers
   % make
   % make install

You might want to enable the Python support for Amesos. This requires
Python, Numeric and SWIG installed on your system. Please consult the
PyTrilinos documentation for more details.


------------------------------------------------------------------------------
section 2: testing Amesos
------------------------------------------------------------------------------

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

   % cd <your-amesos-build-directory>
   % cd examples
   % ./compare_solvers.exe

or, for parallel runs,

   % mpirun -np 4 ./compare_solvers.exe

(The exact MPI command depends on your MPI installation.) This executable
will test all enabled interfaces on a simple problem. All interfaces should
be able to solve the linear system "exactly", and the executable should return
EXIT_SUCCESS.


------------------------------------------------------------------------------
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
COPYRIGHT                   copyright information
CVS/                        Concurrent Versions System data
doc/                        Amesos documentation
doc/AmesosReferenceGuide    PDF version of the guide
example/                    Amesos examples
python/src                  Python interface to Amesos
python/example              Python/Amesos examples
Makefile.am                 automake file
Makefile.in                 automake file
Changelog-Amesos            an (incomplete) history of Amesos changes
README-Amesos               this file
src/                        Amesos source files


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

Please refer to the Doxygen documentation for more details.


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

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


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

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

   http://software.sandia.gov/bugzilla

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


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

Users are encouraged to subscribe to the following mailing lists:

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

Please refer to the Amesos web page for more details.


------------------------------------------------------------------------------
section 8: how to cite Amesos
------------------------------------------------------------------------------

Amesos can be cited using the following BiBTeX entry:

@TechReport{Amesos_users_guide,
  AUTHOR = {M. Sala},
  TITLE = "{Amesos} 2.0 Reference Guide},
  INSTITUTION =  "Sandia National Laboratories",
  NUMBER = "SAND2004-4820",
  ADDRESS = "Albuquerque, NM (USA)",
  YEAR = "2004"
}


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

                          Amesos
                 Copyright (2002) 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 Amesos bugs with at software.sandia.gov/buzgilla.