From 14aba770b38c848c674e50873edbf5b5fe8b2757 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 21 Mar 2026 03:58:50 +0000 Subject: [PATCH 1/2] Fix LaTeX rendering of tau^* in DESIGN.md Replace \tau^{*} and \tau^* with \tau^{\ast} throughout. The literal asterisk inside math delimiters was being consumed by Markdown's italic parser before the LaTeX renderer saw it, producing "Extra close brace or missing open brace" errors and garbled output (HTML-escaped < and stripped braces). https://claude.ai/code/session_01Fbaft6AALu5o8MfFRxUdfV --- DESIGN.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/DESIGN.md b/DESIGN.md index 8509a4b..55f8ba1 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -305,29 +305,29 @@ $$\{A,\ B,\ C,\ D\} \;\longleftrightarrow\; \{\text{strong-},\ \text{weak-},\ \t where $n_s$ is the embedding dimension[^1], the maximum-entropy condition requires equiprobable states: -$$P(v_i \leq -\tau^{*}) = P(-\tau^{*} < v_i \leq 0) = P(0 < v_i \leq \tau^{*}) = P(v_i > \tau^{*}) = \tfrac{1}{4}$$ +$$P(v_i \leq -\tau^{\ast}) = P(-\tau^{\ast} < v_i \leq 0) = P(0 < v_i \leq \tau^{\ast}) = P(v_i > \tau^{\ast}) = \tfrac{1}{4}$$ The threshold is: -$$\tau^{*} = \frac{\Phi^{-1}(3/4)}{\sqrt{n_s}} \approx \frac{0.6745}{\sqrt{n_s}}$$ +$$\tau^{\ast} = \frac{\Phi^{-1}(3/4)}{\sqrt{n_s}} \approx \frac{0.6745}{\sqrt{n_s}}$$ **The quantization function:** -$$q(v_i) = \begin{cases} A & v_i \leq -\tau^{*} \\ B & -\tau^{*} < v_i \leq 0 \\ C & 0 < v_i \leq \tau^{*} \\ D & v_i > \tau^{*} \end{cases}$$ +$$q(v_i) = \begin{cases} A & v_i \leq -\tau^{\ast} \\ B & -\tau^{\ast} < v_i \leq 0 \\ C & 0 < v_i \leq \tau^{\ast} \\ D & v_i > \tau^{\ast} \end{cases}$$ -The four equiprobable zones on the real line, separated by $-\tau^{*}$, $0$, and $+\tau^{*}$: +The four equiprobable zones on the real line, separated by $-\tau^{\ast}$, $0$, and $+\tau^{\ast}$: ```mermaid graph LR A["A\nstrong -\n≤ -τ*"] --- B["B\nweak -\n(-τ*, 0]"] --- C["C\nweak +\n(0, τ*]"] --- D["D\nstrong +\n> τ*"] ``` -**Empirical calibration.** In practice $\tau^{*}$ is estimated from a reservoir sample +**Empirical calibration.** In practice $\tau^{\ast}$ is estimated from a reservoir sample of 1 024 sample activations per compaction cycle, using the empirical 25th and 75th percentiles of $v_i$ to keep the symbol distribution close to equiprobable without assuming a specific activation shape. -**Analytical threshold computation.** For source distributions expressible as polynomial or mixture models, the equiprobable threshold $\tau^*$ can be computed analytically via the hyper-Catalan series (Wildberger & Rubine 2025; the formal development is in §4.4). The threshold equation $F(\tau) = k/4$ for CDF $F$ becomes a polynomial in the distribution parameters, and the threshold solution $\alpha = \sum_\mathbf{m} C_\mathbf{m} \cdot t_2^{m_2} t_3^{m_3} \cdots$ converges without iteration. Truncation order trades precision for compute cost — a natural fit for the resource-constrained setting of §2.1. This does not replace empirical calibration; it provides a second path when a parametric model of the source distribution is available. +**Analytical threshold computation.** For source distributions expressible as polynomial or mixture models, the equiprobable threshold $\tau^{\ast}$ can be computed analytically via the hyper-Catalan series (Wildberger & Rubine 2025; the formal development is in §4.4). The threshold equation $F(\tau) = k/4$ for CDF $F$ becomes a polynomial in the distribution parameters, and the threshold solution $\alpha = \sum_\mathbf{m} C_\mathbf{m} \cdot t_2^{m_2} t_3^{m_3} \cdots$ converges without iteration. Truncation order trades precision for compute cost — a natural fit for the resource-constrained setting of §2.1. This does not replace empirical calibration; it provides a second path when a parametric model of the source distribution is available. Under the equiprobable target, each dimension carries: @@ -804,7 +804,7 @@ where each $C_\mathbf{m}$ is a hyper-Catalan number and $t_j$ are functions of t The series converges by direct evaluation — no Newton iteration, no gradient descent. On constrained hardware, a closed-form series that can be truncated to the precision affordable within the resource budget (§2.1) is preferable to an iterative solver that may not converge within budget. The truncation order itself is a resource-allocation decision: each additional term in the hyper-Catalan series refines the threshold, trading compute cost for quantization precision. -For the standard case ($q = 4$, Gaussian source), the series reduces to the known quartile $\tau^* = \Phi^{-1}(3/4)$. For mixture-of-Gaussians sources — the natural model for multi-modal activation distributions — the threshold is expressible as a hyper-Catalan series in the mixture weights. +For the standard case ($q = 4$, Gaussian source), the series reduces to the known quartile $\tau^{\ast} = \Phi^{-1}(3/4)$. For mixture-of-Gaussians sources — the natural model for multi-modal activation distributions — the threshold is expressible as a hyper-Catalan series in the mixture weights. --- From 11e495e6ab70779219e498f485c9389252c67729 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 21 Mar 2026 04:18:30 +0000 Subject: [PATCH 2/2] =?UTF-8?q?Rename=20Q2=20=E2=86=92=20Q=C2=B2=20through?= =?UTF-8?q?out=20docs;=20add=20asterisk=20lint=20rule?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The name "Q2" in the literature means 2-bit quantization. This project is Q-squared (quaternary quantization = Q²), so the distinction matters. Replace all prose occurrences of Q2 with Q² across DESIGN.md, README.md, RELATED_WORK.md, docs/wildberger-rubine-review.md, and docs/design-revision-plan.md. Update the RELATED_WORK.md TOC anchor for the renamed section heading. Also add a lint rule to scripts/lint-md.mjs (rule 2) that flags literal ASCII asterisk (*) inside $$ display math blocks. This is the root cause of the previous \tau^{*} breakage: Markdown consumes * as italic/bold before KaTeX sees it, producing "Extra close brace or missing open brace" errors. The rule enforces \ast instead, making it detectable at pre-commit. Closes #73 https://claude.ai/code/session_01Fbaft6AALu5o8MfFRxUdfV --- DESIGN.md | 14 ++-- README.md | 2 +- RELATED_WORK.md | 130 +++++++++++++++---------------- docs/design-revision-plan.md | 6 +- docs/wildberger-rubine-review.md | 44 +++++------ scripts/lint-md.mjs | 23 ++++-- 6 files changed, 116 insertions(+), 103 deletions(-) diff --git a/DESIGN.md b/DESIGN.md index 55f8ba1..ce2f1a1 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -728,13 +728,13 @@ where $S$ is the generating function for all structured codewords, $S_1$ is the In the language of quantization, this factorization describes **hierarchical quantization**: first decide the coarse cell, then refine within it. The Geode $G$ counts the refinement possibilities at each subsequent level. -For Q2's transition key, the factorization is concrete. The generating function for all transition sequences of length $\geq 1$ is: +For Q²'s transition key, the factorization is concrete. The generating function for all transition sequences of length $\geq 1$ is: $$S(x) - 1 = \frac{4x}{1 - 3x} = \underbrace{4x}_{S_1} \cdot \underbrace{\frac{1}{1-3x}}_{G}$$ The first factor $S_1 = 4x$ records the first symbol $r_0$ (4 choices, selecting the block file). The Geode $G = 1/(1-3x) = 1 + 3x + 9x^2 + \cdots$ counts all possible continuations — the tail of the key after the first symbol is fixed. -| Level | Paper | Q2 transition key | General quantization | +| Level | Paper | Q² transition key | General quantization | |:-----:|:------|:------------------|:--------------------| | Full structure | $S$ | All transition sequences | All codewords | | First level | $S_1$ | $r_0$ (first symbol → block file) | Coarse quantization cell | @@ -762,7 +762,7 @@ is governed by Euler's polytope formula $V - E + F = \chi$, where: Euler's formula constrains these quantities: you cannot have $F$ cells, $E$ boundaries, and $V$ vertices in arbitrary combination. The topology of the quantization lattice determines admissible $(V, E, F)$ triples. -For Q2 specifically, the $\mathbb{Z}_4$ cycle has $V = 4$ vertices, $E = 4$ edges, and $F = 1$ face (the single outer region): +For Q² specifically, the $\mathbb{Z}_4$ cycle has $V = 4$ vertices, $E = 4$ edges, and $F = 1$ face (the single outer region): $$4 - 4 + 1 = 1 = \chi \quad \checkmark$$ @@ -778,7 +778,7 @@ The Bi-Tri (and higher) hyper-Catalan arrays (Wildberger & Rubine 2025, Table 1) - A **binary split** is a 1-bit quantization step (above/below threshold). - A **ternary split** is a $\log_2 3 \approx 1.585$-bit step (below/near/above). -- A **quaternary split** is a 2-bit step (Q2's $\{A, B, C, D\}$). +- A **quaternary split** is a 2-bit step (Q²'s $\{A, B, C, D\}$). A general quantization framework may mix these: use 2-bit precision on high-variance dimensions and 1-bit on low-variance dimensions. The number of distinct mixed-precision codebooks with $m_2$ binary dimensions, $m_3$ ternary dimensions, and $m_4$ quaternary dimensions is: @@ -810,7 +810,7 @@ For the standard case ($q = 4$, Gaussian source), the series reduces to the know ### 4.5 Reconstruction and series reversion -If Q2 requires a decode path — for lossy compression applications rather than retrieval — the optimal reconstruction point for symbol $s$ is: +If Q² requires a decode path — for lossy compression applications rather than retrieval — the optimal reconstruction point for symbol $s$ is: $$\hat{x}(s) = \mathbb{E}[x \mid q(x) = s]$$ @@ -818,7 +818,7 @@ For non-uniform distributions, this is *not* the cell centroid; it is the condit The hyper-Catalan series provides this inversion combinatorially, without numerical root-finding. Wildberger & Rubine (2025, §10) show that Lagrange inversion and the hyper-Catalan series are two faces of the same coin: the series coefficients that solve the forward threshold problem also yield the inverse. -This is noted as a future extension. The current Q2 pipeline is retrieval-only (quantize, index, search); no reconstruction step is needed. Should a decode path become necessary — for example, in signal compression or approximate model distillation — the reconstruction formula is already provided by the series-reversion machinery. +This is noted as a future extension. The current Q² pipeline is retrieval-only (quantize, index, search); no reconstruction step is needed. Should a decode path become necessary — for example, in signal compression or approximate model distillation — the reconstruction formula is already provided by the series-reversion machinery. --- @@ -941,7 +941,7 @@ The run-reduced key captures that shared structure without requiring knowledge o The generalized framework makes the lingua franca case stronger. The transition key captures relational structure that is invariant under rotation. This invariance is not an accident of the semantic embedding application — it is a consequence of the general framework: structural quantization (§2.4) preserves relational geometry by design. The embedding application is a special case where the rotation $Q$ corresponds to the arbitrary coordinate frame of a trained model. Embeddings across models are not fully incommensurable. Their coordinate frames are; -their semantic geometry is not. The gap between those two facts is where Q2 operates. +their semantic geometry is not. The gap between those two facts is where Q² operates. $$\underbrace{\text{king} - \text{man} + \text{woman}}_{\text{vector arithmetic on any model}} \approx \underbrace{\text{queen}}_{\text{same answer, rotated frame}}$$ diff --git a/README.md b/README.md index cc34c73..abded72 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ Q² converts a model's hidden activations into a compact, retrieval-friendly 64 - Gray‑encode and pack symbols into bytes, then run‑reduce into a transition sequence. - Emit the first 32 transitions as a 64‑bit key, which can be searched efficiently with a Lee distance. -Q2 starts with quaternary quantization of a local model's own native embeddings. This produces something of a fingerprint for the semantic geometry the model is currently evaluating. +Q² starts with quaternary quantization of a local model's own native embeddings. This produces something of a fingerprint for the semantic geometry the model is currently evaluating. This geometry is a product of human language itself. Therefore, we propose that mapping the geometry will produce faster and more accurate embeddings and we believe it most likely solves the incommensurability problem of vector similarity search. diff --git a/RELATED_WORK.md b/RELATED_WORK.md index 43384c4..9a21cda 100644 --- a/RELATED_WORK.md +++ b/RELATED_WORK.md @@ -5,7 +5,7 @@ > This document surveys existing work on quaternary (2-bit, 4-level) quantization in > machine learning. It compares, contrasts, and distinguishes those approaches from > the structural quantization scheme described in [DESIGN.md](DESIGN.md), and -> identifies findings from the literature that are directly relevant to Q2. +> identifies findings from the literature that are directly relevant to Q². --- @@ -28,7 +28,7 @@ - 4.4 [Quaternary neural belief propagation (BP4) for QLDPC codes](#44-quaternary-neural-belief-propagation-bp4-for-qldpc-codes) - 4.5 [Image steganography (OPMS-QQGE)](#45-image-steganography-opms-qqge) 5. [Accuracy vs. Efficiency Trade-offs Across the Literature](#5-accuracy-vs-efficiency-trade-offs-across-the-literature) -6. [Key Distinctions: Q2 vs. the Field](#6-key-distinctions-q2-vs-the-field) +6. [Key Distinctions: Q² vs. the Field](#6-key-distinctions-q-vs-the-field) 7. [Borrowed Insights](#7-borrowed-insights) 8. [References](#references) @@ -49,7 +49,7 @@ subject to $\hat{W}$ having entries drawn from a small codebook. The metric is t Frobenius norm. The quantity being preserved is the weight value itself, so that the quantised model behaves as close to the full-precision model as possible. -**Structural quantization** (the Q2 approach, described in §D-2.4) has a different +**Structural quantization** (the Q² approach, described in §D-2.4) has a different objective: preserve relational and topological structure — distances, trajectories, and complement relationships — rather than pointwise values. The metric is the Lee distance on $\mathbb{Z}_4$. The quantity being preserved is the geometry of the @@ -62,7 +62,7 @@ evaluated on retrieval fidelity, distance preservation, and the downstream quali of the transition key. The distinction matters because insights transfer only within objective class. Most -of the literature surveyed below optimises for reconstruction; Q2 optimises for +of the literature surveyed below optimises for reconstruction; Q² optimises for structure. Some insights nonetheless transfer; Section 7 identifies which ones. --- @@ -86,7 +86,7 @@ Both methods target 4-bit precision by default. Their 2-bit (quaternary) modes exhibit substantially larger accuracy degradation than 4-bit, a finding consistent across the literature. Section 5 quantifies this trade-off. -**Relevance to Q2.** GPTQ and AWQ are already noted in §D-2.4 as the canonical +**Relevance to Q².** GPTQ and AWQ are already noted in §D-2.4 as the canonical examples of reconstruction quantization. Their 2-bit results set the accuracy floor against which BQQ and similar newer methods are measured. @@ -112,21 +112,21 @@ state-of-the-art on ImageNet for 2-bit PTQ of ResNet-class models, and shows strong results on language tasks. It is consistently superior to GPTQ and AWQ at the 2-bit level. -**Relevance to Q2.** BQQ's core finding — that structure in the codebook -outperforms a uniform grid under the same bit budget — resonates with Q2's +**Relevance to Q².** BQQ's core finding — that structure in the codebook +outperforms a uniform grid under the same bit budget — resonates with Q²'s motivation: the $\mathbb{Z}_4$ alphabet is chosen not for reconstruction accuracy but for its algebraic properties (Lee metric, complement involution, Gray map). Both -BQQ and Q2 argue that the alphabet should be chosen to match the structure of the +BQQ and Q² argue that the alphabet should be chosen to match the structure of the problem, not merely to minimise $\|W - \hat{W}\|_F^2$. -The factored-binary view also provides an arithmetic observation relevant to Q2: -the four quaternary levels can be generated by two binary decisions. Q2's Gray +The factored-binary view also provides an arithmetic observation relevant to Q²: +the four quaternary levels can be generated by two binary decisions. Q²'s Gray encoding makes exactly this decomposition ($g = \text{sym} \oplus (\text{sym} \gg 1)$ produces two independent bits), and BQQ independently arrives at the same idea from a reconstruction perspective. **Key distinction.** BQQ's optimisation target is reconstruction fidelity. -Q2's is structural preservation. BQQ would not be an appropriate drop-in for the +Q²'s is structural preservation. BQQ would not be an appropriate drop-in for the transition-key use case: a BQQ-compressed weight matrix has no meaningful Lee distance between its quantised entries, and the complement involution is not preserved by the binary factorisation. @@ -149,13 +149,13 @@ combines quaternary (2-bit) weight quantization with parameter-efficient fine-tu - **Hardware-aware packing.** Symbols are packed four per byte (2 bits per weight) for efficient memory layout. -**Relevance to Q2.** QUAD's symmetric 4-level codebook -$\{-3, -1, +1, +3\} \cdot \Delta$ is not the same as Q2's equiprobable threshold +**Relevance to Q².** QUAD's symmetric 4-level codebook +$\{-3, -1, +1, +3\} \cdot \Delta$ is not the same as Q²'s equiprobable threshold $\tau^* = 0.6745 / \sqrt{n}$ scheme (§D-2.5). QUAD's levels are evenly spaced for -reconstruction; Q2's levels are equiprobable for information maximisation. For +reconstruction; Q²'s levels are equiprobable for information maximisation. For Gaussian activations, an even spacing misallocates levels: the outer levels $\pm 3\Delta$ will be used far less often than the inner levels $\pm\Delta$, wasting -one bit's worth of entropy. Q2's threshold maximises $I(v_i; q(v_i)) = \log_2 4 = 2$ bits +one bit's worth of entropy. Q²'s threshold maximises $I(v_i; q(v_i)) = \log_2 4 = 2$ bits per dimension by construction. QUAD also does not use the Lee metric or the Gray encoding. Its packed byte layout @@ -163,9 +163,9 @@ treats the four symbols as arbitrary indices, not as elements of $\mathbb{Z}_4$. Complement structure is absent. **Borrowed insight.** QUAD's joint optimisation (frozen quantized weights + -trainable adapters) is relevant to the fine-tuning case of Q2-indexed models: +trainable adapters) is relevant to the fine-tuning case of Q²-indexed models: if a downstream task requires domain adaptation, a LoRA-style adapter over a -Q2-indexed backbone would incur only adapter parameter cost without re-running +Q²-indexed backbone would incur only adapter parameter cost without re-running the full quantization pipeline. This is speculative but consistent with QUAD's findings that adapter-based recovery is efficient at 2-bit precision. @@ -183,15 +183,15 @@ higher precision or larger adapter capacity to those channels selectively. This is a form of **mixed-precision quantization** targeted by an oracle derived from task-specific activation statistics. -**Relevance to Q2.** QuES demonstrates that 2-bit precision is not uniformly harmful +**Relevance to Q².** QuES demonstrates that 2-bit precision is not uniformly harmful across a model: some components tolerate it well, others do not. This empirical -finding independently supports Q2's §D-4.3 argument for mixed-precision quantization -guided by structural criteria. Q2 uses the Geode factorization and polytope formula +finding independently supports Q²'s §D-4.3 argument for mixed-precision quantization +guided by structural criteria. Q² uses the Geode factorization and polytope formula as the structural oracle; QuES uses task-specific activation statistics. The two oracles are orthogonal but compatible. **Borrowed insight.** QuES's finding that the failure mode of low-precision -quantization is task-specific (not uniform) suggests that Q2's transition key could +quantization is task-specific (not uniform) suggests that Q²'s transition key could serve as a soft mixed-precision indicator: tokens whose quantization produces long runs (low transition density, §D-3.6) are likely in low-variance, well-behaved activation regimes, while tokens with short runs (high transition density) correspond @@ -214,10 +214,10 @@ achieves near-fp16 accuracy on standard benchmarks, while 2-bit methods (includi BQQ, the current state-of-the-art) show measurable but acceptable degradation on language tasks and more significant degradation on reasoning tasks (cf. QuES §2.4). -**Relevance to Q2.** Q2 does not compress model weights at all; it quantizes +**Relevance to Q².** Q² does not compress model weights at all; it quantizes **activations** (hidden-state vectors at inference time) into a transition key for retrieval. The NVFP4 vs. 2-bit comparison is therefore not directly applicable. The -relevant comparison for Q2's activation quantization is retrieval quality (recall at +relevant comparison for Q²'s activation quantization is retrieval quality (recall at k, distance preservation) rather than perplexity or task accuracy. --- @@ -236,20 +236,20 @@ the straight-through estimator to propagate gradients through the discrete const Reported results show near-full-precision accuracy on language benchmarks at 3B and 7B parameter scales, an impressive result for ternary precision. -**Comparison with Q2 quaternary.** BitNet demonstrates that ternary precision is +**Comparison with Q² quaternary.** BitNet demonstrates that ternary precision is achievable with minimal accuracy loss — if the model is trained with the constraint -from the start. §D-2.3 identifies the mathematical reason Q2 does not use the ternary +from the start. §D-2.3 identifies the mathematical reason Q² does not use the ternary alphabet: $\mathbb{Z}_3$ admits no fixed-point-free involution, so the complement structure required for the Lee metric and hairpin detection (§D-2.8, §D-3.1) is unavailable. BitNet's ternary weights can be trained efficiently precisely because the constraint -is baked into the forward pass. Q2 applies quaternary quantization to **activations** +is baked into the forward pass. Q² applies quaternary quantization to **activations** at inference time, not to weights. The two problems have different constraints: -BitNet relaxes weight precision while maintaining activation precision; Q2 maintains +BitNet relaxes weight precision while maintaining activation precision; Q² maintains weight precision while compressing activation geometry for indexing. -**The BitNet activation distribution.** A notable implication: if Q2 were applied on +**The BitNet activation distribution.** A notable implication: if Q² were applied on top of a BitNet model, the activation distribution might be non-Gaussian (because ternary weights combined with ReLU or SiLU activations produce a distinct distribution shape). The threshold $\tau^* = 0.6745 / \sqrt{n}$ assumes @@ -267,7 +267,7 @@ initialisation and learning-rate scheduling. Quaternary weight networks (4 level consistently outperform binary ones at the same memory budget because the additional expressive power reduces the required hidden-layer width. -**Relevance to Q2.** Q2's choice of 4 levels for activation quantization is +**Relevance to Q².** Q²'s choice of 4 levels for activation quantization is consistent with the empirical finding that the jump from binary to quaternary provides the largest marginal gain per additional bit. Going from 4 to 8 levels yields diminishing returns; going from 2 to 4 levels recovers the magnitude-class @@ -287,8 +287,8 @@ papers report successful deployment of ResNet and MobileNet variants on ARM Cortex-M microcontrollers using 2-bit quantized weights with custom SIMD packing (4 weights per byte). -**Relevance to Q2.** Q2's thermal constraint (§D-5.3) is exactly this scenario: the -LLM is already running on the device, consuming most of the thermal budget. The Q2 +**Relevance to Q².** Q²'s thermal constraint (§D-5.3) is exactly this scenario: the +LLM is already running on the device, consuming most of the thermal budget. The Q² transition key construction adds negligible compute on top of the already-running LLM (one pass of L2 normalisation, thresholding, and run-reduction over the last token's hidden state). The 2-bit packing of 32 transitions into a 64-bit integer @@ -296,7 +296,7 @@ token's hidden state). The 2-bit packing of 32 transitions into a 64-bit integer edge quantization literature. **Borrowed insight.** Edge quantization implementations use compile-time-known -packing constants to enable vectorised comparisons. The Q2 threshold +packing constants to enable vectorised comparisons. The Q² threshold $\tau^* \approx 0.6745 / \sqrt{n}$ can similarly be computed once at model-load time and broadcast as a vector constant, allowing the quantization step to run as a single vectorised comparison on ARM NEON or WebAssembly SIMD, with no @@ -315,14 +315,14 @@ analysis benchmarks (SST-2, IMDb). These studies found that: tasks, because the magnitude class (near/far from threshold) carries sequence length information relevant to gating decisions. 2. The transition between hidden states in a quaternary-weight RNN corresponds to - a 4-symbol trajectory in the weight-space lattice, analogous to Q2's + a 4-symbol trajectory in the weight-space lattice, analogous to Q²'s transition key. -**Relevance to Q2.** The RNN finding that trajectory information is valuable at -the quaternary level independently corroborates Q2's central hypothesis: the +**Relevance to Q².** The RNN finding that trajectory information is valuable at +the quaternary level independently corroborates Q²'s central hypothesis: the *sequence of quantization transitions* (the run-reduced key of §D-3.1) carries richer structural information than any single quantized value. The RNN literature -arrived at this conclusion from a weight-quantization angle; Q2 arrives at it from +arrived at this conclusion from a weight-quantization angle; Q² arrives at it from an activation-quantization angle. --- @@ -338,15 +338,15 @@ CNNs for real-time bearing fault diagnosis, reporting: This case is notable because bearing fault signals are periodic and low-dimensional (vibration sensor, 1D signal), quite different from the high-dimensional activation -spaces addressed by Q2. Yet the result illustrates that quaternary quantization can +spaces addressed by Q². Yet the result illustrates that quaternary quantization can achieve near-lossless compression for structured signals. -**Relevance to Q2.** The bearing fault case is an instance where the activation +**Relevance to Q².** The bearing fault case is an instance where the activation distribution is highly non-Gaussian (periodic signals produce bimodal or harmonic distributions). The study uses a fixed symmetric codebook rather than equiprobable -thresholds. This is the exact scenario where Q2's empirical threshold calibration +thresholds. This is the exact scenario where Q²'s empirical threshold calibration (§D-2.5: reservoir sample of 1024 activations per compaction cycle) adds value over -a fixed codebook: by tracking the empirical quartiles, Q2's thresholds adapt to +a fixed codebook: by tracking the empirical quartiles, Q²'s thresholds adapt to non-Gaussian distributions without requiring knowledge of the distribution shape. --- @@ -356,14 +356,14 @@ non-Gaussian distributions without requiring knowledge of the distribution shape BP4 extends neural belief propagation decoders for quantum Low-Density Parity-Check (QLDPC) codes from binary to quaternary alphabets. QLDPC error correction requires passing messages over GF(4) (the field with 4 elements), which has a different -algebraic structure from $\mathbb{Z}_4$ (the ring used in Q2). Specifically, GF(4) +algebraic structure from $\mathbb{Z}_4$ (the ring used in Q²). Specifically, GF(4) uses XOR-based multiplication; $\mathbb{Z}_4$ uses modular arithmetic. The message passing operates on syndrome vectors in GF(4), not on geometry-preserving lattice codes. -**Relevance to Q2.** BP4 and Q2 both use 4-symbol alphabets but are built on +**Relevance to Q².** BP4 and Q² both use 4-symbol alphabets but are built on different algebraic structures. BP4 requires GF(4) for its syndrome arithmetic; -Q2 requires $\mathbb{Z}_4$ for the Lee metric and complement involution. These +Q² requires $\mathbb{Z}_4$ for the Lee metric and complement involution. These are not interchangeable: the Hamming, Lee, and GF(4) metrics have different distance geometries, and the error-correction properties of Kerdock and Preparata codes (§P-9) do not apply to GF(4)-based QLDPC codes. @@ -382,14 +382,14 @@ embedding. The quantization step maps DCT coefficients to 4 levels, and the embedding modulates inter-coefficient phase relationships at each level. This achieves high payload capacity and resistance to CNN-based steganalyzers. -**Relevance to Q2.** The steganographic use case is superficially different but +**Relevance to Q².** The steganographic use case is superficially different but shares a deep structural property: OPMS-QQGE exploits the *relational geometry* of the quantized space (inter-coefficient phase differences) rather than the -absolute values of individual coefficients. This is precisely the distinction Q2 +absolute values of individual coefficients. This is precisely the distinction Q² makes in §D-2.4: structural quantization preserves relations, not values. OPMS-QQGE's finding that a 4-level representation provides sufficient degrees of -freedom for robust phase-relationship encoding parallels Q2's finding that 4 levels +freedom for robust phase-relationship encoding parallels Q²'s finding that 4 levels provide the minimum alphabet for the complement involution. Both arrive at 4 from a relational-geometry requirement rather than a reconstruction-accuracy requirement. @@ -428,8 +428,8 @@ The literature presents a consistent picture of the accuracy-efficiency frontier near-lossless 2-bit compression; open-ended language generation shows measurable degradation. The distribution shape and task difficulty interact. -**Where Q2 sits.** Q2 does not compress model weights; it quantizes activations -for indexing. The accuracy metric is retrieval quality, not perplexity. Q2 makes +**Where Q² sits.** Q² does not compress model weights; it quantizes activations +for indexing. The accuracy metric is retrieval quality, not perplexity. Q² makes no accuracy-efficiency trade-off on the model's generative performance — the LLM runs at full precision. The trade-off it makes is between index compactness (64-bit key vs. full float32 embedding) and retrieval fidelity (transition-key recall vs. @@ -438,12 +438,12 @@ trade-offs surveyed above. --- -## 6 Key Distinctions: Q2 vs. the Field +## 6 Key Distinctions: Q² vs. the Field -The following table summarises how Q2 differs from the main classes of related work +The following table summarises how Q² differs from the main classes of related work along the axes that matter most: -| Dimension | Reconstruction methods (BQQ/GPTQ/QUAD) | Q2 structural quantization | +| Dimension | Reconstruction methods (BQQ/GPTQ/QUAD) | Q² structural quantization | |-----------|----------------------------------------|-----------------------------| | **What is quantized** | Model weights | Inference-time activations | | **Objective** | Minimize reconstruction error | Preserve relational geometry | @@ -457,7 +457,7 @@ along the axes that matter most: | **Cross-model invariance** | Not targeted | Targeted (§D-5.4) | The single most important distinction is the **target of quantization**: the -reconstruction methods quantize weights to save memory at inference time; Q2 +reconstruction methods quantize weights to save memory at inference time; Q² quantizes activations to produce a compact retrieval index. They solve different problems with the same alphabet. @@ -465,31 +465,31 @@ problems with the same alphabet. ## 7 Borrowed Insights -The following findings from the literature have direct actionable implications for Q2: +The following findings from the literature have direct actionable implications for Q²: ### 7.1 Factored-binary codebook (from BQQ) BQQ's result that two binary decisions generate the four quaternary levels more -efficiently than a uniform grid confirms Q2's Gray encoding choice ($g = \text{sym} +efficiently than a uniform grid confirms Q²'s Gray encoding choice ($g = \text{sym} \oplus (\text{sym} \gg 1)$). The two bits of the Gray code are algebraically independent, which is exactly what BQQ's binary factorisation achieves. This -provides an independent theoretical justification for Q2's Gray map from a +provides an independent theoretical justification for Q²'s Gray map from a reconstruction-error perspective. ### 7.2 Equiprobable thresholds outperform equal-spacing (from QUAD contrast) -QUAD uses equal-spacing for its 4-level codebook. Q2's equiprobable threshold +QUAD uses equal-spacing for its 4-level codebook. Q²'s equiprobable threshold $\tau^*$ maximises entropy per dimension ($I = 2$ bits). The literature on information-theoretic quantization (Max-Lloyd algorithm) confirms that for Gaussian -sources, equiprobable thresholds minimise entropy-normalised distortion. Q2's design +sources, equiprobable thresholds minimise entropy-normalised distortion. Q²'s design is optimal by this criterion. QUAD's equal-spacing design is suboptimal for Gaussian -activations — an insight that supports Q2's threshold design rather than suggesting +activations — an insight that supports Q²'s threshold design rather than suggesting a change. ### 7.3 Mixed-precision oracle from activation statistics (from QuES) QuES uses task-specific activation statistics to identify high-importance channels -that need higher precision. Q2's transition density (§D-3.6) is an activation +that need higher precision. Q²'s transition density (§D-3.6) is an activation statistic: low-density windows correspond to low-variance, "settled" activations; high-density windows correspond to high-variance, structurally active regions. This suggests using transition density as a lightweight proxy for "quantization @@ -503,8 +503,8 @@ concrete mechanism borrowed from QuES's methodology. AWQ's activation-aware scale factor protects high-activation channels from quantization error by rescaling before quantization and inverse-rescaling after. -Q2's L2 normalisation step (§D-5.1) achieves a similar effect at the vector -level: by normalising to unit length before thresholding, Q2 removes the global +Q²'s L2 normalisation step (§D-5.1) achieves a similar effect at the vector +level: by normalising to unit length before thresholding, Q² removes the global scale, ensuring that the threshold $\tau^*$ is applied to a distribution with unit variance rather than an uncalibrated raw activation. Per-channel scale factors (AWQ-style) within the normalised vector are not currently applied; this could be @@ -514,7 +514,7 @@ normalisation. ### 7.5 Trajectory information in RNNs (from RNN quaternary literature) The RNN finding that sequence-of-transitions carries richer information than -individual quantized values (§4.2 above) independently confirms Q2's run-reduction +individual quantized values (§4.2 above) independently confirms Q²'s run-reduction hypothesis. Both approaches observe that the temporal or sequential pattern of transitions through the quantization grid — not the individual cell assignments — is the primary carrier of structural information. @@ -522,11 +522,11 @@ is the primary carrier of structural information. ### 7.6 Adapter-based recovery for downstream tasks (from QUAD) QUAD demonstrates that LoRA-style adapters efficiently recover task-specific -accuracy on top of frozen 2-bit quantized weights. For the Q2 use case, an analogous +accuracy on top of frozen 2-bit quantized weights. For the Q² use case, an analogous pattern exists: the transition key captures the base-model's activation geometry; domain adaptation for a downstream retrieval task could be achieved by training a -small adapter that modifies the last-hidden-state before Q2 quantization, rather -than retraining or recalibrating the full Q2 index. This is consistent with QUAD's +small adapter that modifies the last-hidden-state before Q² quantization, rather +than retraining or recalibrating the full Q² index. This is consistent with QUAD's finding that adapters are highly parameter-efficient at 2-bit precision. --- diff --git a/docs/design-revision-plan.md b/docs/design-revision-plan.md index edd86b8..c514dec 100644 --- a/docs/design-revision-plan.md +++ b/docs/design-revision-plan.md @@ -1,7 +1,7 @@ # DESIGN.md Revision Plan > Section-by-section assessment: what is removed, revised, new, or unchanged -> when Q2 generalizes beyond semantic embeddings and integrates Wildberger-Rubine. +> when Q² generalizes beyond semantic embeddings and integrates Wildberger-Rubine. --- @@ -191,7 +191,7 @@ quantization for retrieval." In a general framework, the distinction is between: - **Reconstruction quantization** (GPTQ, AWQ): minimize $\|W - \hat{W}\|_F^2$. The goal is to approximate the original signal. -- **Structural quantization** (Q2): preserve relational/topological structure. +- **Structural quantization** (Q²): preserve relational/topological structure. The goal is to preserve distances, not values. The section should frame this as two different quantization objectives, not as @@ -358,7 +358,7 @@ order maps to precision/cost tradeoff. #### §4.5 Reconstruction and series reversion -If Q2 ever needs a decode path (lossy compression, not just retrieval), the +If Q² ever needs a decode path (lossy compression, not just retrieval), the optimal reconstruction point $\mathbb{E}[x \mid q(x) = s]$ requires inverting the CDF within each cell. The Lagrange-inversion / hyper-Catalan series provides this without numerical root-finding. diff --git a/docs/wildberger-rubine-review.md b/docs/wildberger-rubine-review.md index d1047c4..90741ca 100644 --- a/docs/wildberger-rubine-review.md +++ b/docs/wildberger-rubine-review.md @@ -1,4 +1,4 @@ -# Review: Wildberger & Rubine in light of Q2 +# Review: Wildberger & Rubine in light of Q² > Paper: "A Hyper-Catalan Series Solution to Polynomial Equations, and the Geode" > N. J. Wildberger & Dean Rubine, *American Mathematical Monthly* 132:5 (2025), 383–402. @@ -7,9 +7,9 @@ ## Executive summary -The first pass assessed this paper narrowly against Q2's embedding retrieval +The first pass assessed this paper narrowly against Q²'s embedding retrieval pipeline and dismissed most of the machinery. That was wrong — it evaluated -against the *application* rather than the *framework*. With Q2 positioned as a +against the *application* rather than the *framework*. With Q² positioned as a general theory of quaternary quantization (not just semantic embeddings), the paper's contributions land differently. The polynomial-solving machinery, the Geode factorization, and the sub-multinomial counting all become relevant @@ -24,7 +24,7 @@ series) remain genuinely irrelevant. ## 1. The polynomial formula as threshold geometry (upgraded from "irrelevant") -**Previously dismissed** because Q2's embedding thresholds come from empirical +**Previously dismissed** because Q²'s embedding thresholds come from empirical percentiles. But that's one application. In general quantization, you face: > Given a distribution $F$ and a target number of equiprobable cells $q$, @@ -39,7 +39,7 @@ becomes a polynomial in the distribution parameters. The paper provides a $$\alpha = \sum_\mathbf{m} C_\mathbf{m} \cdot t_2^{m_2} t_3^{m_3} \cdots$$ -where $C_\mathbf{m}$ is the hyper-Catalan number. For Q2 generalized, this +where $C_\mathbf{m}$ is the hyper-Catalan number. For Q² generalized, this means: - **Optimal thresholds for mixture distributions** (e.g., a mixture of $k$ @@ -57,7 +57,7 @@ means: precision/cost tradeoff that a general quantization framework should expose. **Concrete consequence.** DESIGN §2.5 currently says thresholds are calibrated -from a reservoir sample using empirical percentiles. A general Q2 framework +from a reservoir sample using empirical percentiles. A general Q² framework should also offer: given a parametric model of the source distribution, compute thresholds analytically via the hyper-Catalan series, truncated to a specified order. @@ -66,7 +66,7 @@ order. ## 2. Exact counting of the quantization trie (retained, broadened) -**The connection.** Q2's run-reduced transition sequences form a trie where: +**The connection.** Q²'s run-reduced transition sequences form a trie where: - The root branches into $q$ children (first symbol). - Every subsequent node branches into $q-1$ children (next symbol $\neq$ @@ -84,7 +84,7 @@ a trie whose subtree counts are hyper-Catalan numbers with the appropriate type vector $\mathbf{m}$. This applies to: - **Error-correcting codes** over $\mathbb{Z}_4$ (the Gray map already connects - Q2 to the Nordstrom-Robinson and Kerdock codes via the Hammons et al. 1994 + Q² to the Nordstrom-Robinson and Kerdock codes via the Hammons et al. 1994 result cited in DESIGN §2.7). - **Run-length-limited codes** in storage/communication, where consecutive identical symbols are forbidden — literally the same constraint as @@ -93,7 +93,7 @@ vector $\mathbf{m}$. This applies to: the quantized system, and hyper-Catalan numbers count the admissible trajectories. -**What this gives Q2.** Exact formulas for: +**What this gives Q².** Exact formulas for: - Bucket density at each prefix depth (DESIGN §3.6) - Collision probability for constrained-alphabet codes @@ -109,7 +109,7 @@ The paper's main structural result: $$S - 1 = S_1 \cdot G$$ says every non-trivial structure factors through its outermost type. In -Q2-general, this becomes a statement about **hierarchical quantization**: +Q²-general, this becomes a statement about **hierarchical quantization**: - $S$ is the generating function for all quantized codewords. - $S_1 = t_2 + t_3 + t_4 + \ldots$ is the first quantization step (the @@ -119,9 +119,9 @@ Q2-general, this becomes a statement about **hierarchical quantization**: This is the algebraic skeleton of **progressive quantization**: first decide the coarse cell, then refine within it. The Geode $G$ counts the refinement -possibilities. For Q2's transition key: +possibilities. For Q²'s transition key: -| Level | Paper | Q2 (specific) | Q2 (general) | +| Level | Paper | Q² (specific) | Q² (general) | |:-----:|:------|:--------------|:-------------| | Full structure | $S$ | All transition sequences | All codewords | | First level | $S_1$ | $r_0$ (first symbol → block file) | Coarse quantization cell | @@ -133,7 +133,7 @@ level 2 factors the same way. This is the algebraic version of a multi-resolutio quantization scheme — coarse-to-fine, with the Geode counting the degrees of freedom at each level. -**Concrete consequence.** A general Q2 framework should support multi-resolution +**Concrete consequence.** A general Q² framework should support multi-resolution keys where the first $j$ symbols give a coarse retrieval and deeper symbols refine it. The Geode factorization tells you exactly how many distinct refinements exist at each level, which determines the information gain per @@ -163,14 +163,14 @@ and $V$ vertices in arbitrary combination. The constraint $V - E + F = 1$ (for a planar/simply-connected quantization region) or $V - E + F = 2$ (for a closed surface) limits the topology of admissible quantization schemes. -For Q2 specifically: +For Q² specifically: - The $\mathbb{Z}_4$ cycle has $V = 4$, $E = 4$, $F = 1$ (one "outer" face): $4 - 4 + 1 = 1$. ✓ - The product $\mathbb{Z}_4^n$ has a known face structure whose Euler characteristic is computable from the hyper-Catalan framework. -**Concrete consequence.** When extending Q2 to higher-order alphabets ($q = 8$, +**Concrete consequence.** When extending Q² to higher-order alphabets ($q = 8$, $q = 16$, etc.) or to non-cyclic topologies, Euler's formula provides an *a priori* constraint on what quantization lattice geometries are possible. You don't search — you enumerate the admissible $(V, E, F)$ triples and the @@ -181,12 +181,12 @@ topology supports. ## 5. Series reversion and quantization inversion (upgraded from "irrelevant") -**Previously dismissed** because Q2 retrieval doesn't need to invert. But +**Previously dismissed** because Q² retrieval doesn't need to invert. But general quantization does: **dequantization** (reconstructing an approximate continuous value from a discrete code) requires inverting the quantization map. The paper shows (§10) that Lagrange inversion and the hyper-Catalan series are -two faces of the same coin. For Q2 generalized: +two faces of the same coin. For Q² generalized: - The quantization map $q: \mathbb{R} \to \mathbb{Z}_4$ has a right inverse (the reconstruction map) $q^{-1}: \mathbb{Z}_4 \to \mathbb{R}$ that maps @@ -198,7 +198,7 @@ two faces of the same coin. For Q2 generalized: - The hyper-Catalan series gives this inversion combinatorially, without numerical root-finding. -**Concrete consequence.** If Q2 ever needs a decode path (e.g., for lossy +**Concrete consequence.** If Q² ever needs a decode path (e.g., for lossy compression applications, not just retrieval), the reconstruction formula is already provided by the paper's series reversion machinery. @@ -214,7 +214,7 @@ and $m_3$ ternary splits. In quantization terms: - A **binary split** is a 1-bit quantization step (above/below threshold). - A **ternary split** is a 1.58-bit step (below/near/above). -- A **quaternary split** is a 2-bit step (Q2's $\{A,B,C,D\}$). +- A **quaternary split** is a 2-bit step (Q²'s $\{A,B,C,D\}$). A general quantization framework might mix these: use 2-bit precision on high-variance dimensions and 1-bit on low-variance dimensions. The number of @@ -241,7 +241,7 @@ optimal bit allocation. - **The specific numerical examples** (cubic root of 2, etc.). These are demonstrations of the formula, not structural results. -That's it. Everything else has a plausible Q2-general interpretation. +That's it. Everything else has a plausible Q²-general interpretation. --- @@ -260,7 +260,7 @@ That's it. Everything else has a plausible Q2-general interpretation. ## Summary of reassessment -| Paper section | First pass | Revised (general Q2) | +| Paper section | First pass | Revised (general Q²) | |:--------------|:-----------|:---------------------| | Hyper-Catalan counting | Directly useful | **Directly useful** (unchanged, broadened) | | Geode factorization | Worth investigating | **Core structure** for hierarchical quantization | @@ -272,7 +272,7 @@ That's it. Everything else has a plausible Q2-general interpretation. The shift from "semantic quantization" to "quantization in general" turns the Wildberger-Rubine paper from a source of one useful idea and two nice analogies -into a near-complete algebraic companion to the Q2 framework. +into a near-complete algebraic companion to the Q² framework. --- diff --git a/scripts/lint-md.mjs b/scripts/lint-md.mjs index e884e63..3f172d8 100644 --- a/scripts/lint-md.mjs +++ b/scripts/lint-md.mjs @@ -6,18 +6,21 @@ * Checks performed: * 1. Emoji characters (U+1F000+) inside LaTeX $...$ or $$...$$ blocks — * KaTeX cannot render emoji inside \text{} or math mode. - * 2. Unicode MINUS SIGN (U+2212 −) inside LaTeX math blocks — use ASCII + * 2. Literal asterisk '*' (U+002A) inside display math $$...$$ blocks — + * Markdown's italic/bold parser consumes it before KaTeX renders, + * causing "Extra close brace or missing open brace" errors. Use \ast. + * 3. Unicode MINUS SIGN (U+2212 −) inside LaTeX math blocks — use ASCII * hyphen-minus (-) inside \text{...} and in Mermaid labels instead. - * 3. Rare Unicode subscript/modifier letters (U+1D00–U+1D9F, U+2080–U+20A0) + * 4. Rare Unicode subscript/modifier letters (U+1D00–U+1D9F, U+2080–U+20A0) * in Mermaid diagram source — these characters have limited renderer * support and silently corrupt Mermaid output. - * 4. Unicode MINUS SIGN (U+2212) anywhere in Mermaid blocks — diagram + * 5. Unicode MINUS SIGN (U+2212) anywhere in Mermaid blocks — diagram * labels should use ASCII hyphen-minus. - * 5. Unicode subscript/superscript digits (U+2070–U+209F), modifier + * 6. Unicode subscript/superscript digits (U+2070–U+209F), modifier * letters (U+1D00–U+1D9F), mathematical arrows (U+2190–U+21FF), and * mathematical operators (U+2200–U+22FF) inside fenced code blocks — * monospace fonts often lack these glyphs. - * 6. (Emoji in prose is intentionally allowed — only emoji inside LaTeX + * 7. (Emoji in prose is intentionally allowed — only emoji inside LaTeX * math or Mermaid blocks is flagged, as it breaks rendering.) * * Usage: @@ -115,6 +118,16 @@ function checkDisplayMath(content, filePath) { file: filePath, line: lineNo, message: `Emoji U+${cp.toString(16).toUpperCase()} ('${String.fromCodePoint(cp)}') inside LaTeX display math — KaTeX cannot render emoji; use \\text{word} instead`, }); + } else if (cp === 0x002A) { + // ASCII asterisk * inside display math — Markdown italic/bold parser + // consumes it before KaTeX sees it, leaving unmatched braces and + // producing "Extra close brace or missing open brace" errors. + // Use \ast instead (e.g. \tau^{\ast} not \tau^{*}). + const lineNo = lineOf(content, offset + 2 + j); + violations.push({ + file: filePath, line: lineNo, + message: `Literal '*' (U+002A) inside LaTeX display math — Markdown parses it as italic/bold before KaTeX renders it; use \\ast instead`, + }); } else if (cp === 0x2212) { // U+2212 MINUS SIGN inside math — check if it's inside \text{...} const before = block.slice(0, j);