AbstractLinAlgPack::MatrixConvertToSparse Class Reference

Mix-in interface for extracing explicit elements from a sparse matrix in one of several Fortran compatible formats. More...

#include <AbstractLinAlgPack_MatrixConvertToSparse.hpp>

Inheritance diagram for AbstractLinAlgPack::MatrixConvertToSparse:

[legend]List of all members.


Public Types
enum	EExtractRegion { EXTRACT_FULL_MATRIX, EXTRACT_UPPER_TRIANGULAR, EXTRACT_LOWER_TRIANGULAR }
	More...
enum	EElementUniqueness { ELEMENTS_FORCE_UNIQUE, ELEMENTS_ALLOW_DUPLICATES_SUM }
	More...
Public Member Functions
virtual index_type	num_nonzeros (EExtractRegion extract_region, EElementUniqueness element_uniqueness) const =0
	Returns the number of nonzeros in the matrix.
virtual void	coor_extract_nonzeros (EExtractRegion extract_region, EElementUniqueness element_uniqueness, const index_type len_Aval, value_type Aval[], const index_type len_Aij, index_type Arow[], index_type Acol[], const index_type row_offset=0, const index_type col_offset=0) const =0
	Extract sparse elements in a coordinate data structure.

Detailed Description

Mix-in interface for extracing explicit elements from a sparse matrix in one of several Fortran compatible formats.

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 simplest interface for clients to use to extract nonzero elements from matrices.

The following matrix is used in the documentation for the following extraction functions.


    [	1.1				1.3		1.4	]	1
    [			2.2				2.4	]	2
  A =	[			3.2					]	3
    [	4.1				4.3		4.4	]	4
    [	5.1				5.3		5.4	]	5
        1		  2		  3		  4

Note that above, A has:

A_nz == this->num_nonzeros(EXTRACT_FULL_MATRIX,ELEMENTS_FORCE_UNIQUE) == 12
A_up_nz = this->num_nonzeros(EXTRACT_UPPER_TRIANGULAR,ELEMENTS_FORCE_UNIQUE) == 6
A_lo_nz = this->num_nonzeros(EXTRACT_LOWER_TRIANGULAR,ELEMENTS_FORCE_UNIQUE) == 9

Definition at line 75 of file AbstractLinAlgPack_MatrixConvertToSparse.hpp.

Member Enumeration Documentation

enum AbstractLinAlgPack::MatrixConvertToSparse::EExtractRegion

Enumeration values:

EXTRACT_FULL_MATRIX Extract the nonzero elements from the full matrix.

EXTRACT_UPPER_TRIANGULAR Extract the nonzero elements from the upper triangular region including the diagonal.

EXTRACT_LOWER_TRIANGULAR Extract the nonzero elements from the lower triangular region including the diagonal.

Definition at line 81 of file AbstractLinAlgPack_MatrixConvertToSparse.hpp.

enum AbstractLinAlgPack::MatrixConvertToSparse::EElementUniqueness

Enumeration values:

ELEMENTS_FORCE_UNIQUE Entries must have unique row and column indexes.

ELEMENTS_ALLOW_DUPLICATES_SUM Entries with duplicate row and column indexes are allowed with the understanding that the values are summed.

Definition at line 87 of file AbstractLinAlgPack_MatrixConvertToSparse.hpp.

Member Function Documentation

virtual index_type AbstractLinAlgPack::MatrixConvertToSparse::num_nonzeros ( EExtractRegion extract_region,

EElementUniqueness element_uniqueness

) const [pure virtual]

Returns the number of nonzeros in the matrix.

Parameters:

extract_region [in] Determines what matix region to extract:

EXTRACT_FULL_MATRIX: Extract the nonzero elements for the full matrix.

EXTRACT_UPPER_TRIANGULAR: Extract the nonzero elements for the upper triangular region (including the diagonal).

EXTRACT_LOWER_TRIANGULAR: Extract the nonzero elements for the lower triangular region (including the diagonal).

element_uniqueness [in] Determines if element row and column indexes must be unique.

ELEMENTS_FORCE_UNIQUE: The row and column indexes must be unique.

ELEMENTS_ALLOW_DUPLICATES_SUM: Entries with duplicate row and column indexes are allowed with the understanding that the values will be summed.

Implemented in AbstractLinAlgPack::MatrixConvertToSparseEncap, AbstractLinAlgPack::MatrixExtractSparseElements, and AbstractLinAlgPack::MatrixSymDiagSparse.

virtual void AbstractLinAlgPack::MatrixConvertToSparse::coor_extract_nonzeros ( EExtractRegion extract_region,

EElementUniqueness element_uniqueness,

const index_type len_Aval,

value_type Aval[],

const index_type len_Aij,

index_type Arow[],

index_type Acol[],

const index_type row_offset = 0,

const index_type col_offset = 0

) const [pure virtual]

Extract sparse elements in a coordinate data structure.
The client can extract the structure in Arow[] and Acol[] and/or the nonzero elements in Aval[]. If the client wants to extract the structure it sets\ len_Aij = this->num_nonzeros(extract_region,element_uniqueness) and then Arow[] and Acol[] are filled with the row and column indexes. If the client wants the nonzero values theit sets len_Aval = this->num_nonzeros(extract_region,element_uniqueness) and then Aval[] will be set on output.
The client can choose to extract the nonzeros for the full matrix (extract_region == EXTRACT_FULL_MATRIX) or the upper (extract_region == EXTRACT_UPPER_TRIANGULAR) or lower (extract_region == EXTRACT_LOWER_TRIANGULAR) triangular regions.
The client can force the extracted nonzero elements to have unique row and column indexes (element_uniqueness == ELEMENTS_FORCE_UNIQUE) or can allow elements with duplicate row and column indexes with the understanding that the values will be summed (element_uniqueness == ELEMENTS_ALLOW_DUPLICATES_SUM).

Parameters:

extract_region [in] Determines what matix region to extract:

EXTRACT_FULL_MATRIX: Extract the nonzero elements for the full matrix.

EXTRACT_UPPER_TRIANGULAR: Extract the nonzero elements for the upper triangular region (including the diagonal).

EXTRACT_LOWER_TRIANGULAR: Extract the nonzero elements for the lower triangular region (including the diagonal).

element_uniqueness [in] Determines if element row and column indexes must be unique.

ELEMENTS_FORCE_UNIQUE: The row and column indexes must be unique.

ELEMENTS_ALLOW_DUPLICATES_SUM: Entries with duplicate row and column indexes are allowed with the understanding that the values will be summed.

len_Aval [in] If the client wants to extract the nonzero values of the matrix in Avar[] then len_Aval must be set to the return value from this->num_nonzeros(extract_region) Otherwise len_Avar should be set to zero.

Aval [out] If len_Aval > 0 then Aval must point to the begining of an array of length len_Aval. If len_Aval == 0 then Aval must be NULL. On output, Aval[k] is the nonzero value of the kth nonzero element, for k = 0...len_Aval-1.

len_Aij [in] If the client wants to extract the structure of the matrix in Arow[] and Acol[] then this must be set to len_Aij = this->num_nonzeros(extract_region). Otherwise len_Aij should be set to zero.

Arow [out] If len_Aij > 0 then Arow must point to the begining of an array of length len_Aij. If len_Aij == 0 then Arow must be NULL. On output, Arow[k] is the row index of the kth nonzero element, for k = 0...len_Aij-1.

Acol [out] If len_Aij > 0 then Acol must point to the begining of an array of length len_Aij. If len_Aij == 0 then Acol must be NULL. On output, Acol[k] is the column index of the kth nonzero element, for k = 0...len_Aij-1.

row_offset [in] The row index in Arow[] are offset by +row_offset on output. To leave the first row index as 1 set row_offset = 0. This is to allow the client to place this matrix as a submatrix into a larger matrix stored in the coordinate format. Default value = 0.

col_offset [in] The column index in Acol[] are offset by +col_offset on output. To leave the first column index as 1 set col_offset = 0. This is to allow the client to place this matrix as a submatrix into a larger matrix stored in the coordinate format. Default value = 0.

Preconditions

[len_Aval != 0] len_Aval == this->num_nonzeros(etract_region,element_uniqueness) (throw std::invalid_argument).

[len_Aij != 0] len_Aij == this->num_nonzeros(etract_region,element_uniqueness) (throw std::invalid_argument).

[len_Aval == 0] Aval == NULL (throw std::invalid_argument).

[len_Aij == 0] Arow == NULL (throw std::invalid_argument).

[len_Aij == 0] Acol == NULL (throw std::invalid_argument).

To illustrate the behavior of this function consider the example matix A (shown above) in the following examples:
(1) To extract all of the nonzero elements and structure for the full matrix with the row and column indexes offset by 2 and 4 respectively the following input would yield the following output.
Input:
extract_region = EXTRACT_FULL_MATRIX element_uniqueness = ELEMENTS_FORCE_UNIQUE len_Aval = A_nz = 12 len_Aij = A_nz = 12 row_offset = 2 col_offset = 4
Output:
k Aval[k-1] Arow[k-1] Acol[k-1] - --------- --------- --------- 1 1.1 3 5 2 4.1 5 5 3 5.1 7 5 4 2.2 4 6 5 3.2 5 6 6 1.3 3 7 7 4.3 6 7 8 5.3 7 7 9 1.4 3 8 10 2.4 4 8 11 4.4 6 8 12 5.4 7 8
Note that in the example above that the elements are sorted by column but they do not have to be on output.
(2) To extract all of the nonzero elements and structure for the upper triangular region of the matrix with the row and column indexes offset by 0 and 0 respectively the following input would yield the following output.
Input:
extract_region = EXTRACT_UPPER_TRIANGULAR element_uniqueness = ELEMENTS_FORCE_UNIQUE len_Aval = A_up_nz = 6 len_Aij = A_up_nz = 6 row_offset = 0 col_offset = 0
Output:
k Aval[k-1] Arow[k-1] Acol[k-1] - --------- --------- --------- 1 1.1 1 1 2 2.2 2 2 3 1.3 1 3 4 1.4 1 4 5 2.4 2 4 6 4.4 4 4
Note that in the example above that the elements are sorted by column but they do not have to be on output.
(3) To extract all of the nonzero elements and structure for the lower triangular region of the matrix with the row and column indexes offset by 0 and 0 respectively the following input would yield the following output.
Input:
extract_region = EXTRACT_LOWER_TRIANGULAR element_uniqueness = ELEMENTS_FORCE_UNIQUE len_Aval = A_lo_nz = 9 len_Aij = A_lo_nz = 9 row_offset = 0 col_offset = 0
Output:
k Aval[k-1] Arow[k-1] Acol[k-1] - --------- --------- --------- 1 1.1 1 1 2 4.1 4 1 3 5.1 5 1 4 2.2 2 2 5 3.2 3 2 6 4.3 4 3 7 5.3 5 3 8 4.4 4 4 9 5.4 5 4
Note that in the example above that the elements are sorted by column but they do not have to be on output.
Implemented in AbstractLinAlgPack::MatrixConvertToSparseEncap, AbstractLinAlgPack::MatrixExtractSparseElements, and AbstractLinAlgPack::MatrixSymDiagSparse.

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

AbstractLinAlgPack_MatrixConvertToSparse.hpp

Generated on Thu Sep 18 12:33:55 2008 for AbstractLinAlgPack: C++ Interfaces For Vectors, Matrices And Related Linear Algebra Objects by

1.3.9.1

AbstractLinAlgPack::MatrixConvertToSparse Class Reference

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

Member Function Documentation