Dense

class brainevent.Dense(data, *, shape=None, backend=None, buffers=None)

Unit-aware explicit dense matrix.

Dense stores a full two-dimensional weight matrix and exposes the same representation contract as the sparse matrix families. It is useful when a caller wants matrix metadata, backend selection, plasticity helpers, and event-driven binary matmul dispatch without converting the matrix to CSR or CSC format.

The class is a JAX pytree with a single dynamic leaf, data. Static metadata such as shape, backend, and registered buffers are carried in the pytree auxiliary data so Dense can be passed through jax.jit in the same style as CSR and CSC.

Parameters:

• data (array_like or brainunit.Quantity) – Dense two-dimensional matrix data. Units are preserved.

• shape (Sequence[int] | None) – Explicit matrix shape. When provided it must match data.shape.

• backend (str | None) – Backend attached to event-driven binary matmul and plasticity calls. Typical values are None, 'jax_raw', 'cuda_raw', and 'cublas' where supported.

• buffers (Dict | None) – Named auxiliary buffers to carry with the representation.

data

Full dense matrix data.

Type:

Data

shape

Matrix shape (rows, columns).

Type:

tuple[int, int]

backend

Backend preference propagated to dense binary primitives.

Type:

str or None

nse

Number of stored entries. For a dense matrix this is data.size.

Type:

int

dtype

Data type of the matrix values.

Type:

dtype

Notes

Dense @ BinaryArray and BinaryArray @ Dense dispatch to the event-driven dense binary primitives. Dense numeric operands fall back to ordinary JAX matrix multiplication with unit-aware dtype promotion.

The per-synapse dt2t protocol is intentionally not implemented directly for explicit dense matrices. Materialise a sparse representation first, for example dense.tocsr().dt2t(y, dense.tocsr().data), when a per-stored synapse output is required.

Examples

import jax.numpy as jnp
import brainevent

weights = jnp.array([[1.0, 0.0], [2.0, 3.0]])
dense = brainevent.Dense(weights, backend='jax_raw')
spikes = brainevent.BinaryArray(jnp.array([True, False]))

y = dense @ spikes

See also

CSR

Compressed sparse row representation.

CSC

Compressed sparse column representation.

binary_densemv

Dense matrix-vector event primitive.

binary_densemm

Dense matrix-matrix event primitive.

apply(fn)

Apply fn to the dense data and wrap the result as Dense.

Return type:

Dense

apply2(other, fn, *, reverse=False)

Apply a binary elementwise operation while preserving metadata.

diag_add(other)

Add values to the main diagonal and return a new Dense.

other must have length min(self.shape). Units are handled by the underlying jax.Array / brainunit.Quantity addition.

Return type:

Dense

dt2t(y_dim_arr, w_dim_arr)

Report that direct dense dt2t is not implemented.

The dense representation has no compressed per-synapse storage order to target. Convert to CSR/CSC first when a per-synapse w * y output is required.

Return type:

Array | Quantity

dt2t_transposed(y_dim_arr, w_dim_arr)

Report that direct transposed dense dt2t is not implemented.

Convert to CSR/CSC first when a per-synapse w * y output indexed by columns is required.

Return type:

Array | Quantity

classmethod fromdense(mat, *, backend=None, buffers=None)

Create a Dense representation from an explicit dense matrix.

Parameters:

• mat (array_like or brainunit.Quantity) – Two-dimensional matrix to wrap.

• backend (str | None) – Backend preference attached to the resulting representation.

• buffers (Dict | None) – Named buffers to register on the resulting representation.

Returns:

A new dense matrix representation containing mat.

Return type:

Dense

slice_rows(index)

Return selected rows as a new Dense matrix.

Return type:

Dense

solve(b, tol=1e-06, reorder=1)

Solve the dense linear system self @ x = b.

The tol and reorder parameters are accepted for API parity with sparse solvers and are currently unused. Units are propagated as unit(b) / unit(self.data).

Return type:

Array | Quantity

tocoo()

Convert the dense matrix to COO through the CSR conversion path.

tocsc(*, nse=None, index_dtype=<class 'jax.numpy.int32'>, precompute_weight_indices=False)

Convert the dense matrix to CSC.

Parameters mirror brainevent.CSC.fromdense(); backend is propagated from this Dense instance.

tocsr(*, nse=None, index_dtype=<class 'jax.numpy.int32'>, precompute_weight_indices=False)

Convert the dense matrix to CSR.

Parameters mirror brainevent.CSR.fromdense(); backend is propagated from this Dense instance.

todense()

Return the explicit dense matrix data.

Unlike sparse representations, no materialisation is needed because the storage format is already dense.

Return type:

Array | Quantity

transpose(axes=None)

Return self.T as a new Dense representation.

Only the standard matrix transpose is supported; axes must be None to match the two-dimensional data contract.

Return type:

Dense

tree_flatten()

Return pytree children and static metadata for JAX transformations.

classmethod tree_unflatten(aux_data, children)

Rebuild a Dense instance from pytree leaves and metadata.

update_on_post(pre_trace, post_spike, w_min=None, w_max=None)

Apply a post-spike-triggered dense plasticity update.

Returns a new Dense with updated data and the same metadata.

Return type:

Dense

update_on_pre(pre_spike, post_trace, w_min=None, w_max=None)

Apply a pre-spike-triggered dense plasticity update.

Returns a new Dense with updated data and the same metadata.

Return type:

Dense

with_data(data)

Return a new Dense with replacement data and unchanged metadata.

The replacement must preserve shape, dtype, and physical unit. This is the dense analogue of CSR.with_data: only values change, while backend and buffers are carried forward.

Return type:

Dense