[ooctipus]

Description

Part 1 of 2: the design. The migration of every script and test is in the stacked follow-up, #8090. This PR keeps existing scripts running unchanged, so the two halves can be reviewed separately.

launch_simulation now starts each simulation runtime through the launcher that the runtime's own backend package provides. The resolved config says which launcher is needed, so core never imports one.

# isaaclab.app: the interface every backend runtime implements
class SimulationLauncher:
    device: str | None = None                 # optional device the runtime picked
    def __init__(self, launcher_args): ...    # constructing it starts the runtime
    def close(self, exit_code: int = 0): ...  # stops it

# backend configs name their launcher, resolved lazily like ``class_type``
class PhysxCfg(PhysicsCfg):
    launcher_type: ClassVar[str] = "isaaclab_physx.app:KitLauncher"
class OVRTXRendererCfg(RendererCfg):
    launcher_type: ClassVar[str] = "isaaclab_ov.app:OvrtxLauncher"

launch_simulation(cfg, args) scans the resolved config as it already did and collects launcher_type from the physics and renderer config instances it resolved. It constructs each launcher once and closes them in reverse order when the block exits. Kit needs that no config names (require_kit, no physics config, a Kit visualizer requested only on the CLI) fall back to KitLauncher.

• isaaclab_physx.app.KitLauncher is the old AppLauncher body, minus dead code:
  • removed: argument-collision bookkeeping, the Isaac Sim 5 branch, and the hidden --cpu flag;
  • moved in from launch_simulation: the Isaac Sim availability check and the "Kit already running" guard.
• isaaclab_ov.app.OvrtxLauncher registers the OVRTX USD schemas, which launch_simulation used to do inline.
• Moved into sim_launcher.py because kitless launches need them too: argv fusing, visualizer argument normalization, and the visualizer-settings sync (no longer wrapped in a blanket suppress(Exception)).

Kit stays in isaaclab_physx

Core code no longer imports carb, omni, or omni.replicator. Kit concerns go through one of two owners, and no new global hook is added.

• The SimulationContext backend registry owns anything tied to a simulation's lifetime:
  • isaaclab_physx.app.KitStageBackend is registered through get_or_create_backend when Kit runs;
  • it attaches the stage to Kit's USD context and closes Kit's context stage when clear_instance() closes the other backends;
  • core stage utilities never touch Kit: clear_stage()/close_stage() are Kit-free, and Kit's own consumers (PhysX reset/step, RTX render, the Kit visualizer) run the app updates they need.
• No defensive None handling on invariants: a SimulationContext always has a stage, so consumers read SimulationContext.instance().stage directly (SceneDataProvider.usd_stage / get_usd_stage are removed).
• KitLauncher owns one-time process setup:
  • SettingsManager.set_backend(carb.settings), replacing initialize_carb_settings and is_omniverse_mode;
  • sharing Isaac Sim's stage-helper context;
  • one app update in close(), so scripts no longer need their own.
• Replicator is enabled by the Isaac RTX renderer and seeded by the Replicator event terms that use it. The env classes no longer import it.
• show_stage_in_viewport moves to isaaclab_physx.app, since it only works under Kit.
• Gravity: tasks set it through PhysxManager.set_gravity instead of carb.Float3.

Exit handling

The ~110-line _SimulationAppLifecycle class from #6636 is gone. I measured a real Kit process with no handlers installed, and only two exit paths needed help. Both are now handled by two lines in KitLauncher:

• An unhandled exception exits with 1. Kit's exit path reported 0.
• SIGINT raises KeyboardInterrupt. Kit's own handler exited 0.

SIGTERM, SIGABRT, and SIGSEGV keep their default actions. Fixes #7774, supersedes #7775 and #6531.

Constructing runtime objects after launch

