Concrete matrix type to represent general permutation (mapping) matrices. More...

#include <AbstractLinAlgPack_GenPermMatrixSlice.hpp>

Public Member Functions
	GenPermMatrixSlice ()
	Construct to an uninitialzied, unsized matrix. More...

	GenPermMatrixSlice (index_type rows, index_type cols, EIdentityOrZero type)
	Construct to a matrix intialized to identity or zero (see initialize(,,,)). More...

void	initialize (index_type rows, index_type cols, EIdentityOrZero type)
	Initialize an identity or zero permutation. More...

void	initialize (index_type rows, index_type cols, index_type nz, difference_type row_off, difference_type col_off, EOrderedBy ordered_by, const index_type row_i[], const index_type col_j[], bool test_setup=false)
	Initialize. More...

void	initialize_and_sort (index_type rows, index_type cols, index_type nz, difference_type row_off, difference_type col_off, EOrderedBy ordered_by, index_type row_i[], index_type col_j[], bool test_setup=false)
	Initialize and sort. More...

void	bind (const GenPermMatrixSlice &gpms)
	Bind the view of another GenPermMatrixSlice object. More...

index_type	rows () const

index_type	cols () const

index_type	nz () const

EOrderedBy	ordered_by () const

bool	is_identity () const

index_type	lookup_row_i (index_type col_j) const
	Lookup the ith row index for the nonzero entry in the jth column if it exists. More...

index_type	lookup_col_j (index_type row_i) const
	Lookup the jth column index for the nonzero entry in the ith row if it exists. More...

const GenPermMatrixSlice	create_submatrix (const Range1D &rng, EOrderedBy ordered_by) const
	Create a submatrix by row, by column. More...

Private Member Functions
void	validate_not_identity () const

GenPermMatrixSlice &	operator= (const GenPermMatrixSlice &)
	not defined and not to be called More...

Static Private Member Functions
static void	validate_input_data (index_type rows, index_type cols, index_type nz, difference_type row_off, difference_type col_off, EOrderedBy ordered_by, const index_type row_i[], const index_type col_j[], std::ostringstream &omsg)

Private Attributes
index_type	rows_

index_type	cols_

index_type	nz_

difference_type	row_off_

difference_type	col_off_

EOrderedBy	ordered_by_

const index_type *	row_i_

const index_type *	col_j_

Public types
enum	EIdentityOrZero { IDENTITY_MATRIX, ZERO_MATRIX }

typedef GenPermMatrixSliceIteratorPack::EOrderedBy	EOrderedBy

typedef GenPermMatrixSliceIteratorPack::row_col_iterator < const index_type >	const_iterator

typedef ptrdiff_t	difference_type

Iterator Access.
const_iterator	begin () const
	Return a random access iterator for accessing which row and column that each nonzero 1.0 entry is located at. More...

const_iterator	end () const
	Return the end of `this->const_iterator_begin()`. More...

Detailed Description

Concrete matrix type to represent general permutation (mapping) matrices.

These are matrices who's rows or columns represent eta vectors (i.e. only one nonzero element with the value 1). These matrices can be rectangular and have one or more zero rows & columns. Therefore, these matrices can be used to represent gathering and scattering operations on other vectors and matrices.

This is only a view type. The client specifies the mapping arrays and then this class provides a clean encapsulation for the mapping. Objects of this type can also represent the identity matrix which is constructed with the initialize_identity(...) function.

The default copy constructor is allowd but the default assignment operator function is not.

Definition at line 65 of file AbstractLinAlgPack_GenPermMatrixSlice.hpp.

Member Typedef Documentation

typedef GenPermMatrixSliceIteratorPack::EOrderedBy AbstractLinAlgPack::GenPermMatrixSlice::EOrderedBy

Definition at line 75 of file AbstractLinAlgPack_GenPermMatrixSlice.hpp.

typedef GenPermMatrixSliceIteratorPack::row_col_iterator<const index_type> AbstractLinAlgPack::GenPermMatrixSlice::const_iterator

Definition at line 79 of file AbstractLinAlgPack_GenPermMatrixSlice.hpp.

typedef ptrdiff_t AbstractLinAlgPack::GenPermMatrixSlice::difference_type

Definition at line 81 of file AbstractLinAlgPack_GenPermMatrixSlice.hpp.

Member Enumeration Documentation

enum AbstractLinAlgPack::GenPermMatrixSlice::EIdentityOrZero

Enumerator
IDENTITY_MATRIX
ZERO_MATRIX

Definition at line 72 of file AbstractLinAlgPack_GenPermMatrixSlice.hpp.

Constructor & Destructor Documentation

AbstractLinAlgPack::GenPermMatrixSlice::GenPermMatrixSlice ( )

Construct to an uninitialzied, unsized matrix.

Definition at line 142 of file AbstractLinAlgPack_GenPermMatrixSlice.cpp.

