|
Teuchos - Trilinos Tools Package
Version of the Day
|
|
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.
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.
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_ENABLE_COMPLEX:BOOL=ON CMake option. 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.
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
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:
Teuchos::RCP objects. 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
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.
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 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. 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.
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
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::MpiComm is a subclass of Teuchos::Comm that uses MPI.
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.
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.
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:
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.
1.8.5