Update README.md

README.md

@@ -1,4 +1,305 @@
 ---
-license: apache-2.0
+license: mit
 ---
-Staging..
+
+# HPC-Quantize V2
+
+## Holographic Phase Contraction, Geometry-Preserving Weight Analogs, and Coupled Bilinear Factorization for Ultra-Low-Bit (`Q2_K`) LLM Quantization
+
+**HPC-Quantize V2** is a pure-Python/NumPy ultra-low-bit quantization engine and GGUF re-quantizer (with an integrated desktop GUI in `gui.py`) designed for **2-bit class (`Q2_K`, 2.625 bpw)** compression of large language models.
+
+> **Core thesis:** At 2 bits per weight (only 4 levels $q \in \{0,1,2,3\}$ and 4-bit sub-block scales $Ls, Lm \in \{0..15\}$), quantization is not an independent rounding problem. It is a **coupled bilinear factorization and global sequence-selection problem** best solved by extracting discrete lattice coordinates from **geometry-preserving weight analogs**, projecting them onto the true weights in an orthogonalized affine basis, and optimizing cross-block state trajectories via a **sequential Sieve and 36-state Viterbi dynamic program**.
+
+HPC-Quantize V2 (`hpc_quantize_v2/` + `gui.py`) has **zero C or `ctypes` dependencies**, reads and writes standard `llama.cpp`-compatible `.gguf` models and `.gguf`/`.dat` importance matrices (`iMatrix`), and requires no custom inference kernels.
+
+---
+
+## Key Highlights in V2
+
+1. **Geometry-Preserving Weight Analogs (`hpc_quantize_v2/analog.py`)**:
+   Constructs a manifold of surrogate weight blocks $\tilde{x}$ that preserve exact sub-block first and second importance-weighted moments ($\mu_j, \sigma_j^2$), rank order, total block energy, and the $2\times 2$ D6/Vesica fold Gram matrix while regularizing heavy-tailed outliers toward the 4-level `Q2_K` lattice.
+2. **Coupled Orthogonal-Basis Bilinear `Q2_K` Factorization (`hpc_quantize_v2/factored.py`)**:
+   Replaces independent 1-D scale/offset heuristics with an orthogonalized sub-block decomposition $\hat{x}_{j,k} = s_j(q_{j,k} - \bar{q}_j) + (s_j\bar{q}_j - t_j)$, coupled offset compensation $t_j^{\text{coupled}} = \max(0, (d \cdot Ls_j \cdot S_{wq,j} - S_{x,j})/S_{w,j})$, an exact superblock $2\times 2$ bilinear $(d, d_{\min})$ solve, and a vectorized $16\times 16$ joint $(Ls_j, Lm_j)$ sub-block scan.
+3. **Full HPC Machinery in Vectorized NumPy**:
+   Preserves kurtosis-gated outlier clamping, batched GGML seeds, the 6-state sequential Sieve with bounded parity back-action, the 36-state Viterbi sequence optimizer, D6/Vesica + DC fold-pyramid error shaping, row-aware rolling DC residual carry, and monotone local-safety floors.
+4. **Direct GGUF-to-GGUF + iMatrix Pipeline & GUI (`hpc_quantize_v2/gguf.py`, `gui.py`)**:
+   Ingests `F32`, `F16`, `BF16`, `Q8_0`, `Q4_0`, and `Q2_K` source GGUFs plus `llama.cpp` iMatrix files, copies metadata/tokenizer KVs and non-quantized tensors byte-for-byte, and emits a stock `llama.cpp`-compatible `Q2_K` GGUF.
+
+---
+
+## Why Standard `Q2_K` Quantization Breaks Down
+
+A `Q2_K` superblock encodes 256 weights in 84 bytes (16 sub-blocks of 16 weights each):
+
+$$
+\hat{x}_{16j + k} = d \cdot Ls_j \cdot q_{16j + k} - d_{\min} \cdot Lm_j,
+\qquad
+q \in \{0,1,2,3\}, \quad Ls_j, Lm_j \in \{0,\ldots,15\}, \quad d, d_{\min} \in \mathbb{F}_{16}.
+$$
+
+When factoring raw LLM weights directly into this bilinear form, three structural failure modes occur:
+
+1. **Intra-sub-block outlier collapse**: A single outlier weight in a 16-weight sub-block stretches the span $x_{\max} - x_{\min}$, forcing 13–15 of the 16 weights into a single bin ($q=1$ or $q=2$) and reducing effective precision below 1 bit.
+2. **Inter-sub-block scale crushing**: A single high-dispersion sub-block inflates the shared superblock scale $d$, forcing $Ls_j \in \{1, 2\}$ across the remaining 15 sub-blocks.
+3. **Scale-offset cross-term neglect**: Because $q_{j,k} \in \{0,1,2,3\}$ is non-negative, its importance-weighted mean $\bar{q}_j = \frac{\sum_k w_{j,k} q_{j,k}}{\sum_k w_{j,k}}$ is strictly positive. Rounding the scale $s_j \to d \cdot Ls_j$ shifts the sub-block mean by $(d \cdot Ls_j - s_j)\bar{q}_j$. Factoring $s_j \approx d \cdot Ls_j$ and $t_j \approx d_{\min} \cdot Lm_j$ independently leaves this mean shift uncompensated.
+
+---
+
+## Mathematical Architecture of HPC-Quantize V2
+
+### 1. Geometry-Preserving Weight Analogs
+
+To prevent outliers from collapsing the discrete code assignment $q \in \{0,1,2,3\}$ while respecting the true linear-layer geometry, V2 constructs a portfolio of **geometry-preserving analogs** $\tilde{x}$ of each eligible weight block before extracting candidate lattice coordinates:
+
+#### A. Sub-block Iso-Moment Quantile-Companded Analog (`subblock_isomoment_analog`)
+For each 16-weight sub-block $j$ with importance weights $w_{j,k}$:
+
+$$
+\mu_j = \frac{\sum_k w_{j,k} x_{j,k}}{\sum_k w_{j,k}},
+\qquad
+\sigma_j^2 = \frac{\sum_k w_{j,k}(x_{j,k} - \mu_j)^2}{\sum_k w_{j,k}},
+\qquad
+z_{j,k} = \frac{x_{j,k} - \mu_j}{\sigma_j}.
+$$
+
+Standardized coordinates are mapped through an importance-weighted hyperbolic transport blended with ideal 4-level quantiles $q^{\text{ideal}}_r \in [-1.35, +1.35]$:
+
+$$
+\tilde{z}_{j,k} = (1 - \alpha)\,\tau \tanh\!\left(\frac{(w_{j,k}/\bar{w}_j)^\beta z_{j,k}}{\tau}\right) + \alpha\, q^{\text{ideal}}_{\text{rank}(z_{j,k})},
+$$
+
+and then **orthogonally projected back onto the exact sub-block sphere**:
+
+$$
+\tilde{x}_{j,k} = \mu_j + \sigma_j \frac{\tilde{z}_{j,k} - \bar{z}_j}{\sqrt{\frac{1}{W_j}\sum_k w_{j,k}(\tilde{z}_{j,k} - \bar{z}_j)^2}}.
+$$
+
+This preserves the exact sub-block weighted mean $\mu_j$, weighted variance $\sigma_j^2$, and rank ordering while equalizing spacing across the 4 quantization levels.
+
+#### B. D6 / Vesica Gram-Preserving Fold Analog (`vesica_gram_analog`)
+Decomposes the 256-weight superblock into symmetric (vesica) and antisymmetric (wave) fold modes:
+
+$$
+v_p = \frac{1}{2}(x_p + x_{p+128}),
+\qquad
+u_p = \frac{1}{2}(x_p - x_{p+128}),
+\qquad p \in \{0,\ldots,127\}.
+$$
+
+Let $G \in \mathbb{R}^{2\times 2}$ be the importance-weighted covariance (Gram) matrix of $(v, u)$. V2 whitens $(v, u)$ via $G^{-1/2}$, applies smooth hyperbolic saturation along the principal axes, re-orthogonalizes, and colors back via $G^{1/2}$ so that:
+
+$$
+\operatorname{Gram}_w(\tilde{v}, \tilde{u}) = \operatorname{Gram}_w(v, u),
+\qquad
+\mathbb{E}_w[\tilde{v}] = \mathbb{E}_w[v],
+\qquad
+\mathbb{E}_w[\tilde{u}] = \mathbb{E}_w[u].
+$$
+
+#### C. Cross-Sub-block Scale-Lattice Analog (`subscale_lattice_analog`)
+Tempers extreme sub-block standard deviations $\sigma_j \mapsto \sigma_j^\gamma \sigma_{\text{block}}^{1-\gamma}$ so all 16 sub-blocks fit cleanly into the shared 4-bit $\{0..15\}$ scale lattice while preserving every sub-block's unit direction $\hat{u}_j$ ($\cos\theta = 1$), mean $\mu_j$, and total superblock weighted energy.
+
+---
+
+### 2. Coupled Orthogonal-Basis Bilinear `Q2_K` Factorization
+
+Given candidate discrete codes $q_{j,k} \in \{0,1,2,3\}$ (from raw starts and the analog portfolio), V2 projects the continuous and 4-bit scale parameters directly onto the **true weights** $x$:
+
+1. **Orthogonalized Sub-block Basis**:
+   Rewriting $\hat{x}_{j,k} = s_j(q_{j,k} - \bar{q}_j) + (s_j\bar{q}_j - t_j)$ diagonalizes the $2\times 2$ sub-block normal equations. The true sensitivity of sub-block $j$ to scale error $(s_j - d \cdot Ls_j)^2$ is the centered variance weight:
+   $$
+   V_{qq,j} = \sum_{k=0}^{15} w_{j,k}(q_{j,k} - \bar{q}_j)^2 = S_{qq,j} - S_{wq,j}\bar{q}_j.
+   $$
+2. **Monotone 1-D Factorization (`factor_1d`)**:
+   Factors $s_j \approx d \cdot Ls_j$ under weights $V_{qq,j}$ using multi-start Lloyd iterations followed by an exact vectorized coordinate sweep over integer codes $\{0..15\}$.
+3. **Coupled Offset Target**:
+   Once $(d, Ls_j)$ are chosen, the optimal offset for sub-block $j$ is shifted to absorb the scale rounding residual:
+   $$
+   t_j^{\text{coupled}} = \max\!\left(0,\; \frac{d \cdot Ls_j \cdot S_{wq,j} - S_{x,j}}{S_{w,j}}\right)
+   = \max\!\left(0,\; t_j + \bar{q}_j(d \cdot Ls_j - s_j)\right),
+   $$
+   which is then factored into $d_{\min} \cdot Lm_j$ under weights $S_{w,j}$.
+4. **Global $2\times 2$ Bilinear $(d, d_{\min})$ Solve & Joint $16\times 16$ Sub-scale Scan**:
+   Solves the exact $2\times 2$ linear system for $(d, d_{\min})$ across all 256 weights (augmented by the rank-1 DC spectral penalty), rounds to $\mathbb{F}_{16}$, and performs a vectorized $16\times 16$ joint $(Ls_j, Lm_j)$ minimization per sub-block, followed by $\mathbb{F}_{16}$ ULP neighborhood polishing and D6/Vesica Hadamard code descent.
+
+---
+
+### 3. Global HPC Pipeline
+
+```text
+Source Weights + Optional iMatrix
+        │
+        ▼
+Kurtosis-Gated Clamp & Batched GGML Seeds (make_qkx2_batch / make_qp_batch)
+        │
+        ▼
+Vectorized Superblock WLS + Factored Candidate Field (6×6 / 24×24 Lattice)
+        │
+        ▼
+6-State Sequential Sieve (Bounded Neighbor Parity Back-Action + Log-Slack)
+        │
+        ▼
+36-State Viterbi Global Sequence Optimization (Free-Energy Bins + Manhattan Prior)
+        │
+        ▼
+Sub-block Sieve Assembly + ULP Polish + D6/Vesica Spectral Shaping + Rolling DC Carry
+        │
+        ▼
+Monotone Local-Safety Candidate & Analog-Factored Floors
+        │
+        ▼
+Standard Q2_K GGUF Output
+```
+
+---
+
+## Measured Improvements over the C Reference Solver
+
+Evaluated across 48 synthetic blocks (4 distributions) and a full row (47 superblocks = 12,032 weights) of `blk.0.ffn_down.weight` from `Raon.gguf` weighted by `imatrix.gguf`:
+
+| Benchmark Suite | Mean Objective Reduction | Median Reduction | Min Reduction | Worse Cases |
+| :--- | :---: | :---: | :---: | :---: |
+| **Gaussian** ($\mathcal{N}(0, 0.02^2)$) | **+8.89%** | +8.23% | +3.15% | `0 / 12` |
+| **Heavy-Tailed** ($\text{Student-}t_3$) | **+10.47%** | +9.26% | +4.97% | `0 / 12` |
+| **Offset-Sparse** (50% density + DC shift) | **+14.46%** | +14.83% | +3.67% | `0 / 12` |
+| **Sparse** (10% density) | **+36.05%** | +34.05% | +16.91% | `0 / 12` |
+| **Real `Raon.gguf` (`blk.0.ffn_down.weight` + `iMatrix`)** | **+15.96%** | — | — | `0 / 47` |
+
+Reproduce at any time with:
+
+```bash
+python3 -m hpc_quantize_v2 --bench --bench-per-kind 12
+```
+
+---
+
+## Quickstart
+
+### Requirements
+Only **Python 3.10+** and **NumPy** (`tkinter` is included with standard Python installations for the GUI). No C compiler or shared libraries are needed.
+
+```bash
+pip install numpy
+```
+
+### 1. Desktop GUI (`gui.py`)
+
+Launch the graphical interface to browse a source `.gguf`, attach an `.imatrix`/`.gguf` importance file, inspect eligible tensors, tune analog/HPC parameters, copy the equivalent CLI command, or run quantization with a live progress bar:
+
+```bash
+python3 gui.py
+```
+
+Or pre-populate paths on launch:
+
+```bash
+python3 gui.py --gguf Raon.gguf --imatrix imatrix.gguf --output Raon-Q2K.gguf
+```
+
+### 2. Command-Line Interface (`hpc_quantize_v2`)
+
+**Quantize a full GGUF model to a `Q2_K` GGUF with an iMatrix:**
+
+```bash
+python3 -m hpc_quantize_v2 \
+  --gguf Raon.gguf \
+  --all-q2k \
+  --imatrix-gguf imatrix.gguf \
+  --output Raon-Q2K.gguf \
+  --verbose
+```
+
+**Inspect tensors in a GGUF file:**
+
+```bash
+python3 -m hpc_quantize_v2 --gguf Raon.gguf --list-tensors
+```
+
+**Smoke-test a single tensor into a valid GGUF (copies remaining tensors verbatim):**
+
+```bash
+python3 -m hpc_quantize_v2 \
+  --gguf Raon.gguf \
+  --tensor blk.0.ssm_beta.weight \
+  --imatrix-gguf imatrix.gguf \
+  --output Raon-smoke.gguf
+```
+
+**Quantize a NumPy `.npy` weight array to `.npz`:**
+
+```bash
+python3 -m hpc_quantize_v2 --input weights.npy --output weights_q2k.npz --verbose
+```
+
+### 3. Python API
+
+```python
+import numpy as np
+from hpc_quantize_v2 import (
+    HPCConfig,
+    Q2KQuantizer,
+    factor_only_solve,
+    read_imatrix,
+)
+from hpc_quantize_v2.gguf import write_quantized_gguf
+
+# 1. Quantize an in-memory tensor (shape must be a multiple of 256)
+cfg = HPCConfig(
+    n_cand_d=6,
+    n_cand_m=6,
+    use_weight_analogs=True,
+    factor_coupled_q2k=True,
+    factor_joint_subscales=True,
+    use_spectral=True,
+)
+quantizer = Q2KQuantizer(cfg)
+
+weights = np.random.default_rng(0).normal(0, 0.02, size=(16, 256)).astype(np.float32)
+result = quantizer.quantize(weights, row_width=256)
+print("RMSE:", result.stats.rmse)
+reconstructed = result.dequantize()
+
+# 2. Convert a source GGUF + iMatrix into a quantized Q2_K GGUF
+imat = read_imatrix("imatrix.gguf")
+stats = write_quantized_gguf(
+    "Raon.gguf",
+    "Raon-Q2K.gguf",
+    quantizer,
+    imat=imat,
+    quantize_all=True,
+)
+print(stats)
+```
+
+---
+
+## Package Structure
+
+```text
+HPC-Quantize/
+├── gui.py                         # Standalone Tkinter/TTK GUI wrapper
+└── hpc_quantize_v2/               # Pure-Python V2 package (zero C dependencies)
+    ├── __init__.py                # Public API exports
+    ├── __main__.py                # CLI entry point (--gguf, --input, --demo, --bench)
+    ├── config.py                  # Validated HPCConfig dataclass
+    ├── fp16.py                    # Bit-exact GGML nearest_int & IEEE fp16 ULP primitives
+    ├── q2k.py                     # Q2_K 84-byte block packing, unpacking & dequantization
+    ├── analog.py                  # Geometry-preserving weight analogs (Iso-Moment, Vesica Gram, Subscale)
+    ├── factored.py                # Coupled orthogonal-basis bilinear Q2_K block & candidate solver
+    ├── seeds.py                   # Kurtosis-gated outlier clamping & batched GGML seed solvers
+    ├── spectral.py                # Folded error pyramid, DC/Vesica penalty & Hadamard code descent
+    ├── sieve.py                   # 6-state sequential Sieve with neighbor parity back-action
+    ├── viterbi.py                 # Vectorized 36-state Viterbi sequence optimizer
+    ├── pipeline.py                # End-to-end Q2KQuantizer tensor pipeline
+    ├── reference.py               # Faithful C-reference solver port for A/B benchmarking
+    └── tests/
+        └── test_v2.py             # 19 unit tests covering primitives, analogs, solver, GGUF & pipeline
+```
+
+## Running the Test Suite
+
+```bash
+python3 -m unittest discover -s hpc_quantize_v2/tests -v
+```
+
+---