FujitsuResearch
diff --git a/‎CHANGELOG.md‎
Lines changed: 76 additions & 0 deletions b/‎CHANGELOG.md‎
Lines changed: 76 additions & 0 deletions
diff --git a/‎README.md‎
Lines changed: 2 additions & 1 deletion b/‎README.md‎
Lines changed: 2 additions & 1 deletion
diff --git a/‎docs/algorithms/jointq.md‎
Lines changed: 26 additions & 1 deletion b/‎docs/algorithms/jointq.md‎
Lines changed: 26 additions & 1 deletion
diff --git a/‎docs/algorithms/rtn.md‎
Lines changed: 27 additions & 0 deletions b/‎docs/algorithms/rtn.md‎
Lines changed: 27 additions & 0 deletions
diff --git a/‎docs/api/quantizers/base.md‎
Lines changed: 18 additions & 3 deletions b/‎docs/api/quantizers/base.md‎
Lines changed: 18 additions & 3 deletions
diff --git a/‎docs/getting-started/quickstart.md‎
Lines changed: 1 addition & 1 deletion b/‎docs/getting-started/quickstart.md‎
Lines changed: 1 addition & 1 deletion
@@ -1,11 +1,87 @@
 # Change log
 
+
 ## [v1.2.0] 2026-06-04 (WIP)
 
 ### for Developer: pre-commit
 
 - Added `.pre-commit-config.yaml` with `black`, `isort`, and local hooks (`no-japanese`, `copyright-header`, `no-email-address`); install with `uv sync --extra dev` then `pre-commit install` (see README)
 
