docs(isaac): document a single Isaac Sim 6.0 install path (closes #108)#109
Open
yinsong1986 wants to merge 2 commits into
Open
docs(isaac): document a single Isaac Sim 6.0 install path (closes #108)#109yinsong1986 wants to merge 2 commits into
yinsong1986 wants to merge 2 commits into
Conversation
…ands-labs#108) The repo's Isaac Sim 6.0 install guidance was internally contradictory: the prose (README, docs/index.md, docs/getting-started/installation.md, docs/troubleshooting.md, docs/backends/isaac.md, _install.py) all said Isaac Sim is "not on PyPI / installed separately", but the `[isaac]` extra pinned `isaacsim>=6.0` (and `isaaclab>=3.0,<4.0`) — a PyPI path the prose says isn't supported. Worse, the PyPI `isaacsim[all]` metapackage is incomplete on its own (it omits the `isaacsim-extscache-*` packages), so `SimulationApp` aborts at boot with an `omni.ext` "Failed to resolve extension dependencies" error and `create_world()` never starts. This commits the repo to Option A (strands-labs#108): Isaac Sim installed out-of-band via the Omniverse Launcher / Isaac Lab / NGC Docker image (each ships a complete, bootable Kit), with the pip extra carrying only the genuinely pip-installable helper. Changes: - pyproject.toml: drop `isaacsim`/`isaaclab` from the `[isaac]` extra; keep `usd-core` only. Rewrite the comment block to explain why. - docs/getting-started/installation.md: fix Step 2 prose (the extra does not install Isaac Sim) and add a "Step 3 — verify your install boots" end-to-end snippet (create_world -> add_robot/object/camera -> step -> render -> destroy) that surfaces the extension-resolution failure. - docs/index.md: clarify the `[isaac]` extra installs only `usd-core` + strands-robots, not Isaac Sim. - test_entrypoint.py: replace the assertion that the extra pins `isaacsim`/`isaaclab` with one asserting it pins only `usd-core` and must NOT pin `isaacsim`/`isaaclab` (drift guard for the contradiction). Out of scope (separate follow-ups): the GPU/ICD multi-GPU device- selection note in the issue's environment section.
…trands-labs#107) The `[isaac]` extra previously pinned `isaaclab>=3.0,<4.0`, but the only `isaaclab` distribution on the index is the pre-release `3.0.0b2`. Per PEP 440, `>=3.0,<4.0` excludes pre-releases by default, so pip found no eligible version and the *entire* `[isaac]` extra (and the documented `pip install 'strands-robots-sim[isaac]'`) was unsatisfiable: ERROR: Could not find a version that satisfies the requirement isaaclab<4.0,>=3.0; extra == "isaac" (from versions: 3.0.0b2) This change is on the same branch that already drops `isaaclab` (and `isaacsim`) from `[isaac]` for strands-labs#108. It records the strands-labs#107-specific root cause so the regression can't drift back in: - pyproject.toml: extend the `[isaac]` comment to explain the pre-release/PEP-440 trap and that the fleet-RL path installs Isaac Lab from source (`./isaaclab.sh -i`), per docs/getting-started/installation.md. - test_entrypoint.py: extend the `isaaclab not in [isaac]` drift-guard assertion message to cite strands-labs#107 and the pre-release reason. Acceptance criteria (strands-labs#107): - `pip install 'strands-robots-sim[isaac]'` resolves on Python 3.12 (extra now pins only `usd-core`; no `isaaclab` pre-release pin). - The docs/index.md quickstart runs with exactly what `[isaac]` installs (core SimEngine surface needs only Isaac Sim; Isaac Lab is fleet-RL only, installed out-of-band from source).
Open
5 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changed
Picks one supported Isaac Sim 6.0 install path and makes every surface agree on it, resolving the contradiction reported in #108.
The repo's prose (README,
docs/index.md,docs/getting-started/installation.md,docs/troubleshooting.md,docs/backends/isaac.md, andstrands_robots_sim/isaac/_install.py) all stated Isaac Sim is not on PyPI and must be installed out-of-band — but the[isaac]extra pinnedisaacsim>=6.0(andisaaclab>=3.0,<4.0), i.e. a PyPI install path the prose says isn't supported. Following that pin also produced a broken environment: NVIDIA'sisaacsim[all]metapackage pulls theisaacsim-*packages but not theisaacsim-extscache-*packages, soSimulationAppaborts at boot with:and
create_world()never starts.This PR commits to Option A (the issue's recommended path): Isaac Sim is provisioned out-of-band via the Omniverse Launcher / Isaac Lab / NGC Docker image (each ships a complete, bootable Kit), and the pip extra carries only the genuinely pip-installable helper.
Diff (4 files, +117 / −45)
pyproject.toml— dropisaacsim>=6.0andisaaclab>=3.0,<4.0from the[isaac]extra; keepusd-coreonly. Comment block rewritten to explain the two reasons (internal consistency + the incomplete-metapackage boot failure).docs/getting-started/installation.md— fix Step 2 prose (the[isaac]extra does not install Isaac Sim; it installsusd-core+strands-robots), and add a "Step 3 — verify your install boots" end-to-end snippet (create_world → add_robot → add_object → add_camera → step → render → destroy) that surfaces the extension-resolution failure if the install is incomplete.docs/index.md— clarify the[isaac]extra installs onlyusd-core+strands-robots, not Isaac Sim.strands_robots_sim/isaac/tests/test_entrypoint.py— replace the assertion that the extra pinsisaacsim/isaaclabwithtest_isaac_extra_pins_only_pip_installable_helpers, which asserts the extra pins onlyusd-coreand must not pinisaacsim/isaaclab(drift guard so the contradiction can't return).Why
Following the documented install yielded a non-bootable environment, and the docs disagreed with packaging about how Isaac Sim is meant to be installed. Option A is the lower-friction, already-mostly-documented path: the Launcher/Docker/Isaac Lab images bundle a complete Kit (interpreter + full
isaacsim-extscache-*extension set), so the pip extra only needsusd-core.Test surface
hatch run lint— passes (black / isort / flake8, 51 files).hatch run test— 203 passed, 33 skipped (skips are GPU/install-gated). Includes the updatedtest_entrypoint.py(16 passed).SimulationAppboot in the new Step 3 snippet was authored from the reporter's verified sequence (create_world → … → renderyielding a real(480, 640, 3)RGB + depth), not re-run here.Acceptance criteria (#108)
isaacsim>=6.0-pin contradiction. (Option A; extra no longer pinsisaacsim/isaaclab.)SimulationAppthat boots and runs the quickstart. (Out-of-band Kit is complete; new Step 3 snippet verifies the boot, and Troubleshooting covers the incomplete-install failure.)Also closes #107 (isaaclab pre-release trap)
This PR also resolves #107. The same
pyproject.tomledit that dropsisaacsimfrom[isaac]also dropsisaaclab>=3.0,<4.0— which #107 reports as independently uninstallable: the onlyisaaclabon the index is the pre-release3.0.0b2, and PEP 440 excludes pre-releases from a>=3.0,<4.0pin by default, so the whole[isaac]extra was unsatisfiable:A follow-up commit on this branch records the #107-specific root cause so it can't drift back in:
pyproject.toml— the[isaac]comment now explains the pre-release/PEP-440 trap and notes that the fleet-RL path installs Isaac Lab from source (./isaaclab.sh -i, already documented indocs/getting-started/installation.md→ Step 1 → Isaac Lab), matching [isaac] extra is uninstallable: isaaclab>=3.0,<4.0 only has pre-release 3.0.0b2 on the index #107's recommended resolution (the core quickstart needs only Isaac Sim; Isaac Lab is fleet-RL only).test_entrypoint.py— theisaaclab not in [isaac]drift-guard assertion message now cites [isaac] extra is uninstallable: isaaclab>=3.0,<4.0 only has pre-release 3.0.0b2 on the index #107 and the pre-release reason.Acceptance criteria (#107)
pip install 'strands-robots-sim[isaac]'resolves cleanly on Python 3.12. (Extra now pins onlyusd-core; noisaaclabpre-release pin.)docs/index.mdquickstart runs with exactly what[isaac]installs. (CoreSimEnginesurface needs only Isaac Sim — validated by the reporter on Isaac Sim 6.0 / Python 3.12 with onlyisaacsim, noisaaclab; Isaac Lab is the fleet-RL path, installed out-of-band from source.)Out of scope (follow-ups, not this PR)
Multiple Installable Client Drivers (ICDs)/CUDA error 101under--/renderer/multiGpu/enabled=True, and exposing GPU/device selection viaIsaacConfig. That's a runtime/config change unrelated to the install-path contradiction and deserves its own issue.Project board
This issue is on the Strands Labs - Robots board; please move #108 and #107 to In review.