Raise clear error for unsupported QEP quantizers

Author: FKKimura

CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## [v1.1.1] 2026-05-07
 
+## Bug Fixes
+
+- Raise a clear error when ``Runner`` is configured with ``qep=True`` and a quantizer that does not support QEP (currently `JointQ`). Previously the run failed deep inside `quantize_with_qep` / `adjust_weight` with a confusing low-level error. `Runner.check()` now reports e.g. "Quantizer 'JointQ' (or one of its candidate quantizers) does not support QEP (Quantization Error Propagation). Set qep=False, or use a QEP-compatible quantizer (e.g., GPTQ, DBF, AutoBitQuantizer with QEP-compatible candidates)." Implementation: added `flag_qep_supported` (default `True`) on `Quantizer`, set to `False` on `JointQ`, and propagated via `AutoBitQuantizer._sync_flags` (only `True` when *all* candidate quantizers support QEP).
+
+## Tests
+
+- Added `tests/onecomp/test_runner_check.py` covering the new `qep=True` validation path: JointQ + qep=True raises a clear `ValueError`, while JointQ + qep=False and GPTQ + qep=True both pass `Runner.check()`.
+
 ## [v1.1.0] 2026-04-16
 
 ### Gemma 3 / Gemma 4 & VLM Support

onecomp/quantizer/_quantizer.py

@@ -174,6 +174,7 @@ class Quantizer(metaclass=ABCMeta):
     flag_calibration: bool = False
     flag_hessian: bool = False
     flag_xtx: bool = False  # Whether X^T X is needed (e.g., JointQ)
+    flag_qep_supported: bool = True
 
     def __post_init__(self):
         """__post_init__ method"""

onecomp/quantizer/autobit/_autobit.py

@@ -393,6 +393,11 @@ def _sync_flags(self):
             self.flag_calibration = any(q.flag_calibration for q in self.quantizers)
             self.flag_hessian = any(q.flag_hessian for q in self.quantizers)
             self.flag_xtx = any(q.flag_xtx for q in self.quantizers)
+            # AutoBit supports QEP only when *all* candidate quantizers support it
+            # (the per-layer assignment may dispatch to any child quantizer).
+            self.flag_qep_supported = all(
+                q.flag_qep_supported for q in self.quantizers
+            )
 
     def _validate_manual_fused_consistency(self):
         """Check that manual keyword rules don't split fused groups."""

onecomp/quantizer/jointq/_jointq.py

@@ -250,6 +250,9 @@ class JointQ(Quantizer):
     flag_calibration: bool = True
     flag_hessian: bool = False
     flag_xtx: bool = True
+    # JointQ does not yet support the generic QEP pipeline.
+    # Planned for a future release.
+    flag_qep_supported: bool = False
     hessian_dtype: torch.dtype = torch.float64
 
     # Parameters for the JointQ quantizer

onecomp/runner.py

@@ -291,6 +291,15 @@ def check(self):
                 )
             if self.multi_gpu and not self.quantizer.flag_calibration:
                 raise ValueError("'multi_gpu' requires a quantizer with flag_calibration=True.")
+            if self.qep and not self.quantizer.flag_qep_supported:
+                raise ValueError(
+                    f"Quantizer '{type(self.quantizer).__name__}' "
+                    f"(or one of its candidate quantizers) does not support "
+                    f"QEP (Quantization Error Propagation). "
+                    f"Set qep=False, or use a QEP-compatible quantizer "
+                    f"(e.g., GPTQ, DBF, AutoBitQuantizer with "
+                    f"QEP-compatible candidates)."
+                )
 
         # Cross-validate calibration_dataset when AutoBitQuantizer is used
         quantizer = self.quantizer or (self.quantizers[0] if self.quantizers else None)

tests/onecomp/test_runner_check.py

@@ -0,0 +1,100 @@
+"""Unit tests for ``Runner.check()`` parameter validation.
+
+These tests exercise only the configuration validation path
+(``Runner.check()``) and therefore do not require a GPU or model
+loading.
+
+Copyright 2025-2026 Fujitsu Ltd.
+"""
+
+import pytest
+
+from onecomp import CalibrationConfig, ModelConfig, Runner
+from onecomp.quantizer.autobit import AutoBitQuantizer
+from onecomp.quantizer.gptq import GPTQ
+from onecomp.quantizer.jointq import JointQ
+
+
+def _model_config() -> ModelConfig:
+    return ModelConfig(
+        model_id="TinyLlama/TinyLlama-1.1B-intermediate-step-1431k-3T",
+        device="cuda:0",
+    )
+
+
+class TestRunnerCheckQEPSupport:
+    """``qep=True`` must raise a clear error when the quantizer does
+    not support the generic QEP pipeline.
+    """
+
+    def test_jointq_with_qep_true_raises_clear_error(self):
+        """JointQ + qep=True should raise a clear ValueError, not an
+        obscure error from deep inside the QEP runtime.
+        """
+        runner = Runner(
+            model_config=_model_config(),
+            quantizer=JointQ(bits=4, group_size=128),
+            calibration_config=CalibrationConfig(max_length=128, num_calibration_samples=8),
+            qep=True,
+        )
+
+        with pytest.raises(ValueError, match=r"JointQ.*does not support QEP"):
+            runner.check()
+
+    def test_jointq_with_qep_false_passes_check(self):
+        """JointQ + qep=False is the supported configuration."""
+        runner = Runner(
+            model_config=_model_config(),
+            quantizer=JointQ(bits=4, group_size=128),
+            calibration_config=CalibrationConfig(max_length=128, num_calibration_samples=8),
+            qep=False,
+        )
+        runner.check()
+
+    def test_gptq_with_qep_true_passes_check(self):
+        """GPTQ supports QEP, so check() must pass."""
+        runner = Runner(
+            model_config=_model_config(),
+            quantizer=GPTQ(wbits=4, groupsize=128),
+            calibration_config=CalibrationConfig(max_length=128, num_calibration_samples=8),
+            qep=True,
+        )
+        runner.check()
+
+    def test_autobit_with_jointq_candidate_and_qep_true_raises(self):
+        """AutoBit with a JointQ candidate must also raise on qep=True.
+
+        ``AutoBitQuantizer.flag_qep_supported`` is True only when *all*
+        candidate quantizers support QEP, so a JointQ candidate must
+        propagate the unsupported state.
+        """
+        autobit = AutoBitQuantizer(
+            quantizers=[GPTQ(wbits=4), JointQ(bits=2)],
+            target_bit=3.0,
+        )
+        runner = Runner(
+            model_config=_model_config(),
+            quantizer=autobit,
+            calibration_config=CalibrationConfig(max_length=128, num_calibration_samples=8),
+            qep=True,
+        )
+
+        with pytest.raises(
+            ValueError,
+            match=r"AutoBitQuantizer.*does not support QEP",
+        ):
+            runner.check()
+
+    def test_autobit_with_only_gptq_candidates_and_qep_true_passes(self):
+        """AutoBit with only QEP-compatible candidates must pass."""
+        autobit = AutoBitQuantizer(
+            quantizers=[GPTQ(wbits=4), GPTQ(wbits=2)],
+            target_bit=3.0,
+        )
+        runner = Runner(
+            model_config=_model_config(),
+            quantizer=autobit,
+            calibration_config=CalibrationConfig(max_length=128, num_calibration_samples=8),
+            qep=True,
+        )
+        runner.check()