Development of linear Abstract Numerical Algorithms (ANAs)
[Use Cases for the Fundamental Thyra Operator/Vector Interfaces]

Collaboration diagram for Development of linear Abstract Numerical Algorithms (ANAs):

While the Fundamental Thyra Operator/Vector Interfaces were not principally designed to provide a direct API for the development of ANA software, with some minimal helper functions and classes, directly writing even sophisticated ANA implementations directly in terms of Thyra objects is quite straightforward. More...


Modules
	General ANA support code
	Collection of all multi-vector operations
	Miscellaneous C++ utility code for testing and debugging.
	Collection of all vector operations
Classes
class	Thyra::DefaultAddedLinearOp< Scalar >
	Concrete composite `LinearOpBase` subclass that creates an implicitly added linear operator out of one or more constituent `LinearOpBase` objects. More...
class	Thyra::DefaultBlockedLinearOp< Scalar >
	Concrete composite `LinearOpBase` subclass that creates single linear operator object out of a set of constituent `LinearOpBase` blocks. More...
class	Thyra::DefaultDiagonalLinearOp< Scalar >
	Default concrete `LinearOpBase` subclass for diagonal linear operators. More...
class	Thyra::DefaultIdentityLinearOp< Scalar >
	Represents a identity linear operator `M = I`. More...
class	Thyra::DefaultMultipliedLinearOp< Scalar >
	Concrete composite `LinearOpBase` subclass that creates an implicitly multiplied linear operator out of one or more constituent `LinearOpBase` objects. More...
class	Thyra::DefaultMultiVectorProductVector< Scalar >
	Concrete implementation of a product vector which is really composed out of the columns of a multi-vector. More...
class	Thyra::DefaultMultiVectorProductVectorSpace< Scalar >
	Standard concrete implementation of a product vector space that creates product vectors fromed implicitly from the columns of a multi-vector. More...
class	Thyra::DefaultProductMultiVector< Scalar >
	Concrete implementation of a product multi-vector. More...
class	Thyra::DefaultProductVector< Scalar >
	Concrete implementation of a product vector. More...
class	Thyra::DefaultProductVectorSpace< Scalar >
	Standard concrete implementation of a product vector space. More...
class	Thyra::DefaultScaledAdjointLinearOp< Scalar >
	Concrete decorator `LinearOpBase` subclass that wraps a `LinearOpBase` object and adds on an extra scaling factor and/or a transpose enum. More...
class	Thyra::DefaultZeroLinearOp< Scalar >
	Represents a zero linear operator `M = 0`. More...
class	Thyra::ConstDetachedMultiVectorView< Scalar >
	Create an explicit non-mutable (const) view of a `MultiVectorBase` object. More...
class	Thyra::DetachedMultiVectorView< Scalar >
	Create an explicit mutable (non-const) view of a `MultiVectorBase` object. More...
class	Thyra::ConstDetachedVectorView< Scalar >
	Create an explicit non-mutable (const) view of a `VectorBase` object. More...
class	Thyra::DetachedVectorView< Scalar >
	Create an explicit mutable (non-const) view of a `VectorBase` object. More...
class	Thyra::LinearOpDefaultBase< RangeScalar, DomainScalar >
	Node subclass that provides a good default implementation for the `describe()` function. More...
class	Thyra::ConstLinearOperator< RangeScalar, DomainScalar >
class	Thyra::LinearOperator< RangeScalar, DomainScalar >
class	Thyra::LinearOpTester< RangeScalar, DomainScalar >
	Testing class for `LinearOpBase`. More...
class	Thyra::ListedMultiVectorRandomizer< Scalar >
	`MultiVectorRandomizerBase` subclass that returns a revolving list of preset `MultiVectorBase` objects. More...
class	Thyra::MultiVectorDefaultBase< Scalar >
	Node subclass that uses a default `MultiVectorBase` implementation to provide default implementations for as many other functions in `MultiVectorBase` interface the as is reasonable. More...
class	Thyra::MultiVectorTester< Scalar >
	Unit testing class for a `MultiVectorBase` object. More...
