Update README.md

README.md

@@ -4,26 +4,28 @@ license: mit
 
 # HPC-Quantize V2
 
-## Holographic Phase Contraction, Geometry-Preserving Weight Analogs, and Coupled Bilinear Factorization for Ultra-Low-Bit (`Q2_K`) LLM Quantization
+## Holographic Phase Contraction, Geometry-Preserving Weight Analogs, and Algebraic 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.
+**HPC-Quantize V2** is a standalone Python/NumPy ultra-low-bit quantization engine and GGUF re-quantizer (with a real-time telemetry desktop GUI in `gui.py`) built 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**.
+> **Core thesis:** At 2 bits per weight (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 and should not rely on brute-force grid scans. It is a **coupled bilinear factorization and global sequence-optimization problem** best solved by extracting discrete lattice coordinates from **geometry-preserving weight analogs**, projecting them onto the true weights via **closed-form orthogonalized sufficient statistics**, and optimizing cross-block state trajectories with a **6-state 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.
+HPC-Quantize V2 (`hpc_quantize_v2/` + `gui.py`) has **zero C or `ctypes` dependencies**, reads and writes stock `llama.cpp`-compatible `.gguf` models and `.gguf`/`.dat` importance matrices (`iMatrix`), scales across all CPU cores with **bit-for-bit determinism**, 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.
+   Constructs a portfolio of surrogate weight blocks $\tilde{x}$ that preserve exact sub-block first and second importance-weighted moments ($\mu_j, \sigma_j^2$), rank order, unit sub-block direction ($\cos\theta = 1$), 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.
+   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})$, rank-1 algebraic 1-D code refinement ($S_{vv} - S_{lv}^2/S_{l2}$), and a single-pass vectorized 36-seed candidate lattice evaluator (`81x` faster than per-seed loops).
+3. **Algebraic Coupled Phase-4 Block Assembly (`hpc_quantize_v2/pipeline.py`)**:
+   Replaces legacy brute-force $16\times 16$ sub-block scans, $9\times 9$ weight-level ULP loops, and 256-pass greedy code searches with closed-form sufficient-statistic projections (`1,200–1,475 blocks/sec` in Phase 4, achieving **+2.64% lower objective error** than brute-force Phase 4 in **1/9th the time**).
+4. **Bit-Identical Multi-Core Execution (`--workers 0`)**:
+   Distributes block-independent candidate and analog solves across all CPU cores via zero-copy `fork` shared memory while keeping cross-block Sieve, 36-state Viterbi, and row-aware DC carry strictly sequential — producing **100% bit-for-bit identical** GGUF output regardless of worker count.
+5. **Real-Time Telemetry GUI (`gui.py`) & Direct GGUF-to-GGUF Pipeline (`hpc_quantize_v2/gguf.py`)**:
+   Ingests `F32`, `F16`, `BF16`, `Q8_0`, `Q4_0`, and `Q2_K` source GGUFs plus `llama.cpp` iMatrix files, displays live intra-tensor stage/block progress, dual **Tensor ETA** and block-weighted **Whole-Model ETA**, live `RMSE`/`RMSE/σ`, Sieve temperature, and floor hits, and emits a stock `llama.cpp` `Q2_K` GGUF.
 
 ---
 
@@ -47,7 +49,7 @@ When factoring raw LLM weights directly into this bilinear form, three structura
 
 ## Mathematical Architecture of HPC-Quantize V2
 
-### 1. Geometry-Preserving Weight Analogs
+### 1. Geometry-Preserving Weight Analogs (`analog.py`)
 
 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:
 
@@ -101,7 +103,7 @@ Tempers extreme sub-block standard deviations $\sigma_j \mapsto \sigma_j^\gamma
 
 ---
 
-### 2. Coupled Orthogonal-Basis Bilinear `Q2_K` Factorization
+### 2. Coupled Orthogonal-Basis Bilinear `Q2_K` Factorization (`factored.py`)
 
 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$:
 
@@ -110,21 +112,39 @@ Given candidate discrete codes $q_{j,k} \in \{0,1,2,3\}$ (from raw starts and th
    $$
    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\}$.
+2. **Monotone Rank-1 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 rank-1 coordinate sweep maximizing $S_{lv}^2 / S_{l2}$ (since $\sum_j w_j(v_j - d^* L_j)^2 = S_{vv} - S_{lv}^2/S_{l2}$).
 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:
+   Once $(d, Ls_j)$ are chosen, the optimal offset for sub-block $j$ is shifted in closed form 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
+### 3. Batched Algebraic Phase-4 Assembly (`pipeline.py`)
+
+Instead of brute-force $16\times 16$ sub-block scans and $9\times 9$ weight-level ULP searches, Phase 4 refines both the Viterbi-selected state and the analog-factored state across all blocks in vectorized batches using three exact algebraic identities:
+
+1. **Closed-Form Coupled Sub-scale Projection**:
+   From sufficient statistics $(V_{qq,j}, C_{qx,j}, S_{wq,j}, S_{x,j}, S_{w,j})$, the unconstrained scale minimizer is $s_j^* = \max(0, C_{qx,j}/V_{qq,j})$. Evaluating the local integer neighborhood $Ls_j \in \operatorname{round}(s_j^*/d) + \{-3,\ldots,+3\}$ paired with its closed-form coupled offset $Lm_j \in \operatorname{round}(t_j^*(Ls_j)/m) + \{-1,0,+1\}$ replaces $16\times 16 = 256$ brute-force pairs with $21$ algebraic states.
+2. **Vesica + DC Augmented $2\times 2$ Cramér Solve & $O(1)$ Scalar Quadratic ULP Polish**:
+   With $A_i = Ls_{i\gg 4} q_i$ and $B_i = Lm_{i\gg 4}$, the full extended objective (weighted SSE + Vesica fold pairs + DC carry) is an exact quadratic form in $(d, m)$:
+   $$
+   J(d, m) = \text{const} + \tilde{S}_{aa} d^2 - 2\tilde{S}_{ab} d m + \tilde{S}_{bb} m^2 - 2\tilde{S}_{xa} d + 2\tilde{S}_{xb} m,
+   $$
+   where $(\tilde{S}_{aa}, \tilde{S}_{ab}, \tilde{S}_{bb}, \tilde{S}_{xa}, \tilde{S}_{xb})$ include the Vesica pair sums $(A_p + A_{p+128}, B_p + B_{p+128}, x_p + x_{p+128})$ and the row DC sum $(\sum_i A_i, \sum_i B_i, \sum_i x_i + \text{carry})$. The continuous optimum $(d^*, m^*)$ is solved by $2\times 2$ Cramér's rule and the $\mathbb{F}_{16}$ ULP neighborhood is polished in $O(1)$ scalar arithmetic without touching the 256 weights.
+3. **Closed-Form 1-D Quadratic Vesica/DC Code Projection**:
+   Each weight's optimal discrete step $\Delta q_k^*$ under the combined weighted SSE + Vesica + DC objective is computed directly from the 1-D quadratic minimizer:
+   $$
+   \Delta q_k^* = \operatorname{round}\!\left(\frac{d_{\text{sub},k}\left(w_k e_k + \frac{\lambda_{\text{vw}}}{N}(e_k + e_{k\oplus 128}) + \frac{\lambda_{\text{dc}}}{N} D\right)}{\left(w_k + \frac{\lambda_{\text{vw}} + \lambda_{\text{dc}}}{N}\right) d_{\text{sub},k}^2}\right).
+   $$
+
+---
+
+### 4. End-to-End HPC Pipeline
 
 ```text
 Source Weights + Optional iMatrix
@@ -133,7 +153,7 @@ 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)
+Vectorized Superblock WLS + Multi-Core Analog-Guided Factored Candidate Field
         │
         ▼
 6-State Sequential Sieve (Bounded Neighbor Parity Back-Action + Log-Slack)
@@ -142,10 +162,10 @@ Vectorized Superblock WLS + Factored Candidate Field (6×6 / 24×24 Lattice)
 36-State Viterbi Global Sequence Optimization (Free-Energy Bins + Manhattan Prior)
         │
         ▼
-Sub-block Sieve Assembly + ULP Polish + D6/Vesica Spectral Shaping + Rolling DC Carry
+Batched Algebraic Phase-4 Coupled Assembly + Quadratic ULP Polish + Closed-Form Code Projection
         │
         ▼
-Monotone Local-Safety Candidate & Analog-Factored Floors
+Row-Aware Sequential DC Residual Nudge & Monotone Local-Safety Floors
         │
         ▼
 Standard Q2_K GGUF Output
@@ -153,16 +173,16 @@ Standard Q2_K GGUF Output
 
 ---
 
-## Measured Improvements over the C Reference Solver
+## Measured Benchmarks
 
 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` |
+| **Gaussian** ($\mathcal{N}(0, 0.02^2)$) | **+8.85%** | +8.45% | +3.17% | `0 / 12` |
+| **Heavy-Tailed** ($\text{Student-}t_3$) | **+10.25%** | +8.30% | +5.04% | `0 / 12` |
+| **Offset-Sparse** (50% density + DC shift) | **+14.07%** | +14.83% | +4.16% | `0 / 12` |
+| **Sparse** (10% density) | **+35.40%** | +32.78% | +17.01% | `0 / 12` |
 | **Real `Raon.gguf` (`blk.0.ffn_down.weight` + `iMatrix`)** | **+15.96%** | — | — | `0 / 47` |
 
 Reproduce at any time with:
@@ -182,9 +202,9 @@ Only **Python 3.10+** and **NumPy** (`tkinter` is included with standard Python
 pip install numpy
 ```
 
-### 1. Desktop GUI (`gui.py`)
+### 1. Desktop GUI with Live Telemetry (`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:
+Launch the graphical interface to browse a source `.gguf`, attach an `.imatrix`/`.gguf` importance file, inspect eligible tensors, tune analog/HPC parameters, set CPU worker count, copy the equivalent CLI command, and monitor live quantization with dual progress bars (**Model Progress** and **Tensor Superblocks**) and dual ETAs (**Tensor ETA** and **Model ETA**):
 
 ```bash
 python3 gui.py
@@ -198,7 +218,7 @@ 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:**
+**Quantize a full GGUF model to a `Q2_K` GGUF with an iMatrix (using all CPU cores by default):**
 
 ```bash
 python3 -m hpc_quantize_v2 \
@@ -206,6 +226,7 @@ python3 -m hpc_quantize_v2 \
   --all-q2k \
   --imatrix-gguf imatrix.gguf \
   --output Raon-Q2K.gguf \
+  --workers 0 \
   --verbose
 ```
 
@@ -238,12 +259,11 @@ 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)
+# 1. Quantize an in-memory tensor (workers=0 auto-uses all CPU cores)
 cfg = HPCConfig(
     n_cand_d=6,
     n_cand_m=6,
@@ -251,10 +271,11 @@ cfg = HPCConfig(
     factor_coupled_q2k=True,
     factor_joint_subscales=True,
     use_spectral=True,
+    workers=0,
 )
 quantizer = Q2KQuantizer(cfg)
 
-weights = np.random.default_rng(0).normal(0, 0.02, size=(16, 256)).astype(np.float32)
+weights = np.random.default_rng(0).normal(0, 0.02, size=(64, 256)).astype(np.float32)
 result = quantizer.quantize(weights, row_width=256)
 print("RMSE:", result.stats.rmse)
 reconstructed = result.dequantize()
@@ -277,23 +298,22 @@ print(stats)
 
 ```text
 HPC-Quantize/
-├── gui.py                         # Standalone Tkinter/TTK GUI wrapper
+├── gui.py                         # Standalone Tkinter/TTK GUI with live telemetry dashboard
 └── hpc_quantize_v2/               # Pure-Python V2 package (zero C dependencies)
     ├── __init__.py                # Public API exports
-    ├── __main__.py                # CLI entry point (--gguf, --input, --demo, --bench)
+    ├── __main__.py                # CLI entry point (--gguf, --input, --demo, --bench, --workers)
     ├── 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
+    ├── q2k.py                     # Q2_K 84-byte block packing, unpacking & batched dequantization
     ├── analog.py                  # Geometry-preserving weight analogs (Iso-Moment, Vesica Gram, Subscale)
-    ├── factored.py                # Coupled orthogonal-basis bilinear Q2_K block & candidate solver
+    ├── factored.py                # Coupled orthogonal-basis bilinear Q2_K block & vectorized 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
+    ├── pipeline.py                # End-to-end Q2KQuantizer with multi-core Phase 2b & algebraic Phase 4
+    ├── gguf.py                    # GGUF reader, iMatrix loader & GGUF-to-GGUF streaming writer
     ├── 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
@@ -301,5 +321,3 @@ HPC-Quantize/
 ```bash
 python3 -m unittest discover -s hpc_quantize_v2/tests -v
 ```
-
----