tico 0.1.0.dev250714__py3-none-any.whl → 0.1.0.dev251102__py3-none-any.whl

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)

tico/quantization/wrapq/examples/debug_quant_outputs.py

@@ -0,0 +1,224 @@
+# 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.
+
+# ============================================================================
+# LAYER-WISE DIFF DEBUGGING PIPELINE
+# ----------------------------------------------------------------------------
+# A quantization debugging pipeline that identifies accuracy regressions
+# by comparing UINT vs FP outputs at each layer.
+#
+#   1. Load a full-precision (FP) LLaMA-3-1B model.
+#   2. Wrap each Transformer block with PTQWrapper (activations → fake-quant).
+#   3. Capture reference FP layer outputs before quantization.
+#   4. Calibrate UINT-8 activation observers in a single pass.
+#   5. Freeze quantization parameters (scale, zero-point).
+#   6. Re-run inference and compare UINT-8 vs FP outputs per layer.
+#   7. Report where quantization hurts the most.
+#
+# Use this pipeline to trace precision loss layer by layer, and pinpoint
+# problematic modules during post-training quantization.
+# ============================================================================
+
+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.introspection import (
+    build_fqn_map,
+    compare_layer_outputs,
+    save_fp_outputs,
+)
+from tico.quantization.wrapq.wrappers.ptq_wrapper import PTQWrapper
+
+# 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"
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Layer-wise diff debugging pipeline for PTQ"
+    )
+    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|mps).",
+    )
+    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 used during calibration.",
+    )
+    parser.add_argument(
+        "--calib-preset",
+        choices=list(TOKENS.keys()),
+        default="debug",
+        help="Calibration token budget preset.",
+    )
+    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 repos.",
+    )
+    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."
+    )
+
+    args = parser.parse_args()
+
+    # Basic setup
+    torch.manual_seed(args.seed)
+    device = torch.device(args.device)
+    dtype = DTYPE_MAP[args.dtype]  # noqa: E999 (kept readable)
+
+    print("=== Config ===")
+    print(f"Model            : {args.model}")
+    print(f"Device           : {device.type}")
+    print(f"DType            : {args.dtype}")
+    print(f"Stride           : {args.stride}")
+    print(
+        f"Calib preset     : {args.calib_preset} ({TOKENS[args.calib_preset]:,} tokens)"
+    )
+    print(f"Use HF cache?    : {args.use_cache}")
+    print()
+
+    # -------------------------------------------------------------------------
+    # 1. Load the FP backbone and tokenizer
+    # -------------------------------------------------------------------------
+    print("Loading FP model …")
+    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()
+    )
+
+    # Disable KV cache to force full forward passes for introspection
+    model.config.use_cache = args.use_cache
+
+    # Build module -> FQN map before wrapping
+    m_to_fqn = build_fqn_map(model)
+
+    # Prepare calibration inputs (HF Wikitext-2 train split)
+    CALIB_TOKENS = TOKENS[args.calib_preset]
+    print(f"Calibrating with {CALIB_TOKENS:,} tokens.\n")
+    # Use Wikitext-2 train split for calibration.
+    dataset = load_dataset(DATASET_NAME, DATASET_CONFIG, split=TRAIN_SPLIT)
+
+    # -------------------------------------------------------------------------
+    # 2. Wrap every layer with PTQWrapper (UINT-8 activations)
+    # -------------------------------------------------------------------------
+    print("Wrapping layers with PTQWrapper …")
+    qcfg = PTQConfig()  # default: per-tensor UINT8
+    prepare(model, qcfg)
+
+    # -------------------------------------------------------------------------
+    # 3. Activation calibration plus FP-vs-UINT8 diffing
+    # -------------------------------------------------------------------------
+    print("Calibrating UINT-8 observers …")
+    calib_txt = " ".join(dataset["text"])[:CALIB_TOKENS]
+    ids = tokenizer(calib_txt, return_tensors="pt").input_ids.to(device)
+
+    # Save reference FP activations before observers clamp/quantize
+    save_handles, act_cache = save_fp_outputs(model)
+
+    iterator = range(0, ids.size(1) - 1, args.stride)
+    if not args.no_tqdm:
+        iterator = tqdm.tqdm(iterator, desc="Act-Calibration")
+    with torch.no_grad():
+        for i in iterator:
+            inputs = ids[:, i : i + args.stride]
+            model(inputs)  # observers collect act. ranges
+
+    # Remove save hooks now that FP activations are cached
+    for h in save_handles:
+        h.remove()
+
+    # Freeze (scale, zero-point) after calibration
+    convert(model)
+
+    # Register diff hooks and measure per-layer deltas
+    cmp_handles = compare_layer_outputs(model, act_cache, metrics=["diff", "peir"])
+    # Use same inputs for comparison.
+    with torch.no_grad():
+        model(inputs)
+
+    assert isinstance(cmp_handles, list)
+    for h in cmp_handles:
+        h.remove()
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception as e:
+        print(f"\n[Error] {e}", file=sys.stderr)
+        sys.exit(1)

