/*! \namespace Anasazi * \brief Namespace %Anasazi contains the classes, structs, enums and utilities used by the %Anasazi package. */ /*! @defgroup anasazi_opvec_interfaces Anasazi Operator/Vector Interfaces %Anasazi utilizes abstract interfaces for operators and multivectors to enable the leveraging of existing linear algebra libraries. The choice in linear algebra is made through templating, and access to the functionality of the underlying objects is provided via the traits classes Anasazi::MultiVecTraits and Anasazi::OperatorTraits. Anasazi::MultiVecTraits requires two template arguments: - a scalar class (\c ScalarType), describing the field over which the multivectors are defined, and - a multivector class (\c MV). Because %Anasazi implements block eigensolvers, the underlying primitive is a collection of column vectors (a multivector) instead of a single column vector. The purpose of Anasazi::MultiVecTraits is to provide an interface for performing multivector operations (e.g., multivector \c AXPY). An example illustrating the manipulation of an Epetra_MultiVector using Anasazi::MultiVecTraits follows: \code // build some Epetra_MultiVector objects... Epetra_MultiVector A(...), B(...), C(...); // ...and a Teuchos::SerialDenseMatrix Teuchos::SerialDenseMatrix D(...); typedef Anasazi::MultiVecTraits MVT; // perform C <- 1.0*A + 0.5*B; MVT::MvAddMv(1.0, A, 0.5, B, C); // perform C <- -2.0*A*D + 1.0*C MVT::MvTimesMatAddMv(-2.0, A, D, 1.0, C); \endcode As is customary among large-scale eigenvalue software, %Anasazi assumes matrix-free access to the problem operators, i.e., only matrix-vector products are needed. Therefore, Anasazi::OperatorTraits requires three template arguments: - a scalar class (\c ScalarType), describing the field over which the multivectors are defined, - a multivector class (\c MV), describing the domain and range of the operator, and - an operator class (\c OP). The Anasazi::OperatorTraits interface provides a single mechanism: the ability to apply an operator of type \c OP to a multivector of type MV, yielding another multivector of type \c MV. This is performed as follows: \code // build some Epetra_MultiVector objects... Epetra_MultiVector A(...), B(...); // ...and an Epetra operator Epetra_Operator Op(...); // apply the operation B <- Op*A typedef Anasazi::OperatorTraits OPT; OPT::Apply(Op,A,B); \endcode These interfaces are used throughout %Anasazi to manipulate multivectors and apply operators, so that no low-level access to the underlying objects are needed. Hence, %Anasazi is independent of the underlying linear algebra data structures (e.g., serial or parallel, real or complex). This allows the generic programming of algorithms for the solution of eigenvalue problems. Calling methods of MultiVecTraits requires that a specialization of MultiVecTraits has been implemented for classes ScalarType and \c MV. In the case of Epetra_MultiVector and Epetra_Operator (which are both defined on the field of doubles), this specialization is provided by the %Anasazi adapters to Epetra. Specializations of these traits classes provided by %Anasazi are: - Epetra_MultiVector and Epetra_Operator (with scalar type \c double) - Thyra::MultiVectorBase and Thyra::LinearOpBase (with arbitrary scalar type). This allows %Anasazi to be used with any classes that implement the abstract interfaces provided by the Thyra package. - Tpetra::MultiVector and Tpetra::Operator (with arbitrary scalar type). - Anasazi::MultiVec and Anasazi::Operator (with arbitrary scalar type). This allows %Anasazi to be used with any classes that implement the abstract base classes Anasazi::MultiVec and Anasazi::Operator. Additional specializations of Anasazi::MultiVecTraits and Anasazi::OperatorTraits may be created by the user for any other multivector and operator class. */ /*! @defgroup anasazi_solver_framework Anasazi Eigensolver Framework %Anasazi is a framework for developing large-scale iterative eigensolvers. When developing such a framework, or even a %collection of different solvers, one will notice a large amount of overlap among different implementations. For example, two separate eigensolvers may utilize the same orthogonalization methods, whereas two different implementations of a particular eigensolver may utilize different orthogonalization routines. Dividing the different tasks associated with an iterative eigensolver into multiple routines enables increased code reuse and eases code maintenance. The question arises: how does one distill the essence of a particular eigensolver, with the end goal of separating this code from the supporting code? To illustrate this dilemma, consider the block Davidson iteration. The essence of the algorithm can be distilled as follows: a preconditioner is applied to the current residual vectors, and the resulting vectors are used to expand a subspace from which the next eigenvector approximations (and their residuals) are computed. However, a multitude of choices abound in implementing this simple iteration: the size of the computed basis, whether and how the method is restarted, the convergence criterion for the algorithm, and the use of deflation (locking) mechanisms, etc. Many of these decisions are separate from the actual iteration. Extracting the essential nature of an iteration results in a simpler piece of code to develop, debug and maintain. The %Anasazi iterative eigensolver framework encourages this by providing three distinct entities to fulfill the roles needed by an eigensolver: Anasazi::Eigensolver, Anasazi::StatusTest and Anasazi::SolverManager: - Anasazi::Eigensolver implements the features necessary to describe an eigensolver iteration. The iteration state accessors (e.g., Anasazi::BlockDavidson::getState() and Anasazi::BlockDavidson::initialize()) provide access to private member data, and the iteration occurs inside the Anasazi::Eigensolver::iterate() method. - Anasazi::StatusTest determines when an iteration is to be terminated. Inside the Anasazi::Eigensolver::iterate() method, the eigensolver queries a Anasazi::StatusTest object in order to determine when to return from the Anasazi::Eigensolver::iterate() method. - Anasazi::SolverManager provides a simplified interface to a particular eigensolver. A solver manager implements specific features that are independent of the iteration, such as locking and restarting. Different Anasazi::SolverManager classes may provide varying features and techniques, though they may encapsulate the same underlying eigensolver iteration. A Anasazi::SolverManager is typically driven by a Teuchos::ParameterList, providing a powerful eigensolver via a very simple interface. Returning to the block Davidson example, let's examine how these different pieces come into play. The Anasazi::BlockDavidson class contains both the state and mechanism of the block Davidson iteration. The state consists of the current test basis, the eigenvector estimates, the residual vectors, and other support data. The eigensolver iteration is described above, and is implemented inside the Anasazi::BlockDavidson::iterate() method. On a call to Anasazi::BlockDavidson::iterate(), the iteration persists until one of two things happens: either the basis becomes full or the Anasazi::StatusTest provided to the solver indicates that the iteration should be terminated. This is summarized in the following code snippet: \code void Anasazi::BlockDavidson::iterate() { while (statustest.checkStatus (this) != Anasazi::Passed && getCurSubspaceDim () < getMaxSubspaceDim ()) { // ... perform block Davidson iterations ... } } \endcode The Anasazi::StatusTest::checkStatus() routine takes an Anasazi::Eigensolver object as an argument. For a status test to examine the status of an arbitrary iteration, we must have some abstract interface defining the status of the iteration. This interface is defined by the Anasazi::Eigensolver abstract base class, the class from which all eigensolvers in %Anasazi derive. The following are some example of the methods provided by Anasazi::Eigensolver for use by Anasazi::StatusTest objects: \code // Get the current residual norms std::vector getResNorms (); // Get the Ritz values from the previous iteration. std::vector > getRitzValues (); // Get the current iteration count. int getNumIters () const; // and many more!!! \endcode The termination of Anasazi::Eigensolver::iterate() is partially controlled by the status test. In one example, a user wishing to limit the number of iterations might utilize Anasazi::StatusTestMaxIters. In another example, a user wishing to halt Anasazi::Eigensolver::iterate() when the residual norms satisfy a certain tolerance might utilize Anasazi::StatusTestResNorm. Arbitrary combinations of status tests can be created using a Anasazi::StatusTestCombo class, so that the stopping criterion can now be affected without modifying the iteration. Furthermore, these decisions can be made at runtime. See Anasazi::StatusTest for a list of status tests provided by Anasazi. Recalling again the block Davidson example, we know that after filling the allocated basis in the iterate() routine, the eigensolver must be restarted with a new subspace. A user wishing to perform a particular type of restarting needs access to the entire state of the eigensolver and must be able to set this state. Each of the %Anasazi eigensolvers provides getState() and initialize() methods for retrieving and setting the internal state of the eigensolver. In the case of Anasazi::BlockDavidson, this method can be used to access the current test basis, which can be used for performing a restart. The user may produce a new state for the eigensolver and then pass it to the eigensolver via the Anasazi::BlockDavidson::initialize() method. In this way, the user has great flexibility in dictating the behavior of the algorithm. However, the code for performing restarting and locking and similar features is tedious. Furthermore, much research has been conducted into robust and efficient methods for performing these operations. The Anasazi::SolverManager exists as a way to encapsulate this functionality in an accessible package, suitable for use in other codes. The goal of a solver manager is to perform all of the communication with a particular eigensolver, providing advanced functionality, on behalf of the user. Algorithmic parameters of a particular solver manager are set via a Teuchos::ParameterList. The only other input provided to the solver manager is the Anasazi::Eigenproblem to be solved. Consider the following example: \code // create an eigenproblem Anasazi::Eigenproblem prob = ... // create a parameter list for the Anasazi::BlockDavidsonSolMgr solver manager Teuchos::ParameterList pl; pl.set("Block Size",5); pl.set("Num Blocks",10); pl.set("Maximum Restarts",20); // create a Block Davidson solver manager Anasazi::BlockDavidsonSolMgr manager(prob,pl); // solve the eigenproblem Anasazi::ReturnType ret = manager.solve(); // retrieve the answer Anasazi::Eigensolution sltn = prob.getSolution(); \endcode The Anasazi::BlockDavidsonSolMgr solver manager is responsible for - creating an Anasazi::BlockDavidson eigensolver and initializing it; - creating status tests and other utility classes needed by the solver; - implementing restarting and locking mechanisms; and - putting the computed eigenpairs into the eigenproblem. The division between eigensolver and solver manager enables the following functionality in %Anasazi: - the partitioning of responsibility among the classes, resulting in simpler code and easier development, debugging, reuse and maintenance. - stratified levels of interaction: either custom, powerful low-level interaction with the eigensolver or convenient and simple interaction with a robust and flexible solver manager. - the flexibility to choose many implementation details through the choice of support classes provided to the eigensolver: - Anasazi::StatusTest - Anasazi::OutputManager - Anasazi::SortManager - Anasazi::OrthoManager */