AbstractLinAlgPack::GenPermMatrixSlice::GenPermMatrixSlice	(	index_type	rows,
		index_type	cols,
		EIdentityOrZero	type
	)

inline

Construct to a matrix intialized to identity or zero (see initialize(,,,)).

Definition at line 364 of file AbstractLinAlgPack_GenPermMatrixSlice.hpp.

Member Function Documentation

void AbstractLinAlgPack::GenPermMatrixSlice::initialize	(	index_type	rows,
		index_type	cols,
		EIdentityOrZero	type
	)

Initialize an identity or zero permutation.

If type == IDENTITY_MATRIX then after this function is called this will represent Q = [ I; 0 ] if rows > cols or Q = [ I, 0 ] if rows < cols or Q = I if rows == cols. If type == ZERO_MATRIX] then this will represent a rows x cols zero matrix.

Postconditions:

this->rows() == rows
this->cols() == cols
[type == IDENTITY_MATRIX] this->nz() == min(rows,cols)
[type == ZERO_MATRIX] this->nz() == 0
[type == IDENTITY_MATRIX] this->is_identity() == true
[type == ZERO_MATRIX] this->is_identity() == false
this->ordered_by() == BY_ROW_AND_COL

Definition at line 146 of file AbstractLinAlgPack_GenPermMatrixSlice.cpp.

void AbstractLinAlgPack::GenPermMatrixSlice::initialize	(	index_type	rows,
		index_type	cols,
		index_type	nz,
		difference_type	row_off,
		difference_type	col_off,
		EOrderedBy	ordered_by,
		const index_type	row_i[],
		const index_type	col_j[],
		bool	test_setup = `false`
	)

Initialize.

Parameters

rows	[in] Number of rows in matrix
cols	[in] Number of columns in matrix
nz	[in] Number of nonzero elements in the matrix
row_off	[in] Row offsets for row_i[]
col_off	[in] Column offsets for col_i[]
ordered_by	[in] The ordering of the nonzero elements
row_i	[in] Array (size nz): If nz == 0 then row_i can be NULL
col_j	[in] Array (size nz): If nz == 0 then col_j can be NULL
test_setup	[in] If true then all of the preconditions for the input arguments will be checked.

This function sets up general permutation view. The client must setup the arrays row_i[] and col_j[] to define the mapping. If nz == 0 then row_i and col_j can be NULL. Otherwise, row_i != NULL and col_j != NULL. If nz > 0 and ordered_by == BY_ROW then row_i[k] must be sorted in assending order else if ordered_by == BY_COL or col_j[k] must be sorted in assnding order else if ordered_by == UNORDERED then no ordering for row_i[k] or col_j[k] is required. If nz == 1 then the value of ordered_by is not really significant at it is ordered by row and by column.

It is required that if nz > 0 then: 1 <= row_i[k] + row_off <= rows, for k = 1...nz 1 <= col_j[k] + col_off <= cols, for k = 1...nz

All of these preconditions will be checked if test_setup == true.

After setup, the memory pointed to by row_i[] and col_j[] must not be altered since this object does not make an independent copy of this data.

After construction the nonzero elements of this matrix are: M(row_i[k]+row_off,col_j[k]+col_off) = 1.0, for k = 1...nz.

Definition at line 158 of file AbstractLinAlgPack_GenPermMatrixSlice.cpp.

void AbstractLinAlgPack::GenPermMatrixSlice::initialize_and_sort	(	index_type	rows,
		index_type	cols,
		index_type	nz,
		difference_type	row_off,
		difference_type	col_off,
		EOrderedBy	ordered_by,
		index_type	row_i[],
		index_type	col_j[],
		bool	test_setup = `false`
	)

Initialize and sort.

This is the same as the initialize(...) function except that this function will actually sort the entries by row or by column or not at all..

ToDo: Finish documentation.

Parameters

rows	[in] Number of rows in matrix
cols	[in] Number of columns in matrix
nz	[in] Number of nonzero elements in the matrix
row_off	[in] Row offsets for row_i[]
col_off	[in] Column offsets for col_i[]
ordered_by	[in] The ordering of the nonzero elements
row_i	[in/out] Array (size nz): If nz == 0 then row_i can be NULL. On output it will be sorted according to ordered_by
col_j	[in/out] Array (size nz): If nz == 0 then col_j can be NULL. On output it will be sorted according to ordered_by
test_setup	[in] If true then all of the preconditions for the input arguments will be checked.

Definition at line 211 of file AbstractLinAlgPack_GenPermMatrixSlice.cpp.

void AbstractLinAlgPack::GenPermMatrixSlice::bind ( const GenPermMatrixSlice & gpms )

Bind the view of another GenPermMatrixSlice object.

After construction these objects will share points to the same row_i[] and col_j[] arrays.

Definition at line 251 of file AbstractLinAlgPack_GenPermMatrixSlice.cpp.

index_type AbstractLinAlgPack::GenPermMatrixSlice::rows ( ) const

