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-facingEnginePluginimplementation; loaded automatically through thesimready.evaluate.engines:kitentry-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 anEngineConfig.
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:
--engines-toml <FILE>CLI flag$SIMREADY_ENGINES_TOMLenvironment variable (a missing file is a hard error)engines.tomlin the current working directory~/.simready-benchmark/engines.tomlor~/.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
GetTempFileNameWcapture path accepts a directory of at most 246 UTF-16 code units (supplementary Unicode characters count as two). When the canonicalcapturesdirectory exceeds that bound, the plugin captures and performs its existing blank-frame retries in a unique owned directory under the configuredTEMP, 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, writableTEMPbefore launching the worker. Staging requires an explicit absolute temporary-directory setting (TMPDIR, thenTEMP, thenTMP); it never silently falls back to a drive-root folder or the current working directory. Publication failures appear ascapture_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 leavesscene_fileempty and persists ascene_export_failedwarning 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 5inside 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
isaacsimfrom 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-coreprovides the samepxrmodule in the separate validation environment. These distributions are not interchangeable inside one environment: keep Isaac's USD packages separate fromusd-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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.