Preserve zero batches in histogram calibration

[MrCapricornLiu]

What does this PR do?

Type of change: Bug fix

Histogram calibration can fail when its first batch is all zeros and a later batch contains nonzero values. The initial bin edges are all zero, so growing the range divides by a zero bin width and raises OverflowError. torch.histc also places zeros in the middle of its automatic range when both bounds are zero.

Keep zero-only batches in the first bin, then rebuild the range when the first nonzero batch arrives and carry the previous zero counts into that bin. This preserves the calibrated distribution without imposing a minimum range that would lose resolution for small activations. Ordinary range growth and the NumPy collector are unchanged.

Usage

No API change. Existing histogram-calibrated TensorQuantizer calls accept initial zero batches.

Testing

• All eight new cases fail on unmodified production code. The complete calibrator module passes 36 tests, with one pre-existing skipped test.
• Tests compare every bin count with a NumPy histogram over the complete data, including repeated zero batches, negative values, small/large ranges, reset, and calibration followed by quantized inference through TensorQuantizer.
• On an H800, FP32/FP16/BF16 × percentile/MSE/entropy: incremental calibration after zero batches matches one-shot calibration in histogram counts, amax and quantized output in all nine cases.
• Changed-file pre-commit checks pass, including Ruff, mypy and Bandit.

This covers the default torch_hist=True, skip_zeros=False collector. Empty input after filtering with skip_zeros=True, nonfinite inputs, distributed calibration and full-model accuracy/performance were not tested or changed.

Before your PR is "Ready for review"

• Backward compatible: yes; no API or serialized configuration changes.
• Copied code or new PIP dependencies: none.
• Necessary tests: added to the existing calibrator module.
• Changelog: updated.
• Upstream review: pending.

Additional Information

The histogram collector is separate from the NVFP4 activation headroom algorithm in #2028.

Summary by CodeRabbit

• Bug Fixes

  • Fixed histogram calibration when initial batches contain only zero values and later batches become nonzero.
  • Preserved zero-valued samples in calibrated distributions.
  • Improved calibration reliability for all-zero inputs, reset workflows, percentile calculations, and quantizer outputs.

• Tests

  • Added coverage for zero-value batches, histogram ranges, calibration recovery, percentile results, and finite quantizer outputs.

[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]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 22f89aef-3072-419d-a29e-e57b5cd9cb4a

📥 Commits

Reviewing files that changed from the base of the PR and between 446fe6a and b713fb1.

📒 Files selected for processing (1)

• CHANGELOG.rst

Included review availability: Your plan provides up to 12 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

Histogram calibration now preserves zero-valued samples from initial batches, establishes a valid range for all-zero input, and expands the range when later batches contain nonzero values. Tests cover collection, reset, percentile calibration, and quantizer output.

Changes

Histogram calibration

Layer / File(s)	Summary
Preserve zero batches during histogram collection modelopt/torch/quantization/calib/histogram.py, CHANGELOG.rst	The collector preserves counts from zero-only batches, uses a fallback maximum of 1, and expands the histogram range for later nonzero values. The changelog records the fix.
Validate zero-batch calibration tests/unit/torch/quantization/test_calibrator.py	Tests cover leading zero batches, all-zero inputs, reset behavior, percentile results, and finite tensor-quantizer output.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix

Suggested reviewers: kevalmorabia97

Merge Risk: ⚪ Minimal · up to b713f

The histogram fix preserves zero-prefix counts and supports later nonzero calibration without an established merge-blocking regression.

🚥 Pre-merge checks | ✅ 5 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 20.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 5 functions across 2 files. (1 skipped: 1…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: preserving zero-only batches during histogram calibration.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Security Anti-Patterns	✅ Passed	PASS. The pull request changes only histogram calibration, tests, and the changelog. The added production code contains no torch.load(..., weights_only=False), numpy.load(..., allow_pickle=True), trus…

Full details: Docstring Coverage

Explanation

Docstring coverage is 20.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 5 functions across 2 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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