Thyra Version of the Day
Loading...
Searching...
No Matches
Thyra : Interfaces and Support code for Abstract Numerical Algorithms (ANAs)

Outline

Introduction

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.

Thyra interoperability interfaces

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.

Operator/Vector Interfaces

Module: Thyra interfaces

Operator Solve Interfaces

Nonlinear Interfaces

Module: Thyra nonlinear interfaces

Thyra support software and examples

Module: Thyra support

Operator/Vector 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::VectorSpace, Thyra::Vector, and 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.

Operator Solve Support

Module: Operator/Solve ANA Support Software

This collection contains support software for the operator/solve interfaces. Examples include testing software like Thyra::LinearOpWithSolveTester and decorator subclasses like Thyra::DefaultDiagonalLinearOpWithSolve.

Nonlinear Model Evaluator Support

Module: Thyra nonlinear model-evaluator support

This includes support software for the nonlinear model evaluator interfaces. Examples include decorator subclasses like Thyra::DefaultFiniteDifferenceModelEvaluator.

Nonlinear Solvers Support

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 Thyra::LinearNonlinearSolver and Thyra::DampenedNewtonNonlinearSolver.

Thyra adapters to other packages

Module: Thyra adapters

Thyra/Epetra adapters

Module: Thyra/Epetra Operator/Vector Adapter Code

This software allows the creation/conversion of Thyra objects and Epetra objects. Examples include Thyra::EpetraLinearOp, Thyra::EpetraVector, Thyra::EpetraMultiVector, and Thyra::EpetraVectorSpace.

Thyra/Tpetra adapters

Module: Thyra/Tpetra Operator/Vector Adapter Code

This software allows the creation/conversion of Thyra objects and Tpetra objects. Examples include Thyra::TpetraLinearOp, Thyra::TpetraVector, Thyra::TpetraMultiVector, and Thyra::TpetraVectorSpace.

Thyra/EpetraExt adapters

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.

Browse all of Thyra as a single doxygen collection

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.

Some Technicalities about Thyra Software

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 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 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::Ptr, Teuchos::Array, Teuchos::ArrayRCP, Teuchos::ArrayView, and 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. 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 TEUCHOS_TEST_FOR_EXCEPTION() or TEUCHOS_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 Teuchos::TestForException_break() (e.g. by typing break Teuchos::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.

Other Trilinos Packages on which Thyra Depends

The Thyra code described here is dependent on the following Trilinos packages:

  • teuchos: This package supplies basic utility classes such as Teuchos::RCP and Teuchos::BLAS on which Thyra software depends.
  • rtop: This package supplies the basic interfaces for vector reduction/transformation operators as well as support code and a library of pre-written RTOp subclasses.

Configuration of the Thyra Package

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 make install.

Frequently Asked Questions (FAQ)

Click here for a list of frequently asked questions (FAQ) compiled for thyra.

Documents Describing or are Related to Thyra

Contributors to the Thyra Package and Related Software

The contributors to the Thyra package, or related packages, in alphabetical order, are:

Other Software Related to Thyra

Below is a partial list of software related to Thyra.