nx_q4k_fused_fidelity_gate.nx source
↩ module page · 174 lines · 9198 B
1// nx_q4k_fused_fidelity_gate.nx -- DOES THE FUSED INTEGER GEMM TELL THE TRUTH ON REAL TRAINED WEIGHTS?
2//
3// THE QUESTION THIS ANSWERS, AND WHY SPEED CANNOT ANSWER IT. nx_q4k_fused_vs_x4_gate proves the fused
4// kernel is >=9.9x faster and BIT-EXACT -- but only in a synthetic regime built from d=1.0, dmin=0,
5// scales=1 and small integer activations, where every value is exactly representable. That regime is
6// chosen to isolate the KERNEL's logic. It says nothing about REAL weights, because the fused route is
7// not a reassociation: it is ACTIVATION QUANTISATION (f32 -> Q10). Dispatching on the strength of a
8// speed gate would ship fast wrong answers -- the speed bench in this very lane stayed GREEN on a
9// deliberately corrupted kernel.
10//
11// SO THIS GATE IS ADVERSARIAL BY CONSTRUCTION:
12// * REAL weights -- the actual blk.0.attn_q.weight Q4_K super-blocks from the live Qwen3-4B model,
13// with their real trained super-scales and 6-bit sub-scales/mins (nothing synthetic).
14// * Activations DELIBERATELY NOT Q10-REPRESENTABLE. Values are built and then multiplied by the f32
15// constant 1/3 (0x3EAAAAAB), which has an infinite binary expansion, so every activation carries
16// bits BELOW Q10's 1/1024 resolution. Feeding Q10-exact activations would have flattered the fused
17// path and measured nothing -- the quantisation error would have been zero by construction.
18// * The reference is nx_f32_q4k_matmul_x4: the kernel actually dispatched today, not a strawman.
19//
20// VERDICT UNIT: error is reported in PER-1024 of the reference magnitude (1024 = 100%, 10 ~= 1%), so
21// the actual number is visible and reviewable rather than hidden behind a pass/fail.
22//
23// genealogy_id: nx_q4k_speed_bench (real-model load) + nx_q4k_ggml_kat (2% tolerance discipline)
24import "nx_syscalls.nx"
25import "nx_tier.nx"
26import "nx_le.nx"
27import "nx_gguf.nx"
28import "nx_gguf_load.nx"
29import "nx_f32.nx"
30import "nx_f32_cvt.nx"
31import "nx_f32_q4k_matmul.nx"
32import "nx_gate_verdict.nx"
33
34const FF_COLS: i64 = 64 // output columns (weight rows) to check
35const FF_ONE_THIRD: i64 = 1051372203 // 0x3EAAAAAB = f32(1/3): forces sub-Q10 bits into every activation
36
37func ff_puts(s: *u8) -> i64 { var n: i64 = 0; while s[n] != (0 as u8) { n = n + 1 } sys_write(1, s, n); return 0 }
38func ff_num(v: i64) -> i64 {
39 let b: *u8 = sys_mmap(32); var m: i64 = v
40 if m == 0 { b[0] = 48 as u8; sys_write(1, b, 1); return 0 }
41 if m < 0 { ff_puts("-" as *u8); m = 0 - m }
42 let t: *u8 = sys_mmap(32); var k: i64 = 0
43 while m > 0 { t[k] = (48 + (m % 10)) as u8; m = m / 10; k = k + 1 }
44 var i: i64 = 0
45 while i < k { b[i] = t[k - 1 - i]; i = i + 1 }
46 sys_write(1, b, k); return 0
47}
48func ff_lcg(s: i64) -> i64 { var v: i64 = s * 1103515245 + 12345; v = v & 2147483647; return v }
49
50// Worst relative deviation of `cand` from `ref`, in per-2^20 units (1048576 = 100%).
51//
52// u2605 WHY THIS WAS RESHARPENED. The first version measured in per-1024 units and, once the activation
53// format widened to Q20, reported a flat 0 -- which does NOT mean "no error", it means "below 1/1024
54// (~0.1%), which is all this ruler can see". Reporting that 0 as fidelity would have been the
55// instrument's floor masquerading as a measurement. At per-2^20 the ruler is 1024x finer than the
56// quantity it is measuring, so a 0 here is a real bound rather than a rounding artifact.
57func ff_max_rel_p1024(ref: *i64, cand: *i64, n: i64) -> i64 {
58 var worst: i64 = 0
59 var i: i64 = 0
60 while i < n {
61 let r: i64 = ref[i]
62 let d: i64 = nx_f32_abs(nx_f32_sub(cand[i], r))
63 let ar: i64 = nx_f32_abs(r)
64 // Skip cells whose reference is ~0: a relative error there is meaningless, not lenient --
65 // an absolute check covers them via the max-abs report below.
66 if nx_f32_lt(nx_q10_to_f32(1), ar) == 1 {
67 var lo: i64 = 0
68 var hi: i64 = 2097152
69 while lo < hi {
70 let mid: i64 = (lo + hi + 1) / 2
71 if lo >= hi { hi = lo }
72 let bound: i64 = nx_f32_mul(nx_q20_to_f32(mid), ar)
73 if nx_f32_lt(bound, d) == 1 { lo = mid } else { hi = mid - 1 }
74 }
75 if lo > worst { worst = lo }
76 }
77 i = i + 1
78 }
79 return worst
80}
81
82func main(argc: i64, argv: *i64) -> i64 {
83 // D001: inherit nx_gate_verdict rather than rolling our own PASS/FAIL/verdict line, so
84 // nx_gate_green can judge this gate from outside and flake/erosion stay visible.
85 let ctr: *i64 = gv_ctr()
86 gv_head("nx_q4k_fused_fidelity_gate -- fused GEMM vs x4 on REAL trained Q4_K weights" as *u8)
87
88 let path: *u8 = "/mnt/c/Users/elder/elder-ai-platform/models/unified/text_encoder/Huihui-Qwen3-4B-Instruct-2507-abliterated-Q4_K_M.gguf" as *u8
89 let fd: i64 = sys_openat_rd(path)
90 if fd < 0 { ff_puts(" MODEL ABSENT -- REFUSING to report a fidelity verdict without real weights\n" as *u8); sys_exit(2); return 2 }
91 let CAP: i64 = 1153433600
92 let buf: *u8 = sys_mmap(CAP)
93 var total: i64 = 0
94 var go: i64 = 1
95 while go == 1 {
96 let r: i64 = sys_read(fd, ((buf as i64) + total) as *u8, CAP - total)
97 if r <= 0 { go = 0 } else { total = total + r; if total >= CAP { go = 0 } }
98 }
99 sys_close(fd)
100 if total < 100000000 { ff_puts(" SHORT READ -- REFUSING\n" as *u8); sys_exit(3); return 3 }
101
102 let hdr: *NxGgufHeader = sys_mmap(NX_GGUF_HDR_BYTES) as *NxGgufHeader
103 if nx_gguf_parse(buf, total, hdr) != NX_GGUF_OK { ff_puts(" GGUF PARSE FAIL\n" as *u8); sys_exit(4); return 4 }
104 let qi: nx_int = nx_gguf_find_tensor(hdr, "blk.0.attn_q.weight" as *u8, 19)
105 if qi < 0 { ff_puts(" TENSOR ABSENT\n" as *u8); sys_exit(5); return 5 }
106 let ti: *NxGgufTensorInfo = nx_gguf_tensor_at(hdr, qi)
107 if ti.ggml_type != 12 { ff_puts(" NOT Q4_K\n" as *u8); sys_exit(6); return 6 }
108 let K: i64 = ti.dim_0
109 let w_off: i64 = hdr.data_off + ti.offset
110 let bpr: i64 = (K / 256) * 144
111 if w_off + FF_COLS * bpr > total { ff_puts(" WEIGHT SLICE OUT OF RANGE\n" as *u8); sys_exit(7); return 7 }
112 ff_puts(" real weights: blk.0.attn_q K=" as *u8); ff_num(K); ff_puts(" cols=" as *u8); ff_num(FF_COLS); ff_puts("\n" as *u8)
113
114 // Activations with sub-Q10 bits: scale to ~[-2,2] then multiply by f32(1/3).
115 let A: *i64 = sys_mmap(K * 8) as *i64
116 var s: i64 = 12345
117 var i: i64 = 0
118 while i < K {
119 s = ff_lcg(s)
120 let q: i64 = (s % 4096) - 2048
121 A[i] = nx_f32_mul(nx_q10_to_f32(q), FF_ONE_THIRD)
122 i = i + 1
123 }
124
125 let Cx: *i64 = sys_mmap(FF_COLS * 8) as *i64
126 let Cf: *i64 = sys_mmap(FF_COLS * 8) as *i64
127
128 let rx: nx_int = nx_f32_q4k_matmul_x4(A, buf, w_off, Cx, 1, K, FF_COLS)
129 let rf: nx_int = nx_f32_q4k_matmul_fused(A, buf, w_off, Cf, 1, K, FF_COLS)
130 var ok1: i64 = 0
131 if rx == NX_FQ4M_OK { ok1 = 1 }
132 gv_check("T1 x4 reference ran on real weights" as *u8, ok1, ctr)
133 var ok2: i64 = 0
134 if rf == NX_FQ4M_OK { ok2 = 1 }
135 gv_check("T2 fused ran on real weights" as *u8, ok2, ctr)
136
137 // T3: NON-VACUITY. The comparison must be able to see a difference at all. If the two outputs were
138 // identical for a trivial reason (both zero, both garbage), a tolerance check would pass vacuously.
139 var nonzero: i64 = 0
140 var z: i64 = 0
141 while z < FF_COLS { if nx_f32_lt(nx_q10_to_f32(1), nx_f32_abs(Cx[z])) == 1 { nonzero = nonzero + 1 } z = z + 1 }
142 ff_puts(" (reference nonzero cols=" as *u8); ff_num(nonzero); ff_puts(")\n" as *u8)
143 var ok3: i64 = 0
144 if nonzero >= FF_COLS / 2 { ok3 = 1 }
145 gv_check("T3 reference is non-trivial (comparison not vacuous)" as *u8, ok3, ctr)
146
147 // T4: THE FIDELITY VERDICT on real weights.
148 let worst: i64 = ff_max_rel_p1024(Cx, Cf, FF_COLS)
149 ff_puts(" max relative deviation = " as *u8); ff_num(worst); ff_puts(" per-1048576 (1048576=100%, 10486~=1%, 1049~=0.1%)\n" as *u8)
150 var ok4: i64 = 0
151 if worst <= 20972 { ok4 = 1 }
152 gv_check("T4 fused within 2% of the live x4 path on REAL weights" as *u8, ok4, ctr)
153 // T4b: the STRICT band. 2% is the legacy KAT tolerance and is far too loose to authorise a
154 // dispatcher flip whose error compounds across ~36 layers. Q20 activations should land orders of
155 // magnitude inside it; if they do not, the widening did not do what it claimed.
156 var ok4b: i64 = 0
157 if worst <= 1049 { ok4b = 1 }
158 gv_check("T4b fused within 0.1% strict band (compounds over 36 layers)" as *u8, ok4b, ctr)
159
160 // T5: NEGATIVE CONTROL on the measuring function itself -- perturb one cell and require it to be seen.
161 let saved: i64 = Cf[0]
162 Cf[0] = nx_f32_mul(Cx[0], nx_q10_to_f32(1536)) // 1.5x the reference
163 let w2: i64 = ff_max_rel_p1024(Cx, Cf, FF_COLS)
164 Cf[0] = saved
165 ff_puts(" (neg-control injected 50% error, measured " as *u8); ff_num(w2); ff_puts(" per-1048576)\n" as *u8)
166 var ok5: i64 = 0
167 if w2 > 409600 { ok5 = 1 }
168 gv_check("T5 neg-control: injected 50% error IS detected" as *u8, ok5, ctr)
169
170 let rc: i64 = gv_verdict("Q4K-FUSED-FIDELITY-GATE" as *u8, ctr,
171 "fused GEMM matches the live x4 path on real trained Q4_K weights" as *u8)
172 sys_exit(rc)
173 return rc
174}