mixle.engines.bitpacked module

Packed binary / ternary COMPUTE: exact {-1,+1} and {-1,0,+1} dot products via popcount.

The one sub-byte path that is real arithmetic (not dequant-then-fp32): pack a vector to bits and a . b = D - 2*popcount(a XOR b) (binary) / a two-plane popcount (ternary). The hardware popcount does 64 lanes per instruction with no rounding, and the packed data is 32x smaller than float64.

Performance depends on the fp32 baseline. On Apple silicon, cache-resident GEMM goes through the AMX matrix coprocessor (Accelerate BLAS), which can make this popcount kernel slower; the advantage there is storage and bandwidth rather than compute. On CPUs without a matrix unit, memory-bound problems, or native binary/ternary models where fp32 wastes 32x the bytes, it can be a compute win. The kernel is always exact; select it for the measured regime. The compiled extension is optional (build_kernels.compile_bitpacked_kernels); a correct but slower numpy bitwise_count fallback runs when it is absent.

pack_pm1(x)

Pack a {-1,+1} (or {0,1}) array’s rows to uint64 words; last axis padded to a 64-multiple.

Parameters:

x (Any)

Return type:

ndarray

binary_gemm(a_packed, b_packed, dim)

Exact A @ B.T for {-1,+1} matrices packed by pack_pm1().

a_packed is (N, words) packed rows of A, b_packed is (M, words) packed rows of B (the operand whose columns are dotted), dim is the true bit length. Returns int32 (N, M).

Both operands’ rank, packed word count, and word count implied by dim are validated up front: the compiled kernel derives its loop bound from a_packed alone and has no way to notice a shorter b_packed on its own (MXR-080-0131), so a caller-visible ValueError here is what stands between a mismatched pair and an out-of-bounds read in the nogil kernel.

Parameters:

• a_packed (Any)

• b_packed (Any)

• dim (int)

Return type:

ndarray

binary_dot(a, b)

Exact dot products of a batch of {-1,+1} vectors a (N, D) against b (M, D). Returns (N, M).

Parameters:

• a (Any)

• b (Any)

Return type:

ndarray

ternary_gemm(a_sign, a_nz, b_sign, b_nz)

Exact {-1,0,+1} A @ B.T from packed sign + nonzero-mask bit-planes (compiled path only).

Each operand’s sign and nonzero-mask planes must have identical shape (they describe the same rows), and the two operands’ packed word counts must match. The compiled kernel derives its loop bound from a_sign alone and indexes into the other three planes without any bounds check of its own (MXR-080-0131), so this validation is what turns a shorter plane into a clean exception instead of an out-of-bounds read.

Parameters:

• a_sign (Any)

• a_nz (Any)

• b_sign (Any)

• b_nz (Any)

Return type:

ndarray

pack_ternary(x)

Pack a {-1,0,+1} array’s rows into (sign, nonzero) bit-plane uint64 words for ternary_gemm().

Parameters:

x (Any)

Return type:

tuple[ndarray, ndarray]