CSR Matrix

template<Number ElemType, DataLocation Location, template<typename, typename> typename Storage>
class CSRMatrix : public HighFM::MatrixBase<CSRMatrix<ElemType, Location, Storage>>

The CSRMatrix implement the widely used Compressed Sparse Row (CSR) scheme. It consists of three buffers:

nz_value - Stores the values of each nonzero element nz_column - Stores the column of each nonzero element row_offset - Stores the index to the first element for each row in the two previous arrays

Let us illustrate this scheme with an example:

\[\begin{split} M = \begin{bmatrix} 11 & 0 & 13 & 0 \\ 0 & 0 & 0 & 24 \\ 0 & 32 & 33 & 0 \\ 41 & 0 & 0 & 0 \end{bmatrix} \\ \end{split}\]

Internally, the sparse matrix M is stored as follows:

\[\begin{split}\begin{align*} nz\_value & = & \: \begin{bmatrix} 11 & 13 & 24 & 32 & 33 & 41 \end{bmatrix} \\ nz\_column & = & \: \begin{bmatrix} 0 & 2 & 3 & 1 & 2 & 0 \end{bmatrix} \\ row\_offset & = & \: \begin{bmatrix} 0 & 2 & 3 & 5 & 6 \end{bmatrix} \end{align*}\end{split}\]

Notice that the last element in the row_offset is the number of nonzeros in the matrix. Creating a new object:

