Teuchos - Trilinos Tools Package Version of the Day
Teuchos provides a suite of common tools for many Trilinos packages. These tools include memory management classes such as "smart" pointers and arrays, "parameter lists" for communicating hierarchical lists of parameters between library or application layers, templated wrappers for the BLAS and LAPACK, XML parsers, and other utilities. They provide a unified "look and feel" across Trilinos packages, and help avoid common programming mistakes.
The following people have contributed to the development of Teuchos:
Teuchos has several different build options which change its behavior. You must set these options before building Trilinos, when configuring the build using CMake.
Bounds checking: You may enable bounds checking and other safety checks for some of the memory management and container classes by setting the
Teuchos_ENABLE_DEBUG:BOOL=ON CMake option. Bounds checking is off by default. It incurs a significant performance penalty and so is not recommended for production builds.
Teuchos contains several different types of software. These different collections are organized into different subpackages.
The Teuchos Core subpackage (
Trilinos_ENABLE_TeuchosCore:BOOL=ON) contains basic, general-purpose utilities.
For a detailed description of the Teuchos memory management classes, see the report Teuchos C++ Memory Management Classes, Idioms, and Related Topics: The Complete Reference. An abbreviated table of contents can be found in the Preface of the document.
The classes are:
Teuchos::Ptr: Light-weight smart pointer class for replacing the use of 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 a single object. Teuchos::RCP is safe under multiple inheritance. This is only for persisting relationships. Please refer to the Teuchos::RCP Beginner's Guide.
Teuchos::ArrayRCP: Reference-counted smart pointer class for managing dynamically allocated arrays. This is a general replacement for a raw C++ pointer to handle an array. This is only for persisting relationships.
Teuchos::ArrayView: Light-weight replacement for raw pointers for passing arrays into functions. This is only for non-persisting relationships.
Teuchos::Array: Templated array class idential to the STL vector, but with optional very strong debug-mode runtime checking and full integration with the other array types here.
Teuchos::Tuple: Compile-time sized array class.
Teuchos::ConstNonconstObjectContainer: A simple wrapper class for implementing the "runtime protection of const" idiom.
All the Teuchos memory management classes are configured by default to be as efficient as possible. When building Trilinos, you may set configure options to enable various run-time correctness and safety checks. These options are OFF by default, for maximum performance.
You may turn on run-time debug checking in the above classes by setting the
-D Teuchos_ENABLE_DEBUG:BOOL=ON CMake option at configure time. You may also turn on strong run-time checking of reference counting, including
by setting the
-D Teuchos_ENABLE_DEBUG_RCP_NODE_TRACING:BOOL=ON CMake option. In order to get the strongest debug-mode run-time checking, you must also enable support for Boost by setting the
-D Teuchos_ENABLE_BOOST=ON and building Trilinos against an installation of Boost.
Low-Level Language Support:
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.
Teuchos::getConst() is a simple templated function that returns a constant reference, given a nonconst reference. 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::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::Describable defines an interface that objects may implement in order to make them self-descriptive. It 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, but to be useful, subclasses should override at least the description() method.
Teuchos::VerboseObject is an interface that objects may implement in order to let them describe what they are doing as they are doing it, with a user-specified verbosity level. Any C++ class may inherit from this without requiring any function overrides, but to be useful the class object must use the embedded output stream and verbosity level to print its activities.
Teuchos::oblackholestream is a concrete subclass of
std::ostream that ignores all output. (Output "disappears" into a "black hole.") This class is very useful in writing SPMD parallel programs and controlling which process(es) produce output. Generally only the the root process uses a real
std::ostream object while the other processes use a
Teuchos::oblackholestream for console output.
Testing for Exceptions: The TEUCHOS_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 TEUCHOS_TEST_FOR_EXCEPT() is a shorter macro that just accepts a logic test and is therefore easier to write. Please use TEUCHOS_TEST_FOR_EXCEPT(!test) as a safer, more informative alternative to assert(test).
Stack Tracing: When a debug build is enabled (CMAKE_BUILD_TYPE=DEBUG OR Trilinos_ENABLE_DEBUG=ON) and when using GCC and when enabling BinUtils (TPL_ENABLE_BinUtils=ON) then the TEUCHOS_TEST_FOR_EXCEPTION() family of macros will take snapshopts of the stacktrace when exceptions are thrown. These stacktraces can be printed out after an exception is thrown using the funciton Teuchos::get_stored_stacktrace(). The standard catch macro TEUCHOS_STANDARD_CATCH_STATEMENTS() automatically invokes this function so all main() programs written using this macro will automatically print out stack trace information when uncaught exceptions are encountered. A program can also cause strack tracing info to be printed when an segfault occurs by calling Teuchos::print_stack_on_segfault() before main() runs. More fine tuning of stacktracing can be controlled at configure time using the CMake options Teuchos_ENABLE_STACKTRACE and Teuchos_ENABLE_DEFAULT_STACKTRACE. When Teuchos_ENABLE_STACKTRACE=ON, then stracktracing of exceptions can be turned on and off at runtime using the function Teuchos::TestForException_setEnableStacktrace(). The configure varible Teuchos_ENABLE_DEFAULT_STACKTRACE determines if stack tracing is on or off by defualt at runtime.
NOTE: Stacktracing is always off by default in any build type except CMAKE_BUILD_TYPE=DEBUG and/or Trilinos_ENABLE_DEBUG=ON. Therefore, by default an optimized build of the code will never have stack tracking enabled and will suffer no performance penalty due to stack tracing. It is just debug builds that it is enabled for (and then only by default; it can be disabled even for a debug build).
NOTE: Stacktracing is only enabled when the using GCC and when the binutils libraries are available (see teuchos/CMakeLists.txt and cmake configure output for details).
WARNING: Printing stacktraces can be very expensive if your program throws a lot of exceptions. Therefore, the testing infrastructure for Trilinos with the checkin-test.py script turns off stack tracing by default by configuring with Teuchos_ENABLE_DEFAULT_STACKTRACE=OFF.
Testing Unit Support
Numerical scalar traits : Teuchos::ScalarTraits - a traits class defining basic properties and elementary functions for various scalar data types to be used in numerical computations.
The Teuchos ParameterList subpackage (Trilinos_ENABLE_TeuchosParameterList=ON) contains the Teuchos::ParameterList class and related utilities. The Teuchos::ParameterList class is a serializable hierarchical object database. Many Trilinos packages let users specify run-time options and flags as a Teuchos::ParameterList. They also use it internally to pass information between different software layers.
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. The type of parameter is chosen through the templated set/get methods, which allows it to have any type. This includes standard types such as float, double, or int, another parameter list, or any desired type.
Command-line arguments: Teuchos::CommandLineProcessor - processes command-line arguments from (argc,argv) in a validated manner and automatically generates a documented "--help" command-line option.
Teuchos::XMLObject is an object representation of a subset of XML data. Supported XML features are tags, attributes, and character content.
The Teuchos Comm subpackage (Trilinos_ENABLE_TeuchosComm=ON) contains support for SPMD parallel programs and useful utilities that depend on these.
Single Program Multiple Data (SPMD)
Teuchos::Comm provides an abstract interface to a small subset of the Message Passing Interface (MPI), whether or not Trilinos was actually built with MPI support.
Teuchos::TimeMonitor: A class that automates (and makes exception safe) the process of starting and stopping timers, lets users create timers that are automatically registered and tracked, and provides functions for computing timer statistics over any given set of parallel processes.
The Teuchos Numerics subpackage (Trilinos_ENABLE_TeuchosNumerics=ON) contains BLAS and LAPACK C++ wrappers and C++ classes that use these for dense serial matrices and vectors.
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.
Serial Dense Matrix class: Teuchos::SerialDenseMatrix - A templated dense matrix class. It 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. Bounds checking can be turned on at compile time with the
Teuchos_ENABLE_DEBUG=ON configure flag.
The Teuchos Remainder subpackage (Trilinos_ENABLE_TeuchosRemainder=ON)contains left over stuff that does not fit will into the above subpackages or is slated to be deprecated and removed.
You can browse all of Teuchos as a single doxygen collection. This is not the recommended way to learn about Teuchos software. However, it is a good way to browse the directory structure of Teuchos or to locate specific files.