Skip to content

Document the parallel_state deprecation and its replacement - #6257

Open
Connor-XY wants to merge 3 commits into
NVIDIA:mainfrom
Connor-XY:yx/pstate-p0-mark-deprecation
Open

Connor-XY wants to merge 3 commits into
NVIDIA:mainfrom
Connor-XY:yx/pstate-p0-mark-deprecation

Conversation

@Connor-XY

@Connor-XY Connor-XY commented Aug 4, 2026 •

Copy link
Copy Markdown
Contributor

Global parallel_state accessors cannot select an independent model's parallel grid. Document caller-provided ProcessGroupCollection / ProcessGroup arguments as the migration path, mark 59 accessors with replacement guidance, and clarify where the compatibility shim remains appropriate.

Include current dense/expert, GTP-remat, and dynamic CP group mappings, global versus group-local rank conversion, optional-group and initialization semantics, and the limits of physical pipeline-stage helpers. This is documentation-only: executable ASTs for both Python files are unchanged from main (77391e71cc). Upstream #7045 renamed the hybrid DP×CP accessor to get_dynamic_data_context_parallel_groups (keeping get_hybrid_data_context_parallel_groups as a deprecated alias); the deprecation note now sits on the new accessor. Upstream #7047 added the dynamic_cp and dynamic_tp_cp fields to ProcessGroupCollection. The note on get_dynamic_data_context_parallel_groups points to pg_collection.dynamic_cp[group_size], and the three dynamic group accessors main added since this PR was written carry the standard deprecation note. The guide maps the dynamic (formerly hybrid) groups to dynamic_cp and dynamic_tp_cp, keyed by runtime CP size, and only Gloo groups have no corresponding collection fields.

Validation: Black 26.3.0, isort, Ruff, pylint, syntax, and git diff --check pass. The local mypy run reports the same 13 dependency/type diagnostics as main. The lint and mypy results are from the branch before the sync; after the sync, git diff --check passes and the merge changes only docstrings and the guide. No GPU execution is needed for this documentation-only change. The PR touches no test files, and the integration run of all #6307 PRs on main shows no regressions against main.

The branch was synced with main 77391e7 on 2026-11-01 by a merge commit, so existing commits and review links stay valid. The merge had no conflicts; its message lists the docstring and guide updates for main's changes.

Related to #6307.

@copy-pr-bot

copy-pr-bot Bot commented Aug 4, 2026

Copy link
Copy Markdown

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.

@Connor-XY

Copy link
Copy Markdown
Contributor Author

Part of #6307 — tracking issue for the parallel_state deprecation, with the landing order, the decisions needed, and what remains.

@Connor-XY
Connor-XY force-pushed the yx/pstate-p0-mark-deprecation branch from 5fee2db to 1715e47 Compare August 19, 2026 19:31
@Connor-XY
Connor-XY marked this pull request as ready for review August 19, 2026 19:31
@Connor-XY
Connor-XY requested review from a team as code owners August 19, 2026 19:31
@svcnvidia-nemo-ci svcnvidia-nemo-ci added the Final Review PR is in the "final review" stage label Aug 19, 2026
@Connor-XY
Connor-XY force-pushed the yx/pstate-p0-mark-deprecation branch from 1715e47 to e84f312 Compare September 8, 2026 20:29
@Connor-XY
Connor-XY force-pushed the yx/pstate-p0-mark-deprecation branch from e84f312 to bbb2457 Compare September 18, 2026 18:24
@Connor-XY
Connor-XY force-pushed the yx/pstate-p0-mark-deprecation branch from bbb2457 to a40dd76 Compare September 30, 2026 22:17
@Connor-XY

Copy link
Copy Markdown
Contributor Author

/ok to test a40dd76

@Connor-XY

Copy link
Copy Markdown
Contributor Author

/ok to test 7a4a53b

Document caller-provided process groups as the migration path for Megatron Core. Mark 56 legacy accessors with replacement guidance and clarify compatibility shim boundaries, expert and GTP group selection, global rank conversion, and optional-group semantics. Keep executable code unchanged.

Signed-off-by: Yan Xu <yxu1@nvidia.com>
The new page was only linked from contribute.md, so Sphinx warned that it is
not included in any toctree and the warnings-as-errors docs build failed.

Signed-off-by: Yan Xu <yxu1@nvidia.com>
@Connor-XY
Connor-XY force-pushed the yx/pstate-p0-mark-deprecation branch from 7a4a53b to 399a917 Compare October 1, 2026 21:07
@Connor-XY

Copy link
Copy Markdown
Contributor Author

/ok to test 399a917

Adapted to main outside the conflicts:
- megatron/core/parallel_state.py: NVIDIA#7047 added the ProcessGroupCollection
  fields dynamic_cp and dynamic_tp_cp. The deprecation note on
  get_dynamic_data_context_parallel_groups now points to
  pg_collection.dynamic_cp[group_size] instead of saying no field exists.
  The three dynamic group accessors main added since this PR was written
  now carry the standard deprecation note, pointing to the dynamic_cp and
  dynamic_tp_cp fields. Only docstrings change.
- docs/developer/parallel-state-deprecation.md: The "no corresponding
  fields" sentence now covers only Gloo groups. The guide maps the dynamic
  (formerly hybrid) groups to dynamic_cp and dynamic_tp_cp, keyed by
  runtime CP size, and the group table gains rows for both.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Yan Xu <yxu1@nvidia.com>

This branch was previously deployed

2 inactive (outdated) deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

complexity: low Final Review PR is in the "final review" stage

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants