Frequently Asked Questions (FAQ) about Thyra Operator/Vector Software

Outline

• Questions about the smart pointer class Teuchos::RefCountPtr
  • Q: What are RefCountPtr objects and why are they important?
  • Q: Do I really have to write &*ptr all the time?
  • Q: Should my code use RefCountPtr's everywhere?

• Questions about Fundamental Thyra Operator/Vector Interfaces
  • Q: Why is Thyra written with so many non-member helper functions instead of member functions?
  • Q: Why don't Thyra vectors support element access using the an overloaded operator[]?
  • Q: Why doesn't Thyra support linear algebra operations using overloaded operators for +, -, *, etc?
  • Q: Where is the Scalar class, and how do I use it to replace my underlying data-type, e.g. double, in my ANA?
  • Q: How do I create a Thyra::VectorBase or Thyra::MultiVectorBase object?

Questions about the smart pointer class Teuchos::RefCountPtr

Q: What are RefCountPtr objects and why are they important?

A:The class Teuchos::RefCountPtr implements a form of reference counting which, through the magic of smart pointers in C++, allows objects to be created and used without much concern for when and where they should be deleted. It is a form of garbage collection but is not as general or fail- safe as in languages with built in garbage collection. For more information see:

http://software.sandia.gov/Trilinos/RefCountPtrBeginnersGuideSAND.pdf

and click on: Teuchos::RefCountPtr

Q: Do I really have to write &*ptr all the time?

What are the benefits of &* vs. get()?

A: There are two ways to get at the underlying raw pointer to an object that is wrapped in the RefCountPtr<C> object c_ptr:

C *c_rptr1 = c_ptr.get(); // Unchecked, can be NULL
C *c_rptr2 = &*c_ptr;     // Checked in debug build and will not return NULL

You should use c_ptr.get() when it is okay for the pointer to be NULL. On the other hand, you should use &*c_ptr when you don't want to allow the raw pointer to be NULL. This is because the operator function <tt>Teuchos::RefCountPtr::operator*() will throw an exception if Teuchos::RefCountPtr::get()==NULL when the code is compiled using the macro define -D_DEBUG.

For more information see Item 3 in Appendix B in

http://software.sandia.gov/Trilinos/RefCountPtrBeginnersGuideSAND.pdf

Q: Should my code use RefCountPtr's everywhere?

A: You should only use RefCountPtr to wrap objects where a persisting relationship is being formed or maintained. For non-persisting relationships, use raw C++ references and pointers.

For more information see the main body and Appendix D of the document:

http://software.sandia.gov/Trilinos/RefCountPtrBeginnersGuideSAND.pdf

Questions about Fundamental Thyra Operator/Vector Interfaces

Q: Why is Thyra written with so many non-member helper functions instead of member functions?

In my C++ class we were told that the beauty of OOP is that functions and data can be put together into classes to combine the operations with the data they operate on.

A: Generally member functions should only be used over non-member functions when direct access to private or protected data for functions is required. My minimizing the amount of code that can access non-public data you greatly simplify maintenance. See section 11.3.1 in "The C++ Programming Language: Special Edition" for a discussion of this topic.

Q: Why don't Thyra vectors support element access using the an overloaded operator[]?

A: Direct element access to vector data through the Thyra::VectorBase interface can not be allowed in most general abstract numerical algorithms except in very specialized cases. Direct element access assumes that all of the the vector data is readily available which is not the case in distributed-memory, out-of-core and certainly not client/server runtime configurations. In addition, an overloaded operator[] function would be extremely inefficient since it would have to be a virtual function.

For more information on the philosophy of the design of vector interface Thyra::VectorBase see the document "Vector Reduction/Transformation Operators" at:

http://software.sandia.gov/RTOp/RTOpTOMS.pdf

Q: Why doesn't Thyra support linear algebra operations using overloaded operators for +, -, *, etc?

A: Supporting Matlab-like syntax for linear algebra operations like:

  y = alpha*x + z;

  y = adjoint(A)*x + B*z;

for large abstract objects in a near-optimally efficient manner is extremely non-trivial. Such a capability can be supported through the creation of handle classes and compile-time expression templates but such an implementation is complicated and is difficult for beginners to debug through. There are a whole host of other reasons they Matlab-like syntax will not work as well as in Matlab. For a slightly more detailed discussion, see the document

A Simple Convention for the Specification of Linear Algebra Function Prototypes in C++

In short, Thyra does not (yet) support operator overloading for Matlab-like syntax and will not until the resulting code can be as efficient, compile-time safe, and as debuggable as the current lower-level function-call interface. However, check back with Thyra in the near future and you might find such handle classes with operator overloading.

Q: Where is the Scalar class, and how do I use it to replace my underlying data-type, e.g. double, in my ANA?

A: The 'Scalar' class in a template argument in all of the core Thyra interface code. The goal of this template argument is to allow many abstract numerical algorithms to be written in a general form to support a number of different scalar types (e.g. real, complex, extended precision etc.). While the interfaces, the composite classes, and many of the concrete implementations are fully templated some are not and can only support one scalar type (e.g. see the Epetra/Thyra adapters).

See the Thyra::sillyCgSolve() and Thyra::sillyPowerMethod() examples for how this templating is used.

Q: How do I create a Thyra::VectorBase or Thyra::MultiVectorBase object?

The member functions Thyra::VectorSpaceBase::createMember() and Thyra::VectorSpaceBase::createMembers() are protected and can not be called by client code.

A: You must use the non-member functions Thyra::createMember() and Thyra::createMembers() described here.

---