Main Page | Modules | Class Hierarchy | Alphabetical List | Class List | File List | Class Members | Search for 

AbstractLinAlgPack::MatrixComposite Class Reference

Matrix class for matrices composed out of a set of other matrices and vectors. More...

#include <AbstractLinAlgPack_MatrixComposite.hpp>

Inheritance diagram for AbstractLinAlgPack::MatrixComposite:

[legend]
List of all members.

Constructors, initializers

 MatrixComposite (size_type rows=0, size_type cols=0)
 Construct.
void reinitialize (size_type rows=0, size_type cols=0)
 Initialize a sized (on unsized) zero matrix to start with.
void add_vector (size_type row_offset, size_type col_offset, value_type beta, const GenPermMatrixSlice *G, const release_resource_ptr_t &G_release, BLAS_Cpp::Transp G_trans, const Vector *v, const release_resource_ptr_t &v_release, BLAS_Cpp::Transp v_trans)
 Add a sub-vector beta*op(op(G)*v).
void add_vector (size_type row_offset, size_type col_offset, value_type beta, const Range1D &rng_G, const Vector *v, const release_resource_ptr_t &v_release, BLAS_Cpp::Transp v_trans)
 Add a sub-vector beta*op(v(rng_G)).
void add_vector (size_type row_offset, size_type col_offset, value_type beta, const Vector *v, const release_resource_ptr_t &v_release, BLAS_Cpp::Transp v_trans)
 Add a sub-vector beta*op(v).
void remove_vector (vector_list_t::iterator itr)
 Remove a sub-vector.
void add_matrix (size_type row_offset, size_type col_offset, value_type alpha, const GenPermMatrixSlice *P, const release_resource_ptr_t &P_release, BLAS_Cpp::Transp P_trans, const MatrixOp *A, const release_resource_ptr_t &A_release, BLAS_Cpp::Transp A_trans, const GenPermMatrixSlice *Q, const release_resource_ptr_t &Q_release, BLAS_Cpp::Transp Q_trans)
 Add a sub-matrix alpha*op(P)*op(A)*op(Q).
void add_matrix (size_type row_offset, size_type col_offset, value_type alpha, const Range1D &rng_P, const MatrixOp *A, const release_resource_ptr_t &A_release, BLAS_Cpp::Transp A_trans, const Range1D &rng_Q)
 Add a sub-matrix alpha*op(A)(rng_P,rng_Q).
void add_matrix (size_type row_offset, size_type col_offset, value_type alpha, const Range1D &rng_P, const MatrixOp *A, const release_resource_ptr_t &A_release, BLAS_Cpp::Transp A_trans, const GenPermMatrixSlice *Q, const release_resource_ptr_t &Q_release, BLAS_Cpp::Transp Q_trans)
 Add a sub-matrix alpha*op(A)(rng_P,:)*op(Q).
void add_matrix (size_type row_offset, size_type col_offset, value_type alpha, const GenPermMatrixSlice *P, const release_resource_ptr_t &P_release, BLAS_Cpp::Transp P_trans, const MatrixOp *A, const release_resource_ptr_t &A_release, BLAS_Cpp::Transp A_trans, const Range1D &rng_Q)
 Add a sub-matrix alpha*op(P)*op(A)(:,rng_Q).
void add_matrix (size_type row_offset, size_type col_offset, value_type alpha, const MatrixOp *A, const release_resource_ptr_t &A_release, BLAS_Cpp::Transp A_trans)
 Add a sub-matrix alpha*op(A).
void add_matrix (size_type row_offset, size_type col_offset, value_type alpha, const GenPermMatrixSlice *P, const release_resource_ptr_t &P_release, BLAS_Cpp::Transp P_trans)
 Add a general permutation sub-matrix alpha*op(P).
void remove_matrix (matrix_list_t::iterator itr)
 Remove a sub-matrix.
virtual void finish_construction (const VectorSpace::space_ptr_t &space_cols, const VectorSpace::space_ptr_t &space_rows)
 Call to finish the construction process.

Sub-vector, sub-matrix access (using iterators)

int num_vectors () const
 
