Class SUNMatrixWrapper

Class Documentation

class SUNMatrixWrapper

A RAII wrapper for SUNMatrix structs.

This can create dense, sparse, or banded matrices using the respective constructor.

Public Functions

SUNMatrixWrapper() = default
explicit SUNMatrixWrapper(sunindextype M, sunindextype N, sunindextype NNZ, int sparsetype, SUNContext sunctx)

Create sparse matrix. See SUNSparseMatrix in sunmatrix_sparse.h.

Parameters:
  • M – Number of rows

  • N – Number of columns

  • NNZ – Number of nonzeros

  • sparsetype – Sparse type

  • sunctx – SUNDIALS context

SUNMatrixWrapper(sunindextype M, sunindextype N, SUNContext sunctx)

Create dense matrix. See SUNDenseMatrix in sunmatrix_dense.h.

Parameters:
  • M – Number of rows

  • N – Number of columns

  • sunctx – SUNDIALS context

SUNMatrixWrapper(sunindextype M, sunindextype ubw, sunindextype lbw, SUNContext sunctx)

Create banded matrix. See SUNBandMatrix in sunmatrix_band.h.

Parameters:
  • M – Number of rows and columns

  • ubw – Upper bandwidth

  • lbw – Lower bandwidth

  • sunctx – SUNDIALS context

SUNMatrixWrapper(SUNMatrixWrapper const &A, realtype droptol, int sparsetype)

Create sparse matrix from dense or banded matrix. See SUNSparseFromDenseMatrix and SUNSparseFromBandMatrix in sunmatrix_sparse.h.

Parameters:
  • A – Wrapper for dense matrix

  • droptol – tolerance for dropping entries

  • sparsetype – Sparse type

explicit SUNMatrixWrapper(SUNMatrix mat)

Wrap existing SUNMatrix.

Parameters:

mat

~SUNMatrixWrapper()
inline operator SUNMatrix()

Conversion function.

SUNMatrixWrapper(SUNMatrixWrapper const &other)

Copy constructor.

Parameters:

other

SUNMatrixWrapper(SUNMatrixWrapper &&other)

Move constructor.

Parameters:

other

SUNMatrixWrapper &operator=(SUNMatrixWrapper const &other)

Copy assignment.

Parameters:

other

Returns:

SUNMatrixWrapper &operator=(SUNMatrixWrapper &&other)

Move assignment.

Parameters:

other

Returns:

void reallocate(sunindextype nnz)

Reallocate space for sparse matrix according to specified nnz.

Parameters:

nnz – new number of nonzero entries

void realloc()

Reallocate space for sparse matrix to used space according to last entry in indexptrs.

SUNMatrix get() const

Get the wrapped SUNMatrix.

Note

Even though the returned matrix_ pointer is const qualified, matrix_->content will not be const. This is a shortcoming in the underlying C library, which we cannot address and it is not intended that any of those values are modified externally. If matrix_->content is manipulated, cpp:meth:SUNMatrixWrapper:refresh needs to be called.

Returns:

raw SunMatrix object

inline sunindextype rows() const

Get the number of rows.

Returns:

number of rows

inline sunindextype columns() const

Get the number of columns.

Returns:

number of columns

sunindextype num_nonzeros() const

Get the number of specified non-zero elements (sparse matrices only)

Note

value will be 0 before indexptrs are set.

Returns:

number of nonzero entries

sunindextype num_indexptrs() const

Get the number of indexptrs that can be specified (sparse matrices only)

Returns:

number of indexptrs

sunindextype capacity() const

Get the number of allocated data elements.

Returns:

number of allocated entries

realtype *data()

Get raw data of a sparse matrix.

Returns:

pointer to first data entry

realtype const *data() const

Get const raw data of a sparse matrix.

Returns:

pointer to first data entry

inline realtype get_data(sunindextype idx) const

Get data of a sparse matrix.

Parameters:

idx – data index

Returns:

idx-th data entry

inline realtype get_data(sunindextype irow, sunindextype icol) const

Get data entry for a dense matrix.

Parameters:
  • irow – row

  • icol – col

Returns:

A(irow,icol)

inline void set_data(sunindextype idx, realtype data)

Set data entry for a sparse matrix.

Parameters:
  • idx – data index

  • data – data for idx-th entry

inline void set_data(sunindextype irow, sunindextype icol, realtype data)

Set data entry for a dense matrix.

Parameters:
  • irow – row

  • icol – col

  • data – data for idx-th entry

inline sunindextype get_indexval(sunindextype idx) const

Get the index value of a sparse matrix.

Parameters:

idx – data index

Returns:

row (CSC) or column (CSR) for idx-th data entry

inline void set_indexval(sunindextype idx, sunindextype val)

Set the index value of a sparse matrix.

Parameters:
  • idx – data index

  • val – row (CSC) or column (CSR) for idx-th data entry

inline void set_indexvals(gsl::span<sunindextype const> const vals)

Set the index values of a sparse matrix.

Parameters:

vals – rows (CSC) or columns (CSR) for data entries

inline sunindextype get_indexptr(sunindextype ptr_idx) const

Get the index pointer of a sparse matrix.

Parameters:

ptr_idx – pointer index

Returns:

index where the ptr_idx-th column (CSC) or row (CSR) starts

inline void set_indexptr(sunindextype ptr_idx, sunindextype ptr)

Set the index pointer of a sparse matrix.

Parameters:
  • ptr_idx – pointer index

  • ptr – data-index where the ptr_idx-th column (CSC) or row (CSR) starts

