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

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

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

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

---