CSRMatrix<float> mat1;                                          // Creates an empty CSR matrix
read_hdf5("file.h5", "A", mat1);                                // Reads an HDF5 file and then stores the data in mat1
CSRMap<float> mat2({.nrows = mat1.rows(),                       // Creates a data map to mat1
                    .ncols = mat1.cols(),
                    .nnz = mat1.size(),
                    .row_offset = mat1.row_offset().data(),
                    .nz_columns = mat1.columns().data(),
                    .nz_values = mat1.values().data());
CSRMatrix<float> mat3 = mat2;                                   // Creates a copy of the mat2

Accessing the Elements

CSRMatrix<int> mat;
read_hdf5("file.h5", "A", mat);

mat[1] = 5;                         // Accesses the value of the nonzero element in the position (1)
index_t col = mat.index_at(2);      // Accesses the column index of the nonzero element in the position (2)
auto mat_row = mat(2, all);         // Creates a sparse slice to the second row of the matrix

Template Parameters:
  • ElemType – Data types of the entries. Must be either a double or float.

  • Location – Location of the data

  • Storage – The container to store the data

Constructor

CSRMatrix()

Creates an empty CSRMatrix.

template<DataLocation OtherLoc, template<typename, typename> typename OtherStorage>
CSRMatrix(const CSRMatrix<ElemType, OtherLoc, OtherStorage> &other)

Creates a CSRMatrix from an other CSRMatrix.

Parameters:

other[in] another CSRMatrix to use as the data source.

CSRMatrix(CSRMatrixData<ElemType> data)

Maps the CSRMatrix to an external container when using DataMap as Storage. Otherwise, creates a new CSRMatrix and then copies the data from the external container.

Parameters:

data[in] struct containing the information about the container

CSRMatrix(const CSRMatrix &other)

Creates a CSRMatrix from an other CSRMatrix. When using DataMap as Storage, this will just duplicate map without copying the data.

Parameters:

other[in] another CSRMatrix to use as the data source.

template<ResizableContainer S = storage_value>
CSRMatrix(CSRMatrix &&other) noexcept

Creates a new CSRMatrix and then moves the content from an other CSRMatrix.

Warning

This constructor is only available when using Array as Storage.

Parameters:

other[in] another CSRMatrix to use as the data source.

template<ResizableContainer S = storage_value>
CSRMatrix(const COOMatrix<ElemType> &coo_matrix)

Creates a new CSRMatrix from a COOMatrix. The nonzero entries in the COOMatrix must be sorted by row, and then by column. It also must not contain duplicated entries.

Warning

This constructor is only available when using Array as Storage.

Parameters:

coo_matrix[in] a COOMatrix to use as the data source.

Destructor

virtual ~CSRMatrix() = default

Default Destructor.

Assignment

CSRMatrix &operator=(const CSRMatrix &other)

Copies the content from an other CSRMatrix.

Parameters:

other[in] another CSRMatrix to use as the data source.

Returns:

*this.

template<DataLocation OtherLoc, template<typename, typename> typename OtherStorage>
CSRMatrix &operator=(const CSRMatrix<ElemType, OtherLoc, OtherStorage> &other)

Copies the content from an other CSRMatrix.

Parameters:

other[in] another CSRMatrix to use as the data source.

Returns:

*this.

template<ResizableContainer S = storage_value>
CSRMatrix &operator=(CSRMatrix &&other) noexcept

Moves the content from an other CSRMatrix to this container.

Warning

This routine is only available when using Array as Storage.

Parameters:

other[in] another CSRMatrix to use as the data source.

Returns:

*this.

template<ResizableContainer S = storage_value>
CSRMatrix &operator=(const COOMatrix<ElemType> &coo_matrix)

Copies the content of a COOMatrix. The nonzero entries in the COOMatrix must be sorted by row, and then by column. It also must not contain duplicated entries.

Warning

This routine is only available when using Array as Storage.

Parameters:

coo_matrix[in] a COOMatrix to use as the data source.

template<typename E>
Derived &operator=(internal::MatExpr<E> &&expr)

Evaluates the expression and assign the result to this container. For example,

Matrix<float> A, B, R;
...
R = A + B

Parameters:

expr[in] expression with one or more operations

Internal Buffers

Warning

These routines aims to provide interoperability to other libraries. Changing the properties of the internal buffers (e.g., its size) may result in undefined behaviour.

storage_index &row_offset() noexcept
Returns:

The internal buffer containing the index of the first nonzero element in each row for the columns() and values() containers.

const storage_index &row_offset() const noexcept
Returns:

The internal buffer containing the index of the first nonzero element in each row for the columns() and values() containers.

storage_index &columns() noexcept
Returns:

The internal buffer containing the column of each nonzero element in the CSRMatrix.

const storage_index &columns() const noexcept
Returns:

The internal buffer containing the column of each nonzero element in the CSRMatrix.

storage_value &values() noexcept
Returns:

The internal buffer with values of each nonzero element in the CSRMatrix.

const storage_value &values() const noexcept
Returns:

The internal buffer with values of each nonzero element in the CSRMatrix.

Element Access

ElemType &operator[](index_t idx)

Accesses the nonzero element at (idx) position. In this case, the indexing only includes the nonzero elements.

Returns:

A reference to the value of the requested element.

ElemType operator[](index_t idx) const

Accesses the nonzero element at (idx) position. In this case, the indexing only includes nonzero elements.

Returns:

The value of the requested element.

SparseVectorMap<ElemType, Location> operator()(index_t r, All)
Returns:

The row r of the CSRMatrix as a SparseVector.

SparseVectorMap<ElemType, Location> operator()(index_t r, All) const
Returns:

The row r of the CSRMatrix as a SparseVector.

index_t index_at(index_t idx) const

Accesses the index of the nonzero element at (idx) position. In this case, the indexing only includes nonzeros elements.

Returns:

The column index of the requested element.

Capacity

index_t rows() const noexcept
Returns:

The number of rows in the CSRMatrix.

index_t cols() const noexcept
Returns:

The number of columns in the CSRMatrix

index_t size() const noexcept
Returns:

The number of nonzero entries in the CSRMatrix.

template<ResizableContainer S = storage_value>
void reserve(index_t nonzeros)

Reserves space in memory for nonzeros elements. The previous content in the matrix is destroyed.

Note

This routine is only available when using Array as Storage.

Parameters:

nonzeros[in] reserved size.

template<ResizableContainer S = storage_value>
void clear() noexcept

Clears all the nonzero entries of the CSRMatrix. This routine does not change the number of rows and columns of the matrix.

Note

This routine is only available when using Array as Storage.

template<ResizableContainer S = storage_value>
void resize(index_t nrows, index_t ncols)

Resizes the CSRMatrix, changing the number of rows and columns to nrows and cols, respectively. The previous content in the matrix is destroyed.

Note

This routine is only available when using Array as Storage.

Parameters:
  • nrows[in] number of rows.

  • ncols[in] number of columns.

Modifiers

internal::ConjugateTransposeOp<CSRMatrix, internal::kTranspose> T() const

Warning

If you want to replace the matrix by its transpose, do not use:

mat = mat.T(); 
Instead, do
mat.transpose_inplace() 
to correctly transpose the matrix.

Returns:

An abstract expression representing the transpose of the CSRMatrix.

internal::ConjugateTransposeOp<CSRMatrix, internal::kAdjoint> H() const

Warning

If you want to replace the matrix by its transpose, do not use:

mat = mat.H(); 
Instead, do
mat.adjoint_inplace() 
to correctly transpose the matrix.

Returns:

An abstract expression representing the adjoint (conjugate transpose) of the Matrix. This is equivalent to T() if the matrix is real.

void swap(CSRMatrix &other) noexcept

Swaps the CSRMatrix content with other, including any memory allocation (if applicable).

Parameters:

other[inout] another CSRMatrix to exchange content with.

template<RemappableContainer S = storage_value>
void map_to(CSRMatrixData<ElemType> data)

Replaces the managed container.

Note

This routine is only available when using DataMap as Storage.

Parameters:

data[in] struct containing the information about the container

template<template<typename, typename> typename OtherStorage, RemappableContainer S = storage_value>
void map_to(const CSRMatrix<ElemType, Location, OtherStorage> &data)

Replaces the managed container.

Note

This routine is only available when using DataMap as Storage.

Parameters:

data[in] struct containing the information about the container

CSRMatrixData<ElemType> mat_data() const
Returns:

a simple struct with a pointer to the container and its dimensions.

template<typename T>
struct CSRMatrixData

A simple struct storing the data of a CSR matrix.

Public Members

index_t nrows

Number of rows in the matrix.

index_t ncols

Number of columns in the matrix.

index_t nnz

Number of nonzeros in the matrix.

index_t *row_offset

An array with nrows + 1 entries with the offset of the first element in each row.

index_t *nz_columns

An array with the column index of each nonzero entry in the matrix.

T *nz_values

An array with the values of each nonzero entry in the matrix.