fix(moe): broadcast padding mask for expert bias counts

[cuichenx]

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

What does this PR do?

Fixes the MoE expert-bias update so it broadcasts the flattened padding mask across the expert dimension, preventing a shape mismatch when num_tokens != num_experts.

Root cause

The expert-bias update combined a routing map shaped [num_tokens, num_experts] with a flattened padding mask shaped [num_tokens]. PyTorch aligns that mask with the expert dimension, so the operation fails whenever num_tokens != num_experts.

Expanding the mask to [num_tokens, 1] gives the intended per-token broadcast and excludes padded assignments from local_tokens_per_expert.

Changes

• Broadcast the flattened padding mask across the expert dimension before updating expert-bias token counts.
• Add grad-enabled masked and unmasked router coverage with num_tokens != num_experts.
• Verify exact per-expert counts, total valid assignments, forward completion, and backward gradients.

Validation

• Original 64-token, four-expert grad-enabled reproduction.
• New masked and unmasked focused regression.
• Complete one-GPU TestTop2Router class: 23 passed, 2 skipped.
• Scoped Ruff, Black, isort, pylint, and git diff --check.

Issue tracking

Linked issue: Fixes #6111

Related PRs

• fix(moe): exclude padding tokens from dropless HybridEP routing #5515 (Handle HybridEP packed padding masks) — related padding-mask handling in the MoE routing path.

Contribution process

Pre-checks

• I have added relevant unit tests
• I have added relevant functional tests
• I have added proper typing to my code Typing guidelines
• I have added relevant documentation
• I have run the autoformatter.sh on my PR

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.

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

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

[nemo-automation-bot]

🔄 Merge queue validation started!

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

[nemo-automation-bot]

🔄 Merge queue validation started!

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

[nemo-automation-bot]

🔄 Merge queue validation started!

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