Skip to content

bgz-tensor: symmetric signed-i8 probe + Fisher-Z error decomposition (lab, no wire change) - #1757

Merged
AdaWorldAPI merged 5 commits into
mainfrom
lab/symmetric-i8-tanh-research-20261024
Oct 24, 2026
Merged

AdaWorldAPI merged 5 commits into
mainfrom
lab/symmetric-i8-tanh-research-20261024

Conversation

@AdaWorldAPI

Copy link
Copy Markdown
Owner

Research only. Nothing here changes FamilyGamma, FisherZTable or any stored format.

What lands

  • crates/bgz-tensor/tests/symmetric_i8_quantization_probe.rs: exhaustive tests for a proposed −127..127 code space with −128 reserved as a sentinel (all 256 codes, all 256×256 add pairs, tie handling), measurements of the existing FamilyGamma contract, and a comparison of four schemes over 13 seeded distributions.
  • crates/bgz-tensor/examples/fisher_z_error_decomposition.rs: splits FamilyGamma's round-trip error into calibration, rounding, truncation, f32 decode and tanh-kernel stages that sum exactly to the total (asserted per pair).
  • .claude/board/entries/2026-10-24-tanh-precision-symmetric-i8.md: findings, the wire-contract analysis, and a real-data manifest marked NOT RUN.

Findings

  • The FamilyGamma decoder treats −128 as a valid value. build() never stores it, but encode() emits it for any input below the fitted range (cosine 0 in an all-positive family; 27 of 32,640 held-out pairs) and gives no signal. The format has no version byte and is written to safetensors by thinking-engine, so a sentinel would need a new versioned format.
  • as i8 truncation is the largest in-range error and the only biased stage: codes shift half a bin toward the mid code, about twice the rounding error.
  • Code 0 is the family's mid-z, not cosine 0. In an all-positive family it decodes to 0.656, so lookup_i8's 0 for an unknown centroid is not neutral there.
  • Symmetric quantization keeps exact zeros and matches affine on centred data (RMSE within 1%); affine wins by about 2× on shifted and skewed data.
  • The tanh kernel adds about 1e-8 against 1e-3 for quantization. vstanh (ndarray fix(simd,vml): simd_exp_f32 and vstanh within 1 ULP; tanh keeps ±0 and subnormals ndarray#369) stays within 2 ULP of f32::tanh on every decoded z.

Tests

  • cargo test --release -p bgz-tensor --test symmetric_i8_quantization_probe: 8/8 pass. Each of three disable runs turns the gate red: round half away from zero, no sentinel propagation, and an add clamped to −128.
  • The decomposition example and the test are clippy -D warnings clean and fmt clean.
  • The example compiles against the existing vstanh signature, so it does not depend on ndarray#369 merging.

NOT RUN: the real GGUF and safetensors families (manifest D1–D5).


Generated by Claude Code

Isolated mathematical tests for a proposed -127..127 code space with
-128 reserved as an invalid sentinel, measured against the existing
FamilyGamma codec, which is not changed:

- the code space: 255 values, one sentinel, one zero, odd negation;
  conventional i8 has no negation for -128
- saturating add over all 256x256 pairs: odd and commutative,
  sentinel propagates, valid inputs never produce it; conventional
  saturating_add breaks oddness on 16256 pairs
- round-half-to-even gives symmetric ties; floor(x+0.5) does not
- FamilyGamma: build() never stores -128, but encode() emits -128 for
  any input below the fitted range (cosine 0 in an all-positive family)
  and decodes it as a value; truncation shifts codes half a bin toward
  the mid code on both sides
- four schemes over 13 synthetic distributions: symmetric keeps exact
  zeros and matches affine on centred data; affine beats it by about
  2x RMSE on shifted and skewed data

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01G22yT6htkcdyXsihxxXdrg
Splits FamilyGamma's round-trip error into stages that telescope
exactly to the codec total (asserted per pair): input/range
calibration, rounding to a code, the codec's as-i8 truncation, f32
decode, and vstanh in place of f32::tanh on the same z.

On five seeded synthetic families (k=256, d=64): truncation is the
largest and the only biased stage (mean |e| 2.0e-3 against 1.0e-3 for
rounding in the centred family); the tanh kernel contributes about
3e-9 mean, 1.2e-7 max (<= 2 ULP from f32::tanh). A gamma fitted on 64
rows and applied to held-out rows clamps 80 pairs (27 to -128) and
calibration then dominates the max error (3.6e-2). A family whose
cosines all exceed the 0.9999 input clamp collapses to one z.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01G22yT6htkcdyXsihxxXdrg
@coderabbitai

coderabbitai Bot commented Oct 24, 2026 •

Copy link
Copy Markdown

Important

  • 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

Run configuration
  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 189681c4-d92f-4a45-8093-9386d6cb1789
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Warning

Billing warning: we have not been able to collect payment for this subscription for more than 72 hours. Please update the payment method or pay any pending invoices in Billing to avoid service interruption.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

…xed it

vml_vsneg_is_not_onnx_neg_on_positive_zero pinned vsneg(+0) == +0 so it
would fail once ndarray fixed the sign of zero. ndarray #368 did, and
the test fails on main (Rust Tests run 40047762268). The replacement
pins that vsneg and Neg both give -0.0 for +0.0 in the SIMD body and the
tail. Neg stays inline: vsneg is f32-only and writes into a view.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01G22yT6htkcdyXsihxxXdrg

Copy link
Copy Markdown
Owner Author

The test failure (lance-graph-onnx conformance, vml_vsneg_is_not_onnx_neg_on_positive_zero) is not caused by this PR's code. That test pinned ndarray's old vsneg(+0) == +0 bug so it would fail once the bug was fixed. ndarray #368 fixed it, and main's Rust Tests run 40047762268 fails on the same test.

I've put the fix in this PR: the test is replaced by vml_vsneg_matches_onnx_neg_on_positive_zero, which pins −0.0 from both vsneg and Neg in the SIMD body and the tail. The stale doc comment and the plan note are updated with it. Neg stays inline because vsneg is f32-only. cargo test -p lance-graph-onnx passes locally (11/11); clippy is clean.


Generated by Claude Code

@AdaWorldAPI
AdaWorldAPI marked this pull request as ready for review October 24, 2026 08:31
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 24, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-24T08:33:13.887633Z dda2861 Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@AdaWorldAPI
AdaWorldAPI merged commit 76e44b5 into main Oct 24, 2026
13 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants