#include <AbstractLinAlgPack_MatrixConvertToSparse.hpp>
Inheritance diagram for AbstractLinAlgPack::MatrixConvertToSparse:
Public Types | |
| 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. | |
| 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. | |
| 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. | |
The formats supported are:
Coordiante:
Aval[k], Arow[k], Acol[k], k = 0..num_nonzeros(...)-1
Aval[k], Acol[k], k = 0..num_nonzeros(...)-1
Arow_start[j], j = 0..rows()-1
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.
Definition at line 81 of file AbstractLinAlgPack_MatrixConvertToSparse.hpp.
Definition at line 87 of file AbstractLinAlgPack_MatrixConvertToSparse.hpp.
| virtual index_type AbstractLinAlgPack::MatrixConvertToSparse::num_nonzeros | ( | EExtractRegion | extract_region, | |
| EElementUniqueness | element_uniqueness | |||
| ) | const [pure virtual] |
Returns the number of nonzeros in the matrix.
| extract_region | [in] Determines what matix region to extract:
| |
| element_uniqueness | [in] Determines if element row and column indexes must be unique.
|
| 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).
| extract_region | [in] Determines what matix region to extract:
| |
| element_uniqueness | [in] Determines if element row and column indexes must be unique.
| |
| 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. |
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
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
(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
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
(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
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
1.4.7