[Core] Move scripts, examples, and docs to launch_simulation (2/3)

docs/source/api/lab_physx/isaaclab_physx.app.rst

@@ -11,11 +11,6 @@ isaaclab\_physx.app
       KitStageBackend
       KitStageBackendCfg
 
-   .. rubric:: Functions
-
-   .. autosummary::
-
-      show_stage_in_viewport
 
 Environment variables
 ---------------------
@@ -164,7 +159,5 @@ Kit Stage
    :members:
    :show-inheritance:
 
-.. autofunction:: show_stage_in_viewport
-
 .. _livestream: https://docs.isaacsim.omniverse.nvidia.com/latest/installation/manual_livestream_clients.html
 .. _`WebRTC Livestream`: https://docs.isaacsim.omniverse.nvidia.com/latest/installation/manual_livestream_clients.html#isaac-sim-short-webrtc-streaming-client

docs/source/concepts/renderers.rst

@@ -350,14 +350,14 @@ Configure the behavior through :class:`~isaaclab_physx.renderers.IsaacRtxRendere
    renderer_cfg = IsaacRtxRendererCfg(enable_scene_partitioning=False)
 
 Scene partitioning and the all-environment spectator view are separate controls.
-:class:`~isaaclab.app.AppLauncher` enables spectator support before RTX startup only
+:class:`~isaaclab_physx.app.KitLauncher` enables spectator support before RTX startup only
 when the Kit viewport is enabled or Kit visualization, recording, livestreaming, or XR
 is requested. Regular headless training and camera-sensor runs keep it disabled so
 tiled cameras are not exposed to the spectator mode's world-space layout constraints.
 
 ``global_settings.show_all_partitions_by_default`` maps to that same process-global RTX
 setting; it is not a separate feature. Its default value of ``None`` preserves the
-launch-time choice made by :class:`~isaaclab.app.AppLauncher`. An explicit value overrides
+launch-time choice made by :class:`~isaaclab_physx.app.KitLauncher`. An explicit value overrides
 that setting when the Isaac RTX renderer is constructed. When enabled, environments must
 remain spatially separated because overlapping partition bounds can make content leak into
 another environment or disappear. When disabled, the Kit viewport displays only the

docs/source/concepts/sensors/ray_caster.rst

@@ -44,7 +44,7 @@ Querying the sensor for data can be done at simulation run time like any other s
     .
     .
     # Simulate physics
-    while simulation_app.is_running():
+    while sim.is_running():
       .
       .
       .

docs/source/features/reproducibility.rst

@@ -23,8 +23,8 @@ depending on the manager-based or direct environment implementation respectively
 The ``--deterministic`` flag
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The ``--deterministic`` flag is provided by :meth:`isaaclab.app.AppLauncher.add_app_launcher_args`.
-:class:`~isaaclab.app.app_launcher.AppLauncher` publishes ``/isaaclab/render/deterministic``.
+The ``--deterministic`` flag is provided by :func:`isaaclab.app.add_launcher_args`.
+:class:`~isaaclab_physx.app.KitLauncher` publishes ``/isaaclab/render/deterministic``.
 The Isaac RTX backend reads it on init and applies
 :func:`isaaclab_physx.renderers.isaac_rtx_renderer_utils.apply_isaac_rtx_determinism_settings`.
 

docs/source/features/visualizer_tiled_camera.rst

@@ -34,7 +34,7 @@ This guide is accompanied by the ``run_tiled_camera_visualizer.py`` script in
 
    .. literalinclude:: ../../../scripts/tutorials/07_visualizers/run_tiled_camera_visualizer.py
       :language: python
-      :emphasize-lines: 72-78,81-83,89-96,107-109
+      :emphasize-lines: 72-78,81-83,93-99,107-109
       :linenos:
 
 See `Examples`_ below for the two ways the script can be run, and `Usage`_ for the

docs/source/how-to/add_sensors_on_robot.rst

@@ -39,7 +39,7 @@ The tutorial corresponds to the ``add_sensors_on_robot.py`` script in the
 
    .. literalinclude:: ../../../scripts/tutorials/04_sensors/add_sensors_on_robot.py
       :language: python
-      :emphasize-lines: 72-95, 143-153, 167-168
+      :emphasize-lines: 74-96, 147-160, 177-178
       :linenos:
 
 
@@ -90,6 +90,16 @@ and ``"front_cam"`` is the name of the prim associated with the camera sensor.
    :start-at: camera = CameraCfg(
    :end-before: height_scanner = RayCasterCfg(
 
+Camera sensors need the simulator's rendering extensions, also when running without a visualizer.
+:func:`~app.launch_simulation` enables them automatically when the configuration it is given contains a
+camera. Since this script passes only the simulation configuration and the camera lives in the scene
+configuration, the script requests camera rendering explicitly after parsing its arguments:
+
+.. literalinclude:: ../../../scripts/tutorials/04_sensors/add_sensors_on_robot.py
+   :language: python
+   :start-at: args_cli = parser.parse_args()
+   :end-at: args_cli.enable_cameras = True
+
 Height scanner
 --------------
 

docs/source/how-to/create_empty.rst

@@ -6,8 +6,8 @@ Creating an empty scene
 .. currentmodule:: isaaclab
 
 This tutorial shows how to launch and control Isaac Sim simulator from a standalone Python script. It sets up an
-empty scene in Isaac Lab and introduces the two main classes used in the framework, :class:`app.AppLauncher` and
-:class:`sim.SimulationContext`.
+empty scene in Isaac Lab and introduces the two main entry points used in the framework, the
+:func:`app.launch_simulation` context manager and the :class:`sim.SimulationContext` class.
 
 Please review `Isaac Sim Workflows`_ prior to beginning this tutorial to get
 an initial understanding of working with the simulator.
@@ -23,40 +23,37 @@ The tutorial corresponds to the ``create_empty.py`` script in the ``scripts/tuto
 
    .. literalinclude:: ../../../scripts/tutorials/00_sim/create_empty.py
       :language: python
-      :emphasize-lines: 18-30,34,40-44,46-47,51-54,60-61
+      :emphasize-lines: 18-27,31,37-44,46-47,51-54
       :linenos:
 
 
 The Code Explained
 ~~~~~~~~~~~~~~~~~~
 
-Launching the simulator
------------------------
-
-The first step when working with standalone Python scripts is to launch the simulation application.
-This is necessary to do at the start since various dependency modules of Isaac Sim are only available
-after the simulation app is running.
+Parsing the command-line arguments
+----------------------------------
 
-This can be done by importing the :class:`app.AppLauncher` class. This utility class wraps around
-:class:`isaacsim.SimulationApp` class to launch the simulator. It provides mechanisms to
-configure the simulator using command-line arguments and environment variables.
+A standalone script starts by parsing its command-line arguments. The simulator itself is not started yet:
+it is launched later, once we know which runtime the simulation configuration needs.
 
-For this tutorial, we mainly look at adding the command-line options to a user-defined
-:class:`argparse.ArgumentParser`. This is done by passing the parser instance to the
-:meth:`app.AppLauncher.add_app_launcher_args` method, which appends different parameters
-to it. These include launching the app headless, configuring different Livestream options,
-and enabling off-screen rendering.
+The launch-related command-line options are added to a user-defined :class:`argparse.ArgumentParser`
+by passing the parser instance to the :func:`app.add_launcher_args` function. It appends options such as
+``--device`` to choose the simulation device, ``--visualizer`` (or ``--viz``) to open a visualizer window,
+and ``--livestream`` to stream the simulator. These options are later handed to
+:func:`app.launch_simulation`.
 
 .. literalinclude:: ../../../scripts/tutorials/00_sim/create_empty.py
    :language: python
    :start-at: import argparse
-   :end-at: simulation_app = app_launcher.app
+   :end-at: args_cli = parser.parse_args()
 
 Importing python modules
 ------------------------
 
-Once the simulation app is running, it is possible to import different Python modules from
-Isaac Sim and other libraries. Here we import the following module:
+Isaac Lab configuration classes and utilities can be imported before the simulator is launched. Modules that
+need the running simulator, such as Isaac Sim's ``omni.*`` and ``isaacsim.*`` modules or Isaac Lab classes that
+work on the USD stage, are imported later, after the simulator has been launched, as shown in the following
+tutorials. Here we import the following module:
 
 * :mod:`isaaclab.sim`: A sub-package in Isaac Lab for all the core simulator-related operations.
 
@@ -82,9 +79,17 @@ For this tutorial, we set the physics and rendering time step to 0.01 seconds. T
 by passing these quantities to the :class:`sim.SimulationCfg`, which is then used to create an
 instance of the simulation context.
 
+Before the simulation context can be created, the simulator runtime must be launched. This is done with the
+:func:`app.launch_simulation` context manager. It inspects the given configuration together with the parsed
+command-line arguments and starts only the runtime that they need: the default PhysX physics backend runs
+inside Isaac Sim (Kit), so Isaac Sim is started here, while a kitless backend such as Newton needs no Isaac Sim
+at all. The simulation runs headless unless a visualizer is requested, for example with ``--viz kit``.
+Everything that uses the simulator runs inside the ``with`` block, and the runtime is closed automatically
+when the block exits.
+
 .. literalinclude:: ../../../scripts/tutorials/00_sim/create_empty.py
    :language: python
-   :start-at: # Initialize the simulation context
+   :start-at: # Configure the simulation
    :end-at: sim.set_camera_view([2.5, 2.5, 2.5], [0.0, 0.0, 0.0])
 
 
@@ -112,10 +117,11 @@ properly.
    :meth:`sim.SimulationContext.reset` is different from :meth:`sim.SimulationContext.play` method as the latter
    only plays the timeline and does not initializes the physics handles.
 
-After playing the simulation timeline, we set up a simple simulation loop where the simulator is stepped repeatedly
-while the simulation app is running. The method :meth:`sim.SimulationContext.step` takes in as argument :attr:`render`,
-which dictates whether the step includes updating the rendering-related events or not. By default, this flag is
-set to True.
+After playing the simulation timeline, we set up a simple simulation loop where the simulator is stepped repeatedly.
+The loop condition :meth:`sim.SimulationContext.is_running` keeps it running
+forever when no visualizer is open, and until the last visualizer window is closed otherwise.
+The method :meth:`sim.SimulationContext.step` takes in as argument :attr:`render`, which dictates whether
+the step includes updating the rendering-related events or not. By default, this flag is set to True.
 
 .. literalinclude:: ../../../scripts/tutorials/00_sim/create_empty.py
    :language: python
@@ -125,13 +131,8 @@ set to True.
 Exiting the simulation
 ----------------------
 
-Lastly, the simulation application is stopped and its window is closed by calling
-:meth:`isaacsim.SimulationApp.close` method.
-
-.. literalinclude:: ../../../scripts/tutorials/00_sim/create_empty.py
-   :language: python
-   :start-at: # close sim app
-   :end-at: simulation_app.close()
+There is no explicit shutdown call. When the simulation loop ends and the ``with launch_simulation(...)``
+block exits, the simulator runtime is stopped and its window is closed.
 
 
 The Code Execution
@@ -153,7 +154,7 @@ you can either close the window, or press ``Ctrl+C`` in the terminal.
     :alt: result of create_empty.py
 
 Passing ``--help`` to the above script will show the different command-line arguments added
-earlier by the :class:`app.AppLauncher` class. To run the script headless, omit the visualizer
+earlier by the :func:`app.add_launcher_args` function. To run the script headless, omit the visualizer
 selection:
 
 .. code-block:: bash

docs/source/how-to/create_manager_base_env.rst

@@ -41,7 +41,7 @@ directory.
 
    .. literalinclude:: ../../../scripts/tutorials/03_envs/create_cartpole_base_env.py
       :language: python
-      :emphasize-lines: 47-51, 54-71, 74-108, 111-130, 135-139, 144, 148, 153-154, 160-161
+      :emphasize-lines: 50-54, 57-74, 77-111, 114-132, 138-144, 153, 159
       :linenos:
 
 The Code Explained
@@ -181,6 +181,12 @@ method to step the environment. Both these functions return the observation and
 which may contain additional information provided by the environment. These can be used by an
 agent for decision-making.
 
+Before the environment is created, its configuration is passed to :func:`app.launch_simulation`, which
+launches the simulator runtime that the configuration needs and closes it when the ``with`` block exits.
+Inside this block, :func:`~isaaclab.utils.instantiate` constructs the environment from the class named by
+the configuration's :attr:`~envs.ManagerBasedEnvCfg.class_type` attribute. The class is resolved lazily, so the environment
+class, which works on the USD stage, is only imported once the simulator runtime is running.
+
 The :class:`envs.ManagerBasedEnv` class does not have any notion of terminations since that concept is
 specific for episodic tasks. Thus, the user is responsible for defining the termination condition
 for the environment. In this tutorial, we reset the simulation at regular intervals.

docs/source/how-to/create_manager_rl_env.rst

@@ -51,7 +51,7 @@ The script for running the environment ``run_cartpole_rl_env.py`` is present in
 
    .. literalinclude:: ../../../scripts/tutorials/03_envs/run_cartpole_rl_env.py
       :language: python
-      :emphasize-lines: 38-42, 56-57
+      :emphasize-lines: 45-52, 67
       :linenos:
 
 
@@ -147,8 +147,8 @@ Running the simulation loop
 ---------------------------
 
 Coming back to the ``run_cartpole_rl_env.py`` script, the simulation loop is similar to the previous tutorial.
-The only difference is that we create an instance of :class:`envs.ManagerBasedRLEnv` instead of the
-:class:`envs.ManagerBasedEnv`. Consequently, now the :meth:`envs.ManagerBasedRLEnv.step` method returns additional signals
+The only difference is that the configuration's ``class_type`` creates an instance of :class:`envs.ManagerBasedRLEnv`
+instead of the :class:`envs.ManagerBasedEnv`. Consequently, now the :meth:`envs.ManagerBasedRLEnv.step` method returns additional signals
 such as the reward and termination status. The information dictionary also maintains logging of quantities
 such as the reward contribution from individual terms, the termination status of each term, the episode length etc.
 

docs/source/how-to/create_scene.rst

@@ -42,7 +42,7 @@ This tutorial corresponds to the ``create_scene.py`` script within
 
    .. literalinclude:: ../../../scripts/tutorials/02_scene/create_scene.py
       :language: python
-      :emphasize-lines: 50-63, 68-70, 91-92, 99-100, 105-106, 116-118
+      :emphasize-lines: 50-63, 68-70, 97-98, 105-106, 111-112, 125-127
       :linenos:
 
 
@@ -103,15 +103,21 @@ Scene instantiation
 -------------------
 
 Unlike before where we called the ``design_scene`` function to create the scene, we now
-create an instance of the :class:`scene.InteractiveScene` class and pass in the configuration
-object to its constructor. While creating the configuration instance of ``CartpoleSceneCfg``
-we specify how many environment copies we want to create using the ``num_envs`` argument.
-This will be used to clone the scene for each environment.
+create an instance of the :class:`scene.InteractiveScene` class from the configuration object.
+The configuration names the class it builds in its :attr:`~scene.InteractiveSceneCfg.class_type`
+attribute, so :func:`~isaaclab.utils.instantiate` constructs the scene from it. While creating the
+configuration instance of ``CartpoleSceneCfg`` we specify how many environment copies we want to
+create using the ``num_envs`` argument. This will be used to clone the scene for each environment.
 
 .. literalinclude:: ../../../scripts/tutorials/02_scene/create_scene.py
    :language: python
    :start-at: # Design scene
-   :end-at: scene = InteractiveScene(scene_cfg)
+   :end-at: scene = instantiate(scene_cfg)
+
+The configuration class ``CartpoleSceneCfg`` can be defined at the top of the script, but the
+:class:`scene.InteractiveScene` class works on the USD stage of the running simulator. The
+``class_type`` attribute resolves the class lazily, so the scene class is only imported when it is
+constructed inside the ``with launch_simulation(...)`` block, once the simulator runtime has been launched.
 
 Accessing scene elements
 ------------------------

docs/source/how-to/index.rst

@@ -54,7 +54,7 @@ How-to Guides
 
       .. container:: guide-entry
 
-         :doc:`Deep-dive into AppLauncher </source/how-to/launch_app>`
+         :doc:`Deep-dive into launching the simulation </source/how-to/launch_app>`
 
          Configure and launch simulation applications from Python and the command line.