Skip to content

Update docs - isaacsim package and example script#5054

Open
rdsa-nv wants to merge 2 commits intoisaac-sim:developfrom
rdsa-nv:user/ruben/update-install-docs
Open

Update docs - isaacsim package and example script#5054
rdsa-nv wants to merge 2 commits intoisaac-sim:developfrom
rdsa-nv:user/ruben/update-install-docs

Conversation

@rdsa-nv
Copy link
Contributor

@rdsa-nv rdsa-nv commented Mar 18, 2026

Update isaacsim install to workaround old mujoco-usd-converter converter on https://pypi.nvidia.com/mujoco-usd-converter/

Update installation test to use newton

Description

Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context.
List any dependencies that are required for this change.

Fixes # (issue)

Type of change

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (existing functionality will not work without user modification)
  • Documentation update

Screenshots

Please attach before and after screenshots of the change if applicable.

Checklist

  • I have read and understood the contribution guidelines
  • I have run the pre-commit checks with ./isaaclab.sh --format
  • I have made corresponding changes to the documentation
  • My changes generate no new warnings
  • I have added tests that prove my fix is effective or that my feature works
  • I have updated the changelog and the corresponding version in the extension's config/extension.toml file
  • I have added my name to the CONTRIBUTORS.md or my name already exists there

Update isaacsim install to workaround old mujoco-usd-converter converter
on https://pypi.nvidia.com/mujoco-usd-converter/

Update installation test to use newton
@github-actions github-actions bot added the documentation Improvements or additions to documentation label Mar 18, 2026
@greptile-apps
Copy link
Contributor

greptile-apps bot commented Mar 18, 2026

Greptile Summary

This PR updates the Newton physics integration installation documentation with two changes: (1) adds --index-strategy unsafe-best-match --prerelease=allow flags to the isaacsim install command as a workaround for the old mujoco-usd-converter package on pypi.nvidia.com, and (2) updates the verification command to use the Newton visualizer via --viz newton presets=newton.

  • The isaacsim install command now includes --index-strategy unsafe-best-match, which allows uv to pick the best-matching package version across multiple indexes — a standard workaround for multi-index scenarios.
  • The --prerelease=allow flag is added without an inline explanation; while it resolves the mujoco-usd-converter conflict, it applies globally to all resolved packages, not just isaacsim.
  • The verification command is updated to pass the Newton physics preset (presets=newton) as a Hydra override alongside --viz newton, which is consistent with how zero_agent.py handles remaining CLI arguments (forwarding them to Hydra via parse_known_args).
  • The file is missing a trailing newline, which may cause pre-commit end-of-file-fixer failures.

Confidence Score: 4/5

  • This PR is safe to merge — it is a documentation-only change with no impact on source code or tests.
  • The changes are confined to a single .rst documentation file. The install command flags are reasonable workarounds and the updated verification command aligns with the Newton physics integration. Minor issues include a missing trailing newline and the undocumented broad scope of --prerelease=allow.
  • No files require special attention beyond the minor style issues noted in docs/source/experimental-features/newton-physics-integration/installation.rst.

Important Files Changed

Filename Overview
docs/source/experimental-features/newton-physics-integration/installation.rst Documentation update: adds --index-strategy unsafe-best-match --prerelease=allow to the isaacsim install command as a workaround for an old mujoco-usd-converter, and updates the verification command to use the Newton visualizer (--viz newton presets=newton). Minor issues: missing trailing newline at EOF and undocumented broad scope of --prerelease=allow.

Sequence Diagram

sequenceDiagram
    participant User
    participant uv as uv (package manager)
    participant pypi_nvidia as pypi.nvidia.com
    participant PyPI as pypi.org
    participant IsaacLab as isaaclab.sh

    User->>uv: uv pip install "isaacsim[all,extscache]==6.0.0"<br/>--extra-index-url https://pypi.nvidia.com<br/>--index-strategy unsafe-best-match<br/>--prerelease=allow
    uv->>pypi_nvidia: Resolve isaacsim==6.0.0 and dependencies
    uv->>PyPI: Resolve remaining dependencies (best match across indexes)
    pypi_nvidia-->>uv: isaacsim packages
    PyPI-->>uv: Other dependencies
    uv-->>User: Installation complete

    User->>IsaacLab: ./isaaclab.sh -p scripts/environments/zero_agent.py<br/>--task Isaac-Cartpole-Direct-v0<br/>--num_envs 128 --viz newton presets=newton
    IsaacLab->>IsaacLab: parse_known_args() → --viz newton handled by AppLauncher
    IsaacLab->>IsaacLab: presets=newton forwarded to Hydra as override
    IsaacLab-->>User: Newton physics simulation running with Newton visualizer
Loading

Last reviewed commit: "update docs"

.. code-block:: bash

./isaaclab.sh -p scripts/environments/zero_agent.py --task Isaac-Cartpole-Direct-v0 --num_envs 128
./isaaclab.sh -p scripts/environments/zero_agent.py --task Isaac-Cartpole-Direct-v0 --num_envs 128 --viz newton presets=newton No newline at end of file
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Missing newline at end of file

The file no longer ends with a trailing newline (indicated by \ No newline at end of file in the diff). RST files conventionally end with a newline, and many pre-commit hooks (e.g. end-of-file-fixer) will flag this and prevent the commit from passing.

Suggested change
./isaaclab.sh -p scripts/environments/zero_agent.py --task Isaac-Cartpole-Direct-v0 --num_envs 128 --viz newton presets=newton
./isaaclab.sh -p scripts/environments/zero_agent.py --task Isaac-Cartpole-Direct-v0 --num_envs 128 --viz newton presets=newton


uv pip install "isaacsim[all,extscache]==6.0.0" --extra-index-url https://pypi.nvidia.com

uv pip install "isaacsim[all,extscache]==6.0.0" --extra-index-url https://pypi.nvidia.com --index-strategy unsafe-best-match --prerelease=allow
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 --prerelease=allow broadens scope beyond isaacsim

The --prerelease=allow flag instructs uv to allow pre-release versions for all packages resolved during this install, not just isaacsim. This means a pre-release version of an unrelated transitive dependency could be silently chosen over a stable release, potentially introducing instability.

If the intent is only to unblock isaacsim==6.0.0 (which itself is a specific pinned version), consider whether --prerelease=allow is strictly necessary — or add an inline comment to document why it's needed:

Suggested change
uv pip install "isaacsim[all,extscache]==6.0.0" --extra-index-url https://pypi.nvidia.com --index-strategy unsafe-best-match --prerelease=allow
uv pip install "isaacsim[all,extscache]==6.0.0" --extra-index-url https://pypi.nvidia.com --index-strategy unsafe-best-match --prerelease=allow

At a minimum, consider adding a .. note:: block below explaining that these flags are a workaround for the old mujoco-usd-converter on pypi.nvidia.com, so future readers understand why they are present.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant