Teuchos - Trilinos Tools Package Version of the Day
Loading...
Searching...
No Matches
Teuchos: The Trilinos Tools Library

Outline

Introduction

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.

We encourage the addition of new utilities to Teuchos. Please contact the Teuchos developer team (see below for contact information) if you would like to share your utility.

Teuchos Contributors

The following people have contributed to the development of Teuchos:

Summary of Teuchos' Configuration Options

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.

  • Complex arithmetic: Teuchos does not support complex arithmetic (the std::complex template class) by default. This saves build time and makes libraries smaller. To enable support for complex arithmetic, set the Teuchos_ENABLE_COMPLEX:BOOL=ON CMake option.

Overview of Teuchos Subpackages

Teuchos contains several different types of software. These different collections are organized into different subpackages.

Teuchos Core Subpackage

The Teuchos Core subpackage (Trilinos_ENABLE_TeuchosCore:BOOL=ON) contains basic, general-purpose utilities.

  • Memory Management:

    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.

    By default, these classes are not thread-safe but when configured with -DTeuchos_ENABLE_THREAD_SAFE=ON (or -DTrilinos_ENABLE_THREAD_SAFE=ON), they become thread-safe. (The default may be switched to on in a future version.)

    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

    • Detection of circular references
    • Detection of duplicate owning references
    • Detection of dangling nonowning references

    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:

    • Abstract factories:

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

  • Output 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 to set other information related to the line prefix.

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

  • Exception Handling

    • 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). For related error handling utilties, see Utility code for throwing exceptions and setting breakpoints.

    • 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 variable Teuchos_ENABLE_DEFAULT_STACKTRACE determines if stack tracing is on or off by default 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.

  • Containers

    • Teuchos::Hashtable is a templated dictionary (set of (key,value) pairs) with constant-time lookup for any key.
    • Teuchos::HashSet is a templated set with constant-time lookup.

  • Testing Unit Support

    Teuchos contains some utilities that make it easier to write unit tests. See the native Unit Testing Support Code.

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

Teuchos ParameterList Subpackage

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.

Teuchos Communication Subpackage

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)

  • Performance Monitoring

    • Teuchos::Time: A platform-independent timer implementation. This may be used either by itself, or in combination with Teuchos::TimeMonitor for tracking global timer statistics over processes. If Teuchos is configured with TPL_ENABLE_Valgrind=ON and Teuchos_TIME_MASSIF_SNAPSHOTS=ON Valgrind Massif snapshots are taken before and after each Teuchos::Time invocation. The resulting memory profile can be plotted using the script core/utils/plotMassifMemoryUsage.py.

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

    • Teuchos::Flops - Provides functions that count and report the number of executed floating-point operations (flop). Many Teuchos computational classes accumulate flop counts associated with the this object of the computations.

Teuchos Numerics Subpackage

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.

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

Teuchos Parser Subpackage

The Teuchos Parser subpackage (Trilinos_ENABLE_TeuchosParser=ON) contains classes to parse text-based file formats described as formal grammars. It can be used to parse XML, YAML, and other complex textual input formats. It can be thought of as a version of Flex and Bison which is a set of C++ functions acting on C++ objects as opposed to a set of programs acting on source files. The two main classes in Teuchos Parser are:

  • Teuchos::Language: Stores the user's specification of the file format as a Context Free Grammar plus token regular expressions.
  • Teuchos::Reader: Is subclassed by the user to specify what actions to perform at each stage of parsing a text stream.

Teuchos Remainder Subpackage

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.

Browse all of Teuchos

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.