cusp::hyb_matrix< IndexType, ValueType, MemorySpace > Class Template Reference

Detailed description

template<typename IndexType, typename ValueType, class MemorySpace>
class cusp::hyb_matrix< IndexType, ValueType, MemorySpace >

Hybrid (HYB) representation a sparse matrix.

Template Parameters

IndexType	Type used for matrix indices (e.g. int).
ValueType	Type used for matrix values (e.g. float).
MemorySpace	A memory space (e.g. cusp::host_memory or cusp::device_memory)

Overview

The hyb_matrix is a combination of the ell_matrix and coo_matrix formats. Specifically, the hyb_matrix format splits a matrix into two portions, one stored in ELL format and one stored in COO format.

While the ELL format is well-suited to vector and SIMD architectures, its efficiency rapidly degrades when the number of nonzeros per matrix row varies. In contrast, the storage efficiency of the COO format is invariant to the distribution of nonzeros per row, and the use of segmented reduction makes its performance largely invariant as well. To obtain the advantages of both, we combine these into a hybrid ELL/COO format.

The purpose of the HYB format is to store the typical number of nonzeros per row in the ELL data structure and the remaining entries of exceptional rows in the COO format.

Note

The ell_matrix entries must be sorted by column index.

The ell_matrix entries within each row should be shifted to the left.

The coo_matrix entries must be sorted by row index.

The matrix should not contain duplicate entries.

Example

The following code snippet demonstrates how to create a hyb_matrix. In practice we usually do not construct the HYB format directly and instead convert from a simpler format such as (COO, CSR) into HYB.

// include hyb_matrix header file
 #include <cusp/hyb_matrix.h>
 #include <cusp/print.h>

 int main()
 {
   // allocate storage for (4,3) matrix with 8 nonzeros
   //     ELL portion has 5 nonzeros and storage for 2 nonzeros per row
   //     COO portion has 3 nonzeros

   cusp::hyb_matrix<int, float, cusp::host_memory> A(3, 4, 5, 3, 2);

   // Initialize A to represent the following matrix
   // [10  20  30  40]
   // [ 0  50   0   0]
   // [60   0  70  80]

   // A is split into ELL and COO parts as follows
   // [10  20  30  40]    [10  20   0   0]     [ 0   0  30  40]
   // [ 0  50   0   0]  = [ 0  50   0   0]  +  [ 0   0   0   0]
   // [60   0  70  80]    [60   0  70   0]     [ 0   0   0  80]

   // Initialize ELL part

   // X is used to fill unused entries in the ELL portion of the matrix
   const int X = cusp::ell_matrix<int,float,cusp::host_memory>::invalid_index;

   // first row
   A.ell.column_indices(0,0) = 0; A.ell.values(0,0) = 10;
   A.ell.column_indices(0,1) = 1; A.ell.values(0,1) = 20;

   // second row
   A.ell.column_indices(1,0) = 1; A.ell.values(1,0) = 50;  // shifted to leftmost position
   A.ell.column_indices(1,1) = X; A.ell.values(1,1) =  0;  // padding

   // third row
   A.ell.column_indices(2,0) = 0; A.ell.values(2,0) = 60;
   A.ell.column_indices(2,1) = 2; A.ell.values(2,1) = 70;  // shifted to leftmost position


   // Initialize COO part
   A.coo.row_indices[0] = 0;  A.coo.column_indices[0] = 2;  A.coo.values[0] = 30;
   A.coo.row_indices[1] = 0;  A.coo.column_indices[1] = 3;  A.coo.values[1] = 40;
   A.coo.row_indices[2] = 2;  A.coo.column_indices[2] = 3;  A.coo.values[2] = 80;

   // print the ELL portion
   cusp::print(A.ell);
   // print the COO portion
   cusp::print(A.coo);
   // print the aggregate
   cusp::print(A);
 }

See Also

ell_matrix

coo_matrix

Examples:

hyb.cu.

Definition at line 142 of file hyb_matrix.h.

#include <hyb_matrix.h>