vector_list_t::iterator vectors_begin ()
 
vector_list_t::iterator vectors_end ()
 
vector_list_t::const_iterator vectors_begin () const
 
vector_list_t::const_iterator vectors_end () const
 
int num_matrices () const
 
matrix_list_t::iterator matrices_begin ()
 
matrix_list_t::iterator matrices_end ()
 
matrix_list_t::const_iterator matrices_begin () const
 
matrix_list_t::const_iterator matrices_end () const
 

Overridden from MatrixBase

size_type rows () const
 
size_type cols () const
 
size_type nz () const
 

Overridden from MatrixOp

const VectorSpace & space_rows () const
 
const VectorSpace & space_cols () const
 
mat_ptr_t sub_view (const Range1D &row_rng, const Range1D &col_rng) const
 
void Vp_StMtV (VectorMutable *vs_lhs, value_type alpha, BLAS_Cpp::Transp trans_rhs1, const Vector &v_rhs2, value_type beta) const
 
void Vp_StMtV (VectorMutable *vs_lhs, value_type alpha, BLAS_Cpp::Transp trans_rhs1, const SpVectorSlice &sv_rhs2, value_type beta) const
 
void Vp_StPtMtV (VectorMutable *vs_lhs, value_type alpha, const GenPermMatrixSlice &P_rhs1, BLAS_Cpp::Transp P_rhs1_trans, BLAS_Cpp::Transp M_rhs2_trans, const Vector &v_rhs3, value_type beta) const
 
void Vp_StPtMtV (VectorMutable *vs_lhs, value_type alpha, const GenPermMatrixSlice &P_rhs1, BLAS_Cpp::Transp P_rhs1_trans, BLAS_Cpp::Transp M_rhs2_trans, const SpVectorSlice &sv_rhs3, value_type beta) const
 

Public Types

typedef Teuchos::RefCountPtr<
MemMngPack::ReleaseResource > 		release_resource_ptr_t
 
typedef std::deque< SubVectorEntry > vector_list_t
 Warning! This could be changed to some other STL container!
typedef std::deque< SubMatrixEntry > matrix_list_t
 Warning! This could be changed to some other STL container!

Detailed Description

Matrix class for matrices composed out of a set of other matrices and vectors.

This matrix object represents: 


 M =   sum( a(j) * E(rM(j)) * op(P(j))*op(A(j))*op(Q(j))*F(cM(j)), j=1..num_mats )
     + sum( b(k) * E(rV(k)) * op(op(G(k))*v(k)) * F(cV(k)), k=1..num_vecs )
where:
a(j) : Scalar for sub-matrix A(j)
P(j), Q(j) : GenPermMatrixSlice objects for sub-matrix A(j)
A(j) : MatrixOp object
b(k) : Scalar for the sub-vector v(k)
G(k) : GenPermMatrixSlice object for sub-vector v(k)
v(k) : Vector object
E(r) : An appropriatly sized matrix object that moves the first row of aggregate sub-matrix or sub-vector to row r in M.
F(c) : An appropriatly sized matrix object that moves the first column of aggregate sub-matrix or sub-vector to column c in M.

This formulation allows sub-matrices and sub-vectors to overlap. However, bacause of the need for the compatibility of the vector sub-spaces, the overlapped sub-matrices and sub-vectors may not be compatible and therefore the matrix will be invalid and not work. This can be checked for by this matrix subclass. As long as the sub-matrics and sub-vectors do not overlap, the resulting matrix object will be perfectly compatible.

In the above formulation is it possible for parts to be missing or replaced by simpler means. For example, a sub-matrix may forgo P(j) and Q(j) in which case they are replaced (implicitly) by the identity matrix. Or they can be replaced by Range1D objects so that op(P(j))*op(A(j))*op(Q(j))*F(cM(j)) becomes op(A(j))(rng_P(j),rng_Q(j)). Also, a sub-matrix may only be composed of only a general permulation matrix P(j) and forgo Q(j). Likewise a sub-vector entry can replace op(G(k)*v(k)) using a range as op(v(k)(rng_G(k))) or be a naked sub-vector op(v).

