Skip to content

Run frontier MoE models on hardware you already own β€” pure C, zero deps, experts streamed from disk. Tiny engine, immense model. 🐦

C

engine: fmt=6 E8/IQ3 lattice container β€” CPU decode kernel and dispatch (#452 step 3)

ZacharyZcRc45a8820dda8
diff --git a/c/Makefile b/c/Makefile
index 06fe176e..8c651c95 100644
--- a/c/Makefile
+++ b/c/Makefile
@@ -171,7 +171,7 @@ else
PYTHON ?= python3
endif
CUDA_OBJ =
-TEST_BINS = tests/test_json$(EXE) tests/test_st$(EXE) tests/test_st_pread$(EXE) tests/test_tier$(EXE) tests/test_grammar$(EXE) tests/test_schema_gbnf$(EXE) tests/test_decode_batch$(EXE) tests/test_idot$(EXE) tests/test_i4_grouped$(EXE) tests/test_stops$(EXE) tests/test_topp$(EXE) tests/test_sample_nan$(EXE) tests/test_tok_o200k$(EXE) tests/test_kv_alloc$(EXE) tests/test_int3$(EXE) tests/test_int3_load$(EXE) tests/test_i4_acc512$(EXE) tests/test_compat_direct$(EXE) tests/test_dsa_select$(EXE) tests/test_logit_nan$(EXE) tests/test_pipe_block$(EXE)
+TEST_BINS = tests/test_json$(EXE) tests/test_st$(EXE) tests/test_st_pread$(EXE) tests/test_tier$(EXE) tests/test_grammar$(EXE) tests/test_schema_gbnf$(EXE) tests/test_decode_batch$(EXE) tests/test_idot$(EXE) tests/test_i4_grouped$(EXE) tests/test_stops$(EXE) tests/test_topp$(EXE) tests/test_sample_nan$(EXE) tests/test_tok_o200k$(EXE) tests/test_kv_alloc$(EXE) tests/test_int3$(EXE) tests/test_int3_load$(EXE) tests/test_i4_acc512$(EXE) tests/test_compat_direct$(EXE) tests/test_dsa_select$(EXE) tests/test_logit_nan$(EXE) tests/test_pipe_block$(EXE) tests/test_e8_kernel$(EXE)
ifneq (,$(LINUX))
TEST_BINS += tests/test_uring$(EXE)
endif
@@ -343,6 +343,11 @@ tests/test_sample_nan$(EXE): tests/test_sample_nan.c colibri.c st.h uring.h json
tests/test_kv_alloc$(EXE): tests/test_kv_alloc.c colibri.c st.h json.h tok.h tok_unicode.h compat.h grammar.h tier.h quant.h sample.h kv_persist.h telemetry.h
$(CC) $(CFLAGS) $< -o $@ $(LDFLAGS)
+# fmt=6 kernel oracle: needs the generated grid table, and its fixture comes from
+# the reference codec (tools/make_e8_fixture.py) β€” regenerate if the layout moves.
+tests/test_e8_kernel$(EXE): tests/test_e8_kernel.c quant.h
+ $(CC) $(CFLAGS) $< -o $@ $(LDFLAGS)
+
tests/test_int3$(EXE): tests/test_int3.c colibri.c st.h uring.h json.h tok.h tok_unicode.h compat.h grammar.h tier.h quant.h sample.h kv_persist.h telemetry.h
$(CC) $(CFLAGS) $< -o $@ $(LDFLAGS)
diff --git a/c/colibri.c b/c/colibri.c
index ef32b016..f2b057a8 100644
--- a/c/colibri.c
+++ b/c/colibri.c
@@ -97,6 +97,9 @@ typedef struct {
/* fmt: 0 F32, 1 INT8, 2 INT4 (2/byte), 3 INT2 (4/byte), 4 INT4-GROUPED, 5 INT3-G64.
* q4 ospita int4/int2/int3 packed. fmt=4 (grouped int4, #242): per-row nibbles + one f32
* scale per group of `gs` inputs (s has O*ceil(I/gs) entries).
+ * fmt=6 (E8/IQ3 lattice, #452): 98B per 256 weights = 3.0625 bits/weight, grid
+ * indices + parity-packed signs + sub-scales + fp16 super-scale, ALL inside q4 β€”
+ * `s` is unused for this format (see quant.h E8_* and tools/iq3_pack.py).
* fmt=5 (int3, per-GROUP scales, group=64, see quant.h I3_*): values in [-4,3] stored per
* 64-input group as 24 bytes = 16B low plane (2 bits/val, int2 layout) + 8B high plane
* (1 bit/val), plus ONE f32 scale PER GROUP (s has O*ceil(I/64) entries, not O). 3.5
@@ -467,6 +470,7 @@ static void matmul_qt_ex(float *y, const float *x, QT *w, int S, int allow_idot)
#endif
if(w->fmt==0){ matmul(y,x,w->qf,S,w->I,w->O); return; }
if(w->fmt==4){ matmul_i4_grouped(y,x,w->q4,w->s,S,w->I,w->O,w->gs); return; }
+ if(w->fmt==6){ matmul_e8(y,x,w->q4,NULL,S,w->I,w->O); return; } /* scales live in-block */
if(allow_idot && g_idot && (w->fmt==1 || (w->fmt==2 && (spec_pinned() ? g_i4s<=1 : S>=g_i4s)))){
int I=w->I; int8_t *xq; float *sx;
if(S<0 || I<0 || (size_t)S>SIZE_MAX/(size_t)(I?I:1)){ fprintf(stderr,"matmul_qt: shape overflow\n"); exit(1); }
diff --git a/c/quant.h b/c/quant.h
index b3755380..592874dd 100644
--- a/c/quant.h
+++ b/c/quant.h
@@ -793,4 +793,345 @@ static void pack_int2(const float *w, uint8_t *q2, float *scale, int O, int I, i
}
}
+/* ---- fmt=6: E8/IQ3 lattice container (#452) --------------------------------
+ * 98 bytes per 256 weights = 3.0625 bits/weight. Per super-block:
+ * [ 0..63] uint8 grid index per 4-dim magnitude block
+ * [64..95] uint32 x8 - four 7-bit sign words + 4-bit sub-scale, per 32 weights
+ * [96..97] fp16 super-scale
+ * value = d * (0.5 + code) * 0.5 * grid[idx][j] * sign, with the 8th sign of every
+ * eight derived from odd parity (that is what buys the 8th bit back).
+ * Byte layout and arithmetic mirror tools/iq3_pack.py exactly - that codec is the
+ * oracle this kernel is tested against.
+ *
+ * Decode strategy: expand one 32-weight sub-block into a stack buffer, then FMA it
+ * against the activations. Per-weight table lookups would dominate; per-sub-block
+ * expansion keeps the grid rows (16 bytes each) hot in L1 and lets the compiler
+ * vectorize the multiply-accumulate. */
+#define E8_QK 256 /* weights per super-block */
+#define E8_SUB 32 /* weights per sign/scale word */
+#define E8_BBYTES 98 /* bytes per super-block */
+static inline int64_t e8_blocks(int I){ return ((int64_t)I + E8_QK - 1) / E8_QK; }
+static inline int64_t e8_rowbytes(int I){ return e8_blocks(I) * E8_BBYTES; }
+
+/* The published 256x4 magnitude grid, stored doubled (4,12,..,62 mean 2,6,..,31).
+ * From ggml-common.h (MIT); tools/iq3xxs_grid.json is the same table for the
+ * Python codec, and tests/test_e8_kernel.c checks the two agree through the
+ * fixture. Header-local like the rest of quant.h - the engine is a single
+ * translation unit and the tests include this header directly. */
+static const uint8_t e8_grid[256][4] = {
+ { 4, 4, 4, 4},
+ { 20, 4, 4, 4},
+ { 36, 4, 4, 4},
+ { 12, 12, 4, 4},
+ { 28, 12, 4, 4},
+ { 62, 12, 4, 4},
+ { 4, 20, 4, 4},
+ { 20, 20, 4, 4},
+ { 12, 28, 4, 4},
+ { 20, 36, 4, 4},
+ { 28, 62, 4, 4},
+ { 44, 62, 4, 4},
+ { 12, 4, 12, 4},
+ { 28, 4, 12, 4},
+ { 4, 12, 12, 4},
+ { 20, 12, 12, 4},
+ { 12, 20, 12, 4},
+ { 44, 20, 12, 4},
+ { 4, 28, 12, 4},
+ { 20, 28, 12, 4},
+ { 12, 36, 12, 4},
+ { 36, 44, 12, 4},
+ { 4, 62, 12, 4},
+ { 4, 4, 20, 4},
+ { 20, 4, 20, 4},
+ { 36, 4, 20, 4},
+ { 12, 12, 20, 4},
+ { 4, 20, 20, 4},
+ { 20, 20, 20, 4},
+ { 12, 28, 20, 4},
+ { 28, 28, 20, 4},
+ { 62, 28, 20, 4},
+ { 12, 44, 20, 4},
+ { 62, 44, 20, 4},
+ { 44, 62, 20, 4},
+ { 12, 4, 28, 4},
+ { 62, 4, 28, 4},
+ { 4, 12, 28, 4},
+ { 20, 12, 28, 4},
+ { 44, 20, 28, 4},
+ { 4, 62, 28, 4},
+ { 28, 12, 36, 4},
+ { 62, 28, 36, 4},
+ { 36, 36, 36, 4},
+ { 62, 44, 36, 4},
+ { 28, 62, 36, 4},
+ { 44, 62, 36, 4},
+ { 12, 4, 44, 4},
+ { 62, 4, 44, 4},
+ { 20, 28, 44, 4},
+ { 20, 44, 44, 4},
+ { 44, 28, 52, 4},
+ { 36, 52, 52, 4},
+ { 4, 12, 62, 4},
+ { 36, 12, 62, 4},
+ { 52, 12, 62, 4},
+ { 28, 36, 62, 4},
+ { 12, 52, 62, 4},
+ { 12, 4, 4, 12},
+ { 28, 4, 4, 12},
+ { 4, 12, 4, 12},
+ { 20, 12, 4, 12},
+ { 12, 20, 4, 12},
+ { 28, 20, 4, 12},
+ { 4, 28, 4, 12},
+ { 20, 28, 4, 12},
+ { 36, 28, 4, 12},
+ { 62, 36, 4, 12},
+ { 4, 44, 4, 12},
+ { 4, 4, 12, 12},
+ { 20, 4, 12, 12},
+ { 12, 12, 12, 12},
+ { 4, 20, 12, 12},
+ { 20, 20, 12, 12},
+ { 12, 4, 20, 12},
+ { 28, 4, 20, 12},
+ { 4, 12, 20, 12},
+ { 20, 12, 20, 12},
+ { 12, 20, 20, 12},
+ { 4, 28, 20, 12},
+ { 20, 62, 20, 12},
+ { 4, 4, 28, 12},
+ { 20, 4, 28, 12},
+ { 4, 20, 28, 12},
+ { 12, 28, 28, 12},
+ { 52, 36, 28, 12},
+ { 52, 52, 28, 12},
+ { 12, 4, 36, 12},
+ { 44, 4, 36, 12},
+ { 4, 44, 36, 12},
+ { 4, 20, 44, 12},
+ { 36, 20, 44, 12},
+ { 52, 36, 44, 12},
+ { 12, 62, 44, 12},
+ { 44, 4, 52, 12},
+ { 20, 20, 62, 12},
+ { 4, 36, 62, 12},
+ { 4, 4, 4, 20},
+ { 20, 4, 4, 20},
+ { 12, 12, 4, 20},
+ { 28, 12, 4, 20},
+ { 4, 20, 4, 20},
+ { 20, 20, 4, 20},
+ { 52, 20, 4, 20},
+ { 12, 28, 4, 20},
+ { 20, 36, 4, 20},
+ { 12, 4, 12, 20},
+ { 28, 4, 12, 20},
+ { 44, 4, 12, 20},
+ { 4, 12, 12, 20},
+ { 20, 12, 12, 20},
+ { 12, 20, 12, 20},
+ { 4, 28, 12, 20},
+ { 28, 52, 12, 20},
+ { 62, 52, 12, 20},
+ { 4, 62, 12, 20},
+ { 4, 4, 20, 20},
+ { 20, 4, 20, 20},
+ { 12, 12, 20, 20},
+ { 62, 12, 20, 20},
+ { 4, 20, 20, 20},
+ { 20, 20, 20, 20},
+ { 62, 28, 20, 20},
+ { 4, 36, 20, 20},
+ { 44, 44, 20, 20},
+ { 12, 4, 28, 20},
+ { 4, 12, 28, 20},
+ { 36, 12, 28, 20},
+ { 4, 62, 28, 20},
+ { 36, 62, 28, 20},
+ { 44, 28, 36, 20},
+ { 28, 44, 36, 20},
+ { 28, 4, 44, 20},
+ { 62, 20, 44, 20},
+ { 12, 36, 44, 20},
+ { 36, 62, 44, 20},
+ { 12, 4, 62, 20},
+ { 28, 4, 62, 20},
+ { 52, 12, 62, 20},
+ { 44, 36, 62, 20},
+ { 12, 4, 4, 28},
+ { 4, 12, 4, 28},
+ { 20, 12, 4, 28},
+ { 12, 20, 4, 28},
+ { 28, 20, 4, 28},
+ { 4, 44, 4, 28},
+ { 44, 52, 4, 28},
+ { 20, 62, 4, 28},
+ { 4, 4, 12, 28},
+ { 20, 4, 12, 28},
+ { 4, 20, 12, 28},
+ { 12, 28, 12, 28},
+ { 36, 36, 12, 28},
+ { 52, 36, 12, 28},
+ { 12, 4, 20, 28},
+ { 28, 4, 20, 28},
+ { 4, 12, 20, 28},
+ { 44, 20, 20, 28},
+ { 20, 44, 20, 28},
+ { 20, 62, 20, 28},
+ { 12, 12, 28, 28},
+ { 28, 28, 28, 28},
+ { 4, 28, 36, 28},
+ { 62, 36, 36, 28},
+ { 20, 62, 36, 28},
+ { 4, 4, 44, 28},
+ { 52, 4, 44, 28},
+ { 20, 20, 44, 28},
+ { 44, 44, 44, 28},
+ { 36, 12, 52, 28},
+ { 52, 28, 52, 28},
+ { 28, 52, 52, 28},
+ { 28, 28, 62, 28},
+ { 4, 52, 62, 28},
+ { 36, 4, 4, 36},
+ { 62, 12, 4, 36},
+ { 44, 28, 4, 36},
+ { 62, 28, 4, 36},
+ { 28, 44, 4, 36},
+ { 62, 44, 4, 36},
+ { 36, 62, 12, 36},
+ { 4, 20, 20, 36},
+ { 62, 28, 20, 36},
+ { 4, 36, 20, 36},
+ { 4, 52, 20, 36},
+ { 52, 52, 20, 36},
+ { 62, 4, 28, 36},
+ { 44, 36, 28, 36},
+ { 36, 4, 36, 36},
+ { 12, 44, 36, 36},
+ { 36, 52, 36, 36},
+ { 44, 20, 44, 36},
+ { 28, 36, 44, 36},
+ { 4, 62, 44, 36},
+ { 44, 4, 62, 36},
+ { 4, 12, 62, 36},
+ { 20, 12, 62, 36},
+ { 4, 28, 62, 36},
+ { 20, 12, 4, 44},
+ { 12, 36, 4, 44},
+ { 4, 62, 4, 44},
+ { 4, 4, 12, 44},
+ { 52, 4, 12, 44},
+ { 52, 20, 12, 44},
+ { 44, 44, 12, 44},
+ { 36, 12, 20, 44},
+ { 20, 28, 20, 44},
+ { 20, 62, 20, 44},
+ { 20, 4, 28, 44},
+ { 28, 44, 28, 44},
+ { 4, 12, 36, 44},
+ { 28, 20, 36, 44},
+ { 62, 20, 36, 44},
+ { 20, 62, 36, 44},
+ { 20, 4, 44, 44},
+ { 12, 28, 44, 44},
+ { 4, 44, 52, 44},
+ { 36, 20, 62, 44},
+ { 20, 36, 62, 44},
+ { 36, 20, 4, 52},
+ { 36, 36, 4, 52},
+ { 52, 36, 4, 52},
+ { 36, 52, 4, 52},
+ { 12, 20, 12, 52},
+ { 12, 52, 12, 52},
+ { 62, 12, 20, 52},
+ { 36, 52, 20, 52},
+ { 4, 28, 28, 52},
+ { 52, 28, 28, 52},
+ { 36, 36, 36, 52},
+ { 44, 4, 44, 52},
+ { 20, 44, 44, 52},
+ { 28, 28, 52, 52},
+ { 28, 4, 62, 52},
+ { 12, 20, 62, 52},
+ { 28, 4, 4, 62},
+ { 44, 4, 4, 62},
+ { 62, 4, 4, 62},
+ { 4, 12, 4, 62},
+ { 20, 28, 4, 62},
+ { 20, 44, 4, 62},
+ { 52, 20, 12, 62},
+ { 4, 36, 12, 62},
+ { 20, 12, 20, 62},
+ { 44, 36, 20, 62},
+ { 20, 44, 20, 62},
+ { 4, 4, 28, 62},
+ { 44, 12, 28, 62},
+ { 28, 28, 28, 62},
+ { 4, 52, 28, 62},
+ { 12, 20, 36, 62},
+ { 12, 36, 36, 62},
+ { 4, 4, 44, 62},
+ { 20, 4, 44, 62},
+ { 36, 20, 44, 62},
+ { 4, 28, 52, 62}
+};
+
+static inline float e8_fp16_to_f32(uint16_t h){
+ uint32_t sign=(uint32_t)(h>>15)<<31, exp=(h>>10)&0x1F, man=h&0x3FF, bits;
+ if(!exp) bits = man ? (sign | ((127-15+1)<<23) | (man<<13)) : sign; /* subnormal->approx */
+ else if(exp==0x1F) bits = sign | 0x7F800000u | (man<<13);
+ else bits = sign | ((exp+112)<<23) | (man<<13);
+ float f; memcpy(&f,&bits,4); return f;
+}
+
+/* Expand one 32-weight sub-block. `out` must hold 32 floats. */
+static inline void e8_expand_sub(const uint8_t *blk, int ib, float d, float *out){
+ uint32_t word; memcpy(&word, blk + E8_QK/4 + ib*4, 4);
+ float db = d * (0.5f + (float)((word>>28)&0xF)) * 0.5f;
+ const uint8_t *idx = blk + ib*8;
+ for(int l=0;l<4;l++){
+ uint32_t seven=(word>>(7*l))&0x7F;
+ const uint8_t *g0=e8_grid[idx[l*2+0]], *g1=e8_grid[idx[l*2+1]];
+ int par=0;
+ for(int j=0;j<8;j++){
+ int neg = j<7 ? (int)((seven>>j)&1) : 0;
+ if(j<7) par^=neg; else neg=par; /* odd parity closes the block */
+ float mag = (j<4 ? (float)g0[j] : (float)g1[j-4]) * 0.5f;
+ out[l*8+j] = neg ? -mag*db : mag*db;
+ }
+ }
+}
+
+static void matmul_e8(float *y, const float *x, const uint8_t *q, const float *unused,
+ int S, int I, int O){
+ (void)unused; /* scales live inside the blocks */
+ int64_t nb=e8_blocks(I), rb=e8_rowbytes(I);
+ #pragma omp parallel for schedule(static)
+ for(int o=0;o<O;o++){
+ const uint8_t *wrow=q+(int64_t)o*rb;
+ for(int s=0;s<S;s++){
+ const float *xs=x+(int64_t)s*I;
+ float acc=0;
+ for(int64_t b=0;b<nb;b++){
+ const uint8_t *blk=wrow+b*E8_BBYTES;
+ uint16_t dh; memcpy(&dh, blk+96, 2);
+ float d=e8_fp16_to_f32(dh);
+ int base=(int)(b*E8_QK);
+ for(int ib=0; ib<E8_QK/E8_SUB; ib++){
+ int off=base+ib*E8_SUB;
+ if(off>=I) break;
+ float w[E8_SUB];
+ e8_expand_sub(blk, ib, d, w);
+ int n = I-off < E8_SUB ? I-off : E8_SUB;
+ float a=0;
+ for(int k=0;k<n;k++) a += xs[off+k]*w[k];
+ acc+=a;
+ }
+ }
+ y[(int64_t)s*O+o]=acc;
+ }
+ }
+}
+
#endif /* COLI_QUANT_H */
diff --git a/c/tests/fixtures/e8_case.bin b/c/tests/fixtures/e8_case.bin
new file mode 100644
index 00000000..bec2cd7a
Binary files /dev/null and b/c/tests/fixtures/e8_case.bin differ
diff --git a/c/tests/test_e8_kernel.c b/c/tests/test_e8_kernel.c
new file mode 100644
index 00000000..caf8b7e4
--- /dev/null
+++ b/c/tests/test_e8_kernel.c
@@ -0,0 +1,87 @@
+/* fmt=6 (E8/IQ3 lattice) CPU kernel oracle β€” #452 ladder step 3.
+ *
+ * tools/iq3_pack.py is the format's reference implementation; this checks that
+ * matmul_e8 reads the same bytes to the same numbers. The fixture is generated
+ * by that codec (tests/fixtures/e8_case.bin, written by tools/make_e8_fixture.py)
+ * and carries, for one [O,I] tensor: the packed bytes, the codec's own dequant of
+ * them, an activation row, and the reference y = dequant @ x computed in float64.
+ *
+ * Two properties are checked:
+ * 1. dequant agreement β€” expanding each sub-block must reproduce the codec's
+ * floats bit-for-bit (same grid, same parity rule, same scale arithmetic)
+ * 2. matmul agreement β€” y within float rounding of the float64 reference
+ *
+ * Build: cc -O2 -fopenmp tests/test_e8_kernel.c e8_grid.c -o tests/test_e8_kernel -lm
+ */
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <math.h>
+#include <stdint.h>
+
+#include "../quant.h"
+
+static void *slurp(const char *path, size_t *n) {
+ FILE *f = fopen(path, "rb");
+ if (!f) { fprintf(stderr, "cannot open %s β€” run tools/make_e8_fixture.py\n", path); exit(77); }
+ fseek(f, 0, SEEK_END); long sz = ftell(f); fseek(f, 0, SEEK_SET);
+ void *p = malloc((size_t)sz);
+ if (fread(p, 1, (size_t)sz, f) != (size_t)sz) { fprintf(stderr, "short read\n"); exit(1); }
+ fclose(f); *n = (size_t)sz; return p;
+}
+
+int main(void) {
+ size_t nbytes;
+ uint8_t *raw = slurp("tests/fixtures/e8_case.bin", &nbytes);
+ /* header: int32 O, I, then packed[O*rowbytes], deq[O*I], x[I], yref[O] */
+ int32_t O, I;
+ memcpy(&O, raw, 4); memcpy(&I, raw + 4, 4);
+ size_t rb = (size_t)e8_rowbytes(I);
+ const uint8_t *packed = raw + 8;
+ const float *deq = (const float *)(packed + (size_t)O * rb);
+ const float *x = deq + (size_t)O * I;
+ const float *yref = x + I;
+
+ /* 1. dequant agreement, sub-block by sub-block */
+ int mism = 0;
+ float w[E8_SUB];
+ for (int o = 0; o < O && mism < 5; o++) {
+ const uint8_t *row = packed + (size_t)o * rb;
+ for (int64_t b = 0; b < e8_blocks(I); b++) {
+ const uint8_t *blk = row + b * E8_BBYTES;
+ uint16_t dh; memcpy(&dh, blk + 96, 2);
+ float d = e8_fp16_to_f32(dh);
+ for (int ib = 0; ib < E8_QK / E8_SUB; ib++) {
+ int off = (int)(b * E8_QK) + ib * E8_SUB;
+ if (off >= I) break;
+ e8_expand_sub(blk, ib, d, w);
+ int n = I - off < E8_SUB ? I - off : E8_SUB;
+ for (int k = 0; k < n; k++) {
+ float got = w[k], want = deq[(size_t)o * I + off + k];
+ if (fabsf(got - want) > 1e-6f * (fabsf(want) + 1e-6f)) {
+ if (mism < 5)
+ fprintf(stderr, "dequant mismatch o=%d i=%d: got %.9g want %.9g\n",
+ o, off + k, got, want);
+ mism++;
+ }
+ }
+ }
+ }
+ }
+ if (mism) { printf("FAIL: %d dequant mismatches\n", mism); return 1; }
+
+ /* 2. matmul agreement */
+ float *y = malloc((size_t)O * sizeof(float));
+ matmul_e8(y, x, packed, NULL, 1, I, O);
+ double worst = 0;
+ for (int o = 0; o < O; o++) {
+ double d = fabs((double)y[o] - (double)yref[o]);
+ double rel = d / (fabs((double)yref[o]) + 1e-6);
+ if (rel > worst) worst = rel;
+ }
+ printf("e8 kernel oracle: O=%d I=%d, dequant exact, matmul worst rel %.2e\n", O, I, worst);
+ if (worst > 1e-5) { printf("FAIL\n"); return 1; }
+ printf("OK\n");
+ free(y); free(raw);
+ return 0;
+}
diff --git a/c/tests/test_iq3_pack.py b/c/tests/test_iq3_pack.py
index c2f17fdc..43aa877f 100644
--- a/c/tests/test_iq3_pack.py
+++ b/c/tests/test_iq3_pack.py
@@ -1,4 +1,4 @@
-"""fmt=5 codec oracle (#452 ladder step 2).
+"""fmt=6 codec oracle (#452 ladder step 2).
Checks the properties the container, the converter and the decode kernels all
depend on: exact byte budget, deterministic encode, decode agreeing with a
diff --git a/c/tools/iq3_pack.py b/c/tools/iq3_pack.py
index 03d139b8..b59451f5 100644
--- a/c/tools/iq3_pack.py
+++ b/c/tools/iq3_pack.py
@@ -1,5 +1,8 @@
#!/usr/bin/env python3
-"""fmt=5 (E8/IQ3 grouped container) index codec β€” #452 ladder step 2.
+"""fmt=6 (E8/IQ3 lattice container) index codec β€” #452 ladder step 2.
+
+Note: fmt=5 is taken by the int3 dual-plane container (#132); this lattice
+container is fmt=6.
The ablation (#453) proved the SCHEME: an IQ3_XXS-style codebook plus rotation
matches our simulated E8 ball (51.5% vs 51.5% on OLMoE). That code quantizes to
@@ -7,7 +10,7 @@ lattice points and keeps floats. This module produces the DEPLOYABLE bytes and
reads them back, so the container, the converter and the decode kernels all
agree on one layout.
-Layout β€” one 256-weight super-block, 98 bytes, 3.0625 bpw:
+Layout - one 256-weight super-block, 98 bytes, 3.0625 bpw:
[0 .. 63] uint8 grid index per 4-dim magnitude block (64 blocks)
[64 .. 95] uint32 x8, one per 32-weight sub-block:
diff --git a/c/tools/make_e8_fixture.py b/c/tools/make_e8_fixture.py
new file mode 100644
index 00000000..e58d7d4d
--- /dev/null
+++ b/c/tools/make_e8_fixture.py
@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+"""Generate the fmt=6 kernel fixture from the reference codec (#452).
+
+tests/test_e8_kernel.c checks the C kernel against these bytes, so the fixture
+must come from iq3_pack.py β€” the format's reference implementation β€” and never
+from the kernel itself. Regenerate whenever the layout changes:
+
+ python3 tools/make_e8_fixture.py
+"""
+import os
+import struct
+
+import numpy as np
+
+import iq3_pack as P
+
+O, I = 24, 512
+SEED = 20260721
+
+
+def main():
+ rng = np.random.default_rng(SEED)
+ w = (rng.standard_normal((O, I)) * 0.05).astype(np.float32)
+ packed = P.encode(w)
+ deq = P.decode(packed, I).astype(np.float32)
+ x = (rng.standard_normal(I) * 1.0).astype(np.float32)
+ # float64 reference so the C float path is compared against something better
+ yref = (deq.astype(np.float64) @ x.astype(np.float64)).astype(np.float32)
+
+ out = os.path.join(os.path.dirname(__file__), "..", "tests", "fixtures")
+ os.makedirs(out, exist_ok=True)
+ path = os.path.join(out, "e8_case.bin")
+ with open(path, "wb") as f:
+ f.write(struct.pack("<ii", O, I))
+ f.write(packed.tobytes())
+ f.write(deq.tobytes())
+ f.write(x.tobytes())
+ f.write(yref.tobytes())
+ print(f"wrote {path}: O={O} I={I} packed={packed.nbytes}B "
+ f"({packed.nbytes * 8 / (O * I):.4f} bpw)")
+
+
+if __name__ == "__main__":
+ main()