Template Class COO_Matrix

Class Documentation

template<typename RealT, typename IdxT>
class COO_Matrix

Quick class to provide sparse matrices of COO type.

Simplifies data movement

Todo:

add functionality to keep track of multiple sorted lists. Faster adding of new entries and will have a threshold to sort completely.

m x n sparse matrix

Public Functions

inline COO_Matrix(std::vector<IdxT> r, std::vector<IdxT> c, std::vector<RealT> v, IdxT m, IdxT n)

Constructor for COO Matrix with given cooridnates and values.

Template Parameters:

  • RealT – - Real type for Jacobian entries

  • IdxT – - Integer data type for matrix indices

Parameters:

  • r – [in] row indices

  • c – [in] column indices

  • v – [in] values

  • m – [in] number of rows

  • n – [in] number of columns

Pre:

r.size() == c.size() == v.size()

Pre:

r,c,v represent an array in COO format

Post:

COO_Matrix is created with given coordinates and values

inline COO_Matrix(IdxT m, IdxT n)

Constructor for empty COO Matrix of a given size.

Template Parameters:

  • RealT – - Real type for Jacobian entries

  • IdxT – - Integer data type for matrix indices

Parameters:

  • m – [in] number of rows

  • n – [in] number of columns

Post:

empty COO Matrix is created with given size

inline COO_Matrix()

Constructor for empty COO Matrix of size 0.

Template Parameters:

  • RealT – - Real type for Jacobian entries

  • IdxT – - Integer data type for matrix indices

Post:

empty COO Matrix of size 0 is created

inline std::tuple<std::vector<IdxT>, std::vector<RealT>> getRowCopy(IdxT r)

Get copy of row index.

Template Parameters:

  • RealT – - Real type for Jacobian entries

  • IdxT – - Integer data type for matrix indices

Parameters:

r – [in] row index

Returns:

std::tuple<std::vector<IdxT>, std::vector<RealT>>

inline std::tuple<std::vector<IdxT>&, std::vector<IdxT>&, std::vector<RealT>&> getEntries(const bool sort = true)

Get all entry pointers. Will sort before returning.

Template Parameters:

  • RealT – - Real type for Jacobian entries

  • IdxT – - Integer data type for matrix indices

Returns:

std::tuple<std::vector<IdxT>, std::vector<IdxT>, std::vector<RealT>>

inline std::tuple<std::vector<IdxT>, std::vector<IdxT>, std::vector<RealT>> getEntryCopies()

Sorts the data if it’s not already sorted.

Template Parameters:

  • RealT – - Real type for Jacobian entries

  • IdxT – - Integer data type for matrix indices

Returns:

std::tuple<std::vector<IdxT>, std::vector<IdxT>, std::vector<RealT>>

inline std::tuple<std::vector<IdxT>, std::vector<IdxT>, std::vector<RealT>> setDataToCSR()

Returns the data in CSR Format.

Template Parameters:

  • RealT – - Real type for Jacobian entries

  • IdxT – - Integer data type for matrix indices

Returns:

std::tuple<std::vector<IdxT>, std::vector<IdxT>, std::vector<RealT>>

inline std::vector<IdxT> getCSRRowData()

Only creates the row data.

Todo:

swap this with having the matrix store the data and updates. This can then be passed by reference

Template Parameters:

  • RealT – - Real type for Jacobian entries

  • IdxT – - Integer data type for matrix indices

Returns:

std::vector<IdxT>

inline void setValues(std::vector<IdxT> r, std::vector<IdxT> c, std::vector<RealT> v)

Set coordinates and values of the matrix.

Matrix entries will be sorted in row-major order before the method returns.

Template Parameters:

  • RealT – - Real type for Jacobian entries

  • IdxT – - Integer data type for matrix indices

Parameters:

  • r – [in] row indices of the matrix

  • c – [in] column indices of the matrix

  • v – [in] values of the matrix

Pre:

r.size() == c.size() == v.size()

Pre:

r,c,v represent an array in COO format

Post:

Coordinates and values are set in the matrix.

inline void setValues(RealT alpha, IdxT *r, IdxT *c, RealT *v, IdxT nnz)

Append coordinates and values of the matrix without sorting or deduplicating.

Template Parameters:

  • RealT – - Real type for Jacobian entries

  • IdxT – - Integer data type for matrix indices

Parameters:

  • r – [in] row indices to be stored

  • c – [in] column indices to be stored

  • v – [in] values to be stored

  • nnz – [in] to be stored

inline void axpy(RealT alpha, COO_Matrix<RealT, IdxT> &a, const bool sort = true)

Implements axpy this += alpha * a. Will sort before running.

Template Parameters:

  • RealT – - Real type for Jacobian entries

  • IdxT – - Integer data type for matrix indices

Parameters:

  • alpha – [in] matrix to be added

  • a – [in] scalar to multiply by

Post:

this = this + alpha * a

inline void axpy(RealT alpha, std::vector<IdxT> r, std::vector<IdxT> c, std::vector<RealT> v, const bool sort = true)

axpy on a COO representation of a matrix. Will sort before running

Template Parameters:

  • RealT – - Real type for Jacobian entries

  • IdxT – - Integer data type for matrix indices

Parameters:

  • alpha – scalar to multiply by

  • r – row indices

  • c – column indices

  • v – values

Pre:

r.size() == c.size() == v.size()

Pre:

r,c,v represent an array a in COO format

