1. Teuchos: Utilities for Developers & Users November 2nd, 3:30-4:30pm Roscoe Bartlett Mike Heroux Kris Kampshoff Kevin Long Paul Sexton Heidi Thornquist
Questions from audience
Can you use another matrix-vector multiply?
Are multivectors supported?
Are Petsc and Hypre available via TSF?
How does Trilinos differ from Petsc?
Sandia is a multiprogram laboratory operated by Sandia Corporation, a Lockheed Martin Company, for the United States Department of Energy under contract DE-AC04-94AL85000.

2. What is Teuchos (TEF-hos)?
Lightweight, portable utility package
What’s new?
First release in Trilinos 4.0
Templated BLAS/LAPACK interface
Templated serial dense matrix / vector
Timing classes
Templated parameter list
Numeric traits mechanisms ( ordinal / scalar )
Memory management:
Reference-counted pointers
Pre-allocated workspace
Exception handling
Command-line parsing
“Extended” utilities:
XML parsing
MPI communicators / traits
Users
Developers

3. Templated Parameter List
Design based on NOX parameter list
Adopted by Amesos, ML, Ifpack, AztecOO, …
Parameter lists can be queried for attributes.
No mechanism for “smart” queries of tags.
// Has a solver been chosen?
bool solver_defined = My_List.isParameter(“Solver”);
// Has a preconditioner been chosen?
bool prec_defined = My_List.isSublist(“Preconditioner”);
// Has a double-precision drop tolerance been chosen? (Helper function)
bool drop_tol = Teuchos::isParameterType<double>(Prec_List,
“Drop Tolerance”);
// What if we use the wrong parameter name?
bool solve_tol = My_List.isParameter(“tolerance”);
ReturnType foo_solver( Teuchos::ParameterList& solverPL,… ) {
// Getting parameters
int max_iters = solverPL.template<int> get("Max Iters");
std::string solver = getParameter(solverPL, “Solver”)
double tol = solverPL.get("Tolerance", 1e-8);
// Get sublist ( same as making sublist )
Teuchos::ParameterList precPL = solverPL.sublist("Preconditioner"); …
return Ok; }
Parameters can be input and retrieved with templated “set” and “get” methods, as well as helper functions.
Parameters can be numeric datatypes, pointers to vectors or functions, and other parameter lists.
// Empty parameter list
Teuchos::ParameterList My_List;
// Setting parameters
My_List.set("Max Iters", 1550);
My_List.set("Tolerance", 1e-10);
My_List.set("Solver", "GMRES");
// Create sublist
Teuchos::ParameterList& Prec_List = My_List.sublist("Preconditioner");
// Setting parameters in sublist
Prec_List.set("Type", "ILU");
Prec_List.set("Drop Tolerance", 1e-3);
Parameters can be input and retrieved with templated “set” and “get” methods, as well as helper functions.

4. Numeric Traits Mechanisms
Generic programming technique that uses templated interfaces to define the standard behavior of datatypes.
Assumed: addition, subtraction, multiplication, and division
OrdinalTraits
zero & one
int & long int
ScalarTraits
zero, one, magnitude type, absolute value, conjugate,
square root, random number generator, …
std::numeric_limits
float, double, complex<float>, and complex<double>
Required: none, a compile-time check is performed.
What about arbitrary precision arithmetic?

5. Arbitrary Precision Libraries ARPREC & GNU MP
ARPREC (Bailey, et. al.)
uses arrays of 64-bit floating-point numbers to represent high-precision floating-point numbers.
provides support for datatypes with differing precision levels.
--enable-teuchos-arprec
GNU MP
uses fullwords, arbitrary precision mantissa, and limited precision exponent to represent high-precision floating-point numbers.
platform specific kernels written in assembly language perform common inner-loop functions.
--enable-teuchos-gmp
Caveat: Arbitrary precision arithmetic is expensive, but can be used selectively to overcome numerical inaccuracy.

6. Templated BLAS Interface
Basic Linear Algebra Subroutines (BLAS)
Robust, high-performance dense vector-vector, matrix-vector, and matrix-matrix routines.
Written in Fortran
Fast and efficient
Fortran is highly portable; however, the interface between it and C++ is platform-dependent
Templated C++ wrappers for the BLAS Fortran routines are created through autoconf.
Two main benefits of using a templated interface
Template Specialization: template specialization can be used to support the four native datatypes of existing Fortran BLAS code.
General Implementation: a generic C++ implementation can be created to handle many arbitrary datatypes.

7. Templated BLAS Interface
Using Native Datatypes
Teuchos::BLAS<int,double> blas;
blas.AXPY(…) …
blas.GEMV(…) …
blas.GEMM(…)
Using ARPREC
mp::mp_init(200);
Teuchos::BLAS<int,mp_real> blas;
blas.AXPY(…) …
blas.GEMV(…) …
blas.GEMM(…)

8. Templated LAPACK Interface
Linear Algebra PACKage (LAPACK)
Robust, high-performance dense routines for solving systems of simultaneous linear equations, least-squares solutions of linear systems of equations, eigenvalue problems, and singular value problems.
Templated C++ wrappers for the LAPACK Fortran routines are created for the four native datatypes.
no general implementations at this time
Templated serial dense matrix / vector class designed to be compatible with BLAS/LAPACK interfaces.
Fortran-style storage
Similar to Epetra_SerialDenseMatrix

9. Hilbert Matrices
A Hilbert matrix HN is a square N-by-N matrix such that:
Notoriously ill-conditioned
κ(H3)  524
κ(H5) 
κ(H10)  x 1013
κ(H20)  x 1017
κ(H100)  x 1020
Theoretically, Hilbert matrices are SPD

10. Cholesky Factorization and Hilbert Matrices
In practice, floating-point rounding error causes higher-order Hilbert matrices to no longer be positive definite
Cholesky factorization is often done to determine whether or not a given matrix is positive definite
As such, a Cholesky factorization will often fail on higher-order Hilbert matrices, even though such matrices “should” be positive definite
Precision
Largest N for which Cholesky Factorization is successful
Single Precision 8
Double Precision 13
Arbitrary Precision (20) 29
Arbitrary Precision (40) 40
Arbitrary Precision (200)
145
Arbitrary Precision (400)
233*

11. Cholesky Factorization and Hilbert Matrices
In addition to providing a higher limit on N, using arbitrary precision reduces error.
By solving the linear system: where the vector b is constructed such that the true solution x is equal to a 1-vector we can look at the forward error.

12. Timing Classes Teuchos::Time Teuchos::TimeMonitor
Basic wall-clock timing class
Teuchos::TimeMonitor
Uses Teuchos::Time internally
Constructor starts timer, destructor stops it
Can also maintain an array of timers
Teuchos::Time timer(“My Timer”);
timer.start(); …
timer.stop();
double comp_time = timer.totalElapsedTime()

13. Teuchos Users Overview
Parameter list is easy to use and quickly being adopted by most Trilinos packages.
Numeric traits mechanism allows the use of arbitrary datatypes in templated code.
Such arithmetic may be expensive, but the increased precision may be required for ill-conditioned problems
Arbitrary-precision arithmetic can be used in only the places where it is needed most in order to retain speed
Templated tools libraries are essential for the development of templated solver libraries.
See Teuchos website for more info: