CSC

CSC#

class brainevent.CSC(data, indices=None, indptr=None, *, shape, backend=None, buffers=None)#

Event-driven and Unit-aware Compressed Sparse Column (CSC) matrix.

This class represents a sparse matrix in CSC format, which is efficient for column-wise operations. It is compatible with JAX’s tree utilities and supports unit-aware computations.

The class supports arithmetic with scalars and dense arrays, plus sparse-dense matrix multiplication via @. Sparse-sparse operations are limited.

data#

Array of the non-zero values in the matrix.

Type:: Data

indices#

Array of row indices for the non-zero values.

Type:: jax.Array

indptr#

Array of column pointers indicating where each column starts in the data and indices arrays.

Type:: jax.Array

shape#

The shape of the matrix as (rows, columns).

Type:: tuple[int, int]

nse#

Number of stored elements (non-zero entries).

Type:: int

dtype#

Data type of the matrix values.

Type:: dtype

Notes

In CSC format a matrix of shape (m, n) is stored as three arrays:

indptr of length n + 1 – the j-th column occupies entries indptr[j] to indptr[j+1] in the data and indices arrays.
indices – row indices of the stored elements.
data – the corresponding non-zero values.

Internally, CSC operations are implemented by treating the underlying arrays as a CSR matrix with transposed shape and applying the appropriate transpose flags to the CSR kernels.

Examples

import jax.numpy as jnp
import brainevent

data    = jnp.array([1.0, 2.0, 3.0])
indices = jnp.array([0, 2, 1])
indptr  = jnp.array([0, 1, 2, 3])
csc     = brainevent.CSC((data, indices, indptr), shape=(3, 3))

# Sparse-dense matrix-vector product
x = jnp.ones(3)
y = csc @ x

See also

CSR: Compressed Sparse Row format.
brainevent.COO: Coordinate sparse format.

apply(fn)[source]#

Apply a unary function to the stored data values.

Creates a new CSC matrix with fn(self.data) while preserving the sparsity structure (indices, indptr, shape, and cached diagonal positions).

Parameters:: fn (callable) – A function that accepts a single array argument and returns an array of the same shape. The dtype and unit may differ from the input.
Returns:: A new CSC matrix with transformed data.
Return type:: CSC

Examples

squared = csc.apply(lambda x: x ** 2)

classmethod fromdense(mat, *, nse=None, index_dtype=<class 'jax.numpy.int32'>, backend=None)[source]#

Create a CSC (Compressed Sparse Column) matrix from a dense matrix.

This method converts a dense matrix to CSC format, which is an efficient storage format for sparse matrices.

Parameters:

mat (array_like) – The dense matrix to be converted to CSC format.
nse (int) – The number of non-zero elements in the matrix. If None, it will be calculated from the input matrix.
index_dtype (dtype, optional) – The data type to be used for index arrays (default is jnp.int32).

Returns:

A new CSC matrix instance created from the input dense matrix.

Return type:

CSC

Examples

import jax.numpy as jnp
import brainevent

dense = jnp.array([[1.0, 0.0], [0.0, 2.0]])
csc = brainevent.CSC.fromdense(dense)

solve(b, tol=1e-06, reorder=1)[source]#

Solve the linear system A x = b where A is this CSC matrix.

Delegates to the CSR solver by transposing the matrix.

Parameters:

b (Array | Quantity) – Right-hand side vector. Its first dimension must equal self.shape[0].
tol (float, optional) – Tolerance for singularity detection. Defaults to 1e-6.
reorder (int, optional) – Fill-reducing reordering scheme: 0 for no reordering, 1 for symrcm, 2 for symamd, 3 for csrmetisnd. Defaults to 1.

Returns:

Solution vector x satisfying A x = b.

Return type:

Array | Quantity

Raises:

AssertionError – If b.shape[0] != self.shape[0].

Examples

x = csc.solve(b)

tocoo()[source]#

Convert the CSC matrix to COO (Coordinate) format.

This method transforms the Compressed Sparse Column (CSC) matrix into a COO matrix, which stores sparse data as a collection of (row, column, value) triplets.

Returns:: A COO matrix containing the same data as the original CSC matrix.
Return type:: COO

See also

brainevent.COO: The Coordinate sparse matrix class.

Examples

csc_matrix = CSC((data, indices, indptr), shape=(3, 4))
coo_matrix = csc_matrix.tocoo()

todense()[source]#

Convert the CSC matrix to a dense matrix.

Transposes the underlying CSR-style storage, converts to dense, and transposes back.

Returns:: A dense matrix of shape self.shape containing all the values (including zeros) of the sparse matrix.
Return type:: Array | Quantity

Examples

dense = csc.todense()

transpose(axes=None)[source]#

Transpose the CSC matrix.

Returns the transpose as a CSR matrix. Because the transpose of a CSC matrix is a CSR matrix with the same underlying arrays, this operation is essentially free.

Parameters:: axes (None) – Must be None. Included for API compatibility with NumPy.
Returns:: The transpose of the CSC matrix as a CSR (Compressed Sparse Row) matrix.
Return type:: CSR
Raises:: AssertionError – If axes is not None.

Examples

csr = csc.transpose()
# or equivalently:
csr = csc.T

with_data(data)[source]#

Create a new CSC matrix with updated data while keeping the same structure.

This method creates a new CSC matrix instance with the provided data, maintaining the original indices, indptr, and shape.

Parameters:: data (Array | ndarray | Quantity | Number) – The new data array to replace the existing data in the CSC matrix. It must have the same shape, dtype, and unit as the original data.
Returns:: A new CSC matrix instance with updated data and the same structure as the original.
Return type:: CSC
Raises:: AssertionError – If the shape, dtype, or unit of the new data doesn’t match the original data.

Examples

new_data = jnp.array([10.0, 20.0, 30.0])
new_csc = csc.with_data(new_data)

yw_to_w(y_dim_arr, w_dim_arr)[source]#

Compute a sparse transformation from y-w space to w space.

Performs a specialised sparse matrix-vector product optimised for event-driven neural simulations. The CSC storage is treated as a transposed CSR matrix, so this method calls the CSR kernel with shape=self.shape[::-1] and transpose=True.

Parameters:

y_dim_arr (Array | ndarray | Quantity) – Values in the target (post-synaptic) dimension.
w_dim_arr (Array | ndarray | Quantity) – Per-synapse weight values.

Returns:

Accumulated result, preserving physical units when present.

Return type:

Array | Quantity

See also

yw_to_w_transposed: The transposed (adjoint) variant.

Notes

Internally calls csrmv_yw2y with transpose=True and reversed shape to account for the column-oriented storage format.

yw_to_w_transposed(y_dim_arr, w_dim_arr)[source]#

Compute the transposed sparse transformation from y-w space to w space.

This is the adjoint of yw_to_w(), useful for back-propagation or adjoint computations in event-driven neural simulations. Uses transpose=False with the reversed shape to compute the appropriate transposed operation for CSC storage.

Parameters:

y_dim_arr (Array | ndarray | Quantity) – Values in the target (post-synaptic) dimension.
w_dim_arr (Array | ndarray | Quantity) – Per-synapse weight values.

Returns:

Accumulated result of the transposed operation, preserving physical units when present.

Return type:

Array | Quantity

See also

yw_to_w: The forward (non-transposed) variant.

Notes

Internally calls csrmv_yw2y with transpose=False and reversed shape.

CSC

Contents

CSC#