lacuna.sparse.coond#

N-dimensional COO sparse array (COOND) backed by a Rust core.

This module exposes the COOND class, a Pythonic façade over ND-COO kernels implemented in Rust and bound via PyO3. Indices are stored as int64 and flattened to length nnz * ndim (or accepted as a 2D (nnz, ndim) array), and values are float64 in v0.1.

Notes

  • Operations release the GIL and call from-parts bindings in lacuna._core.

  • Duplicates in indices are allowed; aggregation is performed by operations (e.g., reductions or toarray materialization).

  • When check=True, basic invariants are validated via the native layer.

Contents#

  • COOND: construction, sum/mean, axis reductions/permute, reshape, broadcasting Hadamard, unfolding to CSR/CSC.

Classes

COOND(shape, indices, data[, dtype, check])

N-dimensional sparse array in COO format.
class lacuna.sparse.coond.COOND(shape, indices, data, dtype=<class 'numpy.float64'>, check=True)[source]#

Bases: SparseArray

N-dimensional sparse array in COO format.

Parameters:

  • shape (tuple[int, ...]) – Overall tensor shape of length ndim.

  • indices (array_like of int64, shape (nnz * ndim,) or (nnz, ndim)) – Concatenated per-nnz indices or a 2D array; values must be within bounds of shape. Duplicates are allowed (aggregated by ops).

  • data (array_like of float64, shape (nnz,)) – Nonzero values.

  • dtype (numpy.dtype, optional) – Value dtype, defaults to np.float64.

  • check (bool, optional) – If True, validate invariants in the native layer where applicable.

shape#

Tensor dimensions.

Type:

tuple[int, …]

ndim#

Number of dimensions (len(shape)).

Type:

int

indices#

Flattened indices of length nnz * ndim.

Type:

numpy.ndarray (int64)

data#

Nonzero values of length nnz.

Type:

numpy.ndarray (float64)

nnz#

Number of stored elements.

Type:

int

Notes

Backed by Rust ND-COO kernels via lacuna._core. Operations release the GIL. Key operations include sum, mean, axis reductions/permutations, reshape, broadcasting Hadamard multiply, and unfolding to CSR/CSC.

Examples

Construct a small 3D tensor and run basic ops:

>>> import numpy as np
>>> from lacuna.sparse import COOND
>>> shape = (2, 3, 4)
>>> # 2 nonzeros at positions (0,1,2) and (1,2,3)
>>> idx = np.array([
...     0, 1, 2,
...     1, 2, 3,
... ], dtype=np.int64)
>>> val = np.array([1.0, 3.0])
>>> a = COOND(shape, idx, val)
>>> a.nnz
2
>>> a.sum()
4.0
>>> a.reduce_sum_axes([2]).shape  # sum over last axis
(2, 3)
>>> a.permute_axes([2, 1, 0]).shape
(4, 3, 2)
>>> b = a.reshape((3, 2, 4))
>>> (a.hadamard_broadcast(b)).nnz
2
>>> a.mode_unfold_to_csr(axis=0).shape
(2, 12)
axes_unfold_to_csc(row_axes)[source]#

Unfold by grouping selected axes as CSC rows (the rest become columns).

axes_unfold_to_csr(row_axes)[source]#

Unfold by grouping selected axes as CSR rows and the rest as columns.

Parameters:

row_axes (array_like of int) – Axes that form the row index in the unfolded matrix.

Returns:

A CSR matrix.

Return type:

CSR

classmethod from_arrays(shape, indices, data, check=True)[source]#

Construct COOND from raw arrays.

Parameters:

  • shape (tuple[int, ...]) – Tensor shape.

  • indices (array_like of int64) – Flattened or 2D indices (nnz x ndim).

  • data (array_like of float64) – Nonzero values.

  • check (bool, optional) – Validate invariants via native layer when possible.

hadamard_broadcast(other)[source]#

Elementwise product with broadcasting against another COOND.

Parameters:

other (COOND) – Right-hand operand.

Returns:

Result of broadcasting Hadamard multiplication.

Return type:

COOND

mean()[source]#

Mean of all entries (sum / total elements implied by shape).

mode_unfold_to_csc(axis)[source]#

Unfold along a single mode into a 2D CSC matrix.

Parameters:

axis (int) – Mode (axis) to place along the columns; remaining modes are flattened as rows.

Returns:

A CSC matrix of shape (prod(shape[~axis]), shape[axis]).

Return type:

CSC

mode_unfold_to_csr(axis)[source]#

Unfold along a single mode into a 2D CSR matrix.

Parameters:

axis (int) – Mode (axis) to place along the rows; remaining modes are flattened as columns.

Returns:

A CSR matrix of shape (shape[axis], prod(shape[~axis])).

Return type:

CSR

property nnz#

Number of stored values.

permute_axes(perm)[source]#

Permute axes by the given permutation.

Parameters:

perm (array_like of int) – A permutation of range(ndim).

Returns:

Tensor with permuted axes.

Return type:

COOND

reduce_mean_axes(axes)[source]#

Mean over specified axes.

Parameters:

axes (array_like of int) – Axes to average over.

Returns:

A new tensor with the given axes averaged out.

Return type:

COOND

reduce_sum_axes(axes)[source]#

Sum over specified axes.

Parameters:

axes (array_like of int) – Axes to reduce. Order-insensitive, must be valid axes of shape.

Returns:

A new tensor with the given axes summed out.

Return type:

COOND

reshape(new_shape)[source]#

Return a new tensor with the same data but a different shape.

Parameters:

new_shape (tuple[int, ...]) – Target shape; must be compatible with shape.

sum()[source]#

Sum of all entries.

Returns:

Total sum of nonzero values.

Return type:

float