tico 0.1.0.dev250803__py3-none-any.whl → 0.1.0.dev251106__py3-none-any.whl

tico/quantization/evaluation/metric.py

@@ -0,0 +1,146 @@
+# Copyright (c) 2025 Samsung Electronics Co., Ltd. All Rights Reserved
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from typing import Any, Callable, Dict, List, Optional
+
+import numpy as np
+import torch
+
+
+def compute_max_abs_diff(base: torch.Tensor, target: torch.Tensor) -> float:
+    """
+    Return the *maximum* absolute element-wise difference between two tensors.
+    """
+    assert base.shape == target.shape, "shape mismatch"
+    return (base.detach() - target.detach()).abs().max().item()
+
+
+def compute_peir(base: torch.Tensor, target: torch.Tensor) -> float:
+    """
+    Peak-Error-to-Interval Ratio (PEIR).
+
+        PEIR = max(|base - target|) / (max(base) - min(base))
+
+    The interval denominator uses the reference (*base*) tensor only — this
+    makes PEIR independent of quantisation error in `target`.
+    """
+    assert base.shape == target.shape, "shape mismatch"
+    peak_error = (base.detach() - target.detach()).abs().max().item()
+    interval = (base.detach().max() - base.detach().min()).item()
+    interval = 1.0 if interval == 0.0 else interval  # avoid divide-by-zero
+    return peak_error / interval
+
+
+def mse(base: torch.Tensor, target: torch.Tensor) -> float:
+    """
+    Mean Squared Error (MSE).
+    Penalizes **larger** deviations more heavily than MAE by squaring each
+    difference — helpful to expose occasional large spikes.
+    Formula
+    -------
+        MSE = mean((base - target)²)
+    Returns
+    -------
+    float
+        Mean squared error. *Lower is better*.
+    """
+    return torch.mean((base.detach() - target.detach()) ** 2).item()
+
+
+class MetricCalculator:
+    """
+    Lightweight registry-and-dispatcher for **pair-wise tensor comparison metrics**.
+
+    Purpose
+    -------
+    Consolidate all metrics used to assess the discrepancy between a reference
+    (usually FP32) tensor and its quantized counterpart, while letting the caller
+    choose *at runtime* which subset to evaluate.
+
+    Built-in metrics
+    ----------------
+    Key                     Description
+    --------------------    -------------------------------------------------
+    "diff" / "max_abs_diff"  Maximum absolute element-wise difference
+    "peir"                   Peak-Error-to-Interval Ratio
+
+    Usage pattern
+    -------------
+    >>> calc = MetricCalculator(custom_metrics={'mse': mse_fn})
+    >>> stats = calc.compute(fp_outs, q_outs, metrics=['diff', 'mse'])
+
+    • **Instantiation** registers any extra user metrics
+      (signature: ``fn(base: Tensor, target: Tensor) -> float``).
+    • **compute(...)** takes two *equal-length* lists of tensors and an optional
+      list of metric names.
+        — If *metrics* is *None*, every registered metric is evaluated.
+        — Returns a dict: ``{metric_name -> [value for each tensor pair]}``.
+
+    Implementation notes
+    --------------------
+    * All tensors are detached before calculation to avoid autograd overhead.
+    * Registrations are stored in `self.registry` (str → callable).
+    * Duplicate metric names between built-ins and custom metrics raise an error
+      at construction time to prevent silent shadowing.
+    """
+
+    builtin_metrics: Dict[str, Callable[[torch.Tensor, torch.Tensor], float]] = {
+        "diff": compute_max_abs_diff,
+        "max_abs_diff": compute_max_abs_diff,
+        "peir": compute_peir,
+        "mse": mse,
+    }
+
+    def __init__(
+        self,
+        custom_metrics: Optional[
+            Dict[str, Callable[[torch.Tensor, torch.Tensor], float]]
+        ] = None,
+    ):
+        self.registry: Dict[str, Callable] = self.builtin_metrics.copy()
+        if custom_metrics:
+            dup = self.registry.keys() & custom_metrics.keys()
+            if dup:
+                raise RuntimeError(f"Duplicate metric names: {dup}")
+            assert custom_metrics is not None
+            self.registry.update(custom_metrics)  # type: ignore[arg-type]
+
+    # ----------------------------------------------------------------- #
+    # Public API                                                        #
+    # ----------------------------------------------------------------- #
+    def compute(
+        self,
+        base_outputs: List[torch.Tensor],
+        target_outputs: List[torch.Tensor],
+        metrics: Optional[List[str]] = None,
+    ) -> Dict[str, List[Any]]:
+        """
+        Compute selected metrics for every (base, target) pair.
+
+        Parameters
+        ----------
+        metrics
+            List of metric names to evaluate **this call**.
+            • None → evaluate *all* registered metrics.
+        """
+        sel = metrics or list(self.registry)
+        unknown = set(sel) - self.registry.keys()
+        if unknown:
+            raise RuntimeError(f"Unknown metric(s): {unknown}")
+
+        results: Dict[str, List[Any]] = {m: [] for m in sel}
+        for base, tgt in zip(base_outputs, target_outputs):
+            for m in sel:
+                results[m].append(self.registry[m](base, tgt))
+        return results

