Metadata-Version: 2.4
Name: simready-benchmark-engine-kit
Version: 2026.8.0
Summary: Kit / Isaac Sim engine plugin for SimReady Benchmark
Author: NVIDIA Corporation
License-Expression: Apache-2.0
Project-URL: Homepage, https://www.nvidia.com
Keywords: nvidia,simready,test,kit,isaac
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Requires-Python: <3.13,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: simready-benchmark>=2026.8.0
Requires-Dist: usd-core>=23.5
Requires-Dist: physx-usd-schemas<26.0,>=25.11.1
Requires-Dist: numpy>=1.23.0
Requires-Dist: Pillow>=10.0
Requires-Dist: imageio>=2.28.0
Requires-Dist: imageio-ffmpeg>=0.4.8
Dynamic: license-file

# 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.

```bash
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:

```toml
[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:

| 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
  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