Before adding any sub-vectors or sub-matrices the method reinitialize() must be called to set the shape of the matrix. This will have the effect of wiping the matrix clean. Then the methods add_vector() and add_matrix() can be called to add the constituent sub-vectors and sub-matrices. There are different forms of these methods for the special cases described above.

After all of the sub-vectors and sub-matrices have been added using the methods add_vector and add_matrix() , the method finish_construction() must be called before this matrix object will become fully initialized and ready for use.

The cleanup for all of the matrix and vector objects is given to ReleaseResouce objects so this is a very flexible aggregate matrix class from many perspactives.

Access to the constituent sub-vectors and sub-matrices is given through STL iterators with the element types SubVectorEntry and SubMatrixEntry. The methods vectors_begin() and vectors_end() return the iterators for the list of sub-vectors while matrices_begin() and matrices_end() return the list of sub-matrices. Note that non-const iterators are returned (from non-const functions) as well as const iterators (from const functions). The client should not attempt to modify the elememnts returned from these non-const iterators. The reason that non-const iterators are returned is so that specific sub-vectors and sub-matrices can be removed by calling remove_vector() and remove_matrix(). If the client does modify any of the elements in any way or calls add_vector(), add_matrix(), remove_vector() or remove_matrix() at anytime, the current matrix is invalidated and finish_construction() must be called to update the composite matrix object.

Note that implementing the VectorSpace objects that are returned by space_rows() and space_cols() may be non-trivial. These methods return VectorSpaceBlocked objects. Therefore, in order for clients to use vectors with this matrix object, it must create vectors compatible with these vector space objects. This can be a little tricky but should be doable.

The method ::sub_view(row_rng,col_rng) will return the simplest object it can given the input row_rng, col_rng. For example if the input ranges correspond to whole, unique matrix, then that matrix will be returned and not some encapulation of that matrix.

Definition at line 113 of file AbstractLinAlgPack_MatrixComposite.hpp.

Member Typedef Documentation

typedef Teuchos::RefCountPtr< MemMngPack::ReleaseResource> AbstractLinAlgPack::MatrixComposite::release_resource_ptr_t
 

Definition at line 121 of file AbstractLinAlgPack_MatrixComposite.hpp.

typedef std::deque<SubVectorEntry> AbstractLinAlgPack::MatrixComposite::vector_list_t
 

Warning! This could be changed to some other STL container!

Definition at line 171 of file AbstractLinAlgPack_MatrixComposite.hpp.

typedef std::deque<SubMatrixEntry> AbstractLinAlgPack::MatrixComposite::matrix_list_t
 

Warning! This could be changed to some other STL container!

Definition at line 230 of file AbstractLinAlgPack_MatrixComposite.hpp.

Constructor & Destructor Documentation

AbstractLinAlgPack::MatrixComposite::MatrixComposite (  size_type  rows = 0,
size_type  cols = 0
) 
 

Construct.

Calls this->reinitalize().

Definition at line 243 of file AbstractLinAlgPack_MatrixComposite.cpp.

Member Function Documentation

void AbstractLinAlgPack::MatrixComposite::reinitialize (  size_type  rows = 0,
size_type  cols = 0
) 
 

Initialize a sized (on unsized) zero matrix to start with.

After calling this function the user can add the constituent matrices and vectors using the add_matrix() and add_vector() methods.

Postconditions:

Definition at line 248 of file AbstractLinAlgPack_MatrixComposite.cpp.

void AbstractLinAlgPack::MatrixComposite::add_vector (  size_type  row_offset,
size_type  col_offset,
value_type  beta,
const GenPermMatrixSlice *  G,
const release_resource_ptr_t &  G_release,
BLAS_Cpp::Transp  G_trans,
const Vector *  v,
const release_resource_ptr_t &  v_release,
BLAS_Cpp::Transp  v_trans
) 
 

Add a sub-vector beta*op(op(G)*v).

ToDo : Finish Documentation!

Definition at line 265 of file AbstractLinAlgPack_MatrixComposite.cpp.

