Merge branch 'lab/docs-v1-1-0' into export/v1-1-0

aki916f · aki916f · commit c1b8ce81bf27 · 2026-04-28T12:13:51.000Z
- Add overview figure, ArXiv citation, and quick-start usage to README
- Fix pre-process and DBF docs to match v1.1.0 API signatures
- Add LPCD documentation

See merge request onecomp/onecomp-lab!57
diff --git a/README.md b/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).
diff --git a/docs/algorithms/dbf.md b/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:
diff --git a/docs/index.md b/docs/index.md
@@ -2,17 +2,45 @@
 
 **Open-source Python library for post-training quantization of Large Language Models**
 
+<p align="center">
+  <img src="../figs/onecomp.gif" alt="OneComp" />
+</p>
+
 ---
 
 Fujitsu One Compression (OneComp) is an open-source Python library for post-training quantization of Large Language Models (LLMs).
 It implements state-of-the-art quantization algorithms including GPTQ, DBF, RTN, and the
 research methods **Quantization Error Propagation (QEP)** and
 **Layer-Projected Coordinate Descent (LPCD)**.
 
+## 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.
+
+=== "CLI"
+
+    ```bash
+    onecomp meta-llama/Llama-2-7b-hf
+    ```
+
+=== "Python"
+
+    ```python
+    from onecomp import Runner
+
+    Runner.auto_run(model_id="meta-llama/Llama-2-7b-hf")
+    ```
+
+For full control over each step, see the [step-by-step workflow](user-guide/basic-usage.md#detailed-workflow).
+
 ## Key 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.
-- **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. See the [setup guide](user-guide/vllm-inference.md#3-chat-with-open-webui-optional).
 - **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).
@@ -91,11 +119,14 @@ If you use OneComp in your research, please cite our paper:
 OneComp technical report (coming soon on ArXiv):
 
 ```bibtex
-@misc{onecomp2026,
-  title={TBD},
-  author={TBD},
-  year={2026},
-  note={arXiv preprint coming soon}
+@misc{ichikawa2026onecomponelinerevolutiongenerative,
+      title={OneComp: One-Line Revolution for Generative AI Model Compression}, 
+      author={Yuma Ichikawa and Keiji Kimura and Akihiro Yoshida and Yudai Fujimoto and Hiroki Tokura and Yamato Arai and Yoshiyuki Ishii and Yusei Kawakami and Genki Shikada and Achille Jacquemond and Yoshihiko Fujisawa and Katsuki Fujisawa and Takumi Honda and Akira Sakai},
+      year={2026},
+      eprint={2603.28845},
+      archivePrefix={arXiv},
+      primaryClass={cs.LG},
+      url={https://arxiv.org/abs/2603.28845}, 
 }
 ```
 
diff --git a/docs/user-guide/pre-process.md b/docs/user-guide/pre-process.md
@@ -39,6 +39,28 @@ runner = Runner(model_config=rotated_config, quantizer=gptq)
 runner.run()
 ```
 
+### Custom calibration data
+
+Pass a `CalibrationConfig` to control the calibration dataset, sequence length,
+or sample count used during rotation training. See
+[Configuration › CalibrationConfig](configuration.md#calibrationconfig) for the
+full parameter list.
+
+```python
+from onecomp import CalibrationConfig, prepare_rotated_model
+
+rotated_config = prepare_rotated_model(
+    model_config=model_config,
+    save_directory="./rotated_model",
+    wbits=4,
+    groupsize=128,
+    calibration_config=CalibrationConfig(
+        max_length=2048,
+        num_calibration_samples=256,
+    ),
+)
+```
+
 ## Supported Architectures
 
 | Architecture | Status |
@@ -62,14 +84,13 @@ runner.run()
 | `norm` | Lp norm exponent for MSE search | `2.4` |
 | `grid` | Number of candidate shrink levels for MSE search | `100` |
 | `fp32_had` | Use FP32 for online Hadamard transform | `False` |
-| `num_calibration_samples` | Number of calibration samples | `512` |
-| `calibration_strategy` | Calibration strategy: `"concat_chunk"`, `"concat_chunk_align"`, `"drop_head"`, `"drop_rand"` | `"drop_rand"` |
-| `seed` | Seed for rotation init and calibration data | `0` |
+| `calibration_config` | Calibration data configuration. See [`CalibrationConfig`](configuration.md#calibrationconfig). When `None`, a default `CalibrationConfig()` is used. | `None` |
+| `seed` | Seed for rotation matrix initialisation. The calibration-data seed is controlled by `calibration_config.seed`. | `0` |
 
 !!! note "Input validation"
     `prepare_rotated_model` validates all parameters on entry. Invalid values for
-    `rotation_mode`, `scaling_mode`, `calibration_strategy`, or out-of-range numeric
-    parameters (e.g. `wbits < 1`, `grid < 1`) raise `ValueError`.
+    `rotation_mode`, `scaling_mode`, `calibration_config.strategy`, or out-of-range
+    numeric parameters (e.g. `wbits < 1`, `grid < 1`) raise `ValueError`.
 
 !!! warning "Parameter matching"
     The `wbits`, `groupsize`, and `sym` parameters **must match** the quantizer
diff --git a/figs/onecomp.gif b/figs/onecomp.gif