inline void set_indexptrs(gsl::span<sunindextype const> const ptrs)

Set the index pointers of a sparse matrix.

Parameters:

ptrs – starting data-indices where the columns (CSC) or rows (CSR) start

int sparsetype() const

Get the type of sparse matrix.

Returns:

matrix type

void scale(realtype a)

multiply with a scalar (in-place)

Parameters:

a – scalar value to multiply matrix

void multiply(N_Vector c, const_N_Vector b, realtype alpha = 1.0) const

N_Vector interface for multiply.

Parameters:
  • c – output vector, may already contain values

  • b – multiplication vector

  • alpha – scalar coefficient for matrix

inline void multiply(AmiVector &c, AmiVector const &b, realtype alpha = 1.0) const

AmiVector interface for multiply.

Parameters:
  • c – output vector, may already contain values

  • b – multiplication vector

  • alpha – scalar coefficient for matrix

void multiply(gsl::span<realtype> c, gsl::span<realtype const> b, realtype const alpha = 1.0) const

Perform matrix vector multiplication c += alpha * A*b.

Parameters:
  • c – output vector, may already contain values

  • b – multiplication vector

  • alpha – scalar coefficient

void multiply(N_Vector c, const_N_Vector b, gsl::span<int const> cols, bool transpose) const

Perform reordered matrix vector multiplication c += A[:,cols]*b.

Parameters:
  • c – output vector, may already contain values

  • b – multiplication vector

  • cols – int vector for column reordering

  • transpose – bool transpose A before multiplication

void multiply(gsl::span<realtype> c, gsl::span<realtype const> b, gsl::span<int const> cols, bool transpose) const

Perform reordered matrix vector multiplication c += A[:,cols]*b.

Parameters:
  • c – output vector, may already contain values

  • b – multiplication vector

  • cols – int vector for column reordering

  • transpose – bool transpose A before multiplication

void sparse_multiply(SUNMatrixWrapper &C, SUNMatrixWrapper const &B) const

Perform matrix matrix multiplication C = A * B for sparse A, B, C.

Note

will overwrite existing data, indexptrs, indexvals for C, but will use preallocated space for these vars

Parameters:
  • C – output matrix,

  • B – multiplication matrix

void sparse_add(SUNMatrixWrapper const &A, realtype alpha, SUNMatrixWrapper const &B, realtype beta)

Perform sparse matrix matrix addition C = alpha * A + beta * B.

Note

will overwrite existing data, indexptrs, indexvals for C, but will use preallocated space for these vars

Parameters:
  • A – addition matrix

  • alpha – scalar A

  • B – addition matrix

  • beta – scalar B

void sparse_sum(std::vector<SUNMatrixWrapper> const &mats)

Perform matrix-matrix addition A = sum(mats(0)…mats(len(mats)))

Note

will overwrite existing data, indexptrs, indexvals for A, but will use preallocated space for these vars

Parameters:

mats – vector of sparse matrices

sunindextype scatter(sunindextype const k, realtype const beta, sunindextype *w, gsl::span<realtype> x, sunindextype const mark, SUNMatrixWrapper *C, sunindextype nnz) const

Compute x = x + beta * A(:,k), where x is a dense vector and A(:,k) is sparse, and update the sparsity pattern for C(:,j) if applicable.

This function currently has two purposes:

  • perform parts of sparse matrix-matrix multiplication C(:,j)=A(:,k)*B(k,j) enabled by passing beta=B(k,j), x=C(:,j), C=C, w=sparsity of C(:,j) from B(k,0…j-1), nnz=nnz(C(:,0…j-1)

  • add the k-th column of the sparse matrix A multiplied by beta to the dense vector x. enabled by passing beta=*, x=x, C=nullptr, w=nullptr, nnz=*

Parameters:
  • k – column index

  • beta – scaling factor

  • w – index workspace, (w[i]<mark) indicates non-zeroness of C(i,j) (dimension: m), if this is a nullptr, sparsity pattern of C will not be updated (if applicable).

  • x – dense output vector (dimension: m)

  • mark – marker for w to indicate nonzero pattern

  • C – sparse output matrix, if this is a nullptr, sparsity pattern of C will not be updated

  • nnz – number of nonzeros that were already written to C

Returns:

updated number of nonzeros in C

void transpose(SUNMatrixWrapper &C, realtype const alpha, sunindextype blocksize) const

Compute transpose A’ of sparse matrix A and writes it to the matrix C = alpha * A’.

Parameters:
  • C – output matrix (sparse or dense)

  • alpha – scalar multiplier

  • blocksize – blocksize for transposition. For full matrix transpose set to ncols/nrows

void to_dense(SUNMatrixWrapper &D) const

Writes a sparse matrix A to a dense matrix D.

Parameters:

D – dense output matrix

void to_diag(N_Vector v) const

Writes the diagonal of sparse matrix A to a dense vector v.

Parameters:

v – dense outut vector

void zero()

Set to 0.0, for sparse matrices also resets indexptr/indexvals.

inline SUNMatrix_ID matrix_id() const

Get matrix id.

Returns:

SUNMatrix_ID

void refresh()

Update internal cache, needs to be called after external manipulation of matrix_->content.

SUNContext get_ctx() const

Get SUNDIALS context.

Returns:

SUNDIALS context or nullptr if the matrix is empty

inline void set_ctx(SUNContext ctx)

Set SUNContext.

Update the SUNContext of the wrapped SUNMatrix.

Parameters:

ctx – SUNDIALS context to set