The Thyra package contains a set of interfaces and supporting code that defines basic interoperability mechanisms between different types of numerical software. The foundation of all the interfaces related to abstract numerical algorithms (ANAs) are the mathematical concepts of vectors, vector spaces, and linear operators. All other ANA interfaces and support software are built on these fundamental operator/vector interfaces.
This main page provides the starting point for all of the documentation for Thyra interfaces and software. This documentation is generated using Doxygen.
The documentation for Thyra is broken up into a number of different doxygen collections as described in the next section.
The Doxygen-generated documentation is broken up into a number of different doxygen collections in an attempt to make each individual collection more manageable to browse and comprehend. To access each separate collection, just click on the [doxygen collection] next to each header below.
The thrya package is broadly divided into interoperability interfaces and support software and the directory structure and the doxygen documentation is also divided in this way. This organization mirrors the directory structure of thyra.
Module: Thyra interfaces
All of the software in the
src/interfaces directory define fundamental interoperability interfaces needed to glue code together. This is the most critical aspect of Thyra. In addition, interfaces are also partitioned between fundamental interfaces and extended interfaces.
Module: Thyra interfaces
This minimal set of basic operator/vector interfaces described here forms the foundation for all of the interoperability interfaces related to Abstract Numerical Algorithms (ANAs) provided in the Thyra package.
The fundamental interface classes shown in the above UML class diagram are described below:
Thyra::VectorSpaceBase is the fundamental abstract interface for a vector space that defines the scalar product and factory functions for creating
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.
These interface classes rely on a few basic types and basic exception classes.
One important paper describing the RTOp approach, which provides the foundation for
RTOpPack::RTOpT, can be found in this paper. Note that
RTOpPack::RTOpT is a refinement of the C and C++ RTOp interfaces described in the aforementioned paper.
These are some interfaces based on the above Fundamental ANA Operator/Vector Interfaces and provide other pieces of functionality and define new types of interoperability. For example, this is where interfaces to various types of composite subclasses exist for product, or block, vector spaces (
Thyra::ProductVectorSpaceBase), vectors (
Thyra::ProductVectorBase), and multi-vectors (
Thyra::ProductMultiVectorBase). Various interfaces to decorator and composite linear operators are also contained here and include, for example,
Interfaces to product vector spaces, vectors and multi-vectors
Composite and other linear operator base classes:
Note that below, the term "implicit" denotes the fact that the operators are not actually formed. For example, the sum of the implicitly added linear operators is never calculated, but the action of these operators on a vector is computed correctly as the sum of the action of each individual operator on that vector.
Thyra::ZeroLinearOpBase defines the interface for a zero linear operator.
Thyra::IdentityLinearOpBase defines the interface for an identity linear operator .
Thyra::AddedLinearOpBase defines the interface for implicitly added linear operators.
Thyra::MultipliedLinearOpBase defines the interface for implicitly added linear operators.
Thyra::DiagonalLinearOpBase defines the interface for a basic diagonal linear operator.
Thyra::BlockedLinearOpBase is a base class for a logically blocked
Thyra::PhysicallyBlockedLinearOpBase is a base class for a physically blocked
LinearOpBase object where the blocks can be set externally.
MPI-Specific ANA-based interfaces
Note: These interfaces are not strictly related to ANAs and therefore may not be appropriate to be placed in this collection. However, they are derived for the ANA interfaces and therefore, very weakly, belong in this collection of code.
Thyra::MpiVectorSpaceBase defines an interface for getting information about the partitioning of elements to processors in an SPMD program.
Thyra::MultiVectorFileIOBase is an interface for strategy objects that can read and write (multi)vectors to and from files in a very abstract way.
Thyra::MultiVectorRandomizerBase is an interface for strategy objects that can produce random vectors and multi-vectors.
These are interfaces that provide a high-level interface to preconditioners, linear solvers (
Thyra::LinearOpWithSolveBase), and factories for these (i.e.
Thyra::PreconditionerFactoryBase). Below we use the term "forward" to denote the original operator to which a solver is associated to distinguish it from the "inverse" operator.
Thyra::PreconditionerBase defines an interface to left, right, split left/right, and otherwise general preconditioners.
Thyra::LinearOpWithSolveBase defines a simple interface for performing the inverse linear operator application.
Included here is a variety of extended interfaces that build on the fundamental operator/solve interfaces.
Composite linear operator base classes
Thyra::BlockedLinearOpWithSolveBase is a base class for implicitly defined
Thyra::LinearOpWithSolveBase objects accessible as one or more
Thyra::PhysicallyBlockedLinearOpWithSolveBase is a base class for composite
Thyra::BlockedLinearOpBase objects that are built for constituent
Module: Thyra nonlinear interfaces
Module: Thyra nonlinear model interfaces
Thyra::ModelEvaluatorBase defines basic types used by the model-evaluator.
Thyra::ModelEvaluator defines a very general interface for representing a number of different types of nonlinear problems.
Contained here are interfaces for nonlinear equation solvers.
Module: Thyra support
Module: Thyra operator/vector support
Described here is a fairly large collection of ANA or client support and adapter support software based on the operator/vector interfaces. For example, you will find things such as unit testing classes (e.g.
Thyra::LinearOpTester), and concrete product spaces/vectors/multi-vectors (e.g.
Thyra::DefaultProductVectorSpace). Also included is adapter support and concrete implementations for serial and SPMD (Single Program Multiple Data) space/vector/multi-vector implementations (e.g.
Thyra::DefaultSpmdVectorSpace). Another category of software is efficient Java-like handle/wrapper classes (e.g.
Thyra::LinearOperator) that defines a convenient API for the development of ANAs using MATLAB-like operator overloading. Some examples are also provided, including several for the Conjugate Gradient method and the Power Method. This collection of software is really too vast to give a full sense of what it contains in this short description.
This collection contains support software for the operator/solve interfaces. Examples include testing software like
Thyra::LinearOpWithSolveTester and decorator subclasses like
This includes support software for the nonlinear model evaluator interfaces. Examples include
decorator subclasses like
Module: Thyra nonlinear solver support
Contained here is support software for the nonlinear solver interfaces and some simple concrete implementations. Simple concrete nonlinear equation solver implementations include examples
Module: Thyra adapters
This software allows the creation/conversion of Thyra objects and Epetra objects. Examples include
Module: Thyra/EpetraExt Adapter Code
Included here are various adapters between Epetra and EpetraExt based code and Thyra interfaces. For example, one will find the
Thyra::EpetraModelEvaluator class in this collection of code.
You can browse all of Thyra as a single doxygen collection. Warning: This is not the recommended way to learn about Thyra software. However, this is a good way to browse the directory structure of thyra, to locate files, etc.
A few things about the software in the Thyra package are worth mentioning:
Scalar and Ordinal (Ordinal) data types
All of the 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 SPMD distributed-memory computing is to be used then specializations of the traits class
Teuchos::SerializationTraits must also be provided.
The Thyra interfaces and related software are not templated on an index (i.e. ordinal) type. Instead, the type
Thyra::Ordinal is used which is just a typedef that is defined at configure time to be an integer 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, for example on some 64 bit platforms,
long int may be necessary. 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.
Dynamic memory management
All of the code in the Thyra and related packages almost exclusively use the
Teuchos smart reference counted pointer class
Teuchos::RCP to handle dynamically allocated memory with object-oriented programming. Other types used include
Teuchos::Tuple. Thyra rigorously uses idioms for these classes partially introduced in RCP Beginner's Guide, described in great detail in Teuchos C++ Memory Management Classes, and summarized in Thyra Coding and Documentation Guidelines.
Error (exception) handling
All error and general exception handling in the 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 it is easy to set a breakpoint in a debugger just before an exception is thrown by setting a breakpoint on the function
TestForException_break() (e.g. by typing
break TestForException_break in gdb). If Trilinos is configured with
Trilinos_ENABLE_DEBUG=ON then a lot of runtime error checking is performed in Thyra support software, as well as in many other software packages. Whenever development work is being performed this option should always be enabled since a lot of errors will be caught that would be hard to diagnose otherwise. Significant effort has gone into developing this error checking code and in the information that is embedded in the exception objects (all derived from
std::exception) that are thrown when errors are detected. More detail about how to do debugging with Thyra related to memory management is described in Teuchos C++ Memory Management Classes.
The Thyra code described here is dependent on the following Trilinos packages:
Teuchos::BLASon which Thyra software depends.
The Thyra package is configured using CMake and responds to a number of options that affect the code that is built and what code is installed.
Some of the more important configuration options are:
Trilinos_ENABLE_Thyra=ON: Causes the Thyra package and all of its dependent packages to be enabled and built. Without this option, there will be no Thyra header files or libraries included in the installation of Trilinos, i.e., when one runs
Click here for a list of frequently asked questions (FAQ) compiled for thyra.
This paper describes the basic principles that go into the design of the Thyra Operator/Vector interface layer (and therefore also for the rest of Thyra).
This paper describes the basics of
Teuchos::RCP and outlines a convention for passing objects to and from functions that all of the code in Thyra adheres to.
This document provides a complete discussion of the motivation, the design of, the idioms surrounding, and other important idioms related to the full set of Teuchos memory management classes that Thyra is based on.
This paper describes the need for, and the basic design of,
RTOpPack::RTOpT. The concrete implementation described in this paper used C structs while the current
RTOpPack::RTOpT is a fully templated C++ class implementation.
This short note describes a simple convention for writing function prototypes for linear algebra operations. This convention is used in this set of functions, for instance.
This document describes the coding and documentation guidelines used in the creation of Thyra.
The contributors to the Thyra package, or related packages, in alphabetical order, are:
Below is a partial list of software related to Thyra.
Stratimikos: Unified Wrappers for Thyra Linear Solver and Preconditioner Adapters: Stratimikos contains neatly packaged access to all of the Thyra linear solver and preconditioner wrappers. Currently, these allow the creation of linear solvers for nearly any
Epetra_RowMatrix object. However, the Belos implementation allows for the arbitrary implemention of the linear operators and vector spaces.
MOOCHO/Thyra: Adapters that take Thyra Nonlinear Model Evaluator objects and express them as simulation-constrained optimization problems: These adapters allow an application to access the nonlinear, simulation-constrained optimiztion algorithms in MOOCHO through the Thyra::ModelEvaluator interface.