Simplifies device setting in SimulationCfg and AppLauncher (isaac-sim…

…#696)

# Description

Before setting up the device was tedious and redundant, and you would
see code like:

```python
sim_utils.SimulationCfg(device="cpu", use_gpu_pipeline=False, dt=0.01, physx=sim_utils.PhysxCfg(use_gpu=False))
```

With this MR, we simply set the desired device, and all the parameters,
such as `use_gpu_pipeline` and `use_gpu` propagate automatically,
resulting in the following:

 ```python
sim_utils.SimulationCfg(device="cpu", dt=0.01,
physx=sim_utils.PhysxCfg())
```

The command line input `--cpu` has been removed in favor of `--device device_name`, where valid options for `device_name` are `cpu` (run on CPU), `cuda` (run on GPU with device id 0), or `cuda:N` (run on GPU with device id N, for example `cuda:0`).

## Type of change

- Breaking Change

## Checklist

- [x] I have run the [`pre-commit` checks](https://pre-commit.com/) with `./isaaclab.sh --format`
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [x] I have updated the changelog and the corresponding version in the extension's `config/extension.toml` file
- [x] I have added my name to the `CONTRIBUTORS.md` or my name already exists there

docs/source/how-to/record_animation.rst

@@ -47,7 +47,7 @@ Here we run the state-machine example and record the animation of the simulation
 
 .. code-block:: bash
 
-  ./isaaclab.sh -p source/standalone/environments/state_machine/lift_cube_sm.py --num_envs 8 --cpu --disable_fabric
+  ./isaaclab.sh -p source/standalone/environments/state_machine/lift_cube_sm.py --num_envs 8 --device cpu --disable_fabric
 
 
 On running the script, the Isaac Lab UI window opens with the button "Record Animation" in the toolbar.

docs/source/migration/migrating_from_isaacgymenvs.rst

@@ -83,15 +83,16 @@ setting the GPU buffer dimensions.
 |                                                              |                                                                   |
 |  # IsaacGymEnvs                                              | # IsaacLab                                                        |
 |  sim:                                                        | sim: SimulationCfg = SimulationCfg(                               |
+|                                                              |    device = "cuda:0" # can be "cpu", "cuda", "cuda:<device_id>"   |
 |    dt: 0.0166 # 1/60 s                                       |    dt=1 / 120,                                                    |
 |    substeps: 2                                               |    # decimation will be set in the task config                    |
 |    up_axis: "z"                                              |    # up axis will always be Z in isaac sim                        |
-|    use_gpu_pipeline: ${eq:${...pipeline},"gpu"}              |    use_gpu_pipeline=True,                                         |
+|    use_gpu_pipeline: ${eq:${...pipeline},"gpu"}              |    # use_gpu_pipeline is deduced from the device                  |
 |    gravity: [0.0, 0.0, -9.81]                                |    gravity=(0.0, 0.0, -9.81),                                     |
 |    physx:                                                    |    physx: PhysxCfg = PhysxCfg(                                    |
 |      num_threads: ${....num_threads}                         |        # num_threads is no longer needed                          |
 |      solver_type: ${....solver_type}                         |        solver_type=1,                                             |
-|      use_gpu: ${contains:"cuda",${....sim_device}}           |        use_gpu=True,                                              |
+|      use_gpu: ${contains:"cuda",${....sim_device}}           |        # use_gpu is deduced from the device                       |
 |      num_position_iterations: 4                              |        max_position_iteration_count=4,                            |
 |      num_velocity_iterations: 0                              |        max_velocity_iteration_count=0,                            |
 |      contact_offset: 0.02                                    |        # moved to actor config                                    |

docs/source/migration/migrating_from_omniisaacgymenvs.rst

@@ -76,8 +76,9 @@ for setting the GPU buffer dimensions.
 |                                                              |                                                                   |
 |  # OmniIsaacGymEnvs                                          | # IsaacLab                                                        |
 |  sim:                                                        | sim: SimulationCfg = SimulationCfg(                               |
+|                                                              |    device = "cuda:0" # can be "cpu", "cuda", "cuda:<device_id>"   |
 |    dt: 0.0083 # 1/120 s                                      |    dt=1 / 120,                                                    |
-|    use_gpu_pipeline: ${eq:${...pipeline},"gpu"}              |    use_gpu_pipeline=True,                                         |
+|    use_gpu_pipeline: ${eq:${...pipeline},"gpu"}              |    # use_gpu_pipeline is deduced from the device                  |
 |    use_fabric: True                                          |    use_fabric=True,                                               |
 |    enable_scene_query_support: False                         |    enable_scene_query_support=False,                              |
 |    disable_contact_processing: False                         |    disable_contact_processing=False,                              |
@@ -91,7 +92,7 @@ for setting the GPU buffer dimensions.
 |    physx:                                                    |    physx: PhysxCfg = PhysxCfg(                                    |
 |      worker_thread_count: ${....num_threads}                 |        # worker_thread_count is no longer needed                  |
 |      solver_type: ${....solver_type}                         |        solver_type=1,                                             |
-|      use_gpu: ${contains:"cuda",${....sim_device}}           |        use_gpu=True,                                              |
+|      use_gpu: ${contains:"cuda",${....sim_device}}           |        # use_gpu is deduced from the device                       |
 |      solver_position_iteration_count: 4                      |        max_position_iteration_count=4,                            |
 |      solver_velocity_iteration_count: 0                      |        max_velocity_iteration_count=0,                            |
 |      contact_offset: 0.02                                    |        # moved to actor config                                    |

docs/source/migration/migrating_from_orbit.rst

@@ -90,6 +90,17 @@ should now be:
 Other Breaking changes
 ~~~~~~~~~~~~~~~~~~~~~~
 
+Setting the device
+------------------
+
+The argument ``--cpu`` has been removed in favor of ``--device device_name``. Valid options for ``device_name`` are:
+
+- ``cpu``: Use CPU.
+- ``cuda``: Use GPU with device ID ``0``.
+- ``cuda:N``: Use GPU, where N is the device ID. For example, ``cuda:0``.
+The default value is ``cuda:0``.
+
+
 Offscreen rendering
 -------------------
 

docs/source/setup/sample.rst

@@ -182,8 +182,8 @@ from the environments into the respective libraries function argument and return
       # install python module (for stable-baselines3)
       ./isaaclab.sh -i sb3
       # run script for training
-      # note: we enable cpu flag since SB3 doesn't optimize for GPU anyway
-      ./isaaclab.sh -p source/standalone/workflows/sb3/train.py --task Isaac-Cartpole-v0 --headless --cpu
+      # note: we set the device to cpu since SB3 doesn't optimize for GPU anyway
+      ./isaaclab.sh -p source/standalone/workflows/sb3/train.py --task Isaac-Cartpole-v0 --headless --device cpu
       # run script for playing with 32 environments
       ./isaaclab.sh -p source/standalone/workflows/sb3/play.py --task Isaac-Cartpole-v0 --num_envs 32 --checkpoint /PATH/TO/model.zip
       # run script for recording video of a trained agent (requires installing `ffmpeg`)

docs/source/tutorials/03_envs/register_rl_env_gym.rst

@@ -152,11 +152,11 @@ Now that we have gone through the code, let's run the script and see the result:
 This should open a stage with everything similar to the :ref:`tutorial-create-manager-rl-env` tutorial.
 To stop the simulation, you can either close the window, or press ``Ctrl+C`` in the terminal.
 
-In addition, you can also change the simulation device from GPU to CPU by adding the ``--cpu`` flag:
+In addition, you can also change the simulation device from GPU to CPU by setting the value of the ``--device`` flag explicitly:
 
 .. code-block:: bash
 
-   ./isaaclab.sh -p source/standalone/environments/random_agent.py --task Isaac-Cartpole-v0 --num_envs 32 --cpu
+   ./isaaclab.sh -p source/standalone/environments/random_agent.py --task Isaac-Cartpole-v0 --num_envs 32 --device cpu
 
-With the ``--cpu`` flag, the simulation will run on the CPU. This is useful for debugging the simulation.
+With the ``--device cpu`` flag, the simulation will run on the CPU. This is useful for debugging the simulation.
 However, the simulation will run much slower than on the GPU.

source/extensions/omni.isaac.lab/config/extension.toml

@@ -1,7 +1,7 @@
 [package]
 
 # Note: Semantic Versioning is used: https://semver.org/
-version = "0.20.8"
+version = "0.21.0"
 
 # Description
 title = "Isaac Lab framework for Robot Learning"

source/extensions/omni.isaac.lab/docs/CHANGELOG.rst

@@ -1,6 +1,34 @@
 Changelog
 ---------
 
+0.21.0 (2024-08-05)
+~~~~~~~~~~~~~~~~~~~
+
+Added
+^^^^^
+
+* Added the command line argument ``--device`` in :class:`~omni.isaac.lab.app.AppLauncher`. Valid options are:
+
+  * ``cpu``: Use CPU.
+  * ``cuda``: Use GPU with device ID ``0``.
+  * ``cuda:N``: Use GPU, where N is the device ID. For example, ``cuda:0``.
+  The default value is ``cuda:0``.
+
+Changed
+^^^^^^^
+
+* Simplified setting the device throughout the code by relying on :attr:`omni.isaac.lab.sim.SimulationCfg.device`
+  to activate gpu/cpu pipelines.
+
+Removed
+^^^^^^^
+
+* Removed the parameter :attr:`omni.isaac.lab.sim.SimulationCfg.use_gpu_pipeline`. This is now directly inferred from
+  :attr:`omni.isaac.lab.sim.SimulationCfg.device`.
+* Removed the command line input argument ``--device_id`` in :class:`~omni.isaac.lab.app.AppLauncher`. The device id can
+  now be set using the ``--device`` argument, for example with ``--device cuda:0``.
+
+
 0.20.8 (2024-08-02)
 ~~~~~~~~~~~~~~~~~~~
 

source/extensions/omni.isaac.lab/omni/isaac/lab/app/app_launcher.py

@@ -155,14 +155,26 @@ def add_app_launcher_args(parser: argparse.ArgumentParser) -> None:
         * ``headless`` (bool): If True, the app will be launched in headless (no-gui) mode. The values map the same
           as that for the ``HEADLESS`` environment variable. If False, then headless mode is determined by the
           ``HEADLESS`` environment variable.
-        * ``livestream`` (int): If one of {0, 1, 2}, then livestreaming and headless mode is enabled. The values
+        * ``livestream`` (int): If one of {1, 2}, then livestreaming and headless mode is enabled. The values
           map the same as that for the ``LIVESTREAM`` environment variable. If :obj:`-1`, then livestreaming is
           determined by the ``LIVESTREAM`` environment variable.
+          Valid options are:
+
+          - ``0``: Disabled
+          - ``1``: `Native <https://docs.omniverse.nvidia.com/extensions/latest/ext_livestream/native.html>`_
+          - ``2``: `WebRTC <https://docs.omniverse.nvidia.com/extensions/latest/ext_livestream/webrtc.html>`_
+
         * ``enable_cameras`` (bool): If True, the app will enable camera sensors and render them, even when in
           headless mode. This flag must be set to True if the environments contains any camera sensors.
           The values map the same as that for the ``ENABLE_CAMERAS`` environment variable.
           If False, then enable_cameras mode is determined by the ``ENABLE_CAMERAS`` environment variable.
-        * ``device_id`` (int): If specified, simulation will run on the specified GPU device.
+        * ``device`` (str): The device to run the simulation on.
+          Valid options are:
+
+          - ``cpu``: Use CPU.
+          - ``cuda``: Use GPU with device ID ``0``.
+          - ``cuda:N``: Use GPU, where N is the device ID. For example, "cuda:0".
+
         * ``experience`` (str): The experience file to load when launching the SimulationApp. If a relative path
           is provided, it is resolved relative to the ``apps`` folder in Isaac Sim and Isaac Lab (in that order).
 
@@ -232,11 +244,13 @@ def add_app_launcher_args(parser: argparse.ArgumentParser) -> None:
             help="Enable camera sensors and relevant extension dependencies.",
         )
         arg_group.add_argument(
-            "--device_id",
-            type=int,
-            default=AppLauncher._APPLAUNCHER_CFG_INFO["device_id"][1],
-            help="GPU device ID used for running simulation.",
+            "--device",
+            type=str,
+            default=AppLauncher._APPLAUNCHER_CFG_INFO["device"][1],
+            help='The device to run the simulation on. Can be "cpu", "cuda", "cuda:N", where N is the device ID',
         )
+        # Add the deprecated cpu flag to raise an error if it is used
+        arg_group.add_argument("--cpu", action="store_true", help=argparse.SUPPRESS)
         arg_group.add_argument(
             "--verbose",  # Note: This is read by SimulationApp through sys.argv
             action="store_true",
@@ -267,7 +281,7 @@ def add_app_launcher_args(parser: argparse.ArgumentParser) -> None:
         "headless": ([bool], False),
         "livestream": ([int], -1),
         "enable_cameras": ([bool], False),
-        "device_id": ([int], 0),
+        "device": ([str], "cuda:0"),
         "experience": ([str], ""),
     }
     """A dictionary of arguments added manually by the :meth:`AppLauncher.add_app_launcher_args` method.
@@ -454,7 +468,20 @@ def _config_resolution(self, launcher_args: dict):
             launcher_args["hide_ui"] = True
 
         # --simulation GPU device logic --
-        self.device_id = launcher_args.pop("device_id", AppLauncher._APPLAUNCHER_CFG_INFO["device_id"][1])
+        self.device_id = 0
+        device = launcher_args.get("device", AppLauncher._APPLAUNCHER_CFG_INFO["device"][1])
+        if "cuda" not in device and "cpu" not in device:
+            raise ValueError(
+                f"Invalid value for input keyword argument `device`: {device}."
+                " Expected: a string with the format 'cuda', 'cuda:<device_id>', or 'cpu'."
+            )
+        if "cuda:" in device:
+            self.device_id = int(device.split(":")[-1])
+
+        # Raise an error for the deprecated cpu flag
+        if launcher_args.get("cpu", False):
+            raise ValueError("The `--cpu` flag is deprecated. Please use `--device cpu` instead.")
+
         if "distributed" in launcher_args:
             distributed_train = launcher_args["distributed"]
             # local rank (GPU id) in a current multi-gpu mode

source/extensions/omni.isaac.lab/omni/isaac/lab/envs/direct_rl_env.py

@@ -96,8 +96,7 @@ def __init__(self, cfg: DirectRLEnvCfg, render_mode: str | None = None, **kwargs
         print(f"\tPhysics step-size     : {self.physics_dt}")
         print(f"\tRendering step-size   : {self.physics_dt * self.cfg.sim.render_interval}")
         print(f"\tEnvironment step-size : {self.step_dt}")
-        print(f"\tPhysics GPU pipeline  : {self.cfg.sim.use_gpu_pipeline}")
-        print(f"\tPhysics GPU simulation: {self.cfg.sim.physx.use_gpu}")
+        print(f"\tEnvironment device: {self.device}")
 
         if self.cfg.sim.render_interval < self.cfg.decimation:
             msg = (
@@ -285,6 +284,7 @@ def step(self, action: torch.Tensor) -> VecEnvStepReturn:
         Returns:
             A tuple containing the observations, rewards, resets (terminated and truncated) and extras.
         """
+        action = action.to(self.device)
         # add action noise
         if self.cfg.action_noise_model:
             action = self._action_noise_model.apply(action)

source/extensions/omni.isaac.lab/omni/isaac/lab/envs/manager_based_env.py

@@ -92,8 +92,6 @@ def __init__(self, cfg: ManagerBasedEnvCfg):
         print(f"\tPhysics step-size     : {self.physics_dt}")
         print(f"\tRendering step-size   : {self.physics_dt * self.cfg.sim.render_interval}")
         print(f"\tEnvironment step-size : {self.step_dt}")
-        print(f"\tPhysics GPU pipeline  : {self.cfg.sim.use_gpu_pipeline}")
-        print(f"\tPhysics GPU simulation: {self.cfg.sim.physx.use_gpu}")
 
         if self.cfg.sim.render_interval < self.cfg.decimation:
             msg = (
@@ -259,7 +257,7 @@ def step(self, action: torch.Tensor) -> tuple[VecEnvObs, dict]:
             A tuple containing the observations and extras.
         """
         # process actions
-        self.action_manager.process_action(action)
+        self.action_manager.process_action(action.to(self.device))
 
         # check if we need to do rendering within the physics loop
         # note: checked here once to avoid multiple checks within the loop

source/extensions/omni.isaac.lab/omni/isaac/lab/envs/manager_based_rl_env.py

@@ -153,7 +153,7 @@ def step(self, action: torch.Tensor) -> VecEnvStepReturn:
             A tuple containing the observations, rewards, resets (terminated and truncated) and extras.
         """
         # process actions
-        self.action_manager.process_action(action)
+        self.action_manager.process_action(action.to(self.device))
 
         # check if we need to do rendering within the physics loop
         # note: checked here once to avoid multiple checks within the loop

source/extensions/omni.isaac.lab/omni/isaac/lab/sim/simulation_cfg.py

@@ -24,22 +24,16 @@ class PhysxCfg:
     documentation`_.
 
     PhysX 5 supports GPU-accelerated physics simulation. This is enabled by default, but can be disabled
-    through the flag `use_gpu`. Unlike CPU PhysX, the GPU simulation feature is not able to dynamically
-    grow all the buffers. Therefore, it is necessary to provide a reasonable estimate of the buffer sizes
-    for GPU features. If insufficient buffer sizes are provided, the simulation will fail with errors and
-    lead to adverse behaviors. The buffer sizes can be adjusted through the `gpu_*` parameters.
+    by setting the :attr:`~SimulationCfg.device` to ``cpu`` in :class:`SimulationCfg`. Unlike CPU PhysX, the GPU
+    simulation feature is unable to dynamically grow all the buffers. Therefore, it is necessary to provide
+    a reasonable estimate of the buffer sizes for GPU features. If insufficient buffer sizes are provided, the
+    simulation will fail with errors and lead to adverse behaviors. The buffer sizes can be adjusted through the
+    ``gpu_*`` parameters.
 
     .. _PhysX 5 SDK documentation: https://nvidia-omniverse.github.io/PhysX/physx/5.3.1/_api_build/class_px_scene_desc.html
 
     """
 
-    use_gpu: bool = True
-    """Enable/disable GPU accelerated dynamics simulation. Default is True.
-
-    This enables GPU-accelerated implementations for broad-phase collision checks, contact generation,
-    shape and body management, and constrained solver.
-    """
-
     solver_type: Literal[0, 1] = 1
     """The type of solver to use.Default is 1 (TGS).
 
@@ -165,6 +159,16 @@ class SimulationCfg:
     physics_prim_path: str = "/physicsScene"
     """The prim path where the USD PhysicsScene is created. Default is "/physicsScene"."""
 
+    device: str = "cuda:0"
+    """The device to run the simulation on. Default is ``"cuda:0"``.
+
+    Valid options are:
+
+    - ``"cpu"``: Use CPU.
+    - ``"cuda"``: Use GPU, where the device ID is inferred from :class:`~omni.isaac.lab.app.AppLauncher`'s config.
+    - ``"cuda:N"``: Use GPU, where N is the device ID. For example, "cuda:0".
+    """
+
     dt: float = 1.0 / 60.0
     """The physics simulation time-step (in seconds). Default is 0.0167 seconds."""
 
@@ -219,15 +223,6 @@ class SimulationCfg:
         It is required to set this flag to :obj:`True` when using the TensorAPIs for contact reporting.
     """
 
-    use_gpu_pipeline: bool = True
-    """Enable/disable GPU pipeline. Default is True.
-
-    If set to False, the physics data will be read as CPU buffers.
-    """
-
-    device: str = "cuda:0"
-    """The device for running the simulation/environment. Default is ``"cuda:0"``."""
-
     physx: PhysxCfg = PhysxCfg()
     """PhysX solver settings. Default is PhysxCfg()."""
 

source/extensions/omni.isaac.lab_tasks/config/extension.toml

@@ -1,7 +1,7 @@
 [package]
 
 # Note: Semantic Versioning is used: https://semver.org/
-version = "0.8.2"
+version = "0.9.0"
 
 # Description
 title = "Isaac Lab Environments"

source/extensions/omni.isaac.lab_tasks/docs/CHANGELOG.rst

@@ -1,6 +1,17 @@
 Changelog
 ---------
 
+0.9.0 (2024-08-05)
+~~~~~~~~~~~~~~~~~~~
+
+Changed
+^^^^^^^
+
+* Replaced the command line input ``--cpu`` with ``--device`` in the train and play scripts. Running on cpu is
+  supported by passing ``--device cpu``. Running on a specific gpu is now supported by passing ``--device cuda:<device_id>``,
+  where ``<device_id>`` is the id of the GPU to use, for example ``--device cuda:0``.
+
+
 0.8.2 (2024-08-02)
 ~~~~~~~~~~~~~~~~~~~