+### Save/Load Support for JointQ, RTN, and OneBit Quantizers
+
+- **JointQ**: Added `get_quant_config()`, `finalize_quant_config_for_save()`, and `create_inference_layer()` to `JointQ` class (`onecomp/quantizer/jointq/_jointq.py`)
+  - Emits `quant_method="gptq"` to reuse `GPTQLinear` and vLLM GPTQ plugin (JointQ uses the same scale/zero/assignment structure as GPTQ)
+  - `create_inference_layer()` converts JointQ's 3D assignment `(out_features, num_groups, group_size)` to 2D qweight `(out_features, in_features)` matching GPTQ format, with scale/zero transposition
+  - Handles `actorder` permutation: restores original column order before passing to `GPTQLinear` so `g_idx` is constructed correctly
+  - Symmetric quantization: shifts signed integers `[-2^(n-1), 2^(n-1)-1]` to unsigned `[0, 2^n - 1]` for GPTQLinear bit packing
+  - Added `bits == 1` warning in `validate_params()`: GPTQLinear weight packing does not support 1-bit; inference layer must be built with `pack_weights=False`
+  - Added `_build_quantization_bits()` static method to emit per-layer `quantization_bits` metadata for mixed-precision save
+- **RTN**: Added `get_quant_config()`, `finalize_quant_config_for_save()`, `create_inference_layer()`, and `RTNResult.compute_dequantized_weight()` to `RTN` class (`onecomp/quantizer/rtn/_rtn.py`)
+  - Emits `quant_method="gptq"` to reuse `GPTQLinear` and vLLM GPTQ plugin (RTN uses the same qweight/scales/qzeros tensor format)
+  - `compute_dequantized_weight()` implements `W = (quantized_weight - zero) * scale` with per-channel and group-wise paths
+  - `create_inference_layer()` transposes scale/zero from `(out_features, num_groups)` to `(num_groups, out_features)` for GPTQLinear compatibility
+  - Added `_build_quantization_bits()` static method for per-layer metadata
+- **OneBit**: Added `get_quant_config()`, `finalize_quant_config_for_save()`, `create_inference_layer()`, and `OnebitResult.compute_dequantized_weight()` to `Onebit` class (`onecomp/quantizer/onebit/_onebit.py`)
+  - Emits `quant_method="onebit"` with OneBit-specific parameters (`iters`, `use_importance_scaling`, `use_balancing`, `balance_iters`, `balance_alpha`)
+  - `compute_dequantized_weight()` implements `W ≈ a[:, None] * sign * b[None, :]`
+  - `create_inference_layer()` builds `OneBitLinear` via `OneBitLinear.from_quantization_result()`
+  - Added `_build_quantization_bits()` static method for per-layer metadata
+
+### OneBitLinear Inference Layer Improvements
+
+- Added `OneBitLinear.from_quantization_result()` class method: builds `OneBitLinear` from `OnebitResult` (mirrors the pattern used by `GPTQLinear` and `DoubleBinaryLinear`) (`onecomp/quantizer/onebit/onebit_layer.py`)
+- Added `OneBitLinear.from_saved_state()` class method: reconstructs `OneBitLinear` from saved `state_dict` tensors (`a`, `b`, `sign_packed`, optional `bias`), using the same `cls.__new__` pattern as `DoubleBinaryLinear` (`onecomp/quantizer/onebit/onebit_layer.py`)
+- Removed `preunpack` parameter from `OneBitLinear.__init__()` and `replace_linear_with_onebit_layer()`: sign matrix is now always stored as packed `uint8` and unpacked on demand during `forward()`, matching the DBF inference layer pattern (`onecomp/quantizer/onebit/onebit_layer.py`)
+- Normalized buffers to FP16 with `detach()` in `OneBitLinear.__init__()` to drop autograd graph
+- Added `_load_from_state_dict()` override to clear `sign_matrix` cache when loading from checkpoint
+- Extracted `_unpack_sign_matrix()` helper for sign matrix unpacking logic
+- Removed unreferenced functions `replace_linear_with_onebit_layer()` and `extract_onebit_weights_for_save()` from `onebit_layer.py`: layer construction is now handled by `OneBitLinear.from_quantization_result()` / `OneBitLinear.from_saved_state()`, and save-time weight extraction is covered by the unified `create_inference_layer()` / `state_dict()` path (`onecomp/quantizer/onebit/onebit_layer.py`)
+
+### QuantizedModelLoader: OneBit Support
+
+- `QuantizedModelLoader` now supports `quant_method="onebit"` (`onecomp/quantized_model_loader.py`)
+  - Added `OneBitLinear` to import and layer replacement logic
+  - Added `OneBitLinear.from_saved_state()` call path for creating empty OneBit layers during model loading
+  - Hadamard hook registration now recognizes `OneBitLinear` as a quantized layer class
+
+### BlockWisePTQ / CBQ OneBit Optimizer Compatibility
+
+- Updated OneBit block-wise and cross-block quantization (CBQ) optimizers to work with packed-only `OneBitLinear` (`onecomp/post_process/_blockwise/onebit_block_optimizer.py`, `onecomp/post_process/_blockwise/onebit_cbq_optimizer.py`)
+  - Reads current sign matrices from `sign_packed` via `my_unpack()` when `sign_matrix` is not present, while still allowing `sign_matrix` as a temporary optimization override
+  - Writes sign updates back to `sign_packed` with `my_pack()` and clears `sign_matrix` so packed signs remain the single source of truth after hard evaluation, best-state restore, and final updates
+  - Hoisted `my_pack` / `my_unpack` imports in the OneBit CBQ optimizer
+- Clarified `OneBitLinear.sign_matrix` as a non-persistent temporary override used by optimization flows such as BlockWisePTQ and CBQ (`onecomp/quantizer/onebit/onebit_layer.py`)
+
+### Bug Fix
+
+- Fixed `GPTQLinear.from_saved_state()`: `_weight_is_packed` now defaults to `False` when `wbits == 1` (JointQ `wbits=1` checkpoints are saved with `pack_weights=False` because GPTQLinear packing does not support 1-bit) (`onecomp/quantizer/gptq/gptq_layer.py`)
+- Fixed redundant symmetric shift in RTN inference layer (`onecomp/quantizer/rtn/_rtn.py`)
+- Fixed `run_onebit()` returning `False` on NaN/Inf detection; now raises `ValueError` with proper GPU tensor cleanup to prevent OOM cascading (`onecomp/quantizer/onebit/onebit_impl.py`)
+- Removed pre-computed `dequantized_weight` from `run_onebit()` return dict and `OnebitResult`; dequantized weight is now computed on demand via `compute_dequantized_weight()` (`onecomp/quantizer/onebit/onebit_impl.py`, `onecomp/quantizer/onebit/_onebit.py`)
+- `QuantizedModelLoader._cast_fp16_to_target_dtype()` now skips `OneBitLinear` in addition to `GPTQLinear` and `DoubleBinaryLinear`, so OneBit's fp16 scaling buffers (`a`, `b`, `bias`) are preserved when loading a OneBit-quantized model that requires `bfloat16` (e.g. Gemma 3 / Gemma 4 detected via `needs_bfloat16`). Without this, the post-load safety-net cast rewrote OneBit's stored fp16 metadata to `bfloat16`, breaking the dtype contract that `OneBitLinear.forward` relies on (`self.a.to(x.dtype)` / `self.b.to(x.dtype)` casts to the activation dtype at compute time). Updated the function's docstring to list `OneBitLinear` alongside the other quantized layer types whose fp16 metadata is intentionally retained (`onecomp/quantized_model_loader.py`).
+
+### Tests
+
+- Enabled inherited `test_forward_error` tests for JointQ, OneBit, and RTN (previously skipped with `"does not support create_inference_layer"`) (`tests/onecomp/quantizer/jointq/test_jointq.py`, `tests/onecomp/quantizer/onebit/test_onebit.py`, `tests/onecomp/quantizer/rtn/test_rtn.py`)
+- Added `_forward_error_features` class attribute to `BaseQuantizeSpec` for parameterizing layer size in `test_forward_error`; JointQ overrides to `32` (requires `in_features` divisible by `pack_factor = 32 // wbits`) (`tests/onecomp/quantizer/test_module.py`)
+- Changed JointQ test default `bits` from `1` to `2` to match GPTQLinear packing constraints (`tests/onecomp/quantizer/jointq/test_jointq.py`)
+- Updated `check_equal_results` in RTN and OneBit tests to use `compute_dequantized_weight()` instead of direct `dequantized_weight` attribute access
+- Updated `apply_quantized_weights` in RTN and OneBit tests to use `compute_dequantized_weight()` with proper dtype preservation
+
+### Documentation
+
+- Documented save/load and vLLM compatibility for the newly-supported **JointQ**, **RTN**, and **OneBit** quantizers across the docs:
+  - `docs/api/quantizers/base.md`: moved `JointQ`, `RTN`, and `Onebit` into the supported rows of the "Quantizer Feature Support" table (`get_quant_config` / `create_inference_layer` / Save / Quantized PPL/ACC all Yes), and added a new "Saved `quant_method` and vLLM compatibility" table mapping each quantizer to its emitted `quant_method` (`gptq` / `mixed_gptq` / `dbf` / `onebit`) and serving path
+  - `docs/user-guide/basic-usage.md`: updated the quantized-model evaluation note and the "Quantizer feature support" table to include JointQ/RTN/OneBit, added a `quant_method` column, and clarified which saved models are vLLM-servable
+  - `docs/user-guide/vllm-inference.md`: rewrote the "Supported Quantization Methods" table to distinguish vLLM's **built-in** GPTQ plugin (used for `gptq`: GPTQ uniform bits, JointQ, RTN) from the **OneComp** plugins (`mixed_gptq`, `dbf`), added a note that `Onebit` is not vLLM-servable, and listed the GPTQ/JointQ/AutoBit end-to-end examples; split the `gptq` row so GPTQ/RTN (`wbits` in {2, 3, 4, 8}) and JointQ (`bits` in {2, 3, 4}; `bits=1` is OneComp load-only with `pack_weights=False`) document their distinct supported bit-widths
+  - `docs/algorithms/jointq.md`: added a "Save and Load" section (emits `quant_method="gptq"`, served by vLLM's built-in GPTQ plugin), a note that JointQ `bits` is limited to {2, 3, 4} for vLLM (the JointQ core quantizer rejects `bits > 4`) while `bits=1` requires an explicit `runner.save_quantized_model(..., pack_weights=False)` and is OneComp load-only / not vLLM-servable, and clarified that JointQ does not support QEP (`qep=False`)
+  - `docs/algorithms/rtn.md`: added a "Save and Load" section, a note that vLLM serving uses `wbits` in {2, 3, 4, 8} (RTN itself accepts a wider range, but GPTQ-compatible bit packing and vLLM serving are limited to these), and a warning that rotation-preprocessed RTN models cannot be served with vLLM (no online Hadamard transform), though they remain loadable with `load_quantized_model()`
+  - `docs/getting-started/quickstart.md`, `docs/index.md`, `README.md`: updated quantized-model evaluation and vLLM integration descriptions to include JointQ/RTN/OneBit and reference the GPTQ built-in plugin path
+
+### Examples
+
+- Added `example/vllm_inference/example_jointq_vllm_inference.py`: end-to-end JointQ quantization (4-bit, `group_size=128`) → save → vLLM offline inference. Mirrors the GPTQ vLLM example, uses `qep=False` (JointQ does not support QEP), and documents the `bits >= 2` requirement for vLLM bit-packing. Registered in the README example table.
+
 ### Quantizer module forward test fix
 
 - Fixed `tests/onecomp/quantizer/test_module.py` to feed `y_replaced` consistently into `q_proj` / `k_proj` / `v_proj` after quantized weights are applied, aligning the replacement-path forward test with the intended residual update flow
 
@@ -241,11 +241,12 @@ Then open [http://127.0.0.1:8000](http://127.0.0.1:8000) in your browser.
 | | [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_jointq_vllm_inference.py](./example/vllm_inference/example_jointq_vllm_inference.py) | JointQ 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).
+OneComp-quantized models can be served with [vLLM](https://docs.vllm.ai/): GPTQ, JointQ, and RTN models use vLLM's built-in GPTQ plugin, while DBF and Mixed-GPTQ models are served via OneComp's own plugins.
 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
 
@@ -189,12 +189,37 @@ jointq = JointQ(
 )
 ```
 
+## Save and Load
+
+JointQ reuses GPTQ's scale/zero/assignment structure, so it emits
+`quant_method="gptq"` and can be saved with the standard OneComp save API,
+reloaded with `load_quantized_model()`, and served with vLLM's built-in GPTQ
+plugin:
+
+```python
+runner.save_quantized_model("./output/jointq_model")
+
+# Load later with OneComp
+from onecomp import load_quantized_model
+model, tokenizer = load_quantized_model("./output/jointq_model")
+```
+
+!!! note "Bit-width and vLLM"
+    Use `bits` in {2, 3, 4} for JointQ models served with vLLM. `bits=1`
+    cannot be bit-packed by `GPTQLinear`; if you need to save/load a 1-bit
+    JointQ model with OneComp, call `runner.save_quantized_model(..., pack_weights=False)`.
+    Such 1-bit models are not vLLM-servable.
+
+See [vLLM Inference](../user-guide/vllm-inference.md) for serving details, and the
+[`example/vllm_inference/example_jointq_vllm_inference.py`](https://github.com/FujitsuResearch/OneCompression/blob/main/example/vllm_inference/example_jointq_vllm_inference.py)
+script for an end-to-end quantize → save → serve example.
+
 ## Notes
 
 - JointQ requires GPU for computation (CUDA-based local search).
 - Group-wise quantization (`group_size > 0`) is recommended for accuracy.
   Set `group_size=None` for per-channel quantization.
-- JointQ currently supports dequantized-model evaluation only (not packed quantized inference).
+- JointQ does not support QEP; create the `Runner` with `qep=False`.
 - Incremental lambda mode runs `quantize()` multiple times per layer (once per
   lambda value until rejection), so quantization time increases compared to
   fixed lambda mode.
@@ -56,6 +56,33 @@ runner = Runner(model_config=model_config, quantizer=rtn)
 runner.run()
 ```
 
+## Save and Load
+
+RTN uses the same tensor format as GPTQ (`qweight`/`scales`/`qzeros`), so it emits
+`quant_method="gptq"` and can be saved with the standard OneComp save API, reloaded
+with `load_quantized_model()`, and served with vLLM's built-in GPTQ plugin:
+
+```python
+runner.save_quantized_model("./output/rtn_model")
+
+# Load later with OneComp
+from onecomp import load_quantized_model
+model, tokenizer = load_quantized_model("./output/rtn_model")
+```
+
+See [vLLM Inference](../user-guide/vllm-inference.md) for serving details.
+
+!!! note "Bit-width and vLLM"
+    Use `wbits` in {2, 3, 4, 8} for vLLM serving. RTN itself accepts a wider
+    range of `wbits`, but GPTQ-compatible bit packing and vLLM serving are limited
+    to these bit-widths.
+
+!!! warning "Rotation-preprocessed RTN models cannot be served with vLLM"
+    The SpinQuant-style [Rotation Preprocessing + RTN](../user-guide/examples.md#rotation-preprocessing-rtn)
+    flow produces models that vLLM cannot serve, because vLLM does not apply the online
+    Hadamard transform on `down_proj` inputs. Such models remain loadable with
+    `load_quantized_model()`, which auto-registers the Hadamard hooks.
+
 ## Characteristics
 
 - **No calibration data required** -- quantization is performed directly on the model weights
 
@@ -16,13 +16,13 @@ by each quantizer to enable these features.
 | `GPTQ`             | Yes                | Yes                      | Yes  | Yes               |
 | `DBF`              | Yes                | Yes                      | Yes  | Yes               |
 | `AutoBitQuantizer` | Yes                | Yes                      | Yes  | Yes               |
-| `RTN`              | —                  | —                        | No   | No (fallback)     |
-| `JointQ`           | —                  | —                        | No   | No (fallback)     |
+| `JointQ`           | Yes                | Yes                      | Yes  | Yes               |
+| `RTN`              | Yes                | Yes                      | Yes  | Yes               |
+| `Onebit`           | Yes                | Yes                      | Yes  | Yes               |
 | `QUIP`             | —                  | —                        | No   | No (fallback)     |
 | `CQ`               | —                  | —                        | No   | No (fallback)     |
 | `ARB`              | —                  | —                        | No   | No (fallback)     |
 | `QBB`              | —                  | —                        | No   | No (fallback)     |
-| `Onebit`           | —                  | —                        | No   | No (fallback)     |
 
 For quantizers without support:
 
@@ -32,6 +32,21 @@ For quantizers without support:
 - **Saving**: use `save_dequantized_model()` (FP16) or `save_quantization_results()`
   to persist results.
 
+### Saved `quant_method` and vLLM compatibility
+
+`get_quant_config()` determines the `quant_method` written to the saved `config.json`,
+which in turn decides how the model can be served:
+
+| Quantizer | `quant_method` | vLLM serving |
+|-----------|----------------|--------------|
+| `GPTQ` (uniform bits), `JointQ`, `RTN` | `gptq` | vLLM built-in GPTQ plugin |
+| `GPTQ` (mixed bits), `AutoBitQuantizer` | `mixed_gptq` | OneComp Mixed-GPTQ plugin |
+| `DBF` | `dbf` | OneComp DBF plugin |
+| `Onebit` | `onebit` | Not vLLM-servable; load with `load_quantized_model()` |
+
+All of the above are loadable with OneComp's own `load_quantized_model()`. See
+[vLLM Inference](../../user-guide/vllm-inference.md) for serving details.
+
 ::: onecomp.quantizer._quantizer.Quantizer
     options:
       show_source: false
 
@@ -115,7 +115,7 @@ _, _, quantized_acc = runner.calculate_accuracy()
 
 !!! note
     - Evaluating the original or dequantized model requires loading the full model on GPU.
-    - Quantized-model evaluation is currently supported for **GPTQ**, **DBF**, and **AutoBitQuantizer**. Support for other methods is planned.
+    - Quantized-model evaluation is supported for **GPTQ**, **DBF**, **AutoBitQuantizer**, **JointQ**, **RTN**, and **OneBit**. Other methods automatically fall back to the dequantized (FP16) model.
 
 ## Using QEP (Quantization Error Propagation)