Index-and Value-Compressed Sparse Column (IVCSC) Class Reference

class PyVSparse.IVCSC[source]

_COOconstruct(moduleName, spmat)[source]

Private helper function to construct a IVCSC matrix from a scipy.sparse COO matrix. In C++, the constructor expects std::tuple<indexT, indexT, T> for each non-zero element.

C++ declaration: template <typename T2, typename indexT> IVCSC(std::vector<std::tuple<indexT, indexT, T2>>& entries, uint64_t num_rows, uint32_t num_cols, uint32_t nnz);

Parameters:

moduleName (str) – The name of the module to construct the IVCSC matrix from
spmat (sp.sparse.coo_matrix) – The input matrix

_CSconstruct(moduleName, spmat)[source]

Private helper function to construct a IVCSC matrix from a scipy.sparse CSC or CSR matrix. This uses the Eigen::SparseMatrix<T> constructor in C++. Pybind11 handles the conversion.

A pure Python implementation of a CSR/C matrix could be used to make a IVCSC matrix, but that is not implemented at this time. The C++ backend should support it though.

Parameters:

moduleName (str) – The name of the module to construct the IVCSC matrix from
spmat (Union[sp.sparse.csc_matrix, sp.sparse.csr_matrix]) – The input matrix

__eq__(other)[source]

Compares the matrix to another IVCSC matrix

Parameters:: other (IVCSC) – The matrix to compare to
Returns:: True if the matrices are equal, False otherwise
Return type:: bool

__getitem__(key)[source]

Random access operator for IVCSC.

As of right now, this only supports random access of a single element.

Parameters:: key (int) – The index of the element to access
Returns:: The value at the index
Return type:: any

__imul__(other)[source]

Inplace multiplication of the matrix by a scalar

Parameters:: other (Union[int, float]) – The value or object to multiply the matrix by
Returns:: The matrix multiplied by the input
Return type:: IVCSC
Raises:: TypeError – If the input is not a scalar or numpy array

__init__(spmat, order='col')[source]

Index-and Value-Compressed Sparse Column is a read-only sparse matrix format optimzed for redundant data. See README.md for more information. While the name is indicitive of the storage order, the matrix can be stored in either column-major or row-major order.

This class can be constructed from a few different options: 1.) scipy.sparse.csc_matrix 2.) scipy.sparse.csr_matrix 3.) scipy.sparse.coo_matrix 4.) PyVSparse.IVCSC 5.) A .vcsc file (written by IVCSC.write() or a C++ program that uses IVCSC.write()).

Unlike VCSC, IVCSC has no indexType parameter. The indices are compressed using positive delta-encoding and byte-packing, so index sizes may be different for each value.

The user can also specify the storage order of the matrix. The default is “Col” for column-major order.

Note: IVCSC is generally slower than VCSC due to the extra compression making byte alignment impossible.: However, IVCSC is far more memory efficent for the same reason.

Parameters:

spmat (Union[sp.sparse.csc_matrix, sp.sparse.csr_matrix, sp.sparse.coo_matrix, PyVSparse.IVCSC, str]) – The input matrix or .ivcsc filename
order (str) – The storage order of the matrix. The default is “Col” for column-major order. “Row” can also be specified for row-major order. Capitalization does not matter.

__matmul__(other)[source]

Multiplication of the matrix by a: - dense matrix

The matrix returned will be a dense numpy matrix or vector.

Parameters:: other (Union[np.ndarray]) – The object to multiply the matrix by
Returns:: The matrix multiplied by the input
Return type:: union[np.ndarray]
Raises:: TypeError – If the input is not a numpy array

__mul__(other)[source]

Multiplication of the matrix by a: - scalar

If the input is a scalar, then the matrix returned will be a IVCSC matrix.

Parameters:: other (Union[int, float]) – The value or object to multiply the matrix by
Returns:: The matrix multiplied by the input
Return type:: union[IVCSC]
Raises:: TypeError – If the input is not a scalar

__ne__(other)[source]

Compares the matrix to another IVCSC matrix

Parameters:: other (IVCSC) – The matrix to compare to
Returns:: True if the matrices are not equal, False otherwise
Return type:: bool

__radd__(other)[source]

Coefficient-wise addition of the matrix by a: - dense matrix

Becuase IVCSC is read-only, the matrix returned will be a dense numpy matrix or vector. This is a right addition operation: A + IVCSC

The matrix returned will be a dense numpy matrix or vector.

Parameters:: other (Union[np.ndarray, int, float]) – The object to add to the matrix
Returns:: The matrix added to the input
Return type:: union[np.ndarray]
Raises:: TypeError – If the input is not a numpy array, int, or float

__rsub__(other)[source]

Coefficient-wise subtraction of the matrix by a: - dense matrix

Becuase IVCSC is read-only, the matrix returned will be a dense numpy matrix or vector. This is a right subtraction operation: A - IVCSC

The matrix returned will be a dense numpy matrix or vector.

Parameters:: other (Union[np.ndarray, int, float]) – The object to subtract from the matrix
Returns:: The matrix subtracted from the input
Return type:: union[np.ndarray]
Raises:: TypeError – If the input is not a numpy array, int, or float

__rtruediv__(other)[source]

Coefficient-wise division of the matrix by a: - Dense matrix

Becuase IVCSC is read-only, the matrix returned will be a dense numpy matrix or vector. This is a right division operation: A / IVCSC

The matrix returned will be a dense numpy matrix or vector.

Parameters:: other (Union[int, float]) – The object to divide the matrix by
Returns:: The matrix divided by the input
Return type:: union[np.ndarray]
Raises:: TypeError – If the input is not a scalar

