[Workflow/Docs] Consolidate multi-GPU documentation

[StafaH]

Description

Reworks the multi-GPU guide around a task-first flow modeled after the quickstart and installation pages while retaining the established train_multigpu command spelling.

• starts with the single-GPU-to-multi-GPU workflow using train_multigpu
• explains GPU selection, per-rank environment counts, supported RL libraries, and logging
• standardizes benchmark workflows as startup_multigpu, runtime_multigpu, and training_multigpu
• retains the former hyphenated benchmark names as deprecated, warning-emitting compatibility aliases
• clarifies benchmark measurement scope and scaling comparisons
• simplifies multi-node setup and keeps focused NCCL troubleshooting guidance
• updates OSMO and repository-owned skill references to the underscore convention

No new dependencies.

Type of change

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

Release backport

• Backport this pull request to the active release branch after it merges into develop

Screenshots

Not applicable.

Validation

• uv run --extra test pytest -q source/isaaclab/test/benchmark/test_multigpu_launcher.py source/isaaclab/test/benchmark/test_distributed.py (22 passed)
• uv run isaaclab -f
• uv run --no-project python tools/skills/cli.py check (21 skills validated)
• uv run --isolated --extra test -- make -C docs current-docs (warning-free)

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 canonical and compatibility command dispatch
• I have added changelog fragments for every touched source package
• My name already exists in CONTRIBUTORS.md

[isaaclab-review-bot]

Isaac Lab Review Bot

The CLI rename preserves the deprecated underscore alias and updates documentation and tests, but the OSMO workflow now invokes the new command inside a pinned container image that predates the rename.

• Design and architecture: The alias-based migration preserves compatibility for updated checkouts. However, the OSMO workflow executes the CLI supplied by its container rather than the current checkout, so changing the template command independently of the pinned image creates a producer/consumer version mismatch.
• API: The local CLI supports both train-multigpu and the warning-emitting train_multigpu alias. The pinned nvcr.io/nvidia/isaac-lab:3.0.0-beta2 image does not include this newly introduced canonical spelling, making the updated OSMO default incompatible with that image.
• Implementation: The CLI dispatch and alias forwarding are covered by focused tests. The OSMO multi-GPU path at line 64 should retain train_multigpu until its default container image includes the renamed command, or the image and command must be updated together.

Minor fixes needed. Posted 1 actionable finding inline.

Automated review; human maintainers own approval decisions.

[greptile-apps]

Greptile Summary

The PR consolidates multi-GPU documentation around the canonical underscore command spelling while preserving deprecated hyphenated benchmark aliases.

• Reorganizes the multi-GPU guide around training, GPU selection, benchmarking, multi-node operation, and NCCL troubleshooting.
• Standardizes benchmark commands as startup_multigpu, runtime_multigpu, and training_multigpu.
• Retains the former hyphenated benchmark commands as warning-emitting compatibility aliases.
• Updates CLI help, diagnostics, tests, and changelog documentation to match the new convention.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
docs/source/features/multi_gpu.rst	Replaces the previous guide with a task-first reference covering distributed training, benchmarks, logs, multi-node setup, and troubleshooting.
source/isaaclab/isaaclab/benchmark/dispatch.py	Dispatches canonical underscore benchmark names and preserves hyphenated names as deprecated aliases.
source/isaaclab/isaaclab/benchmark/entrypoints/multigpu.py	Changes the canonical benchmark suffix to _multigpu and defines the former suffix as the compatibility spelling.
source/isaaclab/test/benchmark/test_multigpu_launcher.py	Verifies canonical command dispatch and deprecated alias warning behavior.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  CLI[Benchmark CLI] --> Canonical{Command spelling}
  Canonical -->|workflow_multigpu| Launcher[Multi-GPU launcher]
  Canonical -->|workflow-multigpu| Warning[Deprecation warning]
  Warning --> Launcher
  Launcher --> Workers[One worker per GPU]

Loading

_{Reviews (2): Last reviewed commit: "Apply suggestion from @AntoineRichard" | Re-trigger Greptile}

[AntoineRichard]

Do we need to support this? I don't know if for this in particular applying a deprecation cycle on beta 2 makes sense.

[AntoineRichard]

should we remove this?

[StafaH]

run-ci

[StafaH]

run-co

[StafaH]

run-ci

[StafaH]

run-ci