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 elementnz_column
- Stores the column of each nonzero elementrow_offset
- Stores the index to the first element for each row in the two previous arraysLet 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
orfloat
.Location – Location of the data
Storage – The container to store the data
Constructor
-
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 asStorage
, 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.
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¶
-
const storage_index &row_offset() const noexcept¶
-
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.
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.
Capacity
-
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
andcols
, 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:
Instead, domat = mat.T();
to correctly transpose the matrix.mat.transpose_inplace()
- 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:
Instead, domat = mat.H();
to correctly transpose the matrix.mat.adjoint_inplace()
-
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.