|
Teuchos - Trilinos Tools Package
Version of the Day
|
|
Teuchos - Trilinos Tools Package
Version of the Day
|
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.
The following people have contributed to the development of Teuchos:
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.
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:
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 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::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 other array types.
Teuchos::Tuple: Compile-time sized array class.
Teuchos::ConstNonconstObjectContainer: A simple wrapper class for implementing the "runtime protection of const" idiom.
Runtime debug checking of the above classes can be turned on by setting -DTeuchos_ENABLE_DEBUG:BOOL=ON when configuring. Also, strong runtime checking of reference counting including detection of circular RCPs, detection of duplicate owning RCPs, and detection of dangling non-owning RCPs can be turned on by also configuring with -DTeuchos_ENABLE_DEBUG_RCP_NODE_TRACING:BOOL=ON. Support for boost must also be enabled with -DTeuchos_ENABLE_BOOST=ON in order to get the strongest debug-mode runtime checking. Without these configure options, all of these classes are configured by default to be as efficient as possible.
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.
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 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 an 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_STRACTRACE. 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_STRACTRACE 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 stacktracing. It is just debug builds that it is enabled for (and then only be default and can be disabled).
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 excpetions. Therefore, the testing infrastructure for Trilinos with the checkin-test.py script turns off stack tracing by default by configuring with Teuchos_ENABLE_DEFAULT_STRACTRACE=OFF.
Testing Unit Support
Teuchos contains some utilities that make it easier to write unit tests. See the native Unit Testing Support Code.
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
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.
1.7.6.1