feat: Peg Solitaire env

README.md

@@ -96,6 +96,7 @@ problems.
 | 🎨 GraphColoring                              | Logic  | `GraphColoring-v0`                                   | [code](https://github.com/instadeepai/jumanji/tree/main/jumanji/environments/logic/graph_coloring/)   | [doc](https://instadeepai.github.io/jumanji/environments/graph_coloring/)   |
 | 💣 Minesweeper                           | Logic    | `Minesweeper-v0`                                     | [code](https://github.com/instadeepai/jumanji/tree/main/jumanji/environments/logic/minesweeper/) | [doc](https://instadeepai.github.io/jumanji/environments/minesweeper/) |
 | 🎲 RubiksCube                            | Logic    | `RubiksCube-v0`<br/>`RubiksCube-partly-scrambled-v0` | [code](https://github.com/instadeepai/jumanji/tree/main/jumanji/environments/logic/rubiks_cube/) | [doc](https://instadeepai.github.io/jumanji/environments/rubiks_cube/) |
+|📍️ Solitaire                       | Logic    | `Solitaire-v0`  | [code](https://github.com/instadeepai/jumanji/tree/main/jumanji/environments/logic/solitaire/) | [doc](https://instadeepai.github.io/jumanji/environments/solitaire/) |
 | ✏️ Sudoku                       | Logic    | `Sudoku-v0` <br/>`Sudoku-very-easy-v0`               | [code](https://github.com/instadeepai/jumanji/tree/main/jumanji/environments/logic/sudoku/) | [doc](https://instadeepai.github.io/jumanji/environments/sudoku/) |
 | 📦 BinPack (3D BinPacking Problem)       | Packing  | `BinPack-v2`                                         | [code](https://github.com/instadeepai/jumanji/tree/main/jumanji/environments/packing/bin_pack/)  | [doc](https://instadeepai.github.io/jumanji/environments/bin_pack/)    |
 | 🏭 JobShop (Job Shop Scheduling Problem) | Packing  | `JobShop-v0`                                         | [code](https://github.com/instadeepai/jumanji/tree/main/jumanji/environments/packing/job_shop/)  | [doc](https://instadeepai.github.io/jumanji/environments/job_shop/)    |

docs/api/environments/solitaire.md

@@ -0,0 +1,8 @@
+::: jumanji.environments.logic.solitaire.Solitaire
+    selection:
+      members:
+        - __init__
+        - reset
+        - step
+        - observation_spec
+        - action_spec

docs/environments/solitaire.md

@@ -0,0 +1,39 @@
+# Solitaire
+
+<p align="center">
+    <img src="../env_anim/solitaire.gif" width="500"/>
+</p>
+
+We provide here a Jax JIT-able implementation of [Peg Solitaire](https://en.wikipedia.org/wiki/Peg_solitaire).
+Peg solitaire is a board game for one player involving movement of pegs on a board with holes. The standard game fills the entire board with pegs except for the central hole. The objective is, making valid moves, to empty the entire board except for a solitary peg in the central hole.
+A valid move is to jump one peg over an adjacent peg into a whole two positions away and then remove the jumped peg. The game ends when no more moves are possible and is _solved_ when only a single peg remains (this cannot jump over any more pegs).
+
+## Observation
+The observation in the solitaire contains the placement of pegs on the board. Additionally, an action mask is included with the set of all valid moves in this position.
+
+- `board`: jax array (bool) of shape `(board_size, board_size)`, representing the current board. Each position is either a 1 representing a peg or a 0 representing a hole.
+    + Here is the starting board on a 5x5 grid:
+        ```
+        [[False,  True,  True,  True, False],
+         [ True,  True,  True,  True,  True],
+         [ True,  True, False,  True,  True],
+         [ True,  True,  True,  True,  True],
+         [False,  True,  True,  True, False]]
+        ```
+- `action_mask`: jax array (bool) of shape `(board_size, board_size, 4)`, indicating which actions are valid in the current state of the environment.
+
+## Action
+The action space is a `MultiDiscreteArray` with three integer values.
+
+- The first is the row of the peg to move.
+- The second is the column of the peg to move.
+- The third is direction to move the peg: up (0), right (1), down (2), or left (3).
+
+The move `[2, 4, 3]` in the starting position of a 5x5 board (above) would move the peg in middle of the rightmost column left into the centre and so the peg in row 2, column 4 would be removed.
+
+## Reward
+A reward of 1 is given for each move.
+
+
+## Registered Versions 📖
+- `Solitaire-v0`, a board size of 7x7 (classic English Solitaire).

jumanji/__init__.py

@@ -52,6 +52,9 @@
     kwargs={"time_limit": 20, "generator": partly_scrambled_rubiks_cube_generator},
 )
 
+# Solitaire - English Solitaire with a board size of 7x7.
+register(id="Solitaire-v0", entry_point="jumanji.environments:Solitaire")
+
 # Sudoku - the standard Sudoku puzzle with grid of size 9x9. By default 10000 puzzles
 # of mixed difficulties are set for reset.
 

jumanji/environments/__init__.py

@@ -14,11 +14,12 @@
 
 import sys
 
-from jumanji.environments.logic import game_2048, minesweeper, rubiks_cube
+from jumanji.environments.logic import game_2048, minesweeper, rubiks_cube, solitaire
 from jumanji.environments.logic.game_2048.env import Game2048
 from jumanji.environments.logic.graph_coloring.env import GraphColoring
 from jumanji.environments.logic.minesweeper import Minesweeper
 from jumanji.environments.logic.rubiks_cube import RubiksCube
+from jumanji.environments.logic.solitaire import Solitaire
 from jumanji.environments.logic.sudoku import Sudoku
 from jumanji.environments.packing import bin_pack, job_shop, knapsack, tetris
 from jumanji.environments.packing.bin_pack.env import BinPack

jumanji/environments/logic/solitaire/__init__.py

@@ -0,0 +1,16 @@
+# Copyright 2022 InstaDeep Ltd. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from jumanji.environments.logic.solitaire.env import Solitaire
+from jumanji.environments.logic.solitaire.types import Observation, State

jumanji/environments/logic/solitaire/conftest.py

@@ -0,0 +1,46 @@
+# Copyright 2022 InstaDeep Ltd. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import jax.numpy as jnp
+import pytest
+
+from jumanji.environments.logic.solitaire.types import Board
+from jumanji.environments.logic.solitaire.utils import playing_board
+
+
+@pytest.fixture
+def starting_board5x5() -> Board:
+    """Starting board 5x5."""
+    board = playing_board(5)
+    # Remove middle peg
+    board = board.at[2, 2].set(False)
+    return board
+
+
+@pytest.fixture
+def board7x7() -> Board:
+    """7x7 board with limited moves."""
+    board = jnp.array(
+        [
+            [0, 0, 0, 0, 0, 0, 0],
+            [0, 0, 1, 1, 0, 0, 0],
+            [0, 1, 1, 0, 0, 0, 0],
+            [0, 0, 0, 0, 0, 0, 0],
+            [0, 0, 0, 0, 0, 0, 0],
+            [0, 0, 0, 0, 0, 0, 0],
+            [0, 0, 0, 0, 0, 0, 0],
+        ],
+        dtype=bool,
+    )
+    return board