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. Install and verify it in the active Python 3.12 environment with:

simready-benchmark --setup --install-isaac

The plugin automatically exposes this launcher as isaac_sim (PhysX) and isaac_sim_newton (Newton). No engines.toml is required. The following file is only an advanced override for a standalone/custom install:

[kit.isaac_sim]
executable_path = "C:/simready/.venv/Scripts/isaacsim.EXE"
version = "6.0.1.0"  # auto-detected from the install; yours may differ
tags = ["isaac", "kit"]

[kit.isaac_sim_newton]
executable_path = "C:/simready/.venv/Scripts/isaacsim.EXE"
version = "6.0.1.0"
tags = ["isaac", "kit"]
experience = "isaacsim.exp.full.newton"  # selects the Newton physics app variant

On Linux the launcher is isaacsim (no .EXE). 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:

Field	Description
executable_path	Path to the engine launcher (.bat, .sh, or native binary)
version	Engine version string, for example "6.0.1.0" (auto-detected from the install)
tags	Capability tags used to match the engine to test requirements
experience	Optional Kit .kit experience selecting the app variant to launch, for example "isaacsim.exp.full.newton" for the Newton physics engine. Empty or absent uses the launcher default (PhysX). This field is read by the Kit plugin only
driver_compatibility	Optional list of OS and version-range driver checks

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

Section	Purpose
[paths].sr_specs = "<path>"	Override the sr_specs directory. Lower-priority than the CLI flag and $SIMREADY_SR_SPECS, but higher than project_config.toml, which is the recommended home for sr_specs.
[tests].paths = [...]	On-disk test-pack source directories (unpublished or custom packs). Each path is a SOURCE directory (__init__.py lives there). This setting overrides project_config.toml [tests].paths but is overridden by --tests-path and $SIMREADY_BENCHMARK_TESTS_PATH. A Foundation project config also discovers tier-owned test packages from that checkout.

---

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 simready-benchmark --setup --install-isaac; setup uses extended pip timeouts and retries and verifies the repaired environment.

---

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