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:

Chris Baker, Florida State University, cbaker@csit.fsu.edu
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

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.
Memory Management:
- Teuchos::Ptr: Light-weight smart pointer class for replacing the use if raw C++ pointers for pointing to a single object in funtion argument lists. This is only for non-persisting relationships.
- Teuchos::RCP: Reference-counted smart pointer class for managing dynamically allocated memory to single object that is safe under multiple inheritance. This is only for persisting relationships. See this report
- Teuchos::ArrayRCP: Reference-counted pointer for managing dynamically allocated array memory. This is a general replacement for a raw C++ pointer to handle an array. This is only for persisting relationships.
- 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-debug or --enable-teuchos-abc configure flags.
- Teuchos::ArrayView: A light-weight replacement for raw pointers for passing arrays into functions. This is only for non-persisting relationships.
Low-Level Language Support:
- Abstract factories:
  - Teuchos::AbstractFactory - defines a basic "Abstract Factory" interface that allocates objects and returns them wrapped in Teuchos::RCP 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.
Outputting support
- Teuchos::FancyOStream wraps any std::ostream object and produces nicely indented outputting. It can also add prefixes to each line of output such as the processor rank.
- Teuchos::OSTab is used in conjunction with a Teuchos::FancyOStream object to generate exception safe indentation control as well as set other information related to the line prefix.
- Teuchos::VerboseObject is a base class that objects can inherit from that makes producing coordinated informative outputting easier. This class can be inherited by any C++ subclass without requiring any function overrides but to be useful the class object must use the embedded ostream and verbosity level to print its activities.
- Teuchos::oblackholestream is a concrete subclass of std::ostream that ignores all output. This class is very useful in writing 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.
- 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.
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).
Testing Support
Teuchos contains some utilities that make it easier to write tests
See Teuchos Testing Utilities

Teuchos "Extended" Classes

Containers
- 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

Browse all of Teuchos

You can browse all of Teuchos as a single doxygen collection. Warning, this is not the recommended way to learn about Teuchos software. However, this is a good way to browse the directory structure of teuchos, to locate files, etc.