tico/quantization/wrapq/examples/quantize_linear.py

@@ -0,0 +1,107 @@
+# 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.
+
+# =============================================================================
+# POST-TRAINING QUANTIZATION EXAMPLE — Simple Linear Model
+# -----------------------------------------------------------------------------
+# This demo shows a minimal PTQ flow for a toy model:
+#   1. Define a simple model with a single Linear layer.
+#   2. Replace the FP32 Linear with a QuantLinear wrapper.
+#   3. Run a short calibration pass to collect activation statistics.
+#   4. Freeze scales / zero-points and switch to INT-simulation mode.
+#   5. Compare INT vs FP32 outputs with a mean-absolute-diff check.
+#   6. Export the quantized model to a Circle format.
+# =============================================================================
+
+import pathlib
+
+import torch
+import torch.nn as nn
+
+from tico.quantization import convert, prepare
+from tico.quantization.config.ptq import PTQConfig
+from tico.quantization.evaluation.metric import compute_peir
+from tico.quantization.evaluation.utils import plot_two_outputs
+from tico.quantization.wrapq.mode import Mode
+from tico.quantization.wrapq.wrappers.nn.quant_linear import QuantLinear
+from tico.utils.utils import SuppressWarning
+
+
+# -------------------------------------------------------------------------
+# 0. Define a toy model (1 Linear layer only)
+# -------------------------------------------------------------------------
+class TinyLinearModel(nn.Module):
+    """A minimal model: single Linear layer."""
+
+    def __init__(self, in_features=16, out_features=8):
+        super().__init__()
+        self.fc = nn.Linear(in_features, out_features, bias=False)
+
+    def forward(self, x):
+        return self.fc(x)
+
+
+# Instantiate FP32 model
+model = TinyLinearModel()
+model.eval()
+
+# Keep FP32 reference for diff check
+fp32_layer = model.fc
+
+# -------------------------------------------------------------------------
+# 1. Replace the Linear with QuantLinear wrapper
+# -------------------------------------------------------------------------
+model.fc = prepare(fp32_layer, PTQConfig())  # type: ignore[assignment]
+qlayer = model.fc  # alias for brevity
+
+# -------------------------------------------------------------------------
+# 2. Single-pass calibration (collect activation ranges)
+# -------------------------------------------------------------------------
+assert isinstance(qlayer.wrapped, QuantLinear)
+with torch.no_grad():
+    for _ in range(16):  # small toy batch
+        x = torch.randn(4, 16)  # (batch=4, features=16)
+        _ = model(x)
+
+convert(qlayer)
+
+assert qlayer._mode is Mode.QUANT, "Quantization mode should be active now."
+
+# -------------------------------------------------------------------------
+# 3. Quick INT-sim vs FP32 sanity check
+# -------------------------------------------------------------------------
+x = torch.randn(2, 16)
+with torch.no_grad():
+    int8_out = model(x)
+    fp32_out = fp32_layer(x)
+
+print("┌───────────── Quantization Error Summary ─────────────")
+print(f"│ Mean |diff|: {(int8_out - fp32_out).abs().mean().item():.6f}")
+print(f"│ PEIR       : {compute_peir(fp32_out, int8_out) * 100:.6f} %")
+print("└──────────────────────────────────────────────────────")
+print(plot_two_outputs(fp32_out, int8_out))
+
+# -------------------------------------------------------------------------
+# 4. Export the calibrated model to Circle
+# -------------------------------------------------------------------------
+import tico
+
+save_path = pathlib.Path("tiny_linear.q.circle")
+example_input = torch.randn(1, 16)
+
+with SuppressWarning(UserWarning, ".*"):
+    cm = tico.convert(model, (example_input,))  # forward(x) only
+cm.save(save_path)
+
+print(f"Quantized Circle model saved to {save_path.resolve()}")