Adds docs for fabric cloning & stage in memory (#475)

# Description

<!--
Add a how-to guide for setting-up and explaining fabric cloning and
stage in memory.
-->

Please include a summary of the change and which issue is fixed. Please
also include relevant motivation and context.
List any dependencies that are required for this change.

Fixes # (issue)

<!-- As a practice, it is recommended to open an issue to have
discussions on the proposed pull request.
This makes it easier for the community to keep track of what is being
developed or added, and if a given feature
is demanded by more than one party. -->

## Type of change

<!-- As you go through the list, delete the ones that are not
applicable. -->

- Bug fix (non-breaking change which fixes an issue)
- New feature (non-breaking change which adds functionality)
- Breaking change (fix or feature that would cause existing
functionality to not work as expected)
- This change requires a documentation update

## Screenshots

Please attach before and after screenshots of the change if applicable.

<!--
Example:

| Before | After |
| ------ | ----- |
| _gif/png before_ | _gif/png after_ |

To upload images to a PR -- simply drag and drop an image while in edit
mode and it should upload the image directly. You can then paste that
source into the above before/after sections.
-->

## Checklist

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

<!--
As you go through the checklist above, you can mark something as done by
putting an x character in it

For example,
- [x] I have done this task
- [ ] I have not done this task
-->

---------
Signed-off-by: rwiltz <165190220+rwiltz@users.noreply.github.com>
Signed-off-by: Kelly Guo <kellyguo123@hotmail.com>
Signed-off-by: Ashwin Varghese Kuruttukulam <123109010+ashwinvkNV@users.noreply.github.com>
Signed-off-by: Kelly Guo <kellyg@nvidia.com>
Signed-off-by: Michael Gussert <michael@gussert.com>
Signed-off-by: samibouziri <79418773+samibouziri@users.noreply.github.com>
Signed-off-by: Mayank Mittal <12863862+Mayankm96@users.noreply.github.com>
Signed-off-by: Kyle Morgenstein <34984693+KyleM73@users.noreply.github.com>
Signed-off-by: Hongyu Li <lihongyu0807@icloud.com>
Signed-off-by: Toni-SM <toni.semu@gmail.com>
Signed-off-by: James Tigue <166445701+jtigue-bdai@users.noreply.github.com>
Signed-off-by: Pascal Roth <57946385+pascal-roth@users.noreply.github.com>
Signed-off-by: Victor Khaustov <3192677+vi3itor@users.noreply.github.com>
Signed-off-by: AlvinC <alvincny529@gmail.com>
Signed-off-by: Tyler Lum <tylergwlum@gmail.com>
Signed-off-by: Miguel Alonso Jr. <76960110+miguelalonsojr@users.noreply.github.com>
Signed-off-by: renaudponcelet <renaud.poncelet@gmail.com>
Signed-off-by: matthewtrepte <mtrepte@nvidia.com>
Co-authored-by: lotusl-code <lotusl@nvidia.com>
Co-authored-by: Kelly Guo <kellyg@nvidia.com>
Co-authored-by: jaczhangnv <jaczhang@nvidia.com>
Co-authored-by: rwiltz <165190220+rwiltz@users.noreply.github.com>
Co-authored-by: Yanzi Zhu <yanziz@nvidia.com>
Co-authored-by: nv-mhaselton <mhaselton@nvidia.com>
Co-authored-by: cosmith-nvidia <141183495+cosmith-nvidia@users.noreply.github.com>
Co-authored-by: Michael Gussert <michael@gussert.com>
Co-authored-by: CY Chen <cyc@nvidia.com>
Co-authored-by: oahmednv <oahmed@Nvidia.com>
Co-authored-by: Ashwin Varghese Kuruttukulam <123109010+ashwinvkNV@users.noreply.github.com>
Co-authored-by: Rafael Wiltz <rwiltz@nvidia.com>
Co-authored-by: Peter Du <peterd@nvidia.com>
Co-authored-by: chengronglai <chengrongl@nvidia.com>
Co-authored-by: pulkitg01 <pulkitg@nvidia.com>
Co-authored-by: Connor Smith <cosmith@nvidia.com>
Co-authored-by: Ashwin Varghese Kuruttukulam <ashwinvk@nvidia.com>
Co-authored-by: Kelly Guo <kellyguo123@hotmail.com>
Co-authored-by: shauryadNv <shauryad@nvidia.com>
Co-authored-by: Mayank Mittal <12863862+Mayankm96@users.noreply.github.com>
Co-authored-by: samibouziri <79418773+samibouziri@users.noreply.github.com>
Co-authored-by: James Smith <142246516+jsmith-bdai@users.noreply.github.com>
Co-authored-by: Shundo Kishi <syundo0730@gmail.com>
Co-authored-by: Sheikh Dawood <sabdulajees@nvidia.com>
Co-authored-by: Toni-SM <aserranomuno@nvidia.com>
Co-authored-by: Gonglitian <70052908+Gonglitian@users.noreply.github.com>
Co-authored-by: James Tigue <166445701+jtigue-bdai@users.noreply.github.com>
Co-authored-by: Mayank Mittal <mittalma@leggedrobotics.com>
Co-authored-by: Kyle Morgenstein <34984693+KyleM73@users.noreply.github.com>
Co-authored-by: Johnson Sun <20457146+j3soon@users.noreply.github.com>
Co-authored-by: Pascal Roth <57946385+pascal-roth@users.noreply.github.com>
Co-authored-by: Hongyu Li <lihongyu0807@icloud.com>
Co-authored-by: Jean-Francois-Lafleche <57650687+Jean-Francois-Lafleche@users.noreply.github.com>
Co-authored-by: Wei Jinqi <changshanshi@outlook.com>
Co-authored-by: Louis LE LAY <le.lay.louis@gmail.com>
Co-authored-by: Harsh Patel <hapatel@theaiinstitute.com>
Co-authored-by: Kousheek Chakraborty <kousheekc@gmail.com>
Co-authored-by: Victor Khaustov <3192677+vi3itor@users.noreply.github.com>
Co-authored-by: AlvinC <alvincny529@gmail.com>
Co-authored-by: Felipe Mohr <50018670+felipemohr@users.noreply.github.com>
Co-authored-by: AdAstra7 <87345760+likecanyon@users.noreply.github.com>
Co-authored-by: gao <ziqi.gao@iff-extern.fraunhofer.de>
Co-authored-by: Tyler Lum <tylergwlum@gmail.com>
Co-authored-by: -T.K.- <t_k_233@outlook.com>
Co-authored-by: Clemens Schwarke <96480707+ClemensSchwarke@users.noreply.github.com>
Co-authored-by: Miguel Alonso Jr. <76960110+miguelalonsojr@users.noreply.github.com>
Co-authored-by: Miguel Alonso Jr. <miguel.alonso@nfinite.app>
Co-authored-by: renaudponcelet <renaud.poncelet@gmail.com>
Co-authored-by: Ales Borovicka <aborovicka@nvidia.com>
Co-authored-by: nv-mm <mmagdics@nvidia.com>
Co-authored-by: Antoine RICHARD <antoiner@nvidia.com>

docs/source/how-to/index.rst

@@ -160,3 +160,14 @@ Omniverse Physics.
     :maxdepth: 1
 
     simulation_performance
+
+
+Optimize Stage Creation
+-----------------------
+
+This guide explains 2 features that can speed up stage initialization, **fabric cloning** and **stage in memory**.
+
+.. toctree::
+    :maxdepth: 1
+
+    optimize_stage_creation

docs/source/how-to/optimize_stage_creation.rst

+Optimize Stage Creation
+=======================
+
+Isaac Lab supports two experimental features to speed-up stage creation: **fabric cloning** and **stage in memory**.
+These features are particularly effective for large-scale RL setups with thousands of environments.
+
+What These Features Do
+-----------------------
+
+**Fabric Cloning**
+
+- Clones environments using Fabric library (see `USD Fabric USDRT Documentation <https://docs.omniverse.nvidia.com/kit/docs/usdrt/latest/docs/usd_fabric_usdrt.html>`_)
+- Partially supported and enabled by default on some environments (see `Limitations`_ section for a list)
+
+**Stage in Memory**
+
+- Constructs the stage in memory, rather than with a USD file, avoiding overhead from disk I/O
+- After stage creation, if rendering is required, the stage is attached to the USD context, returning to the default stage configuration
+- Not enabled by default
+
+Usage Examples
+--------------
+
+Fabric cloning can be toggled by setting the ``clone_in_fabric`` flag in the ``InteractiveSceneCfg`` configuration.
+
+**Using Fabric Cloning with a RL environment**
+
+.. code-block:: python
+
+    # create environment configuration
+    env_cfg = CartpoleEnvCfg()
+    env_cfg.scene.clone_in_fabric = True
+    # setup RL environment
+    env = ManagerBasedRLEnv(cfg=env_cfg)
+
+
+Stage in memory can be toggled by setting the ``create_stage_in_memory`` in the ``SimulationCfg`` configuration.
+
+**Using Stage in Memory with a RL environment**
+
+.. code-block:: python
+
+    # create config and set flag
+    cfg = CartpoleEnvCfg()
+    cfg.scene.num_envs = 1024
+    cfg.sim.create_stage_in_memory = True
+    # create env with stage in memory
+    env = ManagerBasedRLEnv(cfg=cfg)
+
+Note, if stage in memory is enabled without using an existing RL environment class, a few more steps are need.
+The stage creation steps should be wrapped in a ``with`` statement to set the stage context.
+If the stage needs to be attached, the ``attach_stage_to_usd_context`` function should be called after the stage is created.
+
+**Using Stage in Memory with a manual scene setup**
+
+.. code-block:: python
+
+    # init simulation context with stage in memory
+    sim = SimulationContext(cfg=SimulationCfg(create_stage_in_memory=True))
+
+    # grab stage in memory and set stage context
+    stage_in_memory = sim.get_initial_stage()
+    with stage_utils.use_stage(stage_in_memory):
+        # create cartpole scene
+        scene_cfg = CartpoleSceneCfg(num_envs=1024)
+        scene = InteractiveScene(scene_cfg)
+        # attach stage to memory after stage is created
+        sim_utils.attach_stage_to_usd_context()
+
+    sim.play()
+
+
+Limitations
+-----------
+
+**Fabric Cloning**
+
+- Fabric-cloned environments must be accessed using USDRT functions, rather than USD functions.
+- Fabric cloning is partially supported and enabled by default on some environments, listed here.
+
+.. code-block:: none
+
+    1.  Isaac-Ant-Direct-v0
+    2.  Isaac-Ant-v0
+    3.  Isaac-Cartpole-Direct-v0
+    4.  Isaac-Cartpole-Showcase-Box-Box-Direct-v0
+    5.  Isaac-Cartpole-Showcase-Box-Discrete-Direct-v0
+    6.  Isaac-Cartpole-Showcase-Box-MultiDiscrete-Direct-v0
+    7.  Isaac-Cartpole-Showcase-Dict-Box-Direct-v0
+    8.  Isaac-Cartpole-Showcase-Dict-Discrete-Direct-v0
+    9.  Isaac-Cartpole-Showcase-Dict-MultiDiscrete-Direct-v0
+    10. Isaac-Cartpole-Showcase-Discrete-Box-Direct-v0
+    11. Isaac-Cartpole-Showcase-Discrete-Discrete-Direct-v0
+    12. Isaac-Cartpole-Showcase-Discrete-MultiDiscrete-Direct-v0
+    13. Isaac-Cartpole-Showcase-MultiDiscrete-Box-Direct-v0
+    14. Isaac-Cartpole-Showcase-MultiDiscrete-Discrete-Direct-v0
+    15. Isaac-Cartpole-Showcase-MultiDiscrete-MultiDiscrete-Direct-v0
+    16. Isaac-Cartpole-Showcase-Tuple-Box-Direct-v0
+    17. Isaac-Cartpole-Showcase-Tuple-Discrete-Direct-v0
+    18. Isaac-Cartpole-Showcase-Tuple-MultiDiscrete-Direct-v0
+    19. Isaac-Cartpole-v0
+    20. Isaac-Factory-GearMesh-Direct-v0
+    21. Isaac-Factory-NutThread-Direct-v0
+    22. Isaac-Factory-PegInsert-Direct-v0
+    23. Isaac-Franka-Cabinet-Direct-v0
+    24. Isaac-Humanoid-Direct-v0
+    25. Isaac-Humanoid-v0
+    26. Isaac-Quadcopter-Direct-v0
+    27. Isaac-Repose-Cube-Allegro-Direct-v0
+    28. Isaac-Repose-Cube-Allegro-NoVelObs-v0
+    29. Isaac-Repose-Cube-Allegro-v0
+    30. Isaac-Repose-Cube-Shadow-Direct-v0
+    31. Isaac-Repose-Cube-Shadow-OpenAI-FF-Direct-v0
+    32. Isaac-Repose-Cube-Shadow-OpenAI-LSTM-Direct-v0
+
+**Stage in Memory**
+
+- Cannot be currently enabled at the same time as **Fabric Cloning**.
+
+- Attaching stage in memory to the USD context can be slow, offsetting some or all of the performance benefits.
+
+  - Note, attaching is only necessary when rendering is enabled. For example, in headless mode, attachment is not required.
+
+- Certain low-level Kit APIs do not yet support stage in memory.
+
+  - In most cases, when these APIs are hit, existing scripts will automatically early attach the stage and print a warning message.
+  - In one particular case, for some environments, the API call to color the ground plane is skipped, when stage in memory is enabled.
+
+
+Benchmark Results
+-----------------
+
+Performance comparison cloning 4000 ShadowHand robots with rendering enabled
+
++--------+-----------------+-------------------+------------------------+---------------------------+------------------------+------------------------+
+| Test # | Stage in Memory | Clone in Fabric   | Attach Stage Time (s)  | Fabric Attach Time (s)    | Clone Paths Time (s)   | First Step Time (s)    |
++========+=================+===================+========================+===========================+========================+========================+
+| 1      | Yes             | Yes               | 3.88                   | 0.15                      | 4.84                   | 1.39                   |
++--------+-----------------+-------------------+------------------------+---------------------------+------------------------+------------------------+
+| 2      | No              | No                | —                      | 60.17                     | 4.46                   | 3.52                   |
++--------+-----------------+-------------------+------------------------+---------------------------+------------------------+------------------------+
+| 3      | No              | Yes               | —                      | 0.47                      | 4.72                   | 2.56                   |
++--------+-----------------+-------------------+------------------------+---------------------------+------------------------+------------------------+
+| 4      | Yes             | No                | 42.64                  | 21.75                     | 1.87                   | 2.16                   |
++--------+-----------------+-------------------+------------------------+---------------------------+------------------------+------------------------+