Thyra : Interfaces and Support code for Abstract Numerical Algorithms (ANAs)

Version of the Day

Outline

• Introduction
• Thyra Software Package Documentation Collections
  • Thyra interoperability interfaces
    • Operator/Vector Interfaces
      • Fundamental ANA Operator/Vector Interfaces
      • Extended ANA Operator/Vector Interfaces
    • Operator Solve Interfaces
      • Fundamental ANA Operator Solve Interfaces
      • Extended ANA Operator Solve Interfaces
    • Nonlinear Interfaces
      • Fundamental ANA Model Evaluator Interfaces
      • Fundamental ANA Nonlinear Solver Interfaces
  • Thyra support software and examples
    • Operator/Vector Support
    • Operator Solve Support
    • Nonlinear Model Evaluator Support
    • Nonlinear Solvers Support
  • Thyra adapters to other packages
    • Epetra/Thyra adpaters
    • EpetraExt/Thyra adpaters
  • Browse all of Thyra as a single doxygen collection
• Some Technicalities about Thyra Interfaces and Supporting Software
• Other Trilinos Packages on which Thyra Depends
• Configuration of the Thyra Package
• Building and Linking Against %Thyra in External Projects
• Frequently Asked Questions (FAQ)
• Documents Describing or are Related to Thyra
• Contributors to the Thyra Package and Related Software
• Other Software Related to Thyra

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 Software Package Documentation Collections

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. Below are links to the different Doxygen documentation collections for the different aspects of Thyra. This organization also mirrors the directory structure of thyra.

Thyra interoperability interfaces

• Operator/Vector Interfaces
  • Fundamental ANA Operator/Vector Interfaces [doxygen collection]
    

    These are minimal stripped-down abstract interface classes for basic finite-dimensional vectors, vector spaces and linear operators. These interfaces form the foundation for all other ANA-based interfaces. Primary interfaces include Thyra::VectorSpaceBase, Thyra::VectorBase, Thyra::MultiVectorBase, and Thyra::LinearOpBase.

  • Extended ANA Operator/Vector Interfaces [doxygen collection]

    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, Thyra::ScaledAdjointLinearOpBase.

• Operator Solve Interfaces
  • Fundamental ANA Operator Solve Interfaces [doxygen collection]
    
    

    These are interfaces that provide a high-level interface to preconditioners, linear solvers (Thyra::LinearOpWithSolveBase), and factories for these (i.e. Thyra::LinearOpWithSolveFactoryBase and Thyra::PreconditionerFactoryBase).

  • Extended ANA Operator Solve Interfaces [doxygen collection]

    Included here is a variety of extended interfaces that build on the fundamental operator/solve interfaces. Examples include Thyra::BlockedLinearOpWithSolveBase. and Thyra::PhysicallyBlockedLinearOpWithSolveBase.

• Nonlinear Interfaces
  • Fundamental ANA Model Evaluator Interfaces [doxygen collection]
    

    Contained here are interfaces for nonlinear models such as Thyra::ModelEvaluator.

  • Fundamental ANA Nonlinear Solver Interfaces [doxygen collection]

    Contained here are interfaces for nonlinear equation solvers.

    Warning! These interfaces are highly experimental and are likely to undergo dramatic changes before they stabilize.

Thyra support software and examples

• Operator/Vector Support [doxygen collection]

  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 [doxygen collection]

  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 [doxygen collection]

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

• Nonlinear Solvers Support [doxygen collection]

  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

• Epetra/Thyra adapters [doxygen collection]

  This software allows the creation of Thyra::VectorSpaceBase, Thyra::VectorBase, Thyra::MultiVectorBase, and Thyra::LinearOpBase objects out of Epetra objects.

• EpetraExt/Thyra adapters [doxygen collection]

  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 Interfaces and Supporting Software

A few things about the software in the Thyra package are worth mentioning:

