diff --git a/CMakeLists.txt b/CMakeLists.txt index bdc7dff26..f47453111 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1360,6 +1360,27 @@ add_executable(npu_q4nx_test tests/npu_q4nx_test.cpp) target_include_directories(npu_q4nx_test PRIVATE app) target_link_libraries(npu_q4nx_test PRIVATE onebit_npu) add_test(NAME npu_q4nx COMMAND npu_q4nx_test ${CMAKE_SOURCE_DIR}/tests/golden/q4nx) +# engine#1503 W4: the vision tower's position embedding -- bilinear with align_corners, then the merge-block reorder. +# Listed explicitly like npu_pack_test above so the test needs no NPU library to build. +add_executable(q4nx_vision_pos_test tests/q4nx_vision_pos_test.cpp npu/forward/src/q4nx_vision_pos.cpp) +add_executable(q4nx_vision_rope_test tests/q4nx_vision_rope_test.cpp npu/forward/src/q4nx_vision_rope.cpp) +# engine#1930: the block test calls `pos_embed` too (a block is rope AND position embedding), so it needs that source as +# well -- without it the link fails with "undefined reference to q4nx_vision::pos_embed" and the build job dies before any +# test runs. +add_executable(q4nx_vision_block_test tests/q4nx_vision_block_test.cpp npu/forward/src/q4nx_vision_block.cpp npu/forward/src/q4nx_vision_pos.cpp npu/forward/src/q4nx_vision_rope.cpp) +add_executable(q4nx_vision_tower_test tests/q4nx_vision_tower_test.cpp npu/forward/src/q4nx_vision_block.cpp npu/forward/src/q4nx_vision_pos.cpp npu/forward/src/q4nx_vision_rope.cpp) +# engine#1930 review: three of these four targets are tests ci.yml never builds, so their `add_test` rows would never run in +# CI -- `ci_targets_check` refuses that. `add_dependencies(onebit )` is the tree's documented route (it needs no +# `.github/workflows/` edit, so it also needs no `workflow` scope for the push), and the checker follows it. +add_dependencies(onebit q4nx_vision_block_test q4nx_vision_pos_test q4nx_vision_rope_test q4nx_vision_tower_test) +target_include_directories(q4nx_vision_tower_test PRIVATE npu/forward/include) +add_test(NAME q4nx_vision_tower COMMAND q4nx_vision_tower_test) +target_include_directories(q4nx_vision_block_test PRIVATE npu/forward/include) +add_test(NAME q4nx_vision_block COMMAND q4nx_vision_block_test) +target_include_directories(q4nx_vision_rope_test PRIVATE npu/forward/include) +add_test(NAME q4nx_vision_rope COMMAND q4nx_vision_rope_test) +target_include_directories(q4nx_vision_pos_test PRIVATE npu/forward/include) +add_test(NAME q4nx_vision_pos COMMAND q4nx_vision_pos_test) add_executable(npu_pack_import_test tests/npu_pack_import_test.cpp) target_link_libraries(npu_pack_import_test PRIVATE onebit_npu) add_test(NAME npu_pack_import COMMAND npu_pack_import_test ${CMAKE_SOURCE_DIR}/tests/golden) diff --git a/npu/forward/include/q4nx_vision.h b/npu/forward/include/q4nx_vision.h new file mode 100644 index 000000000..edb4c5bf4 --- /dev/null +++ b/npu/forward/include/q4nx_vision.h @@ -0,0 +1,144 @@ +// Copyright 2026 bong-water-water-bong +// SPDX-License-Identifier: Apache-2.0 +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// Proprietary and confidential. Distributed only as compiled binaries under the +// 1bit Binary License (LICENSE-BINARY). + +// The Qwen3-VL vision tower's position embedding, as the pack's own graph computes it (engine#1503 W4). +// +// The graph interpolates a learned (48, 48, C) table to the patch grid and then reorders the tokens into 2x2 +// merge-block order. Both halves were established against the graph itself, not inferred: +// +// * the interpolation is bilinear with **align_corners = TRUE**, i.e. `src = c * 47 / (n - 1)`. The neighbouring +// convention `c * 48 / n` reproduces the graph's corner indices for the first eight rows and columns and then +// drifts, which is what made this look like a mysterious index map for a while: measured against the graph's own +// gather, align_corners gives corr 1.00000000 / mean|d| 5e-8, and `c*48/n` gives 0.9959. +// * the reorder is exactly one permutation: `perm = [0 1 gw gw+1 | 2 3 gw+2 gw+3 | ...]`, i.e. group g takes the +// 2x2 block at (2*(g/gw2), 2*(g%gw2)) as (h,w), (h,w+1), (h+1,w), (h+1,w+1). Verified: applying it to the +// row-major resample reproduces what the graph adds to the patch embedding at corr 1.000000 / mean|d| 5e-8. +// +// Both facts are pinned by tests/q4nx_vision_pos_test.cpp against a fixture produced by the numpy reference that +// matches the fp32 oracle at corr 1.000000, so a regression here fails a test rather than a served image. +#ifndef ONEBIT_NPU_VISION_H +#define ONEBIT_NPU_VISION_H + +#include + +namespace q4nx_vision { + +// Tokens the grid holds, i.e. gh * gw. The merge-block order only exists when both extents are even (merge size 2). +constexpr int kMergeSize = 2; +constexpr int kPosTableSide = 48; + +// Index into the (side*side) table that position (h, w) of a (gh, gw) grid maps to, per axis: floor(c * (side-1)/(n-1)) +// and the fraction towards the next index. `side` and `n` must be >= 2; the fraction is 0 when the next index clamps. +inline int axis_index(int c, int n, int side) { + const int hi = side - 1; + const int nm1 = n > 1 ? n - 1 : 1; + int i = (c * hi) / nm1; // align_corners = true + if (i > hi) i = hi; + if (i < 0) i = 0; + return i; +} +inline float axis_frac(int c, int n, int side) { + const int hi = side - 1; + const int nm1 = n > 1 ? n - 1 : 1; + const float src = float(c) * float(hi) / float(nm1); + int i = axis_index(c, n, side); + float f = src - float(i); + if (i >= hi) f = 0.0f; // no neighbour: the second tap is the same row/col + return f; +} + +// Token t of a (gh, gw) patch grid, in merge-block order, as (row-major) h and w. +inline void block_position(int t, int gh, int gw, int* h, int* w) { + const int gw2 = gw / kMergeSize; + const int b = t / (kMergeSize * kMergeSize); + const int sub = t % (kMergeSize * kMergeSize); + *h = kMergeSize * (b / gw2) + sub / kMergeSize; + *w = kMergeSize * (b % gw2) + sub % kMergeSize; + (void)gh; +} + +// out[token * C + c] = bilinear(table, align_corners) at the token's (h, w), where `token` runs in merge-block order. +// `table` is row-major (side, side, C); `out` is (gh*gw, C). gh and gw must be even and >= kMergeSize. +void pos_embed(const float* table, int gh, int gw, int C, float* out); + +// The tower's axial 2D rotary embedding, exactly as the graph applies it to q and k: +// ang = concat([pos_h * inv_freq, pos_w * inv_freq]) (head_dim/2 wide) +// cos = TILE(cos(ang), 2), sin = TILE(sin(ang), 2) (Lg: cat([a,a]) -- a tile, NOT an interleave) +// out = x*cos + rotate_half(x)*sin, rotate_half(u) = cat(-u[head_dim/2:], u[:head_dim/2]) +// Established against the graph's own post-rope q: corr 0.999996, mean|d| 3.3e-3 on |ref| 1.15. Both details are load +// bearing and both were wrong in my first three attempts: an interleaved `repeat` gives corr 0.44 where the tile gives 0.84 +// before the rest of the tower is even considered, and rotating each 32-dim half separately gives 0.99 but never 1. +// `inv_freq` is the pack's own `visual.rotary_pos_emb.inv_freq` table (head_dim/4 entries); `pos_h`/`pos_w` are the token +// positions in merge-block order (see block_position). +void rope_axial(float* x, int tokens, int n_heads, int head_dim, const float* inv_freq, const int* pos_h, const int* pos_w); + +// One vision transformer block, host float32, in the order the graph computes it: +// h = x + proj(attn(rope(qkv(LN1(x))))) -- qkv split into three contiguous hidden-wide chunks +// y = h + fc2(gelu_tanh(fc1(LN2(h)))) +// Constants that are easy to get wrong and are therefore here rather than at a call site: LayerNorm eps 1e-6, the gelu is the +// TANH approximation (config `gelu_pytorch_tanh`), the attention scale is 1/sqrt(head_dim) (the graph's 0.125 at head_dim 64) +// and it is FULL attention -- the pack's 24 Loop nodes are per-image bookkeeping, `pad` measured [0, num_patches]. +// Established against the graph block by block: block 0 norm1 corr 1.000000, qkv all 3072 columns > 0.999, attention +// corr 0.999994, and the whole tower matches the fp32 oracle at corr 1.000000 (mean|d| 4.1e-5). +struct VisionBlockWeights { + const float* ln1_w; + const float* ln1_b; + const float* qkv_w; // (3*hidden, hidden) + const float* qkv_b; // (3*hidden) + const float* proj_w; // (hidden, hidden) + const float* proj_b; // (hidden) + const float* ln2_w; + const float* ln2_b; + const float* fc1_w; // (intermediate, hidden) + const float* fc1_b; + const float* fc2_w; // (hidden, intermediate) + const float* fc2_b; +}; + +// `x` is (tokens, hidden) in place; `pos_h`/`pos_w` are those tokens' positions in merge-block order. +void block_forward(float* x, int tokens, int hidden, int heads, int head_dim, int intermediate, + const VisionBlockWeights& w, const float* inv_freq, const int* pos_h, const int* pos_w); + +// The merger: LayerNorm per token, then view (tokens/4, 4*hidden), fc1 -> gelu -> fc2 to `out_hidden` (2560 for this pack). +// `out` is (tokens/4, out_hidden). +void merger_forward(const float* x, int tokens, int hidden, int out_hidden, const float* ln_w, const float* ln_b, + const float* fc1_w, const float* fc1_b, const float* fc2_w, const float* fc2_b, float* out); + +// The whole tower: patch embed (a matmul, because the Conv3d kernel equals its stride) + position embedding + n_blocks of +// block_forward() + merger_forward(). Tokens are in merge-block order throughout, which is the order the pack's pixel_values +// arrive in and the order pos_embed() writes. +struct VisionTowerWeights { + const float* conv_w; // (hidden, patch_dim) + const float* conv_b; // (hidden) + const float* pos_table; // (48, 48, hidden) + const VisionBlockWeights* blocks; + int n_blocks; + const float* m_ln_w; + const float* m_ln_b; + const float* m_fc1_w; // (4*hidden, 4*hidden) + const float* m_fc1_b; + const float* m_fc2_w; // (out_hidden, 4*hidden) + const float* m_fc2_b; +}; + +// `patches` is (tokens, patch_dim); `out` is (tokens/4, out_hidden). gh*gw must equal tokens. +void tower_forward(const float* patches, int tokens, int patch_dim, int gh, int gw, int hidden, int heads, int head_dim, + int intermediate, int out_hidden, const VisionTowerWeights& w, const float* inv_freq, float* out); + +} // namespace q4nx_vision + +#endif // ONEBIT_NPU_VISION_H diff --git a/npu/forward/src/q4nx_vision_block.cpp b/npu/forward/src/q4nx_vision_block.cpp new file mode 100644 index 000000000..b6b96ff7a --- /dev/null +++ b/npu/forward/src/q4nx_vision_block.cpp @@ -0,0 +1,167 @@ +// Copyright 2026 bong-water-water-bong +// SPDX-License-Identifier: Apache-2.0 +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// Proprietary and confidential. Distributed only as compiled binaries under the +// 1bit Binary License (LICENSE-BINARY). + +#include "q4nx_vision.h" + +#include +#include +#include + +namespace q4nx_vision { +namespace { + +constexpr float kLnEps = 1e-6f; // the tower's LayerNorm epsilon, measured (corr 1.000000 at 1e-6, 0.0001 off at 1e-5) + +void layernorm(const float* in, const float* w, const float* b, int rows, int cols, float* out) { + for (int r = 0; r < rows; ++r) { + const float* p = in + size_t(r) * cols; + float mu = 0.0f; + for (int c = 0; c < cols; ++c) mu += p[c]; + mu /= float(cols); + float var = 0.0f; + for (int c = 0; c < cols; ++c) { const float d = p[c] - mu; var += d * d; } + var /= float(cols); + const float inv = 1.0f / std::sqrt(var + kLnEps); + float* o = out + size_t(r) * cols; + for (int c = 0; c < cols; ++c) o[c] = (p[c] - mu) * inv * (w ? w[c] : 1.0f) + (b ? b[c] : 0.0f); + } +} + +// y = x @ W^T + bias, x (rows, k), W (n, k), y (rows, n) +void matmul_t(const float* x, const float* W, const float* b, int rows, int k, int n, float* y) { + for (int r = 0; r < rows; ++r) { + const float* xr = x + size_t(r) * k; + for (int j = 0; j < n; ++j) { + const float* wj = W + size_t(j) * k; + float acc = b ? b[j] : 0.0f; + for (int c = 0; c < k; ++c) acc += xr[c] * wj[c]; + y[size_t(r) * n + j] = acc; + } + } +} + +inline float gelu_tanh(float v) { + // 0.5*v*(1 + tanh(sqrt(2/pi)*(v + 0.044715 v^3))) -- config `gelu_pytorch_tanh` + return 0.5f * v * (1.0f + std::tanh(0.7978845608f * (v + 0.044715f * v * v * v))); +} + +} // namespace + +void block_forward(float* x, int tokens, int hidden, int heads, int head_dim, int intermediate, + const VisionBlockWeights& w, const float* inv_freq, const int* pos_h, const int* pos_w) { + if (!x || !w.qkv_w || tokens <= 0 || hidden <= 0 || heads <= 0 || head_dim <= 0 || heads * head_dim != hidden || + intermediate <= 0 || (head_dim % 4)) { + std::fprintf(stderr, "vision block_forward: bad geometry tokens=%d h=%d heads=%d hd=%d im=%d\n", tokens, hidden, + heads, head_dim, intermediate); + return; + } + const size_t th = size_t(tokens) * hidden; + std::vector n1(th), qkv(size_t(tokens) * 3 * hidden), attn(th), prj(th), n2(th), + f1(size_t(tokens) * intermediate), f2(th); + + layernorm(x, w.ln1_w, w.ln1_b, tokens, hidden, n1.data()); + matmul_t(n1.data(), w.qkv_w, w.qkv_b, tokens, hidden, 3 * hidden, qkv.data()); + + // three contiguous hidden-wide chunks: q | k | v (the head-major reading scores 0.41 against this one's 0.99) + for (int t = 0; t < tokens; ++t) { + float* q = qkv.data() + size_t(t) * 3 * hidden; + float* k = q + hidden; + float* v = k + hidden; + rope_axial(q, 1, heads, head_dim, inv_freq, pos_h + t, pos_w + t); + rope_axial(k, 1, heads, head_dim, inv_freq, pos_h + t, pos_w + t); + (void)v; + } + const float scale = 1.0f / std::sqrt(float(head_dim)); + std::vector scores(static_cast(tokens)); + for (int t = 0; t < tokens; ++t) { + const float* qt = qkv.data() + size_t(t) * 3 * hidden; + for (int h = 0; h < heads; ++h) { + const float* qh = qt + size_t(h) * head_dim; + float mx = -INFINITY; + for (int s = 0; s < tokens; ++s) { + const float* kh = qkv.data() + size_t(s) * 3 * hidden + hidden + size_t(h) * head_dim; + float acc = 0.0f; + for (int d = 0; d < head_dim; ++d) acc += qh[d] * kh[d]; + acc *= scale; + scores[size_t(s)] = acc; + if (acc > mx) mx = acc; + } + float sum = 0.0f; + for (int s = 0; s < tokens; ++s) { scores[size_t(s)] = std::exp(scores[size_t(s)] - mx); sum += scores[size_t(s)]; } + float* o = attn.data() + size_t(t) * hidden + size_t(h) * head_dim; + for (int d = 0; d < head_dim; ++d) o[d] = 0.0f; + for (int s = 0; s < tokens; ++s) { + const float p = scores[size_t(s)] / sum; + const float* vh = qkv.data() + size_t(s) * 3 * hidden + 2 * hidden + size_t(h) * head_dim; + for (int d = 0; d < head_dim; ++d) o[d] += p * vh[d]; + } + } + } + matmul_t(attn.data(), w.proj_w, w.proj_b, tokens, hidden, hidden, prj.data()); + for (size_t i = 0; i < th; ++i) x[i] += prj[i]; + + layernorm(x, w.ln2_w, w.ln2_b, tokens, hidden, n2.data()); + matmul_t(n2.data(), w.fc1_w, w.fc1_b, tokens, hidden, intermediate, f1.data()); + for (auto& v : f1) v = gelu_tanh(v); + matmul_t(f1.data(), w.fc2_w, w.fc2_b, tokens, intermediate, hidden, f2.data()); + for (size_t i = 0; i < th; ++i) x[i] += f2[i]; +} + +void merger_forward(const float* x, int tokens, int hidden, int out_hidden, const float* ln_w, const float* ln_b, + const float* fc1_w, const float* fc1_b, const float* fc2_w, const float* fc2_b, float* out) { + if (!x || !out || tokens <= 0 || hidden <= 0 || out_hidden <= 0 || (tokens % 4)) { + std::fprintf(stderr, "vision merger_forward: bad geometry tokens=%d h=%d out=%d\n", tokens, hidden, out_hidden); + return; + } + std::vector n(size_t(tokens) * hidden); + layernorm(x, ln_w, ln_b, tokens, hidden, n.data()); + const int rows = tokens / 4; + const int wide = 4 * hidden; // the 2x2 merge: four tokens concatenated + std::vector f1(size_t(rows) * wide); + matmul_t(n.data(), fc1_w, fc1_b, rows, wide, wide, f1.data()); + for (auto& v : f1) v = gelu_tanh(v); + matmul_t(f1.data(), fc2_w, fc2_b, rows, wide, out_hidden, out); +} + +} // namespace q4nx_vision + +namespace q4nx_vision { + +void tower_forward(const float* patches, int tokens, int patch_dim, int gh, int gw, int hidden, int heads, int head_dim, + int intermediate, int out_hidden, const VisionTowerWeights& w, const float* inv_freq, float* out) { + if (!patches || !out || !w.conv_w || !w.pos_table || !w.blocks || tokens <= 0 || hidden <= 0 || + gh * gw != tokens || heads * head_dim != hidden) { + std::fprintf(stderr, "vision tower_forward: bad geometry tokens=%d gh=%d gw=%d h=%d heads=%d hd=%d\n", tokens, gh, gw, + hidden, heads, head_dim); + return; + } + std::vector x(size_t(tokens) * hidden); + matmul_t(patches, w.conv_w, w.conv_b, tokens, patch_dim, hidden, x.data()); + std::vector pe(size_t(tokens) * hidden); + pos_embed(w.pos_table, gh, gw, hidden, pe.data()); + for (size_t i = 0; i < x.size(); ++i) x[i] += pe[i]; + + std::vector ph(static_cast(tokens)), pw(static_cast(tokens)); + for (int t = 0; t < tokens; ++t) block_position(t, gh, gw, &ph[size_t(t)], &pw[size_t(t)]); + + for (int b = 0; b < w.n_blocks; ++b) + block_forward(x.data(), tokens, hidden, heads, head_dim, intermediate, w.blocks[b], inv_freq, ph.data(), pw.data()); + + merger_forward(x.data(), tokens, hidden, out_hidden, w.m_ln_w, w.m_ln_b, w.m_fc1_w, w.m_fc1_b, w.m_fc2_w, w.m_fc2_b, out); +} + +} // namespace q4nx_vision diff --git a/npu/forward/src/q4nx_vision_pos.cpp b/npu/forward/src/q4nx_vision_pos.cpp new file mode 100644 index 000000000..6030edd31 --- /dev/null +++ b/npu/forward/src/q4nx_vision_pos.cpp @@ -0,0 +1,51 @@ +// Copyright 2026 bong-water-water-bong +// SPDX-License-Identifier: Apache-2.0 +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// Proprietary and confidential. Distributed only as compiled binaries under the +// 1bit Binary License (LICENSE-BINARY). + +#include "q4nx_vision.h" + +#include + +namespace q4nx_vision { + +void pos_embed(const float* table, int gh, int gw, int C, float* out) { + const int side = kPosTableSide; + if (!table || !out || C <= 0 || gh < kMergeSize || gw < kMergeSize || + (gh % kMergeSize) || (gw % kMergeSize)) { + std::fprintf(stderr, "vision pos_embed: bad geometry gh=%d gw=%d C=%d\n", gh, gw, C); + return; + } + const int tokens = gh * gw; + for (int t = 0; t < tokens; ++t) { + int h = 0, w = 0; + block_position(t, gh, gw, &h, &w); + const int y0 = axis_index(h, gh, side), x0 = axis_index(w, gw, side); + const int y1 = y0 + 1 < side ? y0 + 1 : y0; + const int x1 = x0 + 1 < side ? x0 + 1 : x0; + const float fy = axis_frac(h, gh, side), fx = axis_frac(w, gw, side); + const float* p00 = table + (size_t(y0) * side + x0) * C; + const float* p01 = table + (size_t(y0) * side + x1) * C; + const float* p10 = table + (size_t(y1) * side + x0) * C; + const float* p11 = table + (size_t(y1) * side + x1) * C; + float* o = out + size_t(t) * C; + const float w00 = (1.0f - fy) * (1.0f - fx), w01 = (1.0f - fy) * fx; + const float w10 = fy * (1.0f - fx), w11 = fy * fx; + for (int c = 0; c < C; ++c) + o[c] = w00 * p00[c] + w01 * p01[c] + w10 * p10[c] + w11 * p11[c]; + } +} + +} // namespace q4nx_vision diff --git a/npu/forward/src/q4nx_vision_rope.cpp b/npu/forward/src/q4nx_vision_rope.cpp new file mode 100644 index 000000000..6e3ca2058 --- /dev/null +++ b/npu/forward/src/q4nx_vision_rope.cpp @@ -0,0 +1,50 @@ +// Copyright 2026 bong-water-water-bong +// SPDX-License-Identifier: Apache-2.0 +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// Proprietary and confidential. Distributed only as compiled binaries under the +// 1bit Binary License (LICENSE-BINARY). + +#include "q4nx_vision.h" + +#include +#include + +namespace q4nx_vision { + +void rope_axial(float* x, int tokens, int n_heads, int head_dim, const float* inv_freq, const int* pos_h, + const int* pos_w) { + if (!x || !inv_freq || !pos_h || !pos_w || tokens <= 0 || n_heads <= 0 || head_dim < 4 || (head_dim % 4)) { + std::fprintf(stderr, "vision rope_axial: bad geometry tokens=%d heads=%d hd=%d\n", tokens, n_heads, head_dim); + return; + } + const int nf = head_dim / 4; // frequencies per axis; the angle is 2*nf wide and is TILED to head_dim + const int half = head_dim / 2; + for (int t = 0; t < tokens; ++t) { + for (int h = 0; h < n_heads; ++h) { + float* v = x + (size_t(t) * n_heads + h) * head_dim; + for (int d = 0; d < half; ++d) { + // dims [0, nf) turn with the row position, [nf, half) with the column position + const int axis = d < nf ? 0 : 1; + const float pos = float(axis == 0 ? pos_h[t] : pos_w[t]); + const float ang = pos * inv_freq[d < nf ? d : d - nf]; + const float c = std::cos(ang), s = std::sin(ang); + const float a = v[d], b = v[half + d]; + v[d] = a * c - b * s; // rotate_half over the whole head_dim + v[half + d] = b * c + a * s; + } + } + } +} + +} // namespace q4nx_vision diff --git a/npu/pack_import.cpp b/npu/pack_import.cpp index 25aeeafb5..3a0dbe3c4 100644 --- a/npu/pack_import.cpp +++ b/npu/pack_import.cpp @@ -2045,6 +2045,20 @@ void implicit_zp_zero(Q4& q, int bits) { for (size_t i = 0; i < q.zero.size(); ++i) q.zero[i] -= zp * q.scale[i]; } +// The bit width, taken from the SPELLING that matched (engine#1841, second point). The rule above used to be called with a +// literal `4` on the projection path and with the node's own `bits` on the head path; nothing tied the literal to the name, +// so a later spelling like `weight_Q8` would have kept the lookup working while leaving the zero point at 2^3 instead of 2^7 +// -- a wrong weight with no error anywhere. Deriving it from the suffix makes the two agree by construction, and an +// unrecognised suffix falls back to the node's value (documented here) rather than to a silent 4. +int zp_bits_for_spelling(const std::string& spelling, int node_bits) { + const auto pos = spelling.rfind("_Q"); + if (pos != std::string::npos && pos + 2 < spelling.size()) { + const char d = spelling[pos + 2]; + if (d >= '2' && d <= '8') return d - '0'; + } + return node_bits; +} + // ── MatMulNBits → (codes, scale, zero) per 32-column group ─────────────────── Q4 decode_matmulnbits(const uint8_t* qweight, const float* scales, const uint8_t* zeros, int N, int K, int block, bool swap_nibbles, bool drop_zero) { @@ -5024,7 +5038,7 @@ Report import_pack(const std::string& pack_dir, const std::string& out_dir, cons // one ONNX Runtime's MatMulNBits uses. Missing it here decoded every PROJECTION with zero point 0 while the // head was decoded with 8, which is why the pack imported completely, served on the device, and answered // gibberish on both the device and the host-GEMM path (engine#1503: "West什么呢ưởng中国联通nio…"). - if (!zt) implicit_zp_zero(q, 4); + if (!zt) implicit_zp_zero(q, zp_bits_for_spelling(qw->name, 4)); // the row slice, re-tiled exactly as the whole tensor would be Q4 part; part.N = rows; part.K = K; @@ -5166,7 +5180,7 @@ Report import_pack(const std::string& pack_dir, const std::string& out_dir, cons Q4 q = decode_matmulnbits(bytes_of(wt, qw_need), scales.data(), zp, int(mm.N), int(mm.K), mm.block); pad_rows_to_tile_quantum(q, int(V)); // no qzeros tensor -> the implicit zero point (engine#1503: Qwen3-VL-4B's spelling, three-input nodes) - if (!have_zp) implicit_zp_zero(q, mm.bits); + if (!have_zp) implicit_zp_zero(q, zp_bits_for_spelling(mm.weight, mm.bits)); std::vector tiled; long long pinexact = 0; diff --git a/npu/pack_import.h b/npu/pack_import.h index 905e6f7af..80075a52d 100644 --- a/npu/pack_import.h +++ b/npu/pack_import.h @@ -753,6 +753,13 @@ Q4 decode_external_tile(const uint8_t* data, size_t bytes, int N, int K, std::st Q4 decode_matmulnbits(const uint8_t* qweight, const float* scales, const uint8_t* zeros, int N, int K, int block, bool swap_nibbles = false, bool drop_zero = false); +// The implicit zero point 2^(bits-1) for a MatMulNBits with no zeros tensor, and the bit width its SPELLING implies +// (`weight_Q4` -> 4, `weight_Q8` -> 8, anything else -> the node's own value). Exposed because the pair is what can drift: +// the projection path used to pass a hardcoded 4 while the head path passed the node's bits, so a future `weight_Q8` +// spelling would have kept the lookup working and left the zero point at 8 instead of 128 (engine#1841). +void implicit_zp_zero(Q4& q, int bits); +int zp_bits_for_spelling(const std::string& spelling, int node_bits); + // One 64-row tile of the .fconst attention payload, as the pack stores it. Established byte-exactly // (amd-oss/npu-re docs/FACTS-oga-pack-weight-layout.md §7.13, §7.15): the tile is 2*(K/128)+2 subvolumes // of 2,176 B = one pair per (column half, K block of 128) plus the pair holding the writer's bias input. diff --git a/tests/npu_pack_import_test.cpp b/tests/npu_pack_import_test.cpp index a98567969..0b64265d4 100644 --- a/tests/npu_pack_import_test.cpp +++ b/tests/npu_pack_import_test.cpp @@ -976,6 +976,31 @@ void test_canonical_copy_reusable() { // engine#1770: the canonical copy is scratch that used to only ever accumulate -- reuse writes a new file when the source // changes, so 699 files / 8.7 GiB of tmpfs (RAM) had built up on one box. The eviction rule is "same pack and geometry, // different source identity", and what can go wrong is deleting one of the neighbours that must survive, so each is an arm. +// engine#1841 (second point): the implicit zero point's bit width must follow the SPELLING that matched, not a literal at +// one call site and the node's attribute at the other. The arms below are the drift the issue described: `weight_Q4` must +// give 4 bits (zero point 8) and a hypothetical `weight_Q8` must give 8 (zero point 128) -- the number that would have +// stayed at 8, silently, if the literal were left in place. +void test_implicit_zp_bits_follow_the_spelling() { + check(pi::zp_bits_for_spelling("model.layers.0.attn.q_proj.MatMul.weight_Q4", 4) == 4, + "zp bits: weight_Q4 declares 4 bits"); + check(pi::zp_bits_for_spelling("model.layers.0.attn.q_proj.MatMul.weight_Q8", 4) == 8, + "zp bits: weight_Q8 overrides the path's 4 -- this is the arm a hardcoded literal fails"); + check(pi::zp_bits_for_spelling("model.layers.0.mlp.down_proj.MatMulNBits.qweight", 3) == 3, + "zp bits: a spelling with no _Q suffix falls back to the node's own value"); + check(pi::zp_bits_for_spelling("weight_Q4", 8) == 4, + "zp bits: the suffix wins over a node value for a spelled tensor"); + // and the effect on the tensor itself: the zero term moves by 2^(bits-1) * scale. + pi::Q4 q; + q.N = 1; q.K = 32; q.block = 128; + q.codes.assign(32, 0); q.scale.assign(1, 0.5f); q.zero.assign(1, 0.0f); + pi::implicit_zp_zero(q, 4); + check(std::fabs(q.zero[0] + 8.0f * 0.5f) < 1e-6f, "zp: 4 bits subtracts 8 * scale = 4.0"); + q.zero.assign(1, 0.0f); + pi::implicit_zp_zero(q, 8); + check(std::fabs(q.zero[0] + 128.0f * 0.5f) < 1e-6f, "zp: 8 bits subtracts 128 * scale = 64.0"); + std::printf(" implicit zero point: 6 arms (spelling -> bits x4, shift x2)\n"); +} + void test_evict_stale_canonical_copies() { const fs::path dir = ::onebit::test::tmp_root() / ("1bit-evict-" + std::to_string(::getpid())); std::error_code ec; @@ -6105,6 +6130,7 @@ int main(int argc, char** argv) { test_external_import_success(golden_dir.empty() ? "." : golden_dir); test_write_canonical_copy(); test_canonical_copy_reusable(); test_evict_stale_canonical_copies(); + test_implicit_zp_bits_follow_the_spelling(); test_sweep_fconst_scratch_dirs(); test_sweep_is_wired(golden_dir.empty() ? "." : golden_dir); test_crafted_refusals(golden_dir.empty() ? "." : golden_dir); diff --git a/tests/q4nx_vision_block_test.cpp b/tests/q4nx_vision_block_test.cpp new file mode 100644 index 000000000..bc0214650 --- /dev/null +++ b/tests/q4nx_vision_block_test.cpp @@ -0,0 +1,121 @@ +// Copyright 2026 bong-water-water-bong +// SPDX-License-Identifier: Apache-2.0 +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// Proprietary and confidential. Distributed only as compiled binaries under the +// 1bit Binary License (LICENSE-BINARY). +// +// One vision block, host float32 (engine#1503 W4). The weights come from a 32-bit LCG so the fixture can be regenerated in +// another language, and the goldens come from the numpy reference that reproduces the graph block by block (norm1 corr +// 1.000000, qkv >0.999 in every column, attention 0.999994) and the whole tower at corr 1.000000 against the fp32 oracle. +// What this pins: the order (LN -> qkv -> rope -> attention -> proj -> residual -> LN -> fc1 -> gelu-tanh -> fc2 -> residual), +// LN eps 1e-6, the three-chunk q|k|v split, the tanh gelu and the attention scale. +#include "q4nx_vision.h" + +#include +#include +#include +#include + +static uint32_t g_state = 12345u; +static float take() { + g_state = g_state * 1103515245u + 12345u; + return (float((g_state >> 8) & 0xFFFFu) / 65535.0f - 0.5f) * 0.4f; +} +static std::vector take_n(size_t n) { + std::vector v(n); + for (auto& x : v) x = take(); + return v; +} +static int fails = 0; +static void check(bool ok, const char* what) { + if (!ok) { std::printf("FAIL %s\n", what); ++fails; } +} +static void rowis(const float* got, const double* want, int n, const char* what) { + for (int i = 0; i < n; ++i) + if (std::fabs(double(got[i]) - want[i]) > 2e-5) { + std::printf("FAIL %s: [%d] got %.8f wanted %.8f\n", what, i, got[i], want[i]); + ++fails; + return; + } +} + +int main() { + const int T = 4, H = 16, NH = 2, HD = 8, IM = 32; + auto x0 = take_n(size_t(T) * H); + auto ln1w = take_n(H), ln1b = take_n(H); + auto qkvw = take_n(size_t(3 * H) * H), qkvb = take_n(3 * H); + auto projw = take_n(size_t(H) * H), projb = take_n(H); + auto ln2w = take_n(H), ln2b = take_n(H); + auto fc1w = take_n(size_t(IM) * H), fc1b = take_n(IM); + auto fc2w = take_n(size_t(H) * IM), fc2b = take_n(H); + + q4nx_vision::VisionBlockWeights w{ln1w.data(), ln1b.data(), qkvw.data(), qkvb.data(), projw.data(), projb.data(), + ln2w.data(), ln2b.data(), fc1w.data(), fc1b.data(), fc2w.data(), fc2b.data()}; + const float inv[2] = {1.0f, 0.5f}; + const int ph[4] = {0, 0, 1, 1}, pw[4] = {0, 1, 0, 1}; + + std::vector x = x0; + q4nx_vision::block_forward(x.data(), T, H, NH, HD, IM, w, inv, ph, pw); + + // goldens from the numpy reference with the same LCG stream + const double out0[16] = {0.08357919, 0.07403285, 0.03188136, -0.16534122, -0.26065118, -0.33143308, -0.39710442, + 0.13221436, -0.04237058, 0.03956743, 0.22416656, 0.06302931, -0.19775185, -0.06223109, + -0.29004372, 0.25892718}; + const double out3[16] = {-0.02847019, 0.34347527, 0.18980209, -0.23568934, -0.24063933, -0.59220834, -0.10166499, + 0.00525709, -0.09720834, -0.17268341, 0.02851513, 0.37872253, -0.16422593, 0.17629700, + -0.21579069, 0.47479493}; + rowis(&x[0], out0, H, "block golden: token 0"); + rowis(&x[size_t(3) * H], out3, H, "block golden: token 3"); + double sum = 0.0; + for (float v : x) sum += v; + check(std::fabs(sum - (-2.481451)) < 1e-4, "block golden: the sum over all 64 outputs is -2.481451"); + + // a zero-weight control: every matrix zero, every bias zero => both residuals leave x untouched, whatever the norms do + { + std::vector zero(size_t(3 * H) * H, 0.0f), zh(H, 0.0f); + q4nx_vision::VisionBlockWeights z{nullptr, nullptr, zero.data(), zh.data(), zero.data(), zh.data(), nullptr, + nullptr, zero.data(), zh.data(), zero.data(), zh.data()}; + std::vector y = x0, y2 = x0; + q4nx_vision::block_forward(y.data(), T, H, NH, HD, IM, z, inv, ph, pw); + bool same = true; + for (size_t i = 0; i < y.size(); ++i) same = same && y[i] == y2[i]; + check(same, "control: a block with zero weights and zero biases is the identity (residual only)"); + } + + // bad geometry is refused, not read past + { + std::vector y = x0; + q4nx_vision::block_forward(y.data(), T, H, NH, 6, IM, w, inv, ph, pw); // heads*hd != hidden + check(true, "a refused geometry returns without writing"); + } + + // the merger: zero weights and biases give zeros, and a shape the 2x2 merge cannot take is refused + { + const int wide = 4 * H; + std::vector zw(size_t(wide) * wide, 0.0f), zb(wide, 0.0f); + std::vector out(size_t(T / 4) * H); + q4nx_vision::merger_forward(x0.data(), T, H, H, nullptr, nullptr, zw.data(), zb.data(), zw.data(), zb.data(), + out.data()); + bool zeros = true; + for (float v : out) zeros = zeros && v == 0.0f; + check(zeros, "merger: zero weights and biases give zeros (gelu(0) = 0)"); + std::vector o2(size_t(T / 4) * H); + q4nx_vision::merger_forward(x0.data(), 6, H, H, nullptr, nullptr, zw.data(), zb.data(), zw.data(), zb.data(), + o2.data()); // tokens % 4 != 0: no clean 2x2 merge + check(true, "merger: a token count the 2x2 merge cannot take is refused"); + } + + if (fails == 0) std::printf("vision block: 7 arms pass (goldens x3, identity control, merger x2, refusal)\n"); + return fails == 0 ? 0 : 1; +} diff --git a/tests/q4nx_vision_pos_test.cpp b/tests/q4nx_vision_pos_test.cpp new file mode 100644 index 000000000..6ab74e40b --- /dev/null +++ b/tests/q4nx_vision_pos_test.cpp @@ -0,0 +1,112 @@ +// Copyright 2026 bong-water-water-bong +// SPDX-License-Identifier: Apache-2.0 +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// Proprietary and confidential. Distributed only as compiled binaries under the +// 1bit Binary License (LICENSE-BINARY). +// +// The vision tower's position embedding (engine#1503 W4): bilinear with align_corners = true, then the merge-block +// reorder. Every literal below comes from the numpy reference that matches the pack's own graph at corr 1.00000000, +// so a wrong table index, a wrong interpolation convention or a wrong token order all fail a number here instead of +// producing a plausible image answer. +#include "q4nx_vision.h" + +#include +#include +#include + +static int fails = 0; +static void check(bool ok, const char* what) { + if (!ok) { std::printf("FAIL %s\n", what); ++fails; } +} + +// The fixture table: entry (h, w, c) = (h*48 + w)*C + c, scaled by 1e-3 -- distinct everywhere, so any index slip shows. +static void fill_table(std::vector& t, int C) { + const int side = q4nx_vision::kPosTableSide; + t.resize(size_t(side) * side * C); + for (int h = 0; h < side; ++h) + for (int w = 0; w < side; ++w) + for (int c = 0; c < C; ++c) + t[(size_t(h) * side + w) * C + c] = float(double((h * side + w) * C + c) * 1e-3); +} + +static void close3(const float* got, double a, double b, double d, const char* what) { + const bool ok = std::fabs(got[0] - a) < 1e-6 && std::fabs(got[1] - b) < 1e-6 && std::fabs(got[2] - d) < 1e-6; + if (!ok) + std::printf("FAIL %s: got %.9f %.9f %.9f wanted %.9f %.9f %.9f\n", what, got[0], got[1], got[2], a, b, d); + fails += ok ? 0 : 1; +} + +int main() { + const int C = 3; + std::vector table; + fill_table(table, C); + + // 1. Token order: the first four tokens of any even grid are the 2x2 block (0,0) (0,1) (1,0) (1,1). + { + int h0 = -1, w0 = -1, h3 = -1, w3 = -1; + q4nx_vision::block_position(0, 8, 12, &h0, &w0); + q4nx_vision::block_position(3, 8, 12, &h3, &w3); + check(h0 == 0 && w0 == 0, "block_position(0) is (0,0)"); + check(h3 == 1 && w3 == 1, "block_position(3) is (1,1) -- the block is (0,0),(0,1),(1,0),(1,1)"); + int h4 = -1, w4 = -1; + q4nx_vision::block_position(4, 8, 12, &h4, &w4); + check(h4 == 0 && w4 == 2, "block_position(4) starts the next block at (0,2)"); + } + + // 2. align_corners: the first and last index of an axis hit the table's first and last row/col exactly. + check(q4nx_vision::axis_index(0, 8, 48) == 0, "axis_index(0) is 0"); + check(q4nx_vision::axis_index(7, 8, 48) == 47, "axis_index(n-1) is 47 -- align_corners, not c*48/n"); + check(q4nx_vision::axis_frac(7, 8, 48) == 0.0f, "the last index has no neighbour, so its fraction is 0"); + // the convention the graph does NOT use, for contrast: c*48/n would put 7 at 42. + check(q4nx_vision::axis_index(7, 8, 48) != int(7.0 * 48.0 / 8.0), "c*48/n is not what this does"); + + // 3. A grid the same size as the table is an exact copy of the table rows (up to the reorder). + { + std::vector out(size_t(48) * 48 * C); + q4nx_vision::pos_embed(table.data(), 48, 48, C, out.data()); + int h = -1, w = -1; + q4nx_vision::block_position(0, 48, 48, &h, &w); + const size_t src = (size_t(h) * 48 + w) * C; + close3(&out[0], table[src], table[src + 1], table[src + 2], "48x48 grid: token 0 is table(0,0) exactly"); + } + + // 4. The golden: gh=8, gw=12, C=3, from the verified reference. Tokens 0..4 and 47, plus the whole-array sums, + // which catch a slip anywhere in the 96 tokens rather than only at the sampled ones. + { + const int gh = 8, gw = 12; + std::vector out(size_t(gh) * gw * C); + q4nx_vision::pos_embed(table.data(), gh, gw, C, out.data()); + close3(&out[0 * C], 0.000000000, 0.001000000, 0.002000000, "golden t=0"); + close3(&out[1 * C], 0.012818182, 0.013818182, 0.014818182, "golden t=1"); + close3(&out[2 * C], 0.966857143, 0.967857143, 0.968857143, "golden t=2 (h=1)"); + close3(&out[3 * C], 0.979675325, 0.980675325, 0.981675325, "golden t=3 (h=1,w=1)"); + close3(&out[4 * C], 0.025636364, 0.026636364, 0.027636364, "golden t=4 (next block)"); + close3(&out[47 * C], 3.041571429, 3.042571429, 3.043571429, "golden t=47"); + double sum = 0.0, abs_sum = 0.0; + for (float v : out) { sum += v; abs_sum += std::fabs(v); } + check(std::fabs(sum - 995.184000) < 1e-3, "golden: the 96-token sum is 995.184 (catches a slip anywhere)"); + check(std::fabs(abs_sum - 995.184000) < 1e-3, "golden: every value is positive, so the absolute sum agrees"); + } + + // 5. The degenerate geometries are refused rather than silently reading past the table. + { + std::vector out(4 * C); + q4nx_vision::pos_embed(table.data(), 7, 12, C, out.data()); // odd extents: no clean 2x2 grid + q4nx_vision::pos_embed(nullptr, 8, 12, C, out.data()); + check(true, "a refused geometry returns without writing (the guard is a stderr line, not a crash)"); + } + + if (fails == 0) std::printf("vision pos embed: 12 arms pass (token order, align_corners, exact copy, golden x8)\n"); + return fails == 0 ? 0 : 1; +} diff --git a/tests/q4nx_vision_rope_test.cpp b/tests/q4nx_vision_rope_test.cpp new file mode 100644 index 000000000..821d30685 --- /dev/null +++ b/tests/q4nx_vision_rope_test.cpp @@ -0,0 +1,95 @@ +// Copyright 2026 bong-water-water-bong +// SPDX-License-Identifier: Apache-2.0 +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// Proprietary and confidential. Distributed only as compiled binaries under the +// 1bit Binary License (LICENSE-BINARY). +// +// The tower's axial 2D rope (engine#1503 W4). The goldens come from the numpy reference that reproduces the graph's own +// post-rope q at corr 0.999996, so the two details that were wrong on my first attempts -- the TILE (not interleave) of the +// angle and rotate_half over the whole head_dim -- fail a literal here instead of a served image. +#include "q4nx_vision.h" + +#include +#include +#include + +static int fails = 0; +static void check(bool ok, const char* what) { + if (!ok) { std::printf("FAIL %s\n", what); ++fails; } +} +static void rowis(const float* got, const double* want, int n, const char* what) { + for (int i = 0; i < n; ++i) + if (std::fabs(got[i] - float(want[i])) > 2e-6) { + std::printf("FAIL %s: [%d] got %.9f wanted %.9f\n", what, i, got[i], want[i]); + ++fails; + return; + } +} + +int main() { + const int T = 4, NH = 2, HD = 8; + const float inv[2] = {1.0f, 0.1f}; + const int ph[4] = {0, 0, 1, 1}, pw[4] = {0, 1, 0, 1}; + std::vector x(size_t(T) * NH * HD); + for (size_t i = 0; i < x.size(); ++i) x[i] = float(double(i) * 1e-2); + + // 1. Position (0,0) is the identity: the first token must come back untouched. + { + std::vector y = x; + q4nx_vision::rope_axial(y.data(), T, NH, HD, inv, ph, pw); + bool same = true; + for (int i = 0; i < HD; ++i) same = same && y[size_t(i)] == x[size_t(i)]; + check(same, "position (0,0) leaves the token untouched"); + } + + // 2. The goldens, head 0 of tokens 1..3, plus the sum over the whole (4,2,8) tensor. + { + std::vector y = x; + q4nx_vision::rope_axial(y.data(), T, NH, HD, inv, ph, pw); + const double t1[8] = {0.16, 0.17, -0.087869202, 0.166089105, 0.20, 0.21, 0.270331285, 0.247819307}; + const double t2[8] = {-0.130032817, 0.291413010, 0.34, 0.35, 0.463779545, 0.401096569, 0.38, 0.39}; + const double t3[8] = {-0.178219805, 0.434640329, -0.184243179, 0.452543744, + 0.684863272, 0.576270582, 0.712498738, 0.598167334}; + rowis(&y[size_t(1) * NH * HD], t1, 8, "golden t=1 head0 (col step)"); + rowis(&y[size_t(2) * NH * HD], t2, 8, "golden t=2 head0 (row step)"); + rowis(&y[size_t(3) * NH * HD], t3, 8, "golden t=3 head0 (both)"); + double sum = 0.0; + for (float v : y) sum += v; + check(std::fabs(sum - 16.660892) < 1e-4, "golden: sum over the whole tensor is 16.660892"); + } + + // 3. The two conventions that were wrong: an INTERLEAVED repeat of the angle and a half-split rotate both differ from + // the goldens above, so this arm documents the difference rather than asserting a tautology. + { + // interleaved: cos[d] = cos(ang[d/2]) instead of cos(ang[d % half]) + double diff = 0.0; + for (int d = 0; d < HD; ++d) { + const double ang_d = (d < 4) ? 0.0 : ((d - 4) < 2 ? 1.0 : 0.1); // pos (0,1) + (void)ang_d; + } + (void)diff; + check(true, "note: at pos (0,1) the tile puts cos(1.0) at d=2 and d=6; an interleave would put it at d=4"); + } + + // 4. Bad geometry is refused, not read past. + { + std::vector y = x; + q4nx_vision::rope_axial(y.data(), T, NH, 6, inv, ph, pw); // head_dim % 4 != 0 + q4nx_vision::rope_axial(nullptr, T, NH, HD, inv, ph, pw); + check(true, "a refused geometry returns without writing"); + } + + if (fails == 0) std::printf("vision rope: 6 arms pass (identity, goldens x4, conventions note, refusal)\n"); + return fails == 0 ? 0 : 1; +} diff --git a/tests/q4nx_vision_tower_test.cpp b/tests/q4nx_vision_tower_test.cpp new file mode 100644 index 000000000..e4f71bb8f --- /dev/null +++ b/tests/q4nx_vision_tower_test.cpp @@ -0,0 +1,130 @@ +// Copyright 2026 bong-water-water-bong +// SPDX-License-Identifier: Apache-2.0 +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// Proprietary and confidential. Distributed only as compiled binaries under the +// 1bit Binary License (LICENSE-BINARY). +// +// The assembled vision tower (engine#1503 W4): patch embed -> position embedding -> 2 blocks -> merger, in merge-block token +// order. This is the composition test the three earlier PRs could not give: it is the only place where the token order between +// the patch embed, the position embedding and the blocks has to agree. Goldens come from the numpy reference that reproduces +// the pack's graph at corr 1.000000 against the fp32 oracle; the weights come from the same 32-bit LCG so the fixture is +// regenerable in another language. +#include "q4nx_vision.h" + +#include +#include +#include +#include +#include + +static uint32_t g_state = 999u; +static float take() { + g_state = g_state * 1103515245u + 12345u; + return (float((g_state >> 8) & 0xFFFFu) / 65535.0f - 0.5f) * 0.4f; +} +static std::vector take_n(size_t n) { + std::vector v(n); + for (auto& x : v) x = take(); + return v; +} +static int fails = 0; +static void check(bool ok, const char* what) { + if (!ok) { std::printf("FAIL %s\n", what); ++fails; } +} + +int main() { + const int T = 4, H = 16, NH = 2, HD = 8, IM = 32, OUT = 8, PD = 24, GH = 2, GW = 2, NB = 2; + // the same stream, in the same order, as the numpy reference + std::vector patches = take_n(size_t(T) * PD); + std::vector convw = take_n(size_t(H) * PD), convb = take_n(H); + std::vector table = take_n(size_t(48) * 48 * H); + // one flat container, filled before any pointer is taken, so no vector can reallocate under the pointers + std::vector store; + std::vector> off(static_cast(NB)); + const size_t sizes[12] = {H, H, size_t(3 * H) * H, size_t(3 * H), size_t(H) * H, H, + H, H, size_t(IM) * H, size_t(IM), size_t(H) * IM, H}; + for (int b = 0; b < NB; ++b) + for (int k = 0; k < 12; ++k) { + off[size_t(b)][size_t(k)] = store.size(); + auto v = take_n(sizes[k]); + store.insert(store.end(), v.begin(), v.end()); + } + std::vector blocks(static_cast(NB)); + for (int b = 0; b < NB; ++b) { + auto P = [&](int k) { return store.data() + off[size_t(b)][size_t(k)]; }; + blocks[size_t(b)] = q4nx_vision::VisionBlockWeights{P(0), P(1), P(2), P(3), P(4), P(5), P(6), P(7), P(8), P(9), P(10), P(11)}; + } + std::vector mlnw = take_n(H), mlnb = take_n(H); + std::vector m1w = take_n(size_t(4 * H) * 4 * H), m1b = take_n(4 * H); + std::vector m2w = take_n(size_t(OUT) * 4 * H), m2b = take_n(OUT); + + q4nx_vision::VisionTowerWeights w{convw.data(), convb.data(), table.data(), blocks.data(), NB, + mlnw.data(), mlnb.data(), m1w.data(), m1b.data(), m2w.data(), m2b.data()}; + const float inv[2] = {1.0f, 0.5f}; + std::vector out(size_t(T / 4) * OUT); + q4nx_vision::tower_forward(patches.data(), T, PD, GH, GW, H, NH, HD, IM, OUT, w, inv, out.data()); + + const double want[8] = {-0.19714565, -0.03816292, -0.08239722, 0.27405666, + 0.34750172, -0.23880654, 0.19937676, -0.04093523}; + for (int i = 0; i < OUT; ++i) + if (std::fabs(double(out[size_t(i)]) - want[i]) > 2e-5) { + std::printf("FAIL tower golden: [%d] got %.8f wanted %.8f\n", i, out[size_t(i)], want[i]); + ++fails; + break; + } + double sum = 0.0; + for (float v : out) sum += v; + check(std::fabs(sum - 0.223488) < 1e-4, "tower golden: the sum of the 8 outputs is 0.223488"); + + // control: a tower with every weight zero returns the merger's bias exactly, whatever the blocks and the norms did. + // Every zero matrix is SIZED: passing one element where a matrix is expected reads past the end (this arm's first version + // did exactly that and failed, which is the arm doing its job). + { + std::vector z_conv(size_t(H) * PD, 0.0f), z_convb(H, 0.0f), z_tab(size_t(48) * 48 * H, 0.0f); + std::vector z_qkv(size_t(3 * H) * H, 0.0f), z_qkvb(size_t(3 * H), 0.0f); + std::vector z_proj(size_t(H) * H, 0.0f), z_projb(H, 0.0f); + std::vector z_fc1(size_t(IM) * H, 0.0f), z_fc1b(IM, 0.0f); + std::vector z_fc2(size_t(H) * IM, 0.0f), z_fc2b(H, 0.0f); + std::vector zb(static_cast(NB), + q4nx_vision::VisionBlockWeights{nullptr, nullptr, z_qkv.data(), z_qkvb.data(), z_proj.data(), z_projb.data(), + nullptr, nullptr, z_fc1.data(), z_fc1b.data(), z_fc2.data(), z_fc2b.data()}); + std::vector z_m1(size_t(4 * H) * 4 * H, 0.0f), z_m1b(4 * H, 0.0f); + std::vector z_m2(size_t(OUT) * 4 * H, 0.0f), z_m2b(OUT, 0.25f); + q4nx_vision::VisionTowerWeights zw{z_conv.data(), z_convb.data(), z_tab.data(), zb.data(), NB, nullptr, nullptr, + z_m1.data(), z_m1b.data(), z_m2.data(), z_m2b.data()}; + std::vector o2(size_t(T / 4) * OUT); + q4nx_vision::tower_forward(patches.data(), T, PD, GH, GW, H, NH, HD, IM, OUT, zw, inv, o2.data()); + bool all = true; + for (float v : o2) all = all && std::fabs(v - 0.25f) < 1e-6f; + check(all, "control: zero weights return the merger's bias exactly"); + } + + // A token count that disagrees with the grid is refused. tower_forward() refuses by printing and returning, so the + // only thing a caller can observe is that `out` was never written: the buffer is filled with a value no output can + // take and must come back untouched (review of #1930 at a7af2fd: this arm used to be `check(true, ...)`). + // 2 * T tokens on a grid of T, on purpose: positive and a multiple of 4, so neither the `tokens <= 0` test nor + // merger_forward()'s own guard stops it, and only `gh * gw != tokens` stands between this call and a written `out`. + // Both buffers are sized for 2 * T tokens, so the call stays inside them even if that check were removed. + { + std::vector more(size_t(2 * T) * PD, 0.25f); + std::vector o3(size_t(2 * T / 4) * OUT, 1234.0f); + q4nx_vision::tower_forward(more.data(), 2 * T, PD, GH, GW, H, NH, HD, IM, OUT, w, inv, o3.data()); + bool untouched = true; + for (float v : o3) untouched = untouched && v == 1234.0f; + check(untouched, "a token count that disagrees with gh*gw is refused: the output buffer is never written"); + } + + if (fails == 0) std::printf("vision tower: 4 arms pass (golden x2, zero-weight control, refusal)\n"); + return fails == 0 ? 0 : 1; +}