tico/{experimental/quantization → quantization}/evaluation/utils.py

@@ -44,7 +44,7 @@ def quantize(
         data = np.array(data)
     # Perfrom quantization
     if not scale:
-        logger.warn("WARNING: scale value is 0. 1e-7 will be used instead.")
+        logger.warning("WARNING: scale value is 0. 1e-7 will be used instead.")
         scale = 1e-7
     rescaled = np.round(data / scale) + zero_point
     # Clamp the values

tico/quantization/passes/__init__.py

@@ -0,0 +1 @@
+# DO NOT REMOVE THIS FILE

tico/{experimental/quantization → quantization}/public_interface.py

@@ -13,25 +13,17 @@
 # limitations under the License.
 
 import copy
-from typing import Any, Dict, Optional, Type
+from typing import Any, Dict, Optional
 
 import torch
 
-from tico.experimental.quantization.algorithm.gptq.quantizer import GPTQQuantizer
-from tico.experimental.quantization.algorithm.pt2e.quantizer import PT2EQuantizer
-from tico.experimental.quantization.algorithm.smoothquant.quantizer import (
-    SmoothQuantQuantizer,
-)
-from tico.experimental.quantization.config import BaseConfig
-from tico.experimental.quantization.quantizer import BaseQuantizer
+from tico.quantization.algorithm.gptq.quantizer import GPTQQuantizer
+from tico.quantization.algorithm.pt2e.quantizer import PT2EQuantizer
+from tico.quantization.config.base import BaseConfig
+from tico.quantization.quantizer import BaseQuantizer
+from tico.quantization.quantizer_registry import get_quantizer
 
 
-config_to_quantizer: Dict[str, Type[BaseQuantizer]] = {
-    "pt2e": PT2EQuantizer,
-    "gptq": GPTQQuantizer,
-    "smooth_quant": SmoothQuantQuantizer,
-}
-
 QUANTIZER_ATTRIBUTE_NAME = "tico_quantizer"
 
 
@@ -40,7 +32,7 @@ def prepare(
     quant_config: BaseConfig,
     args: Optional[Any] = None,
     kwargs: Optional[Dict[str, Any]] = None,
-    inplace: Optional[bool] = False,
+    inplace: Optional[bool] = True,
 ):
     """
     Prepare the model for quantization using the provided configuration.
@@ -61,21 +53,22 @@ def prepare(
     """
     if hasattr(model, QUANTIZER_ATTRIBUTE_NAME):
         raise RuntimeError("prepare() already has been called.")
-    if quant_config.name == "pt2e" and inplace:
+    quantizer = get_quantizer(quant_config)
+
+    if isinstance(quantizer, PT2EQuantizer) and inplace:
         raise RuntimeError(
             "In-place is not supported for PT2E quantization due to limitation in the underlying Torch APIs. Please set 'inplace=False' to proceed."
         )
 
     model = model if inplace else copy.deepcopy(model)
 
-    quantizer = config_to_quantizer[quant_config.name](quant_config)
     model = quantizer.prepare(model, args, kwargs)
     setattr(model, QUANTIZER_ATTRIBUTE_NAME, quantizer)
 
     return model
 
 
-def convert(model, inplace: Optional[bool] = False):
+def convert(model, inplace: Optional[bool] = True):
     """
     Convert the prepared model to a quantized model using the provided configuration.
 

tico/{experimental/quantization → quantization}/quantizer.py

@@ -17,7 +17,7 @@ from typing import Any, Dict, Optional
 
 import torch
 
-from tico.experimental.quantization.config import BaseConfig
+from tico.quantization.config.base import BaseConfig
 
 
 class BaseQuantizer(ABC):

tico/quantization/quantizer_registry.py

@@ -0,0 +1,73 @@
+# Copyright (c) 2025 Samsung Electronics Co., Ltd. All Rights Reserved
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import importlib
+from typing import Dict, Optional, Type, TypeVar
+
+from tico.quantization.config.base import BaseConfig
+from tico.quantization.quantizer import BaseQuantizer
+
+TQ = TypeVar("TQ", bound=BaseQuantizer)
+
+# Mapping: Config type -> Quantizer type
+_REGISTRY: Dict[Type[BaseConfig], Type[BaseQuantizer]] = {}
+
+
+def register_quantizer(config_cls: Type[BaseConfig]):
+    """
+    Decorator to register a quantizer for a given config class.
+    Usage:
+        @register_quantizer(GPTQConfig)
+        class GPTQQuantizer(BaseQuantizer): ...
+    """
+
+    def wrapper(quantizer_cls: Type[TQ]) -> Type[TQ]:
+        _REGISTRY[config_cls] = quantizer_cls
+        return quantizer_cls
+
+    return wrapper
+
+
+def _lookup(cfg: BaseConfig) -> Optional[Type[BaseQuantizer]]:
+    """Return a quantizer class only if the exact config type is registered."""
+    return _REGISTRY.get(type(cfg))
+
+
+def get_quantizer(cfg: BaseConfig) -> BaseQuantizer:
+    """Factory to return a quantizer instance for the given config."""
+    qcls = _lookup(cfg)
+    if qcls is not None:
+        return qcls(cfg)
+
+    # Lazy import by naming convention
+    name = getattr(cfg, "name", None)
+    if name:
+        if name == "ptq":
+            importlib.import_module(f"tico.quantization.wrapq.quantizer")
+        else:
+            try:
+                importlib.import_module(f"tico.quantization.algorithm.{name}.quantizer")
+            except Exception as e:
+                raise RuntimeError(
+                    f"Failed to import quantizer module for config name='{name}': {e}"
+                )
+
+    qcls = _lookup(cfg)
+    if qcls is not None:
+        return qcls(cfg)
+
+    raise RuntimeError(
+        f"No quantizer registered for config type {type(cfg).__name__} "
+        f"(name='{getattr(cfg,'name',None)}')."
+    )

tico/quantization/wrapq/__init__.py

@@ -0,0 +1 @@
+# DO NOT REMOVE THIS FILE

tico/quantization/wrapq/dtypes.py

@@ -0,0 +1,70 @@
+# Copyright (c) 2025 Samsung Electronics Co., Ltd. All Rights Reserved
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class DType:
+    """
+    Self-contained integer dtypes for quantization.
+
+    A DType is just an immutable value-object with two fields:
+      - bits
+      - signed
+
+    Common presets (INT8, UINT4, ..) are provided as constants for convenience.
+    """
+
+    bits: int  # pylint: disable=used-before-assignment
+    signed: bool = False  # False -> unsigned
+
+    @property
+    def qmin(self) -> int:
+        assert self.bits is not None
+        if self.signed:
+            return -(1 << (self.bits - 1))
+        return 0
+
+    @property
+    def qmax(self) -> int:
+        assert self.bits is not None
+        if self.signed:
+            return (1 << (self.bits - 1)) - 1
+        return (1 << self.bits) - 1
+
+    def __str__(self) -> str:
+        prefix = "int" if self.signed else "uint"
+        return f"{prefix}{self.bits}"
+
+    # ────────────────────────────────
+    #  Factory helpers
+    # ────────────────────────────────
+    @staticmethod
+    def int(bits: int):  # type: ignore[valid-type]
+        return DType(bits, signed=True)
+
+    @staticmethod
+    def uint(bits: int):  # type: ignore[valid-type]
+        return DType(bits, signed=False)
+
+
+# ---------------------------------------------------------------------
+#  Convenient canned versions
+# ---------------------------------------------------------------------
+UINT4 = DType.uint(4)
+INT4 = DType.int(4)
+INT8 = DType.int(8)
+UINT8 = DType.uint(8)
+INT16 = DType.int(16)

tico/quantization/wrapq/examples/__init__.py

@@ -0,0 +1 @@
+# DO NOT REMOVE THIS FILE

tico/quantization/wrapq/examples/compare_ppl.py

@@ -0,0 +1,230 @@
+# Copyright (c) 2025 Samsung Electronics Co., Ltd. All Rights Reserved
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# =============================================================================
+# QUICK PTQ WORKFLOW (OPTIONAL FP32 BASELINE)
+# -----------------------------------------------------------------------------
+# Toggle RUN_FP to choose between:
+#   • FP32 perplexity measurement only, OR
+#   • Full post-training UINT-8 flow (wrap → calibrate → eval).
+# =============================================================================
+
+import argparse
+import sys
+
+import torch
+import tqdm
+from datasets import load_dataset
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+from tico.quantization import convert, prepare
+from tico.quantization.config.ptq import PTQConfig
+from tico.quantization.wrapq.utils.metrics import perplexity
+
+# Token-budget presets for activation calibration
+TOKENS: dict[str, int] = {
+    # Smoke test (<1 min turnaround on CPU/GPU)
+    "debug": 2_000,  # ≈16 × 128-seq batches
+    # Good default for 1-7B models (≲3 % ppl delta)
+    "baseline": 50_000,
+    # Production / 4-bit observer smoothing
+    "production": 200_000,
+}
+
+DTYPE_MAP = {
+    "float32": torch.float32,
+    "bfloat16": torch.bfloat16,
+    "float16": torch.float16,
+}
+
+# Hardcoded dataset settings
+DATASET_NAME = "wikitext"
+DATASET_CONFIG = "wikitext-2-raw-v1"
+TRAIN_SPLIT = "train"
+TEST_SPLIT = "test"
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Quick PTQ example (FP or UINT8)")
+    parser.add_argument(
+        "--mode",
+        choices=["fp", "uint8"],
+        default="fp",
+        help="Choose FP baseline only or full UINT8 PTQ path.",
+    )
+    parser.add_argument(
+        "--model", type=str, required=True, help="HF repo name or local path."
+    )
+    parser.add_argument(
+        "--device",
+        type=str,
+        default="cuda" if torch.cuda.is_available() else "cpu",
+        help="Device to run on (cuda|cpu).",
+    )
+    parser.add_argument(
+        "--dtype",
+        choices=list(DTYPE_MAP.keys()),
+        default="float32",
+        help=f"Model dtype for load.",
+    )
+    parser.add_argument(
+        "--stride", type=int, default=512, help="Sliding-window stride for perplexity."
+    )
+    parser.add_argument("--seed", type=int, default=42, help="Random seed.")
+    parser.add_argument(
+        "--trust-remote-code",
+        action="store_true",
+        help="Enable only if you trust the model repo code.",
+    )
+    parser.add_argument(
+        "--hf-token",
+        type=str,
+        default=None,
+        help="Optional HF token for gated/private models.",
+    )
+    parser.add_argument(
+        "--use-cache",
+        dest="use_cache",
+        action="store_true",
+        default=False,
+        help="Use model KV cache if enabled (off by default).",
+    )
+    parser.add_argument(
+        "--no-tqdm", action="store_true", help="Disable tqdm progress bars."
+    )
+    # 2) calib-preset default = debug
+    parser.add_argument(
+        "--calib-preset",
+        choices=list(TOKENS.keys()),
+        default="debug",
+        help="Calibration token budget preset.",
+    )
+
+    args = parser.parse_args()
+
+    # Basic setup
+    torch.manual_seed(args.seed)
+    device = torch.device(args.device)
+    dtype = DTYPE_MAP[args.dtype]
+
+    print("=== Config ===")
+    print(f"Mode             : {args.mode}")
+    print(f"Model            : {args.model}")
+    print(f"Device           : {device.type}")
+    print(f"DType            : {args.dtype}")
+    print(f"Stride           : {args.stride}")
+    print(f"Use HF cache?    : {args.use_cache}")
+    print(
+        f"Calib preset     : {args.calib_preset} ({TOKENS[args.calib_preset]:,} tokens)"
+    )
+    print()
+
+    # -------------------------------------------------------------------------
+    # 1. Load model and tokenizer
+    # -------------------------------------------------------------------------
+    tokenizer = AutoTokenizer.from_pretrained(
+        args.model,
+        trust_remote_code=args.trust_remote_code,
+        token=args.hf_token,
+    )
+
+    model = (
+        AutoModelForCausalLM.from_pretrained(
+            args.model,
+            torch_dtype=dtype,
+            trust_remote_code=args.trust_remote_code,
+            token=args.hf_token,
+        )
+        .to(device)
+        .eval()
+    )
+
+    model.config.use_cache = args.use_cache
+
+    if args.mode == "fp":
+        fp_model = model
+    else:
+        # INT8 PTQ path
+        uint8_model = model
+
+        CALIB_TOKENS = TOKENS[args.calib_preset]
+        print(f"Calibrating with {CALIB_TOKENS:,} tokens.\n")
+
+        # ---------------------------------------------------------------------
+        # 2. Wrap every Transformer layer with PTQWrapper
+        # ---------------------------------------------------------------------
+        qcfg = PTQConfig()  # all-uint8 defaults
+        prepare(uint8_model, qcfg)
+
+        # ---------------------------------------------------------------------
+        # 3. Single-pass activation calibration
+        # ---------------------------------------------------------------------
+        print("Calibrating UINT-8 observers …")
+        calib_txt = " ".join(
+            load_dataset(DATASET_NAME, DATASET_CONFIG, split=TRAIN_SPLIT)["text"]
+        )[:CALIB_TOKENS]
+        ids = tokenizer(calib_txt, return_tensors="pt").input_ids.to(device)
+
+        # Run inference to collect ranges
+        iterator = range(0, ids.size(1) - 1, args.stride)
+        if not args.no_tqdm:
+            iterator = tqdm.tqdm(iterator, desc="Calibration")
+        with torch.no_grad():
+            for i in iterator:
+                uint8_model(ids[:, i : i + args.stride])
+
+        # Freeze (scale, zero-point)
+        convert(uint8_model)
+
+    # -------------------------------------------------------------------------
+    # 4. Evaluate perplexity
+    # -------------------------------------------------------------------------
+    print("\nCalculating perplexities …")
+    test_ds = load_dataset(DATASET_NAME, DATASET_CONFIG, split=TEST_SPLIT)
+    enc = tokenizer("\n\n".join(test_ds["text"]), return_tensors="pt")
+
+    if args.mode == "fp":
+        ppl_fp = perplexity(
+            fp_model,
+            enc,
+            args.device,
+            stride=args.stride,
+            show_progress=not args.no_tqdm,
+        )
+    else:
+        ppl_int8 = perplexity(
+            uint8_model,
+            enc,
+            args.device,
+            stride=args.stride,
+            show_progress=not args.no_tqdm,
+        )
+
+    # -------------------------------------------------------------------------
+    # 5. Report
+    # -------------------------------------------------------------------------
+    print("\n┌── Wikitext-2 test perplexity ─────────────")
+    if args.mode == "fp":
+        print(f"│ FP     : {ppl_fp:8.2f}")
+    else:
+        print(f"│ UINT-8 : {ppl_int8:8.2f}")
+    print("└───────────────────────────────────────────")
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception as e:
+        print(f"\n[Error] {e}", file=sys.stderr)
+        sys.exit(1)