[OMNIML-5823] Add row-padded IQ export and Nemotron recipe

[hychiang-git]

What does this PR do?

Type of change: new feature

This PR extends the IQ1_S and IQ2_XS work in #2381 with row-padded export and model-specific validation:

• Right-pad each logical weight row to complete 256-value blocks without crossing row boundaries.
• Export explicit logical-shape and padded-shape sidecars for both Hugging Face and Megatron checkpoints.
• Preserve aligned-tensor payload compatibility while trimming padded values during dequantization.
• Add a Nemotron 3.5 Lightning mixed weight-only recipe with IQ2_XS expert weights, dynamic NVFP4 Mamba projections, and BF16 elsewhere.
• Add utilities and tests for checkpoint structure, streaming/offloaded export, CPU/CUDA byte parity, stock GGML reconstruction, and GGUF materialization.
• Preserve the configured GGUF converter subclass when creating the mixed-format converter.

Usage

torchrun --nproc_per_node 4 examples/megatron_bridge/quantize.py \
  --hf_model_name_or_path <model-path> \
  --tp_size 1 \
  --recipe models/nvidia/NVIDIA-Nemotron-3.5-Lightning-30B-A3B-BF16/ptq/iq2_xs_experts-nvfp4_mamba \
  --skip_generate \
  --export_megatron_path <output-path>/megatron

The launcher examples under tools/launcher/examples/nvidia/NVIDIA-Nemotron-3.5-Lightning-30B-A3B-BF16/ provide export, checkpoint-validation, stock-decoder, and full-GGUF validation workflows.

Testing

• python -m pytest -q tests/unit/torch/quantization/test_iq1_s.py tests/unit/torch/quantization/test_iq2_xs.py tests/unit/torch/export/test_export_weight.py tests/unit/torch/export/test_get_quantization.py tests/unit/torch/export/test_offload_export.py tests/unit/recipe/test_nemotron_lightning_iq2_xs_recipe.py tests/unit/examples/test_materialize_mixed_iq_gguf.py tests/unit/examples/test_validate_ggml_row_alignment.py tests/unit/examples/test_validate_iq2_xs_reconstruction.py tests/unit/examples/test_validate_mixed_quantized_hf.py — 89 passed.
• pre-commit run --from-ref origin/iq2xs-unified-export --to-ref HEAD — passed.

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.

• Is this change backward compatible?: ✅ Aligned tensors retain their packed payload representation; new shape sidecars extend the checkpoint contract for padded rows.
• If you copied code from any other sources or added a new PIP dependency, did you follow guidance in CONTRIBUTING.md: N/A — no new dependency or copied implementation.
• Did you write any new necessary tests?: ✅
• Did you update Changelog?: ✅
• Did you get Claude approval on this PR?: ❌ Pending.

Additional Information

Depends on #2381. This remains a draft while the parent PR and end-to-end runtime validation are in progress.

[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

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

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