brainevent.binary_coomv

Contents

brainevent.binary_coomv#

brainevent.binary_coomv = <NameScope(brainevent.binary_coomv)>#

Perform event-driven COO sparse matrix-vector multiplication.

Computes the product of a sparse matrix stored in COO (Coordinate) format and a dense vector, where the vector v is treated as containing binary events (spikes). Only entries corresponding to active (nonzero / True) events contribute to the output, making this operation efficient for spike-based neural network simulations.

Mathematically, with transpose=False the operation is

result[i] = sum_j A[i, j] * (v[j] > 0)

and with transpose=True:

result[j] = sum_i A[i, j] * (v[i] > 0)

where A is the sparse matrix defined by (data, row, col).

Parameters:

  • data (Array | ndarray | Quantity | Number) – The non-zero weight values of the sparse matrix. Can be either a scalar (shape (1,), homogeneous weights) or a 1-D array of length nnz (heterogeneous weights).

  • row (Array | ndarray) – 1-D array of row indices for each non-zero element, with length nnz.

  • col (Array | ndarray) – 1-D array of column indices for each non-zero element, with length nnz.

  • v (Array | ndarray | Quantity | Number) – Dense input vector treated as binary events. Elements are interpreted as active when True (boolean dtype) or > 0 (numeric dtype). Shape must be (shape[0],) when transpose=True or (shape[1],) when transpose=False.

  • shape (Tuple[int, int]) – The (m, k) shape of the sparse matrix.

  • transpose (bool) – If True, multiply by the transpose of the sparse matrix, i.e. A^T @ v. Default is False.

  • backend (str | None) – Compute backend to use (e.g. 'numba', 'pallas'). When None the backend is chosen automatically.

Returns:

Result vector of the matrix-vector product. Shape is (shape[0],) when transpose=False or (shape[1],) when transpose=True.

Return type:

Array | ndarray | Quantity | Number

Raises:

ValueError – If row or col are not 1-D, have mismatched lengths, v is not 1-D, data is not scalar or 1-D, or array dimensions are incompatible with shape and transpose.

See also

binary_coomm

Event-driven COO sparse matrix-matrix multiplication.

coomv

Standard (non-event-driven) COO sparse matrix-vector multiplication.

Notes

Physical units attached via brainunit are automatically split off before the computation and re-applied to the result.

This function supports automatic differentiation (JVP and transpose rules), vmap batching, and multiple hardware backends (CPU via Numba, GPU via Pallas/Triton, TPU via Pallas/Mosaic).

Examples

>>> import jax.numpy as jnp
>>> from brainevent._coo.binary import binary_coomv
>>> data = jnp.array([0.5])          # homogeneous weight
>>> row = jnp.array([0, 1, 2])
>>> col = jnp.array([1, 0, 2])
>>> v = jnp.array([True, False, True])  # binary events
>>> binary_coomv(data, row, col, v, shape=(3, 3), transpose=False)
Contents