Skip to content

Add standalone distributed Muon optimizer - #4034

Draft
weifengpy wants to merge 1 commit into
mainfrom
weifeng/distributed-muon-standalone
Draft

Add standalone distributed Muon optimizer#4034
weifengpy wants to merge 1 commit into
mainfrom
weifeng/distributed-muon-standalone

Conversation

@weifengpy

@weifengpy weifengpy commented Jul 31, 2026

Copy link
Copy Markdown
Contributor

Stack from ghstack (oldest at bottom):

Summary

  • add a standalone CUDA-only DistributedMuon that owns momentum and Newton-Schulz math without depending on torch.optim.Muon
  • add components/distributed_optimizers/ with a generic bucketed redistribution runtime, Muon state/math, and parameter-view preparation
  • make redistribution topology a runtime contract: every BucketSpec carries its exact 1D DeviceMesh, owner ranks are mesh-local, and each bucket may use a different participant set
  • let the generic runtime derive process groups and DTensor storage blocks, build logical routes and physical schedules, fuse bucket packing, and perform storage-to-compute redistribution and writeback
  • require forward and reverse routes to be in-bounds, exhaustive, non-overlapping logical block partitions; every compute destination must receive the complete logical tensor before it may source writeback
  • represent replicated or reduced physical copies through participant tuples on one logical block rather than overlapping block entries
  • resolve static DSV3 BucketConfig(mesh_axis=...) entries against named DTensor storage meshes after model parallelization
  • lower each active Shard-to-Owned bucket into one forward and one reverse packed all-to-all while preserving zero-sized storage shards
  • support Owned compute from an exact 1D Shard on either matrix dimension; Support TP-sharded matrices in DistributedMuon #4051 adds named 2D Shard(0)/Shard(1) storage
  • expose typed MuonComputeSharding(view_before_placement=..., placement=...); Muon supplies compute requirements and math but no process groups, storage blocks, or collectives
  • preserve DTensor parameter and momentum storage placements and checkpoint behavior
  • verify before each step that locally computed cached views still share the current DTensor storage, failing before mutation if storage was replaced
  • add a DSV3-16B FSDP2=8, EP=4, spmd_types recipe; projection matrices use Muon while wo, embeddings, lm_head, and unsupported parameters remain in foreach AdamW

This is a standalone PR based on main; it has no dependency on the earlier FlexShard/MuonAdapter stack or PyTorch Muon changes.

Test plan

  • PYTHONPATH=/tmp/pytorch-optimizer-step-test:$PWD python -m pytest tests/unit_tests/test_bucketed_optimizer_redistribution.py tests/unit_tests/test_muon_parameter_prep.py tests/unit_tests/test_deepseek_v3_distributed_muon_config.py -q (13 passed, 11 subtests passed)
  • focused cached-view replacement and numerical/checkpoint tests (2 passed on two GPUs)
  • focused uneven Shard(1) parity/writeback test (1 passed on two GPUs)
  • focused distinct-bucket-mesh test (1 passed on four GPUs)
  • eight-B200 DSV3-16B smoke: FSDP2=8, EP=4, TP=PP=CP=1, spmd_types, local batch size 1, sequence length 128; loss 12.05116, grad norm 8.4805, memory 24.14 GiB per GPU

@meta-cla meta-cla Bot added the CLA Signed This label is managed by the Meta Open Source bot. label Jul 31, 2026
@weifengpy
weifengpy force-pushed the weifeng/distributed-muon-standalone branch 7 times, most recently from b4023f7 to bda57dd Compare July 31, 2026 18:49
@weifengpy
weifengpy force-pushed the weifeng/distributed-muon-standalone branch 19 times, most recently from 36e6530 to f1276f2 Compare August 1, 2026 19:32
@weifengpy
weifengpy force-pushed the weifeng/distributed-muon-standalone branch 6 times, most recently from 0a2d554 to 0e7805d Compare August 3, 2026 18:31
@weifengpy
weifengpy force-pushed the weifeng/distributed-muon-standalone branch 4 times, most recently from 19645aa to 3787193 Compare August 3, 2026 21:30
@weifengpy
weifengpy force-pushed the weifeng/distributed-muon-standalone branch from 3787193 to 93f15a5 Compare August 3, 2026 21:47
@weifengpy weifengpy closed this Aug 4, 2026
@weifengpy weifengpy reopened this Aug 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ciflow/8gpu CLA Signed This label is managed by the Meta Open Source bot.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant