Metadata-Version: 2.4
Name: simready-benchmark-engine-kit
Version: 2026.7.1
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.12
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: simready-benchmark>=2026.7.1
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. Install and verify it in the
active Python 3.12 environment with:

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

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