void AbstractLinAlgPack::MatrixComposite::add_vector (  size_type  row_offset,
size_type  col_offset,
value_type  beta,
const Range1D &  rng_G,
const Vector *  v,
const release_resource_ptr_t &  v_release,
BLAS_Cpp::Transp  v_trans
) 
 

Add a sub-vector beta*op(v(rng_G)).

ToDo : Finish Documentation!

Definition at line 281 of file AbstractLinAlgPack_MatrixComposite.cpp.

void AbstractLinAlgPack::MatrixComposite::add_vector (  size_type  row_offset,
size_type  col_offset,
value_type  beta,
const Vector *  v,
const release_resource_ptr_t &  v_release,
BLAS_Cpp::Transp  v_trans
) 
 

Add a sub-vector beta*op(v).

ToDo : Finish Documentation!

Definition at line 295 of file AbstractLinAlgPack_MatrixComposite.cpp.

void AbstractLinAlgPack::MatrixComposite::remove_vector (  vector_list_t::iterator  itr  ) 
 

Remove a sub-vector.

Preconditions:

Definition at line 325 of file AbstractLinAlgPack_MatrixComposite.cpp.

void AbstractLinAlgPack::MatrixComposite::add_matrix (  size_type  row_offset,
size_type  col_offset,
value_type  alpha,
const GenPermMatrixSlice *  P,
const release_resource_ptr_t &  P_release,
BLAS_Cpp::Transp  P_trans,
const MatrixOp *  A,
const release_resource_ptr_t &  A_release,
BLAS_Cpp::Transp  A_trans,
const GenPermMatrixSlice *  Q,
const release_resource_ptr_t &  Q_release,
BLAS_Cpp::Transp  Q_trans
) 
 

Add a sub-matrix alpha*op(P)*op(A)*op(Q).

ToDo : Finish Documentation!

Definition at line 331 of file AbstractLinAlgPack_MatrixComposite.cpp.

void AbstractLinAlgPack::MatrixComposite::add_matrix (  size_type  row_offset,
size_type  col_offset,
value_type  alpha,
const Range1D &  rng_P,
const MatrixOp *  A,
const release_resource_ptr_t &  A_release,
BLAS_Cpp::Transp  A_trans,
const Range1D &  rng_Q
) 
 

Add a sub-matrix alpha*op(A)(rng_P,rng_Q).

ToDo : Finish Documentation!

Definition at line 384 of file AbstractLinAlgPack_MatrixComposite.cpp.

void AbstractLinAlgPack::MatrixComposite::add_matrix (  size_type  row_offset,
size_type  col_offset,
value_type  alpha,
const Range1D &  rng_P,
const MatrixOp *  A,
const release_resource_ptr_t &  A_release,
BLAS_Cpp::Transp  A_trans,
const GenPermMatrixSlice *  Q,
const release_resource_ptr_t &  Q_release,
BLAS_Cpp::Transp  Q_trans
) 
 

Add a sub-matrix alpha*op(A)(rng_P,:)*op(Q).

ToDo : Finish Documentation!

Definition at line 350 of file AbstractLinAlgPack_MatrixComposite.cpp.

void AbstractLinAlgPack::MatrixComposite::add_matrix (  size_type  row_offset,
size_type  col_offset,
value_type  alpha,
const GenPermMatrixSlice *  P,
const release_resource_ptr_t &  P_release,
BLAS_Cpp::Transp  P_trans,
const MatrixOp *  A,
const release_resource_ptr_t &  A_release,
BLAS_Cpp::Transp  A_trans,
const Range1D &  rng_Q
) 
 

Add a sub-matrix alpha*op(P)*op(A)(:,rng_Q).

ToDo : Finish Documentation!

Definition at line 367 of file AbstractLinAlgPack_MatrixComposite.cpp.

void AbstractLinAlgPack::MatrixComposite::add_matrix (  size_type  row_offset,
size_type  col_offset,
value_type  alpha,
const MatrixOp *  A,
const release_resource_ptr_t &  A_release,
BLAS_Cpp::Transp  A_trans
) 
 

Add a sub-matrix alpha*op(A).

ToDo : Finish Documentation!

Definition at line 447 of file AbstractLinAlgPack_MatrixComposite.cpp.

void AbstractLinAlgPack::MatrixComposite::add_matrix (  size_type  row_offset,
size_type  col_offset,
value_type  alpha,
const GenPermMatrixSlice *  P,
const release_resource_ptr_t &  P_release,
BLAS_Cpp::Transp  P_trans
) 
 

Add a general permutation sub-matrix alpha*op(P).

ToDo : Finish Documentation!

Definition at line 496 of file AbstractLinAlgPack_MatrixComposite.cpp.

void AbstractLinAlgPack::MatrixComposite::remove_matrix (  matrix_list_t::iterator  itr  ) 
 

Remove a sub-matrix.

Preconditions:

Definition at line 535 of file AbstractLinAlgPack_MatrixComposite.cpp.

void AbstractLinAlgPack::MatrixComposite::finish_construction (  const VectorSpace::space_ptr_t &  space_cols,
const VectorSpace::space_ptr_t &  space_rows
)  [virtual]
 

Call to finish the construction process.

This method must be called after all of the sub-vectors and sub-matrices have been added and before this matrix object can be used. This method will validate that the constructed matrix is valid. It is up to the client to pass in vector space objects (presumably of type VectorSpaceBlocked) that represent the rows and columns of this matrix. It would be very complicated for this matrix class to figure out how to construct these vector space objects in general.

Preconditions:

  • space_rows.get() != NULL (throw std::invalid_argument)
  • space_rows->dim() == cols where cols was passed to reinitialize() (throw std::invalid_argument).
  • space_cols.get() != NULL (throw std::invalid_argument)
  • space_cols->dim() == rows where rows was passed to reinitialize() (throw std::invalid_argument).

Parameters:
space_cols [in] Will represent the vector space returned by this->space_cols(). The vector space object will be owned by this and must be not be modified while this is in use. Of course, the sub-spaces from this vector space object must be compatible with the vector spaces for the constitient matrices and vectors that were added.
space_rows [in] Will represent the vector space returned by this->space_rows(). The vector space object will be owned by this and must be not be modified while this is in use. Of course, the sub-spaces from this vector space object must be compatible with the vector spaces for the constitient matrices and vectors that were added.

Definition at line 541 of file AbstractLinAlgPack_MatrixComposite.cpp.

int AbstractLinAlgPack::MatrixComposite::num_vectors (   )  const
 

Definition at line 568 of file AbstractLinAlgPack_MatrixComposite.cpp.

MatrixComposite::vector_list_t::iterator AbstractLinAlgPack::MatrixComposite::vectors_begin (   ) 
 

Definition at line 574 of file AbstractLinAlgPack_MatrixComposite.cpp.

MatrixComposite::vector_list_t::iterator AbstractLinAlgPack::MatrixComposite::vectors_end (   ) 
 

Definition at line 580 of file AbstractLinAlgPack_MatrixComposite.cpp.

MatrixComposite::vector_list_t::const_iterator AbstractLinAlgPack::MatrixComposite::vectors_begin (   )  const
 

Definition at line 586 of file AbstractLinAlgPack_MatrixComposite.cpp.

MatrixComposite::vector_list_t::const_iterator AbstractLinAlgPack::MatrixComposite::vectors_end (   )  const
 

Definition at line 592 of file AbstractLinAlgPack_MatrixComposite.cpp.

int AbstractLinAlgPack::MatrixComposite::num_matrices (   )  const
 

Definition at line 597 of file AbstractLinAlgPack_MatrixComposite.cpp.

MatrixComposite::matrix_list_t::iterator AbstractLinAlgPack::MatrixComposite::matrices_begin (   ) 
 

Definition at line 603 of file AbstractLinAlgPack_MatrixComposite.cpp.

MatrixComposite::matrix_list_t::iterator AbstractLinAlgPack::MatrixComposite::matrices_end (   ) 
 

Definition at line 609 of file AbstractLinAlgPack_MatrixComposite.cpp.

MatrixComposite::matrix_list_t::const_iterator AbstractLinAlgPack::MatrixComposite::matrices_begin (   )  const
 

