BitPackedBinary

class brainevent.BitPackedBinary(arr)

Bit-packed binary event representation.

BitPackedBinary stores binary spike data as uint32 words where each word encodes 32 consecutive spikes. Packing is performed along every axis, so the number of packed arrays equals the number of dimensions.

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

Parameters:

arr (jax.Array) – The original binary spike array (bool or 0/1).

Notes

The class stores both the original spike array (value) and one packed uint32 representation per axis (packed). The original array is used for autodiff (gradient propagation), while the packed arrays are used for efficient CUDA kernel computation.

The class is registered as a JAX PyTree node, so it is compatible with jax.jit, jax.grad, jax.vmap, and other transformations.

See also

BinaryArray

Unpacked binary event representation.

BinaryArray.bitpack

Creates a BitPackedBinary from a BinaryArray.

property T

Transpose of the bit-packed binary array.

Returns:

A new transposed instance.

Return type:

BitPackedBinary

property ndim

Number of dimensions of the original array.

Returns:

Same as len(self.original_shape).

Return type:

int

property original_shape

Shape of the original (unpacked) boolean array.

Returns:

The shape before bit-packing.

Return type:

tuple[int, …]

property packed

Tuple of packed uint32 arrays, one per axis.

Returns:

packed[i] is the uint32 array obtained by packing along axis i. Its shape matches the original shape except that dimension i is ceil(original_shape[i] / 32).

Return type:

tuple[jax.Array, …]

property shape

Logical shape (original unpacked shape).

Returns:

The shape of the original boolean array, not the packed uint32 arrays. This makes BitPackedBinary shape-compatible with the original BinaryArray.

Return type:

tuple[int, …]

transpose(*axes)

Return a transposed BitPackedBinary.

Parameters:

*axes (int, optional) – Axis permutation. If omitted, reverses the axis order (standard transpose).

Returns:

A new instance with permuted axes. Both value and all packed arrays are transposed accordingly.

Return type:

BitPackedBinary

tree_flatten()

Flatten this instance for JAX PyTree serialisation.

Returns:

• children (tuple) – (value, packed[0], packed[1], ...) — the original spike array followed by packed uint32 arrays for each axis.

• aux_data (dict) – Contains original_shape.

classmethod tree_unflatten(aux_data, flat_contents)

Reconstruct a BitPackedBinary from its PyTree representation.

Parameters:

• aux_data (dict) – Static metadata produced by tree_flatten.

• flat_contents (tuple) – Dynamic leaves — the original spike array followed by packed uint32 arrays for each axis.

Returns:

A new instance wrapping all arrays.

Return type:

BitPackedBinary