Importing pxr.Usd before Kit starts makes Kit fail to start. Scripts therefore import only config classes and construct runtime objects with instantiate(cfg) (#8085), which resolves the config's lazy class_type after the runtime is up.

• ManagerBasedEnvCfg and ManagerBasedRLEnvCfg gain class_type.
• The 21 task configs with a custom env class name it. A registry test checks that all 126 match their registered entry point.
• Fixed: {DIR} in an inherited class_type resolved against the module of a subclass missing @configclass, so the call failed with ModuleNotFoundError.

Compatibility in this PR

isaaclab.app.AppLauncher is deprecated. It now starts Kit through launch_simulation, so develop's scripts and tests run unchanged here. It still offers is_available, has_gui, and has_window, which unmigrated scripts use. The migration PR moves every caller and reduces it to an init-only shim.

isaaclab.test.utils.launch_test_simulation(**launcher_args) starts Kit for a test module through launch_simulation. It picks the test device by default.

Behavior changes

• Removed (breaking; each only restated an invariant or forwarded elsewhere):
  • sim_utils.update_stage: the simulation's reset, step, and render process stage changes;
  • sim_utils.is_current_stage_in_memory: compare against SimulationContext.instance().stage;
  • sim_utils.show_stage_in_viewport: use isaaclab_physx.app.show_stage_in_viewport;
  • SettingsManager.initialize_carb_settings (and the module-level function) and is_omniverse_mode: KitLauncher sets the settings backend, and has_kit() checks for Kit;
  • SceneDataProvider.usd_stage / get_usd_stage;
  • the hidden --cpu flag: use --device cpu.
• Replicator seeding: the Replicator event terms seed it with env.cfg.seed when they are built; _get_replicator() only loads it. Calling env.seed(x) later no longer reseeds Replicator.
• Kit startup marker is now [ISAACLAB] KitLauncher initialization complete, and tools/conftest.py is updated to match.
• SIGTERM ends the process immediately, without a Kit teardown.
• Warp environments: render_mode="rgb_array" now warns and returns None, matching the core environments.

Net: +2,326 / −3,045 across 154 files.

Type of change

• Breaking change (AppLauncher deprecated; Kit-coupled helpers removed; Kit exit and seeding behavior changed)

Validation

All runs on the display GPU (GPU 0), with develop's scripts and tests unchanged unless listed here.

• Launcher, app, and config tests:
  • isaaclab/test/app (26) and isaaclab_physx/test/app (88);
  • test_runtime_compatibility (27), visualizer intent (8), distributed device (13), test_preset_kit_decision (6), test_preset_cli (11);
  • test_configclass (37), test_sb3_leapp_export, and the CLI tests (234).
• Kit tests through the deprecated adapter:
  • test_simulation_context (30), PhysX test_rigid_object (44), test_camera (21);
  • stage utils (15), stage in memory (3), test_events (4), texture randomization (2), test_manager_based_env (4).
• Training: train.py --task Isaac-Cartpole --max_iterations 2 exits 0 with isaacsim_physx and newton_mjwarp.
  • physics=physx (kitless ovphysx) fails with an observation batch mismatch.
  • Develop 93b6e7432 fails the same way, so it is unrelated to this PR.
• Every script under scripts/ and examples/, compared against develop with the same invocation:
  • Scripts outside the standalone matrix (78): same outcome on develop and here. 52 run, 19 are blocked by an external resource (datasets, XR, Ray, gr00t, robomimic, moviepy), and 7 fail identically on develop.
  • Standalone matrix (361 cases): no regressions. The only case that first looked new was an old-style script with --visualizer newton_rtx. Kit and OVRTX cannot share a process, so the adapter now skips that visualizer with a warning, as Kit did on develop.
  • Newton-based visualizers next to Kit PhysX: those cases fail on develop too, when Newton builds its model from USD.
• After rebasing onto the latest develop: the state machines, bin_packing, and Cartpole training still run.
• Known pre-existing failure: test_visualizer_integration_newton has a flat-frame check that fails identically on develop.
• Pre-commit passes. The changelog check only flags fragments from other PRs, because it compares against the fork's stale develop.

Release backport

• Backport this pull request to the active release branch after it merges into develop

Checklist

• I have read and understood the contribution guidelines
• I have run the pre-commit checks
• I have made corresponding changes to the documentation (API pages for isaaclab.app, isaaclab_physx.app, isaaclab_ov.app)
• My changes generate no new warnings
• I have added changelog fragments for every touched package

[isaaclab-review-bot]

Isaac Lab Review Bot

The lifecycle policy is cleanly relocated and documented, but dropping exception suppression around SimulationApp.close() changes failure behavior during shutdown and can prevent SIGTERM from producing the documented signal-derived status.

• Design and architecture: The closure-based installer retains the prior lifecycle structure without a demonstrated layering or dependency break. The new isaaclab_physx.app entry point is integrated through the package’s lazy-export pattern.
• API: The new public function is exported and documented consistently, and the removed lifecycle class was private. However, the documented SIGTERM exit-status guarantee is not maintained when app.close() raises.
• Implementation: The normal status values, handler disarming, and post-close signal re-raise follow the prior implementation. Unlike the replaced class, the new callbacks do not suppress exceptions from app.close(); on SIGTERM this skips signal.raise_signal(signum), allowing a traceback, exit 1, or caller interception instead of the intended signal termination. Restore exception suppression while ensuring the re-raise remains unconditional.

Minor fixes needed. Posted 1 actionable finding inline.

Automated review; human maintainers own approval decisions.

[isaaclab-review-bot]

🔵 Suggestion · Implementation — Close failure now skips the SIGTERM re-raise

The replaced handler wrapped close() in contextlib.suppress(Exception) precisely so a teardown failure still reached signal.raise_signal(signum). Here an exception from app.close(exit_code=128 + signum) escapes the handler into the interrupted frame, so the process can report a traceback/exit 1 (or be swallowed by user code) instead of the documented 128+signum. Restore the suppression around both close calls, keeping the re-raise unconditional.

[greptile-apps]

Confidence Score: 3/5

[Medium risk] Refactors process lifecycle handling for the simulation app.

The PR is not ready to merge because standalone core imports can fail and SIGTERM teardown can miss its required termination path.

Findings

1.  Optional backend becomes required ▶
2.  Close errors interrupt SIGTERM shutdown ▶

Summary

The PR moves Kit exit handling from AppLauncher into a small isaaclab_physx.app function, stops overriding SIGABRT, and updates lifecycle tests and API documentation.

• The new core-to-PhysX import conflicts with the packages’ optional-dependency boundary.
• SIGTERM teardown no longer guarantees the intended exit path if closing raises.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Import AppLauncher] --> B{isaaclab_physx installed?}
    B -->|No| C[ModuleNotFoundError]
    B -->|Yes| D[Launch SimulationApp]
    D --> E[Install exit handlers]
    E --> F{Exit path}
    F -->|Normal exit| G[Close app with exit code]
    F -->|SIGTERM| H[Restore SIGTERM default]
    H --> I[Close app with signal status]
    I -->|Returns| J[Re-raise SIGTERM]
    I -->|Raises| K[Re-raise skipped]

Loading

_{Reviews (1) · Last reviewed commit: "Replace AppLauncher lifecycle class with..."}

[greptile-apps]

Optional backend becomes required If an installation contains isaaclab but not the optional isaaclab_physx package, importing AppLauncher now raises ModuleNotFoundError. The import happens before callers can use the launcher or its argument helpers, even though isaaclab does not declare a dependency on isaaclab_physx.

Knowledge Base Used: Physics backend extensions

[greptile-apps]

Close errors interrupt SIGTERM shutdown If app.close() raises during SIGTERM teardown, the handler never reaches signal.raise_signal(signum). It has already restored the default signal action but does not send the signal again, so this path no longer guarantees termination with the intended signal status. The previous handler continued to re-raise SIGTERM after a close error.

[StafaH]

Maybe we can keep the app launcher in isaaclab core, now that I see the import change across the whole codebase, everyone has to import isaaclab_physx which doesn't look good

[ooctipus]

run-ci

[ooctipus]

run-ci

[isaaclab-bot]

Backported to release/3.0.0 as 75137de.