[moe] rename RoutedExperts field grouped_experts -> inner_experts

Address review (tianyu-l on #3859): the config field / module attribute (and thus
the FQN moe.routed_experts.grouped_experts) is renamed to inner_experts, while the
class name stays GroupedExperts and the fused_grouped_experts override (which
targets GroupedExperts.Config, not the field) is unchanged. State-dict adapters,
sharding, quantization, graph_trainer, RL configs, tests and docs updated to the
new FQN. Pure rename (word-boundary; class/override names preserved).

Author: wwwjn

tests/unit_tests/test_fsdp_moe_sharding.py

@@ -60,7 +60,7 @@ def _get_expert_shard_dim(model: Qwen3Model) -> int | None:
     """Return the shard dim used for expert params, or None if not sharded."""
     for layer in model.layers.values():
         if layer.moe_enabled:
-            for param in layer.moe.routed_experts.grouped_experts.parameters():
+            for param in layer.moe.routed_experts.inner_experts.parameters():
                 if hasattr(param, "placements"):
                     for p in param.placements:
                         if isinstance(p, Shard):

tests/unit_tests/test_inference_moe.py

@@ -8,7 +8,7 @@
 
 The inference path fuses the grouped experts (``fused_grouped_experts``) AND flips
 the DeepEP dispatcher to the cudagraph-able EXPAND layout (``deepep_inference``).
-Because ``grouped_experts`` and ``token_dispatcher`` are sibling config nodes under
+Because ``inner_experts`` and ``token_dispatcher`` are sibling config nodes under
 ``moe.routed_experts`` (neither an ancestor of the other), both overrides can be
 applied together without the ancestor/descendant conflict that a single combined
 node would cause.
@@ -36,7 +36,7 @@
 
 # fused_swiglu registers both the dense-FFN and the routed-experts (fused_grouped_experts)
 # overrides; the test MoE config has no dense FeedForward node, so importing it only
-# claims the grouped_experts node here.
+# claims the inner_experts node here.
 _FUSED_SWIGLU = "torchtitan.overrides.fused_swiglu"
 _DEEPEP_INFERENCE = "torchtitan.overrides.deepep_inference"
 
@@ -67,7 +67,7 @@ def _moe_config(comm_backend: str):
 class TestInferenceMoEOverrides(unittest.TestCase):
     def test_grouped_experts_and_dispatcher_are_siblings(self):
         cfg = _moe_config("deepep")
-        self.assertIsInstance(cfg.routed_experts.grouped_experts, GroupedExperts.Config)
+        self.assertIsInstance(cfg.routed_experts.inner_experts, GroupedExperts.Config)
         self.assertIsInstance(
             cfg.routed_experts.token_dispatcher, DeepEPTokenDispatcher.Config
         )
@@ -76,15 +76,15 @@ def test_deepep_both_overrides_apply_without_conflict(self):
         cfg = _moe_config("deepep")
 
         # Both overrides on the same actor: the experts-fusion claims
-        # grouped_experts, the dispatcher flip claims the sibling dispatcher.
+        # inner_experts, the dispatcher flip claims the sibling dispatcher.
         replacements = apply_overrides(
             OverrideConfig(imports=[_FUSED_SWIGLU, _DEEPEP_INFERENCE]),
             cfg,
         )
 
         self.assertEqual(len(replacements), 2)
         self.assertIsInstance(
-            cfg.routed_experts.grouped_experts, FusedGroupedExperts.Config
+            cfg.routed_experts.inner_experts, FusedGroupedExperts.Config
         )
         self.assertIsInstance(
             cfg.routed_experts.token_dispatcher, DeepEPTokenDispatcher.Config
@@ -103,31 +103,31 @@ def test_non_deepep_dispatcher_flip_is_noop(self):
 
         self.assertEqual(len(replacements), 1)
         self.assertIsInstance(
-            cfg.routed_experts.grouped_experts, FusedGroupedExperts.Config
+            cfg.routed_experts.inner_experts, FusedGroupedExperts.Config
         )
 
     def test_composition_is_order_independent(self):
-        # Because grouped_experts and dispatcher are disjoint sibling nodes, applying
+        # Because inner_experts and dispatcher are disjoint sibling nodes, applying
         # the experts-fusion and the dispatcher-flip in either order must yield the
         # same result (unlike an ancestor/descendant pair, where an ancestor
         # replacement would detach the descendant's claimed subtree).
         def summarize(ge):
             return (
-                type(ge.grouped_experts).__qualname__,
+                type(ge.inner_experts).__qualname__,
                 type(ge.token_dispatcher).__qualname__,
                 ge.token_dispatcher.cudagraphable,
             )
 
         a = _moe_config("deepep").routed_experts
-        a.grouped_experts = fused_grouped_experts(a.grouped_experts)
+        a.inner_experts = fused_grouped_experts(a.inner_experts)
         a.token_dispatcher = deepep_inference(a.token_dispatcher)
 
         b = _moe_config("deepep").routed_experts
         b.token_dispatcher = deepep_inference(b.token_dispatcher)
-        b.grouped_experts = fused_grouped_experts(b.grouped_experts)
+        b.inner_experts = fused_grouped_experts(b.inner_experts)
 
         self.assertEqual(summarize(a), summarize(b))
-        self.assertIsInstance(a.grouped_experts, FusedGroupedExperts.Config)
+        self.assertIsInstance(a.inner_experts, FusedGroupedExperts.Config)
         self.assertTrue(a.token_dispatcher.cudagraphable)
 
     def test_trainer_uses_only_experts_fusion(self):
@@ -138,7 +138,7 @@ def test_trainer_uses_only_experts_fusion(self):
         apply_overrides(OverrideConfig(imports=[_FUSED_SWIGLU]), cfg)
 
         self.assertIsInstance(
-            cfg.routed_experts.grouped_experts, FusedGroupedExperts.Config
+            cfg.routed_experts.inner_experts, FusedGroupedExperts.Config
         )
         self.assertFalse(cfg.routed_experts.token_dispatcher.cudagraphable)
 

torchtitan/components/quantization/mx.py

@@ -176,7 +176,7 @@ def __init__(self, config: Config):
 
     def convert(self, model_config):
         for _fqn, config, parent, attr in model_config.traverse(GroupedExperts.Config):
-            # ``parent`` is the RoutedExperts.Config that owns this grouped_experts
+            # ``parent`` is the RoutedExperts.Config that owns this inner_experts
             # node and its sibling dispatcher.
             swap_token_dispatcher(parent, self.config.pad_multiple)
             base_module_cls = type(config)._owner

torchtitan/distributed/fsdp.py

@@ -189,7 +189,7 @@ def apply_fsdp_to_decoder(
             # The routed-expert weights live on the grouped-GEMM child; the
             # sibling dispatcher holds no parameters.
             # pyrefly: ignore [missing-attribute]
-            experts = transformer_block.moe.routed_experts.grouped_experts
+            experts = transformer_block.moe.routed_experts.inner_experts
             expert_params = set(experts.parameters())
             num_experts = experts.num_experts
 

torchtitan/experiments/graph_trainer/common_utils.py

@@ -266,7 +266,7 @@ def get_default_transformer_block_buckets(
                         f"layers.{layer_id}.moe.router",
                         f"layers.{layer_id}.moe.shared_experts",
                     ],
-                    f"layers.{layer_id}.moe.routed_experts.grouped_experts",
+                    f"layers.{layer_id}.moe.routed_experts.inner_experts",
                 ]
             )
         else:
@@ -335,7 +335,7 @@ def apply_simple_fsdp(
 ) -> nn.Module:
     """Wrap the model (and any MoE experts) with graph_trainer's simple_fsdp.
 
-    For MoE-enabled models, the ``moe.routed_experts.grouped_experts`` submodules
+    For MoE-enabled models, the ``moe.routed_experts.inner_experts`` submodules
     (the routed-expert weights) are separately wrapped on the EDP mesh when expert
     parallelism is enabled.
     """
@@ -371,16 +371,16 @@ def apply_simple_fsdp(
             moe = getattr(transformer_block, "moe", None)
             if moe is None:
                 continue
-            grouped_experts = moe.routed_experts.grouped_experts
+            inner_experts = moe.routed_experts.inner_experts
             experts_shard_dim = 0
             if (
                 edp_mesh["efsdp"].size() * parallel_dims.ep
-                > grouped_experts.num_experts
+                > inner_experts.num_experts
             ):
                 experts_shard_dim = 1
 
-            moe.routed_experts.grouped_experts = data_parallel(
-                grouped_experts,
+            moe.routed_experts.inner_experts = data_parallel(
+                inner_experts,
                 edp_mesh,
                 dp_mode,
                 mp_policy=mp_policy,

torchtitan/experiments/graph_trainer/tests/test_passes.py

@@ -437,7 +437,7 @@ def test_transformer_block_bucket_counts_follow_bucket_plan(self):
                     "layers.1.moe.router",
                     "layers.1.moe.shared_experts",
                 ],
-                "layers.1.moe.routed_experts.grouped_experts",
+                "layers.1.moe.routed_experts.inner_experts",
                 ["norm", "lm_head"],
             ],
             n_layers=2,
@@ -1074,12 +1074,12 @@ def test_fsdp_dense_scheduler_places_rs_after_moe_backward(self):
                 c10d.all_to_all_single.default,
                 args=(ffn_norm, [], [], "ep_pg"),
             ),
