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

feat(affine): add a loader-side dequant oracle to the MLX affine contract

Léon Avic Simmonsfaab791fdb9b
diff --git a/c/Makefile b/c/Makefile
index e43a9ecf..62568728 100644
--- a/c/Makefile
+++ b/c/Makefile
@@ -1793,6 +1793,11 @@ tests/test_affine_quant$(EXE): tests/test_affine_quant.c affine_quant.h backend_
tests/test_qpack$(EXE): tests/test_qpack.c qpack.c qpack.h affine_quant.h json.h compat.h
$(CC) $(CFLAGS) tests/test_qpack.c qpack.c -o $@ $(LDFLAGS)
+# Loader-side expansion oracle for the same MLX affine contract: nibble/byte
+# order, scalar decodings, parity against coli_affine_matmul_ref, refusals.
+tests/test_affine_dequant$(EXE): tests/test_affine_dequant.c affine_quant.h
+ $(CC) $(CFLAGS) $< -o $@ $(LDFLAGS)
+
tests/test_edge_runtime$(EXE): tests/test_edge_runtime.c edge_runtime.c edge_runtime.h
$(CC) $(CFLAGS) tests/test_edge_runtime.c edge_runtime.c -o $@ $(LDFLAGS)
diff --git a/c/affine_quant.h b/c/affine_quant.h
index 61f4089c..a763fc8f 100644
--- a/c/affine_quant.h
+++ b/c/affine_quant.h
@@ -224,6 +224,60 @@ coli_affine_matmul_ref(float *output, const float *input, size_t batch,
return COLI_AFFINE_OK;
}
+/* Row-major logical expansion out[output_dim, input_dim] = dequant(view):
+ * out[row*I + col] = scale[row, col/gs] * q[row, col] + bias[row, col/gs],
+ * with the SAME bit conventions as coli_affine_matmul_ref above (little-endian
+ * uint32 words, lowest bits = lowest logical column). This is the loader-side
+ * oracle: matmul_ref folds the dequant into its accumulation and never
+ * materialises the weights, but a dense tensor the ENGINE keeps resident
+ * (qwen36's attention/DeltaNet/shared-expert set from a Swiftlet container's
+ * model.safetensors) needs the expanded f32 rows exactly once, at load time.
+ * Kept next to matmul_ref so the two bit-level readings of the packed words
+ * cannot drift apart without this file changing. */
+static inline ColiAffineStatus
+coli_affine_dequant_ref(const ColiAffineQuantizedView *view, float *output) {
+ ColiAffineStatus status = coli_affine_validate(view);
+ unsigned bits, per_word;
+ uint32_t mask;
+ size_t groups, unused;
+ const uint8_t *weights;
+
+ if (status != COLI_AFFINE_OK) return status;
+ if (!output) return COLI_AFFINE_NULL;
+ if (!coli_affine_size_mul(view->output_dim, view->input_dim, &unused))
+ return COLI_AFFINE_OVERFLOW;
+
+ bits = coli_affine_bits(view->format);
+ per_word = 32u / bits;
+ mask = (UINT32_C(1) << bits) - 1u;
+ groups = view->input_dim / view->group_size;
+ weights = (const uint8_t *)view->weights;
+
+ for (size_t row = 0; row < view->output_dim; row++) {
+ const uint8_t *weight_row =
+ weights + row * (view->input_dim / per_word) * 4;
+ float *out_row = output + row * view->input_dim;
+ for (size_t group = 0; group < groups; group++) {
+ const size_t word_base = group * (view->group_size / per_word);
+ const size_t input_base = group * view->group_size;
+ const size_t scalar_index = row * groups + group;
+ const float scale = coli_affine_load_scalar(
+ view->scales, scalar_index, view->scalar_format);
+ const float bias = coli_affine_load_scalar(
+ view->biases, scalar_index, view->scalar_format);
+ for (size_t local = 0; local < view->group_size; local++) {
+ const size_t word_index = word_base + local / per_word;
+ const uint32_t word =
+ coli_affine_load_le32(weight_row + word_index * 4);
+ const unsigned shift = bits * (unsigned)(local % per_word);
+ out_row[input_base + local] =
+ scale * (float)((word >> shift) & mask) + bias;
+ }
+ }
+ }
+ return COLI_AFFINE_OK;
+}
+
#ifdef __cplusplus
}
#endif
diff --git a/c/tests/test_affine_dequant.c b/c/tests/test_affine_dequant.c
new file mode 100644
index 00000000..cebda56c
--- /dev/null
+++ b/c/tests/test_affine_dequant.c
@@ -0,0 +1,161 @@
+/* coli_affine_dequant_ref gates: the loader-side expansion oracle must read
+ * the SAME bits as coli_affine_matmul_ref and refuse the same malformed
+ * views.
+ *
+ * 1. nibble order -- a Q4 word authored as 0x76543210 must expand to
+ * logical columns 0,1,...,7 in that order (lowest bits = lowest
+ * column). A most-significant-first reading produces the reversed
+ * sequence and fails the exact-value checks.
+ * 2. affine map -- expansion is scale*q + bias per group, with the
+ * BF16/F16/F32 scalar decodings all exercised (the values chosen are
+ * exactly representable in every one of the three, so the checks are
+ * equality, not tolerance).
+ * 3. Q8 arm -- per_word drops to 4 and the mask widens; a crafted
+ * word proves the byte order.
+ * 4. matmul parity -- x @ dequant(W)^T must equal matmul_ref(x, W) on a
+ * multi-group view, so the two readings of the packed words cannot
+ * drift apart.
+ * 5. refusals -- NULL buffers, truncated scales, and a group size
+ * that does not divide input_dim come back as statuses, never as
+ * plausible output.
+ */
+#ifndef _GNU_SOURCE
+#define _GNU_SOURCE
+#endif
+
+#include <math.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include "../affine_quant.h"
+
+#define CHECK(condition) do { \
+ if (!(condition)) { \
+ fprintf(stderr, "%s:%d: check failed: %s\n", \
+ __FILE__, __LINE__, #condition); \
+ exit(1); \
+ } \
+} while (0)
+
+static uint16_t f32_to_bf16(float value) {
+ uint32_t bits;
+ memcpy(&bits, &value, sizeof(bits));
+ return (uint16_t)(bits >> 16); /* the test values are bf16-exact */
+}
+
+/* Q4, one row of 16 logical columns in two groups of 8: word 0 counts
+ * 0..7 LSB-first, word 1 counts 8..15. Group 0 maps q -> 2q - 1, group 1
+ * maps q -> 0.5q + 4; every expected value is exact in bf16/f16/f32. */
+static void test_q4_nibble_order_and_affine(void) {
+ const uint32_t words[2] = { 0x76543210u, 0xFEDCBA98u };
+ const uint16_t scales_bf16[2] = { 0x4000u /* 2.0 */, 0x3F00u /* 0.5 */ };
+ const uint16_t biases_bf16[2] = { 0xBF80u /* -1.0 */, 0x4080u /* 4.0 */ };
+ ColiAffineQuantizedView view = {
+ words, scales_bf16, biases_bf16,
+ sizeof(words), sizeof(scales_bf16), sizeof(biases_bf16),
+ 1, 16, 8, COLI_AFFINE_MLX_Q4, COLI_AFFINE_SCALAR_BF16
+ };
+ float out[16];
+ CHECK(coli_affine_dequant_ref(&view, out) == COLI_AFFINE_OK);
+ for (int q = 0; q < 8; q++)
+ CHECK(out[q] == 2.0f * (float)q - 1.0f);
+ for (int q = 8; q < 16; q++)
+ CHECK(out[q] == 0.5f * (float)q + 4.0f);
+}
+
+/* Q8: 4 values per word, byte order proven by an asymmetric word. */
+static void test_q8_byte_order(void) {
+ const uint32_t words[1] = { 0xFF400201u }; /* q = 1, 2, 64, 255 */
+ const float scales_f32[1] = { 3.0f };
+ const float biases_f32[1] = { -2.0f };
+ const float expected[4] = { 1.0f, 4.0f, 190.0f, 763.0f };
+ ColiAffineQuantizedView view = {
+ words, scales_f32, biases_f32,
+ sizeof(words), sizeof(scales_f32), sizeof(biases_f32),
+ 1, 4, 4, COLI_AFFINE_MLX_Q8, COLI_AFFINE_SCALAR_F32
+ };
+ float out[4];
+ CHECK(coli_affine_dequant_ref(&view, out) == COLI_AFFINE_OK);
+ for (int i = 0; i < 4; i++) CHECK(out[i] == expected[i]);
+}
+
+/* F16 scalar decoding through the same path (1.5 and 0.25 are f16-exact). */
+static void test_f16_scalars(void) {
+ const uint32_t words[1] = { 0x00000021u }; /* q = 1, 2, 0, 0, ... */
+ const uint16_t scales_f16[1] = { 0x3E00u /* 1.5 */ };
+ const uint16_t biases_f16[1] = { 0x3400u /* 0.25 */ };
+ ColiAffineQuantizedView view = {
+ words, scales_f16, biases_f16,
+ sizeof(words), sizeof(scales_f16), sizeof(biases_f16),
+ 1, 8, 8, COLI_AFFINE_MLX_Q4, COLI_AFFINE_SCALAR_F16
+ };
+ float out[8];
+ CHECK(coli_affine_dequant_ref(&view, out) == COLI_AFFINE_OK);
+ CHECK(out[0] == 1.75f && out[1] == 3.25f);
+ for (int i = 2; i < 8; i++) CHECK(out[i] == 0.25f);
+}
+
+/* Multi-row multi-group parity: y = matmul_ref(x, W) must equal
+ * x @ dequant_ref(W)^T, or the two functions read different bits. */
+static void test_matmul_parity(void) {
+ enum { O = 3, I = 32, GS = 16, WORDS_PER_ROW = I / 8 };
+ uint32_t words[O * WORDS_PER_ROW];
+ uint16_t scales[O * (I / GS)], biases[O * (I / GS)];
+ float x[I], expanded[O * I], want[O], got[O];
+ for (int i = 0; i < O * WORDS_PER_ROW; i++)
+ words[i] = 0x9E3779B9u * (uint32_t)(i + 1) + 0x7F4A7C15u;
+ for (int i = 0; i < O * (I / GS); i++) {
+ scales[i] = f32_to_bf16(0.25f + 0.125f * (float)i);
+ biases[i] = f32_to_bf16(-1.0f + 0.5f * (float)(i % 3));
+ }
+ for (int i = 0; i < I; i++) x[i] = 0.0625f * (float)(i - I / 2);
+ ColiAffineQuantizedView view = {
+ words, scales, biases,
+ sizeof(words), sizeof(scales), sizeof(biases),
+ O, I, GS, COLI_AFFINE_MLX_Q4, COLI_AFFINE_SCALAR_BF16
+ };
+ CHECK(coli_affine_matmul_ref(want, x, 1, &view) == COLI_AFFINE_OK);
+ CHECK(coli_affine_dequant_ref(&view, expanded) == COLI_AFFINE_OK);
+ for (int o = 0; o < O; o++) {
+ double sum = 0.0;
+ for (int i = 0; i < I; i++) sum += (double)expanded[o * I + i] * x[i];
+ got[o] = (float)sum;
+ CHECK(fabsf(got[o] - want[o]) <= 1e-4f * (1.0f + fabsf(want[o])));
+ }
+}
+
+static void test_refusals(void) {
+ const uint32_t words[2] = { 0, 0 };
+ const uint16_t scalars[2] = { 0x3F80u, 0x3F80u };
+ float out[16];
+ ColiAffineQuantizedView view = {
+ words, scalars, scalars,
+ sizeof(words), sizeof(scalars), sizeof(scalars),
+ 1, 16, 8, COLI_AFFINE_MLX_Q4, COLI_AFFINE_SCALAR_BF16
+ };
+ CHECK(coli_affine_dequant_ref(NULL, out) == COLI_AFFINE_NULL);
+ CHECK(coli_affine_dequant_ref(&view, NULL) == COLI_AFFINE_NULL);
+
+ ColiAffineQuantizedView truncated = view;
+ truncated.scale_bytes = 2; /* needs 2 groups * 2 bytes */
+ CHECK(coli_affine_dequant_ref(&truncated, out) == COLI_AFFINE_TRUNCATED);
+
+ ColiAffineQuantizedView bad_group = view;
+ bad_group.group_size = 12; /* 16 % 12 != 0 */
+ CHECK(coli_affine_dequant_ref(&bad_group, out) == COLI_AFFINE_BAD_SHAPE);
+
+ ColiAffineQuantizedView bad_format = view;
+ bad_format.format = (ColiAffineFormat)7;
+ CHECK(coli_affine_dequant_ref(&bad_format, out) == COLI_AFFINE_BAD_FORMAT);
+}
+
+int main(void) {
+ test_q4_nibble_order_and_affine();
+ test_q8_byte_order();
+ test_f16_scalars();
+ test_matmul_parity();
+ test_refusals();
+ printf("test_affine_dequant: OK\n");
+ return 0;
+}