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

#include <AbstractLinAlgPack_MatrixLoadSparseElements.hpp>

Inheritance diagram for AbstractLinAlgPack::MatrixLoadSparseElements:

Public Types
enum	EAssumeElementUniqueness { ELEMENTS_ASSUME_UNIQUE, ELEMENTS_ASSUME_DUPLICATES_SUM }

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. More...

virtual void	reset_to_load_values ()=0
	Reinitialize internal counter to load new nonzero values. More...

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. More...

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()`. More...

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. More...

Public Member Functions inherited from AbstractLinAlgPack::MatrixBase
virtual	~MatrixBase ()
	Virtual destructor. More...

virtual const VectorSpace &	space_cols () const =0
	Vector space for vectors that are compatible with the columns of the matrix. More...

virtual const VectorSpace &	space_rows () const =0
	Vector space for vectors that are compatible with the rows of the matrix. More...

virtual size_type	rows () const
	Return the number of rows in the matrix. More...

virtual size_type	cols () const
	Return the number of columns in the matrix. More...

virtual size_type	nz () const
	Return the number of nonzero elements in the matrix. More...

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 71 of file AbstractLinAlgPack_MatrixLoadSparseElements.hpp.

Member Enumeration Documentation

enum AbstractLinAlgPack::MatrixLoadSparseElements::EAssumeElementUniqueness

Enumerator
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 77 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:

this->nz() returns the sum of all of nz_commit in all previous calls to commit_load_nonzeros_buffers() since the last call to reinitialize().

Implemented in AbstractLinAlgPack::MatrixSparseCOORSerial.

The documentation for this class was generated from the following file:

AbstractLinAlgPack_MatrixLoadSparseElements.hpp

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

Member Function Documentation