inline

Definition at line 370 of file AbstractLinAlgPack_GenPermMatrixSlice.hpp.

index_type AbstractLinAlgPack::GenPermMatrixSlice::cols ( ) const

inline

Definition at line 376 of file AbstractLinAlgPack_GenPermMatrixSlice.hpp.

index_type AbstractLinAlgPack::GenPermMatrixSlice::nz ( ) const

inline

Definition at line 382 of file AbstractLinAlgPack_GenPermMatrixSlice.hpp.

GenPermMatrixSlice::EOrderedBy AbstractLinAlgPack::GenPermMatrixSlice::ordered_by ( ) const

inline

Definition at line 394 of file AbstractLinAlgPack_GenPermMatrixSlice.hpp.

bool AbstractLinAlgPack::GenPermMatrixSlice::is_identity ( ) const

inline

Definition at line 388 of file AbstractLinAlgPack_GenPermMatrixSlice.hpp.

size_type AbstractLinAlgPack::GenPermMatrixSlice::lookup_row_i ( index_type col_j ) const

Lookup the ith row index for the nonzero entry in the jth column if it exists.

This function will return 0 if the index is not found. If this->ordered_by() == BY_COL || this->ordered_by() == BY_ROW_AND_COL then this function will be executed in O(log(this->nz())) time. Otherwise it will execute in O(this->nz()) time.

Preconditions:

(1 <= col_j && col_j <= this->cols()) (throw std::out_of_range)

Postconditions:

(1 <= return && return <= this->rows()) || return == 0

Definition at line 258 of file AbstractLinAlgPack_GenPermMatrixSlice.cpp.

size_type AbstractLinAlgPack::GenPermMatrixSlice::lookup_col_j ( index_type row_i ) const

Lookup the jth column index for the nonzero entry in the ith row if it exists.

This function will return 0 if the index is not found. If this->ordered_by() == BY_ROW || this->ordered_by() == BY_ROW_AND_COL then this function will be executed in O(log(this->nz())) time. Otherwise it will execute in O(this->nz()) time.

Preconditions:

(1 <= row_i && row_i <= this->rows()) (throw std::out_of_range)

Postconditions:

(1 <= return && return <= this->cols()) || return == 0

Definition at line 278 of file AbstractLinAlgPack_GenPermMatrixSlice.cpp.

GenPermMatrixSlice::const_iterator AbstractLinAlgPack::GenPermMatrixSlice::begin ( ) const

Return a random access iterator for accessing which row and column that each nonzero 1.0 entry is located at.

Preconditions:

this->is_identity() == false (throw ???)

If this->is_identity() == true then these iterators are obvoisly unneccesary and will throw exceptions.

for( GenPermMatrixSlice::const_iterator itr = gpms.begin(); itr != gpms.end(); ++itr )
{
    std::cout << "row_i = " << itr->row_i();
    std::cout << "col_j = " << itr->col_j();
}

You can also take a difference between iterators.

Definition at line 298 of file AbstractLinAlgPack_GenPermMatrixSlice.cpp.

GenPermMatrixSlice::const_iterator AbstractLinAlgPack::GenPermMatrixSlice::end ( ) const

Return the end of this->const_iterator_begin().

Definition at line 304 of file AbstractLinAlgPack_GenPermMatrixSlice.cpp.

const GenPermMatrixSlice AbstractLinAlgPack::GenPermMatrixSlice::create_submatrix	(	const Range1D &	rng,
		EOrderedBy	ordered_by
	)		const

Create a submatrix by row, by column.

If nz > 1 and this->ordered_by() == BY_ROW then ordered_by must also equal BY_ROW or if this->ordered_by() == BY_COL then ordered_by must also equal BY_COL or an std::logic_error exception will be thrown. If nz == 1, then obviously the nozeros are ordered by row and by column. This function should not be called if this->is_identity() == true.

The argument rng must be explicitly sized (rng.full_range() != true) or the exception std::logic_error will be thrown. Also, the range argument must obey rng.lbound() >= 1, and rng.ubound() <= this->rows() if ordered_by == BY_ROW and rng.ubound() <= this->cols() if ordered_by == BY_COL. The argument ordered_by == UNORDERED is not allowed and this function can not be called if this->ordered_by() == UNORDERED. This operation just does not make any sense.

The returned submatrix will contain all the entries for the designated rows if ordered_by == BY_ROW or columns if ordered_by == BY_CO.

ToDo: Spell out the behavior of this operation more carefully.

Definition at line 310 of file AbstractLinAlgPack_GenPermMatrixSlice.cpp.

void AbstractLinAlgPack::GenPermMatrixSlice::validate_input_data	(	index_type	rows,
		index_type	cols,
		index_type	nz,
		difference_type	row_off,
		difference_type	col_off,
		EOrderedBy	ordered_by,
		const index_type	row_i[],
		const index_type	col_j[],
		std::ostringstream &	omsg
	)