Upload gui.py

gui.py

@@ -0,0 +1,740 @@
+#!/usr/bin/env python3
+"""Graphical User Interface for HPC-Quantize V2 (Factored Q2_K Engine).
+
+Launch::
+
+    python3 gui.py
+
+Provides:
+* Source GGUF, iMatrix (.gguf / .dat), and Output (.gguf / .npz) file pickers
+* Interactive GGUF tensor table with Q2_K eligibility & iMatrix match status
+* Full HPCConfig controls (Geometry-Preserving Analogs, Coupled Bilinear Q2_K,
+  Sieve + 36-state Viterbi, Spectral/Vesica/DC shaping, Candidate lattice size)
+* Live CLI command preview with one-click copy
+* Threaded execution with per-tensor progress bar, live log, and cancellation
+"""
+
+from __future__ import annotations
+
+import argparse
+import queue
+import shlex
+import threading
+import time
+import tkinter as tk
+from pathlib import Path
+from tkinter import filedialog, messagebox, ttk
+
+import numpy as np
+
+from hpc_quantize_v2 import (
+    GGUFReader,
+    HPCConfig,
+    Q2KQuantizer,
+    expand_importance,
+    factor_only_solve,
+    lookup_imatrix,
+    read_imatrix,
+)
+from hpc_quantize_v2.gguf import is_q2k_eligible, write_quantized_gguf
+from hpc_quantize_v2.reference import reference_solve, synthetic_cases
+
+
+class HPCQuantizeGUI:
+    def __init__(self, root: tk.Tk) -> None:
+        self.root = root
+        self.root.title("HPC-Quantize V2 — Factored Q2_K & Geometry-Preserving Analog Engine")
+        self.root.geometry("1180x820")
+        self.root.minsize(980, 680)
+
+        self._log_queue: queue.Queue[tuple[str, object]] = queue.Queue()
+        self._stop_event = threading.Event()
+        self._worker: threading.Thread | None = None
+        self._reader: GGUFReader | None = None
+        self._imatrix: dict[str, np.ndarray] | None = None
+
+        self._init_vars()
+        self._apply_theme()
+        self._build_layout()
+        self._auto_populate_defaults()
+        self._update_cli_preview()
+        self.root.after(100, self._poll_queue)
+
+    def _init_vars(self) -> None:
+        self.gguf_var = tk.StringVar()
+        self.imatrix_var = tk.StringVar()
+        self.output_var = tk.StringVar()
+        self.mode_var = tk.StringVar(value="all")
+        self.filter_var = tk.StringVar()
+
+        self.optimizer_var = tk.StringVar(value="hpc")
+        self.cand_d_var = tk.IntVar(value=6)
+        self.cand_m_var = tk.IntVar(value=6)
+        self.starts_var = tk.IntVar(value=2)
+        self.iters_var = tk.IntVar(value=8)
+        self.ulp_var = tk.IntVar(value=4)
+        self.limit_var = tk.IntVar(value=0)
+
+        self.use_analogs_var = tk.BooleanVar(value=True)
+        self.coupled_q2k_var = tk.BooleanVar(value=True)
+        self.joint_subscales_var = tk.BooleanVar(value=True)
+        self.use_spectral_var = tk.BooleanVar(value=True)
+        self.subblock_sieve_var = tk.BooleanVar(value=True)
+        self.factor_floor_var = tk.BooleanVar(value=True)
+        self.cand_floor_var = tk.BooleanVar(value=True)
+        self.dc_carry_var = tk.BooleanVar(value=True)
+
+        self.dc_lambda_var = tk.DoubleVar(value=1.0)
+        self.vw_lambda_var = tk.DoubleVar(value=1.0)
+        self.dc_decay_var = tk.DoubleVar(value=0.85)
+        self.sse_budget_var = tk.DoubleVar(value=0.0005)
+
+        self.cli_preview_var = tk.StringVar()
+        self.status_var = tk.StringVar(value="Ready.")
+        self.progress_var = tk.DoubleVar(value=0.0)
+
+        for v in (
+            self.gguf_var,
+            self.imatrix_var,
+            self.output_var,
+            self.mode_var,
+            self.optimizer_var,
+            self.cand_d_var,
+            self.cand_m_var,
+            self.limit_var,
+            self.use_spectral_var,
+        ):
+            v.trace_add("write", lambda *_: self._update_cli_preview())
+
+    def _apply_theme(self) -> None:
+        style = ttk.Style(self.root)
+        if "clam" in style.theme_names():
+            style.theme_use("clam")
+        bg = "#141820"
+        panel = "#1c222d"
+        fg = "#e6edf3"
+        accent = "#3b82f6"
+        self.root.configure(bg=bg)
+        style.configure(".", background=bg, foreground=fg, fieldbackground=panel)
+        style.configure("TFrame", background=bg)
+        style.configure("TLabelframe", background=bg, foreground=fg)
+        style.configure("TLabelframe.Label", background=bg, foreground="#93c5fd", font=("Sans", 10, "bold"))
+        style.configure("TLabel", background=bg, foreground=fg)
+        style.configure("TCheckbutton", background=bg, foreground=fg)
+        style.configure("TRadiobutton", background=bg, foreground=fg)
+        style.configure("TButton", background=panel, foreground=fg, padding=(10, 5))
+        style.map("TButton", background=[("active", accent)])
+        style.configure("Accent.TButton", background=accent, foreground="#ffffff", font=("Sans", 10, "bold"))
+        style.configure(
+            "Treeview",
+            background=panel,
+            fieldbackground=panel,
+            foreground=fg,
+            rowheight=24,
+        )
+        style.configure("Treeview.Heading", background="#262f3f", foreground=fg, font=("Sans", 9, "bold"))
+        style.map("Treeview", background=[("selected", accent)])
+
+    def _build_layout(self) -> None:
+        main = ttk.Frame(self.root, padding=10)
+        main.pack(fill=tk.BOTH, expand=True)
+
+        # 1. File Selection Frame
+        files_frame = ttk.LabelFrame(main, text="1. GGUF & iMatrix Paths", padding=10)
+        files_frame.pack(fill=tk.X, pady=(0, 8))
+        files_frame.columnconfigure(1, weight=1)
+
+        ttk.Label(files_frame, text="Source GGUF:").grid(row=0, column=0, sticky=tk.W, padx=(0, 8), pady=3)
+        ttk.Entry(files_frame, textvariable=self.gguf_var).grid(row=0, column=1, sticky=tk.EW, pady=3)
+        ttk.Button(files_frame, text="Browse...", command=self._browse_gguf).grid(row=0, column=2, padx=4, pady=3)
+        ttk.Button(files_frame, text="Inspect GGUF", command=self.inspect_files).grid(row=0, column=3, pady=3)
+
+        ttk.Label(files_frame, text="iMatrix (.gguf/.dat):").grid(row=1, column=0, sticky=tk.W, padx=(0, 8), pady=3)
+        ttk.Entry(files_frame, textvariable=self.imatrix_var).grid(row=1, column=1, sticky=tk.EW, pady=3)
+        ttk.Button(files_frame, text="Browse...", command=self._browse_imatrix).grid(row=1, column=2, padx=4, pady=3)
+        ttk.Button(files_frame, text="Clear", command=lambda: self.imatrix_var.set("")).grid(row=1, column=3, pady=3)
+
+        ttk.Label(files_frame, text="Output (.gguf/.npz):").grid(row=2, column=0, sticky=tk.W, padx=(0, 8), pady=3)
+        ttk.Entry(files_frame, textvariable=self.output_var).grid(row=2, column=1, sticky=tk.EW, pady=3)
+        ttk.Button(files_frame, text="Save As...", command=self._browse_output).grid(row=2, column=2, padx=4, pady=3)
+
+        # 2. Middle Split: Left = Settings, Right = Tensor Browser
+        mid = ttk.PanedWindow(main, orient=tk.HORIZONTAL)
+        mid.pack(fill=tk.BOTH, expand=True, pady=(0, 8))
+
+        left_pane = ttk.Frame(mid)
+        right_pane = ttk.Frame(mid)
+        mid.add(left_pane, weight=2)
+        mid.add(right_pane, weight=3)
+
+        # Left: Engine & Factorization Options
+        opt_frame = ttk.LabelFrame(left_pane, text="2. Factored Q2_K & Analog Controls", padding=10)
+        opt_frame.pack(fill=tk.BOTH, expand=True, padx=(0, 6))
+
+        mode_row = ttk.Frame(opt_frame)
+        mode_row.pack(fill=tk.X, pady=(0, 6))
+        ttk.Label(mode_row, text="Target Scope:").pack(side=tk.LEFT, padx=(0, 8))
+        ttk.Radiobutton(
+            mode_row, text="All Q2_K-Eligible Tensors", variable=self.mode_var, value="all"
+        ).pack(side=tk.LEFT, padx=4)
+        ttk.Radiobutton(
+            mode_row, text="Selected Tensor(s)", variable=self.mode_var, value="selected"
+        ).pack(side=tk.LEFT, padx=4)
+
+        opt_row = ttk.Frame(opt_frame)
+        opt_row.pack(fill=tk.X, pady=(0, 6))
+        ttk.Label(opt_row, text="Global Optimizer:").pack(side=tk.LEFT, padx=(0, 8))
+        ttk.Radiobutton(
+            opt_row, text="HPC (Sieve + 36-State Viterbi)", variable=self.optimizer_var, value="hpc"
+        ).pack(side=tk.LEFT, padx=4)
+        ttk.Radiobutton(
+            opt_row, text="MSE (Local Greedy)", variable=self.optimizer_var, value="mse"
+        ).pack(side=tk.LEFT, padx=4)
+
+        checks = ttk.Frame(opt_frame)
+        checks.pack(fill=tk.X, pady=4)
+        ttk.Checkbutton(
+            checks,
+            text="Geometry-Preserving Weight Analogs (Iso-Moment + Vesica Gram + Subscale Lattice)",
+            variable=self.use_analogs_var,
+        ).pack(anchor=tk.W, pady=2)
+        ttk.Checkbutton(
+            checks,
+            text="Coupled Orthogonal-Basis Bilinear Q2_K Factorization",
+            variable=self.coupled_q2k_var,
+        ).pack(anchor=tk.W, pady=2)
+        ttk.Checkbutton(
+            checks,
+            text="Exact Joint (Ls, Lm) 16x16 Sub-block Scan",
+            variable=self.joint_subscales_var,
+        ).pack(anchor=tk.W, pady=2)
+        ttk.Checkbutton(
+            checks,
+            text="Spectral Fold / Vesica / DC Objective Penalty",
+            variable=self.use_spectral_var,
+        ).pack(anchor=tk.W, pady=2)
+        ttk.Checkbutton(
+            checks,
+            text="Sub-block 6-State Sieve & Rolling DC Residual Carry",
+            variable=self.subblock_sieve_var,
+        ).pack(anchor=tk.W, pady=2)
+        ttk.Checkbutton(
+            checks,
+            text="Local-Safety Candidate & Factored Floors (Monotone Bound)",
+            variable=self.factor_floor_var,
+        ).pack(anchor=tk.W, pady=2)
+
+        grid_f = ttk.Frame(opt_frame)
+        grid_f.pack(fill=tk.X, pady=6)
+        for col in range(4):
+            grid_f.columnconfigure(col, weight=1)
+
+        self._spin_pair(grid_f, 0, 0, "Cand d (1-24):", self.cand_d_var, 1, 24)
+        self._spin_pair(grid_f, 0, 2, "Cand dmin (1-24):", self.cand_m_var, 1, 24)
+        self._spin_pair(grid_f, 1, 0, "Solver Starts:", self.starts_var, 1, 8)
+        self._spin_pair(grid_f, 1, 2, "Solver Iters:", self.iters_var, 1, 32)
+        self._spin_pair(grid_f, 2, 0, "FP16 ULP Radius:", self.ulp_var, 0, 16)
+        self._spin_pair(grid_f, 2, 2, "Tensor Limit (0=all):", self.limit_var, 0, 9999)
+
+        spec_f = ttk.LabelFrame(opt_frame, text="Spectral & DC Parameters", padding=6)
+        spec_f.pack(fill=tk.X, pady=4)
+        for col in range(4):
+            spec_f.columnconfigure(col, weight=1)
+        ttk.Label(spec_f, text="DC Lambda:").grid(row=0, column=0, sticky=tk.W, padx=4, pady=2)
+        ttk.Entry(spec_f, textvariable=self.dc_lambda_var, width=8).grid(row=0, column=1, sticky=tk.EW, padx=4, pady=2)
+        ttk.Label(spec_f, text="Vesica Lambda:").grid(row=0, column=2, sticky=tk.W, padx=4, pady=2)
+        ttk.Entry(spec_f, textvariable=self.vw_lambda_var, width=8).grid(row=0, column=3, sticky=tk.EW, padx=4, pady=2)
+        ttk.Label(spec_f, text="DC Decay:").grid(row=1, column=0, sticky=tk.W, padx=4, pady=2)
+        ttk.Entry(spec_f, textvariable=self.dc_decay_var, width=8).grid(row=1, column=1, sticky=tk.EW, padx=4, pady=2)
+        ttk.Label(spec_f, text="SSE Budget:").grid(row=1, column=2, sticky=tk.W, padx=4, pady=2)
+        ttk.Entry(spec_f, textvariable=self.sse_budget_var, width=8).grid(row=1, column=3, sticky=tk.EW, padx=4, pady=2)
+
+        # Right: GGUF Tensor Browser
+        browser_frame = ttk.LabelFrame(right_pane, text="3. GGUF Tensor Inspector", padding=10)
+        browser_frame.pack(fill=tk.BOTH, expand=True)
+
+        search_row = ttk.Frame(browser_frame)
+        search_row.pack(fill=tk.X, pady=(0, 6))
+        ttk.Label(search_row, text="Filter:").pack(side=tk.LEFT, padx=(0, 6))
+        filter_entry = ttk.Entry(search_row, textvariable=self.filter_var)
+        filter_entry.pack(side=tk.LEFT, fill=tk.X, expand=True)
+        filter_entry.bind("<KeyRelease>", lambda _e: self._populate_tensor_tree())
+        ttk.Button(
+            search_row, text="Select Eligible", command=self._select_all_eligible
+        ).pack(side=tk.LEFT, padx=4)
+
+        cols = ("name", "type", "dims", "row", "q2k", "imat")
+        self.tree = ttk.Treeview(browser_frame, columns=cols, show="headings", selectmode="extended")
+        self.tree.heading("name", text="Tensor Name")
+        self.tree.heading("type", text="Type")
+        self.tree.heading("dims", text="Dims")
+        self.tree.heading("row", text="Row Width")
+        self.tree.heading("q2k", text="Q2_K")
+        self.tree.heading("imat", text="iMatrix")
+
+        self.tree.column("name", width=250, anchor=tk.W)
+        self.tree.column("type", width=60, anchor=tk.CENTER)
+        self.tree.column("dims", width=110, anchor=tk.CENTER)
+        self.tree.column("row", width=75, anchor=tk.E)
+        self.tree.column("q2k", width=55, anchor=tk.CENTER)
+        self.tree.column("imat", width=65, anchor=tk.CENTER)
+        self.tree.bind("<<TreeviewSelect>>", lambda _e: self._update_cli_preview())
+
+        tree_scroll = ttk.Scrollbar(browser_frame, orient=tk.VERTICAL, command=self.tree.yview)
+        self.tree.configure(yscrollcommand=tree_scroll.set)
+        self.tree.pack(side=tk.LEFT, fill=tk.BOTH, expand=True)
+        tree_scroll.pack(side=tk.RIGHT, fill=tk.Y)
+
+        # 4. Equivalent CLI Command Preview
+        cli_frame = ttk.LabelFrame(main, text="4. Equivalent Terminal Command", padding=8)
+        cli_frame.pack(fill=tk.X, pady=(0, 8))
+        ttk.Entry(cli_frame, textvariable=self.cli_preview_var, state="readonly").pack(
+            side=tk.LEFT, fill=tk.X, expand=True, padx=(0, 6)
+        )
+        ttk.Button(cli_frame, text="Copy Command", command=self._copy_cli).pack(side=tk.RIGHT)
+
+        # 5. Action Buttons + Progress + Log Console
+        bottom = ttk.LabelFrame(main, text="5. Execution & Live Output", padding=8)
+        bottom.pack(fill=tk.BOTH, expand=False)
+
+        btn_row = ttk.Frame(bottom)
+        btn_row.pack(fill=tk.X, pady=(0, 6))
+        self.run_btn = ttk.Button(
+            btn_row, text="Run Quantization", style="Accent.TButton", command=self.start_quantization
+        )
+        self.run_btn.pack(side=tk.LEFT, padx=(0, 6))
+        self.stop_btn = ttk.Button(
+            btn_row, text="Cancel", state=tk.DISABLED, command=self.stop_worker
+        )
+        self.stop_btn.pack(side=tk.LEFT, padx=(0, 6))
+        self.bench_btn = ttk.Button(
+            btn_row, text="Run Solver Benchmark", command=self.start_benchmark
+        )
+        self.bench_btn.pack(side=tk.LEFT, padx=(0, 12))
+        ttk.Label(btn_row, textvariable=self.status_var).pack(side=tk.LEFT, fill=tk.X, expand=True)
+
+        self.progress = ttk.Progressbar(bottom, variable=self.progress_var, maximum=100.0)
+        self.progress.pack(fill=tk.X, pady=(0, 6))
+
+        log_frame = ttk.Frame(bottom)
+        log_frame.pack(fill=tk.BOTH, expand=True)
+        self.log_text = tk.Text(
+            log_frame,
+            height=9,
+            bg="#0f131a",
+            fg="#d1d5db",
+            insertbackground="#ffffff",
+            font=("Monospace", 9),
+            wrap=tk.WORD,
+        )
+        log_scroll = ttk.Scrollbar(log_frame, orient=tk.VERTICAL, command=self.log_text.yview)
+        self.log_text.configure(yscrollcommand=log_scroll.set)
+        self.log_text.pack(side=tk.LEFT, fill=tk.BOTH, expand=True)
+        log_scroll.pack(side=tk.RIGHT, fill=tk.Y)
+
+    def _spin_pair(self, parent, row, col, label, var, low, high) -> None:
+        ttk.Label(parent, text=label).grid(row=row, column=col, sticky=tk.W, padx=4, pady=2)
+        sp = ttk.Spinbox(parent, from_=low, to=high, textvariable=var, width=6)
+        sp.grid(row=row, column=col + 1, sticky=tk.EW, padx=4, pady=2)
+
+    def _auto_populate_defaults(self) -> None:
+        default_gguf = Path("Raon.gguf")
+        default_imat = Path("imatrix.gguf")
+        if default_imat.exists():
+            self.imatrix_var.set(str(default_imat.resolve()))
+        if default_gguf.exists():
+            self.gguf_var.set(str(default_gguf.resolve()))
+            self.output_var.set(str(default_gguf.with_name("Raon-Q2K.gguf").resolve()))
+            self.inspect_files()
+
+    def _browse_gguf(self) -> None:
+        path = filedialog.askopenfilename(
+            title="Select Source GGUF",
+            filetypes=[("GGUF Model", "*.gguf"), ("All Files", "*.*")],
+        )
+        if path:
+            self.gguf_var.set(path)
+            p = Path(path)
+            if not self.output_var.get():
+                self.output_var.set(str(p.with_name(f"{p.stem}-Q2K.gguf")))
+            self.inspect_files()
+
+    def _browse_imatrix(self) -> None:
+        path = filedialog.askopenfilename(
+            title="Select iMatrix File",
+            filetypes=[("iMatrix Files", "*.gguf *.dat *.imatrix"), ("All Files", "*.*")],
+        )
+        if path:
+            self.imatrix_var.set(path)
+            self.inspect_files()
+
+    def _browse_output(self) -> None:
+        path = filedialog.asksaveasfilename(
+            title="Select Output File",
+            defaultextension=".gguf",
+            filetypes=[("GGUF Model", "*.gguf"), ("NumPy Archive", "*.npz"), ("All Files", "*.*")],
+        )
+        if path:
+            self.output_var.set(path)
+
+    def _log(self, msg: str) -> None:
+        self.log_text.insert(tk.END, msg + "\n")
+        self.log_text.see(tk.END)
+
+    def build_config(self) -> HPCConfig:
+        cfg = HPCConfig(
+            n_cand_d=int(self.cand_d_var.get()),
+            n_cand_m=int(self.cand_m_var.get()),
+            factor_starts=int(self.starts_var.get()),
+            factor_standalone_iters=int(self.iters_var.get()),
+            ulp_radius=int(self.ulp_var.get()),
+            optimizer=self.optimizer_var.get(),
+            use_weight_analogs=bool(self.use_analogs_var.get()),
+            factor_coupled_q2k=bool(self.coupled_q2k_var.get()),
+            factor_joint_subscales=bool(self.joint_subscales_var.get()),
+            use_spectral=bool(self.use_spectral_var.get()),
+            subblock_sieve=bool(self.subblock_sieve_var.get()),
+            use_factor_floor=bool(self.factor_floor_var.get()),
+            use_candidate_floor=bool(self.cand_floor_var.get()),
+            apply_dc_carry=bool(self.dc_carry_var.get()),
+            dc_lambda=float(self.dc_lambda_var.get()),
+            vw_lambda=float(self.vw_lambda_var.get()),
+            dc_decay=float(self.dc_decay_var.get()),
+            sse_budget=float(self.sse_budget_var.get()),
+            verbose=False,
+        )
+        return cfg.validate()
+
+    def build_cli_command(self) -> str:
+        cmd = ["python3", "-m", "hpc_quantize_v2"]
+        gguf = self.gguf_var.get().strip()
+        if gguf:
+            cmd += ["--gguf", gguf]
+        selected = self._selected_tensor_names()
+        if self.mode_var.get() == "selected" and len(selected) == 1:
+            cmd += ["--tensor", next(iter(selected))]
+        else:
+            cmd.append("--all-q2k")
+        imat = self.imatrix_var.get().strip()
+        if imat:
+            cmd += ["--imatrix-gguf", imat]
+        out = self.output_var.get().strip()
+        if out:
+            cmd += ["--output", out]
+        if self.limit_var.get() > 0:
+            cmd += ["--limit", str(self.limit_var.get())]
+        cmd += ["--cand-d", str(self.cand_d_var.get()), "--cand-m", str(self.cand_m_var.get())]
+        if self.optimizer_var.get() == "mse":
+            cmd.append("--mse")
+        if not self.use_spectral_var.get():
+            cmd.append("--no-spectral")
+        cmd.append("--verbose")
+        return " ".join(shlex.quote(part) for part in cmd)
+
+    def _update_cli_preview(self) -> None:
+        try:
+            self.cli_preview_var.set(self.build_cli_command())
+        except Exception:
+            pass
+
+    def _copy_cli(self) -> None:
+        cmd = self.cli_preview_var.get()
+        self.root.clipboard_clear()
+        self.root.clipboard_append(cmd)
+        self.status_var.set("Copied CLI command to clipboard.")
+
+    def inspect_files(self) -> None:
+        imat_path = self.imatrix_var.get().strip()
+        if imat_path and Path(imat_path).exists():
+            try:
+                self._imatrix = read_imatrix(imat_path)
+                self._log(f"Loaded iMatrix: {len(self._imatrix)} entries from {imat_path}")
+            except Exception as exc:
+                self._imatrix = None
+                self._log(f"iMatrix load error: {exc}")
+        else:
+            self._imatrix = None
+
+        gguf_path = self.gguf_var.get().strip()
+        if not gguf_path or not Path(gguf_path).exists():
+            return
+        try:
+            self._reader = GGUFReader(gguf_path)
+            eligible = sum(1 for t in self._reader.tensors if is_q2k_eligible(t.name, t.dims))
+            self._log(
+                f"Inspected {gguf_path}: {len(self._reader.tensors)} tensors "
+                f"({eligible} Q2_K-eligible), {len(self._reader.metadata)} metadata keys."
+            )
+            self.status_var.set(f"Loaded {len(self._reader.tensors)} tensors ({eligible} Q2_K-eligible).")
+            self._populate_tensor_tree()
+        except Exception as exc:
+            self._reader = None
+            self._log(f"GGUF inspect error: {exc}")
+
+    def _populate_tensor_tree(self) -> None:
+        self.tree.delete(*self.tree.get_children())
+        if self._reader is None:
+            return
+        filt = self.filter_var.get().strip().lower()
+        for ti in self._reader.tensors:
+            if filt and filt not in ti.name.lower() and filt not in ti.type_name.lower():
+                continue
+            elig = is_q2k_eligible(ti.name, ti.dims)
+            has_imat = (
+                self._imatrix is not None
+                and lookup_imatrix(self._imatrix, ti.name) is not None
+            )
+            self.tree.insert(
+                "",
+                tk.END,
+                iid=ti.name,
+                values=(
+                    ti.name,
+                    ti.type_name,
+                    str(ti.dims),
+                    ti.row_width,
+                    "Yes" if elig else "No",
+                    "Yes" if has_imat else "-",
+                ),
+            )
+
+    def _select_all_eligible(self) -> None:
+        if self._reader is None:
+            return
+        eligible_ids = [
+            ti.name
+            for ti in self._reader.tensors
+            if is_q2k_eligible(ti.name, ti.dims) and self.tree.exists(ti.name)
+        ]
+        self.tree.selection_set(eligible_ids)
+
+    def _selected_tensor_names(self) -> set[str]:
+        return set(self.tree.selection())
+
+    def stop_worker(self) -> None:
+        if self._worker and self._worker.is_alive():
+            self._stop_event.set()
+            self.status_var.set("Cancelling after current tensor...")
+
+    def start_quantization(self) -> None:
+        if self._worker and self._worker.is_alive():
+            return
+        gguf_path = self.gguf_var.get().strip()
+        if not gguf_path or not Path(gguf_path).exists():
+            messagebox.showerror("Missing Source GGUF", "Please select a valid source GGUF file.")
+            return
+        out_path = self.output_var.get().strip()
+        if not out_path:
+            p = Path(gguf_path)
+            out_path = str(p.with_name(f"{p.stem}-Q2K.gguf"))
+            self.output_var.set(out_path)
+        try:
+            cfg = self.build_config()
+        except Exception as exc:
+            messagebox.showerror("Invalid Configuration", str(exc))
+            return
+
+        selected = self._selected_tensor_names() if self.mode_var.get() == "selected" else None
+        if self.mode_var.get() == "selected" and not selected:
+            messagebox.showwarning("No Tensor Selected", "Select one or more tensors in the table first.")
+            return
+
+        imat_path = self.imatrix_var.get().strip()
+        limit = int(self.limit_var.get())
+
+        self._stop_event.clear()
+        self.progress_var.set(0.0)
+        self.run_btn.configure(state=tk.DISABLED)
+        self.bench_btn.configure(state=tk.DISABLED)
+        self.stop_btn.configure(state=tk.NORMAL)
+        self.status_var.set("Running quantization...")
+
+        self._worker = threading.Thread(
+            target=self._quantize_worker,
+            args=(gguf_path, imat_path, out_path, cfg, selected, limit),
+            daemon=True,
+        )
+        self._worker.start()
+
+    def _quantize_worker(
+        self,
+        gguf_path: str,
+        imat_path: str,
+        out_path: str,
+        cfg: HPCConfig,
+        selected: set[str] | None,
+        limit: int,
+    ) -> None:
+        t0 = time.time()
+        try:
+            imat = None
+            if imat_path and Path(imat_path).exists():
+                imat = read_imatrix(imat_path)
+                self._log_queue.put(("log", f"Loaded iMatrix ({len(imat)} tensors) from {imat_path}"))
+
+            quantizer = Q2KQuantizer(cfg)
+            if out_path.lower().endswith(".npz") and selected and len(selected) == 1:
+                reader = GGUFReader(gguf_path)
+                tname = next(iter(selected))
+                x, row = reader.read_tensor(tname)
+                imp = None
+                if imat is not None:
+                    raw = lookup_imatrix(imat, tname)
+                    if raw is not None:
+                        imp = expand_importance(raw, x.size, row)
+                res = quantizer.quantize(x, importance=imp, row_width=row)
+                np.savez_compressed(
+                    out_path,
+                    scales=res.scales,
+                    qs=res.qs,
+                    dm=res.dm,
+                    dequantized=res.dequantize(),
+                    rmse=np.float32(res.stats.rmse),
+                )
+                self._log_queue.put(
+                    ("done", f"Saved {out_path} (RMSE={res.stats.rmse:.6e}, {time.time() - t0:.1f}s)")
+                )
+                return
+
+            def on_progress(done: int, total: int, name: str, action: str, rmse: float | None, has_imat: bool):
+                pct = 100.0 * done / max(total, 1)
+                self._log_queue.put(("progress", (pct, f"[{done}/{total}] {action} {name}")))
+                if action == "Q2_K" and rmse is not None:
+                    self._log_queue.put(
+                        (
+                            "log",
+                            f"[{done}/{total}] Q2_K {name:44s} RMSE={rmse:.6e} iMatrix={'yes' if has_imat else 'no'}",
+                        )
+                    )
+
+            stats = write_quantized_gguf(
+                gguf_path,
+                out_path,
+                quantizer,
+                imat=imat,
+                quantize_all=(selected is None),
+                tensor_names=selected,
+                limit=limit,
+                verbose=False,
+                progress_callback=on_progress,
+                stop_event=self._stop_event,
+            )
+            dt = time.time() - t0
+            self._log_queue.put(
+                (
+                    "done",
+                    f"Wrote {out_path}: {int(stats['quantized'])}/{int(stats['tensors'])} tensors Q2_K, "
+                    f"overall RMSE={stats['rmse']:.6e} ({dt:.1f}s)",
+                )
+            )
+        except InterruptedError as exc:
+            self._log_queue.put(("cancelled", str(exc)))
+        except Exception as exc:
+            self._log_queue.put(("error", str(exc)))
+
+    def start_benchmark(self) -> None:
+        if self._worker and self._worker.is_alive():
+            return
+        try:
+            cfg = self.build_config()
+        except Exception as exc:
+            messagebox.showerror("Invalid Configuration", str(exc))
+            return
+        self._stop_event.clear()
+        self.progress_var.set(0.0)
+        self.run_btn.configure(state=tk.DISABLED)
+        self.bench_btn.configure(state=tk.DISABLED)
+        self.stop_btn.configure(state=tk.NORMAL)
+        self.status_var.set("Running factored solver benchmark...")
+        self._worker = threading.Thread(target=self._bench_worker, args=(cfg,), daemon=True)
+        self._worker.start()
+
+    def _bench_worker(self, cfg: HPCConfig) -> None:
+        from collections import defaultdict
+
+        try:
+            cases = synthetic_cases(123, 8)
+            gains = defaultdict(list)
+            total = len(cases)
+            for idx, (kind, x) in enumerate(cases, 1):
+                if self._stop_event.is_set():
+                    raise InterruptedError("Benchmark cancelled.")
+                w = np.ones(x.size, dtype=np.float32)
+                v2 = factor_only_solve(x, w, cfg)
+                ref_obj, _ = reference_solve(x, w, cfg, cfg.use_spectral)
+                gains[kind].append((ref_obj - v2.objective) / max(abs(ref_obj), 1.0e-30))
+                self._log_queue.put(("progress", (100.0 * idx / total, f"Bench {idx}/{total} ({kind})")))
+
+            self._log_queue.put(("log", f"--- Benchmark (spectral={cfg.use_spectral}, analogs={cfg.use_weight_analogs}) ---"))
+            for kind, vals in gains.items():
+                arr = np.asarray(vals)
+                self._log_queue.put(
+                    (
+                        "log",
+                        f"  {kind:14s} mean={arr.mean()*100:6.2f}%  median={np.median(arr)*100:6.2f}%  "
+                        f"min={arr.min()*100:6.2f}%  worse={int(np.sum(arr < -1e-9))}/{arr.size}",
+                    )
+                )
+            self._log_queue.put(("done", "Benchmark complete."))
+        except InterruptedError as exc:
+            self._log_queue.put(("cancelled", str(exc)))
+        except Exception as exc:
+            self._log_queue.put(("error", str(exc)))
+
+    def _poll_queue(self) -> None:
+        while True:
+            try:
+                kind, payload = self._log_queue.get_nowait()
+            except queue.Empty:
+                break
+            if kind == "log":
+                self._log(str(payload))
+            elif kind == "progress":
+                pct, msg = payload  # type: ignore[misc]
+                self.progress_var.set(float(pct))
+                self.status_var.set(str(msg))
+            elif kind == "done":
+                self.progress_var.set(100.0)
+                self.status_var.set(str(payload))
+                self._log(str(payload))
+                self._reset_buttons()
+            elif kind in ("cancelled", "error"):
+                self.status_var.set(f"{kind.upper()}: {payload}")
+                self._log(f"{kind.upper()}: {payload}")
+                self._reset_buttons()
+        self.root.after(100, self._poll_queue)
+
+    def _reset_buttons(self) -> None:
+        self.run_btn.configure(state=tk.NORMAL)
+        self.bench_btn.configure(state=tk.NORMAL)
+        self.stop_btn.configure(state=tk.DISABLED)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="HPC-Quantize V2 GUI")
+    parser.add_argument("--gguf", help="pre-populate source GGUF path")
+    parser.add_argument("--imatrix", help="pre-populate iMatrix path")
+    parser.add_argument("--output", help="pre-populate output GGUF path")
+    parser.add_argument("--check", action="store_true", help="validate GUI bindings without opening a window")
+    args = parser.parse_args()
+
+    if args.check:
+        cfg = HPCConfig().validate()
+        print("GUI check OK:", cfg)
+        return
+
+    root = tk.Tk()
+    app = HPCQuantizeGUI(root)
+    if args.gguf:
+        app.gguf_var.set(args.gguf)
+    if args.imatrix:
+        app.imatrix_var.set(args.imatrix)
+    if args.output:
+        app.output_var.set(args.output)
+    if args.gguf or args.imatrix:
+        app.inspect_files()
+    root.mainloop()
+
+
+if __name__ == "__main__":
+    main()