Merge pull request #11 from FujitsuResearch/develop/v1-1-0

Develop/v1 1 0

Author: FKKimura

.gitignore

@@ -6,17 +6,25 @@ build/
 models
 .vscode/
 .cursor/rules/benchmark-directory.mdc
+.cursor/rules/example-workflow.mdc
 .cursor/rules/merge-request-review.mdc
 .cursor/rules/test-workflow.mdc
+.cursor/rules/gitlab-integration.mdc
+.cursor/rules/slurm-submit.mdc
 .hydra/
 *.out
 *.err
 md/*.md
 example/run_example.sh
-work/issue-*
+work/
 site/
 debug_code/
 .pytest_cache/
 *.pt
 # Large test data (download separately if needed for regression tests)
 tests/onecomp/quantizer/jointq/data/model_layers_0_self_attn_k_proj.pth
+.uv-sync.lock
+.uv-sync.done
+.uv-sync-vllm.lock
+.uv-sync-vllm.done
+.venv-vllm/

CHANGELOG.md

@@ -2,16 +2,43 @@
 
 Fujitsu One Compression (OneComp) is a Python package for LLM compression.
 
+<p align="center">
+  <img src="docs/assets/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).
-- **vLLM Plugin Integration**: Serve OneComp-quantized models with [vLLM](https://docs.vllm.ai/) via built-in plugins for DBF and Mixed-GPTQ quantization methods.
+- **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).
+- **Block-wise PTQ**: Post-quantization block-wise distillation that minimises intermediate-representation MSE against an FP16 teacher model at Transformer-block granularity. Includes Phase 1 (greedy per-block optimisation) and Phase 2 CBQ (cross-block sliding-window optimisation). Supports GPTQ, DBF, and OneBit quantizers.
 - **LoRA SFT Post-Process**: Fine-tune quantized models with LoRA adapters for accuracy recovery or domain-specific knowledge injection. Supports SFT loss, teacher distillation, and intermediate block alignment.
 - **Rotation Preprocessing**: SpinQuant/OstQuant-based rotation preprocessing that reduces quantization error by learning optimal rotation matrices before quantization. Rotation/scaling matrices are absorbed into model weights, with online Hadamard hooks automatically registered at load time. Supports Llama and Qwen3 architectures.
 - (TBD)
@@ -25,6 +52,8 @@ Other Hugging Face-compatible models may work but are currently untested.
 |---|-------------|-----------------|--------|
 | 1 | Llama | TinyLlama, Llama-2, Llama-3 | ✅ Verified |
 | 2 | Qwen3 | Qwen3-0.6B ~ 32B | ✅ Verified |
+| 3 | Gemma | Gemma 2, Gemma 3, Gemma 4  | ✅ Verified |
+
 
 > **Note:** Support for additional architectures is planned. Contributions and test reports are welcome.
 
@@ -52,6 +81,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
@@ -97,18 +127,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)
@@ -119,7 +152,7 @@ In the environment created by `uv sync`, you can run commands in two ways:
 
 ```bash
 uv run pytest tests/ -v
-uv run python example/example1.py
+uv run python example/example_gptq.py
 uv run black --check onecomp/
 ```
 
@@ -128,7 +161,7 @@ uv run black --check onecomp/
 ```bash
 source .venv/bin/activate
 pytest tests/ -v
-python example/example1.py
+python example/example_gptq.py
 black --check onecomp/
 ```
 
@@ -144,7 +177,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
@@ -162,30 +195,34 @@ Then open [http://127.0.0.1:8000](http://127.0.0.1:8000) in your browser.
 |----------|--------|-------------|
 | Quantization | [example_gptq.py](./example/example_gptq.py) | GPTQ quantization |
 | | [example_qep_gptq.py](./example/example_qep_gptq.py) | GPTQ + QEP (error propagation) |
+| | [example_lpcd_gptq.py](./example/example_lpcd_gptq.py) | GPTQ + QEP + LPCD quantization |
 | | [example_jointq.py](./example/example_jointq.py) | JointQ quantization |
 | | [example_autobit.py](./example/example_autobit.py) | AutoBit mixed-precision quantization |
 | | [example_auto_run.py](./example/example_auto_run.py) | AutoBit with automatic VRAM estimation |
+| Calibration | [example_custom_calibration.py](./example/example_custom_calibration.py) | Custom calibration dataset with CalibrationConfig |
 | Save / Load | [example_save_load.py](./example/example_save_load.py) | Save and load quantized models |
 | Rotation Preprocessing | [example_llama_preprocess_rtn.py](./example/pre_process/example_llama_preprocess_rtn.py) | Rotation preprocessing + RTN (TinyLlama) |
 | | [example_preprocess_save_load.py](./example/pre_process/example_preprocess_save_load.py) | Save and load rotation-preprocessed quantized models |
-| Post-Process | [example_lora_sft.py](./example/post_process/example_lora_sft.py) | LoRA SFT post-quantization fine-tuning |
+| Post-Process | [example_blockwise_ptq.py](./example/post_process/example_blockwise_ptq.py) | Block-wise PTQ (GPTQ + Phase 1 & CBQ) |
+| | [example_lora_sft.py](./example/post_process/example_lora_sft.py) | LoRA SFT post-quantization fine-tuning |
 | | [example_lora_sft_knowledge.py](./example/post_process/example_lora_sft_knowledge.py) | LoRA SFT knowledge injection |
 | vLLM | [example_gptq_vllm_inference.py](./example/vllm_inference/example_gptq_vllm_inference.py) | GPTQ + QEP quantization and vLLM inference |
 | | [example_autobit_vllm_inference.py](./example/vllm_inference/example_autobit_vllm_inference.py) | AutoBit quantization and vLLM inference |
 
 ## 🔌 vLLM Inference
 
 OneComp-quantized models can be served with [vLLM](https://docs.vllm.ai/) via built-in plugins (DBF, Mixed-GPTQ).
+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
 ```
 
-See the [vLLM Inference guide](https://FujitsuResearch.github.io/OneCompression/user-guide/vllm-inference/) for details.
+See the [vLLM Inference guide](https://FujitsuResearch.github.io/OneCompression/user-guide/vllm-inference/) for details, including Open WebUI setup instructions.
 
 
 ## 📄 License
@@ -220,3 +257,15 @@ year={2025},
 url={https://openreview.net/forum?id=a3l3K9khbL}
 }
 ```
+
+LPCD (Layer-Projected Coordinate Descent):
+
+```
+@article{ichikawa2025lpcd,
+title={LPCD: Unified Framework from Layer-Wise to Submodule Quantization},
+author={Yuma Ichikawa and Yudai Fujimoto and Akira Sakai},
+journal={arXiv preprint arXiv:2512.01546},
+year={2025},
+url={https://arxiv.org/abs/2512.01546}
+}
+```

README.md

@@ -0,0 +1 @@
+count_accepted_lambda.py