Omniverse Isaac Gym environments#

Environments#

The repository https://github.com/NVIDIA-Omniverse/OmniIsaacGymEnvs provides the example reinforcement learning environments for Omniverse Isaac Gym.

These environments can be easily loaded and configured by calling a single function provided with this library. This function also makes it possible to configure the environment from the command line arguments (see OmniIsaacGymEnvs’s configuration-and-command-line-arguments) or from its parameters (task_name, num_envs, headless, and cli_args).

Additionally, multi-threaded environments can be loaded. These are designed to isolate the RL policy in a new thread, separate from the main simulation and rendering thread. Read more about it in the OmniIsaacGymEnvs framework documentation: Multi-Threaded Environment Wrapper.

Note

The command line arguments has priority over the function parameters.

Note

Only the configuration related to the environment will be used. The configuration related to RL algorithms are discarded since they do not belong to this library.

Note

Omniverse Isaac Gym environments implement a functionality to get their configuration from the command line. Setting the headless option from the trainer configuration will not work. In this case, it is necessary to set the load function’s headless argument to True or to invoke the scripts as follows: python script.py headless=True.

Usage#

Common environments#

In this approach, the RL algorithm maintains the main execution loop.

# import the environment loader
from skrl.envs.loaders.torch import load_omniverse_isaacgym_env

# load environment
env = load_omniverse_isaacgym_env(task_name="Cartpole")

# import the environment loader
from skrl.envs.loaders.jax import load_omniverse_isaacgym_env

# load environment
env = load_omniverse_isaacgym_env(task_name="Cartpole")

# import the environment loader
from skrl.envs.loaders.torch import load_omniverse_isaacgym_env

# load environment
env = load_omniverse_isaacgym_env()

# import the environment loader
from skrl.envs.loaders.jax import load_omniverse_isaacgym_env

# load environment
env = load_omniverse_isaacgym_env()

Run the main script passing the configuration as command line arguments. For example:

python main.py task=Cartpole

Multi-threaded environments#

In this approach, the RL algorithm is executed on a secondary thread while the simulation and rendering is executed on the main thread.

import threading

# import the environment loader
from skrl.envs.loaders.torch import load_omniverse_isaacgym_env

# load environment
env = load_omniverse_isaacgym_env(task_name="Cartpole", multi_threaded=True, timeout=30)

# ...

# start training in a separate thread
threading.Thread(target=trainer.train).start()

# run the simulation in the main thread
env.run()

import threading

# import the environment loader
from skrl.envs.loaders.jax import load_omniverse_isaacgym_env

# load environment
env = load_omniverse_isaacgym_env(task_name="Cartpole", multi_threaded=True, timeout=30)

# ...

# start training in a separate thread
threading.Thread(target=trainer.train).start()

# run the simulation in the main thread
env.run()

import threading

# import the environment loader
from skrl.envs.loaders.torch import load_omniverse_isaacgym_env

# load environment
env = load_omniverse_isaacgym_env(multi_threaded=True, timeout=30)

# ...

# start training in a separate thread
threading.Thread(target=trainer.train).start()

# run the simulation in the main thread
env.run()

import threading

# import the environment loader
from skrl.envs.loaders.jax import load_omniverse_isaacgym_env

# load environment
env = load_omniverse_isaacgym_env(multi_threaded=True, timeout=30)

# ...

# start training in a separate thread
threading.Thread(target=trainer.train).start()

# run the simulation in the main thread
env.run()

Run the main script passing the configuration as command line arguments. For example:

python main.py task=Cartpole

API#

skrl.envs.loaders.torch.load_omniverse_isaacgym_env(task_name: str = '', num_envs: int | None = None, headless: bool | None = None, cli_args: Sequence[str] = [], omniisaacgymenvs_path: str = '', show_cfg: bool = True, multi_threaded: bool = False, timeout: int = 30) → VecEnvBase | VecEnvMT#

Load an Omniverse Isaac Gym environment (OIGE)

Omniverse Isaac Gym benchmark environments: https://github.com/NVIDIA-Omniverse/OmniIsaacGymEnvs

Parameters:

task_name (str, optional) – The name of the task (default: ""). If not specified, the task name is taken from the command line argument (task=TASK_NAME). Command line argument has priority over function parameter if both are specified
num_envs (int, optional) – Number of parallel environments to create (default: None). If not specified, the default number of environments defined in the task configuration is used. Command line argument has priority over function parameter if both are specified
headless (bool, optional) – Whether to use headless mode (no rendering) (default: None). If not specified, the default task configuration is used. Command line argument has priority over function parameter if both are specified
cli_args (list of str, optional) – OIGE configuration and command line arguments (default: [])
omniisaacgymenvs_path (str, optional) – The path to the omniisaacgymenvs directory (default: ""). If empty, the path will obtained from omniisaacgymenvs package metadata
show_cfg (bool, optional) – Whether to print the configuration (default: True)
multi_threaded (bool, optional) – Whether to use multi-threaded environment (default: False)
timeout (int, optional) – Seconds to wait for data when queue is empty in multi-threaded environment (default: 30)

Raises:

ValueError – The task name has not been defined, neither by the function parameter nor by the command line arguments
RuntimeError – The omniisaacgymenvs package is not installed or the path is wrong

Returns:

Omniverse Isaac Gym environment

Return type:

omni.isaac.gym.vec_env.vec_env_base.VecEnvBase or omni.isaac.gym.vec_env.vec_env_mt.VecEnvMT