Wrapping

This library works with a common API to interact with the following RL environments:

OpenAI Gym / Farama Gymnasium (single and vectorized environments)
DeepMind
robosuite
NVIDIA Isaac Gym (preview 2, 3 and 4)
NVIDIA Isaac Orbit
NVIDIA Omniverse Isaac Gym

To operate with them and to support interoperability between these non-compatible interfaces, a wrapping mechanism is provided as shown in the diagram below

Basic usage

# import the environment wrapper and loader
from skrl.envs.torch import wrap_env
from skrl.envs.torch import load_omniverse_isaacgym_env

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

# wrap the environment
env = wrap_env(env)  # or 'env = wrap_env(env, wrapper="omniverse-isaacgym")'

# import the environment wrapper and loader
from skrl.envs.torch import wrap_env
from skrl.envs.torch import load_omniverse_isaacgym_env

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

# wrap the environment
env = wrap_env(env)  # or 'env = wrap_env(env, wrapper="omniverse-isaacgym")'

# import the environment wrapper and loader
from skrl.envs.torch import wrap_env
from skrl.envs.torch import load_isaac_orbit_env

# load the environment
env = load_isaac_orbit_env(task_name="Isaac-Cartpole-v0")

# wrap the environment
env = wrap_env(env)  # or 'env = wrap_env(env, wrapper="isaac-orbit")'

import isaacgymenvs

# import the environment wrapper
from skrl.envs.torch import wrap_env

# create/load the environment using the easy-to-use API from NVIDIA
env = isaacgymenvs.make(seed=0,
                        task="Cartpole",
                        num_envs=512,
                        sim_device="cuda:0",
                        rl_device="cuda:0",
                        graphics_device_id=0,
                        headless=False)

# wrap the environment
env = wrap_env(env)  # or 'env = wrap_env(env, wrapper="isaacgym-preview4")'

# import the environment wrapper and loader
from skrl.envs.torch import wrap_env
from skrl.envs.torch import load_isaacgym_env_preview4

# load the environment
env = load_isaacgym_env_preview4(task_name="Cartpole")

# wrap the environment
env = wrap_env(env)  # or 'env = wrap_env(env, wrapper="isaacgym-preview4")'

# import the environment wrapper and loader
from skrl.envs.torch import wrap_env
from skrl.envs.torch import load_isaacgym_env_preview3

# load the environment
env = load_isaacgym_env_preview3(task_name="Cartpole")

# wrap the environment
env = wrap_env(env)  # or 'env = wrap_env(env, wrapper="isaacgym-preview3")'

# import the environment wrapper and loader
from skrl.envs.torch import wrap_env
from skrl.envs.torch import load_isaacgym_env_preview2

# load the environment
env = load_isaacgym_env_preview2(task_name="Cartpole")

# wrap the environment
env = wrap_env(env)  # or 'env = wrap_env(env, wrapper="isaacgym-preview2")'

# import the environment wrapper and gym
from skrl.envs.torch import wrap_env
import gym

# load environment
env = gym.make('Pendulum-v1')

# wrap the environment
env = wrap_env(env)  # or 'env = wrap_env(env, wrapper="gym")'

Visit the Gym documentation (Vector) for more information about the creation and usage of vectorized environments

# import the environment wrapper and gym
from skrl.envs.torch import wrap_env
import gym

# load a vectorized environment
env = gym.vector.make("Pendulum-v1", num_envs=10, asynchronous=False)

# wrap the environment
env = wrap_env(env)  # or 'env = wrap_env(env, wrapper="gym")'

# import the environment wrapper and gymnasium
from skrl.envs.torch import wrap_env
import gymnasium as gym

# load environment
env = gym.make('Pendulum-v1')

# wrap the environment
env = wrap_env(env)  # or 'env = wrap_env(env, wrapper="gymnasium")'

Visit the Gymnasium documentation (Vector) for more information about the creation and usage of vectorized environments

# import the environment wrapper and gymnasium
from skrl.envs.torch import wrap_env
import gymnasium as gym

# load a vectorized environment
env = gym.vector.make("Pendulum-v1", num_envs=10, asynchronous=False)

# wrap the environment
env = wrap_env(env)  # or 'env = wrap_env(env, wrapper="gymnasium")'

# import the environment wrapper and the deepmind suite
from skrl.envs.torch import wrap_env
from dm_control import suite

# load environment
env = suite.load(domain_name="cartpole", task_name="swingup")

# wrap the environment
env = wrap_env(env)  # or 'env = wrap_env(env, wrapper="dm")'

# import the environment wrapper and robosuite
from skrl.envs.torch import wrap_env
import robosuite
from robosuite.controllers import load_controller_config

# load environment
controller_config = load_controller_config(default_controller="OSC_POSE")
env = robosuite.make("TwoArmLift",
                     robots=["Sawyer", "Panda"],             # load a Sawyer robot and a Panda robot
                     gripper_types="default",                # use default grippers per robot arm
                     controller_configs=controller_config,   # each arm is controlled using OSC
                     env_configuration="single-arm-opposed", # (two-arm envs only) arms face each other
                     has_renderer=True,                      # on-screen rendering
                     render_camera="frontview",              # visualize the "frontview" camera
                     has_offscreen_renderer=False,           # no off-screen rendering
                     control_freq=20,                        # 20 hz control for applied actions
                     horizon=200,                            # each episode terminates after 200 steps
                     use_object_obs=True,                    # provide object observations to agent
                     use_camera_obs=False,                   # don't provide image observations to agent
                     reward_shaping=True)                    # use a dense reward signal for learning

# wrap the environment
env = wrap_env(env)  # or 'env = wrap_env(env, wrapper="robosuite")'

API

skrl.envs.torch.wrappers.wrap_env(env: Any, wrapper: str = 'auto', verbose: bool = True) → skrl.envs.torch.wrappers.Wrapper

Wrap an environment to use a common interface

Example:

>>> from skrl.envs.torch import wrap_env
>>>
>>> # assuming that there is an environment called "env"
>>> env = wrap_env(env)

Parameters

env (gym.Env, gymnasium.Env, dm_env.Environment or VecTask) – The environment to be wrapped

wrapper (str, optional) –

The type of wrapper to use (default: “auto”). If "auto", the wrapper will be automatically selected based on the environment class. The supported wrappers are described in the following table:

Environment	Wrapper tag
OpenAI Gym	`"gym"`
Gymnasium	`"gymnasium"`
DeepMind	`"dm"`
Robosuite	`"robosuite"`
Isaac Gym preview 2	`"isaacgym-preview2"`
Isaac Gym preview 3	`"isaacgym-preview3"`
Isaac Gym preview 4	`"isaacgym-preview4"`
Omniverse Isaac Gym	`"omniverse-isaacgym"`
Isaac Sim (orbit)	`"isaac-orbit"`

verbose (bool, optional) – Whether to print the wrapper type (default: True)

Raises

ValueError – Unknow wrapper type

Returns

Wrapped environment

Return type

Wrapper

Internal API

class skrl.envs.torch.wrappers.Wrapper(env: Any)

Bases: object

__init__(env: Any) → None

Base wrapper class for RL environments

Parameters: env (Any supported RL environment) – The environment to wrap

property device

The device used by the environment

If the wrapped environment does not have the device property, the value of this property will be "cuda:0" or "cpu" depending on the device availability

property action_space: gym.spaces.space.Space: Action space

close() → None

Close the environment

Raises: NotImplementedError – Not implemented

property num_envs: int

Number of environments

If the wrapped environment does not have the num_envs property, it will be set to 1

property observation_space: gym.spaces.space.Space: Observation space

render(*args, **kwargs) → None

Render the environment

Raises: NotImplementedError – Not implemented

reset() → Tuple[torch.Tensor, Any]

Reset the environment

Raises: NotImplementedError – Not implemented
Returns: Observation, info
Return type: torch.Tensor and any other info

property state_space: gym.spaces.space.Space

State space

If the wrapped environment does not have the state_space property, the value of the observation_space property will be used

step(actions: torch.Tensor) → Tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, Any]

Perform a step in the environment

Parameters: actions (torch.Tensor) – The actions to perform
Raises: NotImplementedError – Not implemented
Returns: Observation, reward, terminated, truncated, info
Return type: tuple of torch.Tensor and any other info

class skrl.envs.torch.wrappers.OmniverseIsaacGymWrapper(env: Any)

Bases: skrl.envs.torch.wrappers.Wrapper

__init__(env: Any) → None

Omniverse Isaac Gym environment wrapper

Parameters: env (Any supported Omniverse Isaac Gym environment) – The environment to wrap

close() → None: Close the environment

render(*args, **kwargs) → None: Render the environment

reset() → Tuple[torch.Tensor, Any]

Reset the environment

Returns: Observation, info
Return type: torch.Tensor and any other info

run(trainer: Optional[omni.isaac.gym.vec_env.vec_env_mt.TrainerMT] = None) → None

Run the simulation in the main thread

This method is valid only for the Omniverse Isaac Gym multi-threaded environments

Parameters: trainer (omni.isaac.gym.vec_env.vec_env_mt.TrainerMT, optional) – Trainer which should implement a run method that initiates the RL loop on a new thread

step(actions: torch.Tensor) → Tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, Any]

Perform a step in the environment

Parameters: actions (torch.Tensor) – The actions to perform
Returns: Observation, reward, terminated, truncated, info
Return type: tuple of torch.Tensor and any other info

class skrl.envs.torch.wrappers.IsaacOrbitWrapper(env: Any)

Bases: skrl.envs.torch.wrappers.Wrapper

__init__(env: Any) → None

Isaac Orbit environment wrapper

Parameters: env (Any supported Isaac Orbit environment) – The environment to wrap

close() → None: Close the environment

render(*args, **kwargs) → None: Render the environment

reset() → Tuple[torch.Tensor, Any]

Reset the environment

Returns: Observation, info
Return type: torch.Tensor and any other info

step(actions: torch.Tensor) → Tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, Any]

Perform a step in the environment

Parameters: actions (torch.Tensor) – The actions to perform
Returns: Observation, reward, terminated, truncated, info
Return type: tuple of torch.Tensor and any other info

class skrl.envs.torch.wrappers.IsaacGymPreview3Wrapper(env: Any)

Bases: skrl.envs.torch.wrappers.Wrapper

__init__(env: Any) → None

Isaac Gym environment (preview 3) wrapper

Parameters: env (Any supported Isaac Gym environment (preview 3) environment) – The environment to wrap

close() → None: Close the environment

render(*args, **kwargs) → None: Render the environment

reset() → Tuple[torch.Tensor, Any]

Reset the environment

Returns: Observation, info
Return type: torch.Tensor and any other info

step(actions: torch.Tensor) → Tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, Any]

Perform a step in the environment

Parameters: actions (torch.Tensor) – The actions to perform
Returns: Observation, reward, terminated, truncated, info
Return type: tuple of torch.Tensor and any other info

class skrl.envs.torch.wrappers.IsaacGymPreview2Wrapper(env: Any)

Bases: skrl.envs.torch.wrappers.Wrapper

__init__(env: Any) → None

Isaac Gym environment (preview 2) wrapper

Parameters: env (Any supported Isaac Gym environment (preview 2) environment) – The environment to wrap

close() → None: Close the environment

render(*args, **kwargs) → None: Render the environment

reset() → Tuple[torch.Tensor, Any]

Reset the environment

Returns: Observation, info
Return type: torch.Tensor and any other info

step(actions: torch.Tensor) → Tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, Any]

Perform a step in the environment

Parameters: actions (torch.Tensor) – The actions to perform
Returns: Observation, reward, terminated, truncated, info
Return type: tuple of torch.Tensor and any other info

class skrl.envs.torch.wrappers.GymWrapper(env: Any)

Bases: skrl.envs.torch.wrappers.Wrapper

__init__(env: Any) → None

OpenAI Gym environment wrapper

Parameters: env (Any supported OpenAI Gym environment) – The environment to wrap

property action_space: gym.spaces.space.Space: Action space

close() → None: Close the environment

property observation_space: gym.spaces.space.Space: Observation space

render(*args, **kwargs) → None: Render the environment

reset() → Tuple[torch.Tensor, Any]

Reset the environment

Returns: Observation, info
Return type: torch.Tensor and any other info

property state_space: gym.spaces.space.Space

State space

An alias for the observation_space property

step(actions: torch.Tensor) → Tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, Any]

Perform a step in the environment

Parameters: actions (torch.Tensor) – The actions to perform
Returns: Observation, reward, terminated, truncated, info
Return type: tuple of torch.Tensor and any other info

class skrl.envs.torch.wrappers.GymnasiumWrapper(env: Any)

Bases: skrl.envs.torch.wrappers.Wrapper

__init__(env: Any) → None

Gymnasium environment wrapper

Parameters: env (Any supported Gymnasium environment) – The environment to wrap

property action_space: gymnasium.spaces.space.Space: Action space

close() → None: Close the environment

property observation_space: gymnasium.spaces.space.Space: Observation space

render(*args, **kwargs) → None: Render the environment

reset() → Tuple[torch.Tensor, Any]

Reset the environment

Returns: Observation, info
Return type: torch.Tensor and any other info

property state_space: gymnasium.spaces.space.Space

State space

An alias for the observation_space property

step(actions: torch.Tensor) → Tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, Any]

Perform a step in the environment

Parameters: actions (torch.Tensor) – The actions to perform
Returns: Observation, reward, terminated, truncated, info
Return type: tuple of torch.Tensor and any other info

class skrl.envs.torch.wrappers.DeepMindWrapper(env: Any)

Bases: skrl.envs.torch.wrappers.Wrapper

__init__(env: Any) → None

DeepMind environment wrapper

Parameters: env (Any supported DeepMind environment) – The environment to wrap

_observation_to_tensor(observation: Any, spec: Optional[Any] = None) → torch.Tensor

Convert the DeepMind observation to a flat tensor

Parameters: observation (Any supported DeepMind observation) – The DeepMind observation to convert to a tensor
Raises: ValueError if the observation spec type is not supported
Returns: The observation as a flat tensor
Return type: torch.Tensor

_spec_to_space(spec: Any) → gym.spaces.space.Space

Convert the DeepMind spec to a Gym space

Parameters: spec (Any supported DeepMind spec) – The DeepMind spec to convert
Raises: ValueError if the spec type is not supported
Returns: The Gym space
Return type: gym.Space

_tensor_to_action(actions: torch.Tensor) → Any

Convert the action to the DeepMind expected format

Parameters: actions (torch.Tensor) – The actions to perform
Raises: ValueError – If the action space type is not supported
Returns: The action in the DeepMind expected format
Return type: Any supported DeepMind action

property action_space: gym.spaces.space.Space: Action space

close() → None: Close the environment

property observation_space: gym.spaces.space.Space: Observation space

render(*args, **kwargs) → None

Render the environment

OpenCV is used to render the environment. Install OpenCV with pip install opencv-python

reset() → Tuple[torch.Tensor, Any]

Reset the environment

Returns: The state of the environment
Return type: torch.Tensor

property state_space: gym.spaces.space.Space

State space

An alias for the observation_space property

step(actions: torch.Tensor) → Tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, Any]

Perform a step in the environment

Parameters: actions (torch.Tensor) – The actions to perform
Returns: Observation, reward, terminated, truncated, info
Return type: tuple of torch.Tensor and any other info

class skrl.envs.torch.wrappers.RobosuiteWrapper(env: Any)

Bases: skrl.envs.torch.wrappers.Wrapper

__init__(env: Any) → None

Robosuite environment wrapper

Parameters: env (Any supported robosuite environment) – The environment to wrap

_observation_to_tensor(observation: Any, spec: Optional[Any] = None) → torch.Tensor

Convert the observation to a flat tensor

Parameters: observation (Any supported observation) – The observation to convert to a tensor
Raises: ValueError if the observation spec type is not supported
Returns: The observation as a flat tensor
Return type: torch.Tensor

_spec_to_space(spec: Any) → gym.spaces.space.Space

Convert the robosuite spec to a Gym space

Parameters: spec (Any supported robosuite spec) – The robosuite spec to convert
Raises: ValueError if the spec type is not supported
Returns: The Gym space
Return type: gym.Space

_tensor_to_action(actions: torch.Tensor) → Any

Convert the action to the robosuite expected format

Parameters: actions (torch.Tensor) – The actions to perform
Raises: ValueError – If the action space type is not supported
Returns: The action in the robosuite expected format
Return type: Any supported robosuite action

property action_space: gym.spaces.space.Space: Action space

close() → None: Close the environment

property observation_space: gym.spaces.space.Space: Observation space

render(*args, **kwargs) → None: Render the environment

reset() → Tuple[torch.Tensor, Any]

Reset the environment

Returns: The state of the environment
Return type: torch.Tensor

property state_space: gym.spaces.space.Space

State space

An alias for the observation_space property

step(actions: torch.Tensor) → Tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, Any]

Perform a step in the environment

Parameters: actions (torch.Tensor) – The actions to perform
Returns: Observation, reward, terminated, truncated, info
Return type: tuple of torch.Tensor and any other info