Unverified Commit aef99e45 authored by Mayank Mittal's avatar Mayank Mittal Committed by GitHub

Fixes sphinx tabs to make them work in dark theme (#584)

Earlier, we used the `sphinx-tabs` module, which didn't work well with
the `sphinx-book-theme` of our documentation. This MR removes this
dependency and uses `sphinx-design` instead for tabs. This natively
supports the dark theme.

## Type of change

- Bug fix (non-breaking change which fixes an issue)
- This change requires a documentation update

## Screenshots


https://github.com/isaac-sim/IsaacLab/assets/12863862/a56e1fa4-9b3c-4161-83bd-95b0e3b10334


## 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
- [ ] I have run all the tests with `./isaaclab.sh --test` and they pass
- [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
parent ff5c1a94
......@@ -29,7 +29,9 @@ project = "Isaac Lab"
copyright = "2022-2024, The Isaac Lab Project Developers."
author = "The Isaac Lab Project Developers."
version = "0.3.0"
# Read version from the package
with open(os.path.join(os.path.dirname(__file__), "..", "VERSION")) as f:
version = f.read().strip()
# -- General configuration ---------------------------------------------------
......@@ -51,7 +53,6 @@ extensions = [
"sphinxcontrib.bibtex",
"sphinx_copybutton",
"sphinx_design",
"sphinx_tabs.tabs",
]
# mathjax hacks
......
......@@ -116,6 +116,8 @@ Table of Contents
:caption: Project Links
GitHub <https://github.com/isaac-sim/IsaacLab>
NVIDIA Isaac Sim <https://docs.omniverse.nvidia.com/isaacsim/latest/index.html>
NVIDIA PhysX <https://nvidia-omniverse.github.io/PhysX/physx/5.4.0/index.html>
Indices and tables
==================
......@@ -124,4 +126,4 @@ Indices and tables
* :ref:`modindex`
* :ref:`search`
.. _NVIDIA Isaac Sim: https://docs.omniverse.nvidia.com/app_isaacsim/app_isaacsim/overview.html
.. _NVIDIA Isaac Sim: https://docs.omniverse.nvidia.com/isaacsim/latest/index.html
# for building the docs
sphinx-book-theme==1.0.1
sphinx-book-theme==1.1.3
myst-parser
sphinxcontrib-bibtex==2.5.0
sphinxcontrib-bibtex
autodocsumm
sphinx-copybutton
sphinx_design
sphinxemoji
sphinx-tabs
# basic python
numpy
......
......@@ -4,7 +4,7 @@ Multi-GPU and Multi-Node Training
.. currentmodule:: omni.isaac.lab
Isaac Lab supports multi-GPU and multi-node reinforcement learning. Currently, this feature is only
available for RL-Games library training workflows. We are working on extending this feature to
available for RL-Games and skrl libraries workflows. We are working on extending this feature to
other workflows.
.. attention::
......@@ -17,10 +17,10 @@ Multi-GPU Training
------------------
For complex reinforcement learning environments, it may be desirable to scale up training across multiple GPUs.
This is possible in Isaac Lab with the ``rl_games`` and ``skrl`` RL libraries through the use of the
This is possible in Isaac Lab through the use of the
`PyTorch distributed <https://pytorch.org/docs/stable/distributed.html>`_ framework.
In this workflow, ``torch.distributed`` is used to launch multiple processes of training, where the number of
The :meth:`torch.distributed` API is used to launch multiple processes of training, where the number of
processes must be equal to or less than the number of GPUs available. Each process runs on
a dedicated GPU and launches its own instance of Isaac Sim and the Isaac Lab environment.
Each process collects its own rollouts during the training process and has its own copy of the policy
......@@ -31,28 +31,26 @@ at the end of the epoch.
:align: center
:alt: Multi-GPU training paradigm
|
To train with multiple GPUs, use the following command, where ``--proc_per_node`` represents the number of available GPUs:
.. tabs::
.. tab-set::
:sync-group: rl-train
.. group-tab:: rl_games
.. tab-item:: rl_games
:sync: rl_games
.. code-block:: shell
python -m torch.distributed.run --nnodes=1 --nproc_per_node=2 source/standalone/workflows/rl_games/train.py --task=Isaac-Cartpole-v0 --headless --distributed
.. group-tab:: skrl
.. tab-item:: skrl
:sync: skrl
.. code-block:: shell
python -m torch.distributed.run --nnodes=1 --nproc_per_node=2 source/standalone/workflows/skrl/train.py --task=Isaac-Cartpole-v0 --headless --distributed
Due to limitations of NCCL on Windows, this feature is currently supported on Linux only.
Multi-Node Training
-------------------
......@@ -62,15 +60,18 @@ To train across multiple nodes/machines, it is required to launch an individual
For the master node, use the following command, where ``--proc_per_node`` represents the number of available GPUs, and
``--nnodes`` represents the number of nodes:
.. tabs::
.. tab-set::
:sync-group: rl-train
.. group-tab:: rl_games
.. tab-item:: rl_games
:sync: rl_games
.. code-block:: shell
python -m torch.distributed.run --nproc_per_node=2 --nnodes=2 --node_rank=0 --rdzv_id=123 --rdzv_backend=c10d --rdzv_endpoint=localhost:5555 source/standalone/workflows/rl_games/train.py --task=Isaac-Cartpole-v0 --headless --distributed
.. group-tab:: skrl
.. tab-item:: skrl
:sync: skrl
.. code-block:: shell
......@@ -80,15 +81,18 @@ Note that the port (``5555``) can be replaced with any other available port.
For non-master nodes, use the following command, replacing ``--node_rank`` with the index of each machine:
.. tabs::
.. tab-set::
:sync-group: rl-train
.. group-tab:: rl_games
.. tab-item:: rl_games
:sync: rl_games
.. code-block:: shell
python -m torch.distributed.run --nproc_per_node=2 --nnodes=2 --node_rank=1 --rdzv_id=123 --rdzv_backend=c10d --rdzv_endpoint=ip_of_master_machine:5555 source/standalone/workflows/rl_games/train.py --task=Isaac-Cartpole-v0 --headless --distributed
.. group-tab:: skrl
.. tab-item:: skrl
:sync: skrl
.. code-block:: shell
......
......@@ -94,6 +94,7 @@ The ``Isaac Lab`` repository is structured as follows:
├── source
│   ├── extensions
│   │   ├── omni.isaac.lab
│   │   ├── omni.isaac.lab_assets
│   │   └── omni.isaac.lab_tasks
│   ├── standalone
│   │   ├── demos
......@@ -189,34 +190,6 @@ important to note that Omniverse also provides a similar
However, it requires going through the build process and does not support testing of the python module in
standalone applications.
Extension Dependency Management
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Certain extensions may have dependencies which need to be installed before the extension can be run.
While Python dependencies can be expressed via the ``INSTALL_REQUIRES`` array in ``setup.py``, we need
a separate installation pipeline to handle non-Python dependencies. We have therefore created
an additional setup procedure, ``./isaaclab.sh --install-deps {dep_type}``, which scans the ``extension.toml``
file of the directories under ``source/extensions`` for ``apt`` and ``rosdep`` dependencies.
This example ``extension.toml`` has both ``apt_deps`` and ``ros_ws`` specified, so both
``apt`` and ``rosdep`` packages will be installed if ``./isaaclab.sh --install-deps all``
is passed:
.. code-block:: toml
[isaaclab_settings]
apt_deps = ["example_package"]
ros_ws = "path/from/extension_root/to/ros_ws"
From the ``apt_deps`` in the above example, the package ``example_package`` would be installed via ``apt``.
From the ``ros_ws``, a ``rosdep install --from-paths {ros_ws}/src --ignore-src`` command will be called.
This will install all the `ROS package.xml dependencies <https://docs.ros.org/en/humble/Tutorials/Intermediate/Rosdep.html>`__
in the directory structure below. Currently the ROS distro is assumed to be ``humble``.
``apt`` deps are automatically installed this way during the build process of the ``Dockerfile.base``,
and ``rosdep`` deps during the build process of ``Dockerfile.ros2``.
Standalone applications
~~~~~~~~~~~~~~~~~~~~~~~
......
......@@ -19,14 +19,17 @@ To check the minimum system requirements,refer to the documentation
We have tested Isaac Lab with Isaac Sim 4.0 release on Ubuntu
20.04LTS with NVIDIA driver 525.147.
.. tabs::
.. tab-set::
:sync-group: os
.. tab:: Linux
.. tab-item:: Linux
:sync: linux
On Linux systems, by default, Isaac Sim is installed in the directory
``${HOME}/.local/share/ov/pkg/isaac_sim-*``, with ``*`` corresponding to the Isaac Sim version.
.. tab:: Windows
.. tab-item:: Windows
:sync: windows
On Windows systems, by default,Isaac Sim is installed in the directory
``C:\Users\user\AppData\Local\ov\pkg\isaac_sim-*``, with ``*`` corresponding to the Isaac Sim version.
......@@ -47,11 +50,18 @@ Cloning Isaac Lab
Clone the Isaac Lab repository into your workspace:
.. code:: bash
.. tab-set::
.. tab-item:: SSH
.. code:: bash
# Option 1: With SSH
git clone git@github.com:isaac-sim/IsaacLab.git
# Option 2: With HTTPS
.. tab-item:: HTTPS
.. code:: bash
git clone https://github.com/isaac-sim/IsaacLab.git
......@@ -59,9 +69,11 @@ Clone the Isaac Lab repository into your workspace:
We provide a helper executable `isaaclab.sh <https://github.com/isaac-sim/IsaacLab/blob/main/isaaclab.sh>`_ that provides
utilities to manage extensions:
.. tabs::
.. tab-set::
:sync-group: os
.. tab:: Linux
.. tab-item:: Linux
:sync: linux
.. code:: text
......@@ -81,7 +93,8 @@ Clone the Isaac Lab repository into your workspace:
-d, --docs Build the documentation from source using sphinx.
-c, --conda [NAME] Create the conda environment for Isaac Lab. Default name is 'isaaclab'.
.. tab:: Windows
.. tab-item:: Windows
:sync: windows
.. code:: text
......@@ -108,9 +121,11 @@ Set up a symbolic link between the installed Isaac Sim root folder
and ``_isaac_sim`` in the Isaac Lab directory. This makes it convenient
to index the python modules and look for extensions shipped with Isaac Sim.
.. tabs::
.. tab-set::
:sync-group: os
.. tab:: Linux
.. tab-item:: Linux
:sync: linux
.. code:: bash
......@@ -120,7 +135,8 @@ to index the python modules and look for extensions shipped with Isaac Sim.
ln -s path_to_isaac_sim _isaac_sim
# For example: ln -s /home/nvidia/.local/share/ov/pkg/isaac-sim-4.0.0 _isaac_sim
.. tab:: Windows
.. tab-item:: Windows
:sync: windows
.. code:: batch
......@@ -128,7 +144,7 @@ to index the python modules and look for extensions shipped with Isaac Sim.
cd IsaacLab
:: create a symbolic link - requires launching Command Prompt with Administrator access
mklink /D _isaac_sim path_to_isaac_sim
# For example: mklink /D _isaac_sim C:/Users/nvidia/AppData/Local/ov/pkg/isaac-sim-4.0.0
:: For example: mklink /D _isaac_sim C:/Users/nvidia/AppData/Local/ov/pkg/isaac-sim-4.0.0
Setting up the conda environment (optional)
......@@ -148,9 +164,11 @@ Although using a virtual environment is optional, we recommend using ``conda``.
In case you want to use ``conda`` to create a virtual environment, you can
use the following command:
.. tabs::
.. tab-set::
:sync-group: os
.. tab:: Linux
.. tab-item:: Linux
:sync: linux
.. code:: bash
......@@ -159,7 +177,8 @@ use the following command:
# Option 2: Custom name for conda environment
./isaaclab.sh --conda my_env # or "./isaaclab.sh -c my_env"
.. tab:: Windows
.. tab-item:: Windows
:sync: windows
.. code:: batch
......@@ -186,45 +205,53 @@ is equivalent to running ``python`` or ``python3`` in your virtual environment.
Installation
~~~~~~~~~~~~
- Install dependencies using ``apt`` (on Ubuntu):
- Install dependencies using ``apt`` (on Linux only):
.. code:: bash
# these dependency are needed by robomimic which is not available on Windows
sudo apt install cmake build-essential
- Run the install command that iterates over all the extensions in ``source/extensions`` directory and installs them
using pip (with ``--editable`` flag):
.. tabs::
.. tab-set::
:sync-group: os
.. tab:: Linux
.. tab-item:: Linux
:sync: linux
.. code:: bash
./isaaclab.sh --install # or "./isaaclab.sh -i"
.. tab:: Windows
.. tab-item:: Windows
:sync: windows
.. code:: bash
.. code:: batch
isaaclab.bat --install :: or "isaaclab.bat -i"
.. note::
By default, this will install all the learning frameworks. If you want to install only a specific framework, you can
By default, the above will install all the learning frameworks. If you want to install only a specific framework, you can
pass the name of the framework as an argument. For example, to install only the ``rl_games`` framework, you can run
.. tabs::
.. tab-set::
:sync-group: os
.. tab:: Linux
.. tab-item:: Linux
:sync: linux
.. code:: bash
./isaaclab.sh --install rl_games
./isaaclab.sh --install rl_games # or "./isaaclab.sh -i rl_games"
.. tab:: Windows
.. tab-item:: Windows
:sync: windows
.. code:: bash
.. code:: batch
isaaclab.bat --install rl_games :: or "isaaclab.bat -i"
isaaclab.bat --install rl_games :: or "isaaclab.bat -i rl_games"
The valid options are ``rl_games``, ``rsl_rl``, ``sb3``, ``skrl``, ``robomimic``, ``none``.
......@@ -51,29 +51,39 @@ Running Isaac Automator
To run Isaac Automator, first build the Isaac Automator container:
.. tabs::
.. tab-set::
:sync-group: os
.. tab-item:: Linux
:sync: linux
.. tab:: Linux
.. code-block:: bash
./build
.. tab:: Windows
.. code-block:: bash
.. tab-item:: Windows
:sync: windows
.. code-block:: batch
docker build --platform linux/x86_64 -t isa .
Next, enter the automator container:
.. tabs::
.. tab-set::
:sync-group: os
.. tab-item:: Linux
:sync: linux
.. tab:: Linux
.. code-block:: bash
./run
.. tab:: Windows
.. code-block:: bash
.. tab-item:: Windows
:sync: windows
.. code-block:: batch
docker run --platform linux/x86_64 -it --rm -v .:/app isa bash
......@@ -108,10 +118,23 @@ Isaac Lab commands can be executed in the same way as running locally.
For example:
.. code-block:: bash
.. tab-set::
:sync-group: os
.. tab-item:: Linux
:sync: linux
.. code-block:: bash
./isaaclab.sh -p source/standalone/workflows/rl_games/train.py --task=Isaac-Cartpole-v0
.. tab-item:: Windows
:sync: windows
.. code-block:: batch
./isaaclab.bat -p source/standalone/workflows/rl_games/train.py --task=Isaac-Cartpole-v0
Destroying a Development
-------------------------
......
......@@ -21,37 +21,52 @@ Installing Isaac Sim
- To use the pip installation approach for Isaac Sim, we recommend first creating a virtual environment.
Ensure that the python version of the virtual environment is **Python 3.10**.
.. tabs::
.. tab-set::
.. tab:: Conda
.. tab-item:: conda environment
.. code-block:: bash
conda create -n isaaclab python=3.10
conda activate isaaclab
.. tab:: Virtual environment (venv)
.. tab-item:: venv environment
.. tab-set::
:sync-group: os
.. tab-item:: Linux
:sync: linux
.. code-block:: bash
# create a conda environment named isaaclab with python3.10
python3.10 -m venv isaaclab
# on Linux
# activate the conda environment
source isaaclab/bin/activate
# on Windows
.. tab-item:: Windows
:sync: windows
.. code-block:: batch
# create a virtual environment named isaaclab with python3.10
python3.10 -m venv isaaclab
# activate the virtual environment
isaaclab\Scripts\activate
- Next, install a CUDA-enabled PyTorch 2.2.2 build based on the CUDA version available on your system.
.. tabs::
.. tab-set::
.. tab:: CUDA 11
.. tab-item:: CUDA 11
.. code-block:: bash
pip install torch==2.2.2 --index-url https://download.pytorch.org/whl/cu118
.. tab:: CUDA 12
.. tab-item:: CUDA 12
.. code-block:: bash
......@@ -80,20 +95,30 @@ Cloning Isaac Lab
Clone the Isaac Lab repository into your workspace:
.. code:: bash
.. tab-set::
.. tab-item:: SSH
.. code:: bash
# Option 1: With SSH
git clone git@github.com:isaac-sim/IsaacLab.git
# Option 2: With HTTPS
.. tab-item:: HTTPS
.. code:: bash
git clone https://github.com/isaac-sim/IsaacLab.git
.. note::
We provide a helper executable `isaaclab.sh <https://github.com/isaac-sim/IsaacLab/blob/main/isaaclab.sh>`_ that provides
utilities to manage extensions:
.. tabs::
.. tab-set::
:sync-group: os
.. tab:: Linux
.. tab-item:: Linux
:sync: linux
.. code:: text
......@@ -113,7 +138,8 @@ Clone the Isaac Lab repository into your workspace:
-d, --docs Build the documentation from source using sphinx.
-c, --conda [NAME] Create the conda environment for Isaac Lab. Default name is 'isaaclab'.
.. tab:: Windows
.. tab-item:: Windows
:sync: windows
.. code:: text
......@@ -144,36 +170,43 @@ Installation
- Run the install command that iterates over all the extensions in ``source/extensions`` directory and installs them
using pip (with ``--editable`` flag):
.. tabs::
.. tab-set::
:sync-group: os
.. tab:: Linux
.. tab-item:: Linux
:sync: linux
.. code:: bash
./isaaclab.sh --install # or "./isaaclab.sh -i"
.. tab:: Windows
.. tab-item:: Windows
:sync: windows
.. code:: bash
isaaclab.bat --install :: or "isaaclab.bat -i"
.. note::
By default, this will install all the learning frameworks. If you want to install only a specific framework, you can
pass the name of the framework as an argument. For example, to install only the ``rl_games`` framework, you can run
.. tabs::
.. tab-set::
:sync-group: os
.. tab:: Linux
.. tab-item:: Linux
:sync: linux
.. code:: bash
./isaaclab.sh --install rl_games
./isaaclab.sh --install rl_games # or "./isaaclab.sh -i rl_games"
.. tab:: Windows
.. tab-item:: Windows
:sync: windows
.. code:: bash
isaaclab.bat --install rl_games :: or "isaaclab.bat -i"
isaaclab.bat --install rl_games :: or "isaaclab.bat -i rl_games"
The valid options are ``rl_games``, ``rsl_rl``, ``sb3``, ``skrl``, ``robomimic``, ``none``.
......@@ -60,9 +60,11 @@ To avoid the overhead of finding and locating the Isaac Sim installation
directory every time, we recommend exporting the following environment
variables to your terminal for the remaining of the installation instructions:
.. tabs::
.. tab-set::
:sync-group: os
.. tab:: Linux
.. tab-item:: Linux
:sync: linux
.. code:: bash
......@@ -71,7 +73,8 @@ variables to your terminal for the remaining of the installation instructions:
# Isaac Sim python executable
export ISAACSIM_PYTHON_EXE="${ISAACSIM_PATH}/python.sh"
.. tab:: Windows
.. tab-item:: Windows
:sync: windows
.. code:: batch
......@@ -87,16 +90,19 @@ For more information on common paths, please check the Isaac Sim
- Check that the simulator runs as expected:
.. tabs::
.. tab-set::
:sync-group: os
.. tab:: Linux
.. tab-item:: Linux
:sync: linux
.. code:: bash
# note: you can pass the argument "--help" to see all arguments possible.
${ISAACSIM_PATH}/isaac-sim.sh
.. tab:: Windows
.. tab-item:: Windows
:sync: windows
.. code:: batch
......@@ -106,9 +112,11 @@ For more information on common paths, please check the Isaac Sim
- Check that the simulator runs from a standalone python script:
.. tabs::
.. tab-set::
:sync-group: os
.. tab:: Linux
.. tab-item:: Linux
:sync: linux
.. code:: bash
......@@ -117,7 +125,8 @@ For more information on common paths, please check the Isaac Sim
# checks that Isaac Sim can be launched from python
${ISAACSIM_PYTHON_EXE} ${ISAACSIM_PATH}/standalone_examples/api/omni.isaac.core/add_cubes.py
.. tab:: Windows
.. tab-item:: Windows
:sync: windows
.. code:: batch
......@@ -133,15 +142,18 @@ For more information on common paths, please check the Isaac Sim
need to run the following command for the *first* time after
installation to remove all the old user data and cached variables:
.. tabs::
.. tab-set::
:sync-group: os
.. tab:: Linux
.. tab-item:: Linux
:sync: linux
.. code:: bash
${ISAACSIM_PATH}/isaac-sim.sh --reset-user
.. tab:: Windows
.. tab-item:: Windows
:sync: windows
.. code:: batch
......@@ -162,9 +174,11 @@ Verifying the Isaac Lab installation
To verify that the installation was successful, run the following command from the
top of the repository:
.. tabs::
.. tab-set::
:sync-group: os
.. tab:: Linux
.. tab-item:: Linux
:sync: linux
.. code:: bash
......@@ -175,7 +189,8 @@ top of the repository:
# Option 2: Using python in your virtual environment
python source/standalone/tutorials/00_sim/create_empty.py
.. tab:: Windows
.. tab-item:: Windows
:sync: windows
.. code:: batch
......
......@@ -47,7 +47,7 @@ class SimulationContext(_SimulationContext):
can be accessed using the ``instance()`` method.
.. attention::
Since we only support the ``torch <https://pytorch.org/>``_ backend for simulation, the
Since we only support the `PyTorch <https://pytorch.org/>`_ backend for simulation, the
simulation context is configured to use the ``torch`` backend by default. This means that
all the data structures used in the simulation are ``torch.Tensor`` objects.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment