Upload 8 files

__main__.py

@@ -51,6 +51,8 @@ def _config_from_args(args) -> HPCConfig:
         cfg.therm_passes = int(args.thermal)
     if args.thermal_tilt is not None:
         cfg.therm_lambda_tilt = float(args.thermal_tilt)
+    if args.pin_dc:
+        cfg.pin_dc = True
     if args.no_q4_fallback:
         cfg.enable_q4_fallback = False
     if args.keep_embd:
@@ -296,6 +298,12 @@ def main() -> None:
         help="zero-residual anneal: multiplier (>=1, 1=off) on dc/vw lambdas during thermal passes; "
         "~100-1e3 drives the coherent residual (row DC + vesica) toward zero, spending weighted SSE",
     )
+    parser.add_argument(
+        "--pin-dc",
+        action="store_true",
+        help="zero-DC pin (Q2_K free lunch): re-solve (d, m) on the exact dc=0 line "
+        "after assembly/thermal; strictly lowers SSE while driving row-DC residual to ~0",
+    )
     parser.add_argument(
         "--format",
         choices=("mixed", "mixed_q1", "custom", "q1_0", "q3_k", "q4_0", "q2_k"),

config.py

@@ -89,6 +89,13 @@ class HPCConfig:
     # residual (row DC + vesica pairs) toward the lattice floor, leaving an
     # (almost) spectrally white error.  1.0 = off.
     therm_lambda_tilt: float = 1.0
+    # Zero-DC pin (the "Q2_K free lunch"): after assembly (and any thermal
+    # refinement) re-solve (d, m) on the exact dc=0 constraint line — a joint
+    # least-squares translation whose closed form *lowers* SSE while driving
+    # each block's row-DC residual to ~0 (bounded only by fp16 storage of the
+    # newly fitted d/m).  Structurally available only in formats with an
+    # additive dof (Q2_K); a no-op elsewhere.
+    pin_dc: bool = False
 
     # ---- seed clamp -----------------------------------------------------
     clamp_kurtosis_off: float = 6.0

cuda_backend.py

@@ -26,7 +26,7 @@ except ImportError:  # pragma: no cover
 from .config import HPCConfig
 from .factored import MULTS_D, MULTS_M, N_CAND_D, N_CAND_M, TOTAL_CANDIDATES
 from .pipeline import QuantizedTensor, TensorStats, _phase3_select
-from .q2k import NS, QK_K, Q2KBlock
+from .q2k import NS, QK_K, Q2KBlock, pin_q2k_dc_residual
 from .seeds import seed_clamp_value
 from .spectral import fold_weights
 
@@ -1162,6 +1162,30 @@ def quantize_cuda(
                 X_np, W_np, final_d, final_m, final_ls, final_lm, final_codes, cfg, row_width, dev
             )
 
+        if cfg.pin_dc:
+            _check_stop()
+            t_pin = time.time()
+            _emit(
+                f"Phase 4.7: Zero-DC Pin ({gpu_name})",
+                0,
+                n_blocks,
+                "re-solving (d, m) on the exact dc=0 constraint line "
+                "(exact-JS zero-coherent-residual pin, SSE-nondecreasing)",
+                sigma=sigma,
+                temperature=temperature,
+            )
+            final_d, final_m = pin_q2k_dc_residual(
+                final_d.copy(), final_m.copy(), final_ls, final_lm, final_codes, X_np.astype(np.float64)
+            )
+            _emit(
+                f"Phase 4.7: Zero-DC Pin ({gpu_name})",
+                n_blocks,
+                n_blocks,
+                f"done in {time.time() - t_pin:.1f}s",
+                sigma=sigma,
+                temperature=temperature,
+            )
+
     scales = (final_ls & 0x0F) | ((final_lm & 0x0F) << np.uint8(4))
     qs = np.empty((n_blocks, QK_K // 4), dtype=np.uint8)
     for base in (0, 128):

gui.py

@@ -183,6 +183,7 @@ class HPCQuantizeGUI:
         self.sse_budget_var = tk.DoubleVar(value=0.0005)
         self.thermal_var = tk.IntVar(value=0)
         self.thermal_tilt_var = tk.DoubleVar(value=1.0)
+        self.pin_dc_var = tk.BooleanVar(value=False)
 
         self.cli_preview_var = tk.StringVar()
         self.status_var = tk.StringVar(value="Ready.")
@@ -477,10 +478,15 @@ class HPCQuantizeGUI:
         ).grid(row=2, column=1, sticky=tk.EW, padx=4, pady=2)
         ttk.Label(spec_f, text="Zero-Residual Tilt (1=off):").grid(row=2, column=2, sticky=tk.W, padx=4, pady=2)
         ttk.Entry(spec_f, textvariable=self.thermal_tilt_var, width=8).grid(row=2, column=3, sticky=tk.EW, padx=4, pady=2)
+        ttk.Checkbutton(
+            spec_f,
+            text="Pin DC residual to 0 (Q2_K free lunch)",
+            variable=self.pin_dc_var,
+        ).grid(row=3, column=0, columnspan=2, sticky=tk.W, padx=4, pady=1)
         ttk.Label(
             spec_f, text="(λ multiplier ≥1 during thermal anneal; ~1e2–1e3 ≈ zero-coherent-residual '0-error' anneal)",
             foreground="#93c5fd",
-        ).grid(row=3, column=0, columnspan=4, sticky=tk.W, padx=4, pady=(0, 2))
+        ).grid(row=4, column=0, columnspan=4, sticky=tk.W, padx=4, pady=(0, 2))
 
         # Right: GGUF Tensor Browser
         browser_frame = ttk.LabelFrame(right_pane, text="3. GGUF Tensor Inspector & Live Status", padding=8)
@@ -809,6 +815,7 @@ class HPCQuantizeGUI:
             sse_budget=float(self.sse_budget_var.get()),
             therm_passes=max(0, int(self.thermal_var.get())),
             therm_lambda_tilt=max(1.0, float(self.thermal_tilt_var.get())),
+            pin_dc=bool(self.pin_dc_var.get()),
             quant_format=self.quant_format_var.get(),
             custom_quant_map=self._custom_map_for_plan() or {},
             enable_q4_fallback=bool(self.q4_fallback_var.get()) and self.quant_format_var.get() not in ("q2_k", "q3_k"),
@@ -860,6 +867,8 @@ class HPCQuantizeGUI:
             cmd += ["--thermal", str(int(self.thermal_var.get()))]
         if self.thermal_tilt_var.get() > 1.0:
             cmd += ["--thermal-tilt", str(float(self.thermal_tilt_var.get()))]
+        if self.pin_dc_var.get():
+            cmd += ["--pin-dc"]
         cmd.append("--verbose")
         return " ".join(shlex.quote(part) for part in cmd)
 

pipeline.py

@@ -50,6 +50,7 @@ from .q2k import (
     make_block,
     pack_codes,
     pack_scales,
+    pin_q2k_dc_residual,
     unpack_codes,
     weighted_sse,
 )
@@ -1138,6 +1139,44 @@ class Q2KQuantizer:
                 temperature=temperature,
             )
 
+        if cfg.pin_dc and n_blocks > 0:
+            _check_stop()
+            t_pin = time.time()
+            _emit(
+                "Phase 4.7: Zero-DC Pin (Q2_K Free Lunch)",
+                0,
+                n_blocks,
+                "re-solving (d, m) on the exact dc=0 constraint line "
+                "(exact-JS zero-coherent-residual pin, SSE-nondecreasing)",
+                sigma=sigma,
+                temperature=temperature,
+            )
+            pin_d = np.empty(n_blocks, dtype=np.float64)
+            pin_m = np.empty(n_blocks, dtype=np.float64)
+            pin_ls = np.empty((n_blocks, NS), dtype=np.uint8)
+            pin_lm = np.empty((n_blocks, NS), dtype=np.uint8)
+            pin_codes = np.empty((n_blocks, QK_K), dtype=np.uint8)
+            for i, b in enumerate(blocks):
+                pin_d[i] = b.d_float
+                pin_m[i] = b.dmin_float
+                pin_ls[i], pin_lm[i] = b.unpack_scales()
+                pin_codes[i] = unpack_codes(b.qs)
+            pin_d, pin_m = pin_q2k_dc_residual(
+                pin_d, pin_m, pin_ls, pin_lm, pin_codes, X.astype(np.float64)
+            )
+            blocks = [
+                make_block(pin_d[i], pin_m[i], pin_ls[i], pin_lm[i], pin_codes[i])
+                for i in range(n_blocks)
+            ]
+            _emit(
+                "Phase 4.7: Zero-DC Pin (Q2_K Free Lunch)",
+                n_blocks,
+                n_blocks,
+                f"done in {time.time() - t_pin:.1f}s",
+                sigma=sigma,
+                temperature=temperature,
+            )
+
         if cfg.apply_dc_carry and (cfg.dc_lambda > 0.0 or cfg.dc_decay > 0.0):
             _check_stop()
             _emit(

q2k.py

@@ -235,3 +235,37 @@ def weighted_sse_batch(
     if w is None:
         return np.sum(e * e, axis=1)
     return np.sum(np.asarray(w, dtype=np.float64) * e * e, axis=1)
+
+
+def pin_q2k_dc_residual(d, m, ls, lm, codes, X):
+    """Zero-DC pin: re-solve (d, m) on the exact ``sum(e) == 0`` line.
+
+    With e_i = X_i - d*ls_g*c_i + m*lm_g, requiring Σe = 0 makes m a line
+    m(d) = (d·Σa - ΣX)/Σb  (a = ls·c, b = lm); subtracting the residual mean
+    along that line is a translation that can only *lower* SSE, so the
+    closed-form optimum d* = Σ(u·v)/Σ(v²) dominates the input state on both
+    counts and leaves dc ~ 0 (bounded below by the fp16 storage of the
+    ``d``/``m`` fields).  Blocks without a usable translation dof (Σb == 0
+    or Σv² == 0) keep their input parameters.
+    """
+    ls64 = np.asarray(ls, dtype=np.float64)
+    lm64 = np.asarray(lm, dtype=np.float64)
+    c64 = np.asarray(codes, dtype=np.float64)
+    a_el = np.repeat(ls64, 16, axis=1) * c64
+    b_el = np.repeat(lm64, 16, axis=1)
+    sx0 = np.sum(np.asarray(X, dtype=np.float64), axis=1)
+    sa = a_el.sum(axis=1)
+    sb = b_el.sum(axis=1)
+    sb_safe = np.where(sb > 0.0, sb, np.nan)
+    u = np.asarray(X, dtype=np.float64) - b_el * (sx0 / sb_safe)[:, None]
+    v = a_el - b_el * (sa / sb_safe)[:, None]
+    vv = np.sum(v * v, axis=1)
+    uv = np.sum(u * v, axis=1)
+    ok = np.isfinite(vv) & (vv > 0.0) & np.isfinite(uv) & (sb > 0.0)
+    d_new = np.where(ok, uv / np.where(ok, vv, 1.0), np.asarray(d, dtype=np.float64))
+    m_new = (d_new * sa - sx0) / np.where(ok, sb, 1.0)
+    m_new = np.where(ok, m_new, np.asarray(m, dtype=np.float64))
+    # match the fp16 fields the block will actually carry in the file
+    d_new = from_fp16_bits(to_fp16_bits(d_new.astype(np.float32))).astype(np.float64)
+    m_new = from_fp16_bits(to_fp16_bits(m_new.astype(np.float32))).astype(np.float64)
+    return d_new, m_new