[3/4] Hyperparameter Transfer: add dense GPT depth-MuP recipe

[plugyawn]

PR [1/4] (current): #4829

• I, the PR author, have personally reviewed every line of this PR.

What does this PR do?

PR 3/4 of the scaling-recipes split requested in #4381. This builds on #4829 and the canonical
width-MuP recipe PR.
Design doc: PR_MuP.pdf

References: [1/4]: #4829, [2/4]: #4998, [4/4]: #5000

Intended delta for review:
plugyawn/Megatron-LM@feature/scaling-recipe-mup...feature/depth-mup

Because stacked PRs are not enabled in this repository, this PR is opened against main to track the intended progression, but the intended review delta is the comparison above.

This PR adds an experimental depth_mup recipe for dense GPT-style residual transformers with
Adam/AdamW.

The recipe applies:

• residual branch multiplier: depth_mult^-1;
• hidden matrix-like LR depth multiplier: depth_mult^0;
• hidden Adam epsilon depth multiplier: depth_mult^-1;
• dense block output-projection init compensation: depth_mult^+0.5.

The init compensation is included because Megatron already has layer-count-based residual output-
projection initialization; this keeps the initialization behavior from double-counting depth while
making residual branch scaling explicit in the forward graph.

Supported surface in this PR:

• dense GPT-style residual transformer blocks;
• Adam/AdamW-style optimizer semantics;
• standard next-token training.

Explicitly out of scope for this first version:

• SGD depth-MuP;
• MTP depth transfer;
• MoE/hybrid/Mamba depth transfer;
• cross-attention and experimental attention variants;
• general inference semantics.

Issue tracking

Related to #4381 and #4088.

Testing

• Added unit coverage for depth_mup config resolution and validation.
• Added optimizer grouping/regression coverage for depth-MuP AdamW behavior.
• Added residual/output-init/eval-gating coverage.
• python -m py_compile megatron/core/parameterization/spec.py megatron/core/parameterization/ model_policy.py megatron/core/parameterization/training_policy.py megatron/core/parameterization/ eval_runtime.py megatron/training/arguments.py megatron/training/checkpointing.py megatron/ training/yaml_arguments.py tests/unit_tests/transformer/test_mup.py tests/unit_tests/ test_optimizer.py
• Local pytest collection is currently blocked in my environment by Python 3.12 / Torch Dynamo
  compatibility.

Pre-checks

• I have added relevant unit tests
• I have added relevant functional tests
• I have added proper typing to my code
• I have added relevant documentation
• I have run `tools/autoformat.sh

Code review

Feel free to message or comment @NVIDIA/mcore-oncall to help accelerate your merge into main. The less complex your PR is, the faster it will be approved and merged!

All PRs start as draft. If you open a non-draft PR, it will be automatically converted to draft.

Step 1: Mark PR as "Ready for Review"

1. When your PR is ready, click Ready for Review.
2. An oncall reviewer is auto-assigned and expert reviewers are notified based on your changes.
   • Some PRs may jump straight to step 2. This is determined by .github/CODEOWNERS.

⚠️ Only mark as ready once merge-conflicts are resolved and the CI is passing.
Final Review might get declined if these requirements are not fulfilled.

Step 2: Final Review

For PRs that change megatron/core, once all expert reviewers have approved, the Final Review label is applied automatically and final reviewers are assigned.

For PRs outside megatron/core, this step is skipped.

Step 3: Approved

Once all required reviewers have approved, the Approved label is applied automatically.

Merge

Any member of mcore-engineers will be able to merge your PR.

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

[github-actions]

This PR has been automatically converted to draft because all PRs must start as drafts.

When you are ready for review, click Ready for Review to begin the review process. This will:

1. Add the oncall reviewer (optional reviewer)
2. Add required review teams based on your changes

See the contribution guide for more details.