_npzConstruct(moduleName, secondary='csc')[source]

This is a wrapper function to construct a VCSC matrix from a .npz file. This still creates a scipy.sparse matrix, but allows for a convenient way to read the file.

Parameters:

moduleName (str) – The npz file name
secondary (str) – The secondary format to convert the matrix to a valid form if the npz file is not one with an available constructor. i.e. BSR -> CSC. The default is “csc”

Raises:

TypeError – If the secondary format is not a valid format.

append(matrix)[source]

Appends a matrix to the current matrix

The appended matrix must be of the same type or a scipy.sparse.csc_matrix/csr_matrix depending on the storage order of the current matrix. For a column-major matrix, the appended matrix will be appended to the end of the columns. For a row-major matrix, the appended matrix will be appended to the end of the rows.

Parameters:: matrix (Union[IVCSC, sp.sparse.csc_matrix, sp.sparse.csr_matrix]) – The matrix to append
Raises:: TypeError – If the input matrix is not a supported type of matrix
Return type:: None

byteSize()[source]

Returns the memory consumption of the matrix in bytes

Returns:: The memory consumption of the matrix in bytes
Return type:: np.uint64

fromIVCSC(ivcsc)[source]

Copy constructor for IVCSC

Parameters:: ivcsc (IVCSC) – The input IVCSC matrix

max(axis=None)[source]

On axis=None, returns the maximum of all elements in the matrix

If axis=0, returns the maximum of each column

If axis=1, returns the maximum of each row

Parameters:: axis (int) – The axis to find the maximum along. The default is None, which finds the maximum of all elements in the matrix.
Returns:: The maximum of the matrix or the maximum of each row/column
Return type:: Union[np.int64, np.double, np.ndarray]

min(axis=None)[source]

On axis=None, returns the minimum of all nonzero elements in the matrix

If axis=0, returns the nonzero minimum of each column

If axis=1, returns the nonzero minimum of each row

Note: because of the way the matrix is stored,

minimums that are zero are very expensive to compute.

There are a few exceptions: - If a row/column is all zeros, then the minimum will be zero. - if axis=None, then the minimum will be zero if nnz < rows * cols

Parameters:: axis (int) – The axis to find the minimum along. The default is None, which finds the minimum of all nonzero elements in the matrix.
Returns:: The minimum of the matrix or the minimum of each row/column
Return type:: Union[np.int64, np.double, np.ndarray]

norm()[source]

Returns the Frobenius norm of the matrix

Returns:: The Frobenius norm of the matrix
Return type:: np.double

read(filename)[source]

Function to read a IVCSC formatted matrix from a file. This function should automatically determine the template type of the matrix.

Parameters:: filename (str) – The name of the file to read from

shape()[source]

Returns the shape of the matrix as a tuple (rows, cols)

:return The shape of the matrix :rtype: Tuple[np.uint32, np.uint32]

Return type:: tuple[numpy.uint32, numpy.uint32]

slice(start, end)[source]

Returns a slice of the matrix.

Currently, only slicing by storage order is supported. For example, if the matrix is stored in column-major order, Then the returned matrix will be a slice of the columns.

Parameters:

start (int) – The start index of the slice
end (int) – The end index of the slice

Returns:

The slice of the matrix

Return type:

IVCSC

sum(axis=None)[source]

On axis=None, returns the sum of all elements in the matrix

If axis=0, returns the sum of each column

If axis=1, returns the sum of each row

Note: Sum is either int64 or a double

Parameters:: axis (int) – The axis to sum along. The default is None, which sums all elements in the matrix.
Returns:: The sum of the matrix or the sum of each row/column
Return type:: Union[np.int64, np.double, np.ndarray]
Raises:: ValueError – If the axis is not 0, 1, or None

tocsc()[source]

Converts the matrix to a scipy.sparse.csc_matrix

Note: This is a copy. This does not destroy the original matrix.: If the storage order of the IVCSC matrix is in row-major, then then a csr_matrix will be created and converted to a csc_matrix.

Returns:: The matrix in scipy.sparse.csc_matrix format
Return type:: sp.sparse.csc_matrix

tocsr()[source]

Converts the matrix to a scipy.sparse.csr_matrix

Note: This is a copy. This does not destroy the original matrix.: If the storage order of the IVCSC matrix is in column-major, then then a csc_matrix will be created and converted to a csr_matrix.

Returns:: The matrix in scipy.sparse.csr_matrix format
Return type:: sp.sparse.csr_matrix

trace()[source]

Returns the sum of all elements along the diagonal.

Throws ValueError if matrix is not square.

Note: Sum is either int64 or a double.

Returns:: The sum of the diagonal
Return type:: Union[np.int64, np.double]
Raises:: ValueError – If the matrix is not square

transpose(inplace=True)[source]

Transposes the matrix.

Note: This is a very slow operation. It is recommended to use the transpose() function from another matrix format instead.

Nothing is returned if the operation is in place.

Memory usage will change after this operation.

Parameters:: inplace (bool) – Whether to transpose the matrix in place. The default is True
Returns:: The transposed IVCSC matrix
Return type:: IVCSC

vectorLength(vector)[source]

Returns the euclidean length of the vector

Parameters:: vector (int) – The index of the vector to find the euclidean length of
Returns:: The euclidean length of the vector
Return type:: np.double
Raises:: IndexError – If the vector index is out of range

write(filename)[source]

Writes the matrix to a file. If the file name doesn’t include .vcsc, it will be appended.

Parameters:: filename (str) – The name of the file to write to
Return type:: None