Skip to main content

simready.evaluate.engine-kit

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

This wheel is the bridge between simready-evaluate (the engine-agnostic core) and an Isaac Sim runtime. Install it, then drive the evaluation through the simready-evaluate command. Refer to the simready-evaluate 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-evaluate[kit]"
# Equivalent to:
pip install simready.evaluate.engine-kit

Both forms pull in simready-evaluate, 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-evaluate package page for the platform-by-platform environment setup (including the Python 3.12 requirement on Ubuntu) and to run a first test.

The native exact-file loader and Framework discovery share provider import isolation. Kit requires Evaluate >=2026.9.0rc2,<2026.11; Evaluate's Kit extra requires engine-kit >=2026.9.0rc3,<2026.11. Use compatible builds in the host and Isaac environments. Source-selected tests use that source's eager and lazy helpers even when an installed copy is already cached. Unknown cache ownership or an incompatible older Framework produces a discovery error, not an unscoped fallback. This import contract is separate from native simulation qualification.

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 Evaluate'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-evaluate README for engine selection. With no --runtime, Evaluate 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 Evaluate extra (for example, simready-foundation-tier-core[evaluate]). 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.evaluate.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

Automatic pip-Isaac discovery only inspects the active Python environment. The recommended separate Isaac environment requires engines.toml, including its launcher and python_executable. The framework resolves configuration through this four-tier lookup:

  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 or ~/.simready-evaluate/engines.toml

On Windows, ~ is %USERPROFILE%. If both home files apply, their normalized settings must agree. Use --engines-toml FILE or SIMREADY_ENGINES_TOML to select explicitly when they differ; unused lower-priority home files are not compared. Reuse an existing home file rather than creating a conflicting second configuration.

Fields per custom engine instance (only executable_path is always required):

Field Description
executable_path Path to the engine launcher (.bat, .sh, or native binary)
python_executable Optional Python interpreter belonging to a separate pip-Isaac environment; configure it alongside that environment's launcher.
runtime Optional explicit physics backend, "PhysX" or "Newton"; preferred over legacy engine-name inference and separate from the CLI engine instance name.
version Optional declared engine identity metadata; defaults to "0.0.0" when omitted. Configured versions are not auto-detected or enforced scheduling gates. Set this to the installed version; automatic active-environment Isaac discovery reads its installed package metadata.
tags Optional capability tags used to match the engine to test requirements; defaults to ["kit"]. Isaac tests normally require both "isaac" and "kit".
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_EVALUATE_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 evaluation. 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-evaluate --rerun failed --output-dir <resolved-run-dir>. Use the resolved directory printed by the original run, not merely its requested output parent: fresh runs can allocate a child directory. A passing retry supports only those test outcomes, not full asset certification. Preserve the original logs and capture warnings (capture_completion_error, capture_file_missing, capture_file_empty). They identify the requested frame/camera, failing capture phase and enforced render settings. Renderer exceptions retain their original cause rather than becoming a missing-image message. Integrated-versus-standalone differences still need a controlled reproduction before assigning the root cause.
  • Long Windows capture directories need native-safe staging. Kit's native GetTempFileNameW capture path accepts a directory of at most 246 UTF-16 code units (supplementary Unicode characters count as two). When the canonical captures directory exceeds that bound, the plugin captures and performs its existing blank-frame retries in a unique owned directory under the configured TEMP, then exclusively publishes the verified non-empty PNG to the original report/result path. It does not rename results or add render/physics steps. Staging is cleaned on success, capture failure, and cancellation; unrelated temporary/result files are preserved. A too-long or unwritable temporary directory fails with a request to choose a shorter, writable TEMP before launching the worker. Staging requires an explicit absolute temporary-directory setting (TMPDIR, then TEMP, then TMP); it never silently falls back to a drive-root folder or the current working directory. Publication failures appear as capture_publication_error, not successful evidence or an asset defect. The native limit is documented in Microsoft's GetTempFileNameW reference.
  • Optional USD scene export fails. The adapter exports a root-layer snapshot into owned staging before publishing test_scene.usda; long Windows paths use a short, explicitly configured temporary directory. It validates the export result and non-empty file, preserves unrelated files, and attempts export only once after a test scene exists. Failure leaves scene_file empty and persists a scene_export_failed warning in result JSON and the report; it does not change the physics verdict. Inspect the original engine log and directory permissions. This snapshot is not a flattened, self-contained USD package, and it retains the root layer's authored references.
  • 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. Evaluate 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 in the separate validation environment. These distributions are not interchangeable inside one environment: keep Isaac's USD packages separate from usd-core, as described in Installation above.

License

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

Metadata

Release files for simready-evaluate-engine-kit 2026.10.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distribution (wheel)

Table of built distributions (wheels) for simready-evaluate-engine-kit 2026.10.0
File Interpreter ABI Platform Actions
simready_evaluate_engine_kit-2026.10.0-py3-none-any.whl Python 3 none any Details for simready_evaluate_engine_kit-2026.10.0-py3-none-any.whl

Release files / simready_evaluate_engine_kit-2026.10.0-py3-none-any.whl

Download URL simready_evaluate_engine_kit-2026.10.0-py3-none-any.whl
Size 205.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2bab39b4d9ff621ba915711539eb3e758092ba7db3f6c7338d3d01d48a12f585
BLAKE2b-256 checksum
How to use checksums
0598cb13f7e650d2e8ab6bdd952982daebbfc3f5753a7dd62f82583ec7bd4215
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.8

Security for simready-evaluate-engine-kit 2026.10.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

2026.10.0 This release

1 release file No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page