TCSR

TCSR#

class brainevent.TCSR(source, *, backend=None, binary_backend=None, backward_algorithm='bptt')#

Represent a unit-aware sparse matrix in tiled CSR storage.

TCSR stores a logical matrix W with shape (num_pre, num_post) in a canonical tiled CSR structure. W.T is an O(1) logical view sharing the same values, tile metadata, workspaces, and lazily materialized TCSC mirror.

Parameters:

source (CSR) – Plain CSR whose column indices are nondecreasing within every row. Direct construction trusts this ordering and does not verify it.
backend (str | None) – Backend used by floating-point sparse operations.
binary_backend (str | None) – Backend used by event-driven binary sparse operations.
backward_algorithm (str) – Weight-gradient interpretation for floating event operands. Default is "bptt".

data#

Current-view compressed values. Heterogeneous storage has one value per entry; homogeneous storage has one shared value.

Type:: jax.Array or brainunit.Quantity

indices#

Current-view minor-axis coordinates.

Type:: jax.Array

indptr#

Current-view int64 row pointers.

Type:: jax.Array

shape#

Current logical matrix shape.

Type:: tuple[int, int]

nse#

Number of represented sparse entries.

Type:: int

Notes

Enable JAX x64 before construction: jax.config.update("jax_enable_x64", True). TCSR requires int64 row pointers for both canonical and mirror storage.

Use fromcsr() when CSR row ordering is unknown. Use direct construction or from_sorted_csr() only when every row is already sorted by nondecreasing column index.

For a logical shape (m, n), public matrix multiplication follows normal array conventions: W @ X accepts X.shape == (n, batch) and returns (m, batch), while X @ W accepts X.shape == (batch, m) and returns (batch, n). The same rule applies to W.T using its reversed logical shape. Internal neuron-batch and batch-neuron service layouts are selected automatically.

See also

fromcsr: Build from CSR while enforcing row-local ordering.
from_sorted_csr: Build from a CSR already known to be sorted.
brainevent.CSR: Plain compressed sparse row representation.

Examples

>>> import jax
>>> import jax.numpy as jnp
>>> import brainevent
>>> jax.config.update("jax_enable_x64", True)
>>> source = brainevent.CSR(
...     (
...         jnp.asarray([2.0, 1.0], dtype=jnp.float32),
...         jnp.asarray([1, 0], dtype=jnp.int32),
...         jnp.asarray([0, 2], dtype=jnp.int64),
...     ),
...     shape=(1, 2),
... )
>>> matrix = brainevent.TCSR.fromcsr(source)
>>> matrix.todense()
Array([[1., 2.]], dtype=float32)

property T: TCSR#

Return the transposed TCSR view.

Returns:: O(1) logical transpose sharing all underlying TCS storage.
Return type:: TCSR

See also

transpose: Method form with optional axes validation.

dt2t(y_dim_arr, w_dim_arr)[source]#

Expand logical row values over the current view’s sparse slots.

Parameters:

y_dim_arr (Array | ndarray | Quantity) – Logical row values with shape (self.shape[0],).
w_dim_arr (Array | ndarray | Quantity) – Per-slot values in the current view’s compressed order.

Returns:

Per-slot products in the same order as w_dim_arr.

Return type:

Array | Quantity

See also

dt2t_transposed: Expand logical column values over sparse slots.

dt2t_transposed(y_dim_arr, w_dim_arr)[source]#

Expand logical column values over the current view’s sparse slots.

Parameters:

y_dim_arr (Array | ndarray | Quantity) – Logical column values with shape (self.shape[1],).
w_dim_arr (Array | ndarray | Quantity) – Per-slot values in the current view’s compressed order.

Returns:

Per-slot products in the same order as w_dim_arr.

Return type:

Array | Quantity

See also

dt2t: Expand logical row values over sparse slots.

solve(b, *args, **kwargs)[source]#

Reject sparse solve until TCSR has a supported solver contract.

Parameters:

b (Array | ndarray | Quantity | Number) – Right-hand side supplied by the caller.
*args (Any) – Reserved positional solver options.
**kwargs (Any) – Reserved keyword solver options.

Raises:

NotImplementedError – Always, because TCSR solve is not implemented.

Return type:

Array | ndarray | Quantity | Number

tocsc()[source]#

Materialize the current logical matrix as a plain CSC matrix.

Returns:: Plain CSC matrix with the same logical values and shape.
Return type:: CSC

Notes

A canonical TCSR view materializes the shared TCSC mirror lazily. A transposed view can reuse canonical CSR structure directly. Homogeneous data remains a size-one value buffer.

transpose(axes=None)[source]#

Return a transposed TCSR view sharing the same storage.

Parameters:: axes (Any) – Accepted transpose axes. Only None and (1, 0) are valid.
Returns:: TCSR view with reversed logical shape and orientation state.
Return type:: TCSR
Raises:: ValueError – If axes does not describe a matrix transpose.

Notes

The returned view shares canonical values, tile metadata, workspace, and mirror state. No sparse coordinates are rebuilt.

update_on_post(pre_trace, post_spike, w_min=None, w_max=None)[source]#

Reject postsynaptic-triggered STDP until TCSR supports it.

Parameters:

pre_trace (Array | ndarray | Quantity | Number) – Presynaptic eligibility trace.
post_spike (Array | ndarray | Quantity | Number) – Postsynaptic spike vector.
w_min (Any) – Reserved lower clipping bound.
w_max (Any) – Reserved upper clipping bound.

Raises:

NotImplementedError – Always, because TCSR postsynaptic STDP is not implemented.

Return type:

Self

update_on_pre(pre_spike, post_trace, w_min=None, w_max=None)[source]#

Reject presynaptic-triggered STDP until TCSR supports it.

Parameters:

pre_spike (Array | ndarray | Quantity | Number) – Presynaptic spike vector.
post_trace (Array | ndarray | Quantity | Number) – Postsynaptic eligibility trace.
w_min (Any) – Reserved lower clipping bound.
w_max (Any) – Reserved upper clipping bound.

Raises:

NotImplementedError – Always, because TCSR presynaptic STDP is not implemented.

Return type:

Self

TCSR

Contents

TCSR#