Document OpenUSD parser thread-limit workaround

[kellyguo11]

Description

Document the known OpenUSD physics-parser race that can terminate Newton workflows while loading collider-rich rigid bodies.

The Known Issues page now explains:

• the affected kitless OpenUSD versions and Isaac Sim releases prior to 6.1;
• that Isaac Sim 6.1 and later contain the upstream fix;
• that kitless Isaac Lab obtains pxr from usd-exchange, while usd-core is an alternative provider with a different distribution version scheme;
• the PXR_WORK_THREAD_LIMIT=1 workaround for affected Linux and Windows workflows; and
• that limiting OpenUSD's process-wide worker pool can reduce USD import performance.

Related to Isaac Sim #692, OpenUSD #4002, and NVIDIA NVBug 6592534.

No dependencies are added.

Type of change

• Documentation update

Screenshots

Not applicable.

Checklist

• I have read and understood the contribution guidelines.
• I have run the pre-commit checks with uv run isaaclab -f.
• I have made corresponding changes to the documentation.
• My changes generate no new warnings.
• Documentation-only change; no runtime test is required.
• Documentation-only change; no package changelog fragment is required.
• My name already exists in CONTRIBUTORS.md.

Validation

• make -C docs current-docs (with the project environment and non-interactive EULA acceptance)
• UV_FROZEN=1 ISAACLAB_CHANGELOG_BASE_REF=codex-doc-base uv run isaaclab -f (the temporary local base-ref alias pointed to upstream/develop)

Release backport

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

[greptile-apps]

Greptile Summary

This PR documents an OpenUSD physics-parser race affecting collider-rich Newton workflows, including affected versions, failure symptoms, thread-limit workarounds, and their performance tradeoff.

• Adds Linux and Windows examples for setting PXR_WORK_THREAD_LIMIT.
• Adds Kit-specific guidance using AppLauncher.limit_cpu_threads.
• Links the upstream OpenUSD fix.
• The Kit example currently omits the startup environment setting required by the repository's existing workaround.

Confidence Score: 4/5

This documentation should not merge until the Kit workaround also preserves the required pre-startup PXR_WORK_THREAD_LIMIT setting.

The new Kit example can leave OpenUSD's worker pool unrestricted because limit_cpu_threads is applied through SimulationApp after OpenUSD reads its startup environment, so users may still experience the crash the documentation is intended to prevent.

Files Needing Attention: docs/source/refs/issues.rst

Important Files Changed

Filename	Overview
docs/source/refs/issues.rst	Adds the OpenUSD parser-race documentation, but presents the later-applied Kit thread limit as a sufficient replacement for the startup environment variable.

_{Reviews (1): Last reviewed commit: "Document OpenUSD parser thread limit" | Re-trigger Greptile}

[greptile-apps]

Kit workaround is insufficient

For Kit-based scripts, limit_cpu_threads=1 is not equivalent to setting PXR_WORK_THREAD_LIMIT=1. AppLauncher forwards the value to SimulationApp, but only distributed launches set the environment variable. Existing tests note that OpenUSD reads this variable before SimulationApp applies its limit. Users who follow this example can therefore remain exposed to the parser race and still encounter crashes or hangs. Please document that PXR_WORK_THREAD_LIMIT must also be set before process startup.

[isaaclab-review-bot]

Isaac Lab Review Bot

Reviewed the new Newton Known Issues entry documenting the OpenUSD collider-parser race and its single-thread workarounds. The documentation is integrated cleanly, and no actionable finding was supplied or established by the available patch context.

• Design and architecture: The subsection is appropriately placed under "Newton backends," preserves the existing section hierarchy and anchor, and groups the new OpenUSD reference with the page’s existing link targets.
• API: No API or configuration behavior changes. The documented compatibility surfaces are PXR_WORK_THREAD_LIMIT=1, AppLauncher(headless=True, limit_cpu_threads=1), and the physics=newton_mjwarp preset; the added RST reference resolves to the OpenUSD pull request. The supplied repository context does not independently confirm the launcher argument or affected-version boundary, so those technical claims remain a non-blocking verification consideration.
• Implementation: The heading, tab-set, code-block indentation, and link target are structurally consistent with the surrounding RST. This is confined to documentation, adds no dependency, and does not require a source-package changelog fragment. The documented CPU-performance tradeoff is clearly disclosed.

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.

[kellyguo11]

run-ci

[hujc7]

run-ci

[hujc7]

does this need backport?

[hujc7]

Superseded — re-posted as inline comments anchored to the relevant lines, so each finding sits on the code it concerns. See the inline thread(s) on this PR.

[hujc7]

[P2] Agent found bug: this is false for Isaac Sim 6.0.x, which is the release Isaac Lab pins. Capped at [P2] only because I have already approved this PR — on merit I would fix it before merge.

Kit ships a private OpenUSD, so immunity is per-build:

Line	kit-kernel	USD package	Backport
6.0.1-ga / release/6.0	110.1.2+production	0.25.11.kit.2	absent
release/6.1 / develop	110.3.0+feature.*	0.25.11.kit.5	present

pyproject.toml:169 pins isaacsim[all,extscache]==6.0.1.0, and Newton-under-Kit is an exercised configuration — rendering_test_utils.py:109-114 parametrizes ("franka_cloth", "newton", "isaacsim_rtx_renderer"), with paired Kit and _kitless modules. As written, the entry tells users on the supported install that it does not apply to them.

Suggested:

Isaac Sim 6.1 and newer are not affected: their bundled OpenUSD contains the upstream fix. Isaac Sim 6.0.x does not — apply the workaround there as well.

[hujc7]

[P2] Agent review: this condition, and the removal condition at the end of the section, both name usd-core — a distribution a supported Isaac Lab install never has.

pyproject.toml:73 pins usd-exchange==2.3.0 as the sole USD provider, and test_source_package_metadata.py:50 asserts "usd-core" not in locked. So pip show usd-core returns nothing and a reader cannot tell whether the entry applies to them, or when to stop applying the workaround.

Suggested: key both conditions on the installed version instead.

Affects: kitless Newton workflows on OpenUSD earlier than 26.05. Check with uv run python -c "from pxr import Usd; print(Usd.GetVersion())" — below (0, 26, 5) is affected. Isaac Lab installs OpenUSD through usd-exchange, not usd-core.

[kellyguo11]

run-ci

[isaaclab-bot]

Backported to release/3.0.0 as 282f982.