class	Thyra::ParameterDrivenMultiVectorInput< Scalar >
	Concrete utility class that an ANA can use for reading in a (multi)vector as directed by a parameter sublist. More...
class	Thyra::SingleRhsLinearOpBase< Scalar >
	Base class for linear operators that can only implement a single RHS vector apply operation and only support one scalar type. More...
class	Thyra::SingleScalarLinearOpBase< Scalar >
	Base class for linear operators that can only handle a single scalar type. More...
class	Thyra::UniversalMultiVectorRandomizer< Scalar >
	Univeral `MultiVectorRandomizerBase` subclass that is compatible with all `MultiVectorBase` objects. More...
class	Thyra::Converter< Scalar, TargetType >
	Converter that defines the interface for objects that can be converted to vectors. More...
class	Thyra::ConstVector< Scalar >
	Read-only handle class for wrapping `Thyra::VectorBase` objects and allowing for operator-overloading linear algebra. More...
class	Thyra::Vector< Scalar >
	Read-write handle class for wrapping `Thyra::VectorBase` objects and allowing for operator-overloading linear algebra. More...
class	Thyra::VectorDefaultBase< Scalar >
	Convenient node subclass for concrete `VectorBase` subclasses that relies on a default `MultiVectorBase` implementation. More...
class	Thyra::VectorSpace< Scalar >
	Handle class for `VectorSpaceBase`. More...
class	Thyra::VectorSpaceDefaultBase< Scalar >
	Node `VectorSpaceBase` subclass that provides default implementations for many functions using a default multi-vectors implementation. More...
class	Thyra::VectorSpaceTester< Scalar >
	Testing class for `VectorSpace` and the `VectorBase` and `MultiVectorBase` objects that it creates. More...
class	Thyra::VectorTester< Scalar >
	Unit testing class for a `VectorBase` object. More...
Enumerations
enum	Thyra::LCSign
	LCSign is used to indicate whether a linear combination object represents addition or subtraction. More...
Functions
template<class Scalar>
Scalar	Thyra::convertTo (const LCSign sign)
	Convert LCSign to a floating-point Scalar object.

Detailed Description

It turns out that using Thyra for the development of simple ANAs, as described below, really does not require any deep understanding of the foundational Thyra operator/vector interfaces.

Overview of Using Thyra Software for Development of ANA Software

There are several different types of helper classes and functions that simplify the use of Thyra for the development of ANAs.

