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
6.7 KB
Raw Blame
/* 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;
}