Add WaterSIC for KV-cache quantization

[kaix-nv]

What does this PR do?

Type of change: ?
New feature. Integrates WaterSIC for KV-cache quantization.

WaterSIC is an information-theoretically near-optimal quantization algorithm (Lifar et al., 2026) that uses the waterfilling principle for per-column rate allocation combined with Successive Interference Cancellation (ZSIC) and Huffman entropy coding. This PR adds KV-cache quantization for HF models.

Usage

import modelopt.torch.quantization as mtq

# FP8 weights + WaterSIC KV cache
python hf_ptq.py --pyt_ckpt_path Qwen/Qwen3-8B --qformat fp8 --kv_cache_qformat watersic_kv

# With custom rate and KL-aware mode
 python hf_ptq.py --pyt_ckpt_path Qwen/Qwen3-8B --qformat fp8 --kv_cache_qformat watersic_kv \
      --watersic_target_rate 4.0 --watersic_kl_aware

Testing

python examples/watersic_kv_cache/kv_cache_real_model_plots.py
Capture real post-RoPE Q, K tensors from Qwen3-8B (layers 1, 12, 24, 35) and plots rate vs KL divergence for all 5 method.

Before your PR is "Ready for review"

Make sure you read and follow Contributor guidelines and your commits are signed (git commit -s -S).

Make sure you read and follow the Security Best Practices (e.g. avoiding hardcoded trust_remote_code=True, torch.load(..., weights_only=False), pickle, etc.).

• Is this change backward compatible?: ✅ / ❌ / N/A
• If you copied code from any other sources or added a new PIP dependency, did you follow guidance in CONTRIBUTING.md: ✅ / ❌ / N/A
• Did you write any new necessary tests?: ✅ / ❌ / N/A
• Did you update Changelog?: ✅ / ❌ / N/A

Additional Information

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 42c9eb13-da64-424d-9eb7-512f4fe6e291

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch kaix/watersic-kv-cache

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://NVIDIA.github.io/Model-Optimizer/pr-preview/pr-1217/
Built to branch gh-pages at 2026-04-13 21:56 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[codecov]

Codecov Report

❌ Patch coverage is 64.07407% with 97 lines in your changes missing coverage. Please review.
✅ Project coverage is 76.68%. Comparing base (0b42c14) to head (4b44815).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
...orch/quantization/algorithms/watersic_kv/helper.py	31.18%	64 Missing ⚠️
modelopt/torch/quantization/model_calib.py	14.81%	23 Missing ⚠️
.../torch/quantization/algorithms/watersic_kv/zsic.py	91.45%	10 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1217      +/-   ##
==========================================
- Coverage   76.91%   76.68%   -0.24%     
==========================================
  Files         350      355       +5     
  Lines       40481    41414     +933     
==========================================
+ Hits        31137    31758     +621     
- Misses       9344     9656     +312     

Flag	Coverage Δ
unit	55.57% <64.07%> (+0.04%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.