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 { IDENTITY_MATRIX, ZERO_MATRIX }
  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.

Private Member Functions

void validate_not_identity () const
 
GenPermMatrixSliceoperator= (const GenPermMatrixSlice &)
 not defined and not to be called

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_typerow_i_
const index_typecol_j_


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

Enumerator:
IDENTITY_MATRIX 
ZERO_MATRIX 

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:

Postconditions:

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:

Postconditions:

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.

static 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 
) [static, private]

void AbstractLinAlgPack::GenPermMatrixSlice::validate_not_identity (  )  const [private]

Definition at line 457 of file AbstractLinAlgPack_GenPermMatrixSlice.cpp.

GenPermMatrixSlice& AbstractLinAlgPack::GenPermMatrixSlice::operator= ( const GenPermMatrixSlice  )  [private]

not defined and not to be called


Member Data Documentation

index_type AbstractLinAlgPack::GenPermMatrixSlice::rows_ [private]

Definition at line 301 of file AbstractLinAlgPack_GenPermMatrixSlice.hpp.

index_type AbstractLinAlgPack::GenPermMatrixSlice::cols_ [private]

Definition at line 302 of file AbstractLinAlgPack_GenPermMatrixSlice.hpp.

index_type AbstractLinAlgPack::GenPermMatrixSlice::nz_ [private]

Definition at line 303 of file AbstractLinAlgPack_GenPermMatrixSlice.hpp.

difference_type AbstractLinAlgPack::GenPermMatrixSlice::row_off_ [private]

Definition at line 304 of file AbstractLinAlgPack_GenPermMatrixSlice.hpp.

difference_type AbstractLinAlgPack::GenPermMatrixSlice::col_off_ [private]

Definition at line 305 of file AbstractLinAlgPack_GenPermMatrixSlice.hpp.

EOrderedBy AbstractLinAlgPack::GenPermMatrixSlice::ordered_by_ [private]

Definition at line 306 of file AbstractLinAlgPack_GenPermMatrixSlice.hpp.

const index_type* AbstractLinAlgPack::GenPermMatrixSlice::row_i_ [private]

Definition at line 307 of file AbstractLinAlgPack_GenPermMatrixSlice.hpp.

const index_type* AbstractLinAlgPack::GenPermMatrixSlice::col_j_ [private]

Definition at line 308 of file AbstractLinAlgPack_GenPermMatrixSlice.hpp.


The documentation for this class was generated from the following files:
Generated on Wed May 12 21:56:59 2010 for MOOCHO (Single Doxygen Collection) by  doxygen 1.4.7