Post:

this = this + alpha * a

inline void axpy(RealT alpha, IdxT *r, IdxT *c, RealT *v, IdxT nnz)

Append coordinates and values of the matrix without sorting or deduplicating.

Need to deduplicate bus entries right away to get around the new mappings introduced by bus faults.

Only use for buses, which are 2x2, so the cost of loops is not uncontrolled. Don’t allow resizing.

Template Parameters:

  • RealT – - Real type for Jacobian entries

  • IdxT – - Integer data type for matrix indices

Parameters:

  • r – [in] row indices to be stored

  • c – [in] column indices to be stored

  • v – [in] values to be stored

  • nnz – [in] to be stored

inline void scal(RealT alpha)

Scale all values by alpha.

Template Parameters:

  • RealT – - Real type for Jacobian entries

  • IdxT – - Integer data type for matrix indices

Parameters:

alpha – [in] scalar to scale by

inline RealT frobNorm()

Calculates the Frobenius Norm of the matrix.

Template Parameters:

  • RealT – - Real type for Jacobian entries

  • IdxT – - Integer data type for matrix indices

Returns:

RealT - Frobenius Norm of the matrix

inline void permutation(std::vector<IdxT> row_perm, std::vector<IdxT> col_perm)

Permutate the matrix to a different one. Only changes the coordinates.

Template Parameters:

RealT – - Real type for Jacobian entries

Parameters:

  • row_perm – [in]

  • col_perm –

Pre:

row_perm.size() == this->rows_size_ = col_perm.size() == this->columns_size_

Post:

this = this(row_perm, col_perm)

inline void permutationSizeMap(std::vector<IdxT> row_perm, std::vector<IdxT> col_perm, IdxT m, IdxT n)

Permutes the matrix and can change its size efficently.

Template Parameters:

  • RealT – - Real type for Jacobian entries

  • IdxT – - Integer data type for matrix indices

Parameters:

  • row_perm – [in] row permutation

  • col_perm – [in] column permutation

  • m – [in] number of rows

  • n – [in] number of columns

Pre:

row_perm.size() == this->rows_size_

Pre:

col_perm.size() == this->columns_size_

Pre:

indices are set to -1 if they are to be removed

Post:

this = this(row_perm, col_perm) and removed indices have corresponding values set to 0

inline void zeroMatrix()

Turn matrix into the null matrix. Does not actually delete memory.

Template Parameters:

  • RealT – - Real type for Jacobian entries

  • IdxT – - Integer data type for matrix indices

inline void zeroValuedMatrix()

Initializes matrix values to 0 without changing the sparsity pattern.

Template Parameters:

  • RealT – - Real type for Jacobian entries

  • IdxT – - Integer data type for matrix indices

inline void identityMatrix(IdxT n)

Turn matrix into the identity matrix.

Todo:

  • it might be better to explicitly zero out the matrix and require to be so in preconditions

Template Parameters:

  • RealT – - Real type for Jacobian entries

  • IdxT – - Integer data type for matrix indices

Parameters:

n – [in] size of the identity matrix

Post:

this = I_n

inline void sortSparse()

Restructure the sparse matrix for faster accesses and modifications.

Template Parameters:

  • RealT – - Real type for Jacobian entries

  • IdxT – - Integer data type for matrix indices

inline bool isSorted()

Check if the matrix is sorted.

Template Parameters:

  • RealT – - Real type for Jacobian entries

  • IdxT – - Integer data type for matrix indices

Parameters:

bool – [out] - true if sorted, false otherwise

inline IdxT nnz()

Get the number of non-zero elements in the matrix.

Template Parameters:

  • RealT – - Real type for Jacobian entries

  • IdxT – - Integer data type for matrix indices

Parameters:

IdxT – [out] - number of non-zero elements in the matrix

inline void deduplicate()

Deduplicate matrix entries.

@node This is currently only used in component-level Jacobian tests, which don’t use CooMatrix or CsrMatrix yet, to compare with Dependency::Tracking maps.

Template Parameters:

  • RealT – - Real type for Jacobian entries

  • IdxT – - Integer data type for matrix indices

inline void printMatrix(std::string name = "")

Print matrix in sorted order.

Template Parameters:

  • RealT – - Real type for Jacobian entries

  • IdxT – - Integer data type for matrix indices

Parameters:

name – [in] to identify the specific matrix printed

void printMatrixMarket(const std::string &filename, const std::string &comment)

Print matrix to file in Matrix Market format.

Template Parameters:

  • RealT – - Real type for Jacobian entries

  • IdxT – - Integer data type for matrix indices

Parameters:

  • filename – [in] Output file path

  • comment – [in] Optional comment for the Matrix Market file

Public Static Functions

static inline void sortSparseCOO(std::vector<IdxT> &rows, std::vector<IdxT> &columns, std::vector<RealT> &values, size_t nnz)

Sorts unordered COO matrix.

Matrix entries can appear in arbitrary order and will be sorted in row-major order before the method returns. Duplicate entries are not allowed and should be pre-summed.

Todo:

simple setup. Should add stable sorting since lists are pre-sorted_

Pre:

rows, columns, and values are of the same size and represent a COO matrix with no duplicates

Post:

Matrix entries are sorted in row-major order

Template Parameters:

  • RealT – - Real type for Jacobian entries

  • IdxT – - Integer data type for matrix indices

Parameters:

  • rows –

  • columns –

  • values –