Definition at line 615 of file AbstractLinAlgPack_MatrixComposite.cpp.

MatrixComposite::matrix_list_t::const_iterator AbstractLinAlgPack::MatrixComposite::matrices_end (   )  const
 

Definition at line 621 of file AbstractLinAlgPack_MatrixComposite.cpp.

size_type AbstractLinAlgPack::MatrixComposite::rows (   )  const [virtual]
 

Reimplemented from AbstractLinAlgPack::MatrixBase.

Definition at line 628 of file AbstractLinAlgPack_MatrixComposite.cpp.

size_type AbstractLinAlgPack::MatrixComposite::cols (   )  const [virtual]
 

Reimplemented from AbstractLinAlgPack::MatrixBase.

Definition at line 633 of file AbstractLinAlgPack_MatrixComposite.cpp.

size_type AbstractLinAlgPack::MatrixComposite::nz (   )  const [virtual]
 

Reimplemented from AbstractLinAlgPack::MatrixBase.

Definition at line 638 of file AbstractLinAlgPack_MatrixComposite.cpp.

const VectorSpace& AbstractLinAlgPack::MatrixComposite::space_rows (   )  const [virtual]
 

Implements AbstractLinAlgPack::MatrixBase.

const VectorSpace& AbstractLinAlgPack::MatrixComposite::space_cols (   )  const [virtual]
 

Implements AbstractLinAlgPack::MatrixBase.

MatrixOp::mat_ptr_t AbstractLinAlgPack::MatrixComposite::sub_view (  const Range1D &  row_rng,
const Range1D &  col_rng
)  const [virtual]
 

Reimplemented from AbstractLinAlgPack::MatrixOp.

Definition at line 672 of file AbstractLinAlgPack_MatrixComposite.cpp.

void AbstractLinAlgPack::MatrixComposite::Vp_StMtV (  VectorMutable *  vs_lhs,
value_type  alpha,
BLAS_Cpp::Transp  trans_rhs1,
const Vector &  v_rhs2,
value_type  beta
)  const [virtual]
 

Implements AbstractLinAlgPack::MatrixOp.

Definition at line 685 of file AbstractLinAlgPack_MatrixComposite.cpp.

void AbstractLinAlgPack::MatrixComposite::Vp_StMtV (  VectorMutable *  vs_lhs,
value_type  alpha,
BLAS_Cpp::Transp  trans_rhs1,
const SpVectorSlice &  sv_rhs2,
value_type  beta
)  const [virtual]
 

Reimplemented from AbstractLinAlgPack::MatrixOp.

Definition at line 698 of file AbstractLinAlgPack_MatrixComposite.cpp.

void AbstractLinAlgPack::MatrixComposite::Vp_StPtMtV (  VectorMutable *  vs_lhs,
value_type  alpha,
const GenPermMatrixSlice &  P_rhs1,
BLAS_Cpp::Transp  P_rhs1_trans,
BLAS_Cpp::Transp  M_rhs2_trans,
const Vector &  v_rhs3,
value_type  beta
)  const [virtual]
 

Reimplemented from AbstractLinAlgPack::MatrixOp.

Definition at line 711 of file AbstractLinAlgPack_MatrixComposite.cpp.

void AbstractLinAlgPack::MatrixComposite::Vp_StPtMtV (  VectorMutable *  vs_lhs,
value_type  alpha,
const GenPermMatrixSlice &  P_rhs1,
BLAS_Cpp::Transp  P_rhs1_trans,
BLAS_Cpp::Transp  M_rhs2_trans,
const SpVectorSlice &  sv_rhs3,
value_type  beta
)  const [virtual]
 

Reimplemented from AbstractLinAlgPack::MatrixOp.

Definition at line 725 of file AbstractLinAlgPack_MatrixComposite.cpp.

The documentation for this class was generated from the following files:
Generated on Thu Sep 18 12:33:54 2008 for AbstractLinAlgPack: C++ Interfaces For Vectors, Matrices And Related Linear Algebra Objects by doxygen 1.3.9.1