[Backport release/3.0.0] Consolidate multi-GPU documentation

[kellyguo11]

Description

Backports #7182 to release/3.0.0 by cherry-picking merged commit c1b0cbd25c488d3c30d070636f8b402e9cbcdc17.

This consolidates the multi-GPU guide, standardizes benchmark workflows on startup_multigpu, runtime_multigpu, and training_multigpu, and retains the hyphenated forms as deprecated compatibility aliases.

No new dependencies.

Type of change

• Documentation update
• Non-breaking benchmark CLI change with deprecated compatibility aliases

Release backport

Not applicable; this PR targets the active release branch.

Validation

• Focused benchmark tests: 22 passed
• uv run isaaclab -f equivalent with ISAACLAB_CHANGELOG_BASE_REF=release/3.0.0: passed
• Warning-as-error docs build: passed
• Backport patch ID matches merged [Workflow/Docs] Consolidate multi-GPU documentation #7182

The host was macOS, while the project lock and ovstage wheel support Linux/Windows. Validation therefore used a temporary uv-managed Python 3.12 environment; Sphinx autodoc mocked only the unavailable Linux ovstage module.

Checklist

• I have read and understood the contribution guidelines
• I have run the pre-commit checks
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove the canonical and compatibility command dispatch
• I have included the original changelog fragment for the touched package
• The original author already exists in CONTRIBUTORS.md

[greptile-apps]

Greptile Summary

The PR consolidates the multi-GPU guide and standardizes benchmark workflow names while preserving deprecated compatibility aliases.

• Makes startup_multigpu, runtime_multigpu, and training_multigpu the canonical benchmark commands.
• Retains the previous hyphenated commands with deprecation warnings and equivalent dispatch behavior.
• Updates documentation, CLI help, diagnostics, changelog material, and focused compatibility tests.

Confidence Score: 5/5

The PR appears safe to merge, with canonical and deprecated benchmark command forms resolving consistently.

The naming transition preserves existing CLI behavior through explicit compatibility aliases, and the updated documentation, diagnostics, and tests align with the implemented launcher contract.

Important Files Changed

Filename	Overview
source/isaaclab/isaaclab/benchmark/dispatch.py	Adds canonical underscore workflow dispatch and preserves hyphenated aliases with deprecation warnings.
source/isaaclab/isaaclab/benchmark/entrypoints/multigpu.py	Changes the canonical suffix, defines the compatibility suffix, and leaves worker launch semantics unchanged.
docs/source/features/multi_gpu.rst	Consolidates multi-GPU training, benchmarking, multi-node operation, logging, and troubleshooting guidance.
source/isaaclab/test/benchmark/test_multigpu_launcher.py	Covers canonical command dispatch and deprecated alias compatibility.
source/isaaclab/isaaclab/benchmark/distributed.py	Updates user-facing launcher guidance to the canonical underscore spelling without changing rank behavior.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  CLI[isaaclab benchmark] --> Parse{Workflow spelling}
  Parse -->|*_multigpu| Canonical[Canonical workflow]
  Parse -->|*-multigpu| Warning[Emit deprecation warning]
  Warning --> Canonical
  Canonical --> Base[Resolve base workflow]
  Base --> Launcher[Multi-GPU launcher]
  Launcher --> Workers[One benchmark worker per GPU]

Loading

_{Reviews (1): Last reviewed commit: "[Workflow/Docs] Consolidate multi-GPU do..." | Re-trigger Greptile}

[isaaclab-review-bot]

Isaac Lab Review Bot

This backport standardizes multi-GPU benchmark workflow names on the _multigpu suffix, preserves the former hyphenated names as deprecated aliases, and consolidates multi-GPU training and benchmark guidance in multi_gpu.rst.

• Design and architecture: The documentation consolidation creates a clear canonical guide while retaining focused links from the benchmark and quick-start pages. Compatibility handling remains localized to CLI dispatch and does not alter the launcher or per-rank worker architecture.
• API: The CLI migration preserves existing commands: canonical and legacy workflow names are accepted, legacy names emit a migration message, and both paths delegate to the same launcher with unchanged remaining arguments. The changelog documents the replacement names, and the affected Sphinx references shown in the patch use the new label.
• Implementation: Dispatch, suffix constants, launcher configuration, help and error text, documentation, and focused tests are consistent with the naming change. The documented distributed-result scopes and unsupported training options match the implementation. A non-blocking tradeoff is that deprecation is reported with a direct stderr message rather than Python's warnings framework, so callers cannot filter or escalate it through warning controls.

No blocking issues. No inline issue met the actionable-evidence threshold; the assessment above records the review feedback.

Automated review; human maintainers own approval decisions.