Belos Version of the Day
Public Types | Public Member Functions | Static Public Member Functions
Belos::TsqrOrthoManagerImpl< Scalar, MV > Class Template Reference

TSQR-based OrthoManager subclass implementation. More...

#include <BelosTsqrOrthoManagerImpl.hpp>

List of all members.

Public Types

typedef Scalar scalar_type
typedef Teuchos::ScalarTraits
< Scalar >::magnitudeType 
magnitude_type
typedef MV multivector_type
typedef
Teuchos::SerialDenseMatrix
< int, Scalar > 
mat_type
 Type of the projection and normalization coefficients.
typedef Teuchos::RCP< mat_typemat_ptr

Public Member Functions

 TsqrOrthoManagerImpl (const Teuchos::RCP< const Teuchos::ParameterList > &params, const std::string &label)
 Constructor.
void setLabel (const std::string &label)
 Set the label for timers (if timers are enabled)
const std::string & getLabel ()
 Get the label for timers (if timers are enabled)
void innerProd (const MV &X, const MV &Y, mat_type &Z) const
 Euclidean inner product.
void norm (const MV &X, std::vector< magnitude_type > &normVec) const
 Compute the 2-norm of each column j of X.
void project (MV &X, Teuchos::Array< mat_ptr > C, Teuchos::ArrayView< Teuchos::RCP< const MV > > Q)
 Compute $C := Q^* X$ and $X := X - Q C$.
int normalize (MV &X, mat_ptr B)
 Orthogonalize the columns of X in place.
int normalizeOutOfPlace (MV &X, MV &Q, mat_ptr B)
 Normalize X into Q*B, overwriting X.
int projectAndNormalize (MV &X, Teuchos::Array< mat_ptr > C, mat_ptr B, Teuchos::ArrayView< Teuchos::RCP< const MV > > Q)
 Equivalent (in exact arithmetic) to project(X,C,Q) followed by normalize(X,B).
int projectAndNormalizeOutOfPlace (MV &X_in, MV &X_out, Teuchos::Array< mat_ptr > C, mat_ptr B, Teuchos::ArrayView< Teuchos::RCP< const MV > > Q)
 Project and normalize X_in into X_out; overwrite X_in.
magnitude_type orthonormError (const MV &X) const
 Return $ \| I - X^* \cdot X \|_F $.
magnitude_type orthogError (const MV &X1, const MV &X2) const
 Return the Frobenius norm of the inner product of X1 and X1.
magnitude_type blockReorthogThreshold () const
 Relative tolerance for triggering a block reorthogonalization.
magnitude_type relativeRankTolerance () const
 Relative tolerance for determining (via the SVD) whether a block is of full numerical rank.

Static Public Member Functions

static Teuchos::RCP< const
Teuchos::ParameterList
getDefaultParameters ()
 Get default parameters for TsqrOrthoManagerImpl.
static Teuchos::RCP< const
Teuchos::ParameterList
getFastParameters ()
 Get "fast" parameters for TsqrOrthoManagerImpl.

Detailed Description

template<class Scalar, class MV>
class Belos::TsqrOrthoManagerImpl< Scalar, MV >

TSQR-based OrthoManager subclass implementation.

TsqrOrthoManagerImpl implements the interface defined by OrthoManager. It doesn't actually inherit from OrthoManager, which gives us a bit more freedom when defining the actual subclass of OrthoManager (TsqrOrthoManager).

This class uses a combination of Tall Skinny QR (TSQR) and Block Gram-Schmidt (BGS) to orthogonalize multivectors.

