simready-benchmark-engine-kit

Kit / Isaac Sim engine plugin for SimReady Benchmark. Provides KitPlugin, registered with the framework through the simready_benchmark.engines entry-point group.

This wheel is the bridge between simready-benchmark (the engine-agnostic core) and an Isaac Sim runtime. Install it, then drive the benchmark through the simready-benchmark command. Refer to the simready-benchmark package page for the full install, setup, and first-test walkthrough; this page covers the Kit and Isaac Sim specifics.

Requirements

Before you install the plugin, make sure your environment meets these requirements:

• Python 3.12 exactly. Isaac Sim requires Python 3.12.
• A 64-bit x86 machine (x86_64, also called AMD64) on Windows 10 or 11, or on Linux (Ubuntu). usd-core, a core dependency, publishes no ARM (aarch64) wheels, so the install fails on ARM machines, including ARM cloud instances.
• A CUDA-capable NVIDIA GPU and about 30 GB of free disk for Isaac Sim.

Installation

Work inside a dedicated Python 3.12 virtual environment.

pip install "simready-benchmark[kit]"
# Equivalent to:
pip install simready-benchmark-engine-kit

Both forms pull in simready-benchmark, usd-core, physx-usd-schemas, numpy, Pillow, and the video-encoding backend as transitive dependencies. The PhysX schema package keeps merge-mesh collision validation available in stock OpenUSD environments outside Kit. Pip honors the active environment's normal index and mirror configuration. You can also install both wheel files from a local repository build. Refer to the simready-benchmark package page for the platform-by-platform environment setup (including the Python 3.12 requirement on Ubuntu) and to run a first test.

Isaac Sim

Isaac Sim is a separate, multi-gigabyte install. Keep pip Isaac in its own Python 3.12 venv so its usd-exchange dependency cannot overwrite Benchmark's usd-core validation files. Configure the venv's launcher and python_executable in engines.toml; the installation guide contains complete Windows and Linux examples. Declare isaac_sim for PhysX and isaac_sim_newton for Newton:

[kit.isaac_sim]
executable_path = "C:/simready/isaac-env/Scripts/isaacsim.exe"
python_executable = "C:/simready/isaac-env/Scripts/python.exe"
version = "6.1.0.0"  # set this to the installed Isaac version
tags = ["isaac", "kit"]
runtime = "PhysX"

[kit.isaac_sim_newton]
executable_path = "C:/simready/isaac-env/Scripts/isaacsim.exe"
python_executable = "C:/simready/isaac-env/Scripts/python.exe"
version = "6.1.0.0"
tags = ["isaac", "kit"]
runtime = "Newton"
experience = "isaacsim.exp.full.newton"  # selects the Newton physics app variant

On Linux use the venv's bin/isaacsim and bin/python. isaac_sim runs default PhysX and isaac_sim_newton launches the Newton experience. Select one per run with --runtime. Refer to the main simready-benchmark README for engine selection. With no --runtime, Benchmark uses all configured engines but runs runtime-specific physics tests only when the asset validation record has the matching feature variant (for example, FET_003_PHYSX or FET_003_NEWTON). Runtime-neutral tests remain eligible on both engines.

Tier Catalogs and Runtime Tests

Install a Foundation tier that supplies the Benchmark extra (for example, simready-foundation-tier-core[benchmark]). Catalogs and tests are then discovered through Python entry points; a Foundation checkout is not required. Asset inputs remain independent and are passed with --assets.

What This Wheel Provides

This wheel provides these Kit integration components:

• KitPlugin. The framework-facing EnginePlugin implementation; loaded automatically through the simready_benchmark.engines:kit entry-point.
• KitSession. A single Kit subprocess and the lifecycle around it.
• KitLogCapture. Structured ingest of Kit's log lines.
• build_kit_command, resolve_kit_runner_path. Helpers for composing the Kit invocation from an EngineConfig.

End-user @test-decorated functions interact with Kit through ctx.scene on the RunContext (a SceneHandle whose concrete type is KitSceneHandle when this plugin is active).

Configuration

Pip Isaac needs no configuration file. If an advanced engines.toml override is present, the framework resolves it through a four-tier lookup (first match wins):

1. --engines-toml <FILE> CLI flag
2. $SIMREADY_ENGINES_TOML environment variable (a missing file is a hard error)
3. engines.toml in the current working directory
4. ~/.simready-benchmark/engines.toml

Required fields per custom engine instance:

Optional sections (handled at the framework level, not the plugin):

Known Issues (Isaac Sim First Run)

These known issues can affect first-run behavior with Isaac Sim:

• The first run on a machine where Isaac Sim has never launched can be very slow or appear to fail until Isaac Sim compiles its shader cache. To warm the cache, launch Isaac Sim directly, wait for the main viewport, open any USD file, then close it. Re-run the benchmark. After one successful run the cache is warm and later runs complete normally.
• A test can fail with an entirely white (blank) comparison frame. Isaac Sim and Kit sometimes do not render a frame in time, which fails the comparison. This is an engine rendering issue, not an asset defect. Re-run only the failed tests with simready-benchmark --rerun failed; if they pass on the second run, the asset is good. If your original run used a custom --output-dir or --project-config, pass the same flag to --rerun failed so it finds the results.
• The Isaac Sim install stalls or fails on a network read timeout. Re-run pip with --timeout 120 --retries 5 inside the separate Isaac venv.
• Newton reports that its contact limit was exceeded. Benchmark discards that attempt and retries the affected test once in a fresh Kit session with a capacity derived from the observed contact count. Adaptive recovery is capped at 65,536 contacts because the solver preallocates this resource and its memory and processing cost grows with capacity. If the retry also overflows or needs more than the ceiling, the result is a runtime error rather than an asset failure. Keep the run output and both session logs; do not tune a single fixed capacity as a general asset workaround.

Compatibility

This plugin has these compatibility constraints:

• Targets the supported pip Isaac Sim release. The plugin pins no specific Isaac Sim or Kit version; setup installs the latest compatible isaacsim from the NVIDIA package index and discovery reads its installed version.
• Inside Kit, from pxr import ... resolves through the Kit runtime. Outside Kit (for plain-Python unit tests, CLI listing, or static analysis on a developer machine without Kit installed), usd-core provides the same pxr module. usd-core is the headless USD distribution, with no GPU or Hydra renderers, so it does not bloat installs that already have Kit.

License

Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. SPDX-License-Identifier: Apache-2.0