Tutorial: Repository Structure#

Introduction#

Welcome to the first of four short tutorials, guiding you through the process of creating your own PettingZoo environment, from conception to deployment.

We will be creating a parallel environment, meaning that each agent acts simultaneously.

Before thinking about the environment logic, we should understand the structure of environment repositories.

Tree structure#

Environment repositories are usually laid out using the following structure:

Custom-Environment
├── custom-environment
    └── env
        └── custom_environment.py
    └── custom_environment_v0.py
├── README.md
└── requirements.txt

/custom-environment/env is where your environment will be stored, along with any helper functions (in the case of a complicated environment).
/custom-environment/custom_environment_v0.py is a file that imports the environment - we use the file name for environment version control.
/README.md is a file used to describe your environment.
/requirements.txt is a file used to keep track of your environment dependencies. At the very least, pettingzoo should be in there. Please version control all your dependencies via ==.

Advanced: Additional (optional) files#

The above file structure is minimal. A more deployment-ready environment would include

/docs/ for documentation,
/setup.py for packaging,
/custom-environment/__init__.py for depreciation handling, and
Github actions for continuous integration of environment tests.

Implementing these are outside the scope of this tutorial.

Skeleton code#

The entirety of your environment logic is stored within /custom-environment/env

/custom-environment/env/custom_environment.py#

from pettingzoo import ParallelEnv


class CustomEnvironment(ParallelEnv):
    metadata = {
        "name": "custom_environment_v0",
    }

    def __init__(self):
        pass

    def reset(self, seed=None, options=None):
        pass

    def step(self, actions):
        pass

    def render(self):
        pass

    def observation_space(self, agent):
        return self.observation_spaces[agent]

    def action_space(self, agent):
        return self.action_spaces[agent]