Merge branch 'master' into master

Farama-Foundation · Aug 29, 2024 · 798c696 · 798c696
2 parents 12d6533 + 715394f
commit 798c696
Show file tree

Hide file tree

Showing 75 changed files with 183 additions and 65 deletions.
diff --git a/CITATION.cff b/CITATION.cff
@@ -45,7 +45,10 @@ preferred-citation:
     given-names: Pablo Samuel
   - family-names: Terry
     given-names: Jordan
-  journal: CoRR
-  title: Minigrid
-  volume: abs/2306.13831
+  title: "Minigrid & Miniworld: Modular & Customizable Reinforcement Learning Environments for Goal-Oriented Tasks"
+  type: inproceedings
   year: 2023
+  conference:
+    name: "Neural Information Processing Systems (NeurIPS)"
+  publisher:
+    name: "Proceedings of the Conference on Neural Information Processing Systems (NeurIPS)"
diff --git a/README.md b/README.md
@@ -9,7 +9,7 @@
   <img src="figures/door-key-curriculum.gif" width=200 alt="Figure Door Key Curriculum">
 </p>
 
-The Minigrid library contains a collection of discrete grid-world environments to conduct research on Reinforcement Learning. The environments follow the [Gymnasium]() standard API and they are designed to be lightweight, fast, and easily customizable. 
+The Minigrid library contains a collection of discrete grid-world environments to conduct research on Reinforcement Learning. The environments follow the [Gymnasium](https://github.com/Farama-Foundation/Gymnasium) standard API and they are designed to be lightweight, fast, and easily customizable. 
 
 The documentation website is at [minigrid.farama.org](https://minigrid.farama.org/), and we have a public discord server (which we also use to coordinate development work) that you can join here: [https://discord.gg/bnJ6kubTg6](https://discord.gg/bnJ6kubTg6)
 
@@ -43,11 +43,11 @@ The original `gym-minigrid` environments were created as part of work done at [M
 To cite this project please use:
 
 ```bibtex
-@article{MinigridMiniworld23,
-  author       = {Maxime Chevalier-Boisvert and Bolun Dai and Mark Towers and Rodrigo de Lazcano and Lucas Willems and Salem Lahlou and Suman Pal and Pablo Samuel Castro and Jordan Terry},
-  title        = {Minigrid \& Miniworld: Modular \& Customizable Reinforcement Learning Environments for Goal-Oriented Tasks},
-  journal      = {CoRR},
-  volume       = {abs/2306.13831},
+@inproceedings{MinigridMiniworld23,
+  author       = {Maxime Chevalier{-}Boisvert and Bolun Dai and Mark Towers and Rodrigo Perez{-}Vicente and Lucas Willems and Salem Lahlou and Suman Pal and Pablo Samuel Castro and Jordan Terry},
+  title        = {Minigrid {\&} Miniworld: Modular {\&} Customizable Reinforcement Learning Environments for Goal-Oriented Tasks},
+  booktitle    = {Advances in Neural Information Processing Systems 36, New Orleans, LA, USA},
+  month        = {December},
   year         = {2023},
 }
 ```

diff --git a/docs/_scripts/gen_env_docs.py b/docs/_scripts/gen_env_docs.py
@@ -19,6 +19,7 @@
 filtered_envs_by_type = {}
 env_names = []
 babyai_envs = {}
+wfc_envs = {}
 
 # Obtain filtered list
 for env_spec in tqdm(all_envs):
@@ -32,6 +33,9 @@
             curr_babyai_env = split[2]
             babyai_env_name = curr_babyai_env.split(":")[1]
             babyai_envs[babyai_env_name] = env_spec
+        elif len(split) > 2 and "wfc" in split[2]:
+            curr_wfc_env = env_spec.kwargs["wfc_config"]
+            wfc_envs[curr_wfc_env] = env_spec
         elif env_module == "minigrid":
             env_name = split[1]
             filtered_envs_by_type[env_name] = env_spec
@@ -56,7 +60,13 @@
     )
 }
 
-for env_name, env_spec in chain(filtered_envs.items(), filtered_babyai_envs.items()):
+# Because they share a class, only the default (MazeSimple) environment should be kept
+canonical_wfc_env_name = "MazeSimple"
+filtered_wfc_envs = {canonical_wfc_env_name: wfc_envs[canonical_wfc_env_name]}
+
+for env_name, env_spec in chain(
+    filtered_envs.items(), filtered_babyai_envs.items(), filtered_wfc_envs.items()
+):
     env = env_spec.make()
 
     docstring = trim(env.unwrapped.__doc__)

diff --git a/docs/_scripts/gen_envs_display.py b/docs/_scripts/gen_envs_display.py
@@ -4,16 +4,41 @@
 
 import gymnasium
 
+# Display bonus WFC presets
+from minigrid.envs.wfc import WFCEnv
+from minigrid.envs.wfc.config import (
+    WFC_PRESETS_INCONSISTENT,
+    WFC_PRESETS_SLOW,
+    register_wfc_presets,
+)
+from utils import env_name_format
+
+register_wfc_presets(WFC_PRESETS_INCONSISTENT, gymnasium.register)
+register_wfc_presets(WFC_PRESETS_SLOW, gymnasium.register)
+
+# Read name from the actual class so it is updated if the class name changes
+WFCENV_NAME = WFCEnv.__name__
+
+
+def title_from_id(env_id):
+    words = []
+    for chunk in env_id.split("_"):
+        words.extend(env_name_format(chunk).split(" "))
+
+    return " ".join(w.title() for w in words)
+
 
 def create_grid_cell(type_id, env_id, base_path):
+    # All WFCEnv environments should link to WFCEnv page
+    href = f"{base_path}{env_id if type_id != 'wfc' else WFCENV_NAME}"
     return f"""
-            <a href="{base_path}{env_id}">
+            <a href="{href}">
                 <div class="env-grid__cell">
                     <div class="cell__image-container">
                         <img src="/_static/videos/{type_id}/{env_id}.gif">
                     </div>
                     <div class="cell__title">
-                        <span>{' '.join(env_id.split('_')).title()}</span>
+                        <span>{title_from_id(env_id)}</span>
                     </div>
                 </div>
             </a>
@@ -64,6 +89,10 @@ def generate_page(env, limit=-1, base_path=""):
             env_name = split[-1].split(":")[-1]
             env_type = env_module if len(split) == 2 else split[-1].split(":")[0]
 
+            if env_name == WFCENV_NAME:
+                env_name = env_spec.kwargs["wfc_config"]
+                assert isinstance(env_name, str)
+
             if env_module == "minigrid":
                 if env_type not in type_dict.keys():
                     type_dict[env_type] = []

diff --git a/docs/_scripts/gen_gifs.py b/docs/_scripts/gen_gifs.py
@@ -24,12 +24,18 @@
 # iterate through all envspecs
 for env_spec in tqdm(gymnasium.envs.registry.values()):
     # minigrid.envs:Env or minigrid.envs.babyai:Env
+    if not isinstance(env_spec.entry_point, str):
+        continue
     split = env_spec.entry_point.split(".")
     # ignore minigrid.envs.env_type:Env
     env_module = split[0]
     env_name = split[-1].split(":")[-1]
     env_type = env_module if len(split) == 2 else split[-1].split(":")[0]
 
+    # Override env_name for WFC to include the preset name
+    if env_name == "WFCEnv":
+        env_name = env_spec.kwargs["wfc_config"]
+
     if env_module == "minigrid" and env_name not in envs_completed:
         os.makedirs(os.path.join(output_dir, env_type), exist_ok=True)
         path = os.path.join(output_dir, env_type, env_name + ".gif")

diff --git a/docs/_scripts/utils.py b/docs/_scripts/utils.py
@@ -32,7 +32,9 @@ def trim(docstring):
 
 def env_name_format(str):
     # KeyCorridorEnv
-    split = re.findall(r"[A-Z](?:[a-z]+|[A-Z]*(?=[A-Z]|$))", str)
+    split = re.findall(r"[A-Z](?:[a-z]+[0-9]*|[A-Z]*[0-9]*(?=[A-Z]|$))", str)
+    if not split:
+        split.append(str)
     # ['Key', 'Corridor', 'Env']
     split = filter(lambda x: x.upper() != "ENV", split)
     return " ".join(split)
diff --git a/docs/_static/videos/minigrid/ObstructedMaze_Full_V1.gif b/docs/_static/videos/minigrid/ObstructedMaze_Full_V1.gif
diff --git a/docs/_static/videos/wfc/Dungeon.gif b/docs/_static/videos/wfc/Dungeon.gif
diff --git a/docs/_static/videos/wfc/DungeonLessRooms.gif b/docs/_static/videos/wfc/DungeonLessRooms.gif
diff --git a/docs/_static/videos/wfc/DungeonMazeScaled.gif b/docs/_static/videos/wfc/DungeonMazeScaled.gif
diff --git a/docs/_static/videos/wfc/DungeonRooms.gif b/docs/_static/videos/wfc/DungeonRooms.gif
diff --git a/docs/_static/videos/wfc/DungeonSpirals.gif b/docs/_static/videos/wfc/DungeonSpirals.gif
diff --git a/docs/_static/videos/wfc/Maze.gif b/docs/_static/videos/wfc/Maze.gif
diff --git a/docs/_static/videos/wfc/MazeKnot.gif b/docs/_static/videos/wfc/MazeKnot.gif
diff --git a/docs/_static/videos/wfc/MazePaths.gif b/docs/_static/videos/wfc/MazePaths.gif
diff --git a/docs/_static/videos/wfc/MazeSimple.gif b/docs/_static/videos/wfc/MazeSimple.gif
diff --git a/docs/_static/videos/wfc/MazeSpirals.gif b/docs/_static/videos/wfc/MazeSpirals.gif
diff --git a/docs/_static/videos/wfc/MazeWall.gif b/docs/_static/videos/wfc/MazeWall.gif
diff --git a/docs/_static/videos/wfc/Mazelike.gif b/docs/_static/videos/wfc/Mazelike.gif
diff --git a/docs/_static/videos/wfc/ObstaclesAngular.gif b/docs/_static/videos/wfc/ObstaclesAngular.gif
diff --git a/docs/_static/videos/wfc/ObstaclesBlackdots.gif b/docs/_static/videos/wfc/ObstaclesBlackdots.gif
diff --git a/docs/_static/videos/wfc/ObstaclesHogs2.gif b/docs/_static/videos/wfc/ObstaclesHogs2.gif
diff --git a/docs/_static/videos/wfc/ObstaclesHogs3.gif b/docs/_static/videos/wfc/ObstaclesHogs3.gif
diff --git a/docs/_static/videos/wfc/RoomsFabric.gif b/docs/_static/videos/wfc/RoomsFabric.gif
diff --git a/docs/_static/videos/wfc/RoomsMagicOffice.gif b/docs/_static/videos/wfc/RoomsMagicOffice.gif
diff --git a/docs/_static/videos/wfc/RoomsOffice.gif b/docs/_static/videos/wfc/RoomsOffice.gif
diff --git a/docs/_static/videos/wfc/Skew2.gif b/docs/_static/videos/wfc/Skew2.gif
diff --git a/docs/_static/videos/wfc/SkewCave.gif b/docs/_static/videos/wfc/SkewCave.gif
diff --git a/docs/_static/videos/wfc/SkewLake.gif b/docs/_static/videos/wfc/SkewLake.gif
diff --git a/docs/_static/videos/wfc/WFCEnv.gif b/docs/_static/videos/wfc/WFCEnv.gif
diff --git a/docs/content/basic_usage.md b/docs/content/basic_usage.md
@@ -13,10 +13,10 @@ There is a UI application which allows you to manually control the agent with th
 ./minigrid/manual_control.py
 ```
 
-The environment being run can be selected with the `--env` option, eg:
+The environment being run can be selected with the `--env-id` option, eg:
 
 ```bash
-./minigrid/manual_control.py --env MiniGrid-Empty-8x8-v0
+./minigrid/manual_control.py --env-id MiniGrid-Empty-8x8-v0
 ```
 
 ## Installation

diff --git a/docs/content/publications.md b/docs/content/publications.md
@@ -7,7 +7,10 @@ firstpage:
 
 
 List of publications & submissions using Minigrid or BabyAI (please open a pull request to add missing entries):
+- [DRED: Zero-Shot Transfer in Reinforcement Learning via Data-Regularised Environment Design](https://arxiv.org/abs/2402.03479) (University of Edinburgh, ICML 2024)
+- [Conviction-Based Planning for Sparse Reward Reinforcement Learning Problems](https://prl-theworkshop.github.io/prl2024-icaps/papers/8.pdf)(UQÀM, PRL @ ICAPS 2024)
 - [Learning from Active Human Involvement through Proxy Value Propagation](https://metadriverse.github.io/pvp/)(UCLA, NeurIPS Spotlight 2023)
+- [Go Beyond Imagination: Maximizing Episodic Reachability with World Models](https://arxiv.org/pdf/2308.13661.pdf) (UMich, ICML 2023)
 - [Hierarchies of Reward Machines](https://arxiv.org/abs/2205.15752) (Imperial College London, ILASP, Universitat Pompeu Fabra, ICML 2023)
 - [Minimal Value-Equivalent Partial Models for Scalable and Robust Planning in Lifelong Reinforcement Learning](https://arxiv.org/abs/2301.10119) (Mila, McGill University, CoLLAs 2023)
 - [DEIR: Efficient and Robust Exploration through Discriminative-Model-Based Episodic Intrinsic Rewards](https://arxiv.org/abs/2304.10770) (U-Tokyo, Google Brain, IJCAI 2023)

diff --git a/docs/environments/wfc/index.md b/docs/environments/wfc/index.md
@@ -0,0 +1,18 @@
+---
+firstpage:
+lastpage:
+---
+
+## WFC Environments
+
+```{raw} html
+   :file: list.html
+```
+
+```{toctree}
+:hidden:
+:caption: Wave Function Collapse Environments
+
+WFCEnv
+
+```
diff --git a/docs/index.md b/docs/index.md
@@ -41,11 +41,11 @@ env.close()
 To cite this project please use:
 
 ```bibtex
-@article{MinigridMiniworld23,
-  author       = {Maxime Chevalier-Boisvert and Bolun Dai and Mark Towers and Rodrigo de Lazcano and Lucas Willems and Salem Lahlou and Suman Pal and Pablo Samuel Castro and Jordan Terry},
-  title        = {Minigrid \& Miniworld: Modular \& Customizable Reinforcement Learning Environments for Goal-Oriented Tasks},
-  journal      = {CoRR},
-  volume       = {abs/2306.13831},
+@inproceedings{MinigridMiniworld23,
+  author       = {Maxime Chevalier{-}Boisvert and Bolun Dai and Mark Towers and Rodrigo Perez{-}Vicente and Lucas Willems and Salem Lahlou and Suman Pal and Pablo Samuel Castro and Jordan Terry},
+  title        = {Minigrid {\&} Miniworld: Modular {\&} Customizable Reinforcement Learning Environments for Goal-Oriented Tasks},
+  booktitle    = {Advances in Neural Information Processing Systems 36, New Orleans, LA, USA},
+  month        = {December},
   year         = {2023},
 }
 ```
@@ -74,6 +74,7 @@ api/wrapper
 
 environments/minigrid/index
 environments/babyai/index
+environments/wfc/index
 ```
 
 ```{toctree}

diff --git a/minigrid/__init__.py b/minigrid/__init__.py
@@ -5,7 +5,7 @@
 from minigrid import minigrid_env, wrappers
 from minigrid.core import roomgrid
 from minigrid.core.world_object import Wall
-from minigrid.envs.wfc.config import WFC_PRESETS
+from minigrid.envs.wfc.config import WFC_PRESETS, register_wfc_presets
 
 __version__ = "2.3.1"
 
@@ -568,12 +568,7 @@ def register_minigrid_envs():
 
     # WaveFunctionCollapse
     # ----------------------------------------
-    for name in WFC_PRESETS.keys():
-        register(
-            id=f"MiniGrid-WFC-{name}-v0",
-            entry_point="minigrid.envs.wfc:WFCEnv",
-            kwargs={"wfc_config": name},
-        )
+    register_wfc_presets(WFC_PRESETS, register)
 
     # BabyAI - Language based levels - GoTo
     # ----------------------------------------

diff --git a/minigrid/core/world_object.py b/minigrid/core/world_object.py
@@ -25,7 +25,6 @@
 
 
 class WorldObj:
-
     """
     Base class for grid world objects
     """

diff --git a/minigrid/envs/babyai/core/levelgen.py b/minigrid/envs/babyai/core/levelgen.py
@@ -1,6 +1,7 @@
 """
 Copied and adapted from https://github.com/mila-iqia/babyai
 """
+
 from __future__ import annotations
 
 from minigrid.core.constants import COLOR_NAMES

diff --git a/minigrid/envs/babyai/core/roomgrid_level.py b/minigrid/envs/babyai/core/roomgrid_level.py
@@ -1,6 +1,7 @@
 """
 Copied and adapted from https://github.com/mila-iqia/babyai
 """
+
 from __future__ import annotations
 
 from minigrid.core.roomgrid import RoomGrid

diff --git a/minigrid/envs/babyai/core/verifier.py b/minigrid/envs/babyai/core/verifier.py
@@ -1,6 +1,7 @@
 """
 Copied and adapted from https://github.com/mila-iqia/babyai
 """
+
 from __future__ import annotations
 
 import os

diff --git a/minigrid/envs/babyai/goto.py b/minigrid/envs/babyai/goto.py
@@ -2,6 +2,7 @@
 Copied and adapted from https://github.com/mila-iqia/babyai.
 Levels described in the Baby AI ICLR 2019 submission, with the `Go to` instruction.
 """
+
 from __future__ import annotations
 
 from minigrid.envs.babyai.core.levelgen import LevelGen

diff --git a/minigrid/envs/babyai/open.py b/minigrid/envs/babyai/open.py
@@ -2,6 +2,7 @@
 Copied and adapted from https://github.com/mila-iqia/babyai.
 Levels described in the Baby AI ICLR 2019 submission, with the `Open` instruction.
 """
+
 from __future__ import annotations
 
 from minigrid.core.constants import COLOR_NAMES

diff --git a/minigrid/envs/babyai/other.py b/minigrid/envs/babyai/other.py
@@ -2,6 +2,7 @@
 Copied and adapted from https://github.com/mila-iqia/babyai.
 Levels described in the Baby AI ICLR 2019 submission, with different instructions than those in other files.
 """
+
 from __future__ import annotations
 
 from minigrid.envs.babyai.core.roomgrid_level import RoomGridLevel

diff --git a/minigrid/envs/babyai/pickup.py b/minigrid/envs/babyai/pickup.py
@@ -2,6 +2,7 @@
 Copied and adapted from https://github.com/mila-iqia/babyai.
 Levels described in the Baby AI ICLR 2019 submission, with the `Pick up` instruction.
 """
+
 from __future__ import annotations
 
 from minigrid.envs.babyai.core.levelgen import LevelGen

diff --git a/minigrid/envs/babyai/putnext.py b/minigrid/envs/babyai/putnext.py
@@ -2,6 +2,7 @@
 Copied and adapted from https://github.com/mila-iqia/babyai.
 Levels described in the Baby AI ICLR 2019 submission, with the `Put Next` instruction.
 """
+
 from __future__ import annotations
 
 from minigrid.envs.babyai.core.roomgrid_level import RoomGridLevel

diff --git a/minigrid/envs/babyai/unlock.py b/minigrid/envs/babyai/unlock.py
@@ -2,6 +2,7 @@
 Copied and adapted from https://github.com/mila-iqia/babyai.
 Levels described in the Baby AI ICLR 2019 submission, with the `Unlock` instruction.
 """
+
 from __future__ import annotations
 
 from minigrid.core.constants import COLOR_NAMES

diff --git a/minigrid/envs/blockedunlockpickup.py b/minigrid/envs/blockedunlockpickup.py
@@ -7,7 +7,6 @@
 
 
 class BlockedUnlockPickupEnv(RoomGrid):
-
     """
 
     ## Description

diff --git a/minigrid/envs/crossing.py b/minigrid/envs/crossing.py
@@ -11,7 +11,6 @@
 
 
 class CrossingEnv(MiniGridEnv):
-
     """
     ## Description
 

diff --git a/minigrid/envs/distshift.py b/minigrid/envs/distshift.py
@@ -7,7 +7,6 @@
 
 
 class DistShiftEnv(MiniGridEnv):
-
     """
     ## Description
 

diff --git a/minigrid/envs/doorkey.py b/minigrid/envs/doorkey.py
@@ -7,7 +7,6 @@
 
 
 class DoorKeyEnv(MiniGridEnv):
-
     """
     ## Description
 
@@ -91,7 +90,7 @@ def _gen_grid(self, width, height):
         self.place_agent(size=(splitIdx, height))
 
         # Place a door in the wall
-        doorIdx = self._rand_int(1, width - 2)
+        doorIdx = self._rand_int(1, height - 2)
         self.put_obj(Door("yellow", is_locked=True), splitIdx, doorIdx)
 
         # Place a yellow key on the left side

diff --git a/minigrid/envs/fetch.py b/minigrid/envs/fetch.py
@@ -8,7 +8,6 @@
 
 
 class FetchEnv(MiniGridEnv):
-
     """
     ## Description
 

diff --git a/minigrid/envs/fourrooms.py b/minigrid/envs/fourrooms.py
@@ -7,7 +7,6 @@
 
 
 class FourRoomsEnv(MiniGridEnv):
-
     """
     ## Description
 

diff --git a/minigrid/envs/keycorridor.py b/minigrid/envs/keycorridor.py
@@ -6,7 +6,6 @@
 
 
 class KeyCorridorEnv(RoomGrid):
-
     """
     ## Description