Java-like handle classes supporting efficient operator-overloading for linear algebra operations
The following Java-like handle classes wrap Thyra base objects and define the basic linear algebra operations:
- Thyra::VectorSpace wraps Thyra::VectorSpaceBase objects.
- Thyra::Vector wraps Thyra::VectorBase objects and allows developers to write linear algebra experessions like y = alpha*x + z. The class Thyra::ConstVector is a base class of Thyra::Vector that allows for the compile checking of const protection.
- Thyra::LinearOperator wraps Thyra::LinearOpBase objects and allows developers to write linear algebra experessions like D = alpha*A + adjoint(B) * C. Unlike vectors, however, explicit objects are not formed in these types of operations and instead the implicit operators defined below. The class Thyra::ConstLinearOperator is a base class of Thyra::LinearOperator that allows for the compile checking of const protection.
Hande clases have the same basic semantics as Thyra::RCP for copy construction and assignment and infact they all use Thyra::RCP internally to point to the underlying Thyra base objects. For an example of their use, see the function sillierCgSolve() which calls silliestCgSolve().
"Standard" non-member wrapper functions for vector (and multi-vector) reduction/transformation operations
While the use of the RTOpPack::RTOpT interface class and the single Thyra::VectorBase::applyOp() function provide an elegant and efficient solution for the interoperability of vector interfaces, it is not the easiest API for developing ANAs. However, a number of easy to use C++ wrapper functions for many different vector and multi-vector operations is already provided:
- Collection of all vector operations
- Collection of all multi-vector operations
These C++ wrapper functions rely on pre-implemented RTOpPack::RTOpT subclasses. Adding new RTOpPack::RTOpT subclasses and new wrapper functions for new vector and multi-vector reduction/transformation operations is an easy matter for an experienced C++ developer who understands RTOpPack::RTOpT (please contact rabartl@sandia.gov if you need a new vector or multi-vector operation that is not already supported).
Implicit vector space, vector, multi-vector and linear operator subclasses
One of the big advantages of having a set of abstract interfaces to operators and vectors is that it is quite easy to define some very useful aggregate subclasses that allow one or more individual objects be treated as a single object (see the "Composite" and "Decorator" design patterns in the GoF's "Design Patterns" book).
1. Implicit product vector spaces, vectors and multi-vectors
  One particularly useful category of composite linear algebra objects is the product vector space $\mathcal{X} = \mathcal{V}_0 {}\times \mathcal{V}_1 {}\times {}\ldots {}\times \mathcal{V}_{m-1}$ where $\mathcal{V}_k$ , for $k = 0 {}\ldots {m-1}$ , are different constituent vector spaces. Product vector spaces give rise to product vectors
  
  $x = \left[\begin{array}{c} v_0 \\ v_1 \\ \vdots \\ v_{m-1} \end{array}\right]$
  
  (where $v_0 \in \mathcal{V}_0, v_1 \in \mathcal{V}_1, \ldots, v_{m-1} \in \mathcal{V}_{m-1}$ ) and product multi-vectors
  
  $X = \left[\begin{array}{c} V_0 \\ V_1 \\ \vdots \\ V_{m-1} \end{array}\right].$
  
  (where $V_0 \in \mathcal{V}_0 | \mathcal{D}, V_1 \in \mathcal{V}_1 | \mathcal{D}, \ldots, V_{m-1} \in \mathcal{V}_{m-1} | \mathcal{D}$ and $\mathcal{D}$ is the domain space for the multi-vectors).
  Very general concrete implementations of the product vector space, vector and multi-vector interfaces described here are provided and are shown below:
  - Thyra::DefaultProductVectorSpace is a general concrete implementation of Thyra::ProductVectorSpaceBase that should be sufficient for most use cases.
  - Thyra::DefaultProductVector is a general concrete implementation of Thyra::ProductVectorBase that should be sufficient for most use cases.
  - Thyra::DefaultProductMultiVector is a general concrete implementation of Thyra::ProductMultiVectorBase that should be sufficient for most use cases.
  Note that the above concrete subclasses are very efficient for must, but not all, possible use cases for such composite objects.
  When using product vector spaces, product vectors and product multi-vectors it is generally the case where a concrete Thyra::DefaultProductVectorSpace object is first created and then Thyra::DefaultProductVector and Thyra::DefaultProductMultiVector objects are created by the functions Thyra::DefaultProductVectorSpace::createMember() and Thyra::DefaultProductVectorSpace::createMembers(). See this example of how product vector spaces are used.
2. Miscellaneous implicit linear operators
  These are several different types of useful implicit composite/decorator Thyra::LinearOpBase subclasses. These concrete subclasses provide the building blocks for arbitararly complex implicitly composed linear operators. Default implementations for these implicit linear operator subclasses are shown below:
  - Thyra::DefaultZeroLinearOp is used to define a zero linear operator of the form:
    $M = 0 \in \Re^{m \times n}$
    defined in terms of two vector spaces (a range and a domain).
  - Thyra::DefaultIdentityLinearOp is used to define an identity linear operator of the form:
    $M = I \in \Re^{n \times n}$
    defined in terms of a single vector space.
  - Thyra::DefaultDiagonalLinearOp is a simple concrete subclass that defines a diagonal linear operator
    $M = \mbox{diag}(d) \in \Re^{n \times n}$
    out of any Thyra::VectorBase object for the diagonal $d \in \Re^n$ .
  - Thyra::DefaultScaledAdjointLinearOp is a simple concrete decorator subclass that defines an implicit scaled and/or adjoined (or transposed) linear operator
    $M = \gamma \; op(A)$ .
  - Thyra::DefaultAddedLinearOp is a simple concrete composite subclass that represent the implicit addition of two or more constituent Thyra::LinearOpBase objects of the form
    $M =\; A_0 + A_1 + \ldots + A_{m-1}}$
    composed out of one or more constituent linear operators $A_0, A_1 \ldots A_{m-1}$ .
  - Thyra::DefaultMultipliedLinearOp is a simple concrete composite subclass that defines a composite multiplicative Thyra::LinearOpBase of the form
    $M =\; A_0 A_1 \ldots A_{m-1}}$
    composed out of one or more constituent linear operators $A_0, A_1 \ldots A_{m-1}$ .
  - Thyra::DefaultBlockedLinearOp is a simple concrete composite subclass that defines a composite blocking of Thyra::LinearOpBase objects of the form
    $M = \begin{array}{cccc} A_{0,0} & A_{0,1} & \ldots & A_{0,n-1} \\ A_{1,0} & A_{1,1} & \ldots & A_{1,n-1} \\ \vdots & \vdots & \ddots & \vdots \\ A_{m-1,0} & A_{m-1,1} & \ldots & A_{m-1,n-1} \end{array}$
    composed out of one or more constituent linear operators.
