Teuchos: The Trilinos Tools Library

Version of the Day

intro

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
• Kris Kampshoff, University of Minnesota, kamp@cs.umn.edu
• Kevin Long, Sandia National Labs, krlong@sandia.gov
• Heidi Thornquist, Sandia National Labs, hkthorn@sandia.gov

startup

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
  • 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 List:
  • 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.
  
  

• Memory Management:
  • Smart pointer: Teuchos::RefCountPtr - a reference-counted pointer that is safe under multiple inheritance.
  
  

• 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
  • Test for Exception: 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.

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

---