===============================================================================

#  Current revision: $Revision$
#  Branch:           $Branch$
#  Last modified:    $Date$
#  Modified by:      $Author$

===============================================================================

Attention new users!!
This file contains a short description of the most relevant ML examples.

===============================================================================

Files and directories in ml/examples:

BasicExamples/              ** Beginning users should start here **
Elasticity/                 Solving elasticy problems (scalar)
ExampleMatrices/            Input matrices for Elasticity examples
MatrixFormats/              Various matrix storage types available (e.g., CSR)
MatrixReading/              Reading in various matrix types from file
Maxwell/                    Solving eddy current equations
StandAlone/                 Using ML without other Trilinos packages
TwoLevelDD/                 Preconditioning with two-level domain decomposition
Visualization/              Using ML's visualization capabilities
MultipleRHS/                Solving systems with multiple right-hand-sides
Advanced/                   Advanced usage:  filtering, preconditioner analysis
Other/                      Examples that don't fit into other categories
XML/                        Shows how to set the ML parameters using
                            an XML file
MLAPI/                      Shows how to write MATLAB-like codes using the
                            MLAPI, the Application Program Interface of ML.
FiniteElements/             A simple finite element code for scalar, second 
                            order symmetric and non-symmetric (SUPG) PDEs, for
                            both serial and parallel runs. NOW CONTAINED IN
                            THE GALERI PACKAGE (Trilinos/packages/galeri),
                            THIS DIRECTORY DOES NO LONGER EXIST IN THE ML
                            PACKAGE.
README                      this file
README.AddingExamples       (for developers) instructions on adding examples

===============================================================================

Files in ml/examples/BasicExamples/

*) ml_preconditioner.cpp (RECOMMENDED, START HERE):

The goal of this example is to present the basic usage of the
ML_Epetra::MultiLevelPreconditioner class.  The example builds a simple matrix
and solves the corresponding linear system using AztecOO and ML as a
preconditioner. It finally checks the accuracy of the computed solution. 
This is the simplest way of using ML.

*) ml_aztec_simple.c:

This example creates a simple matrix, corresponding to a 2D Laplacian on a
structured grid, as an Aztec matrix. This matrix is wrapped as an ML_Operator,
then the V-cycle is built, and the resulting preconditioner is used within
Aztec (C version). The example works with the AztecOO distributed within
Trilinos.

*) ml_operator.cpp:

The goal of this example is to present the usage of the
ML_Epetra::MultiLevelOperator class. This can should be used if the
user wants to build all the ML components by him/herself (starting
from an Epetra_RowMatrix), then use the resulting ML preconditioner within 
AztecOO. 

*) ml_readex.c:

The goal of this example is to read old Aztec files (.data) and
use the old/low level multigrid interface to set up a preconditioner.
A hidden file '.data' is included which correspond to a simple finite
element model of a Laplacian.

===============================================================================

files in ml/examples/MatrixReading/

*) ml_read_matrix_AIJ.cpp

This example reads a matrix in AIJ format, and creates
the corresponding Epetra_CrsMatrix. Then matrix is then
distributed over all the available processes.

===============================================================================

files in ml/examples/Maxwell

*) ml_simple_max.c

Sample driver for Maxwell equation AMG solver in the ML package. The 
software is tested by setting up a 2-dimensional uniform grid example on 
a square. Two different ways of creating matrices are shown.

*) ml_maxwell.cpp

Sample driver for Maxwell equation AMG solver in the ML package. The
software is tested by setting up a 2-dimensional uniform grid example on
a square. For details about the problem at hand, please refer to file
ml_simple_max.c, of which this file is the C++ counterpart.

===============================================================================

files in ml/examples/StandAlone/

*) mlguide.c

description of the ML interface functions for a simple, 1D problem. Must be run
with one processor. This example does not require any other Trilinos packages.

*) mlguide_par.c

description of the ML interface functions in parallel. Must be run with two
processors. This example does not require any other Trilinos packages.

===============================================================================

files in ml/examples/TwoLevelDD

*) ml_2level_DD.cpp

Goal of this example is to present how to define two-level domain decomposition
preconditioner based on aggregation procedures using class 
ML_Epetra::MultiLevelPreconditioner.

===============================================================================

files in ml/examples/Visualization

*) ml_viz.cpp

Goal of this example is to present the visualization capabilities of
ML. Using ML, the user can visualize the aggregates for all levels.
This requires, as additional input, the coordinates of the fine-grid
nodes. The output file is simple collection of 2D or 3D points,
each of them containing the (double) value of the aggregate it belongs to.
A freely-downloadable software, called XD3D, can for example
be used to visualize the aggregates. ML can also visualize the effect
of smoothers and the entire ML cycle on random vectors; see the
`visualization' section of this example.

===============================================================================

files in ml/examples/MatrixFormats

*) ml_MatrixFree.cpp

Goal of this example if to show how to take advantage of the getrow()
to define matrix-free operator using the MultiLevelPreconditioner class.
The example defines a 3D Laplacian on a structured Cartesian grid; the  
problem is discretized using a classical 7-point formula, but the values
of the matrix are never stored, and the rows are created "on-the-fly" at
each call to getrow().

===============================================================================

files in ml/examples/XML

*) ml_XML.cpp:

The goal of this example is to show how to modify the parameter list 
that is stored within the MultiLevelPreconditioner class without 
recompiling the application. A set of parameters to be added is stored
in a file, called ml_ParameterList.xml, located in the working
directory. This file is parsed, and its content is used to build
the preconditioner.