Creating explicit views of vector and multi-vector elements
Warning! using the utility classes below it is very easy to obtain direct access to vector and multi-vector elements but in general, this is a very bad idea. However, as described in this report, there are some types of ANAs that require direct element access to certain kinds of vectors and multi-vectors (for example, vectors and multi-vectors that lie is the domain space of a multi-vector). The following utility classes streamline creating and using explicit views.
- Thyra::ConstDetachedVectorView creates a (const) non-mutable explicit view of a const Thyra::VectorBase object, allows direct access to vector elements and then frees the view in the destructor.
- Thyra::DetachedVectorView creates a (non-const) mutable explicit view of a Thyra::VectorBase object, allows direct access to vector elements and then frees the view in the destructor.
- Thyra::ConstDetachedMultiVectorView creates a (const) non-mutable explicit view of a const Thyra::MultiVectorBase object, allows direct access to multi-vector elements and then frees the view in the destructor.
- Thyra::DetachedMultiVectorView creates a (non-const) mutable explicit view of a Thyra::MultiVectorBase object, allows direct access to multi-vector elements and then frees the view in the destructor.
One of the big advantages of using the above utility classes in addition to their convenience is that views are freed in destructors and these view will be freed even in the event that an exception is thrown. The use of these view classes is quite straightforward.
Basic default implementation node subclasses
The following subclasses directly derive from Fundamental Thyra Operator/Vector Interfaces and provide general default implementations for as many virtual functions as reasonable:
- Thyra::VectorSpaceDefaultBase should be a direct or indirect base class of almost every concrete Thyra::VectorSpaceBase adapter subclass. This node subclass provides the default implementation Thyra::VectorSpaceDefaultBase::createMembers() using the Thyra::DefaultColumnwiseMultiVector subclass. Therefore, a subclass need only provide a VectorBase implementation and override the Thyra::VectorSpaceBase::createMember() and related functions.
- Thyra::LinearOpDefaultBase should be a direct or indirect base class of almost every concrete Thyra::MultiVectorBase adpater subclass. This node subclass provides just the default implementation override Thyra::LinearOpDefaultBase::describe()
- Thyra::SingleScalarLinearOpBase provides a node subclass for all linear operators that can only handle a single scalar type for both the range and domain spaces.
- Thyra::SingleRhsLinearOpBase provides a node subclass for all linear operators that can only handle a single scalar type for both the range and domain spaces and only single vector arguments for Thyra::SingleRhsLinearOpBase::apply().
- Thyra::MultiVectorDefaultBase should be a direct or indirect base class of almost every concrete Thyra::MultiVectorBase adpater subclass. This node subclass provides a default of every inherited virtual function from the base class Thyra::MultiVectorBase in terms of just Thyra::MultiVectorBase::col(). While many of these default function implementations are highly non-optimal, however, they allow for rapid prototyping of new Thyra::MultiVectorBase subclasses.
- Thyra::VectorDefaultBase should be a direct or indirect base class of almost every concrete Thyra::VectorBase adpater subclass. This node subclass provides full general and efficient implementations of all of the inherited virtual functions from the base class Thyra::MultiVectorBase.
Unit testing software
This is basic testing software for Thyra:
- Thyra::LinearOpTester is a unit testing class that validates the implementation of a Thyra::LinearOpBase object by checking its linear properties, and/or its adjoint, and/or symmetry. In addition, it can check if two linear operators are the same.
- Thyra::MultiVectorTester is a unit testing class that validates the implementation of a Thyra::MultiVectorBase object. This class exposes a Thyra::LinearOpTester object for testing the LinearOpBase base interface of Thyra::MultiVectorBase.
- Thyra::VectorTester is a unit testing class that validates the implementation of a Thyra::VectorBase object. This class exposes a Thyra::MultiVectorTester object for testing the MultiVectorBase base interface of Thyra::VectorBase.
- Thyra::VectorSpaceTester is a unit testing class that accepts any Thyra::VectorSpaceBase object and then proceeds to create a number of Thyra::VectorBase and Thyra::MultiVectorBase objects and then and validates all of these objects. This class class, therefore, is a unit testing class for all three interfaces ThyraVectorSpaceBase, ThyraVectorBase, and Thyra::MultiVectorBase.
- Thyra::VectorStdOpsTester is a unit testing class that accepts any Thyra::VectorSpaceBase object and then tests all of the standard vector RTOp wrappers documented here.
- Thyra::MultiVectorStdOpsTester is a unit testing class that accepts any Thyra::VectorSpaceBase object and then tests all of the standard multi-vector RTOp wrappers documented here.
Miscellaneous Tools for testing and debugging
There is software included in the Thyra package to support basic testing and debugging.
First, 100/% general output stream operators for any Thyra::VectorBase or Thyra::LinearOpBase object are provided in the following operator functions:
- Thyra::operator<<(std::ostream& o, const Thyra::VectorBase<Scalar>& v) is an output stream operator for printing Thyra::VectorBase objects.
- Thyra::operator<<(std::ostream& o, const Thyra::LinearOpBase<Scalar>& M) is an output stream operator for printing Thyra::LinearOpBase (and therefore also Thyra::MultiVectorBase) objects.
Miscellaneous software
Here is software that does not neatly fall into any of the above categories but is still considered ANA software.
- Thyra::ParameterDrivenMultiVectorInput is a simple concrete utility class that derives from Teuchos::ParameterListAcceptor that defines a parameter sublist that specifies how to read (multi)vectors for a file(s) or directly from the parameter list.

