Class SUNMatrixWrapper

Class Documentation

class amici::SUNMatrixWrapper

A RAII wrapper for SUNMatrix structs.

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

Public Functions

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

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

SUNMatrixWrapper(sunindextype M, sunindextype N)

Create dense matrix. See SUNDenseMatrix in sunmatrix_dense.h.

Parameters

  • M: Number of rows

  • N: Number of columns

SUNMatrixWrapper(sunindextype M, sunindextype ubw, sunindextype lbw)

Create banded matrix. See SUNBandMatrix in sunmatrix_band.h.

Parameters

  • M: Number of rows and columns

  • ubw: Upper bandwidth

  • lbw: Lower bandwidth

SUNMatrixWrapper(const SUNMatrixWrapper &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

SUNMatrixWrapper(SUNMatrix mat)

Wrap existing SUNMatrix.

Parameters

  • mat:

~SUNMatrixWrapper()
SUNMatrixWrapper(const SUNMatrixWrapper &other)

Copy constructor.

Parameters

  • other:

SUNMatrixWrapper(SUNMatrixWrapper &&other)

Move constructor.

Parameters

  • other:

SUNMatrixWrapper &operator=(const SUNMatrixWrapper &other)

Copy assignment.

Return

Parameters

  • other:

SUNMatrixWrapper &operator=(SUNMatrixWrapper &&other)

Move assignment.

Return

Parameters

  • other:

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.

const SUNMatrix get() const

Get the wrapped SUNMatrix.

Return

raw SunMatrix object

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.

sunindextype rows() const

Get the number of rows.

Return

number of rows

sunindextype columns() const

Get the number of columns.

Return

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.

Return

number of nonzero entries

sunindextype num_indexptrs() const

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

Return

number of indexptrs

sunindextype capacity() const

Get the number of allocated data elements.

Return

number of allocated entries

realtype *data()

Get raw data of a sparse matrix.

Return

pointer to first data entry

const realtype *data() const

Get const raw data of a sparse matrix.

Return

pointer to first data entry

realtype get_data(sunindextype idx) const

Get data of a sparse matrix.

Return

idx-th data entry

Parameters

  • idx: data index

realtype get_data(sunindextype irow, sunindextype icol) const

Get data entry for a dense matrix.

Return

A(irow,icol)

Parameters

  • irow: row

  • icol: col

void set_data(sunindextype idx, realtype data)

Set data entry for a sparse matrix.

Parameters

  • idx: data index

  • data: data for idx-th entry

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

sunindextype get_indexval(sunindextype idx) const

Get the index value of a sparse matrix.

Return

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

Parameters

  • idx: data index

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

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

Set the index values of a sparse matrix.

Parameters

  • vals: rows (CSC) or columns (CSR) for data entries

sunindextype get_indexptr(sunindextype ptr_idx) const

Get the index pointer of a sparse matrix.

Return

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

Parameters

  • ptr_idx: pointer index

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

void set_indexptrs(const gsl::span<const sunindextype> 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.

Return

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) const

N_Vector interface for multiply.

Parameters

  • c: output vector, may already contain values

  • b: multiplication vector

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

Perform matrix vector multiplication c += A*b.

Parameters

  • c: output vector, may already contain values

  • b: multiplication vector

void multiply(N_Vector c, const N_Vector b, gsl::span<const int> 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<const realtype> b, gsl::span<const int> 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, const SUNMatrixWrapper &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(const SUNMatrixWrapper &A, realtype alpha, const SUNMatrixWrapper &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(const std::vector<SUNMatrixWrapper> &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(const sunindextype k, const realtype beta, sunindextype *w, gsl::span<realtype> x, const sunindextype 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=*

Return

updated number of nonzeros in C

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

void transpose(SUNMatrixWrapper &C, const realtype 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.

SUNMatrix_ID matrix_id() const

Get matrix id.

Return

SUNMatrix_ID

void refresh()

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