|
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 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).
Testing Support
Teuchos contains some utilities that make it easier to write tests
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.4