merge export/v1-1-0 and resolve conflict

Author: aki916f

CHANGELOG.md

@@ -129,6 +129,8 @@
 
 ### Bug Fix
 
+- Fixed `model_config.py`: `load_model()` VLM fallback did not trigger for models raising `"Unrecognized configuration class"` (e.g. Cohere2VisionForConditionalGeneration). Added the error pattern to `_vlm_hints`
+- Fixed `gptq/_gptq.py`: Cholesky decomposition in `run_gptq` could fail with `LinAlgError` on ill-conditioned Hessians (observed on large VLMs at deeper layers). Extracted `_compute_inverse_hessian()` with progressive damping fallback (up to 5 retries, 10x damping increase per retry). No impact on normal operation
 - Fixed `TypeError` in `QuantLinear.forward` when `S_qk` scaling was applied to MLP layers (`onecomp/pre_process/quant_models.py`)
 - Fixed wrong module grouping in `make_grouped_module` where GC-driven `id()` reuse caused attention projections (q/k/v) and MLP projections (gate/up) to be merged into the same group.  (`qep/_quantize_with_qep_arch.py`)
 - Fixed silent weight corruption in `GPTQLinear` when `qzero=0` was stored through the GPTQ v1 zero-point path (`onecomp/quantizer/gptq/gptq_layer.py`)
@@ -138,6 +140,14 @@
   - Added regression tests for per-slot pack corruption, packed/unpacked forward paths, the `gptq_v2` branch, and the `from_saved_state` path for GPTQ v1 tensors
   - **NOTE**: If you have GPTQ models quantized with previous versions, please re-quantize them with this release, as they may contain corrupted internal data.
 
+### Packaging
+
+- Bumped minimum `transformers` requirement from `>=5.3.0` to `>=5.5.0` (`pyproject.toml`)
+- Added `cu130` optional-dependency extra and the `pytorch-cu130` wheel index (`https://download.pytorch.org/whl/cu130`) for CUDA 13 hosts (e.g. NVIDIA B200) (`pyproject.toml`)
+- Pinned the `vllm` extra to `vllm>=0.10` to prevent uv from falling back to legacy versions whose source build requires `CUDA_HOME` (`pyproject.toml`)
+- Added uv `conflicts` declarations between the `vllm` extra and the `cpu` / `cu118` / `cu121` / `cu124` / `cu126` / `cu128` extras: vLLM `>=0.20` requires `torch>=2.10`, which is only published for `cu130`. This forces `vllm` to be installed only with `--extra cu130` and prevents silent fallback to a `vllm` version incompatible with `transformers>=5` at runtime (`pyproject.toml`)
+- Restricted `tool.uv.environments` to `sys_platform == 'linux'` and `python_full_version >= '3.12', < '3.14'` to skip lock splits for unused Windows and out-of-range Python versions (`pyproject.toml`)
+
 ### Examples
 
 - Added `example/example_custom_calibration.py`: Demonstrates `CalibrationConfig` with a custom calibration dataset (Python code snippets in `example/data/python_calibration.txt`).  Quantizes TinyLlama with GPTQ 3-bit using both default C4 and custom Python-code calibration, then compares inference outputs across multiple prompts to show how calibration data choice affects quantization quality.
@@ -167,6 +177,7 @@
 - Added `docs/api/quantizers/onebit.md` (OneBit API reference)
 - Updated `mkdocs.yml` nav: added AutoBit/JointQ algorithm pages, OneBit API page; renamed Post-Process nav title to include Block-wise PTQ
 - Added example script links to `docs/user-guide/pre-process.md`
+- Added a Troubleshooting section to `docs/user-guide/vllm-inference.md` describing how to bypass the unconditional DeepGEMM (FP8) kernel warmup for non-FP8 quantization (GPTQ / DBF / Mixed-GPTQ) by setting `VLLM_USE_DEEP_GEMM=0` and `VLLM_DEEP_GEMM_WARMUP=skip`
 
 ### Tests
 

README.md

@@ -2,14 +2,39 @@
 
 Fujitsu One Compression (OneComp) is a Python package for LLM compression.
 
+<p align="center">
+  <img src="figs/onecomp.gif" alt="OneComp" />
+</p>
+
+## ⚡ Just one line.
+
+```bash
+onecomp <generative AI>
+```
+
+**That's all you need.** OneComp detects your GPU VRAM, picks the best bit-width per layer, quantizes with error propagation, evaluates, and saves — fully automatic.
+
+```bash
+# Example
+onecomp meta-llama/Llama-2-7b-hf
+```
+
+Or from Python:
+
+```python
+from onecomp import Runner
+
+Runner.auto_run(model_id="meta-llama/Llama-2-7b-hf")
+```
+
 ## 📖 Documentation
 
 Full documentation is available at **[https://FujitsuResearch.github.io/OneCompression/](https://FujitsuResearch.github.io/OneCompression/)**.
 
 ## 📦 Features
 
 - **Quantization Error Propagation (QEP)**: A post-training quantization method that corrects quantization errors by propagating them to subsequent layers, improving the accuracy of quantized LLMs. See [Arai & Ichikawa, NeurIPS 2025](https://openreview.net/forum?id=a3l3K9khbL) for details. The original reference implementation is available at [FujitsuResearch/qep](https://github.com/FujitsuResearch/qep).
-- **Layer-Projected Coordinate Descent (LPCD)**: A unified PTQ framework that extends layer-wise quantization to arbitrary submodules by optimising relaxed objectives and projecting the solutions with layer-wise quantizers. See [Ichikawa et al., 2025](https://arxiv.org/abs/2512.01546) for details.
+- **Layer-Projected Coordinate Descent (LPCD)**: A unified Post Training Quantization (PTQ) framework that extends layer-wise quantization to arbitrary submodules by optimising relaxed objectives and projecting the solutions with layer-wise quantizers. See [Ichikawa et al., 2025](https://arxiv.org/abs/2512.01546) for details.
 - **vLLM Plugin Integration**: Serve OneComp-quantized models with [vLLM](https://docs.vllm.ai/) via built-in plugins for DBF and Mixed-GPTQ quantization methods. Pair with [Open WebUI](https://github.com/open-webui/open-webui) for a ChatGPT-like chat experience on your local machine.
 - **AutoBit**: Mixed-precision quantization with ILP-based bitwidth assignment. Automatically estimates the target bitwidth from available VRAM and assigns per-layer bitwidths to minimize quantization error under the memory budget.
 - **JointQ**: Joint quantization method that optimizes weight assignments and scale parameters simultaneously for improved quantization accuracy. Supports group-wise quantization (e.g., 4-bit, groupsize=128).
@@ -54,6 +79,7 @@ Choose the appropriate CUDA version for your system:
 | CUDA 12.4    | `pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124` |
 | CUDA 12.6    | `pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu126` |
 | CUDA 12.8    | `pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128` |
+| CUDA 13.0    | `pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu130` |
 
 Check your CUDA version:
 ```bash
@@ -99,19 +125,21 @@ uv sync --extra cu128 --extra dev --extra visualize
 The `uv sync` command creates a Python virtual environment and installs all dependent libraries.
 
 The `--extra cu128` option installs the CUDA-enabled version of PyTorch (along with `torchvision` from the same CUDA index).
-Replace `cu128` with the appropriate variant for your environment: `cpu`, `cu118`, `cu121`, `cu124`, `cu126`, or `cu128`.
+Replace `cu128` with the appropriate variant for your environment: `cpu`, `cu118`, `cu121`, `cu124`, `cu126`, `cu128`, or `cu130`.
 PyTorch will be automatically downloaded by `uv`, so you do not need to install it beforehand.
 
 Adding `--extra dev` installs development tools (black, pytest, pylint).
 Adding `--extra visualize` installs matplotlib for visualization features.
 Adding `--extra hydra` installs `hydra-core` for the example scripts and `model_validation/` runners that use Hydra-based configuration.
 
-To use vLLM for serving quantized models, add `--extra vllm`:
+To use vLLM for serving quantized models, add `--extra vllm` together with `--extra cu130`:
 
 ```bash
-uv sync --extra cu128 --extra dev --extra visualize --extra vllm
+uv sync --extra cu130 --extra dev --extra visualize --extra vllm
 ```
 
+> **Note:** `--extra vllm` is only compatible with `--extra cu130`. Recent vLLM releases require `torch>=2.10`, whose wheels are only published for the `cu130` index. Combining `--extra vllm` with `cpu` / `cu118` / `cu121` / `cu124` / `cu126` / `cu128` is rejected by `uv` at lock time.
+
 > **Note:** `--extra vllm` may take a long time on the first run if a pre-built `xformers` wheel is not available for your Python/CUDA combination (e.g. Python 3.13). Using Python 3.12 typically avoids this.
 
 #### Running commands (uv environment)
@@ -147,7 +175,7 @@ pip install torch --index-url https://download.pytorch.org/whl/cu128
 pip install -e ".[dev]"
 ```
 
-Replace `cu128` with the appropriate variant for your environment: `cpu`, `cu118`, `cu121`, `cu124`, `cu126`, or `cu128`.
+Replace `cu128` with the appropriate variant for your environment: `cpu`, `cu118`, `cu121`, `cu124`, `cu126`, `cu128`, or `cu130`.
 
 
 ### Building Documentation Locally
@@ -185,8 +213,8 @@ OneComp-quantized models can be served with [vLLM](https://docs.vllm.ai/) via bu
 Combined with [Open WebUI](https://github.com/open-webui/open-webui), you can chat with your quantized model through a ChatGPT-like browser interface — entirely on your local machine.
 
 ```bash
-# uv users
-uv sync --extra cu128 --extra vllm
+# uv users (vLLM requires cu130; see Installation for details)
+uv sync --extra cu130 --extra vllm
 
 # pip users
 pip install vllm

benchmark/llama3-8b-jointq/.gitignore

@@ -54,3 +54,6 @@ llama3-8b-fixed-lam0.3/
 llama3-8b-fixed-lam0.5/
 llama3-8b-incremental/
 llama3-8b-incremental-actorder-mse/
+
+run_llama3-8b_diagonal_lam*_actorder.sh
+llama3-8b-diagonal-lam*-actorder/

benchmark/qwen3-14b-jointq/.gitignore

@@ -55,3 +55,6 @@ qwen3-14b-fixed-lam0.3/
 qwen3-14b-fixed-lam0.5/
 qwen3-14b-incremental/
 qwen3-14b-incremental-actorder-mse/
+
+run_qwen3-14b_diagonal_lam*_actorder.sh
+qwen3-14b-diagonal-lam*-actorder/

benchmark/qwen3-8b-jointq/.gitignore

@@ -55,3 +55,6 @@ qwen3-8b-fixed-lam0.3/
 qwen3-8b-fixed-lam0.5/
 qwen3-8b-incremental/
 qwen3-8b-incremental-actorder-mse/
+
+run_qwen3-8b_diagonal_lam*_actorder.sh
+qwen3-8b-diagonal-lam*-actorder/

docs/algorithms/dbf.md

@@ -25,32 +25,91 @@ with optional weight balancing.
 
 ## Parameters
 
-| Parameter       | Type    | Description                                  | Default    |
-|----------------|---------|----------------------------------------------|------------|
-| `target_bits`   | `float` | Target bit-width (e.g., 1.5)               | —          |
-| `iters`         | `int`   | Number of ADMM optimization iterations       | `100`      |
-| `reg`           | `float` | Regularization coefficient                   | `1.0`      |
-| `use_balancing` | `bool`  | Apply weight balancing before factorization   | `True`     |
-| `balance_iters` | `int`   | Number of balancing iterations                | `20`       |
-| `balance_alpha` | `float` | Balancing alpha parameter                     | `0.5`      |
+| Parameter            | Type                       | Description                                                                       | Default |
+|---------------------|----------------------------|-----------------------------------------------------------------------------------|---------|
+| `target_bits`        | `float`                    | Target bit-width (e.g., 1.5)                                                      | `1.5`   |
+| `iters`              | `int`                      | Number of ADMM optimization iterations                                            | `600`   |
+| `reg`                | `float`                    | Regularization coefficient                                                        | `3e-2`  |
+| `use_balancing`      | `bool`                     | Apply weight balancing before factorization                                       | `True`  |
+| `balance_iters`      | `int`                      | Number of balancing iterations                                                    | `40`    |
+| `balance_alpha`      | `float`                    | Balancing alpha parameter                                                         | `1.0`   |
+| `balance_mode`       | `str`                      | Balancing mode (`"l1"` or `"l2"`)                                                 | `"l1"`  |
+| `use_adaptive_rho`   | `bool`                     | Adapt the ADMM penalty parameter ρ during optimization                            | `True`  |
+| `mlp_target_bits`    | `Optional[float]`          | Override `target_bits` for layers whose name contains `"mlp"`                     | `None`  |
+| `module_target_bits` | `Optional[dict[str,float]]`| Per-layer override of `target_bits`, keyed by exact layer name (highest priority) | `None`  |
 
 ## Usage
 
+### Quick Start
+
+For a first run, use a small model (TinyLlama) and a lightweight calibration
+configuration. This combination fits in a few GB of GPU memory and is the
+recommended way to verify the pipeline end-to-end.
+
 ```python
-from onecomp import ModelConfig, Runner
+from onecomp import CalibrationConfig, ModelConfig, Runner
 from onecomp.quantizer.dbf import DBF
 
 model_config = ModelConfig(
-    model_id="meta-llama/Llama-2-7b-hf",
+    model_id="TinyLlama/TinyLlama-1.1B-intermediate-step-1431k-3T",
     device="cuda:0",
 )
+calib_config = CalibrationConfig(
+    max_length=512,
+    num_calibration_samples=128,
+)
+dbf = DBF(target_bits=1.5)
+runner = Runner(
+    model_config=model_config,
+    quantizer=dbf,
+    calibration_config=calib_config,
+)
+runner.run()
+```
+
+### Recommended Configuration
 
-dbf = DBF(target_bits=1.5, iters=100, use_balancing=True)
+For production use, run with longer sequences and more calibration samples to
+improve quantization quality. DBF holds fp32 ADMM buffers in addition to the
+model weights, so the per-forward GPU memory consumption is higher than GPTQ.
+To avoid `CUDA out of memory` with the default calibration settings on larger
+models such as Llama-2-7B, set `CalibrationConfig.batch_size` to enable
+chunked calibration.
+
+```python
+from onecomp import CalibrationConfig, ModelConfig, Runner
+from onecomp.quantizer.dbf import DBF
 
-runner = Runner(model_config=model_config, quantizer=dbf)
+model_config = ModelConfig(
+    model_id="meta-llama/Llama-2-7b-hf",
+    device="cuda:0",
+)
+calib_config = CalibrationConfig(
+    max_length=2048,
+    num_calibration_samples=128,  # Increase to 256-512 for higher accuracy
+    batch_size=32,                # Tune to GPU free memory (8-32)
+)
+dbf = DBF(target_bits=1.5)
+runner = Runner(
+    model_config=model_config,
+    quantizer=dbf,
+    calibration_config=calib_config,
+)
 runner.run()
 ```
 
+!!! note "Tuning `batch_size` to your GPU"
+    `CalibrationConfig.batch_size` controls the number of calibration sequences
+    forwarded through the model at once, and is the main knob for peak GPU
+    memory. Rough guideline:
+
+    - H100 (80 GB): `batch_size=32`
+    - A100 (40 GB): `batch_size=16`
+    - When sharing the GPU with other processes: `batch_size=8`
+
+    If you still hit `CUDA out of memory`, halve the value until the run
+    succeeds.
+
 ## Save and Load
 
 DBF models can be saved in a format compatible with the OneComp loader:

docs/getting-started/installation.md

@@ -49,6 +49,12 @@ Install the appropriate version of PyTorch for your system.
     pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128
     ```
 
+=== "CUDA 13.0"
+
+    ```bash
+    pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu130
+    ```
+
 Check your CUDA version:
 
 ```bash
@@ -92,17 +98,20 @@ uv sync --extra cu128 --extra dev --extra visualize
 ```
 
 The `uv sync` command creates a virtual environment and installs all dependencies (including `torchvision` from the same CUDA index as PyTorch).
-Replace `cu128` with the appropriate CUDA variant for your system: `cpu`, `cu118`, `cu121`, `cu124`, `cu126`, or `cu128`.
+Replace `cu128` with the appropriate CUDA variant for your system: `cpu`, `cu118`, `cu121`, `cu124`, `cu126`, `cu128`, or `cu130`.
 
 Adding `--extra dev` installs development tools (black, pytest, pylint).
 Adding `--extra visualize` installs matplotlib for visualization features.
 
-To use vLLM for serving quantized models, add `--extra vllm`:
+To use vLLM for serving quantized models, add `--extra vllm` together with `--extra cu130`:
 
 ```bash
-uv sync --extra cu128 --extra dev --extra visualize --extra vllm
+uv sync --extra cu130 --extra dev --extra visualize --extra vllm
 ```
 
+!!! note "vLLM requires the `cu130` extra"
+    Recent vLLM releases depend on `torch>=2.10`, whose wheels are only published for the `cu130` index. The `--extra vllm` declaration in `pyproject.toml` therefore conflicts with `cpu`, `cu118`, `cu121`, `cu124`, `cu126`, and `cu128`; combining any of these with `--extra vllm` is rejected by `uv` at lock time.
+
 !!! warning
     Do **not** install vLLM with `uv pip install vllm` after `uv sync`. Packages installed via `uv pip` are not tracked by the lockfile and will be removed or overwritten by subsequent `uv sync` or `uv run` commands. Always use `--extra vllm` instead.