The Block Gram-Schmidt procedure used here is inspired by that of G. W. Stewart ("Block Gram-Schmidt Orthogonalization", SISC vol 31 #1 pp. 761--775, 2008), except that we use TSQR+SVD instead of (Gram-Schmidt with reorthogonalization) to handle the current block. "Orthogonalization faults" may still happen, but we do not handle them by default. Rather, we make one BGS pass, do TSQR+SVD, check the resulting column norms, and make a second BGS pass (+ TSQR+SVD) if necessary. If we then detect an orthogonalization fault, we throw TsqrOrthoFault.

Note:
Despite the "Impl" part of the name of this class, we don't actually use it for the "pImpl" C++ idiom. We just separate out the TSQR implementation to make it easier to implement the OrthoManager and MatOrthoManager interfaces for the case where the inner product operator is not the identity matrix.

Definition at line 128 of file BelosTsqrOrthoManagerImpl.hpp.


Member Typedef Documentation

template<class Scalar , class MV >
typedef Scalar Belos::TsqrOrthoManagerImpl< Scalar, MV >::scalar_type

Definition at line 131 of file BelosTsqrOrthoManagerImpl.hpp.

template<class Scalar , class MV >
typedef Teuchos::ScalarTraits<Scalar>::magnitudeType Belos::TsqrOrthoManagerImpl< Scalar, MV >::magnitude_type

Definition at line 132 of file BelosTsqrOrthoManagerImpl.hpp.

template<class Scalar , class MV >
typedef MV Belos::TsqrOrthoManagerImpl< Scalar, MV >::multivector_type

Definition at line 133 of file BelosTsqrOrthoManagerImpl.hpp.

template<class Scalar , class MV >
Belos::TsqrOrthoManagerImpl< Scalar, MV >::mat_type

Type of the projection and normalization coefficients.

Definition at line 136 of file BelosTsqrOrthoManagerImpl.hpp.

template<class Scalar , class MV >
typedef Teuchos::RCP<mat_type> Belos::TsqrOrthoManagerImpl< Scalar, MV >::mat_ptr

Definition at line 137 of file BelosTsqrOrthoManagerImpl.hpp.


Constructor & Destructor Documentation

template<class Scalar , class MV >
Belos::TsqrOrthoManagerImpl< Scalar, MV >::TsqrOrthoManagerImpl ( const Teuchos::RCP< const Teuchos::ParameterList > &  params,
const std::string &  label 
)

Constructor.

Parameters:
params[in] Configuration parameters, both for this orthogonalization manager, and for TSQR itself (as an RCP<const ParameterList> under "TsqrImpl"). Call the getDefaultParameters() class method for default parameters and their documentation, including TSQR implementation parameters. Call the getFastParameters() class method to get documented parameters for faster computation, possibly at the expense of accuracy and robustness. If params is null, then getDefaultParameters() is used. Otherwise, we make and store a deep copy of params, so that after the constructor returns, you may change params without affecting the configuration of this TsqrOrthoManagerImpl instance.
label[in] Label for timers. This only matters if the compile-time option for enabling timers is set.

Definition at line 816 of file BelosTsqrOrthoManagerImpl.hpp.


Member Function Documentation

template<class Scalar , class MV >
Teuchos::RCP< const Teuchos::ParameterList > Belos::TsqrOrthoManagerImpl< Scalar, MV >::getDefaultParameters ( ) [static]

Get default parameters for TsqrOrthoManagerImpl.

Get a (pointer to a) default list of parameters for configuring a TsqrOrthoManager or TsqrMatOrthoManager instance. The same parameters work for both.

Note:
To get nondefault behavior, a good thing to do is to make a deep copy of the returned parameter list, and then modify individual entries as desired.
TSQR implementation configuration options are stored under "TsqrImpl" as an RCP<const ParameterList>. (Don't call sublist() to get them; call get().)
Warning:
This method is not reentrant. It should only be called by one thread at a time.

Definition at line 1387 of file BelosTsqrOrthoManagerImpl.hpp.

template<class Scalar , class MV >
Teuchos::RCP< const Teuchos::ParameterList > Belos::TsqrOrthoManagerImpl< Scalar, MV >::getFastParameters ( ) [static]

Get "fast" parameters for TsqrOrthoManagerImpl.

Get a (pointer to a) list of parameters for configuring a TsqrOrthoManager or TsqrMatOrthoManager instance for maximum speed, at the cost of accuracy (no block reorthogonalization) and robustness to rank deficiency (no randomization of the null space basis).

Note:
TSQR implementation configuration options are stored under "TsqrImpl" as an RCP<const ParameterList>. (Don't call sublist() to get them; call get().)
Warning:
This method is not reentrant. It should only be called by one thread at a time.

Definition at line 1445 of file BelosTsqrOrthoManagerImpl.hpp.

template<class Scalar , class MV >
void Belos::TsqrOrthoManagerImpl< Scalar, MV >::setLabel ( const std::string &  label) [inline]

Set the label for timers (if timers are enabled)

Definition at line 205 of file BelosTsqrOrthoManagerImpl.hpp.

template<class Scalar , class MV >
const std::string& Belos::TsqrOrthoManagerImpl< Scalar, MV >::getLabel ( ) [inline]

Get the label for timers (if timers are enabled)

Definition at line 208 of file BelosTsqrOrthoManagerImpl.hpp.

template<class Scalar , class MV >
void Belos::TsqrOrthoManagerImpl< Scalar, MV >::innerProd ( const MV &  X,
const MV &  Y,
mat_type Z 
) const [inline]

Euclidean inner product.

Compute the Euclidean block inner product X^* Y, and store the result in Z.

Parameters:
X[in]
Y[in]
Z[out] On output, $X^* Y$

Definition at line 219 of file BelosTsqrOrthoManagerImpl.hpp.

template<class Scalar , class MV >
void Belos::TsqrOrthoManagerImpl< Scalar, MV >::norm ( const MV &  X,
std::vector< magnitude_type > &  normVec 
) const [inline]

Compute the 2-norm of each column j of X.

Parameters:
X[in] Multivector for which to compute column norms
normvec[out] On output: normvec[j] is the 2-norm of column j of X. normvec is resized if necessary so that it has at least as many entries as there are columns of X.
Note:
Performance of this method depends on how MultiVecTraits implements column norm computation for the given multivector type MV. It may or may not be the case that a reduction is performed for every column of X. Furthermore, whether or not the columns of X are contiguous (as opposed to a view of noncontiguous columns) may also affect performance. The computed results should be the same regardless, except perhaps for small rounding differences due to a different order of operations.

Definition at line 241 of file BelosTsqrOrthoManagerImpl.hpp.

template<class Scalar , class MV >
void Belos::TsqrOrthoManagerImpl< Scalar, MV >::project ( MV &  X,
Teuchos::Array< mat_ptr C,
Teuchos::ArrayView< Teuchos::RCP< const MV > >  Q 
)

Compute $C := Q^* X$ and $X := X - Q C$.

Project X against the span of the (Euclidean) orthogonal vectors Q, and store the resulting coefficients in C.

Parameters:
X[in/out] On input: the vectors to project. On output: $X := X - Q C$ where $C := Q^* X$.
C[out] The projection coefficients $C := Q^* X$
Q[in] The orthogonal basis against which to project

Definition at line 846 of file BelosTsqrOrthoManagerImpl.hpp.

template<class Scalar , class MV >
int Belos::TsqrOrthoManagerImpl< Scalar, MV >::normalize ( MV &  X,
mat_ptr  B 
)

Orthogonalize the columns of X in place.

Orthogonalize the columns of X in place, storing the resulting coefficients in B. Return the rank of X. If X is full rank, then X*B on output is a QR factorization of X on input. If X is not full rank, then the first rank columns of X on output form a basis for the column space of X (on input). Additional options control randomization of the null space basis.

Parameters:
X[in/out]
B[out]
Returns:
Rank of X

Definition at line 927 of file BelosTsqrOrthoManagerImpl.hpp.

template<class Scalar , class MV >
int Belos::TsqrOrthoManagerImpl< Scalar, MV >::normalizeOutOfPlace ( MV &  X,
MV &  Q,
mat_ptr  B 
) [inline]

Normalize X into Q*B, overwriting X.

Normalize X into Q*B, overwriting X with invalid values.

Parameters:
X[in/out] Vector(s) to normalize
Q[out] Normalized vector(s)
B[out] Normalization coefficients
Returns:
Rank of X
Note:
Q must have at least as many columns as X. It may have more columns than X; those columns are ignored.
We expose this interface to applications because TSQR is not able to compute an orthogonal basis in place; it needs scratch space. Applications can exploit this interface to avoid excessive copying of vectors when using TSQR for orthogonalization.

Definition at line 299 of file BelosTsqrOrthoManagerImpl.hpp.

template<class Scalar , class MV >
int Belos::TsqrOrthoManagerImpl< Scalar, MV >::projectAndNormalize ( MV &  X,
Teuchos::Array< mat_ptr C,
mat_ptr  B,
Teuchos::ArrayView< Teuchos::RCP< const MV > >  Q 
) [inline]

Equivalent (in exact arithmetic) to project(X,C,Q) followed by normalize(X,B).

However, this method performs reorthogonalization more efficiently and accurately.

Parameters:
X[in/out] The vectors to project against Q and normalize
C[out] The projection coefficients
B[out] The normalization coefficients
Q[in] The orthogonal basis against which to project
Returns:
Rank of X after projection

Definition at line 341 of file BelosTsqrOrthoManagerImpl.hpp.

template<class Scalar , class MV >
int Belos::TsqrOrthoManagerImpl< Scalar, MV >::projectAndNormalizeOutOfPlace ( MV &  X_in,
MV &  X_out,
Teuchos::Array< mat_ptr C,
mat_ptr  B,
Teuchos::ArrayView< Teuchos::RCP< const MV > >  Q 
) [inline]

Project and normalize X_in into X_out; overwrite X_in.

Project X_in against Q, storing projection coefficients in C, and normalize X_in into X_out, storing normalization coefficients in B. On output, X_out has the resulting orthogonal vectors and X_in is overwritten with invalid values.

Parameters:
X_in[in/out] On input: The vectors to project against Q and normalize. On output: Overwritten with invalid values.
X_out[out] The normalized input vectors after projection against Q.
C[out] Projection coefficients
B[out] Normalization coefficients
Q[in] The orthogonal basis against which to project
Returns:
Rank of X_in after projection
Note:
We expose this interface to applications for the same reason that we expose normalizeOutOfPlace().

Definition at line 371 of file BelosTsqrOrthoManagerImpl.hpp.

template<class Scalar , class MV >
magnitude_type Belos::TsqrOrthoManagerImpl< Scalar, MV >::orthonormError ( const MV &  X) const [inline]

Return $ \| I - X^* \cdot X \|_F $.

Return the Frobenius norm of I - X^* X, which is an absolute measure of the orthogonality of the columns of X.

Definition at line 387 of file BelosTsqrOrthoManagerImpl.hpp.

template<class Scalar , class MV >
magnitude_type Belos::TsqrOrthoManagerImpl< Scalar, MV >::orthogError ( const MV &  X1,
const MV &  X2 
) const [inline]

Return the Frobenius norm of the inner product of X1 and X1.

Definition at line 400 of file BelosTsqrOrthoManagerImpl.hpp.

template<class Scalar , class MV >
magnitude_type Belos::TsqrOrthoManagerImpl< Scalar, MV >::blockReorthogThreshold ( ) const [inline]

Relative tolerance for triggering a block reorthogonalization.

If any column norm in a block decreases by this amount, then we reorthogonalize.

Definition at line 413 of file BelosTsqrOrthoManagerImpl.hpp.

template<class Scalar , class MV >
magnitude_type Belos::TsqrOrthoManagerImpl< Scalar, MV >::relativeRankTolerance ( ) const [inline]

Relative tolerance for determining (via the SVD) whether a block is of full numerical rank.

Definition at line 417 of file BelosTsqrOrthoManagerImpl.hpp.


The documentation for this class was generated from the following file:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines