Thyracontains 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::VectorSpaceBaseis the fundamental abstract interface for a vector space that defines the scalar product and factory functions for creating
Thyra::VectorBaseis the fundamental abstract interface for finite-dimensional vectors.
Thyra::LinearOpBaseis the fundamental abstract interface for linear operators.
Thyra::MultiVectorBaseis the fundamental abstract interface for collections of column vectors.
RTOpPack::RTOpTis the fundamental abstract interface to all diagonal vector reduction/transformation operations.
From here on out, the abstract C++ classes
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
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/(...). 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::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
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.
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_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::LinearOpBaseobjects out of Epetra objects.
Thyra::LinearOpWithSolveFactoryBasein terms of
Amesos_BaseSolverimplementations. These adapters allow a client to take any
Epetra_RowMatrixobject embedded in a
Thyra::EpetraLinearOpobject and immediately use to to define a direct linear solver.
Thyra::LinearOpWithSolveFactoryBasein terms of the
AztecOOclass. These adapters allow a client to take any
Epetra_RowMatrixobject embedded in a
Thyra::EpetraLinearOpobject and immediately use to to define an iterative linear solver such as GMRES or CG.