Foundational Thyra operator/vector interfaces (Note: above graphic is not hyper-linked!)
Thyra contains abstract interfaces to linear algebra objects such as vectors and linear operators and its most fundamental interfaces are shown in the UML class diagram below. This documentation page is meant to provide a road-map to the Doxygen-generated C++ code documentation and provide convenient access to helpful examples.This main page provides the starting point for all of the documentation for the Thyra Operator/Vector Interfaces.
Foundational Thyra operator/vector interfaces (Note: above graphic is not hyper-linked!)
Thyra::VectorSpaceBase is the fundamental abstract interface for a vector space that defines the scalar product and factory functions for creating Thyra::VectorBase and Thyra::MultiVectorBase objects. Thyra::VectorBase is the fundamental abstract interface for finite-dimensional vectors. Thyra::LinearOpBase is the fundamental abstract interface for linear operators. Thyra::MultiVectorBase is the fundamental abstract interface for collections of column vectors. RTOpPack::RTOpT is the fundamental abstract interface to all diagonal vector reduction/transformation operations.
From here on out, the abstract C++ classes Thyra::VectorSpaceBase, Thyra::VectorBase, Thyra::MultiVectorBase and Thyra::LinearOpBase will be referred to as the foundational Thyra operator/vector interfaces.
The rest of the C++ classes and non-member functions described in this doxygen collection are designed to support one of a number of different use cases associated with the above foundational Thyra operator/vector interfaces.
There are primarily three different use cases related to the foundational Thyra operator/vector interfaces shown above. The first, and by far the most important, is the use of the Thyra Operator/Vector Interfaces as an Interoperability Layer for Abstract Numerical Algorithms (ANAs). This first use case is really the main reason for the creation of Thyra in the first place and is the most basic and important dependence that another package can have on Thyra. The second most important use case is the Development of Concrete Thyra Operator/Vector Subclass Implementations of vector spaces, vectors, multi-vectors and linear operators. These types of subclass implementations are also known as "adapter" subclasses if they "adapt" some pre-existing set of classes or interfaces (which is often the case). The third use case is the use of the Thyra Operator/Vector Interfaces as an API for the Development of Abstract Numerical Algorithms (ANAs). While the foundational Thyra operator/vector interface classes were not directly designed for this use case, with some minimal helper functions and classes, directly writing ANA implementations in terms of Thyra objects is quite straightforward.
Click on the links below for a discussion of each of these three use cases and a description of additional supporting code. These use cases provide the primary documentation organization for the software in this doxygen collection.
All of these interfaces are templated on a Scalar (i.e. floating-point) type and therefore almost all of Thyra supports arbitrary scalar types such as complex types (e.g. std::complex<double>), automatic differentiation types, interval types and extended precision types (i.e. mpf_class) in addition to simpler real types such as double and float. The only requirement for the Scalar data type is that it have value semantics (i.e. default constructor, copy constructor, assignment operators) and define the basic overloaded operators operator+(...), operator-(...), operator*(...) and operator/(...). The traits class Teuchos::ScalarTraits provides a means to write type independent code and all of the Thyra software uses this traits class. Any scalar type that is to be used as a Scalar must provide a specialization of this traits class (see source code for Teuchos_ScalarTraits.hpp for examples of how to do this). In addition, if MPI is to be used then specializations of the traits classes Teuchos::PrimitiveTypeTraits and Teuchos::RawMPITraits must also be provided.
The fundamental Thyra interfaces and related software are not templated on an index (i.e. ordinal) type. Instead, the type Thyra::Index is used which is just a typedef that is defined at configure time to be an integral type of sufficient size. This type must be able to hold the value of the largest dimension of a vector space that will be used by an executable. For most platforms and use cases, int is sufficient but in other cases long int may be necessary on some 64 bit platforms. Not templating on the index (ordinal) type does not result in any degradation in usability, runtime speed, or storage usage for any use case. However, certain types of subclasses of the Thyra interfaces, such as sparse matrix subclasses, may need to be templated on a local index (ordinal) type.
All of the code in the Thyra package almost exclusively uses the Teuchos smart reference counted pointer class Teuchos::RefCountPtr to handle dynamically allocated memory with object-oriented programming. Thyra also religiously uses the idioms described in this report for passing object to and from functions that involve Teuchos::RefCountPtr .
All error and general exception handling in the fundamental Thyra interfaces and related software is performed using the built-in C++ exception handling mechanisms (i.e. try, throw and catch) and all thrown exceptions should inherit from the standard base class std::exception. All exceptions in Thyra software are thrown using the macros TEST_FOR_EXCEPTION() or TEST_FOR_EXCEPT(). By consistently using these macros is is easy to set a breakpoint in a debugger just before an exception is thrown by setting a breakpoint on the function TestForException_break(). If the code is configured with the macro _DEBUG defined (i.e. CPPFLAGS="-D_DEBUG ...") then a lot of runtime validation is performed. Whenever development work is being performed this macro should always be enabled since a lot of errors will be caught that would be hard to diagnose otherwise.
Thyra::VectorSpaceBase, Thyra::VectorBase, Thyra::MultiVectorBase, and Thyra::LinearOpBase objects out of Epetra objects.
Thyra::LinearOpWithSolveBase and Thyra::LinearOpWithSolveFactoryBase in terms of Amesos_BaseSolver implementations. These adapters allow a client to take any Epetra_RowMatrix object embedded in a Thyra::EpetraLinearOp object and immediately use to to define a direct linear solver.
Thyra::LinearOpWithSolveBase and Thyra::LinearOpWithSolveFactoryBase in terms of the AztecOO class. These adapters allow a client to take any Epetra_RowMatrix object embedded in a Thyra::EpetraLinearOp object and immediately use to to define an iterative linear solver such as GMRES or CG.
1.3.9.1