Examples of Abstract Numerical Algorithms

There are several code examples that one can study to see how to use the code described here as an API for developing ANAs.

sillyPowerMethod() is a simple example ANA that implements the power method for estimating the dominate eigenvalue of a linear operator.
sillyCgSolve() is a simple example ANA that implements the conjugate gradient method for solving a symmetric positive definite linear system.
sillierCgSolve() calls the function silliestCgSolve() to implement CG using handle classes.
silliestCgSolve() is a simple example ANA that also implements the conjugate gradient method for solving a symmetric positive definite linear system but it uses the handle layer with operator overloading.
Thyra::LinearOpTester::check() shows how to access a Thyra::LinearOpBase objects domain and range spaces, how to use these spaces to create vectors and multi-vectors and how to perform various types of operations involving vectors, multi-vectors and linear operators.

Other Use Cases

Enumeration Type Documentation

enum Thyra::LCSign

LCSign is used to indicate whether a linear combination object represents addition or subtraction.

Definition at line 58 of file Thyra_VectorDecl.hpp.

Function Documentation

template<class Scalar>

Scalar Thyra::convertTo ( const LCSign sign ) [inline]

Convert LCSign to a floating-point Scalar object.

Definition at line 65 of file Thyra_VectorDecl.hpp.

Generated on Wed May 12 21:42:28 2010 for Thyra Operator/Vector Support by

1.4.7

Development of linear Abstract Numerical Algorithms (ANAs) [Use Cases for the Fundamental Thyra Operator/Vector Interfaces]

Modules

Classes

Enumerations