Integrating an Existing Gym Environment

Maze supports a seamless integration of existing OpenAI Gym environments. This holds for already registered, built-in Gym environments but also for any other custom environment following the Gym environments interface.

To get full Maze feature support for Gym environments we first have to transform them into Maze environments. This page shows how this is easily accomplished via the GymMazeEnv.

../_images/gym_env_wrapper.png

In short, a Gym environment is transformed into a MazeEnv by wrapping it with the GymMazeEnv. Under the hood the GymMazeEnv automatically:

  1. Transforms the Gym environment into a GymCoreEnv.

  2. Transforms the observation and action spaces into a dictionary spaces via the GymObservationConversion and GymActionConversion interfaces.

  3. Packs the GymCoreEnv into a MazeEnv which is fully compatible with all other Maze components and modules.

To get a better understanding of the overall structure please see the Maze environment hierarchy.

Instantiating a Gym Environment as a Maze Environment

The config snippet below shows how to instantiate an existing, already registered Gym environment as a GymMazeEnv referenced by its environment name (here CartPole-v0).

# @package env
_target_: maze.core.wrappers.maze_gym_env_wrapper.make_gym_maze_env
name: CartPole-v0

To achieve the same result directly with plain Python you can start with the code snippet below.

from maze.core.wrappers.maze_gym_env_wrapper import GymMazeEnv
env = GymMazeEnv(env="CartPole-v0")

In case your custom Gym environment is not yet registered with Gym, you can also explicitly instantiate the environment before passing it to the GymMazeEnv.

from maze.core.wrappers.maze_gym_env_wrapper import GymMazeEnv
custom_gym_env = CustomGymEnv()
env = GymMazeEnv(env=custom_gym_env)

Test your own Gym Environment with Maze

If you already have a project set up and would like to test Maze with your own environment the quickest way to get started is to:

First, make sure that your project is either installed or available in your PYTHONPATH.

Second, add an environment factory function similar to the one shown in the snippet below to your project (e.g., my_project/env_factory.py).

from maze.core.env.maze_env import MazeEnv
from maze.core.wrappers.maze_gym_env_wrapper import GymMazeEnv

def make_env(name: str) -> MazeEnv:
    custom_gym_env = CustomGymEnv()
    return GymMazeEnv(custom_gym_env)

That’s all we need to do. You can now start training an agent for your environment by running:

$ maze-run -cn conf_train env._target_=my_project.env_factory.make_env

This basically updates the original gym_env config via Hydra overrides.

Note that the argument name is unused so far but is required to adhere to the gym_env config signature. When creating your own config files you can of course tailor this signature to your needs.

Where to Go Next