Skip to content

K
KincoActuatorIsaacLab
Unverified Commit ff5c1a94 authored by Mayank Mittal's avatar Mayank Mittal Committed by GitHub
Browse files
Options

Moves migration guides to their own section in the docs (#573) 

This MR moves the migration guide to their own section to make them more
prominent. Additionally, it removes the migration information about
Isaac Sim which is now outdated for the latest release.

## Type of change

- This change requires a documentation update

## 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
- [ ] 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 35345c63
Show whitespace changes
Inline Side-by-side
Showing with 187 additions and 148 deletions
docs/index.rst
View file @ ff5c1a94
......@@ -81,7 +81,6 @@ Table of Contents
:caption: Resources
:titlesonly:
source/migration/index
source/tutorials/index
source/how-to/index
source/deployment/index
......@@ -92,11 +91,19 @@ Table of Contents
source/api/index
.. toctree::
:maxdepth: 1
:caption: Migration Guides
:titlesonly:
source/migration/migrating_from_isaacgymenvs
source/migration/migrating_from_omniisaacgymenvs
source/migration/migrating_from_orbit
.. toctree::
:maxdepth: 1
:caption: References
source/refs/migration
source/refs/contributing
source/refs/troubleshooting
source/refs/issues
......
docs/source/features/multi_gpu.rst
View file @ ff5c1a94
......@@ -3,7 +3,14 @@ Multi-GPU and Multi-Node Training
.. currentmodule:: omni.isaac.lab
Isaac Lab supports multi-GPU and multi-node reinforcement learning on Linux.
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
other workflows.
.. attention::
Multi-GPU and multi-node training is only supported on Linux. Windows support is not available at this time.
This is due to limitations of the NCCL library on Windows.
Multi-GPU Training
......@@ -12,6 +19,7 @@ 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
`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
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.
......@@ -50,7 +58,9 @@ Multi-Node Training
To scale up training beyond multiple GPUs on a single machine, it is also possible to train across multiple nodes.
To train across multiple nodes/machines, it is required to launch an individual process on each node.
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:
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::
......@@ -84,6 +94,11 @@ For non-master nodes, use the following command, replacing ``--node_rank`` with
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/skrl/train.py --task=Isaac-Cartpole-v0 --headless --distributed
For more details on multi-node training with PyTorch, please visit the `PyTorch documentation <https://pytorch.org/tutorials/intermediate/ddp_series_multinode.html>`_. As mentioned in the PyTorch documentation, "multinode training is bottlenecked by inter-node communication latencies". When this latency is high, it is possible multi-node training will perform worse than running on a single node instance.
For more details on multi-node training with PyTorch, please visit the
`PyTorch documentation <https://pytorch.org/tutorials/intermediate/ddp_series_multinode.html>`_.
Due to limitations of NCCL on Windows, this feature is currently supported on Linux only.
.. note::
As mentioned in the PyTorch documentation, "multi-node training is bottlenecked by inter-node communication
latencies". When this latency is high, it is possible multi-node training will perform worse than running on
a single node instance.
docs/source/migration/index.rst deleted 100644 → 0
View file @ 35345c63
Migration Guides
================
The following guides show the migration process from previous frameworks that are now deprecated,
including IsaacGymEnvs, OmniIsaacGymEnvs, and Orbit.
.. toctree::
:maxdepth: 1
:titlesonly:
migrating_from_isaacgymenvs
migrating_from_omniisaacgymenvs
migrating_from_orbit
docs/source/migration/migrating_from_isaacgymenvs.rst
View file @ ff5c1a94
.. _migrating-from-isaacgymenvs:
Migrating from IsaacGymEnvs and Isaac Gym Preview Release
=========================================================
From IsaacGymEnvs
=================
.. currentmodule:: omni.isaac.lab
IsaacGymEnvs was a reinforcement learning framework designed for the Isaac Gym Preview Release.
As both IsaacGymEnvs and the Isaac Gym Preview Release are now deprecated, the following guide walks through the key differences
between IsaacGymEnvs and Isaac Lab, as well as differences in APIs between Isaac Gym Preview Release
and Isaac Sim.
`IsaacGymEnvs`_ was a reinforcement learning framework designed for the `Isaac Gym Preview Release`_.
As both IsaacGymEnvs and the Isaac Gym Preview Release are now deprecated, the following guide walks through
the key differences between IsaacGymEnvs and Isaac Lab, as well as differences in APIs between Isaac Gym Preview
Release and Isaac Sim.
Task Config Setup
~~~~~~~~~~~~~~~~~
In IsaacGymEnvs, task config files were defined in ``.yaml`` format. With Isaac Lab, configs are now specified using a specialized
Python class :class:`~omni.isaac.lab.utils.configclass`. The :class:`~omni.isaac.lab.utils.configclass` module provides a wrapper on top of Python's ``dataclasses`` module.
Each environment should specify its own config class annotated by ``@configclass`` that inherits from :class:`~envs.DirectRLEnvCfg`,
which can include simulation parameters, environment scene parameters, robot parameters, and task-specific parameters.
In IsaacGymEnvs, task config files were defined in ``.yaml`` format. With Isaac Lab, configs are now specified using
a specialized Python class :class:`~omni.isaac.lab.utils.configclass`. The :class:`~omni.isaac.lab.utils.configclass`
module provides a wrapper on top of Python's ``dataclasses`` module. Each environment should specify its own config
class annotated by ``@configclass`` that inherits from :class:`~envs.DirectRLEnvCfg`, which can include simulation
parameters, environment scene parameters, robot parameters, and task-specific parameters.
Below is an example skeleton of a task config class:
......@@ -48,14 +49,16 @@ Below is an example skeleton of a task config class:
Simulation Config
-----------------
Simulation related parameters are defined as part of the :class:`~omni.isaac.lab.sim.SimulationCfg` class, which is a :class:`~omni.isaac.lab.utils.configclass` module
that holds simulation parameters such as ``dt``, ``device``, and ``gravity``.
Each task config must have a variable named ``sim`` defined that holds the type :class:`~omni.isaac.lab.sim.SimulationCfg`.
Simulation related parameters are defined as part of the :class:`~omni.isaac.lab.sim.SimulationCfg` class,
which is a :class:`~omni.isaac.lab.utils.configclass` module that holds simulation parameters such as ``dt``,
``device``, and ``gravity``. Each task config must have a variable named ``sim`` defined that holds the type
:class:`~omni.isaac.lab.sim.SimulationCfg`.
In Isaac Lab, the use of ``substeps`` has been replaced
by a combination of the simulation ``dt`` and the ``decimation`` parameters. For example, in IsaacGymEnvs, having ``dt=1/60`` and ``substeps=2``
is equivalent to taking 2 simulation steps with ``dt=1/120``, but running the task step at ``1/60`` seconds.
The ``decimation`` parameter is a task parameter that controls the number of simulation steps to take for each task (or RL) step, replacing the ``controlFrequencyInv`` parameter in IsaacGymEnvs.
by a combination of the simulation ``dt`` and the ``decimation`` parameters. For example, in IsaacGymEnvs, having
``dt=1/60`` and ``substeps=2`` is equivalent to taking 2 simulation steps with ``dt=1/120``, but running the task step
at ``1/60`` seconds. The ``decimation`` parameter is a task parameter that controls the number of simulation steps to
take for each task (or RL) step, replacing the ``controlFrequencyInv`` parameter in IsaacGymEnvs.
Thus, the same setup in Isaac Lab will become ``dt=1/120`` and ``decimation=2``.
In Isaac Sim, physx simulation parameters such as ``num_position_iterations``, ``num_velocity_iterations``,
......@@ -66,7 +69,8 @@ to each individual articulation and rigid body config.
When running simulation on the GPU, buffers in PhysX require pre-allocation for computing and storing
information such as contacts, collisions and aggregate pairs. These buffers may need to be adjusted
depending on the complexity of the environment, the number of expected contacts and collisions,
and the number of actors in the environment. The :class:`~omni.isaac.lab.sim.PhysxCfg` class provides access for setting the GPU buffer dimensions.
and the number of actors in the environment. The :class:`~omni.isaac.lab.sim.PhysxCfg` class provides access for
setting the GPU buffer dimensions.
+--------------------------------------------------------------+-------------------------------------------------------------------+
| | |
......@@ -99,9 +103,9 @@ and the number of actors in the environment. The :class:`~omni.isaac.lab.sim.Phy
Scene Config
------------
The :class:`~omni.isaac.lab.scene.InteractiveSceneCfg` class can be used to specify parameters related to the scene, such as the number of environments
and the spacing between environments.
Each task config must have a variable named ``scene`` defined that holds the type :class:`~omni.isaac.lab.scene.InteractiveSceneCfg`.
The :class:`~omni.isaac.lab.scene.InteractiveSceneCfg` class can be used to specify parameters related to the scene,
such as the number of environments and the spacing between environments. Each task config must have a variable named
``scene`` defined that holds the type :class:`~omni.isaac.lab.scene.InteractiveSceneCfg`.
+--------------------------------------------------------------+-------------------------------------------------------------------+
| | |
......@@ -129,8 +133,9 @@ The following parameters must be set for each environment config:
num_observations = 4
num_states = 0
Note that the maximum episode length parameter (now ``episode_length_s``) is in seconds instead of steps as it was in IsaacGymEnvs. To convert between
step count to seconds, use the equation: ``episode_length_s = dt * decimation * num_steps``
Note that the maximum episode length parameter (now ``episode_length_s``) is in seconds instead of steps as it was
in IsaacGymEnvs. To convert between step count to seconds, use the equation:
``episode_length_s = dt * decimation * num_steps``
RL Config Setup
......@@ -231,10 +236,13 @@ The terrain can then be added to the scene in ``_setup_scene(self)`` by referenc
Actors
------
Isaac Lab and Isaac Sim both use the `USD (Universal Scene Description) <https://github.com/PixarAnimationStudios/OpenUSD>`_ library for describing the scene. Assets defined in MJCF and URDF formats can be imported to USD using importer tools described in the `Importing a New Asset <../how-to/import_new_asset.html>`_ tutorial.
Isaac Lab and Isaac Sim both use the `USD (Universal Scene Description) <https://github.com/PixarAnimationStudios/OpenUSD>`_
library for describing the scene. Assets defined in MJCF and URDF formats can be imported to USD using importer
tools described in the `Importing a New Asset <../how-to/import_new_asset.html>`_ tutorial.
Each Articulation and Rigid Body actor can also have its own config class. The :class:`~omni.isaac.lab.assets.ArticulationCfg` can be
used to define parameters for articulation actors, including file path, simulation parameters, actuator properties, and initial states.
Each Articulation and Rigid Body actor can also have its own config class. The
:class:`~omni.isaac.lab.assets.ArticulationCfg` class can be used to define parameters for articulation actors,
including file path, simulation parameters, actuator properties, and initial states.
.. code-block::python
......@@ -276,17 +284,19 @@ used to define parameters for articulation actors, including file path, simulati
},
)
Within the :class:`~assets.ArticulationCfg`, the ``spawn`` attribute can be used to add the robot to the scene by specifying the path to the robot file.
In addition, :class:`~omni.isaac.lab.sim.schemas.RigidBodyPropertiesCfg` can be used to specify simulation properties
for the rigid bodies in the articulation.
Similarly, :class:`~omni.isaac.lab.sim.schemas.ArticulationRootPropertiesCfg` can be used to specify simulation properties for the articulation.
Joint and dof properties are now specified as part of the ``actuators`` dictionary using :class:`~actuators.ImplicitActuatorCfg`.
Joints and dofs with the same properties can be grouped into regex expressions or provided as a list of names or expressions.
Within the :class:`~assets.ArticulationCfg`, the ``spawn`` attribute can be used to add the robot to the scene by
specifying the path to the robot file. In addition, :class:`~omni.isaac.lab.sim.schemas.RigidBodyPropertiesCfg` can
be used to specify simulation properties for the rigid bodies in the articulation.
Similarly, the :class:`~omni.isaac.lab.sim.schemas.ArticulationRootPropertiesCfg` class can be used to specify
simulation properties for the articulation. Joint properties are now specified as part of the ``actuators``
dictionary using :class:`~actuators.ImplicitActuatorCfg`. Joints with the same properties can be grouped into
regex expressions or provided as a list of names or expressions.
Actors are added to the scene by simply calling ``self.cartpole = Articulation(self.cfg.robot_cfg)``,
where ``self.cfg.robot_cfg`` is an :class:`~assets.ArticulationCfg` object. Once initialized, they should also be added
to the :class:`~scene.InteractiveScene` by calling ``self.scene.articulations["cartpole"] = self.cartpole`` so that
the :class:`~scene.InteractiveScene` can traverse through actors in the scene for writing values to the simulation and resetting.
where ``self.cfg.robot_cfg`` is an :class:`~assets.ArticulationCfg` object. Once initialized, they should also
be added to the :class:`~scene.InteractiveScene` by calling ``self.scene.articulations["cartpole"] = self.cartpole``
so that the :class:`~scene.InteractiveScene` can traverse through actors in the scene for writing values to the
simulation and resetting.
Simulation Parameters for Actors
""""""""""""""""""""""""""""""""
......@@ -906,3 +916,7 @@ To launch inferencing in Isaac Lab, use the command:
.. code-block:: bash
python source/standalone/workflows/rl_games/play.py --task=Isaac-Cartpole-Direct-v0 --num_envs=25 --checkpoint=<path/to/checkpoint>
.. _IsaacGymEnvs: https://github.com/isaac-sim/IsaacGymEnvs
.. _Isaac Gym Preview Release: https://developer.nvidia.com/isaac-gym
docs/source/migration/migrating_from_omniisaacgymenvs.rst
View file @ ff5c1a94
.. _migrating-from-omniisaacgymenvs:
Migrating from OmniIsaacGymEnvs
===============================
From OmniIsaacGymEnvs
=====================
.. currentmodule:: omni.isaac.lab
OmniIsaacGymEnvs was a reinforcement learning framework using the Isaac Sim platform.
`OmniIsaacGymEnvs`_ was a reinforcement learning framework using the Isaac Sim platform.
Features from OmniIsaacGymEnvs have been integrated into the Isaac Lab framework.
We have updated OmniIsaacGymEnvs to Isaac Sim version 4.0.0 to support the migration process
to Isaac Lab. Moving forward, OmniIsaacGymEnvs will be deprecated and future development
......@@ -16,10 +16,12 @@ will continue in Isaac Lab.
Task Config Setup
~~~~~~~~~~~~~~~~~
In OmniIsaacGymEnvs, task config files were defined in ``.yaml`` format. With Isaac Lab, configs are now specified using a specialized
Python class :class:`~omni.isaac.lab.utils.configclass`. The :class:`~omni.isaac.lab.utils.configclass` module provides a wrapper on top of Python's ``dataclasses`` module.
Each environment should specify its own config class annotated by ``@configclass`` that inherits from :class:`~envs.DirectRLEnvCfg`,
which can include simulation parameters, environment scene parameters, robot parameters, and task-specific parameters.
In OmniIsaacGymEnvs, task config files were defined in ``.yaml`` format. With Isaac Lab, configs are now specified
using a specialized Python class :class:`~omni.isaac.lab.utils.configclass`. The
:class:`~omni.isaac.lab.utils.configclass` module provides a wrapper on top of Python's ``dataclasses`` module.
Each environment should specify its own config class annotated by ``@configclass`` that inherits from the
:class:`~envs.DirectRLEnvCfg` class, which can include simulation parameters, environment scene parameters,
robot parameters, and task-specific parameters.
Below is an example skeleton of a task config class:
......@@ -49,9 +51,10 @@ Below is an example skeleton of a task config class:
Simulation Config
-----------------
Simulation related parameters are defined as part of the :class:`~omni.isaac.lab.sim.SimulationCfg` class, which is a :class:`~omni.isaac.lab.utils.configclass` module
that holds simulation parameters such as ``dt``, ``device``, and ``gravity``.
Each task config must have a variable named ``sim`` defined that holds the type :class:`~omni.isaac.lab.sim.SimulationCfg`.
Simulation related parameters are defined as part of the :class:`~omni.isaac.lab.sim.SimulationCfg` class,
which is a :class:`~omni.isaac.lab.utils.configclass` module that holds simulation parameters such as ``dt``,
``device``, and ``gravity``. Each task config must have a variable named ``sim`` defined that holds the type
:class:`~omni.isaac.lab.sim.SimulationCfg`.
Simulation parameters for articulations and rigid bodies such as ``num_position_iterations``, ``num_velocity_iterations``,
``contact_offset``, ``rest_offset``, ``bounce_threshold_velocity``, ``max_depenetration_velocity`` can all
......@@ -60,7 +63,8 @@ be specified on a per-actor basis in the config class for each individual articu
When running simulation on the GPU, buffers in PhysX require pre-allocation for computing and storing
information such as contacts, collisions and aggregate pairs. These buffers may need to be adjusted
depending on the complexity of the environment, the number of expected contacts and collisions,
and the number of actors in the environment. The :class:`~omni.isaac.lab.sim.PhysxCfg` class provides access for setting the GPU buffer dimensions.
and the number of actors in the environment. The :class:`~omni.isaac.lab.sim.PhysxCfg` class provides access
for setting the GPU buffer dimensions.
+--------------------------------------------------------------+-------------------------------------------------------------------+
| | |
......@@ -116,9 +120,9 @@ Parameters such as ``add_ground_plane`` and ``add_distant_light`` are now part o
Scene Config
------------
The :class:`~omni.isaac.lab.scene.InteractiveSceneCfg` class can be used to specify parameters related to the scene, such as the number of environments
and the spacing between environments.
Each task config must have a variable named ``scene`` defined that holds the type :class:`~omni.isaac.lab.scene.InteractiveSceneCfg`.
The :class:`~omni.isaac.lab.scene.InteractiveSceneCfg` class can be used to specify parameters related to the scene,
such as the number of environments and the spacing between environments. Each task config must have a variable named
``scene`` defined that holds the type :class:`~omni.isaac.lab.scene.InteractiveSceneCfg`.
+--------------------------------------------------------------+-------------------------------------------------------------------+
| | |
......@@ -139,8 +143,9 @@ observation and action buffers. Reward term scaling parameters can also be speci
In Isaac Lab, the ``controlFrequencyInv`` parameter has been renamed to ``decimation``,
which must be specified as a parameter in the config class.
In addition, the maximum episode length parameter (now ``episode_length_s``) is in seconds instead of steps as it was in OmniIsaacGymEnvs.
To convert between step count to seconds, use the equation: ``episode_length_s = dt * decimation * num_steps``.
In addition, the maximum episode length parameter (now ``episode_length_s``) is in seconds instead of steps as it was
in OmniIsaacGymEnvs. To convert between step count to seconds, use the equation:
``episode_length_s = dt * decimation * num_steps``.
The following parameters must be set for each environment config:
......@@ -253,9 +258,9 @@ The terrain can then be added to the scene in ``_setup_scene(self)`` by referenc
Actors
------
In Isaac Lab, each Articulation and Rigid Body actor can have its own config class.
The :class:`~omni.isaac.lab.assets.ArticulationCfg` can be
used to define parameters for articulation actors, including file path, simulation parameters, actuator properties, and initial states.
In Isaac Lab, each Articulation and Rigid Body actor can have its own config class. The
:class:`~omni.isaac.lab.assets.ArticulationCfg` class can be used to define parameters for articulation actors,
including file path, simulation parameters, actuator properties, and initial states.
.. code-block::python
......@@ -297,26 +302,29 @@ used to define parameters for articulation actors, including file path, simulati
},
)
Within the :class:`~assets.ArticulationCfg`, the ``spawn`` attribute can be used to add the robot to the scene by specifying the path to the robot file.
In addition, :class:`~omni.isaac.lab.sim.schemas.RigidBodyPropertiesCfg` can be used to specify simulation properties
for the rigid bodies in the articulation.
Similarly, :class:`~omni.isaac.lab.sim.schemas.ArticulationRootPropertiesCfg` can be used to specify simulation properties for the articulation.
Joint and dof properties are now specified as part of the ``actuators`` dictionary using :class:`~actuators.ImplicitActuatorCfg`.
Joints and dofs with the same properties can be grouped into regex expressions or provided as a list of names or expressions.
Within the :class:`~assets.ArticulationCfg`, the ``spawn`` attribute can be used to add the robot to the scene
by specifying the path to the robot file. In addition, the :class:`~omni.isaac.lab.sim.schemas.RigidBodyPropertiesCfg`
class can be used to specify simulation properties for the rigid bodies in the articulation. Similarly, the
:class:`~omni.isaac.lab.sim.schemas.ArticulationRootPropertiesCfg` class can be used to specify simulation properties
for the articulation. The joint properties are now specified as part of the ``actuators`` dictionary using
:class:`~actuators.ImplicitActuatorCfg`. Joints with the same properties can be grouped into regex expressions or
provided as a list of names or expressions.
Actors are added to the scene by simply calling ``self.cartpole = Articulation(self.cfg.robot_cfg)``,
where ``self.cfg.robot_cfg`` is an :class:`~assets.ArticulationCfg` object. Once initialized, they should also be added
Actors are added to the scene by simply calling ``self.cartpole = Articulation(self.cfg.robot_cfg)``, where
``self.cfg.robot_cfg`` is an :class:`~assets.ArticulationCfg` object. Once initialized, they should also be added
to the :class:`~scene.InteractiveScene` by calling ``self.scene.articulations["cartpole"] = self.cartpole`` so that
the :class:`~scene.InteractiveScene` can traverse through actors in the scene for writing values to the simulation and resetting.
the :class:`~scene.InteractiveScene` can traverse through actors in the scene for writing values to the simulation
and resetting.
Accessing States from Simulation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
APIs for accessing physics states in Isaac Lab require the creation of an :class:`~assets.Articulation` or :class:`~assets.RigidObject`
object. Multiple objects can be initialized for different articulations or rigid bodies in the scene by defining
corresponding :class:`~assets.ArticulationCfg` or :class:`~assets.RigidObjectCfg` config, as outlined in the section above.
This replaces the previously used ``ArticulationView`` and ``RigidPrimView`` classes used in OmniIsaacGymEnvs.
APIs for accessing physics states in Isaac Lab require the creation of an :class:`~assets.Articulation` or
:class:`~assets.RigidObject` object. Multiple objects can be initialized for different articulations or rigid bodies
in the scene by defining corresponding :class:`~assets.ArticulationCfg` or :class:`~assets.RigidObjectCfg` config,
as outlined in the section above. This replaces the previously used :class:`~omni.isaac.core.articulations.ArticulationView`
and :class:`omni.isaac.core.prims.RigidPrimView` classes used in OmniIsaacGymEnvs.
However, functionality between the classes are similar:
......@@ -370,10 +378,13 @@ Each environment in Isaac Lab should be in its own directory following this stru
my_env.py
* ``my_environment`` is the root directory of the task.
* ``my_environment/agents`` is the directory containing all RL config files for the task. Isaac Lab supports multiple RL libraries that can each have its own individual config file.
* ``my_environment/__init__.py`` is the main file that registers the environment with the Gymnasium interface. This allows the training and inferencing scripts to find the task by its name. The content of this file should be as follow:
* ``my_environment/agents`` is the directory containing all RL config files for the task. Isaac Lab supports multiple
RL libraries that can each have its own individual config file.
* ``my_environment/__init__.py`` is the main file that registers the environment with the Gymnasium interface.
This allows the training and inferencing scripts to find the task by its name.
The content of this file should be as follow:
.. code-block:: python
.. code-block:: python
import gymnasium as gym
......@@ -394,28 +405,30 @@ Each environment in Isaac Lab should be in its own directory following this stru
},
)
* ``my_environment/my_env.py`` is the main python script that implements the task logic and task config class for the environment.
* ``my_environment/my_env.py`` is the main python script that implements the task logic and task config class for
the environment.
Task Logic
~~~~~~~~~~
The ``post_reset`` API in OmniIsaacGymEnvs is no longer required in Isaac Lab.
Everything that was previously done in ``post_reset`` can be done in the ``__init__`` method after
executing the base class's ``__init__``. At this point, simulation has already started.
The ``post_reset`` API in OmniIsaacGymEnvs is no longer required in Isaac Lab. Everything that was previously
done in ``post_reset`` can be done in the ``__init__`` method after executing the base class's
``__init__``. At this point, simulation has already started.
In OmniIsaacGymEnvs, due to limitations of the GPU APIs, resets could not be performed based on states of the current step.
Instead, resets have to be performed at the beginning of the next time step.
This restriction has been eliminated in Isaac Lab, and thus, tasks follow the correct workflow of applying actions, stepping simulation,
collecting states, computing dones, calculating rewards, performing resets, and finally computing observations.
This workflow is done automatically by the framework such that a ``post_physics_step`` API is not required in the task.
However, individual tasks can override the ``step()`` API to control the workflow.
In OmniIsaacGymEnvs, due to limitations of the GPU APIs, resets could not be performed based on states of the current
step. Instead, resets have to be performed at the beginning of the next time step.
This restriction has been eliminated in Isaac Lab, and thus, tasks follow the correct workflow of applying actions,
stepping simulation, collecting states, computing dones, calculating rewards, performing resets, and finally computing
observations. This workflow is done automatically by the framework such that a ``post_physics_step`` API is not
required in the task. However, individual tasks can override the ``step()`` API to control the workflow.
In Isaac Lab, we also separate the ``pre_physics_step`` API for processing actions from the policy with
the ``apply_action`` API, which sets the actions into the simulation. This provides more flexibility in controlling
when actions should be written to simulation when ``decimation`` is used.
``pre_physics_step`` will be called once per step before stepping simulation.
``apply_actions`` will be called ``decimation`` number of times for each RL step, once before each simulation step call.
The ``pre_physics_step`` method will be called once per step before stepping simulation.
The ``apply_actions`` method will be called ``decimation`` number of times for each RL step,
once before each simulation step call.
The ordering of the calls are as follow:
......@@ -453,7 +466,8 @@ We have also performed some renamings of APIs:
Putting It All Together
~~~~~~~~~~~~~~~~~~~~~~~
The Cartpole environment is shown here in completion to fully show the comparison between the OmniIsaacGymEnvs implementation and the Isaac Lab implementation.
The Cartpole environment is shown here in completion to fully show the comparison between the OmniIsaacGymEnvs
implementation and the Isaac Lab implementation.
Task Config
-----------
......@@ -599,9 +613,9 @@ executing the base class's ``__init__``. At this point, simulation has already s
Scene Setup
-----------
``set_up_scene`` in OmniIsaacGymEnvs has been replaced by ``_setup_scene``.
In Isaac Lab, cloning and collision filtering have been provided as APIs for the task class to call when necessary.
Similarly, adding ground plane and lights should also be taken care of in the task class.
The ``set_up_scene`` method in OmniIsaacGymEnvs has been replaced by the ``_setup_scene`` API in the task class in
Isaac Lab. Additionally, scene cloning and collision filtering have been provided as APIs for the task class to
call when necessary. Similarly, adding ground plane and lights should also be taken care of in the task class.
Adding actors to the scene has been replaced by ``self.scene.articulations["cartpole"] = self.cartpole``.
+-----------------------------------------------------------+----------------------------------------------------------+
......@@ -639,9 +653,9 @@ Adding actors to the scene has been replaced by ``self.scene.articulations["cart
Pre-Physics Step
----------------
Note that resets are no longer performed in the ``pre_physics_step`` API.
In addition, the separation of ``_pre_physics_step`` and ``_apply_action`` allow for more flexibility
in processing the action buffer and setting actions into simulation.
Note that resets are no longer performed in the ``pre_physics_step`` API. In addition, the separation of the
``_pre_physics_step`` and ``_apply_action`` methods allow for more flexibility in processing the action buffer
and setting actions into simulation.
+------------------------------------------------------------------+-------------------------------------------------------------+
| OmniIsaacGymEnvs | IsaacLab |
......@@ -675,10 +689,11 @@ in processing the action buffer and setting actions into simulation.
Dones and Resets
----------------
In Isaac Lab, ``dones`` are computed in the ``_get_dones()`` method and should return two variables: ``resets`` and ``time_out``.
``_reset_idx()`` is also called after stepping simulation instead of before, as it was done in OmniIsaacGymEnvs.
``progress_buf`` has been renamed to ``episode_length_buf`` in Isaac Lab and
bookkeeping is now done automatically by the framework. Task implementations should no longer increment and reset the ``episode_length_buf`` buffer.
In Isaac Lab, the ``dones`` are computed in the ``_get_dones()`` method and should return two variables: ``resets`` and
``time_out``. The ``_reset_idx()`` method is also called after stepping simulation instead of before, as it was done in
OmniIsaacGymEnvs. The ``progress_buf`` tensor has been renamed to ``episode_length_buf`` in Isaac Lab and the
bookkeeping is now done automatically by the framework. Task implementations no longer need to increment or
reset the ``episode_length_buf`` buffer.
+------------------------------------------------------------------+--------------------------------------------------------------------------+
| OmniIsaacGymEnvs | Isaac Lab |
......@@ -974,3 +989,6 @@ To launch inferencing in Isaac Lab, use the command:
.. code-block:: bash
python source/standalone/workflows/rl_games/play.py --task=Isaac-Cartpole-Direct-v0 --num_envs=25 --checkpoint=<path/to/checkpoint>
.. _`OmniIsaacGymEnvs`: https://github.com/isaac-sim/OmniIsaacGymEnvs
docs/source/migration/migrating_from_orbit.rst
View file @ ff5c1a94
.. _migrating-from-orbit:
Migrating from Orbit
====================
From Orbit
==========
.. currentmodule:: omni.isaac.lab
Since Orbit was used as basis for Isaac Lab, migrating from Orbit to Isaac Lab is straightforward.
Since `Orbit`_ was used as basis for Isaac Lab, migrating from Orbit to Isaac Lab is straightforward.
The following sections describe the changes that need to be made to your code to migrate from Orbit to Isaac Lab.
Updates to scripts
~~~~~~~~~~~~~~~~~~
Renaming of the launch script
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The script ``orbit.sh`` has been renamed to ``isaaclab.sh``.
......@@ -18,7 +18,8 @@ Updates to extensions
~~~~~~~~~~~~~~~~~~~~~
The extensions ``omni.isaac.orbit``, ``omni.isaac.orbit_tasks``, and ``omni.isaac.orbit_assets`` have been renamed
to ``omni.isaac.lab``, ``omni.isaac.lab_tasks``, and ``omni.isaac.lab_assets``, respectively. Thus, the new folder structure looks like this:
to ``omni.isaac.lab``, ``omni.isaac.lab_tasks``, and ``omni.isaac.lab_assets``, respectively. Thus,
the new folder structure looks like this:
- ``source/extensions/omni.isaac.lab/omni/isaac/lab``
- ``source/extensions/omni.isaac.lab_tasks/omni/isaac/lab_tasks``
......@@ -73,7 +74,7 @@ This change must also be reflected in the imports for your tasks. For example,
from omni.isaac.orbit_tasks.locomotion.velocity.velocity_env_cfg ...
should now be
should now be:
.. code-block:: python
......@@ -86,8 +87,8 @@ Other Breaking changes
Offscreen rendering
-------------------
The input argument ``--offscreen_render`` given to :class:`omni.isaac.lab.app.AppLauncher` and the environment variable ``OFFSCREEN_RENDER``
have been renamed to ``--enable_cameras`` and ``ENABLE_CAMERAS`` respectively.
The input argument ``--offscreen_render`` given to :class:`omni.isaac.lab.app.AppLauncher` and the environment variable
``OFFSCREEN_RENDER`` have been renamed to ``--enable_cameras`` and ``ENABLE_CAMERAS`` respectively.
Event term distribution configuration
......@@ -111,7 +112,7 @@ Therefore, event term configurations whose functions have a ``distribution`` arg
},
)
should now be
should now be:
.. code-block:: python
:emphasize-lines: 6
......@@ -125,3 +126,6 @@ should now be
"operation": "add",
},
)
.. _Orbit: https://isaac-orbit.github.io/
docs/source/refs/migration.rst
View file @ ff5c1a94
Migration Guide (Isaac Sim)
===========================
Moving from Isaac Sim 2022.2.1 to 2023.1.0 brings in a number of changes to the
Moving from Isaac Sim 2022.2.1 to 2023.1.0 and later brings in a number of changes to the
APIs and the way the application is built. This document outlines the changes
and how to migrate your code to the new APIs. Many of these changes attribute to
the underlying Omniverse Kit upgrade from 104.2 to 105.1. The new upgrade brings
......@@ -11,11 +11,6 @@ the following notable changes:
* Upgrading the Python from 3.7 to 3.10
.. warning::
This document is a work in progress and will be updated as we move closer
to the release of Isaac Sim 2023.1.0.
Renaming of PhysX Flatcache to PhysX Fabric
-------------------------------------------
......
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