[nathon-lee]

What does this PR do ?

Adds a new user-guide page docs/user-guide/features/low_precision_training.md that consolidates the FP8/FP4 training story in Megatron Core: recipes (delayed, tensorwise, mxfp8, blockwise, nvfp4, custom), hardware compatibility, numerical-stability and memory knobs, a configuration cookbook, a feature compatibility matrix, end-to-end example links, and troubleshooting. The page is added to index.md toctree. Docs-only change; no code modified.

Issue tracking

Addresses the "Low-precision guide" item under the Precision section of the 2026 Q2 Megatron Core Roadmap.

Linked issue: Related to #4997

Contribution process

Pre-checks

• I have added relevant unit tests (N/A — docs only)
• I have added relevant functional tests (N/A — docs only)
• I have added proper typing to my code (N/A — docs only)
• I have added relevant documentation
• I have run the autoformatter.sh on my PR (N/A — no Python changes)

Notes for reviewers

• Scope: docs-only, two files changed (docs/user-guide/features/low_precision_training.md new; index.md toctree entry added).
• Local verification: cd docs && uv run --group docs sphinx-build --keep-going . _build/html succeeds with zero new warnings introduced by this PR.
• Sources cross-checked against code: CLI flags and defaults verified against transformer_config.py (fp8/fp4 fields), enums.py (Fp8Recipe, Fp4Recipe), optimizer_config.py (MXFP8 + reuse_grad_buf_for_mxfp8_param_ag recommendation), and arguments.py (recipe-mutual-exclusion / TE version assertions / CPU-offload constraint).
• TE version numbers: I intentionally avoided pinning per-recipe minimum TE versions in the compatibility table (only the nvfp4 >= 2.7.0.dev0 constraint that Megatron enforces is stated). Happy to add precise minimums per recipe if a reviewer can confirm them from the TE side.
• Examples referenced (all existing files):
  • train_llama3_8b_h100_fp8.sh
  • train_llama3_8b_fsdp_h100_fp8.sh
  • 02_train.sh
  • nemotron5_56b.sh (tensorwise)
  • nemotron5p5_12b_H.sh (blockwise)

CC @NVIDIA/mcore-oncall for review routing / suggested precision expert reviewer.

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

[wujingyue]

Suggested change

	the TE `FusedAdam` path and lets you store optimizer state in lower
	the TE `FusedAdam` path and lets you store optimizer state and gradients in lower

Am I right? The name --main-grads-dtype suggests gradients can also be in lower precision.

[nathon-lee]

Thank you for your review!

[wujingyue]

/claude fix

[svcnvidia-nemo-ci]

🛠️ Claude fix commit 28c5d9b238f3 (attempt 1)

⚠️ This explanation is AI-generated and may be inaccurate; the exact commit is authoritative.

What changed
No edits made. The pinned base merge was already fully resolved: zero unmerged paths and zero conflict markers. The index.md resolution is minimal and correct, adding only the low＿precision＿training toctree line while preserving the base's removal of the deleted context＿parallel entry. Verified the new doc's relative link targets and all merged toctree entries resolve, and that the base touched no FP8／FP4 lines in transformer＿config.py or arguments.py.

Files changed by Claude

• No additional file edits; the pinned base was merged.

Why
Nothing in scope to repair. The merge is clean; no CI logs exist (the failing-job name is empty and the claude-fix-ci directory is empty; steering file is 0 bytes). Lint does not apply to this docs-only PR: autoformat.sh lints only Python under megatron／core and tests／, which is empty here, and there is no markdownlint or link-check config. Editing would mean speculatively rewriting PR prose with no failure to justify it.

DCO
@nathon-lee, please fix any DCO failures on your commits before merge. DCO does not block this workflow.

View exact commit

Sanitized and posted by svcnvidia-nemo-ci.

[svcnvidia-nemo-ci]

/ok to test 28c5d9b

[svcnvidia-nemo-ci]

✅ Claude fix CI passed after attempt 1. View exact-SHA CI.

[wujingyue]

/ok to test 2e35b16

[nathon-lee]

Thanks for checking! The remaining failure appears to be unrelated to this docs-only change and comes from existing transformer CUDA graph tests. Could you please rerun the CI when convenient? Thanks!

[nemo-automation-bot]

🔄 Merge queue validation started!

You can track the progress here: https://github.com/NVIDIA/Megatron-LM/actions/runs/37106358941