Creating Environments

GV offers three ways to create environments: Programmatically, using OpenAI Gym’s make(), and using YAML configuration files. The programmatic way is the most flexible, but also the most cumbersome, as it requires design knowledge and ad-hoc code. For now, we focus on the last two.

Using OpenAI Gym

Some predefined environments can be instantiated directly using gym.make(), e.g.,:

import gym
import gym_gridverse

env = gym.make('GV-FourRooms-7x7-v0')

The resulting environment object is an instance of GymEnvironment, which not only satisfied the gym interface, but also provides additional utilities.

Using YAML

While gym.make() is a very convenient way to instantiate pre-registered environments, the main strength of GV is the ability to create custom environments by combining existing and custom transition functions, observation functions, reward functions, etc. Because custom environments cannot be pre-registered, it is not possible to instantiate them via gym.make(). Instead, we provide a separate way to define and instantiate environments based on YAML configuration files. The yaml/ folder contains some example environments in the YAML format, e.g.,

• yaml/gv_empty.8x8.yaml

• yaml/gv_four_rooms.9x9.yaml

• yaml/gv_nine_rooms.13x13.yaml

• yaml/gv_crossing.7x7.yaml

• yaml/gv_keydoor.9x9.yaml

• yaml/gv_dynamic_obstacles.7x7.yaml

• yaml/gv_teleport.7x7.yaml

To create an environment from YAML, you can use the factory function factory_env_from_yaml(). However, factory_env_from_yaml() returns an instance of InnerEnv, which does not provide the same interface as gym.Env. The InnerEnv environment (and other relevant classes) will be explained later, in the design section; for now, if you want to load a YAML environment and interact with it using the gym interface, you must wrap it with GymEnvironment as follows:

from gym_gridverse.envs.yaml.factory import factory_env_from_yaml
from gym_gridverse.gym import outer_env_factory, GymEnvironment

inner_env = factory_env_from_yaml('path/to/env.yaml')
state_representation = make_state_representation(
    'default',
    inner_env.state_space,
)
observation_representation = make_observation_representation(
    'default',
    inner_env.observation_space,
)
outer_env = OuterEnv(
    inner_env,
    state_representation=state_representation,
    observation_representation=observation_representation,
)
env = GymEnvironment(outer_env)

Tip

Script scripts/gv_viewer.py loads an environment expressed in the YAML format and provides manual controls for the agent; this is currently the recommended way to check whether a YAML file is properly formatted, and that the resulting environment behaves as expected:

gv_viewer.py yaml/gv_nine_rooms.13x13.yaml

Schema

The schema for the YAML format is provided in the json-schema format (since YAML is approximately a superset of JSON): schema.yaml.

Broadly speaking, the fields of the YAML format describe the environment spaces (state, action, and observation), as well as its functions (reset, reward, transition, observation, and terminating). For a full overview, we refer to the provided schema and the example YAML files.