Teuchos: The Trilinos Tools Library

Version of the Day

Introduction

Teuchos provides a suite of common tools for Trilinos for developers to use. These tools include BLAS/LAPACK wrappers, smart pointers, parameter lists, XML parsers, etc.

Teuchos Contributors

The following people have contributed to the development of Teuchos:

• Roscoe Bartlett, Sandia National Labs, rabartl@sandia.gov
• Michael Heroux, Sandia National Labs, maherou@sandia.gov
• Kris Kampshoff, University of Minnesota, kamp@cs.umn.edu
• Kevin Long, Sandia National Labs, krlong@sandia.gov
• Paul Sexton, University of Illinois-Chicago, pmsext@software.sandia.gov
• Heidi Thornquist (Package Lead), Sandia National Labs, hkthorn@sandia.gov

Overview of Teuchos

Teuchos contains a number of classes. These classes have been divided between a "standard" build and an "extended" build. The "standard" build has shown to be a portable subset of the Teuchos tools and is built by default when Teuchos is enabled (--enable-teuchos). The "extended" build is also portable, but contains more special purpose tools like XML parsing and communicators (--enable-teuchos-extended).

Additionally, boundschecking for some of the container classes can be enabled through configuring Trilinos with --enable-teuchos-abc. Boundschecking incurs a significant performance penalty and so is not recommended for production builds. To enable complex arithmetic in the computational classes, Teuchos must be configured with --enable-teuchos-complex.

Teuchos "Standard" Classes

• Low-level math
  • Numerical scalar traits : Teuchos::ScalarTraits - a traits class defining basic propertys and elementary functions for various scalar data types to be used in numerical computations.

  • BLAS wrapper class: Teuchos::BLAS - A ``thin'' layer of C++ code wrapping the basic linear algebra subprograms (BLAS). This class provides a single instance interface between Teuchos and the BLAS. In this way we can easily switch BLAS interfaces and manage the C++/Fortran translation differences that exist between different computer systems. This class also provides a very convenient way to templatize the BLAS.

  • LAPACK wrapper class: Teuchos::LAPACK - A ``thin'' layer of C++ code wrapping LAPACK. Like Teuchos::BLAS, it provides nice C++ access to LAPACK.

  • Serial Dense Matrix class: Teuchos::SerialDenseMatrix - A templated, dense rectangular matrix class that provides basic operations like addition, multiplication, scaling, logical comparison, norms, etc. This class also provides support for a dense matrix that needs to be replicated across processors in a parallel application. Teuchos::SerialDenseVector inherits from Teuchos::SerialDenseMatrix, providing some additional methods that are useful to dense vectors. Boundschecking can be turned on at compile time with the --enable-teuchos-abc configure flag.

• Parameter Options:
  • Parameter Entry: Teuchos::ParameterEntry - A structure that holds a Teuchos::any object as the value and information on the status of the parameter. The type of parameter is chosen through the templated Set/Get methods. Teuchos::ParameterEntry object is held as the "value" in the Teuchos::ParameterList map.

  • Parameter List: Teuchos::ParameterList - A templated parameter list which holds a map of <key,value> pairs, where the "value" is a Teuchos::ParameterEntry object and the "key" is a string object. The type of parameter is chosen through the templated Set/Get methods, which allows it to be any standard type (float, double, int, ...) or another parameter list.

  • Commandline arguments: Teuchos::CommandLineProcessor - processes commandline arguments from (argc,argv[]) in a validated manner and automatically generates a documented --help option.

• Low-Level Language Support:
  • Smart pointer: Teuchos::RefCountPtr - a reference-counted pointer for managing dynamically allocated memory that is safe under multiple inheritance.

  • Abstract factories:
    • Teuchos::AbstractFactory - defines a basic "Abstract Factory" interface that allocates objects and returns them wrapped in Teuchos::RefCountPtr objects.
    • Teuchos::AbstractFactoryStd - defines a general concrete implementation of Teuchos::AbstractFactory that allows creating quick concrete subclass implementations for concrete types.

  • Dynamic casting: Teuchos::dyn_cast() - a wrapper for dynamic_cast<> that throws std::bad_cast exceptions with very detailed error messages on what types are involved.

  • Array argument call generation : arrayArg() - a set of overloaded templated functions for generating inline array arguments for function calls.

  • Teuchos::getConst() is a silly little templated function that returns a constant reference given any constant object. This function allows a piece of code to access the const version of a member function given a non-const reference to an object.

  • Teuchos::oblackholestream is a concrete subclass of std::ostream that ignores all output. This class is very useful in writting SPMD parallel programs and controlling which processor(s) produce output. Generally only the the root process uses a real std::ostream object while all of the slave processors use a Teuchos::oblackholestream for console output.

• Performance Monitoring
  • Timing class: Teuchos::TimeMonitor - Provides timing functions for the purposes of performance analysis.

  • Floating point operation class: Teuchos::Flops - Provides floating point operations (FLOPS) counting and reporting functions for the purposes of performance analysis. All Teuchos computational classes accumulate FLOP counts associated with the this object of the computations.

• Exception Handling
  • Testing for Exceptions: The TEST_FOR_EXCEPTION() macro accepts a logical test, an exception handler, and a message. It then throws an "intelligent" exception informing the user of the file, line, and message where the exception was thrown. The macro TEST_FOR_EXCEPT() is a shorter macro that just accepts a logic test and is therefore easier to write. Please use TEST_FOR_EXCEPT(!test) as an alternative to assert(test).

• Debugging Support
  • Pretty Printing Objects: The abstract base class Teuchos::Describable defines an interface that subclasses can override that allows the creation of formated output of an object's state complete with indentation control. This class has default definitions for all of its virtual member functions and therefore can be inherited by existing C++ classes without requiring any additional implementation support to get started.

Teuchos "Extended" Classes

• Containers
  • Teuchos::Array is a templated array class similar to the STL vector, but with optional boundschecking. Boundschecking is useful for debugging, and can be turned on at compile time with the --enable-teuchos-abc configure flag.

  • Teuchos::Hashtable is a templated map with constant-time lookup.

  • Teuchos::HashSet is a templated set with constant-time lookup.

  
  

• XML
  • Teuchos::XMLObject is an object representation of a subset of XML data. Supported XML features are tags, attributes, and character content.

  • Teuchos::FileInputSource can read XML from a file and produce a Teuchos::XMLObject

  • Teuchos::StringInputSource can read XML from a character string and produce a Teuchos::XMLObject

  
  

• MPI
  • Teuchos::MPISession has methods to initialize, finalize, and query the global MPI environment.

  • Teuchos::MPIComm represents an MPI communicator

  • Teuchos::MPIContainerComm has methods to communicate Teuchos::Array objects

---