Inheritance diagram for cusp::hyb_matrix< IndexType, ValueType, MemorySpace >:

Public Methods
	hyb_matrix (void)
	hyb_matrix (IndexType num_rows, IndexType num_cols, IndexType num_ell_entries, IndexType num_coo_entries, IndexType num_entries_per_row, IndexType alignment=32)
template<typename MatrixType >
	hyb_matrix (const MatrixType &matrix)
void	resize (IndexType num_rows, IndexType num_cols, IndexType num_ell_entries, IndexType num_coo_entries, IndexType num_entries_per_row, IndexType alignment=32)
void	swap (hyb_matrix &matrix)
template<typename MatrixType >
hyb_matrix &	operator= (const MatrixType &matrix)

Public Members
ell_matrix_type	ell
coo_matrix_type	coo

Constructor & Destructor Documentation

template<typename IndexType, typename ValueType, class MemorySpace>

cusp::hyb_matrix< IndexType, ValueType, MemorySpace >::hyb_matrix ( void  )

inline

Construct an empty hyb_matrix.

Definition at line 186 of file hyb_matrix.h.

template<typename IndexType, typename ValueType, class MemorySpace>

cusp::hyb_matrix< IndexType, ValueType, MemorySpace >::hyb_matrix ( IndexType  num_rows, IndexType  num_cols, IndexType  num_ell_entries, IndexType  num_coo_entries, IndexType  num_entries_per_row, IndexType  alignment = 32  )

inline

Construct a hyb_matrix with a specific shape and separation into ELL and COO portions.

Parameters

num_rows	Number of rows.
num_cols	Number of columns.
num_ell_entries	Number of nonzero matrix entries in the ELL portion.
num_coo_entries	Number of nonzero matrix entries in the ELL portion.
num_entries_per_row	Maximum number of nonzeros per row in the ELL portion.
alignment	Amount of padding used to align the ELL data structure (default 32).

Definition at line 197 of file hyb_matrix.h.

template<typename IndexType, typename ValueType, class MemorySpace>

template<typename MatrixType >

cusp::hyb_matrix< IndexType, ValueType, MemorySpace >::hyb_matrix

(

const MatrixType &

matrix

)

Construct a hyb_matrix from another matrix.

Parameters

matrix

Another sparse or dense matrix.

Member Function Documentation

template<typename IndexType, typename ValueType, class MemorySpace>

template<typename MatrixType >

hyb_matrix& cusp::hyb_matrix< IndexType, ValueType, MemorySpace >::operator=

(

const MatrixType &

matrix

)

Assignment from another matrix.

Parameters

matrix

Another sparse or dense matrix.

template<typename IndexType, typename ValueType, class MemorySpace>

void cusp::hyb_matrix< IndexType, ValueType, MemorySpace >::resize ( IndexType  num_rows, IndexType  num_cols, IndexType  num_ell_entries, IndexType  num_coo_entries, IndexType  num_entries_per_row, IndexType  alignment = 32  )

inline

Resize matrix dimensions and underlying storage

Definition at line 215 of file hyb_matrix.h.

template<typename IndexType, typename ValueType, class MemorySpace>

void cusp::hyb_matrix< IndexType, ValueType, MemorySpace >::swap ( hyb_matrix< IndexType, ValueType, MemorySpace > &  matrix )

inline

Swap the contents of two hyb_matrix objects.

Parameters

matrix

Another hyb_matrix with the same IndexType and ValueType.

Definition at line 228 of file hyb_matrix.h.

Member Data Documentation

template<typename IndexType, typename ValueType, class MemorySpace>

coo_matrix_type cusp::hyb_matrix< IndexType, ValueType, MemorySpace >::coo

Storage for the ell_matrix portion.

Definition at line 182 of file hyb_matrix.h.

template<typename IndexType, typename ValueType, class MemorySpace>

ell_matrix_type cusp::hyb_matrix< IndexType, ValueType, MemorySpace >::ell

Storage for the ell_matrix portion.

Definition at line 178 of file hyb_matrix.h.