veloxquant_mlx.dsa.bit_pack module¶
Manual sub-byte bit packing for compact codebook index storage.
Provides BitPackBuffer, which packs arrays of 1/2/3/4-bit unsigned
codebook indices into dense uint8 byte arrays (and unpacks them back),
using hand-rolled bit manipulation rather than a third-party bitstream
library. This is what lets low-bit quantizers (e.g. 2-bit, 3-bit codebooks)
actually realize their target storage footprint instead of padding every
index out to a full byte; see veloxquant_mlx.handlers.bit_pack_handler
for the pipeline stage that drives it.
- class veloxquant_mlx.dsa.bit_pack.BitPackBuffer(b)[source]¶
Bases:
objectCompact buffer that packs b-bit unsigned integers into uint8 bytes.
Supports b ∈ {1, 2, 3, 4}. All bit manipulation is implemented manually.
For non-power-of-2 bit widths (b=3), 8 values fit exactly in 3 bytes: each group of 8 values is packed into 3 bytes (24 bits / 3 bits = 8 values).
- Parameters:
b (
int) – Bits per element. Must be one of {1, 2, 3, 4}.- Raises:
ValueError – If b is not in {1, 2, 3, 4}.
- pack(indices)[source]¶
Pack an array of b-bit unsigned integers into bytes.
- Parameters:
indices (
ndarray) – Array of uint8 values in range [0, 2^b). Shape (n,).- Return type:
- Returns:
Packed uint8 array. Length is ceil(n * b / 8).
- Raises:
ValueError – If any value exceeds 2^b - 1.