Counting 3,384 Big Data & Machine Learning Frameworks, Toolsets, and Examples...
Suggestion? Feedback? Tweet @stkim1

Author
Contributors
Last Commit
Dec. 13, 2018
Created
Dec. 13, 2017

mazelab: A customizable framework to create maze and gridworld environments.

This repository contains a customizable framework to create maze and gridworld environments with gym-like API. It has modular designs and it allows large flexibility for the users to easily define their own environments such as changing rendering colors, adding more objects, define available actions etc. The motivation of this repository is, as maze or gridworld are used very often in the reinforcement learning community, however, it is still lack of a standardized framework.

The repo will be actively maintained, any comments, feedbacks or improvements are highly welcomed.

Installation

Install dependencies

Run the following command to install all required dependencies:

pip install -r requirements.txt

Note that it is highly recommanded to use an Miniconda environment:

conda create -n mazelab python=3.7

Install mazelab

Run the following commands to install mazelab from source:

git clone https://github.com/zuoxingdong/mazelab.git
cd mazelab
pip install -e .

Installing from source allows to flexibly modify and adapt the code as you pleased, this is very convenient for research purpose which often needs fast prototyping.

Getting started

Detailed tutorials is coming soon. For now, it is recommended to have a look in examples/ or the source code.

Examples

We have provided a Jupyter Notebook for each example to illustrate how to make various of maze environments, and generate animation of the agent's trajectory following the optimal actions solved by our build-in Dijkstra optimal planner.

Simple empty maze

Simple empty maze

Random shape maze

Random shape maze

Random maze

Random maze

U-maze

U-maze

Double T-maze

Double T-maze

Morris water maze

Morris water maze

How to create your own maze/gridworld environment

  • Define Generator: You can define your own maze generator, simply by creating a class inherited from base class BaseGenerator and the class should look like at least:
    class Generator(BaseGenerator):
        def make_objects(self):
            ...

        def __call__(self):
            ...
  • Create maze object:
    generator = Generator()
    maze = Maze(generator)
  • Define Motion: define your own available actions
    motion = Motion()
    motion.add('north', [-1, 0])
    motion.add('south', [1, 0])
    motion.add('west', [0, -1])
    motion.add('east', [0, 1])
  • Define Gym-like Environment:
    class Env(BaseNavigationEnv):
        def step(self, action):
            ...

        def reset(self):
            self.state = self.make_state()
            self.goal = self.make_goal()

            return self.get_observation()

        def make_state(self):
            ...

        def make_goal(self):
            ...

        def is_valid(self, position):
            ...

        def is_goal(self, position):
  • Create environment:
    env = Env(maze, motion)
  • Solve environment:
    actions = dijkstra_solver(np.array(env.maze.to_impassable()), env.motion, env.state.positions[0], env.goal.positions[0])
  • Record video of executing optimal actions:
    env = Monitor(env, directory='./', force=True)
    env.reset()
    for action in actions:
        env.step(action)
    env.close()

Roadmap

  • More extensive documentations
  • More different kinds of mazes
  • More color patterns

Reference

Please use this bibtex if you want to cite this repository in your publications:

@misc{mazelab,
      author = {Zuo, Xingdong},
      title = {mazelab: A customizable framework to create maze and gridworld environments.},
      year = {2018},
      publisher = {GitHub},
      journal = {GitHub repository},
      howpublished = {\url{https://github.com/zuoxingdong/mazelab}},
    }

Latest Releases
Stable release
 Nov. 18 2018
0.0.1
 Mar. 22 2018