AbstractLinAlgPack::MatrixLoadSparseElements Class Reference

Mix-in interface for loading nonzero elements into a sparse matrix data structure. More...

#include <AbstractLinAlgPack_MatrixLoadSparseElements.hpp>

Inheritance diagram for AbstractLinAlgPack::MatrixLoadSparseElements:

[legend]
List of all members.

Public Types

enum  EAssumeElementUniqueness { ELEMENTS_ASSUME_UNIQUE, ELEMENTS_ASSUME_DUPLICATES_SUM }
  More...

Public Member Functions

virtual void reinitialize (size_type rows, size_type cols, size_type max_nz, EAssumeElementUniqueness element_uniqueness=ELEMENTS_ASSUME_DUPLICATES_SUM)=0
 Resize the matrix and reserve space for nonzero elements to be added.
virtual void reset_to_load_values ()=0
 Reinitialize internal counter to load new nonzero values.
virtual void get_load_nonzeros_buffers (size_type max_nz_load, value_type **val, index_type **row_i, index_type **col_j)=0
 Get pointers to buffers to add nonzero elements.
virtual void commit_load_nonzeros_buffers (size_type nz_commit, value_type **val, index_type **row_i, index_type **col_j)=0
 Commit nonzeros in buffers obtained from get_load_nonzeros_buffers().
virtual void finish_construction (bool test_setup)=0
 To be called when the matrix construction is finally finished after all of the nonzero entries have been added.

Detailed Description

Mix-in interface for loading nonzero elements into a sparse matrix data structure.

The formats supported are:

Coordiante:


     Aval[k], Arow[k], Acol[k], k = 0..num_nonzeros(...)-1
 
Compressed Row (Column):

    Aval[k], Acol[k], k = 0..num_nonzeros(...)-1
    Arow_start[j], j = 0..rows()-1
 
This is meant to be the do-all interface for clients to use to add nonzero elements for sparse matrices.

ToDo: Discuss element uniqueness!

ToDo: Finish documentation!

Definition at line 58 of file AbstractLinAlgPack_MatrixLoadSparseElements.hpp.


Member Enumeration Documentation

enum AbstractLinAlgPack::MatrixLoadSparseElements::EAssumeElementUniqueness
 

Enumeration values:
ELEMENTS_ASSUME_UNIQUE  Entries assumed have unique row and column indexes (client must enforce this!).
ELEMENTS_ASSUME_DUPLICATES_SUM  Entries allowed with duplicate row and column indexes with the understanding that the values are summed.

Definition at line 64 of file AbstractLinAlgPack_MatrixLoadSparseElements.hpp.


Member Function Documentation

virtual void AbstractLinAlgPack::MatrixLoadSparseElements::reinitialize size_type  rows,
size_type  cols,
size_type  max_nz,
EAssumeElementUniqueness  element_uniqueness = ELEMENTS_ASSUME_DUPLICATES_SUM
[pure virtual]
 

Resize the matrix and reserve space for nonzero elements to be added.

All of the nonzeros in the current matrix are discarded and we start fresh.

ToDo: Finish documentation!

Implemented in AbstractLinAlgPack::MatrixSparseCOORSerial.

virtual void AbstractLinAlgPack::MatrixLoadSparseElements::reset_to_load_values  )  [pure virtual]
 

Reinitialize internal counter to load new nonzero values.

The row and column index arrays are preserved from the last setup and here the client only wants to set the nonzero values for the same matrix structure.

ToDo: Finish documentation!

Implemented in AbstractLinAlgPack::MatrixSparseCOORSerial.

virtual void AbstractLinAlgPack::MatrixLoadSparseElements::get_load_nonzeros_buffers size_type  max_nz_load,
value_type **  val,
index_type **  row_i,
index_type **  col_j
[pure virtual]
 

Get pointers to buffers to add nonzero elements.

Parameters:
max_nz_load [in] Maximum number of nonzero elements that will be set in the returned buffers. If reset_to_load_values()
val [out] On output *val is set to a pointer to an contiguous array of memory of at least max_nz_load entries for which the values of the nonzero elements to add are to be set.
row_i [out] On output *row_i is set to a pointer to an contiguous array of memory of at least max_nz_load entries for which the row indexes of the nonzero elements to add are to be set. If row_i == NULL then no buffer is allocated for the row indexes.
col_j [out] On output *col_J is set to a pointer to an contiguous array of memory of at least max_nz_load entries for which the column indexes of the nonzero elements to add are to be set. If col_j == NULL then no buffer is allocated for the column indexes.
Preconditions:
  • If reset_to_load_values() was called to setup nonzero elements, then row_i and col_j must be NULL or a std::logic_error exception is thrown.

After entries in the arrays (*val)[], (*row_i)[] and (*col_j)[] are set, the client must call this->commit_load_nonzeros_buffers() to commit the nonzero entries that are set in these buffers.

Implemented in AbstractLinAlgPack::MatrixSparseCOORSerial.

virtual void AbstractLinAlgPack::MatrixLoadSparseElements::commit_load_nonzeros_buffers size_type  nz_commit,
value_type **  val,
index_type **  row_i,
index_type **  col_j
[pure virtual]
 

Commit nonzeros in buffers obtained from get_load_nonzeros_buffers().

Parameters:
nz_commit [in] Number of nonzero elements to be loaded fron the buffers. Note that nz_commit <= max_nz_load on the previous call to get_load_nonzeros_buffers().
val [in/out] On input (*val)[] contains an array of nz_commit value entries for nonzero elements to load. This must point to the same buffer returned from the last call to get_load_nonzero_buffers(). On output *val is set to NULL>
row_i [in/out] On input (*row_i)[] contains an array of nz_commit row index entries for nonzero elements to load. This must point to the same buffer returned from the last call to get_load_nonzero_buffers(). If row_i == NULL then no row indexes are set. Here it is assumed that the row indexes from a previous load have already been set. On output *row_i is set to NULL>
col_j [in/out] On input (*col_j)[] contains an array of nz_commit column index entries for nonzero elements to load. This must point to the same buffer returned from the last call to get_load_nonzero_buffers(). If col_J == NULL then no column indexes are set. Here it is assumed that the column indexes from a previous load have already been set. On output *col_j is set to NULL>
Preconditions:
  • If reset_to_load_values() was called to setup nonzero elements, then row_i and col_j must be NULL or a std::logic_error exception is thrown.

ToDo: Finish documentation!

Implemented in AbstractLinAlgPack::MatrixSparseCOORSerial.

virtual void AbstractLinAlgPack::MatrixLoadSparseElements::finish_construction bool  test_setup  )  [pure virtual]
 

To be called when the matrix construction is finally finished after all of the nonzero entries have been added.

If reset_to_load_values() was called to initialize this set of loads then the number of nonzeros added must be exactly the same as the original load or an std::logic_error will be thrown with an appropriate error message.

Parameters:
test_setup [in] If true, then the setup will be checked (ToDo: elaborate)
Postconditions:

Implemented in AbstractLinAlgPack::MatrixSparseCOORSerial.


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