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:


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 betaop(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 alphaop(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 alphaop(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 alphaop(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::RCP< 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!
Classes
struct	SubMatrixEntry
	Matrix list entry for a sub-matrix. More...
struct	SubVectorEntry
	Vector list entry for a sub-vector. More...

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::RCP< 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:

this->vectors_begin() == this->vectors_end()
this->matrices_begin() == this->matrices_end()

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:

this->vectors_begin() != this->vectors_end()
this->vectors_begin() <= itr && itr < this->vectors_end()

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:

this->matrices_begin() != this->matrices_end()
this->matrices_begin() <= itr && itr < this->matrices_end()

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 Wed May 12 21:50:51 2010 for AbstractLinAlgPack: C++ Interfaces For Vectors, Matrices And Related Linear Algebra Objects by

1.4.7

AbstractLinAlgPack::MatrixComposite Class Reference

Constructors, initializers

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

Overridden from MatrixBase

Overridden from MatrixOp

Public Types

Classes

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation