Upload 8 files

__main__.py

@@ -49,6 +49,8 @@ def _config_from_args(args) -> HPCConfig:
         cfg.use_spectral = False
     if args.thermal is not None:
         cfg.therm_passes = int(args.thermal)
+    if args.thermal_tilt is not None:
+        cfg.therm_lambda_tilt = float(args.thermal_tilt)
     if args.no_q4_fallback:
         cfg.enable_q4_fallback = False
     if args.keep_embd:
@@ -286,6 +288,14 @@ def main() -> None:
         metavar="PASSES",
         help="thermal refinery heat-bath passes after Phase 4 (default 0 = off; seeded, bit-exact per seed)",
     )
+    parser.add_argument(
+        "--thermal-tilt",
+        type=float,
+        default=None,
+        metavar="TILT",
+        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(
         "--format",
         choices=("mixed", "mixed_q1", "custom", "q1_0", "q3_k", "q4_0", "q2_k"),

anneal.py

@@ -31,6 +31,19 @@ from .q2k import QK_K
 EPS_D = 1.0e-15
 
 
+def thermal_spectral_lams(cfg: HPCConfig, n: int) -> tuple[float, float]:
+    """Per-code-normalized ``(lam_vw, lam_dc)`` with the zero-residual tilt applied.
+
+    ``therm_lambda_tilt`` scales both spectral lambdas during annealing so the
+    exact Gibbs chain trades weighted SSE for coherent-residual (DC/vesica)
+    drain; ``1.0`` (default) is the shipping objective.
+    """
+    if not cfg.use_spectral:
+        return 0.0, 0.0
+    tilt = max(1.0, float(cfg.therm_lambda_tilt))
+    return (float(cfg.vw_lambda) / n) * tilt, (float(cfg.dc_lambda) / n) * tilt
+
+
 def pair_energy(
     e: np.ndarray,
     w: np.ndarray | None,
@@ -188,8 +201,7 @@ def thermal_refine_codes(
     """
     n_blocks = X.shape[0]
     n_passes = cfg.therm_passes if passes is None else int(passes)
-    lam_vw = (float(cfg.vw_lambda) / QK_K) if cfg.use_spectral else 0.0
-    lam_dc = (float(cfg.dc_lambda) / QK_K) if cfg.use_spectral else 0.0
+    lam_vw, lam_dc = thermal_spectral_lams(cfg, QK_K)
     if n_blocks == 0 or n_passes == 0 or (lam_vw == 0.0 and lam_dc == 0.0):
         return d, m, ls, lm, codes, 0
     if cfg.fold_depth > 1:
@@ -472,8 +484,7 @@ def thermal_refine_q4_0(
     a no-op when the refinery or spectrals are disabled.
     """
     n_blocks, n = X.shape
-    lam_vw = (float(cfg.vw_lambda) / n) if cfg.use_spectral else 0.0
-    lam_dc = (float(cfg.dc_lambda) / n) if cfg.use_spectral else 0.0
+    lam_vw, lam_dc = thermal_spectral_lams(cfg, n)
     if n_blocks == 0 or cfg.therm_passes == 0 or (lam_vw == 0.0 and lam_dc == 0.0):
         return q.copy(), 0
     d64 = np.asarray(d, dtype=np.float64)
@@ -505,8 +516,7 @@ def thermal_refine_q1_0(
     uint8 bits and the number of strictly improved blocks.
     """
     n_blocks, n = X.shape
-    lam_vw = (float(cfg.vw_lambda) / n) if cfg.use_spectral else 0.0
-    lam_dc = (float(cfg.dc_lambda) / n) if cfg.use_spectral else 0.0
+    lam_vw, lam_dc = thermal_spectral_lams(cfg, n)
     if n_blocks == 0 or cfg.therm_passes == 0 or (lam_vw == 0.0 and lam_dc == 0.0):
         return bits.copy(), 0
     d64 = np.asarray(d, dtype=np.float64)
@@ -539,8 +549,7 @@ def thermal_refine_q3_k(
     polish outputs) are handled exactly via signed steps.
     """
     n_blocks, n = X.shape
-    lam_vw = (float(cfg.vw_lambda) / n) if cfg.use_spectral else 0.0
-    lam_dc = (float(cfg.dc_lambda) / n) if cfg.use_spectral else 0.0
+    lam_vw, lam_dc = thermal_spectral_lams(cfg, n)
     if n_blocks == 0 or cfg.therm_passes == 0 or (lam_vw == 0.0 and lam_dc == 0.0):
         return np.asarray(codes).copy(), 0
     scale64 = np.asarray(scale, dtype=np.float64)

config.py

@@ -83,6 +83,12 @@ class HPCConfig:
     therm_t0: float = 0.25
     therm_t_decay: float = 0.35
     therm_seed: int = 271828
+    # Zero-residual anneal: multiplier >= 1 applied to the spectral lambdas
+    # (dc_lambda, vw_lambda) while annealing.  At large tilts (~1e2-1e3) the
+    # exact-conditional Gibbs chain spends weighted SSE to drain the *coherent*
+    # residual (row DC + vesica pairs) toward the lattice floor, leaving an
+    # (almost) spectrally white error.  1.0 = off.
+    therm_lambda_tilt: float = 1.0
 
     # ---- seed clamp -----------------------------------------------------
     clamp_kurtosis_off: float = 6.0
@@ -137,6 +143,8 @@ class HPCConfig:
             raise ValueError("therm_t0 must be positive")
         if not 0.0 < self.therm_t_decay < 1.0:
             raise ValueError("therm_t_decay must lie in (0, 1)")
+        if self.therm_lambda_tilt < 1.0:
+            raise ValueError("therm_lambda_tilt must be >= 1.0 (1.0 = off)")
         if self.device not in ("auto", "cuda", "cpu") and not self.device.startswith("cuda:"):
             raise ValueError("device must be 'auto', 'cuda', 'cuda:N', or 'cpu'")
         if self.quant_format not in ("mixed", "mixed_q1", "custom", "q1_0", "q3_k", "q4_0", "q2_k"):

gui.py

@@ -182,6 +182,7 @@ class HPCQuantizeGUI:
         self.dc_decay_var = tk.DoubleVar(value=0.85)
         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.cli_preview_var = tk.StringVar()
         self.status_var = tk.StringVar(value="Ready.")
@@ -474,6 +475,12 @@ class HPCQuantizeGUI:
         ttk.Spinbox(
             spec_f, from_=0, to=16, increment=1, textvariable=self.thermal_var, width=8
         ).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.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))
 
         # Right: GGUF Tensor Browser
         browser_frame = ttk.LabelFrame(right_pane, text="3. GGUF Tensor Inspector & Live Status", padding=8)
@@ -801,6 +808,7 @@ class HPCQuantizeGUI:
             dc_decay=float(self.dc_decay_var.get()),
             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())),
             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"),
@@ -850,6 +858,8 @@ class HPCQuantizeGUI:
             cmd.append("--promote-attn-q4")
         if self.thermal_var.get() > 0:
             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()))]
         cmd.append("--verbose")
         return " ".join(shlex.quote(part) for part in cmd)