• Scalar and Index (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::Index 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. Thyra also rigorously uses the idioms described in this report for passing object to and from functions that involve Teuchos::RCP.

• 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 TEST_FOR_EXCEPTION() or 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 --enable-teuchos-debug 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.

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's configure script (which should be called from the base Trilinos-level configure script) 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:

• --enable-thyra: 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.
• --enable-export-makefiles: Causes the installation of the Thyra package (an other Trilinos packages) to have the makefile fragments Makefile.export.thyra and Makefile.export.thyra.macros installed in the installation directory $TRILINOS_INSTALL_DIR/include for use by external makefiles (see below).

See the output from ./configure --help (where ./ is the base source directory for the thyra package) for a complete listing of all of the configure options that Thyra responds to.

The Thyra package is also affected by configure options passed to other packages; some of these options are:

• --enable-teuchos-debug: Causes a great deal of return error checking code to be added to the Thyra support software.
• --enable-teuchos-complex: Causes the std::complex<> scalar type to be used in templated examples and tests.
• --enable-teuchos-gmp: Causes the GNU MP extended-precision mpf_class scalar type to be used in templated examples and tests.

Note that the above options will not be listed by Trilinos/packages/thyra/configure --help but instead are listed by Trilinos/packages/teuchos/configure --help.

Building and Linking Against %Thyra in External Projects

It is recommended that developers external to Trilinos install Thyra with the rest of Trilinos and then compile and link against the installed headers and libraries (see the Trilinos Users Guide for a discussion of installing Trilinos). Remember that in order to install the contents of the thyra package, one must enable it (see the --enable-thyra and other configure options described above) before installation.

When make install is run, Thyra will be installed with the rest of Trilinos in the directory specified by the configure option --prefix=$TRILINOS_INSTALL_DIR. It is important that a client's external makefile system be consistent with the environment used to build Thyra. To do this, if the option --enable-export-makefiles was enabled at configure time, then a set of makefile fragments is installed in the directory

Once Thyra software is installed in the location specified by the configure option --prefix=$TRILINOS_INSTALL_DIR with the rest of Trilinos (where $TRILINOS_INSTALL_DIR is the path of the directory that you specify where Trilinos will be installed with make install), it is important that a client's external makefile system be consistent with the environment used to build Thyra. To do this, if the option --enable-export-makefiles was enabled at configure time, then a set of makefile fragments is installed in the directory

  $TRILINOS_INSTALL_DIR/include/

The installed makefile fragment files Makefile.export.thyra and Makefile.export.thyra.macros can then be included in an external makefile to give compiler options, include paths, libraries etc.

An example external makefile

When Thyra is installed with Trilinos, the directory

  $TRILINOS_INSTALL_DIR/example/thyra/

is created which contains an example of an external project that uses Thyra. The example makefile

  $TRILINOS_INSTALL_DIR/example/thyra/Makefile

that builds an external version the sillyCgSolve_serial.exe program is shown below:

##
## Example external makefile that shows how to compile and
## link against an installed version of Thyra (part of Trilinos)
##

# Points to where Trilinos is installed
TRILINOS_INSTALL_DIR = ../..

# Include the makefile fragment that specifies the compile/link commands 
include $(TRILINOS_INSTALL_DIR)/include/Makefile.export.thyra.macros
# Include the makefile fragement that defines the include paths and libraries
include $(TRILINOS_INSTALL_DIR)/include/Makefile.export.thyra

#
# Get the compile and link flags
#

LOCAL_CXX = $(THYRA_CXX)
LOCAL_CXXLD = $(THYRA_CXXLD)
LOCAL_CXXFLAGS = $(THYRA_CXXFLAGS)

_LOCAL_COMPILE_FLAGS = $(THYRA_CXXFLAGS) $(THYRA_DEFS) $(THYRA_CPPFLAGS) -I$(TRILINOS_INSTALL_DIR)/include
_LOCAL_LINK_FLAGS = $(THYRA_LIBS)
# For platforms where perl and GNUMake are used
LOCAL_COMPILE_FLAGS = $(shell perl $(TRILINOS_INSTALL_DIR)/include/strip_dup_incl_paths.pl $(_LOCAL_COMPILE_FLAGS))
LOCAL_LINK_FLAGS = $(shell perl $(TRILINOS_INSTALL_DIR)/include/strip_dup_libs.pl $(_LOCAL_LINK_FLAGS))
# For platforms where perl and/or GNUMake are not available
#LOCAL_COMPILE_FLAGS = $(_LOCAL_COMPILE_FLAGS)
#LOCAL_LINK_FLAGS = $(_LOCAL_LINK_FLAGS)

#
# Define the compile and link targets that use the included macros
#

sillyCgSolve_serial.exe : sillyCgSolve_serial.o
	$(LOCAL_CXXLD) $(LOCAL_CXXFLAGS) sillyCgSolve_serial.o -o sillyCgSolve_serial.exe $(LOCAL_LINK_FLAGS)

sillyCgSolve_serial.o : sillyCgSolve_serial.cpp
	$(LOCAL_CXX) $(LOCAL_COMPILE_FLAGS) -c sillyCgSolve_serial.cpp

clean:
	rm -f *.o *.exe *~

By using the macros starting with THYRA_ one is guaranteed that the same compiler with the same options are used to build the client's code that were used to build Trilinos. Of particular importance are THYRA_CXX, THYRA_DEFS, THYRA_CPPFLAGS, and THYRA_CXXLD since these ensure that the same C++ compiler and the same -D macro definitions are used.

Frequently Asked Questions (FAQ)

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

Documents Describing or are Related to Thyra

• A Overview of Thyra Operator/Vector interfaces [PDF]

  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).

• Teuchos::RCP Beginner's Guide : An Introduction to the Trilinos Smart Reference-Counted Pointer Class for (Almost) Automatic Dynamic Memory Management in C++ [PDF]

  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.

• Vector Reduction/Transformation Operators [PDF]

  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.

• A Simple Convention for the Specification of Linear Algebra Function Prototypes in C++ [PDF]

  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.

• A Thyra Coding and Documentation Guidelines (TCDG) [PDF]

  This document describes the coding and documentation guidelines used in the creation of Thyra.

Contributors to the Thyra Package and Related Software

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

• Roscoe Bartlett (rabartl@sandia.gov) [website]: Thyra lead developer, MOOCHO lead developer
• Todd Coffey (tscoffe@sandia.gov) : Rythmos lead developer
• Michael Heroux (maherou@sandia.gov): Trilinos lead, Epetra and AztecOO lead developer
• Kevin Long (krlong@sandia.gov) : Sundance lead developer
• Roger Pawlowski (rppawlo@sandia.gov) : NOX lead developer
• Eric Phipps (etphipp@sandia.gov) : LOCA lead developer
• Allan Williams (william@sandia.gov) : FEI lead developer

Other Software Related to Thyra

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.

---