Module Spurs.CsmatSource

Compressed Sparse Row (CSR) vs Compressed Sparse Column (CSC) formats.

They are explained in more detail in t

In the CSR (Compressed Sparse Row) format, a matrix is represented by three vectors: indptr, indices, and data.

These vectors satisfy the following relation:

  for i in [0, nrows]:
    A(i, indices[indptr[i] .. indptr[i + 1]]) = data[indptr[i] .. indptr[i + 1]]

In the CSC (Compressed Sparse Column) format, the relation becomes:

  for i in [0, ncols]:
    A(indices[indptr[i] .. indptr[i + 1]], i) = data[indptr[i] .. indptr[i + 1]]

The outer dimension of a compressed matrix is always kept in full. For CSR matrices, the outer dimension is the rows, and for CSC matrices, the outer dimension is the columns. The inner dimension of a compressed matrix is compressed with index-data pairs. It is the opposite of the outer dimension.

Raised when trying to create invalid sparse matrices.

try_new_csr (rows, cols) indptr indices data attempts to create a new CSR matrix. It checks that:

• indptr is of length rows + 1
• indices and data have the same length
• the last element of indptr is equal to length indices
• the indices for each inner dimension are sorted (see t)
• every element in indices is less than cols

Returns Ok m if the inputs represent a valid CSR matrix, otherwise Error s

try_new_csr (rows, cols) indptr indices data attempts to create a new CSR matrix. It checks that:

• indptr is of length cols + 1
• indices and data have the same length
• the last element of indptr is equal to length indices
• the indices for each inner dimension are sorted (see t)
• every element in indices is less than rows

Returns Ok m if the inputs represent a valid CSC matrix, otherwise Error s

new_csr (rows, cols) indptr indices data creates a new CSR matrix.

Raises MatrixException if the inputs do not describe a valid CSR matrix, described in try_new_csr

new_csc (rows, cols) indptr indices data creates a new CSC matrix.

Raises MatrixException if the inputs do not describe a valid CSC matrix, described in try_new_csc

new_csr_from_unsorted (rows, cols) indptr indices data creates a new CSR matrix, sorting the index-data pairs for each inner dimension as needed.

Raises MatrixException if the inputs do not describe a valid CSR matrix, described in try_new_csr

new_csc_from_unsorted (rows, cols) indptr indices data creates a new CSC matrix, sorting the index-data pairs for each inner dimension as needed.

Raises MatrixException if the inputs do not describe a valid CSC matrix, described in try_new_csc

csr from dense ~epsilon m creates a new CSR matrix mathematically equivalent to m, ignoring all elements less than epsilon

csc from dense ~epsilon m creates a new CSC matrix mathematically equivalent to m, ignoring all elements less than epsilon

empty c creates a new empty (0, 0)-shaped sparse matrix with format c for building purposes.

zero (rows, cols) creates a new CSR matrix representing the zero matrix.

eye_csr n creates the n x n matrix, compressed in CSR format.

eye_csc n creates the n x n matrix, compressed in CSC format.

iteroi f m iterates through m, calling f outer inner x on each element.

NOTE: For CSR matrices, it will call f row col item, and for CSC matrices, it will call f col row item. To avoid this behavior, use iterrc.

iterrc f m iterates through m, calling f row col x on each element.

NOTE: Due to the nature of CSC matrices, do not depend on the iteration order of this function. It will jump back and forth between rows.

itero f m calls f outer v on each outer dimension, where v is the corresponding sparse vector.

map f m returns a new sparse matrix with the same format and shape, with all data values x mapped to f x

map_inplace f x maps all values x of m to f x, in place.

scale c m returns a new sparse matrix with all elements of m scaled by c

scale_inplace c m scales all elements of m by c in place

get m (row, col) returns the non-zero value at (row, col). This search is logarithmic in the number of non-zeroes in the corresponding outer dimension.

Returns None if the row and column do not describe a non-zero value.

set m (row, col) x reassigns the value at (row, col) to x. This search is logarithmic in the number of non-zeroes in the corresponding outer dimension.

Returns None if the row and column do not describe a non-zero value.

nnz m returns the number of non-zero values in m

nnz_index m row col finds the non-zero index of the element specified by row and col. Returns None if the indexing does not describe a non-zero element.

This search is logarithmic in the number of non-zeroes in the corresponding outer slice. Once available, the Common.Nnz_index.t allows retrieval with O(1) compexity.

get_nnz m i indexes a sparse matrix using its non-zero index. See nnz_index.

Raises an exception if the index is invalid.

set_nnz m i x reassigns a values in sparse matrix using its non-zero index. See nnz_index.

Raises an exception if the index is invalid.

get_outer m outer returns the sparse vector of m at outer dimension outer. Returns None if the index is out of bounds.

get_outer_exn m outer returns the sparse vector of m at outer dimension outer. Raises an exception if the index is out of bounds.

Shorthand for get

Shorthand for set. Raises an exception if trying to set an invalid value.

Shorthand for get_nnz

Shorthand for set_nnz

to_other_storage m returns a new matrix representing the same matrix as m mathematically, in the opposite conversion format. This is an expensive operation, linear in the number of non-zero data in the matrix

to_dense m converts m into a dense matrix.

append m v appends v as a new outer dimension to m, extending the size of the outer dimension by one. This is adding a new row to CSR matrices, and a new column to CSC matrices.

Raises an exception if the v.dim does not have the same size as the inner dimension of m.

append_outer ~epsilon m v appends v as a new outer dimension to m, extending the size of the outer dimension by one. This is adding a new row to CSR matrices, and a new column to CSC matrices.

Ignores all elements less than epsilon

Raises an exception if the vector to add does not have the same size as the inner dimension of m.

insert row col x inserts an element in the matrix at (row, col). If the element is already present, its value is overwritten.

This is not an efficient operation. However, it is efficient if the elements are inserted in order according to the formatting (for example, row-by-row for CSR matrices)

If the index is out of bounds, the matrix will be resized to the necessary size.

expand m rows cols expands m to have rows rows and cols columns, padding with compressed zeroes.

Raises MatrixException if rows or cols are smaller than their current values.

transpose_mut m converts m to its mathematical transpose in-place. Converts CSR matrices to CSC and vise-versa. This is a cheap operation.

This is not the same as to_other_storage, mathematically changing what the matrix is.

transpose m returns a new matrix that is the mathematical transpose of m. Returns a matrix in the opposite compression format. This is a cheap operation.

This is not the same as to_other_storage, mathematically changing what the matrix is.

to_csr m creates a new CSR matrix equivalent to m. If m is a CSR matrix, create a copy.

into_csr m returns a new CSR matrix equivalent to m. If m is a CSR matrix, it is returned as a value. For a version that copies, see to_csr

to_csc m creates a new CSC matrix equivalent to m. If m is a CSC matrix, create a copy.

into_csc m returns a new CSC matrix equivalent to m. If m is a CSC matrix, it is returned as a value. For a version that copies, see to_csc

to_col v converts sparse vector v into a new matrix with only one column.

to_row v converts sparse vector v into a new matrix with only one row.

density m returns the density (proportion non-zero) of a matrix

diag m returns the diagonal of a sparse matrix as a sparse vector

degrees m returns a vector containing the degree of each vertex, ie the number of neighbors of each vertex. We do not count diagonal entries as a neighbor.

to_inner_onehot generates a one-hot matrix, compressing the inner dimension.

Returns a matrix with the same size, the same CSR/CSC type, and a single value of 1.0 within each populated inner vector, at the index of the largest value of each inner vector.

is_csr m returns true if m is a CSR matrix.

is_csc m returns true if m is a CSC matrix.

max_outer_nnz m returns the max number of nonzeros in any outer dimension in m

Default pretty-printer for sparse matrices

Default show for sparse matrices

Default equal function for sparse matrices

copy m creates a copy of m, shallowly copying its inner Dynarrays.

In the case of primitive sparse matrices, this can be considered a deep copy.

check_structure outer inner indptr indices checks the structure of CsMat components, ensuring:

• indptr is of length outer_dim() + 1
• indices and data have the same length, nnz == indptr[outer_dims()]
• indices is sorted for each outer slice
• indices are lower than inner_dims()

print_float_matrix m prints m to stdout.

print_int_matrix m prints m to stdout.