lacuna.sparse.csr#

Sparse CSR matrix implementation backed by a Rust core.

This module exposes a minimal, NumPy-friendly CSR matrix class with high-performance kernels delegated to a PyO3-bound Rust extension.

Notes

  • Index arrays (indptr, indices) are stored as int64 and validated (when check=True) against structural invariants expected by the Rust core.

  • Data is stored as float64 in v0.1.

  • Most computational methods call into the Rust core when available; if the core is not available, a RuntimeError is raised.

Classes

CSR(indptr, indices, data, shape[, dtype, check])

Compressed Sparse Row (CSR) matrix.
class lacuna.sparse.csr.CSR(indptr, indices, data, shape, dtype=<class 'numpy.float64'>, check=True)[source]#

Bases: SparseMatrix

Compressed Sparse Row (CSR) matrix.

Parameters:

  • indptr (array-like of int64, shape (n_rows + 1,)) – Row pointer array. Must be non-decreasing, start at 0, end at nnz.

  • indices (array-like of int64, shape (nnz,)) – Column indices for each non-zero. Must be strictly increasing within each row.

  • data (array-like of float64, shape (nnz,)) – Non-zero values.

  • shape (tuple[int, int]) – Matrix shape (n_rows, n_cols).

  • dtype (numpy.dtype, optional (default: np.float64)) – Data dtype (v0.1 supports float64 only).

  • check (bool, optional (default: True)) – When True, validate structural invariants using the Rust core.

Notes

The constructor may raise if the structure is invalid when check=True.

Examples

Construct a small CSR and run basic ops:

>>> import numpy as np
>>> from lacuna.sparse import CSR
>>> indptr = np.array([0, 2, 3])  # 2 rows, 3 nnz
>>> indices = np.array([0, 2, 1])
>>> data = np.array([1.0, 3.0, 2.0])
>>> a = CSR(indptr, indices, data, shape=(2, 3))
>>> a.nnz
3
>>> (a @ np.array([1.0, 0.0, 1.0])).tolist()  # SpMV
[4.0, 2.0]
>>> a.sum()
6.0
property T#

Transpose of the matrix (CSR).

Returns:

Transposed matrix as a new CSR instance.

Return type:

CSR

Raises:

RuntimeError – If the native core is not available.

astype(dtype)[source]#

Return a copy converted to the given dtype.

Parameters:

dtype (numpy.dtype or str) – Target dtype. v0.1 supports float64 only.

Returns:

A new CSR with data cast to the requested dtype.

Return type:

CSR

Raises:

NotImplementedError – If dtype is not float64 in v0.1.

classmethod diag(diagonal, dtype=<class 'numpy.float64'>)[source]#

Create a diagonal matrix in CSR format.

Parameters:

  • diagonal (array-like) – Diagonal values.

  • dtype (numpy.dtype, optional) – Data type (default: np.float64).

Returns:

Diagonal matrix.

Return type:

CSR

Examples

>>> D = CSR.diag([1.0, 2.0, 3.0])
>>> D.nnz
3
>>> D.sum()
6.0
divide(other)[source]#
eliminate_zeros()[source]#

Remove exact zeros from the matrix structure.

Returns:

New CSR with all zero entries removed.

Return type:

CSR

Raises:

RuntimeError – If the native core is not available.

classmethod eye(n, dtype=<class 'numpy.float64'>)[source]#

Create an identity matrix in CSR format.

Parameters:

  • n (int) – Size of the square identity matrix.

  • dtype (numpy.dtype, optional) – Data type (default: np.float64).

Returns:

Identity matrix of size n×n.

Return type:

CSR

Examples

>>> I = CSR.eye(5)
>>> I.nnz
5
>>> I.sum()
5.0
floor_divide(other)[source]#
classmethod from_arrays(indptr, indices, data, shape, check=True)[source]#

Construct a CSR from raw arrays.

Parameters:

  • indptr – See CSR.__init__.

  • indices – See CSR.__init__.

  • data – See CSR.__init__.

  • shape – See CSR.__init__.

  • check – See CSR.__init__.

Returns:

New CSR instance.

Return type:

CSR

multiply(other)[source]#
property nnz#

Number of stored non-zero entries (int).

power(other)[source]#
prune(eps)[source]#

Remove entries with absolute value <= eps.

Parameters:

eps (float) – Threshold for pruning.

Returns:

New CSR with pruned entries.

Return type:

CSR

Raises:

RuntimeError – If the native core is not available.

remainder(other)[source]#
sign()[source]#
sum(axis=None)[source]#

Sum elements along the given axis using the Rust core.

Parameters:

axis ({None, 0, 1}, optional) – None for total sum (scalar), 0 for column sums (length = ncols), 1 for row sums (length = nrows).

Returns:

Scalar for total sum, 1D array for axis-specific sums.

Return type:

float or numpy.ndarray

Raises:
toarray()[source]#

Materialize the sparse matrix as a dense numpy.ndarray.

Returns:

Dense array of shape self.shape with the same dtype as data.

Return type:

numpy.ndarray

classmethod zeros(shape, dtype=<class 'numpy.float64'>)[source]#

Create a CSR matrix filled with zeros (empty sparse matrix).

Parameters:

  • shape (tuple of int) – Matrix shape (nrows, ncols).

  • dtype (numpy.dtype, optional) – Data type (default: np.float64).

Returns:

Empty sparse matrix (no non-zero elements).

Return type:

CSR

Examples

>>> A = CSR.zeros((10, 20))
>>> A.nnz
0
>>> A.shape
(10, 20)