Upload 6 files

__init__.py

@@ -26,6 +26,7 @@ from .gguf import (
     expand_importance,
     is_q1_0_eligible,
     is_q2k_eligible,
+    is_q3_k_eligible,
     is_q4_0_eligible,
     lookup_imatrix,
     read_imatrix,
@@ -34,6 +35,7 @@ from .gguf import (
 from .pipeline import Q2KQuantizer, QuantizedTensor, TensorStats
 from .q1_0 import Q1_0_BLOCK_BYTES, QK1_0, dequantize_q1_0_bytes, quantize_tensor_q1_0
 from .q2k import Q2KBlock, QK_K, dequantize_params, pack_codes, unpack_codes
+from .q3_k import Q3_K_BLOCK_BYTES, QK3_K, dequantize_q3_k_bytes, quantize_tensor_q3_k
 from .q4_0 import QK4_0, dequantize_q4_0_bytes, quantize_tensor_q4_0
 
 __all__ = [
@@ -60,6 +62,7 @@ __all__ = [
     "expand_importance",
     "is_q1_0_eligible",
     "is_q2k_eligible",
+    "is_q3_k_eligible",
     "is_q4_0_eligible",
     "lookup_imatrix",
     "read_imatrix",
@@ -68,6 +71,10 @@ __all__ = [
     "Q1_0_BLOCK_BYTES",
     "dequantize_q1_0_bytes",
     "quantize_tensor_q1_0",
+    "QK3_K",
+    "Q3_K_BLOCK_BYTES",
+    "dequantize_q3_k_bytes",
+    "quantize_tensor_q3_k",
     "QK4_0",
     "dequantize_q4_0_bytes",
     "quantize_tensor_q4_0",

__main__.py

@@ -22,7 +22,6 @@ from .config import HPCConfig
 from .factored import factor_only_solve
 from .gguf import (
     GGUFReader,
-    SUPPORTED_READ_TYPES,
     expand_importance,
     is_q2k_eligible,
     lookup_imatrix,
@@ -56,7 +55,7 @@ def _config_from_args(args) -> HPCConfig:
         cfg.promote_attn_q4 = True
     if args.format is not None:
         cfg.quant_format = args.format
-        if args.format == "q2_k":
+        if args.format in ("q2_k", "q3_k"):
             cfg.enable_q4_fallback = False
     if getattr(args, "tensor_type", None):
         custom: dict[str, str] = {}
@@ -69,6 +68,7 @@ def _config_from_args(args) -> HPCConfig:
             canonical = {
                 "q1_0": "Q1_0",
                 "q2_k": "Q2_K",
+                "q3_k": "Q3_K",
                 "q4_0": "Q4_0",
                 "copy": "Copy",
                 "auto": "Auto",
@@ -77,7 +77,7 @@ def _config_from_args(args) -> HPCConfig:
             if norm is None:
                 raise SystemExit(
                     f"--tensor-type {key!r} has invalid quant {value!r}; "
-                    "use Q1_0, Q2_K, Q4_0, Copy, or Auto"
+                    "use Q1_0, Q2_K, Q3_K, Q4_0, Copy, or Auto"
                 )
             custom[key] = norm
         cfg.custom_quant_map = custom
@@ -127,8 +127,6 @@ def _run_gguf(args, cfg: HPCConfig) -> None:
                 source_type=ti.type,
                 custom_quant_map=cfg.custom_quant_map or None,
             )
-            if tgt is not None and ti.type not in SUPPORTED_READ_TYPES:
-                tgt = None
             tag = tgt if tgt else "COPY"
             print(
                 f"  {tag:4s} {ti.name:48s} {ti.type_name:6s} "
@@ -155,8 +153,8 @@ def _run_gguf(args, cfg: HPCConfig) -> None:
             verbose=True,
         )
         print(
-            f"wrote {args.output}: {int(stats.get('q2_k', 0))} Q2_K + {int(stats.get('q4_0', 0))} Q4_0 + "
-            f"{int(stats.get('q1_0', 0))} Q1_0 "
+            f"wrote {args.output}: {int(stats.get('q2_k', 0))} Q2_K + {int(stats.get('q3_k', 0))} Q3_K + "
+            f"{int(stats.get('q4_0', 0))} Q4_0 + {int(stats.get('q1_0', 0))} Q1_0 "
             f"({int(stats['quantized'])}/{int(stats['tensors'])} tensors), rmse={stats['rmse']:.6e}"
         )
         return
@@ -281,9 +279,9 @@ def main() -> None:
     parser.add_argument("--no-spectral", action="store_true", help="disable spectral/DC objective")
     parser.add_argument(
         "--format",
-        choices=("mixed", "mixed_q1", "custom", "q1_0", "q4_0", "q2_k"),
+        choices=("mixed", "mixed_q1", "custom", "q1_0", "q3_k", "q4_0", "q2_k"),
         default=None,
-        help="quantization format mode: mixed (Q2_K+Q4_0), mixed_q1 (Q1_0+Q4_0), custom (per-tensor-type overrides), q1_0 (pure Q1_0), q4_0 (pure Q4_0), or q2_k (pure Q2_K)",
+        help="quantization format mode: mixed (Q2_K+Q4_0), mixed_q1 (Q1_0+Q4_0), custom (per-tensor-type overrides), q1_0 (pure Q1_0), q3_k (pure Q3_K), q4_0 (pure Q4_0), or q2_k (pure Q2_K)",
     )
     parser.add_argument(
         "--tensor-type",
@@ -291,7 +289,7 @@ def main() -> None:
         default=[],
         metavar="TYPE=QUANT",
         help="per-tensor-type override, e.g. ffn_up=Q1_0 or attn_output=Q1_0 "
-        "(QUANT: Q1_0, Q2_K, Q4_0, Copy, Auto; repeatable)",
+        "(QUANT: Q1_0, Q2_K, Q3_K, Q4_0, Copy, Auto; repeatable)",
     )
     parser.add_argument("--no-q4-fallback", action="store_true", help="disable Q4_0 fallback for non-256-aligned tensors")
     parser.add_argument("--keep-embd", action="store_true", help="keep token_embd/output.weight at source precision")

config.py

@@ -121,15 +121,15 @@ class HPCConfig:
             raise ValueError("workers must be >= 0 (0 = auto CPU count)")
         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", "q4_0", "q2_k"):
+        if self.quant_format not in ("mixed", "mixed_q1", "custom", "q1_0", "q3_k", "q4_0", "q2_k"):
             raise ValueError(
-                "quant_format must be 'mixed', 'mixed_q1', 'custom', 'q1_0', 'q4_0', or 'q2_k'"
+                "quant_format must be 'mixed', 'mixed_q1', 'custom', 'q1_0', 'q3_k', 'q4_0', or 'q2_k'"
             )
-        allowed_custom = {"q1_0", "q2_k", "q4_0", "copy", "auto"}
+        allowed_custom = {"q1_0", "q2_k", "q3_k", "q4_0", "copy", "auto"}
         for tensor_type, quant in self.custom_quant_map.items():
             if str(quant).strip().lower() not in allowed_custom:
                 raise ValueError(
                     f"custom_quant_map[{tensor_type!r}] must be one of "
-                    f"Q1_0, Q2_K, Q4_0, Copy, Auto, got {quant!r}"
+                    f"Q1_0, Q2_K, Q3_K, Q4_0, Copy, Auto, got {quant!r}"
                 )
         return self

gguf.py

@@ -23,6 +23,7 @@ from pathlib import Path
 import numpy as np
 
 from .q2k import QK_K, blocks_to_bytes, dequantize_params_batch, unpack_codes
+from .q3_k import Q3_K_BLOCK_BYTES, QK3_K, dequantize_q3_k_bytes, quantize_tensor_q3_k
 from .q4_0 import Q4_0_BLOCK_BYTES, QK4_0, quantize_tensor_q4_0
 from .q1_0 import QK1_0, Q1_0_BLOCK_BYTES, quantize_tensor_q1_0
 
@@ -37,6 +38,7 @@ GGML_TYPE_Q5_0 = 6
 GGML_TYPE_Q5_1 = 7
 GGML_TYPE_Q8_0 = 8
 GGML_TYPE_Q2_K = 10
+GGML_TYPE_Q3_K = 11
 GGML_TYPE_BF16 = 30
 GGML_TYPE_Q1_0 = 41
 
@@ -49,21 +51,9 @@ TYPE_NAME = {
     GGML_TYPE_Q5_1: "Q5_1",
     GGML_TYPE_Q8_0: "Q8_0",
     GGML_TYPE_Q2_K: "Q2_K",
+    GGML_TYPE_Q3_K: "Q3_K",
     GGML_TYPE_BF16: "BF16",
     GGML_TYPE_Q1_0: "Q1_0",
-    11: "Q3_K",
-    12: "Q4_K",
-    13: "Q5_K",
-    14: "Q6_K",
-    15: "Q8_K",
-    16: "IQ2_XXS",
-    17: "IQ2_XS",
-    18: "IQ3_XXS",
-    19: "IQ1_S",
-    20: "IQ4_NL",
-    21: "IQ3_S",
-    22: "IQ2_S",
-    23: "IQ4_XS",
 }
 
 BLOCK_SIZE = {
@@ -76,12 +66,8 @@ BLOCK_SIZE = {
     GGML_TYPE_Q5_1: 32,
     GGML_TYPE_Q8_0: 32,
     GGML_TYPE_Q2_K: QK_K,
+    GGML_TYPE_Q3_K: QK3_K,
     GGML_TYPE_Q1_0: QK1_0,
-    11: QK_K,  # Q3_K
-    12: QK_K,  # Q4_K
-    13: QK_K,  # Q5_K
-    14: QK_K,  # Q6_K
-    15: QK_K,  # Q8_K
 }
 BLOCK_BYTES = {
     GGML_TYPE_F32: 4,
@@ -93,12 +79,8 @@ BLOCK_BYTES = {
     GGML_TYPE_Q5_1: 24,
     GGML_TYPE_Q8_0: 34,
     GGML_TYPE_Q2_K: 84,
+    GGML_TYPE_Q3_K: Q3_K_BLOCK_BYTES,
     GGML_TYPE_Q1_0: Q1_0_BLOCK_BYTES,
-    11: 110,  # Q3_K
-    12: 144,  # Q4_K
-    13: 176,  # Q5_K
-    14: 210,  # Q6_K
-    15: 292,  # Q8_K
 }
 TYPE_BPW = {
     GGML_TYPE_F32: 32.0,
@@ -110,8 +92,8 @@ TYPE_BPW = {
     GGML_TYPE_Q4_1: 5.0,
     GGML_TYPE_Q4_0: 4.5,
     GGML_TYPE_Q2_K: 2.625,
+    GGML_TYPE_Q3_K: 3.4375,
     GGML_TYPE_Q1_0: 1.125,
-    11: 3.4375,  # Q3_K
     12: 4.5,     # Q4_K
     13: 5.5,     # Q5_K
     14: 6.5625,  # Q6_K
@@ -140,6 +122,7 @@ SUPPORTED_READ_TYPES = {
     GGML_TYPE_Q4_0,
     GGML_TYPE_Q8_0,
     GGML_TYPE_Q2_K,
+    GGML_TYPE_Q3_K,
     GGML_TYPE_Q1_0,
 }
 
@@ -150,7 +133,6 @@ class TensorInfo:
     dims: tuple[int, ...]
     type: int
     offset: int
-    raw_size: int | None = None
 
     @property
     def n_elements(self) -> int:
@@ -169,8 +151,6 @@ class TensorInfo:
 
     @property
     def n_bytes(self) -> int:
-        if self.raw_size is not None:
-            return self.raw_size
         if self.type not in BLOCK_SIZE:
             raise ValueError(f"unsupported GGUF type {self.type} ({self.type_name})")
         block = BLOCK_SIZE[self.type]
@@ -260,18 +240,6 @@ class GGUFReader:
             self.info_end = f.tell()
             self.alignment = int(self.metadata.get("general.alignment", DEFAULT_ALIGNMENT))
             self.data_start = _align(self.info_end, self.alignment)
-        file_size = self.path.stat().st_size
-        for i, ti in enumerate(self.tensors):
-            if ti.type in BLOCK_SIZE:
-                continue
-            end = (
-                self.tensors[i + 1].offset
-                if i + 1 < len(self.tensors)
-                else file_size - self.data_start
-            )
-            if end < ti.offset:
-                raise ValueError(f"{self.path}: tensor '{ti.name}' has an invalid offset")
-            ti.raw_size = end - ti.offset
         self._by_name = {ti.name: ti for ti in self.tensors}
 
     def info(self, name: str) -> TensorInfo:
@@ -360,6 +328,9 @@ def _dequantize(raw: bytes, ti: TensorInfo) -> np.ndarray:
         d = blocks[:, :2].copy().view("<f2").reshape(-1, 1).astype(np.float32)
         bits = np.unpackbits(blocks[:, 2:], axis=1, bitorder="little")[:, :QK1_0].astype(np.float32)
         return (d * (bits * 2.0 - 1.0)).reshape(-1)
+    if t == GGML_TYPE_Q3_K:
+        n_blocks = len(raw) // Q3_K_BLOCK_BYTES
+        return dequantize_q3_k_bytes(raw, n_blocks)
     if t == GGML_TYPE_Q2_K:
         blocks = np.frombuffer(raw, dtype=np.uint8).reshape(-1, 84)
         n = blocks.shape[0]
@@ -538,6 +509,20 @@ def is_q2k_eligible(name: str, dims: tuple[int, ...]) -> bool:
     return n_elements >= QK_K and n_elements % QK_K == 0
 
 
+def is_q3_k_eligible(name: str, dims: tuple[int, ...]) -> bool:
+    """True for 256-aligned 2D/3D weight tensors eligible for Q3_K."""
+    if _is_skipped_metadata_tensor(name, dims):
+        return False
+    if _is_embd_or_head(name):
+        return False
+    if dims[0] % QK3_K != 0:
+        return False
+    n_elements = 1
+    for d in dims:
+        n_elements *= int(d)
+    return n_elements >= QK3_K and n_elements % QK3_K == 0
+
+
 def is_q4_0_eligible(
     name: str,
     dims: tuple[int, ...],
@@ -603,10 +588,11 @@ def target_quant_type(
       tensor types fall back to the 'mixed' plan.
     * 'q4_0': all 32-aligned eligible weight tensors -> Q4_0.
     * 'q2_k': only Q2_K-eligible tensors -> Q2_K; everything else copied.
+    * 'q3_k': only Q3_K-eligible tensors -> Q3_K; everything else copied.
     * 'q1_0': all 128-aligned eligible weight tensors -> Q1_0.
 
     ``custom_quant_map`` maps a layer-independent tensor type (see
-    :func:`tensor_type_key`) to 'Q1_0', 'Q2_K', 'Q4_0', 'Copy', or 'Auto'.
+    :func:`tensor_type_key`) to 'Q1_0', 'Q2_K', 'Q3_K', 'Q4_0', 'Copy', or 'Auto'.
     Non-Auto entries override the selected mode for that tensor type.  A target
     is applied only when the tensor is actually eligible for it; explicit
     'Copy' (and ineligible targets) leave the tensor at its source precision.
@@ -627,6 +613,9 @@ def target_quant_type(
         elif choice == "Q2_K":
             if is_q2k_eligible(name, dims):
                 tgt = "Q2_K"
+        elif choice == "Q3_K":
+            if is_q3_k_eligible(name, dims):
+                tgt = "Q3_K"
         elif choice == "Q4_0":
             if is_q4_0_eligible(name, dims, include_embd=True, allow_q2k_tensors=True):
                 tgt = "Q4_0"
@@ -668,6 +657,9 @@ def target_quant_type(
     elif fmt == "q2_k":
         if is_q2k_eligible(name, dims):
             tgt = "Q2_K"
+    elif fmt == "q3_k":
+        if is_q3_k_eligible(name, dims):
+            tgt = "Q3_K"
     else:
         if promote_attn_q4 and _is_attention_projection(name) and is_q4_0_eligible(
             name, dims, include_embd=quantize_embd_q4, promote_attn=True
@@ -682,7 +674,7 @@ def target_quant_type(
 
     if tgt is not None and source_type is not None:
         src_bpw = source_type_bpw(int(source_type))
-        tgt_bpw = {"Q2_K": 2.625, "Q4_0": 4.5, "Q1_0": 1.125}[tgt]
+        tgt_bpw = {"Q2_K": 2.625, "Q3_K": 3.4375, "Q4_0": 4.5, "Q1_0": 1.125}[tgt]
         if src_bpw <= tgt_bpw + 1.0e-6:
             return None
     return tgt
@@ -750,7 +742,7 @@ def write_quantized_gguf(
                     custom_choice is not None
                     and str(custom_choice).strip().lower() not in ("", "auto")
                 )
-                if target_fmt is None and not explicit_custom:
+                if target_fmt is None and not explicit_custom and q_format != "q3_k":
                     src_bpw = source_type_bpw(ti.type)
                     if q_format == "q1_0" and len(ti.dims) >= 2 and ti.dims[0] % QK1_0 == 0 and src_bpw > 1.125:
                         target_fmt = "Q1_0"
@@ -792,6 +784,11 @@ def write_quantized_gguf(
             out_type = GGML_TYPE_Q2_K
             out_size = n_blocks * 84
             total_planned_blocks += n_blocks
+        elif fmt == "Q3_K":
+            n_blocks = ti.n_elements // QK3_K
+            out_type = GGML_TYPE_Q3_K
+            out_size = n_blocks * Q3_K_BLOCK_BYTES
+            total_planned_blocks += max(1, n_blocks // 16)
         elif fmt == "Q4_0":
             n_blocks = ti.n_elements // QK4_0
             out_type = GGML_TYPE_Q4_0
@@ -809,9 +806,10 @@ def write_quantized_gguf(
         data_offset = _align(data_offset + out_size, alignment)
 
     has_q2k = any(fmt == "Q2_K" for fmt in plan)
+    has_q3k = any(fmt == "Q3_K" for fmt in plan)
     has_q1_0 = any(fmt == "Q1_0" for fmt in plan)
-    # 10 = MOSTLY_Q2_K, 2 = MOSTLY_Q4_0, 40 = MOSTLY_Q1_0
-    ftype_code = 10 if has_q2k else (40 if has_q1_0 else 2)
+    # 11 = MOSTLY_Q3_K, 10 = MOSTLY_Q2_K, 2 = MOSTLY_Q4_0, 40 = MOSTLY_Q1_0
+    ftype_code = 11 if has_q3k else (10 if has_q2k else (40 if has_q1_0 else 2))
     kv_pairs = []
     for key, vtype, raw in reader.kv_pairs:
         if quantized_count and key == "general.file_type" and vtype == 4:
@@ -825,6 +823,7 @@ def write_quantized_gguf(
     total_rmse = 0.0
     total_quantized = 0
     total_q2k = 0
+    total_q3k = 0
     total_q4_0 = 0
     total_q1_0 = 0
     total_elements = 0
@@ -937,6 +936,78 @@ def write_quantized_gguf(
                         float(res.stats.rmse),
                         imp is not None,
                     )
+            elif fmt == "Q3_K":
+                t_blocks_q3 = ti.n_elements // QK3_K
+                eff_tb = max(1, t_blocks_q3 // 16)
+                raw_imp = lookup_imatrix(imat, ti.name) if imat is not None else None
+                has_imat = raw_imp is not None and raw_imp.size == ti.row_width
+                written_bytes = 0
+                sse_q3 = 0.0
+                done_q3_blks = 0
+                t_q3_start = time.time()
+
+                for x_chunk, row, _r0, _r1 in reader.iter_tensor_row_chunks(ti.name, max_elements=8_388_608):
+                    if stop_event is not None and stop_event.is_set():
+                        raise InterruptedError("Quantization cancelled by user")
+                    imp_chunk = expand_importance(raw_imp, x_chunk.size, row) if has_imat else None
+                    q3_bytes, nb_chunk, chunk_rmse = quantize_tensor_q3_k(
+                        x_chunk, importance=imp_chunk, cfg=cfg
+                    )
+                    fout.write(q3_bytes)
+                    written_bytes += len(q3_bytes)
+                    sse_q3 += (chunk_rmse * chunk_rmse) * x_chunk.size
+                    done_q3_blks += nb_chunk
+                    if stage_callback is not None:
+                        frac = done_q3_blks / max(t_blocks_q3, 1)
+                        eff_blocks = completed_planned_blocks + frac * eff_tb
+                        elapsed_model = max(time.time() - model_t0, 1.0e-6)
+                        model_rate = eff_blocks / elapsed_model
+                        model_eta = max(total_planned_blocks - eff_blocks, 0.0) / max(model_rate, 1.0e-6)
+                        el_q3 = max(time.time() - t_q3_start, 1.0e-6)
+                        r_q3 = done_q3_blks / el_q3
+                        eta_q3 = (t_blocks_q3 - done_q3_blks) / max(r_q3, 1.0e-6)
+                        stage_callback(
+                            idx + 1,
+                            len(out_infos),
+                            ti,
+                            {
+                                "phase": "Q3_K: Analog + WLS + Sieve/Viterbi + FP16-ULP Quantization",
+                                "done": done_q3_blks,
+                                "total": t_blocks_q3,
+                                "detail": f"blk {done_q3_blks:,}/{t_blocks_q3:,} ({r_q3:.0f} blk/s) rmse={chunk_rmse:.6e}",
+                                "rate": r_q3,
+                                "eta": eta_q3,
+                                "rmse": chunk_rmse,
+                                "sigma": float(np.sqrt(np.mean(x_chunk.astype(np.float64) ** 2))),
+                                "model_pct": 100.0 * eff_blocks / max(total_planned_blocks, 1),
+                                "model_eta": model_eta,
+                                "model_done_blocks": int(eff_blocks),
+                                "model_total_blocks": total_planned_blocks,
+                            },
+                        )
+
+                if written_bytes != out_size:
+                    raise RuntimeError(f"{ti.name}: Q3_K payload size mismatch")
+                completed_planned_blocks += eff_tb
+                q3_rmse = float(np.sqrt(sse_q3 / ti.n_elements))
+                total_rmse += sse_q3
+                total_elements += ti.n_elements
+                total_quantized += 1
+                total_q3k += 1
+                if verbose:
+                    print(
+                        f"  Q3_K {ti.name:48s} row={ti.row_width:6d} "
+                        f"rmse={q3_rmse:.6e} imatrix={'yes' if has_imat else 'no'}"
+                    )
+                if progress_callback is not None:
+                    progress_callback(
+                        idx + 1,
+                        len(out_infos),
+                        ti.name,
+                        "Q3_K",
+                        q3_rmse,
+                        has_imat,
+                    )
             elif fmt == "Q4_0":
                 t_blocks_q4 = ti.n_elements // QK4_0
                 eff_tb = max(1, t_blocks_q4 // 8)
@@ -1105,57 +1176,9 @@ def write_quantized_gguf(
         "tensors": float(len(out_infos)),
         "quantized": float(total_quantized),
         "q2_k": float(total_q2k),
+        "q3_k": float(total_q3k),
         "q4_0": float(total_q4_0),
         "q1_0": float(total_q1_0),
         "elements": float(total_elements),
         "rmse": rmse,
     }
-
-
-def estimate_gguf_size(
-    reader: GGUFReader,
-    *,
-    enable_q4_fallback: bool = True,
-    quantize_embd_q4: bool = True,
-    promote_attn_q4: bool = False,
-    quant_format: str = "mixed",
-    custom_quant_map: dict[str, str] | None = None,
-) -> int:
-    """Return the projected byte size of a full-model quantized GGUF."""
-    plan: list[tuple[TensorInfo, str | None]] = []
-    for ti in reader.tensors:
-        tgt = target_quant_type(
-            ti.name,
-            ti.dims,
-            enable_q4_fallback=enable_q4_fallback,
-            quantize_embd_q4=quantize_embd_q4,
-            promote_attn_q4=promote_attn_q4,
-            quant_format=quant_format,
-            source_type=ti.type,
-            custom_quant_map=custom_quant_map,
-        )
-        if tgt is not None and ti.type not in SUPPORTED_READ_TYPES:
-            tgt = None
-        plan.append((ti, tgt))
-
-    header = 24
-    for key, _vtype, raw in reader.kv_pairs:
-        header += 8 + len(key.encode("utf-8")) + 4 + len(raw)
-    for ti, _tgt in plan:
-        header += 8 + len(ti.name.encode("utf-8")) + 4 + 8 * len(ti.dims) + 4 + 8
-    data_start = _align(header, reader.alignment)
-
-    offset = 0
-    final_end = data_start
-    for ti, tgt in plan:
-        if tgt == "Q2_K":
-            out_size = (ti.n_elements // QK_K) * 84
-        elif tgt == "Q4_0":
-            out_size = (ti.n_elements // QK4_0) * Q4_0_BLOCK_BYTES
-        elif tgt == "Q1_0":
-            out_size = (ti.n_elements // QK1_0) * Q1_0_BLOCK_BYTES
-        else:
-            out_size = ti.n_bytes
-        final_end = data_start + offset + out_size
-        offset = _align(offset + out_size, reader.alignment)
-    return final_end

gui.py

@@ -49,23 +49,30 @@ if not (_HERE / "hpc_quantize_v2").is_dir() and (_HERE / "__init__.py").is_file(
 from hpc_quantize_v2 import (
     GGUFReader,
     HPCConfig,
+    Q1_0_BLOCK_BYTES,
     Q2KQuantizer,
+    Q3_K_BLOCK_BYTES,
+    QK1_0,
+    QK3_K,
+    QK4_0,
+    QK_K,
     cuda_device_name,
     cuda_is_available,
     dequantize_q1_0_bytes,
+    dequantize_q3_k_bytes,
     dequantize_q4_0_bytes,
     expand_importance,
     factor_only_solve,
     lookup_imatrix,
     quantize_tensor_q1_0,
+    quantize_tensor_q3_k,
     quantize_tensor_q4_0,
     read_imatrix,
 )
 from hpc_quantize_v2.gguf import (
-    SUPPORTED_READ_TYPES,
-    estimate_gguf_size,
     is_q1_0_eligible,
     is_q2k_eligible,
+    is_q3_k_eligible,
     is_q4_0_eligible,
     target_quant_type,
     tensor_type_key,
@@ -116,7 +123,7 @@ def _fmt_eta(seconds: float) -> str:
 class HPCQuantizeGUI:
     def __init__(self, root: tk.Tk) -> None:
         self.root = root
-        self.root.title("HPC-Quantize V2 — Factored Q1_0 / Q2_K / Q4_0 & Geometry-Preserving Analog Engine")
+        self.root.title("HPC-Quantize V2 — Factored Q1_0 / Q2_K / Q3_K / Q4_0 & Geometry-Preserving Analog Engine")
         self.root.geometry("1260x900")
         self.root.minsize(1040, 740)
 
@@ -176,7 +183,6 @@ class HPCQuantizeGUI:
         self.sse_budget_var = tk.DoubleVar(value=0.0005)
 
         self.cli_preview_var = tk.StringVar()
-        self.custom_size_var = tk.StringVar(value="Projected GGUF size: load a source GGUF")
         self.status_var = tk.StringVar(value="Ready.")
         self.model_progress_var = tk.DoubleVar(value=0.0)
         self.tensor_progress_var = tk.DoubleVar(value=0.0)
@@ -314,7 +320,7 @@ class HPCQuantizeGUI:
         mid.add(right_pane, weight=3)
 
         # Left: Engine & Factorization Options
-        opt_frame = ttk.LabelFrame(left_pane, text="2. Factored Q1_0 / Q2_K / Q4_0 & Analog Controls", padding=8)
+        opt_frame = ttk.LabelFrame(left_pane, text="2. Factored Q1_0 / Q2_K / Q3_K / Q4_0 & Analog Controls", padding=8)
         opt_frame.pack(fill=tk.BOTH, expand=True, padx=(0, 6))
 
         mode_row = ttk.Frame(opt_frame)
@@ -335,6 +341,7 @@ class HPCQuantizeGUI:
             ("Mixed Q1_0 + Q4_0", "mixed_q1"),
             ("Pure Q1_0 (1.125 bpw)", "q1_0"),
             ("Pure Q2_K (2.625 bpw)", "q2_k"),
+            ("Pure Q3_K (3.438 bpw)", "q3_k"),
             ("Pure Q4_0 (4.500 bpw)", "q4_0"),
         ):
             ttk.Radiobutton(
@@ -366,9 +373,6 @@ class HPCQuantizeGUI:
         ttk.Label(
             self.custom_frame, textvariable=self.custom_hint_var, style="TeleKey.TLabel"
         ).pack(anchor=tk.W, pady=(4, 0))
-        ttk.Label(
-            self.custom_frame, textvariable=self.custom_size_var
-        ).pack(anchor=tk.W, pady=(2, 0))
 
         opt_row = ttk.Frame(opt_frame)
         opt_row.pack(fill=tk.X, pady=(0, 4))
@@ -473,7 +477,7 @@ class HPCQuantizeGUI:
         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())
-        for label, val in (("All", "ALL"), ("Q1_0", "Q1_0"), ("Q2_K", "Q2_K"), ("Q4_0", "Q4_0"), ("Copy", "COPY")):
+        for label, val in (("All", "ALL"), ("Q1_0", "Q1_0"), ("Q2_K", "Q2_K"), ("Q3_K", "Q3_K"), ("Q4_0", "Q4_0"), ("Copy", "COPY")):
             ttk.Radiobutton(
                 search_row,
                 text=label,
@@ -496,6 +500,7 @@ class HPCQuantizeGUI:
         self.tree.heading("state", text="Live Status / RMSE")
         self.tree.tag_configure("Q1_0", foreground="#fbbf24")
         self.tree.tag_configure("Q2_K", foreground="#93c5fd")
+        self.tree.tag_configure("Q3_K", foreground="#c4b5fd")
         self.tree.tag_configure("Q4_0", foreground="#34d399")
         self.tree.tag_configure("Copy", foreground="#9ca3af")
 
@@ -629,6 +634,8 @@ class HPCQuantizeGUI:
             return "-Q1_0-Q4_0.gguf"
         if fmt == "custom":
             return "-Custom.gguf"
+        if fmt == "q3_k":
+            return "-Q3_K.gguf"
         if fmt == "q4_0":
             return "-Q4_0.gguf"
         return "-Q2K.gguf"
@@ -640,7 +647,7 @@ class HPCQuantizeGUI:
             not cur_out
             or any(
                 cur_out.endswith(sfx)
-                for sfx in ("-Q2K.gguf", "-Q1_0.gguf", "-Q1_0-Q4_0.gguf", "-Custom.gguf", "-Q4_0.gguf")
+                for sfx in ("-Q2K.gguf", "-Q3_K.gguf", "-Q1_0.gguf", "-Q1_0-Q4_0.gguf", "-Custom.gguf", "-Q4_0.gguf")
             )
         ):
             p = Path(gguf_p)
@@ -689,6 +696,8 @@ class HPCQuantizeGUI:
                 options.append("Q1_0")
             if any(is_q2k_eligible(t.name, t.dims) for t in tensors):
                 options.append("Q2_K")
+            if any(is_q3_k_eligible(t.name, t.dims) for t in tensors):
+                options.append("Q3_K")
             if any(
                 is_q4_0_eligible(t.name, t.dims, include_embd=True, allow_q2k_tensors=True)
                 for t in tensors
@@ -719,20 +728,10 @@ class HPCQuantizeGUI:
             ).grid(row=r, column=c * 2 + 1, sticky=tk.W, padx=(0, 12), pady=1)
             rows += 1
 
-        hint = (
+        self.custom_hint_var.set(
             "Quantizable tensor types only; norms/1D tensors and other non-eligible "
             "weights are copied unchanged."
         )
-        unsupported = sorted(
-            {ti.type_name for ti in self._reader.tensors if ti.type not in SUPPORTED_READ_TYPES}
-        )
-        if unsupported:
-            hint += (
-                " Copy-only source formats (cannot down-quantize): "
-                + ", ".join(unsupported)
-                + "."
-            )
-        self.custom_hint_var.set(hint)
         self._update_cli_preview()
 
     def _on_custom_type_changed(self) -> None:
@@ -795,7 +794,7 @@ class HPCQuantizeGUI:
             sse_budget=float(self.sse_budget_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() != "q2_k",
+            enable_q4_fallback=bool(self.q4_fallback_var.get()) and self.quant_format_var.get() not in ("q2_k", "q3_k"),
             quantize_embd_q4=bool(self.embd_q4_var.get()),
             promote_attn_q4=bool(self.promote_attn_q4_var.get()),
             device=self.device_var.get(),
@@ -848,31 +847,6 @@ class HPCQuantizeGUI:
             self.cli_preview_var.set(self.build_cli_command())
         except Exception:
             pass
-        self._update_projected_size()
-
-    def _update_projected_size(self) -> None:
-        if self.quant_format_var.get() != "custom":
-            self.custom_size_var.set("Projected GGUF size: switch to Custom mode")
-            return
-        if self._reader is None:
-            self.custom_size_var.set("Projected GGUF size: load a source GGUF")
-            return
-        try:
-            size = estimate_gguf_size(
-                self._reader,
-                enable_q4_fallback=bool(self.q4_fallback_var.get())
-                and self.quant_format_var.get() != "q2_k",
-                quantize_embd_q4=bool(self.embd_q4_var.get()),
-                promote_attn_q4=bool(self.promote_attn_q4_var.get()),
-                quant_format=self.quant_format_var.get(),
-                custom_quant_map=self._custom_map_for_plan(),
-            )
-        except Exception as exc:
-            self.custom_size_var.set(f"Projected GGUF size: unavailable ({exc})")
-            return
-        self.custom_size_var.set(
-            f"Projected GGUF size: {size / 1024**3:.2f} GiB ({size / 1e9:.2f} GB)"
-        )
 
     def _copy_cli(self) -> None:
         cmd = self.cli_preview_var.get()
@@ -910,24 +884,24 @@ class HPCQuantizeGUI:
             return
         filt = self.filter_var.get().strip().lower()
         plan_filt = self.plan_filter_var.get()
-        n_q2, n_q4, n_copy = 0, 0, 0
+        n_q2, n_q3, n_q4, n_copy = 0, 0, 0, 0
         n_q1 = 0
+        planned_bytes = 0
         for ti in self._reader.tensors:
-            requested_tgt = target_quant_type(
+            tgt = target_quant_type(
                 ti.name,
                 ti.dims,
-                enable_q4_fallback=bool(self.q4_fallback_var.get()) and self.quant_format_var.get() != "q2_k",
+                enable_q4_fallback=bool(self.q4_fallback_var.get()) and self.quant_format_var.get() not in ("q2_k", "q3_k"),
                 quantize_embd_q4=bool(self.embd_q4_var.get()),
                 promote_attn_q4=bool(self.promote_attn_q4_var.get()),
                 quant_format=self.quant_format_var.get(),
                 source_type=ti.type,
                 custom_quant_map=self._custom_map_for_plan(),
             )
-            tgt = requested_tgt
-            if tgt is not None and ti.type not in SUPPORTED_READ_TYPES:
-                tgt = None
             if tgt == "Q2_K":
                 n_q2 += 1
+            elif tgt == "Q3_K":
+                n_q3 += 1
             elif tgt == "Q4_0":
                 n_q4 += 1
             elif tgt == "Q1_0":
@@ -935,6 +909,17 @@ class HPCQuantizeGUI:
             else:
                 n_copy += 1
 
+            if tgt == "Q2_K":
+                planned_bytes += (ti.n_elements // QK_K) * 84
+            elif tgt == "Q3_K":
+                planned_bytes += (ti.n_elements // QK3_K) * Q3_K_BLOCK_BYTES
+            elif tgt == "Q4_0":
+                planned_bytes += (ti.n_elements // QK4_0) * 18
+            elif tgt == "Q1_0":
+                planned_bytes += (ti.n_elements // QK1_0) * Q1_0_BLOCK_BYTES
+            else:
+                planned_bytes += ti.n_bytes
+
             tgt_label = tgt if tgt else "Copy"
             if plan_filt != "ALL" and tgt_label.upper() != plan_filt:
                 continue
@@ -949,14 +934,11 @@ class HPCQuantizeGUI:
                 self._imatrix is not None
                 and lookup_imatrix(self._imatrix, ti.name) is not None
             )
-            if tgt:
-                state_str = f"Pending ({tgt_label})"
-            elif requested_tgt:
-                state_str = f"Copy {ti.type_name} (cannot dequantize for {requested_tgt})"
-            elif ti.type_name in ("Q1_0", "Q2_K", "Q4_0"):
-                state_str = f"Keep {ti.type_name} (<= target)"
-            else:
-                state_str = "Passthrough"
+            state_str = (
+                f"Pending ({tgt_label})"
+                if tgt
+                else (f"Keep {ti.type_name} (<= target)" if ti.type_name in ("Q1_0", "Q2_K", "Q3_K", "Q4_0") else "Passthrough")
+            )
             self.tree.insert(
                 "",
                 tk.END,
@@ -972,8 +954,15 @@ class HPCQuantizeGUI:
                     state_str,
                 ),
             )
+        if planned_bytes >= 1024 ** 3:
+            planned_text = f"{planned_bytes / (1024 ** 3):.2f} GiB"
+        elif planned_bytes >= 1024 ** 2:
+            planned_text = f"{planned_bytes / (1024 ** 2):.1f} MiB"
+        else:
+            planned_text = f"{planned_bytes / 1024:.1f} KiB"
         self.status_var.set(
-            f"Plan ({self.quant_format_var.get().upper()}): {n_q1} Q1_0 | {n_q2} Q2_K | {n_q4} Q4_0 | {n_copy} Copy (Total: {len(self._reader.tensors)} tensors)"
+            f"Plan ({self.quant_format_var.get().upper()}): {n_q1} Q1_0 | {n_q2} Q2_K | {n_q3} Q3_K | {n_q4} Q4_0 | {n_copy} Copy "
+            f"(Total: {len(self._reader.tensors)} tensors, est. {planned_text})"
         )
 
     def _select_all_eligible(self) -> None:
@@ -985,7 +974,7 @@ class HPCQuantizeGUI:
             if target_quant_type(
                 ti.name,
                 ti.dims,
-                enable_q4_fallback=bool(self.q4_fallback_var.get()) and self.quant_format_var.get() != "q2_k",
+                enable_q4_fallback=bool(self.q4_fallback_var.get()) and self.quant_format_var.get() not in ("q2_k", "q3_k"),
                 quantize_embd_q4=bool(self.embd_q4_var.get()),
                 promote_attn_q4=bool(self.promote_attn_q4_var.get()),
                 quant_format=self.quant_format_var.get(),
@@ -993,7 +982,6 @@ class HPCQuantizeGUI:
                 custom_quant_map=self._custom_map_for_plan(),
             )
             is not None
-            and ti.type in SUPPORTED_READ_TYPES
             and self.tree.exists(ti.name)
         ]
         self.tree.selection_set(eligible_ids)
@@ -1077,10 +1065,6 @@ class HPCQuantizeGUI:
                 reader = GGUFReader(gguf_path)
                 tname = next(iter(selected))
                 ti = reader.info(tname)
-                if ti.type not in SUPPORTED_READ_TYPES:
-                    raise ValueError(
-                        f"{tname}: cannot dequantize source type {ti.type_name} for .npz export"
-                    )
                 x, row = reader.read_tensor(tname)
                 imp = None
                 if imat is not None:
@@ -1109,6 +1093,18 @@ class HPCQuantizeGUI:
                         ("done", f"Saved Q1_0 {out_path} (RMSE={rmse_q1:.6e}, {time.time() - t0:.1f}s)")
                     )
                     return
+                if tgt == "Q3_K":
+                    raw_q3, nb_q3, rmse_q3 = quantize_tensor_q3_k(x, importance=imp, cfg=cfg)
+                    np.savez_compressed(
+                        out_path,
+                        q3_k_bytes=np.frombuffer(raw_q3, dtype=np.uint8),
+                        dequantized=dequantize_q3_k_bytes(raw_q3, nb_q3),
+                        rmse=np.float32(rmse_q3),
+                    )
+                    self._log_queue.put(
+                        ("done", f"Saved Q3_K {out_path} (RMSE={rmse_q3:.6e}, {time.time() - t0:.1f}s)")
+                    )
+                    return
                 if tgt == "Q4_0":
                     raw_q4, nb_q4, rmse_q4 = quantize_tensor_q4_0(x, importance=imp, cfg=cfg)
                     np.savez_compressed(
@@ -1166,7 +1162,8 @@ class HPCQuantizeGUI:
             self._log_queue.put(
                 (
                     "done",
-                    f"Wrote {out_path}: {int(stats.get('q1_0', 0))} Q1_0 + {int(stats.get('q2_k', 0))} Q2_K + {int(stats.get('q4_0', 0))} Q4_0 "
+                    f"Wrote {out_path}: {int(stats.get('q1_0', 0))} Q1_0 + {int(stats.get('q2_k', 0))} Q2_K + "
+                    f"{int(stats.get('q3_k', 0))} Q3_K + {int(stats.get('q4_0', 0))} Q4_0 "
                     f"({int(stats['quantized'])}/{int(stats['tensors'])} tensors), "
                     f"overall RMSE={stats['rmse']:.6e} ({dt_sec:.1f}s)",
                 )
@@ -1310,7 +1307,7 @@ class HPCQuantizeGUI:
                 done, total, name, action, rmse, has_imat = payload  # type: ignore[misc]
                 self.model_progress_var.set(100.0 * done / max(total, 1))
                 self.tensor_progress_var.set(100.0)
-                if action in ("Q1_0", "Q2_K", "Q4_0") and rmse is not None:
+                if action in ("Q1_0", "Q2_K", "Q3_K", "Q4_0") and rmse is not None:
                     self._update_tree_row_state(name, f"{action} (RMSE={rmse:.4e})")
                     self._log(
                         f"[{done}/{total}] FINISHED {name:42s} -> {action} RMSE={rmse:.6e} (iMatrix={'yes' if has_imat else 'no'})"

q3_k.py

@@ -0,0 +1,715 @@
+"""Full HPC V2 Q3_K quantizer.
+
+Implements the HPC-Quantize V2 decision stack for llama.cpp/GGML ``Q3_K``
+(256 weights per 110-byte block = 3.4375 bpw):
+
+1. **Geometry-Preserving Analog + WLS Seeds**:
+   Finds an optimal signed scale from the raw weights and an iso-moment
+   companded analog for every 16-weight sub-block.
+2. **24-Candidate Scale Lattice & Extended Spectral Objective**:
+   Evaluates 24 scale multipliers (mapped to 6 symbolic quhit states) on
+   importance-weighted SSE + D6/Vesica fold pyramid + DC penalty, including
+   negative-scale sign-flip candidates.
+3. **6-State Sequential Sieve & 6-State Viterbi DP**:
+   Runs the 6-state sequential Sieve with parity back-action and a 6-state
+   Viterbi dynamic program across the sub-block chain.
+4. **Asymmetric Sign-Flip fp16-ULP Polish & Closed-Form Vesica/DC Shaping**:
+   Polishes each sub-block scale over ``+/-8`` fp16 ULPs, then jointly fits the
+   GGML super-scale ``d`` and signed 6-bit sub-block scales ``sc``.  The final
+   3-bit codes ``[-4, +3]`` are emitted in the exact ``block_q3_K`` layout.
+"""
+
+from __future__ import annotations
+
+from math import ceil
+import numpy as np
+
+try:
+    import torch
+except ImportError:  # pragma: no cover
+    torch = None  # type: ignore[assignment]
+
+from .config import HPCConfig
+from .cuda_backend import cuda_is_available
+from .factored import MULTS_D
+from .fp16 import from_fp16_bits, nearest_int, to_fp16_bits
+from .sieve import sieve_measure_chain, subblock_chain_edges
+from .viterbi import robust_temperature
+
+QK3_K = 256
+Q3_K_BLOCK_BYTES = 110
+Q3_K_SUBBLOCK = 16
+Q3_K_N_SUBBLOCKS = QK3_K // Q3_K_SUBBLOCK
+Q3_N_CAND = 24
+Q3_N_STATES = 6
+
+
+def _nearest_int_t(value):
+    """GGML round-to-nearest-even for torch tensors."""
+    shifted = value + 12582912.0
+    return (shifted.view(torch.int32) & 0x007FFFFF) - 0x00400000
+
+
+def _unpack_q3_k_scales(scales: np.ndarray) -> np.ndarray:
+    """Decode the 12-byte GGML Q3_K scale field into signed values [-32, 31]."""
+    scales = np.asarray(scales, dtype=np.uint8)
+    B = scales.shape[0]
+    vals = np.empty((B, Q3_K_N_SUBBLOCKS), dtype=np.uint8)
+    for j in range(8):
+        vals[:, j] = scales[:, j] & np.uint8(0x0F)
+        vals[:, j + 8] = scales[:, j] >> np.uint8(4)
+    for j in range(Q3_K_N_SUBBLOCKS):
+        hi = (scales[:, 8 + (j % 4)] >> np.uint8(2 * (j // 4))) & np.uint8(0x03)
+        vals[:, j] |= hi << np.uint8(4)
+    return vals.astype(np.int16) - 32
+
+
+def _pack_q3_k_scales(scales: np.ndarray) -> np.ndarray:
+    """Encode signed 6-bit scales [-32, 31] into the 12-byte GGML field."""
+    sc = np.asarray(scales, dtype=np.int16).reshape(-1, Q3_K_N_SUBBLOCKS)
+    B = sc.shape[0]
+    vals = np.clip(sc + 32, 0, 63).astype(np.uint8)
+    out = np.zeros((B, 12), dtype=np.uint8)
+    for j in range(8):
+        out[:, j] = vals[:, j] & np.uint8(0x0F)
+        out[:, j] |= (vals[:, j + 8] & np.uint8(0x0F)) << np.uint8(4)
+    for j in range(Q3_K_N_SUBBLOCKS):
+        hi = (vals[:, j] >> np.uint8(4)) & np.uint8(0x03)
+        out[:, 8 + (j % 4)] |= hi << np.uint8(2 * (j // 4))
+    return out
+
+
+def _pack_q3_k_codes(codes: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+    """Pack signed 3-bit codes [-4, 3] into GGML hmask[32] + qs[64]."""
+    c = np.asarray(codes, dtype=np.int16).reshape(-1, QK3_K)
+    B = c.shape[0]
+    low = (c & 3).astype(np.uint8)
+    hmask = np.zeros((B, QK3_K // 8), dtype=np.uint8)
+    high = c >= 0
+    for bit in range(8):
+        group = high[:, bit * 32 : (bit + 1) * 32]
+        hmask |= group.astype(np.uint8) << np.uint8(bit)
+    qs = np.empty((B, QK3_K // 4), dtype=np.uint8)
+    qs[:, :32] = (
+        low[:, 0:32]
+        | (low[:, 32:64] << np.uint8(2))
+        | (low[:, 64:96] << np.uint8(4))
+        | (low[:, 96:128] << np.uint8(6))
+    )
+    qs[:, 32:] = (
+        low[:, 128:160]
+        | (low[:, 160:192] << np.uint8(2))
+        | (low[:, 192:224] << np.uint8(4))
+        | (low[:, 224:256] << np.uint8(6))
+    )
+    return hmask, qs
+
+
+def dequantize_q3_k_bytes(raw: bytes | np.ndarray, n_blocks: int) -> np.ndarray:
+    """Decode GGML Q3_K blocks into float32 weights."""
+    blocks = np.frombuffer(raw, dtype=np.uint8).reshape(n_blocks, Q3_K_BLOCK_BYTES)
+    hmask = blocks[:, : QK3_K // 8]
+    qs = blocks[:, QK3_K // 8 : QK3_K // 8 + QK3_K // 4]
+    sc = _unpack_q3_k_scales(blocks[:, QK3_K // 8 + QK3_K // 4 : Q3_K_BLOCK_BYTES - 2])
+    d = blocks[:, Q3_K_BLOCK_BYTES - 2 :].copy().view("<f2").reshape(n_blocks, 1)
+
+    out = np.empty((n_blocks, QK3_K), dtype=np.float32)
+    for sb in range(Q3_K_N_SUBBLOCKS):
+        group = sb // 2
+        l0 = (sb % 2) * 16
+        l = np.arange(l0, l0 + 16)
+        shift = np.uint8(2 * (group % 4))
+        qoff = 0 if group < 4 else 32
+        low = (qs[:, qoff + l] >> shift) & np.uint8(0x03)
+        high = (hmask[:, l] >> np.uint8(group)) & np.uint8(0x01)
+        code = low.astype(np.int16) - np.where(high != 0, 0, 4).astype(np.int16)
+        scale = d * sc[:, sb : sb + 1].astype(np.float32)
+        out[:, sb * 16 : (sb + 1) * 16] = scale * code.astype(np.float32)
+    return out.reshape(-1)
+
+
+def _q3_sieve_and_viterbi(cand_errors: np.ndarray, cfg: HPCConfig) -> np.ndarray:
+    """6-state sequential Sieve + 6-state Viterbi DP over a Q3 candidate lattice."""
+    B = cand_errors.shape[0]
+    if cfg.optimizer != "hpc" or B < 2:
+        return np.argmin(cand_errors, axis=1).astype(np.int64)
+
+    max_gb = min(int(cfg.graph_max_blocks), 512)
+    stride = max(1, ceil(B / max_gb))
+    gb = ceil(B / stride)
+    temp = max(float(robust_temperature(cand_errors, cfg)), 1.0e-12)
+
+    pad = gb * stride - B
+    ce = cand_errors.astype(np.float64)
+    if pad > 0:
+        ce = np.concatenate([ce, np.full((pad, Q3_N_CAND), np.inf, dtype=np.float64)], axis=0)
+    ce_grouped = ce.reshape(gb, stride, Q3_N_STATES, 4)
+
+    group_min = np.min(ce_grouped, axis=(1, 3))
+    finite = np.isfinite(ce_grouped)
+    counts = np.sum(finite, axis=(1, 3))
+    valid = (counts > 0) & np.isfinite(group_min)
+    gm_b = np.where(np.isfinite(group_min), group_min, 0.0)[:, None, :, None]
+    shifted = np.where(finite, (ce_grouped - gm_b) / (2.0 * temp), np.inf)
+    sums = np.sum(np.exp(-shifted), axis=(1, 3))
+    mean_exp = np.maximum(sums / np.maximum(counts, 1), 1.0e-300)
+    bin_err = np.where(valid, group_min - 2.0 * temp * np.log(mean_exp), np.inf)
+
+    agg = np.mean(np.where(finite, ce_grouped, 0.0), axis=1).reshape(gb, Q3_N_CAND)
+    mn = np.min(agg, axis=1, keepdims=True)
+    coeff = np.exp(-np.clip((agg - mn) / (2.0 * temp), 0.0, 80.0)).reshape(gb, Q3_N_STATES, 4)
+    amps = np.sum(coeff, axis=2)
+    norms = np.linalg.norm(amps, axis=1, keepdims=True)
+    amps = np.where(norms > 1.0e-30, amps / np.maximum(norms, 1.0e-30), 1.0 / np.sqrt(6.0))
+
+    marg, _ = sieve_measure_chain(
+        amps,
+        subblock_chain_edges(gb),
+        same_penalty=cfg.same_penalty,
+        log_slack=cfg.log_slack,
+        deterministic=True,
+    )
+    m_tot = np.sum(marg, axis=1, keepdims=True)
+    pm = np.where(m_tot > 1.0e-30, marg / np.maximum(m_tot, 1.0e-30), 1.0 / 6.0)
+    log_prior = np.log(pm + 1.0e-30)
+
+    fin_err = bin_err[np.isfinite(bin_err)]
+    scale_err = max(float(fin_err.mean()) if fin_err.size else 1.0e-10, 1.0e-20)
+    local = np.where(np.isfinite(bin_err), bin_err - cfg.viterbi_beta * scale_err * log_prior, np.inf)
+
+    states = np.arange(Q3_N_STATES)
+    trans = cfg.viterbi_alpha * scale_err * np.abs(states[None, :] - states[:, None])
+    dp = np.full((gb, Q3_N_STATES), np.inf, dtype=np.float64)
+    back = np.zeros((gb, Q3_N_STATES), dtype=np.int64)
+    dp[0] = local[0]
+    for gi in range(1, gb):
+        totals = dp[gi - 1][:, None] + trans
+        best_sp = np.argmin(totals, axis=0)
+        best_val = totals[best_sp, states]
+        dp[gi] = np.where(np.isfinite(best_val), best_val + local[gi], np.inf)
+        back[gi] = best_sp
+
+    path = np.zeros(gb, dtype=np.int64)
+    if np.any(np.isfinite(dp[-1])):
+        path[-1] = int(np.argmin(dp[-1]))
+        for gi in range(gb - 2, -1, -1):
+            path[gi] = back[gi + 1, path[gi + 1]]
+
+    ce_bins = cand_errors.reshape(B, Q3_N_STATES, 4)
+    bin_local_arg = np.argmin(ce_bins, axis=2)
+    blk_gi = np.arange(B) // stride
+    chosen_bin = path[blk_gi]
+    chosen_cand = chosen_bin * 4 + bin_local_arg[np.arange(B), chosen_bin]
+
+    global_best = np.argmin(cand_errors, axis=1).astype(np.int64)
+    cur_e = cand_errors[np.arange(B), chosen_cand]
+    g_e = cand_errors[np.arange(B), global_best]
+    return np.where(g_e < cur_e * cfg.greedy_override_ratio, global_best, chosen_cand)
+
+
+def _subblock_scales_hpc(
+    X: np.ndarray, W: np.ndarray, cfg: HPCConfig
+) -> np.ndarray:
+    """Run the HPC 3-bit pipeline on (M, 16) sub-blocks and return signed scales."""
+    M = X.shape[0]
+    X_f32 = X.astype(np.float32)
+    W_f32 = W.astype(np.float32)
+    lam_dc = (float(cfg.dc_lambda) / Q3_K_SUBBLOCK) if cfg.use_spectral else 0.0
+    lam_vw = (float(cfg.vw_lambda) / Q3_K_SUBBLOCK) if cfg.use_spectral else 0.0
+    half = Q3_K_SUBBLOCK // 2
+
+    amax = np.max(np.abs(X_f32), axis=1)
+    d_range = amax / 3.5
+    wsum = np.maximum(np.sum(W_f32, axis=1, keepdims=True), 1.0e-30)
+    mu = np.sum(W_f32 * X_f32, axis=1, keepdims=True) / wsum
+    var = np.sum(W_f32 * (X_f32 - mu) ** 2, axis=1, keepdims=True) / wsum
+    sig = np.sqrt(np.maximum(var, 1.0e-30))
+    x_comp = mu + sig * 1.85 * np.tanh((X_f32 - mu) / (1.85 * sig))
+    d_analog = np.max(np.abs(x_comp), axis=1).astype(np.float32) / 3.5
+
+    wls_d = d_range.copy()
+    best_seed_sse = np.full(M, np.inf, dtype=np.float64)
+    for d_start in (d_range, -d_range, d_analog, -d_analog):
+        d = d_start.astype(np.float64)
+        for _ in range(4):
+            act = np.abs(d) > 1.0e-15
+            sd = np.where(act, d, 1.0)[:, None]
+            q = np.where(act[:, None], np.clip(nearest_int((X_f32 / sd).astype(np.float32)) + 4, 0, 7), 4)
+            c = (q - 4).astype(np.float64)
+            num = np.sum(W_f32 * X_f32 * c, axis=1, dtype=np.float64)
+            den = np.sum(W_f32 * c * c, axis=1, dtype=np.float64)
+            valid = den > 1.0e-30
+            d = np.where(valid, num / np.where(valid, den, 1.0), 0.0)
+        df = from_fp16_bits(to_fp16_bits(d.astype(np.float32)))
+        act = np.abs(df) > 1.0e-15
+        sdf = np.where(act, df, 1.0)[:, None]
+        q = np.where(act[:, None], np.clip(nearest_int(X_f32 / sdf) + 4, 0, 7), 4)
+        e = X_f32 - df[:, None] * (q.astype(np.float32) - 4.0)
+        sse = np.sum(W_f32 * e * e, axis=1, dtype=np.float64)
+        take = sse < best_seed_sse
+        best_seed_sse = np.where(take, sse, best_seed_sse)
+        wls_d = np.where(take, df, wls_d)
+
+    cand_d16 = to_fp16_bits(wls_d[:, None] * MULTS_D[None, :])
+    cand_d = from_fp16_bits(cand_d16)
+    act_c = np.abs(cand_d) > 1.0e-15
+    sd_c = np.where(act_c, cand_d, 1.0)[:, :, None]
+    q_c = np.where(
+        act_c[:, :, None],
+        np.clip(nearest_int(X_f32[:, None, :] / sd_c) + 4, 0, 7),
+        4,
+    ).astype(np.float32)
+    e_c = X_f32[:, None, :] - cand_d[:, :, None] * (q_c - 4.0)
+    sse_c = np.sum(W_f32[:, None, :] * e_c * e_c, axis=2)
+    if cfg.use_spectral and (lam_dc > 0.0 or lam_vw > 0.0):
+        v_c = e_c[:, :, :half] + e_c[:, :, half:]
+        dc_c = np.sum(e_c, axis=2)
+        cand_errors = (sse_c + lam_vw * np.sum(v_c * v_c, axis=2) + lam_dc * dc_c * dc_c).astype(np.float32)
+    else:
+        cand_errors = sse_c.astype(np.float32)
+
+    best_cand = _q3_sieve_and_viterbi(cand_errors, cfg)
+    rows = np.arange(M)
+    d_sel = cand_d[rows, best_cand]
+
+    rad = max(int(cfg.ulp_radius), 4)
+    deltas = np.arange(-rad, rad + 1, dtype=np.int32)
+    pos_b = np.clip(to_fp16_bits(np.abs(d_sel)).astype(np.int32)[:, None] + deltas[None, :], 0, 0x7BFF).astype(np.uint16)
+    neg_b = (pos_b | np.uint16(0x8000)).astype(np.uint16)
+    all_b = np.concatenate([pos_b, neg_b], axis=1)
+    all_d = from_fp16_bits(all_b)
+    act_u = np.abs(all_d) > 1.0e-15
+    sd_u = np.where(act_u, all_d, 1.0)[:, :, None]
+    q_u = np.where(
+        act_u[:, :, None],
+        np.clip(nearest_int(X_f32[:, None, :] / sd_u) + 4, 0, 7),
+        4,
+    ).astype(np.uint8)
+    e_u = X_f32[:, None, :] - all_d[:, :, None] * (q_u.astype(np.float32) - 4.0)
+    sse_u = np.sum(W_f32[:, None, :] * e_u * e_u, axis=2, dtype=np.float64)
+    pick_u = np.argmin(sse_u, axis=1)
+    best_d = all_d[rows, pick_u]
+    best_q = q_u[rows, pick_u].astype(np.int64)
+
+    if cfg.use_spectral and (lam_vw > 0.0 or lam_dc > 0.0):
+        c_f = (best_q - 4).astype(np.float64)
+        e = X_f32.astype(np.float64) - best_d[:, None].astype(np.float64) * c_f
+        sse_live = np.sum(W_f32 * e * e, axis=1, dtype=np.float64)
+        sse_cap = sse_live * (1.0 + cfg.sse_budget)
+        v = e[:, :half] + e[:, half:]
+        dc = np.sum(e, axis=1)
+        d_f64 = best_d.astype(np.float64)[:, None]
+        denom = (W_f32 + lam_vw + lam_dc) * (d_f64 * d_f64)
+        act_b = np.abs(d_f64) > 1.0e-15
+        s_den = np.where(act_b & (denom > 1.0e-30), denom, 1.0)
+        v_full = np.concatenate([v, v], axis=1)
+        grad = d_f64 * (W_f32 * e + lam_vw * v_full + lam_dc * dc[:, None])
+        dq = np.where(act_b, nearest_int((grad / s_den).astype(np.float32)), 0)
+        q_new = np.clip(best_q + dq, 0, 7)
+        e_new = X_f32.astype(np.float64) - d_f64 * (q_new - 4).astype(np.float64)
+        sse_new = np.sum(W_f32 * e_new * e_new, axis=1, dtype=np.float64)
+        v_new = e_new[:, :half] + e_new[:, half:]
+        dc_new = np.sum(e_new, axis=1)
+        spec_old = lam_vw * np.sum(v * v, axis=1) + lam_dc * dc * dc
+        spec_new = lam_vw * np.sum(v_new * v_new, axis=1) + lam_dc * dc_new * dc_new
+        accept = (sse_new <= sse_cap) & ((sse_new + spec_new) < (sse_live + spec_old) - 1.0e-15)
+        best_q = np.where(accept[:, None], q_new, best_q)
+
+    return best_d.astype(np.float32)
+
+
+def _fit_q3_k_blocks(
+    X: np.ndarray, W: np.ndarray, sub_scales: np.ndarray, cfg: HPCConfig
+) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """Fit the GGML super-scale d and signed 6-bit scales for (B, 256) blocks."""
+    B = X.shape[0]
+    X = X.reshape(B, Q3_K_N_SUBBLOCKS, Q3_K_SUBBLOCK).astype(np.float64)
+    W = W.reshape(B, Q3_K_N_SUBBLOCKS, Q3_K_SUBBLOCK).astype(np.float64)
+    s = sub_scales.reshape(B, Q3_K_N_SUBBLOCKS).astype(np.float64)
+    rows = np.arange(B)
+
+    max_idx = np.argmax(np.abs(s), axis=1)
+    max_scale = s[rows, max_idx]
+    d0 = np.where(np.abs(max_scale) > 1.0e-30, -max_scale / 32.0, 0.0)
+
+    cand_d16 = to_fp16_bits((d0[:, None] * MULTS_D[None, :]).astype(np.float32))
+    cand_d = from_fp16_bits(cand_d16).astype(np.float64)
+    act_d = np.abs(cand_d) > 1.0e-15
+    safe_d = np.where(act_d, cand_d, 1.0)
+    sc = np.where(
+        act_d[:, :, None],
+        np.clip(nearest_int((s[:, None, :] / safe_d[:, :, None]).astype(np.float32)), -32, 31),
+        0,
+    )
+    scale = cand_d[:, :, None] * sc
+    act_s = np.abs(scale) > 1.0e-15
+    safe_s = np.where(act_s, scale, 1.0)
+    code = np.where(
+        act_s[:, :, :, None],
+        np.clip(nearest_int((X[:, None, :, :] / safe_s[:, :, :, None]).astype(np.float32)), -4, 3),
+        0,
+    )
+    e = X[:, None, :, :] - scale[:, :, :, None] * code
+    sse_c = np.sum(W[:, None, :, :] * e * e, axis=(2, 3))
+    best_cand = _q3_sieve_and_viterbi(sse_c, cfg)
+    best_d16 = cand_d16[rows, best_cand]
+
+    rad = max(int(cfg.ulp_radius), 4)
+    deltas = np.arange(-rad, rad + 1, dtype=np.int32)
+    pos_b = np.clip(
+        to_fp16_bits(np.abs(from_fp16_bits(best_d16))).astype(np.int32)[:, None] + deltas[None, :],
+        0,
+        0x7BFF,
+    ).astype(np.uint16)
+    neg_b = (pos_b | np.uint16(0x8000)).astype(np.uint16)
+    all_b = np.concatenate([pos_b, neg_b], axis=1)
+    all_d = from_fp16_bits(all_b).astype(np.float64)
+    act_u = np.abs(all_d) > 1.0e-15
+    safe_u = np.where(act_u, all_d, 1.0)
+    sc_u = np.where(
+        act_u[:, :, None],
+        np.clip(nearest_int((s[:, None, :] / safe_u[:, :, None]).astype(np.float32)), -32, 31),
+        0,
+    )
+    scale_u = all_d[:, :, None] * sc_u
+    act_su = np.abs(scale_u) > 1.0e-15
+    safe_su = np.where(act_su, scale_u, 1.0)
+    code_u = np.where(
+        act_su[:, :, :, None],
+        np.clip(nearest_int((X[:, None, :, :] / safe_su[:, :, :, None]).astype(np.float32)), -4, 3),
+        0,
+    )
+    e_u = X[:, None, :, :] - scale_u[:, :, :, None] * code_u
+    sse_u = np.sum(W[:, None, :, :] * e_u * e_u, axis=(2, 3))
+    pick_u = np.argmin(sse_u, axis=1)
+    best_d16 = all_b[rows, pick_u]
+    best_d = all_d[rows, pick_u]
+
+    act_b = np.abs(best_d) > 1.0e-15
+    safe_b = np.where(act_b, best_d, 1.0)
+    sc = np.where(
+        act_b[:, None],
+        np.clip(nearest_int((s / safe_b[:, None]).astype(np.float32)), -32, 31),
+        0,
+    )
+    scale = best_d[:, None] * sc
+    act_s = np.abs(scale) > 1.0e-15
+    safe_s = np.where(act_s, scale, 1.0)
+    code = np.where(
+        act_s[:, :, None],
+        np.clip(nearest_int((X / safe_s[:, :, None]).astype(np.float32)), -4, 3),
+        0,
+    )
+    return best_d16.astype(np.uint16), sc.astype(np.int16), code.astype(np.int16)
+
+
+def _subblock_scales_hpc_cuda(
+    X_np: np.ndarray, W_np: np.ndarray, dev: "torch.device", cfg: HPCConfig
+) -> np.ndarray:
+    """Run the HPC 3-bit sub-block pipeline on CUDA and return signed scales."""
+    M = X_np.shape[0]
+    lam_dc = (float(cfg.dc_lambda) / Q3_K_SUBBLOCK) if cfg.use_spectral else 0.0
+    lam_vw = (float(cfg.vw_lambda) / Q3_K_SUBBLOCK) if cfg.use_spectral else 0.0
+    half = Q3_K_SUBBLOCK // 2
+
+    with torch.no_grad():
+        X = torch.from_numpy(X_np).to(dev, dtype=torch.float32)
+        W = torch.from_numpy(W_np).to(dev, dtype=torch.float32)
+
+        amax = torch.max(torch.abs(X), dim=1).values
+        d_range = amax / 3.5
+        wsum = torch.clamp(torch.sum(W, dim=1, keepdim=True), min=1.0e-30)
+        mu = torch.sum(W * X, dim=1, keepdim=True) / wsum
+        var = torch.sum(W * (X - mu) ** 2, dim=1, keepdim=True) / wsum
+        sig = torch.sqrt(torch.clamp(var, min=1.0e-30))
+        x_comp = mu + sig * 1.85 * torch.tanh((X - mu) / (1.85 * sig))
+        d_analog = torch.max(torch.abs(x_comp), dim=1).values / 3.5
+
+        wls_d = d_range.clone()
+        best_seed_sse = torch.full((M,), float("inf"), dtype=torch.float32, device=dev)
+        for d_start in (d_range, -d_range, d_analog, -d_analog):
+            d = d_start.clone()
+            for _ in range(4):
+                act = torch.abs(d) > 1.0e-15
+                sd = torch.where(act, d, torch.ones_like(d))[:, None]
+                sh = (X / sd) + 12582912.0
+                qi = ((sh.view(torch.int32) & 0x007FFFFF) - 0x00400000 + 4).clamp(0, 7)
+                q = torch.where(act[:, None], qi, torch.full_like(qi, 4))
+                c = (q - 4).to(torch.float32)
+                num = torch.sum(W * X * c, dim=1)
+                den = torch.sum(W * c * c, dim=1)
+                valid = den > 1.0e-30
+                d = torch.where(valid, num / torch.where(valid, den, torch.ones_like(den)), torch.zeros_like(den))
+            df = d.to(torch.float16).to(torch.float32)
+            act = torch.abs(df) > 1.0e-15
+            sdf = torch.where(act, df, torch.ones_like(df))[:, None]
+            sh = (X / sdf) + 12582912.0
+            qi = ((sh.view(torch.int32) & 0x007FFFFF) - 0x00400000 + 4).clamp(0, 7)
+            q = torch.where(act[:, None], qi, torch.full_like(qi, 4))
+            e = X - df[:, None] * (q.to(torch.float32) - 4.0)
+            sse = torch.sum(W * e * e, dim=1)
+            take = sse < best_seed_sse
+            best_seed_sse = torch.where(take, sse, best_seed_sse)
+            wls_d = torch.where(take, df, wls_d)
+
+        mults = torch.tensor(MULTS_D, dtype=torch.float32, device=dev)
+        cand_d = (wls_d[:, None] * mults[None, :]).to(torch.float16).to(torch.float32)
+        act_c = torch.abs(cand_d) > 1.0e-15
+        sd_c = torch.where(act_c, cand_d, torch.ones_like(cand_d))[:, :, None]
+        sh_c = (X[:, None, :] / sd_c) + 12582912.0
+        qi_c = ((sh_c.view(torch.int32) & 0x007FFFFF) - 0x00400000 + 4).clamp(0, 7)
+        q_c = torch.where(act_c[:, :, None], qi_c, torch.full_like(qi_c, 4)).to(torch.float32)
+        e_c = X[:, None, :] - cand_d[:, :, None] * (q_c - 4.0)
+        sse_c = torch.sum(W[:, None, :] * e_c * e_c, dim=2)
+        if cfg.use_spectral and (lam_dc > 0.0 or lam_vw > 0.0):
+            v_c = e_c[:, :, :half] + e_c[:, :, half:]
+            dc_c = torch.sum(e_c, dim=2)
+            cand_err_t = sse_c + lam_vw * torch.sum(v_c * v_c, dim=2) + lam_dc * dc_c * dc_c
+        else:
+            cand_err_t = sse_c
+
+        best_cand_np = _q3_sieve_and_viterbi(cand_err_t.cpu().numpy(), cfg)
+        best_cand_t = torch.from_numpy(best_cand_np).to(dev)
+        rows = torch.arange(M, device=dev)
+        d_sel = cand_d[rows, best_cand_t]
+
+        rad = max(int(cfg.ulp_radius), 4)
+        deltas = torch.arange(-rad, rad + 1, dtype=torch.int32, device=dev)
+        abs_bits = torch.abs(d_sel).to(torch.float16).view(torch.int16).to(torch.int32) & 0x7FFF
+        pos_b = torch.clamp(abs_bits[:, None] + deltas[None, :], 0, 0x7BFF)
+        neg_b = pos_b | 0x8000
+        all_b = torch.cat([pos_b, neg_b], dim=1)
+        all_d = all_b.to(torch.int16).view(torch.float16).to(torch.float32)
+        act_u = torch.abs(all_d) > 1.0e-15
+        sd_u = torch.where(act_u, all_d, torch.ones_like(all_d))[:, :, None]
+        sh_u = (X[:, None, :] / sd_u) + 12582912.0
+        qi_u = ((sh_u.view(torch.int32) & 0x007FFFFF) - 0x00400000 + 4).clamp(0, 7)
+        q_u = torch.where(act_u[:, :, None], qi_u, torch.full_like(qi_u, 4)).to(torch.uint8)
+        e_u = X[:, None, :] - all_d[:, :, None] * (q_u.to(torch.float32) - 4.0)
+        sse_u = torch.sum(W[:, None, :] * e_u * e_u, dim=2)
+        pick_u = torch.argmin(sse_u, dim=1)
+        best_d = all_d[rows, pick_u]
+        best_q = q_u[rows, pick_u].to(torch.int64)
+
+        if cfg.use_spectral and (lam_vw > 0.0 or lam_dc > 0.0):
+            d_col = best_d[:, None]
+            e = X - d_col * (best_q.to(torch.float32) - 4.0)
+            sse_live = torch.sum(W * e * e, dim=1)
+            sse_cap = sse_live * (1.0 + float(cfg.sse_budget))
+            v = e[:, :half] + e[:, half:]
+            dc = torch.sum(e, dim=1)
+            denom = (W + lam_vw + lam_dc) * (d_col * d_col)
+            act_b = torch.abs(d_col) > 1.0e-15
+            s_den = torch.where(act_b & (denom > 1.0e-30), denom, torch.ones_like(denom))
+            v_full = torch.cat([v, v], dim=1)
+            grad = d_col * (W * e + lam_vw * v_full + lam_dc * dc[:, None])
+            sh_dq = (grad / s_den) + 12582912.0
+            dq = torch.where(
+                act_b,
+                ((sh_dq.view(torch.int32) & 0x007FFFFF) - 0x00400000).to(torch.int64),
+                torch.zeros_like(best_q),
+            )
+            q_new = torch.clamp(best_q + dq, 0, 7)
+            e_new = X - d_col * (q_new.to(torch.float32) - 4.0)
+            sse_new = torch.sum(W * e_new * e_new, dim=1)
+            v_new = e_new[:, :half] + e_new[:, half:]
+            dc_new = torch.sum(e_new, dim=1)
+            spec_old = lam_vw * torch.sum(v * v, dim=1) + lam_dc * dc * dc
+            spec_new = lam_vw * torch.sum(v_new * v_new, dim=1) + lam_dc * dc_new * dc_new
+            accept = (sse_new <= sse_cap) & ((sse_new + spec_new) < (sse_live + spec_old) - 1.0e-12)
+            best_q = torch.where(accept[:, None], q_new, best_q)
+
+        return best_d.cpu().numpy().astype(np.float32)
+
+
+def _fit_q3_k_blocks_cuda(
+    X_np: np.ndarray,
+    W_np: np.ndarray,
+    sub_scales: np.ndarray,
+    dev: "torch.device",
+    cfg: HPCConfig,
+) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """Fit GGML Q3_K super-scales and codes on CUDA."""
+    B = X_np.shape[0]
+    with torch.no_grad():
+        X = torch.from_numpy(X_np).to(dev, dtype=torch.float32).reshape(B, Q3_K_N_SUBBLOCKS, Q3_K_SUBBLOCK)
+        W = torch.from_numpy(W_np).to(dev, dtype=torch.float32).reshape(B, Q3_K_N_SUBBLOCKS, Q3_K_SUBBLOCK)
+        s = torch.from_numpy(sub_scales.reshape(B, Q3_K_N_SUBBLOCKS)).to(dev, dtype=torch.float32)
+        rows = torch.arange(B, device=dev)
+
+        max_idx = torch.argmax(torch.abs(s), dim=1)
+        max_scale = s[rows, max_idx]
+        d0 = torch.where(torch.abs(max_scale) > 1.0e-30, -max_scale / 32.0, torch.zeros_like(max_scale))
+        mults = torch.tensor(MULTS_D, dtype=torch.float32, device=dev)
+        cand_d = (d0[:, None] * mults[None, :]).to(torch.float16).to(torch.float32)
+        cand_bits = cand_d.to(torch.float16).view(torch.int16)
+
+        act_d = torch.abs(cand_d) > 1.0e-15
+        safe_d = torch.where(act_d, cand_d, torch.ones_like(cand_d))
+        qi = _nearest_int_t(s[:, None, :] / safe_d[:, :, None])
+        sc = torch.where(act_d[:, :, None], torch.clamp(qi, -32, 31), torch.zeros_like(qi))
+        scale = cand_d[:, :, None] * sc.to(torch.float32)
+        act_s = torch.abs(scale) > 1.0e-15
+        safe_s = torch.where(act_s, scale, torch.ones_like(scale))
+        cq = _nearest_int_t(X[:, None, :, :] / safe_s[:, :, :, None])
+        code = torch.where(act_s[:, :, :, None], torch.clamp(cq, -4, 3), torch.zeros_like(cq))
+        e = X[:, None, :, :] - scale[:, :, :, None] * code.to(torch.float32)
+        sse_c = torch.sum(W[:, None, :, :] * e * e, dim=(2, 3))
+
+        best_cand_np = _q3_sieve_and_viterbi(sse_c.cpu().numpy(), cfg)
+        best_cand_t = torch.from_numpy(best_cand_np).to(dev)
+        best_bits = cand_bits[rows, best_cand_t]
+
+        rad = max(int(cfg.ulp_radius), 4)
+        deltas = torch.arange(-rad, rad + 1, dtype=torch.int32, device=dev)
+        abs_bits = best_bits.to(torch.int32) & 0x7FFF
+        pos_b = torch.clamp(abs_bits[:, None] + deltas[None, :], 0, 0x7BFF)
+        neg_b = pos_b | 0x8000
+        all_b = torch.cat([pos_b, neg_b], dim=1)
+        all_d = all_b.to(torch.int16).view(torch.float16).to(torch.float32)
+        act_u = torch.abs(all_d) > 1.0e-15
+        safe_u = torch.where(act_u, all_d, torch.ones_like(all_d))
+        q_u = _nearest_int_t(s[:, None, :] / safe_u[:, :, None])
+        sc_u = torch.where(act_u[:, :, None], torch.clamp(q_u, -32, 31), torch.zeros_like(q_u))
+        scale_u = all_d[:, :, None] * sc_u.to(torch.float32)
+        act_su = torch.abs(scale_u) > 1.0e-15
+        safe_su = torch.where(act_su, scale_u, torch.ones_like(scale_u))
+        c_u = _nearest_int_t(X[:, None, :, :] / safe_su[:, :, :, None])
+        code_u = torch.where(act_su[:, :, :, None], torch.clamp(c_u, -4, 3), torch.zeros_like(c_u))
+        e_u = X[:, None, :, :] - scale_u[:, :, :, None] * code_u.to(torch.float32)
+        sse_u = torch.sum(W[:, None, :, :] * e_u * e_u, dim=(2, 3))
+        pick_u = torch.argmin(sse_u, dim=1)
+        best_d16 = all_b[rows, pick_u]
+        best_d = all_d[rows, pick_u]
+
+        act_b = torch.abs(best_d) > 1.0e-15
+        safe_b = torch.where(act_b, best_d, torch.ones_like(best_d))
+        sc = torch.where(
+            act_b[:, None],
+            torch.clamp(_nearest_int_t(s / safe_b[:, None]), -32, 31),
+            torch.zeros_like(s, dtype=torch.int32),
+        )
+        scale = best_d[:, None] * sc.to(torch.float32)
+        act_s = torch.abs(scale) > 1.0e-15
+        safe_s = torch.where(act_s, scale, torch.ones_like(scale))
+        code = torch.where(
+            act_s[:, :, None],
+            torch.clamp(_nearest_int_t(X / safe_s[:, :, None]), -4, 3),
+            torch.zeros_like(sc, dtype=torch.int32)[:, :, None].expand(B, Q3_K_N_SUBBLOCKS, Q3_K_SUBBLOCK),
+        )
+        return (
+            best_d16.cpu().numpy().astype(np.uint16),
+            sc.cpu().numpy().astype(np.int16),
+            code.cpu().numpy().astype(np.int16),
+        )
+
+
+def _quantize_q3_k_hpc_cuda(
+    X: np.ndarray, W: np.ndarray, dev: "torch.device", cfg: HPCConfig
+) -> tuple[bytes, float]:
+    """Full HPC V2 Q3_K pipeline on CUDA for a chunk of (B, 256) blocks."""
+    B = X.shape[0]
+    X_f32 = X.astype(np.float32)
+    W_f32 = W.astype(np.float32)
+
+    sub_scales = _subblock_scales_hpc_cuda(
+        X_f32.reshape(B * Q3_K_N_SUBBLOCKS, Q3_K_SUBBLOCK),
+        W_f32.reshape(B * Q3_K_N_SUBBLOCKS, Q3_K_SUBBLOCK),
+        dev,
+        cfg,
+    )
+    d16, sc, code = _fit_q3_k_blocks_cuda(X_f32, W_f32, sub_scales, dev, cfg)
+
+    hmask, qs = _pack_q3_k_codes(code)
+    scales = _pack_q3_k_scales(sc)
+    out = np.empty((B, Q3_K_BLOCK_BYTES), dtype=np.uint8)
+    out[:, : QK3_K // 8] = hmask
+    out[:, QK3_K // 8 : QK3_K // 8 + QK3_K // 4] = qs
+    out[:, QK3_K // 8 + QK3_K // 4 : Q3_K_BLOCK_BYTES - 2] = scales
+    out[:, Q3_K_BLOCK_BYTES - 2 :] = d16.astype("<u2").view(np.uint8).reshape(B, 2)
+
+    d = from_fp16_bits(d16).astype(np.float32)
+    deq = (d[:, None, None] * sc[:, :, None].astype(np.float32) * code.astype(np.float32)).reshape(B, QK3_K)
+    raw_sse = float(np.sum((X_f32 - deq) ** 2, dtype=np.float64))
+    return out.tobytes(), raw_sse
+
+
+def _quantize_q3_k_hpc_cpu(
+    X: np.ndarray, W: np.ndarray, cfg: HPCConfig
+) -> tuple[bytes, float]:
+    """Full HPC V2 Q3_K pipeline on CPU for a chunk of (B, 256) blocks."""
+    B = X.shape[0]
+    X_f32 = X.astype(np.float32)
+    W_f32 = W.astype(np.float32)
+
+    sub_scales = _subblock_scales_hpc(
+        X_f32.reshape(B * Q3_K_N_SUBBLOCKS, Q3_K_SUBBLOCK),
+        W_f32.reshape(B * Q3_K_N_SUBBLOCKS, Q3_K_SUBBLOCK),
+        cfg,
+    )
+    d16, sc, code = _fit_q3_k_blocks(X_f32, W_f32, sub_scales, cfg)
+
+    hmask, qs = _pack_q3_k_codes(code)
+    scales = _pack_q3_k_scales(sc)
+    out = np.empty((B, Q3_K_BLOCK_BYTES), dtype=np.uint8)
+    out[:, : QK3_K // 8] = hmask
+    out[:, QK3_K // 8 : QK3_K // 8 + QK3_K // 4] = qs
+    out[:, QK3_K // 8 + QK3_K // 4 : Q3_K_BLOCK_BYTES - 2] = scales
+    out[:, Q3_K_BLOCK_BYTES - 2 :] = d16.astype("<u2").view(np.uint8).reshape(B, 2)
+
+    d = from_fp16_bits(d16).astype(np.float32)
+    deq = (d[:, None, None] * sc[:, :, None].astype(np.float32) * code.astype(np.float32)).reshape(B, QK3_K)
+    raw_sse = float(np.sum((X_f32 - deq) ** 2, dtype=np.float64))
+    return out.tobytes(), raw_sse
+
+
+def quantize_tensor_q3_k(
+    weights: np.ndarray,
+    importance: np.ndarray | None = None,
+    cfg: HPCConfig | None = None,
+    chunk_blocks: int = 1024,
+) -> tuple[bytes, int, float]:
+    """Quantize a tensor to GGML Q3_K using the full HPC V2 pipeline."""
+    cfg = cfg or HPCConfig()
+    x = np.asarray(weights, dtype=np.float32).ravel()
+    if x.size == 0 or x.size % QK3_K != 0:
+        raise ValueError("Q3_K requires a non-empty weight count divisible by 256")
+    n_blocks = x.size // QK3_K
+    X = x.reshape(n_blocks, QK3_K)
+
+    if importance is not None:
+        imp = np.asarray(importance, dtype=np.float32).ravel()
+        if imp.size != x.size:
+            raise ValueError("importance length must match weight count")
+        W_raw = imp.reshape(n_blocks, QK3_K)
+    else:
+        W_raw = None
+
+    use_cuda = cfg.device != "cpu" and torch is not None and cuda_is_available() and (
+        cfg.device.startswith("cuda") or (cfg.device == "auto" and n_blocks >= 64)
+    )
+    dev = torch.device("cuda" if cfg.device == "auto" else cfg.device) if use_cuda else None
+
+    chunks: list[bytes] = []
+    total_sse = 0.0
+    for start in range(0, n_blocks, chunk_blocks):
+        stop = min(start + chunk_blocks, n_blocks)
+        Xb = X[start:stop]
+        sig2 = np.mean(Xb * Xb, axis=1, keepdims=True)
+        if W_raw is None:
+            Wb = np.sqrt(sig2 + Xb * Xb)
+        else:
+            wr = W_raw[start:stop]
+            Wb = np.sqrt(np.maximum(wr, 1.0e-6)) * np.sqrt(sig2 + Xb * Xb) if cfg.temper_imatrix else wr
+        wm = np.mean(Wb, axis=1, keepdims=True)
+        Wb = np.where(wm > 1.0e-30, Wb / np.maximum(wm, 1.0e-30), 1.0).astype(np.float32)
+
+        if use_cuda and dev is not None:
+            raw_b, sse_b = _quantize_q3_k_hpc_cuda(Xb, Wb, dev, cfg)
+        else:
+            raw_b, sse_b = _quantize_q3_k_hpc_cpu(Xb, Wb, cfg)
+        chunks.append(raw_b)
+        total_sse += sse_b
+
+    rmse = float(np.sqrt(total_sse / x.size))
+    return b"".join(chunks), n_blocks, rmse