Representing sparse data

template<typename SpMat> concept SparseMatrix

#include <base.hh>

Any object \(\texttt{M}\) of type \(\texttt{SpMat}\) has the following attributes.

type

description

\(\texttt{M.n_rows}\)

\(\texttt{const int64_t}\)

number of rows

\(\texttt{M.n_cols}\)

\(\texttt{const int64_t}\)

number of columns

\(\texttt{M.nnz}\)

\(\texttt{int64_t}\)

number of structural nonzeros

\(\texttt{M.vals}\)

\(\texttt{SpMat::scalar_t *}\)

pointer to values of structural nonzeros

\(\texttt{M.own_memory}\)

\(\texttt{const bool}\)

A flag indicating if memory attached to \(\texttt{M}\) should be deallocated when \(\texttt{M}\) is deleted. This flag is set automatically based on the type of constructor used for \(\texttt{M}.\)

Memory-owning constructors

\(\texttt{SpMat}\) must have a constructor for an empty matrix of given dimensions. Conformant implementations of this constructor look like the following.
SpMat(int64_t n_rows, int64_t n_cols) 
 : n_rows(n_rows), n_cols(n_cols), nnz(0), vals(nullptr), own_memory(true) {
     // class-specific code ...
 };
If we construct \(\texttt{SpMat M(m, n)},\) then we can’t store data in \(\texttt{M}\) until a function call of the form \(\texttt{M.reserve(nnz)}.\) Here’s an outline of a conformant implementation of this function.
void reserve(int64_t nnz) {
    assert this->own_memory;
    this->nnz = nnz;
    this->vals = new SpMat::scalar_t[nnz];
    // ... class-specific code ...
}
The destructor of \(\texttt{M}\) is responsible for deallocating \(\texttt{M.vals}\) and other attached data. A conformant implemnentation of the destructor will look like the following.
~SpMat() {
    if (this->own_memory) {
        delete [] this->vals;
        // ... class-specific code ...
    }
}        

Non-owning constructors

This concept doesn’t place specific requirements constructors for non-owning sparse matrix views of existing data. However, all of RandBLAS’ sparse matrix classes offer such constructors. See individual classes’ documentation for details.

Built-in sparse matrix classes

template<typename T, SignedInteger sint_t = int64_t> struct COOMatrix

A COO-format sparse matrix that complies with the SparseMatrix concept.

Public Functions

inline COOMatrix(int64_t n_rows, int64_t n_cols, int64_t nnz, T *vals, sint_t *rows, sint_t *cols, bool compute_sort_type = true)

Constructs a sparse matrix based on declared dimensions and the data in three buffers (vals, rows, cols). This constructor initializes \(\texttt{own_memory(false)}\), and so the provided buffers are unaffected when this object’s destructor is invoked.

Public Members

sint_t *rows = nullptr: Row indicies for nonzeros.

sint_t *cols = nullptr: Column indicies for nonzeros.

NonzeroSort sort = NonzeroSort::None: A flag to indicate if the data in (rows, cols, vals) is sorted in a CSC-like order, a CSR-like order, or neither order.

template<typename T, SignedInteger sint_t = int64_t> struct CSRMatrix

A CSR-format sparse matrix that complies with the SparseMatrix concept.

Public Functions

inline CSRMatrix(int64_t n_rows, int64_t n_cols, int64_t nnz, T *vals, sint_t *rowptr, sint_t *colidxs)

Constructs a sparse matrix based on declared dimensions and the data in three buffers (vals, rowptr, colidxs). This constructor initializes \(\texttt{own_memory(false)}\), and so the provided buffers are unaffected when this object’s destructor is invoked.

Public Members

sint_t *rowptr = nullptr: Pointer offset array for the CSR format. The number of nonzeros in row i is given by rowptr[i+1] - rowptr[i]. The column index of the k-th nonzero in row i is colidxs[rowptr[i] + k].

sint_t *colidxs = nullptr: Column index array in the CSR format.

template<typename T, RandBLAS::SignedInteger sint_t = int64_t> struct CSCMatrix

A CSC-format sparse matrix that complies with the SparseMatrix concept.

Public Functions

inline CSCMatrix(int64_t n_rows, int64_t n_cols, int64_t nnz, T *vals, sint_t *rowidxs, sint_t *colptr)

Constructs a sparse matrix based on declared dimensions and the data in three buffers (vals, rowidxs, colptr). This constructor initializes \(\texttt{own_memory(false)}\), and so the provided buffers are unaffected when this object’s destructor is invoked.

Public Members

sint_t *rowidxs = nullptr: Row index array in the CSC format.

sint_t *colptr = nullptr: Pointer offset array for the CSC format. The number of nonzeros in column j is given by colptr[j+1] - colptr[j]. The row index of the k-th nonzero in column j is rowidxs[colptr[j] + k].