Thyra : Interfaces and Support code for the Interoperability of Abstract Numerical Algorithms

Version 1.0 in Trilinos 6.0

Outline

• Introduction
• Thyra Software Package Documentation Collections
• Other Trilinos Packages on which Thyra Depends
• Configuration of the Thyra Package
• Building and Linking Against Thyra in External Projects
• 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 of these interfaces are the mathematical concepts of vectors, vector spaces, and linear operators. All other interfaces and support software are built on these basic 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.

Below are links to the different Doxygen documentation collections for the different aspects of Thyra:

• Miscellaneous Utilities: Some utility code that does not belong in any one of the below collections of code.

• Abstract Numerical Algorithm (ANA) Software: Interfaces and support code for developing and using ANAs.
  • RTOp: Vector Reduction/Transformation Operators: Documents the basic RTOp interfaces and support software and catalogs a library of pre-created RTOp subclasses.

  • Operator/Vector Interfaces and Support Software: Contains the most fundamental Thyra operator/vector interfaces as well as standard adapter code and ANA development utilities.

• Other Thyra software
  • Single program multiple data (SPMD) vector and matrix creational, loading and accessing interfaces: These are abstract interfaces that application code can use to fill vectors and sparse matrices on distributed-memory parallel computers (as well as on SMP computers of course) [Does not exist yet].

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::RefCountPtr and Teuchos::BLAS that Thyra software is dependent on.

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. using 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 and some of these options are:

• --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 packages that one must enable it (see the --enable-thyra and other configure options described above) before installation.

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
#

# For platforms where perl and GNUMake are used
#COMPILE_FLAGS = $(shell perl $(TRILINOS_INSTALL_DIR)/include/strip_dup_incl_paths.pl \
#	$(THYRA_CXXFLAGS) $(THYRA_DEFS) $(THYRA_CPPFLAGS) $(THYRA_INCLUDES))
# For platforms where perl and/or GNUMake are not available
COMPILE_FLAGS = $(THYRA_CXXFLAGS) $(THYRA_DEFS) $(THYRA_CPPFLAGS) $(THYRA_INCLUDES)
# For platforms where perl and GNUMake are used
#LINK_FLAGS = $(shell perl $(TRILINOS_INSTALL_DIR)/include/strip_dup_libs.pl $(THYRA_LIBS))
# For platforms where perl and/or GNUMake are not available
LINK_FLAGS = $(THYRA_LIBS)

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

sillyCgSolve_serial.exe : sillyCgSolve_serial.o
	$(THYRA_CXXLD) $(THYRA_CXXFLAGS) sillyCgSolve_serial.o -o sillyCgSolve_serial.exe $(LINK_FLAGS)

sillyCgSolve_serial.o : sillyCgSolve_serial.cpp
	$(THYRA_CXX) $(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.

Documents Describing or are Related to Thyra

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

  This paper describes the basics of Teuchos::RefCountPtr and outlines a convention for passing objects to and from functions that all of the code in Thyra adheres to.

• Vector Reduction/Transformation Operators

  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.

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): Thyra lead developer
• Paul Boggs (ptboggs@sandia.gov) : Split/O3D lead developer, Thyra developer
• Todd Coffey (tscoffe@sandia.gov) : Rythmos lead developer, Thyra developer
• Michael Heroux (maherou@sandia.gov): Trilinos leader
• Rob Hoekstra (rjhoeks@sandia.gov) : EpetraExt lead developer
• Victoria Howle (vehowle@sandia.gov) : Meros lead developer, Thyra developer
• Kevin Long (krlong@sandia.gov) : Sundance lead developer, Thyra developer
• Roger Pawlowski (rppawlo@sandia.gov) : NOX lead developer
• Heidi Thornquist (hkthorn@sandia.gov): Belos lead developer, Thyra developer
• Allan Williams (william@sandia.gov) : FEI lead developer, Thyra developer

Other Software Related to Thyra

Below is a partial list of software related to Thyra.

• ANA Operator/Vector Adapters for Epetra: This software allows the creation of Thyra::VectorSpaceBase, Thyra::VectorBase, Thyra::MultiVectorBase, and Thyra::LinearOpBase objects out of Epetra objects.

• ANA Linear Solver Adapters for Amesos: This software defines the implementation of the extended interfaces 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.

• ANA Linear Solver Adapters for AztecOO: This software defines the implementation of the extended interfaces 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.

---