-            "layers.1.moe.routed_experts.grouped_experts",
+            "layers.1.moe.routed_experts.inner_experts",
             backward=True,
         )
         moe_dispatch_wait = self._tag_fsdp_schedule_node(
             graph.call_function(c10d.wait_tensor.default, args=(moe_dispatch,)),
-            "layers.1.moe.routed_experts.grouped_experts",
+            "layers.1.moe.routed_experts.inner_experts",
             backward=True,
         )
         dense1_attention = self._tag_fsdp_schedule_node(
@@ -3432,7 +3432,7 @@ def test_moe_efsdp_bucket_plan_splits_expert_buckets(self):
             ],
             buckets,
         )
-        self.assertIn("layers.1.moe.routed_experts.grouped_experts", buckets)
+        self.assertIn("layers.1.moe.routed_experts.inner_experts", buckets)
         self.assertNotIn("layers.1", buckets)
 
     def test_prepare_ep_overlap_trace_inputs_marks_batch_dims(self):

torchtitan/experiments/rl/examples/alphabet_sort/config_registry.py

@@ -604,7 +604,7 @@ def rl_grpo_qwen3_moe_debug_deepep() -> Controller.Config:
     overrides (``generator.override``) to its own copy: ``fused_swiglu`` (which
     registers both the dense-FFN and routed-experts gate+up fusion) and
     ``deepep_inference`` (switch the sibling DeepEP dispatcher to the cudagraph-able
-    EXPAND layout, ``cudagraphable=True``). ``grouped_experts`` and ``token_dispatcher`` are
+    EXPAND layout, ``cudagraphable=True``). ``inner_experts`` and ``token_dispatcher`` are
     sibling nodes under ``moe.routed_experts``, so the experts fusion and the
     dispatcher flip do not conflict. The overrides touch only the generator's spec, so
     the trainer and weight sync are unaffected. (This mirrors how converters are

torchtitan/experiments/rl/examples/search_r1/config_registry.py

@@ -162,7 +162,7 @@ def rl_grpo_qwen3_30b_a3b_deepep_search_r1_perf() -> Controller.Config:
     sibling ``deepep_inference`` override, which switches the DeepEP dispatcher to the
     cudagraph-able EXPAND layout. Both actors apply ``fused_swiglu`` (which registers
     both the dense-FFN and routed-experts gate+up fusion) + ``helion_rope`` (CUDA-only),
-    as ``rl_grpo_qwen3_30b_a3b_varlen_perf``. ``grouped_experts`` and ``token_dispatcher`` are
+    as ``rl_grpo_qwen3_30b_a3b_varlen_perf``. ``inner_experts`` and ``token_dispatcher`` are
     sibling nodes under ``moe.routed_experts``, so the experts fusion and the generator's
     dispatcher flip do not conflict.
     """

torchtitan/experiments/rl/models/vllm_registry.py

@@ -172,7 +172,7 @@ def model_spec_to_hf_config_dict(spec: ModelSpec) -> dict[str, Any]:
         hf["num_experts_per_tok"] = (
             moe.router.top_k
         )  # top_k is on the router, not experts
-        hf["moe_intermediate_size"] = moe.routed_experts.grouped_experts.hidden_dim
+        hf["moe_intermediate_size"] = moe.routed_experts.inner_experts.hidden_dim
         hf["decoder_sparse_step"] = 1
         hf.setdefault("norm_topk_prob", True)
 

torchtitan/models/common/config_utils.py

@@ -386,14 +386,14 @@ def make_routed_experts_config(
 ) -> RoutedExperts.Config:
     """Build a fully-specified RoutedExperts.Config.
 
-    Composes the pure grouped-GEMM ``grouped_experts`` (weights) with the token
+    Composes the pure grouped-GEMM ``inner_experts`` (weights) with the token
     ``token_dispatcher`` (communication) -- the two sibling children of the routed
     region. The ``fused_grouped_experts`` override targets the former; the DeepEP
     inference override targets the latter.
     """
     return RoutedExperts.Config(
         num_experts=num_experts,
-        grouped_experts=GroupedExperts.Config(
+        inner_experts=GroupedExperts.Config(
             dim=dim,
             hidden_dim=hidden_dim,
             num_experts=num_experts,