/* @HEADER@ */

/* @HEADER@ */

namespace Playa
{
/*! \mainpage Playa: Painless Linear Algebra

Playa is a user-friendly, representation-independent system of components
for development of high-performance 
parallel linear solvers, nonlinear solvers, and optimizers.

The five fundamental Playa object types are 
VectorType, VectorSpace, Vector, LinearOperator, and LinearSolver. 

<ul>
<li> VectorType is an abstract factory that produces VectorSpace objects
of a user-specified type, dimension, and distribution across processors.
<li> VectorSpace is an abstract factory that produces Vector objects. This 
provides a consistent user interface for creating vectors without
the client code needing to know anything about what sort of vector
object is being created. 
<li> Vector objects represent vectors. In addition to the fundamental
operations of vector addition and scalar-vector multiplication,
arbitrary user-defined transformation and reduction operations can be
implemented through application of templated functors. Some examples
of such functors are in the PlayaFunctors namespace.
<li> LinearOperator objects represent linear functions that map vector inputs
to vector outputs.
<li> LinearSolver is an object wrapper for algorithms for solving linear
systems of equations \f$ A{\bf x}={\bf b}.\f$ Solvers from several Trilinos 
packages are available through this interface: Amesos, AztecOO, and Belos, 
with preconditioning by Ifpack and ML. For specialized
applications, user-defined solvers and
preconditioners can be constructed out of Playa objects.
</ul>

<H3> Contributors to Playa  </H3>

<ul>
<li> <A HREF="http://www.math.ttu.edu/~klong/"> Kevin Long </A>
-- Texas Tech University. Email <A HREF="mailto:kevin.long@ttu.edu"> kevin.long@ttu.edu </A>
<li> <A HREF="http://csmr.ca.sandia.gov/~ptboggs/"> Paul Boggs </A>
--  Sandia National Laboratories, Livermore. 
<li> <A HREF="http://www.math.ttu.edu/~vhowle/"> Victoria Howle </A>
-- Texas Tech University. 
<li> <A HREF="http://www.math.ttu.edu/~kirby/"> Robert Kirby </A>
-- Texas Tech University. 
</ul>

<H1> Quick start guide </H1>

<H2> Creating spaces and vectors </H2>
Vectors are rarely constructed directly by the user. Instead, they are usually created by a call to the createMember() method of VectorSpace. Similarly,
a VectorSpace is usually constructed indirectly by one of the methods of a
VectorType object.
The user's choice of VectorType subclass specifies which internal object
representation will be used.
<ul>
<li> EpetraVectorType specifies Epetra distributed vectors and matrices
<li> SerialVectorType specifies serial vectors and dense matrices. 
If called in a SPMD program the spaces and vectors created will be replicated
on each processor.
</ul>
Here's how to create a Vector distributed with 10 elements per processer, 
represented internally by an Epetra_Vector object. 
\code
VectorType<double> vecType = new EpetraVectorType();
int numPerProc = 10;
VectorSpace<double> space = vecType.createEvenlyPartitionedSpace(MPIComm::world(), numPerProc);
Vector<double> x = space.createMember();
\endcode
Spaces with more complicated distributions of data over processors can be
created with the createSpace() method of VectorType.



<H2> Implicit operators </H2>

<ul>
<li> identityOperator() creates a matrix-free identity operator on a specified VectorSpace
<li> zeroOperator() forms a matrix-free zero operator on specified range and domain spaces
<li> diagonalOperator() forms a matrix-free diagonal operator with a specified vector
<li> makeBlockOperator() 
<li> transposedOperator() creates an operator that performs a matrix-free transpose application
<li> inverse() creates an implicit inverse of the specified LinearOperator with
the solves carried out using the specified LinearSolver.
</ul>

In addition, certain implicit operations can be specified using 
overloaded operators:
<ul>
<li> Operator addition and subtraction
\code
LinearOperator<double> APlusB = A+B;
\endcode
<li> Scalar-operator multiplication 
\code
LinearOperator<double> aTimesA = a*A;
\endcode
<li> Operator composition
\code
LinearOperator<double> AB = A*B;
\endcode
</ul>
All of these form implicit operators. For example, \f$z=ABx\f$ is computed
by first computing \f$y=Bx\f$, then \f$z=Ay\f$. The matrix-matrix product
\f$ AB\f$ is never explicitly formed.

The implicit inverse and transpose operations can also be done through member functions of LinearOperator, for example,
\code
LinearOperator<double> AInv = A.inverse(mySolver);
LinearOperator<double> ATrans = A.transpose();
\endcode



<H2> Solvers </H2>

Linear solver algorithms are represented by subtypes of LinearSolver.

<H4> Preconditoners </H4>

The Preconditioner object stores a preconditioner with 
left and right operators. A preconditioner instance will rarely be
created directly by the user; it will be created
inside a solver by a user-specified subtype of PreconditionerFactory.

<H2> Solver Parameters </H2>

Linear solvers are usually created from Teuchos ParameterList objects. 

\code
LinearSolver<double> amesos = LinearSolverBuilder::createSolver("amesos.xml");
\endcode

\code
LinearSolver<double> solver = LinearSolverBuilder::createSolver(solverParams);
\endcode



<H4> Amesos parameter example </H4>
Amesos is a serial sparse direct solver package.
\code
<ParameterList>
  <ParameterList name="Linear Solver">
    <Parameter name="Type" type="string" value="Amesos"/>
    <Parameter name="Verbosity" type="int" value="0"/>
  </ParameterList>
</ParameterList>
\endcode

<H4> Belos parameter examples </H4>
<ul> 
<li> Parameters for Belos GMRES with ML preconditioning
\code
<ParameterList>
  <ParameterList name="Linear Solver">
    <Parameter name="Type" type="string" value="Belos"/>
    <Parameter name="Maximum Iterations" type="int" value="1000"/>
    <Parameter name="Method" type="string" value="GMRES"/>
    <ParameterList name="Preconditioner">
       <Parameter name="Type" type="string" value="ML"/>
       <Parameter name="Problem Type" type="string" value="SA"/>
       <ParameterList name="ML Settings">
          <Parameter name="output" type="int" value="10"/>
       </ParameterList>
    </ParameterList> 
    <Parameter name="Convergence Tolerance" type="double" value="1e-12"/>
    <Parameter name="Output Frequency" type="int" value="0"/>
    <!-- num blocks is the restart size -->
    <Parameter name="Num Blocks" type="int" value="200"/>
    <Parameter name="Block Size" type="int" value="1"/>
  </ParameterList>
</ParameterList>
\endcode
<li> Parameters for Belos GMRES with ILU preconditioning
\code
<ParameterList>
  <ParameterList name="Linear Solver">
    <Parameter name="Type" type="string" value="Belos"/>
    <Parameter name="Maximum Iterations" type="int" value="500"/>
    <Parameter name="Method" type="string" value="GMRES"/>
    <ParameterList name="Preconditioner">
       <Parameter name="Type" type="string" value="Ifpack"/>
       <Parameter name="Prec Type" type="string" value="ILU"/>
       <Parameter name="Overlap" type="int" value="1"/>
       <ParameterList name="Ifpack Settings">
          <Parameter name="fact: level-of-fill" type="int" value="2"/>
       </ParameterList>
    </ParameterList> 
    <Parameter name="Convergence Tolerance" type="double" value="1e-10"/>
    <Parameter name="Output Frequency" type="int" value="0"/>
    <!-- num blocks is the restart size -->
    <Parameter name="Num Blocks" type="int" value="200"/>
    <Parameter name="Block Size" type="int" value="1"/>
    <!-- set verbosity to 33 or 41 for useful diagnostics -->
    <Parameter name="Verbosity" type="int" value="0"/>
  </ParameterList>
</ParameterList>
\endcode
</ul>

<H4> Aztec parameter examples </H4>
\code
<ParameterList>
  <ParameterList name="Linear Solver">
    <Parameter name="Max Iterations" type="int" value="500"/>
    <Parameter name="Method" type="string" value="GMRES"/>
    <ParameterList name="Preconditioner">
       <Parameter name="Type" type="string" value="ML"/>
       <Parameter name="Problem Type" type="string" value="SA"/>
       <ParameterList name="ML Settings">
          <Parameter name="output" type="int" value="10"/>
       </ParameterList>
    </ParameterList> 
    <Parameter name="Tolerance" type="double" value="1e-12"/>
    <Parameter name="Type" type="string" value="Aztec"/>
    <Parameter name="Verbosity" type="int" value="0"/>
  </ParameterList>
</ParameterList>
\endcode

*/
}