Adds release notes and asset caching to docs (#261)

# Description

This is a documentation only change that includes:

* Add new release notes page to track release notes for all previous
releases
* Add simulation stability section to troubleshooting page with OVD
instructions and link to omni physics guide
* Add documentation around asset caching using Hub
* Fixes typing issue for documentation building

.pre-commit-config.yaml

@@ -38,7 +38,7 @@ repos:
       - id: pyupgrade
         args: ["--py310-plus"]
         # FIXME: This is a hack because Pytorch does not like: torch.Tensor | dict aliasing
-        exclude: "source/isaaclab/isaaclab/envs/common.py|source/isaaclab/isaaclab/ui/widgets/image_plot.py"
+        exclude: "source/isaaclab/isaaclab/envs/common.py|source/isaaclab/isaaclab/ui/widgets/image_plot.py|source/isaaclab_tasks/isaaclab_tasks/direct/humanoid_amp/motions/motion_loader.py"
   - repo: https://github.com/codespell-project/codespell
     rev: v2.2.6
     hooks:

docs/index.rst

@@ -137,8 +137,9 @@ Table of Contents
    source/refs/additional_resources
    source/refs/contributing
    source/refs/troubleshooting
-   source/refs/migration.rst
+   source/refs/migration
    source/refs/issues
+   source/refs/release_notes
    source/refs/changelog
    source/refs/license
    source/refs/bibliography

docs/source/refs/migration.rst

+.. _migration_guide:
+
 Migration Guide (Isaac Sim)
 ===========================
 
@@ -73,7 +75,7 @@ Articulation, RigidPrim, XFormPrim, and others. Single-object classes are now pr
 ``Single``, such as ``SingleArticulation``, while tensorized View classes now have the ``View``
 suffix removed.
 
-The exact renamings of the classes are as follow:
+The exact renaming of the classes are as follow:
 
 * ``Articulation`` --> ``SingleArticulation``
 * ``ArticulationView`` --> ``Articulation``

docs/source/refs/troubleshooting.rst

@@ -9,6 +9,28 @@ Tricks and Troubleshooting
     assistance.
 
 
+Debugging physics simulation stability issues
+---------------------------------------------
+
+When importing new robots into Isaac Lab or setting up a new environment, simulation instability
+can often appear if the assets have not been tuned with reasonable simulation parameters.
+In reinforcement learning scenarios, this will often result in NaNs propagating into the learning pipeline
+due to invalid states in the simulation.
+
+If this happens, we recommend consulting the
+`Articulation and Robot Simulation Stability Guide <https://docs.omniverse.nvidia.com/kit/docs/omni_physics/latest/dev_guide/guides/articulation_stability_guide.html>`_
+which recommends various simulation parameters and best practices to achieve better stability in robot simulations.
+
+Additionally, `Omniverse PhysX Visual Debugger <https://docs.omniverse.nvidia.com/kit/docs/omni_physics/latest/extensions/ux/source/omni.physx.pvd/docs/dev_guide/physx_visual_debugger.html>`_
+allows for recording of data of PhysX simulations, which can often help simulation issues and aid the debugging process.
+
+To enable OmniPVD capture in Isaac Lab, add the relevant kit arguments to the command line prompt when launching an Isaac Lab process
+
+.. code:: bash
+
+    ./isaaclab.sh -p scripts/demos/bipeds.py --kit_args "--/persistent/physics/omniPvdOvdRecordingDirectory=/tmp/ --/physics/omniPvdOutputEnabled=true" --headless
+
+
 Checking the internal logs from the simulator
 ---------------------------------------------
 

docs/source/setup/installation/asset_caching.rst

+Asset Caching
+=============
+
+Assets used in Isaac Lab are hosted on AWS S3 buckets on the cloud.
+Asset loading time can depend on your network connection and geographical location.
+In some cases, it is possible that asset loading times can be long when assets are pulled from the AWS servers.
+
+If you run into cases where assets take a few minutes to load for each run,
+we recommend enabling asset caching following the below steps.
+
+First, launch the Isaac Sim app:
+
+.. tab-set::
+   :sync-group: os
+
+   .. tab-item:: :icon:`fa-brands fa-linux` Linux
+      :sync: linux
+
+      .. code:: bash
+
+         ./isaaclab.sh -s
+
+   .. tab-item:: :icon:`fa-brands fa-windows` Windows
+      :sync: windows
+
+      .. code:: batch
+
+         isaaclab.bat -s
+
+On the top right of the Isaac Sim app, there will be an icon labelled ``CACHE:``.
+There may be a message indicating ``HUB NOT DETECTED`` or ``NEW VERSION DETECTED``.
+
+.. figure:: ../../_static/setup/asset_caching.jpg
+    :align: center
+    :figwidth: 100%
+    :alt: Simulator with cache messaging.
+
+Click on the message, which will download HUB for asset caching.
+Once installed, HUB will run automatically each time an Isaac Lab or Isaac Sim instance is run.
+
+Note that for the first run, assets will still need to be pulled from the cloud, which could lead to longer loading times.
+However, subsequent runs that use the same assets will be able to use the cached files from HUB.
+HUB will provide better control for caching of assets used in Isaac Lab.
+
+Nucleus
+-------
+
+Prior to Isaac Sim 4.5, assets were accessible from the Omniverse Nucleus server and through setting up a local Nucleus server.
+Although from Isaac Sim 4.5, we have deprecated the use of Omniverse Nucleus and the Omniverse Launcher, any existing instances
+or setups of local Nucleus instances should still work. We recommend keeping existing setups if a local Nucleus server
+was previously already set up.

docs/source/setup/installation/index.rst

@@ -59,3 +59,4 @@ For users getting started with Isaac Lab, we recommend installing Isaac Lab by c
     Pip installation (recommended for Ubuntu 22.04 and Windows) <pip_installation>
     Binary installation (recommended for Ubuntu 20.04) <binaries_installation>
     Advanced installation (Isaac Lab pip) <isaaclab_pip_installation>
+    Asset caching <asset_caching>

scripts/benchmarks/benchmark_rlgames.py

@@ -137,7 +137,7 @@ def main(env_cfg: ManagerBasedRLEnvCfg | DirectRLEnvCfg | DirectMARLEnvCfg, agen
     world_rank = 0
     if args_cli.distributed:
         env_cfg.sim.device = f"cuda:{app_launcher.local_rank}"
-        agent_cfg.device = f"cuda:{app_launcher.local_rank}"
+        agent_cfg["params"]["config"]["device"] = f"cuda:{app_launcher.local_rank}"
         world_rank = app_launcher.global_rank
 
     # specify directory for logging experiments

source/isaaclab_tasks/docs/CHANGELOG.rst

@@ -2,7 +2,7 @@ Changelog
 ---------
 
 0.10.22 (2025-01-14)
-~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~
 
 Added
 ^^^^^

source/isaaclab_tasks/isaaclab_tasks/direct/humanoid_amp/motions/motion_loader.py

@@ -6,6 +6,7 @@
 import numpy as np
 import os
 import torch
+from typing import Optional
 
 
 class MotionLoader:
@@ -70,10 +71,10 @@ class MotionLoader:
         self,
         a: torch.Tensor,
         *,
-        b: torch.Tensor | None = None,
-        blend: torch.Tensor | None = None,
-        start: np.ndarray | None = None,
-        end: np.ndarray | None = None,
+        b: Optional[torch.Tensor] = None,
+        blend: Optional[torch.Tensor] = None,
+        start: Optional[np.ndarray] = None,
+        end: Optional[np.ndarray] = None,
     ) -> torch.Tensor:
         """Linear interpolation between consecutive values.
 
@@ -101,10 +102,10 @@ class MotionLoader:
         self,
         q0: torch.Tensor,
         *,
-        q1: torch.Tensor | None = None,
-        blend: torch.Tensor | None = None,
-        start: np.ndarray | None = None,
-        end: np.ndarray | None = None,
+        q1: Optional[torch.Tensor] = None,
+        blend: Optional[torch.Tensor] = None,
+        start: Optional[np.ndarray] = None,
+        end: Optional[np.ndarray] = None,
     ) -> torch.Tensor:
         """Interpolation between consecutive rotations (Spherical Linear Interpolation).
 
@@ -195,7 +196,7 @@ class MotionLoader:
         return duration * np.random.uniform(low=0.0, high=1.0, size=num_samples)
 
     def sample(
-        self, num_samples: int, times: np.ndarray | None = None, duration: float | None = None
+        self, num_samples: int, times: Optional[np.ndarray] = None, duration: float | None = None
     ) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor]:
         """Sample motion data.