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

AbstractLinAlgPack::GenPermMatrixSlice Class Reference

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

#include <AbstractLinAlgPack_GenPermMatrixSlice.hpp>

List of all members.

Public types

typedef GenPermMatrixSliceIteratorPack::EOrderedBy EOrderedBy
 
typedef GenPermMatrixSliceIteratorPack::row_col_iterator<
const index_type > 		const_iterator
 
typedef ptrdiff_t difference_type
 
enum  EIdentityOrZero
  More...

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.
const_iterator end () const
 Return the end of this->const_iterator_begin().

Public Member Functions

 GenPermMatrixSlice ()
 Construct to an uninitialzied, unsized matrix.
 GenPermMatrixSlice (index_type rows, index_type cols, EIdentityOrZero type)
 Construct to a matrix intialized to identity or zero (see initialize(,,,)).
void initialize (index_type rows, index_type cols, EIdentityOrZero type)
 Initialize an identity or zero permutation.
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.
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.
void bind (const GenPermMatrixSlice &gpms)
 Bind the view of another GenPermMatrixSlice object.
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.
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.
const GenPermMatrixSlice create_submatrix (const Range1D &rng, EOrderedBy ordered_by) const
 Create a submatrix by row, by column.

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 52 of file AbstractLinAlgPack_GenPermMatrixSlice.hpp.

Member Typedef Documentation

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

Definition at line 62 of file AbstractLinAlgPack_GenPermMatrixSlice.hpp.

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

Definition at line 66 of file AbstractLinAlgPack_GenPermMatrixSlice.hpp.

typedef ptrdiff_t AbstractLinAlgPack::GenPermMatrixSlice::difference_type
 

Definition at line 68 of file AbstractLinAlgPack_GenPermMatrixSlice.hpp.

Member Enumeration Documentation

enum AbstractLinAlgPack::GenPermMatrixSlice::EIdentityOrZero
 

Definition at line 59 of file AbstractLinAlgPack_GenPermMatrixSlice.hpp.

Constructor & Destructor Documentation

AbstractLinAlgPack::GenPermMatrixSlice::GenPermMatrixSlice (   ) 
 

Construct to an uninitialzied, unsized matrix.

Definition at line 129 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 351 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:

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.

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.

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 238 of file AbstractLinAlgPack_GenPermMatrixSlice.cpp.

index_type AbstractLinAlgPack::GenPermMatrixSlice::rows (   )  const [inline]
 

Definition at line 357 of file AbstractLinAlgPack_GenPermMatrixSlice.hpp.

index_type AbstractLinAlgPack::GenPermMatrixSlice::cols (   )  const [inline]
 

Definition at line 363 of file AbstractLinAlgPack_GenPermMatrixSlice.hpp.

index_type AbstractLinAlgPack::GenPermMatrixSlice::nz (   )  const [inline]
 

Definition at line 369 of file AbstractLinAlgPack_GenPermMatrixSlice.hpp.

GenPermMatrixSlice::EOrderedBy AbstractLinAlgPack::GenPermMatrixSlice::ordered_by (   )  const [inline]
 

Definition at line 381 of file AbstractLinAlgPack_GenPermMatrixSlice.hpp.

bool AbstractLinAlgPack::GenPermMatrixSlice::is_identity (   )  const [inline]
 

Definition at line 375 of file AbstractLinAlgPack_GenPermMatrixSlice.hpp.

index_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

index_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

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:

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 285 of file AbstractLinAlgPack_GenPermMatrixSlice.cpp.

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

Return the end of this->const_iterator_begin().

Definition at line 291 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 297 of file AbstractLinAlgPack_GenPermMatrixSlice.cpp.

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