CompactBinary

CompactBinary#

class brainevent.CompactBinary(packed, active_ids, n_active, value, n_orig, batch_size=None, bit_width=32)#

Binary event representation with bitpack and stream compaction.

Combines two compression strategies for binary (0/1) spike data:

  • Bitpack: Packs 32 binary values into each uint32 word.

  • Compaction: Extracts indices of active (non-zero) elements into a contiguous list, enabling scatter kernels to skip inactive rows.

For 1D input (n,):

  • Bitpack along axis 0: packed shape (ceil(n/32),)

  • Compaction: indices of non-zero elements

For 2D input (n, batch_size):

  • Bitpack along axis 1 (batch): packed shape (n, ceil(batch_size/32))

  • Compaction along axis 0 (feature): indices of rows active in ANY batch

Instances are typically created via from_array() rather than direct construction.

Parameters:

  • packed (jax.Array) – Bit-packed uint32 data.

  • active_ids (jax.Array) – Int32 array of active element indices, shape (n_orig,).

  • n_active (jax.Array) – Int32 scalar (shape (1,)) count of active elements.

  • value (jax.Array) – Original dense binary array (for autodiff).

  • n_orig (int) – Original feature dimension size.

  • batch_size (int or None) – Batch dimension size, or None for 1D input.

  • bit_width (int) – Bit width for packing (32).

See also

BitPackedBinary

Bit-packed only (no compaction).

property active_ids#

Indices of active elements.

Returns:

Shape (n_orig,), int32. Only [:n_active] entries valid.

Return type:

jax.Array

property batch_size#

Batch dimension size, or None for 1D.

Return type:

int or None

property bit_width#

Bit width for packing (32).

Return type:

int

classmethod compacy_only_vector(x)[source]#

Create a 1D compact-only CompactBinary without bit-packing.

This constructor is intended for the compact_only_vector FCN-MV scatter backend, which consumes only active_ids / n_active and does not read packed. The returned object uses a zero-length uint32 sentinel for packed so that packed-dependent paths can reject it explicitly.

Parameters:

x (jax.Array) – 1D binary spike vector. Non-zero values are treated as active.

Returns:

Compact-only event representation for a 1D spike vector.

Return type:

CompactBinary

property dtype#

Dtype of the original array.

Return type:

jnp.dtype

classmethod from_array(x, bit_width=32)[source]#

Create a CompactBinary from a raw binary array.

Parameters:

  • x (jax.Array) – Binary array of shape (n,) or (n, batch_size). Non-zero values are treated as 1.

  • bit_width (int, optional) – Bit width for packing. Must be 32.

Returns:

New instance with bitpack and compaction data.

Return type:

CompactBinary

Raises:

ValueError – If x is not 1D or 2D, or bit_width is not 32.

classmethod from_array_light(x, bit_width=32)[source]#

Create a CompactBinary with deferred compaction.

For 1D input, skips computing active_ids / n_active (uses zeros). This is faster under jax.vmap because the MV→MM batching rule recomputes compaction for the merged matrix.

For 2D input, identical to from_array().

Parameters:

  • x (jax.Array) – Binary array of shape (n,) or (n, batch_size).

  • bit_width (int, optional) – Must be 32.

Return type:

CompactBinary

classmethod from_packed(packed, active_ids, n_active, value, n_orig, batch_size=None, bit_width=32)[source]#

Construct from pre-computed bitpack and compaction data.

Parameters:

  • packed (jax.Array) – Pre-computed bit-packed uint32 array.

  • active_ids (jax.Array) – Pre-computed active indices, int32, shape (n_orig,).

  • n_active (jax.Array) – Pre-computed active count, int32, shape (1,).

  • value (jax.Array) – Original dense binary array.

  • n_orig (int) – Original feature dimension.

  • batch_size (int or None) – Batch size, or None for 1D.

  • bit_width (int) – Must be 32.

Return type:

CompactBinary

property n_active#

Number of active elements.

Returns:

Shape (1,), int32.

Return type:

jax.Array

property n_orig#

Original feature dimension size.

Return type:

int

property ndim#

Number of dimensions of the original array.

Return type:

int

property packed#

Bit-packed uint32 data.

Returns:

Shape (n_words,) for 1D or (n_orig, batch_words) for 2D.

Return type:

jax.Array

property shape#

Logical shape of the original array.

Return type:

tuple[int, …]

property size#

Total number of elements in the original array.

Return type:

int

to_dense()[source]#

Reconstruct the original dense binary array.

Returns:

The original dense array stored during construction.

Return type:

jax.Array

property value#

Original dense binary array (for autodiff).

Return type:

jax.Array