multi-puzzle-solver 0.9.13__py3-none-any.whl → 0.9.14__py3-none-any.whl

{multi_puzzle_solver-0.9.13.dist-info → multi_puzzle_solver-0.9.14.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: multi-puzzle-solver
-Version: 0.9.13
+Version: 0.9.14
 Summary: Efficient solvers for numerous popular and esoteric logic puzzles using CP-SAT
 Author: Ar-Kareem
 Project-URL: Homepage, https://github.com/Ar-Kareem/puzzle_solver
@@ -264,6 +264,11 @@ These are all the puzzles that are implemented in this repo. <br> Click on any o
       <img src="https://raw.githubusercontent.com/Ar-Kareem/puzzle_solver/master/images/lits_solved.png" alt="Lits" width="140">
     </a>
   </td>
+  <td align="center">
+    <a href="#black-box-puzzle-type-34"><b>Black Box</b><br><br>
+      <img src="https://raw.githubusercontent.com/Ar-Kareem/puzzle_solver/master/images/black_box_solved.png" alt="Black Box" width="140">
+    </a>
+  </td>
 </tr>
 </table>
 
@@ -312,6 +317,7 @@ These are all the puzzles that are implemented in this repo. <br> Click on any o
   - [Star Battle (Puzzle Type #31)](#star-battle-puzzle-type-31)
   - [Star Battle Shapeless (Puzzle Type #32)](#star-battle-shapeless-puzzle-type-32)
   - [Lits (Puzzle Type #33)](#lits-puzzle-type-33)
+  - [Black Box (Puzzle Type #34)](#black-box-puzzle-type-34)
   - [Why SAT / CP-SAT?](#why-sat--cp-sat)
   - [Testing](#testing)
   - [Contributing](#contributing)
@@ -804,7 +810,7 @@ You have a grid of squares, some of which contain digits, and the rest of which
 For example, it follows that no square can contain a zero, and that two adjacent squares can not both contain a one. No region has an area greater than 9 (because then its area would not be a single digit).
 </details>
 
-(Note: The solver for this puzzle is the only extremely slow solver in this repo and will take a minute to solve a simple 6x7 puzzle)
+Note: It may take a few seconds for the model to be built.
 
 **Unsolved puzzle**
 
@@ -837,7 +843,7 @@ Solution found
  [1 6 6 1 4 4 4]]
 Solutions found: 1
 status: OPTIMAL
-Time taken: 46.27 seconds
+Time taken: 0.10 seconds
 ```
 
 **Solved puzzle**
@@ -1212,8 +1218,6 @@ You have a grid of squares; some squares contain numbers. Your job is to colour
 For instance, a square containing the number one must have four black squares as its neighbours by the last criterion; but then it's impossible for it to be connected to any outside white square, which violates the second to last criterion. So no square will contain the number one. 
 </details>
 
-(Note: The solver for this puzzle is slightly slower and could take several seconds to solve a 16x11 puzzle)
-
 **Unsolved puzzle**
 
 <img src="https://raw.githubusercontent.com/Ar-Kareem/puzzle_solver/master/images/range_unsolved.png" alt="Range unsolved" width="500">
@@ -1254,7 +1258,7 @@ B . . . B . B . . . . . B . . .
 B . . . . . . B . . . . B . . .
 Solutions found: 1
 status: OPTIMAL
-Time taken: 3.32 seconds
+Time taken: 0.04 seconds
 ```
 
 **Solved puzzle**
@@ -1410,8 +1414,6 @@ Complete the track from A to B so that the rows and columns contain the same num
 
 </details>
 
-(Note: The solver for this puzzle is slightly slower and could take several seconds to solve a large 15x15 puzzle)
-
 **Unsolved puzzle**
 
 <img src="https://raw.githubusercontent.com/Ar-Kareem/puzzle_solver/master/images/tracks_unsolved.png" alt="Tracks unsolved" width="500">
@@ -1461,7 +1463,7 @@ solutions = binst.solve_and_print()
  ['  ' '  ' '  ' '  ' '  ' '  ' '  ' '  ' '  ' '  ' '  ' '  ' '  ' '┏━' '━┛']]
 Solutions found: 1
 status: OPTIMAL
-Time taken: 9.42 seconds
+Time taken: 1.04 seconds
 ```
 
 **Solved puzzle**
@@ -2782,6 +2784,114 @@ Time taken: 0.38 seconds
 
 ---
 
+## Black Box (Puzzle Type #34)
+
+* [**Play online**](https://www.chiark.greenend.org.uk/~sgtatham/puzzles/js/blackbox.html)
+
+* [**Instructions**](https://www.chiark.greenend.org.uk/~sgtatham/puzzles/doc/blackbox.html#blackbox)
+
+* [**Solver Code**][34]
+
+<details>
+  <summary><strong>Rules</strong></summary>
+
+A number of balls are hidden in a rectangular arena. You have to deduce the positions of the balls by firing lasers positioned at the edges of the arena and observing how their beams are deflected.
+
+Beams will travel straight from their origin until they hit the opposite side of the arena (at which point they emerge), unless affected by balls in one of the following ways:
+
+    A beam that hits a ball head-on is absorbed and will never re-emerge. This includes beams that meet a ball on the first rank of the arena.
+    A beam with a ball in its front-left square and no ball ahead of it gets deflected 90 degrees to the right.
+    A beam with a ball in its front-right square and no ball ahead of it gets similarly deflected to the left.
+    A beam that would re-emerge from its entry location is considered to be ‘reflected’.
+    A beam which would get deflected before entering the arena by a ball to the front-left or front-right of its entry point is also considered to be ‘reflected’.
+
+Beams that are reflected appear as a ‘R’; beams that hit balls head-on appear as ‘H’. Otherwise, a number appears at the firing point and the location where the beam emerges (this number is unique to that shot).
+
+You can place guesses as to the location of the balls, based on the entry and exit patterns of the beams; once you have placed enough balls a button appears enabling you to have your guesses checked.
+
+Here is a diagram showing how the positions of balls can create each of the beam behaviours shown above:
+
+      1 R H R - - - -  
+    | . . O . O . . . |
+    2 . . . . . . . . 3
+    | . . . . . . . . |
+    | . . . . . . . . |
+    3 . . . . . . . . |
+    | . . . . . . O . |
+    H . . . . . . . . |
+    | . . . . . O . . |
+      1 2 - R R - - - 
+
+As shown, it is possible for a beam to receive multiple reflections before re-emerging (see turn 3). Similarly, a beam may be reflected (possibly more than once) before receiving a hit (the ‘H’ on the left side of the example).
+
+Note that any layout with more than 4 balls may have a non-unique solution. The following diagram illustrates this; if you know the board contains 5 balls, it is impossible to determine where the fifth ball is (possible positions marked with an x):
+
+      - - - - - - - -  
+    | . . . . . . . . |
+    | . . . . . . . . |
+    | . . O . . O . . |
+    | . . . x x . . . |
+    | . . . x x . . . |
+    | . . O . . O . . |
+    | . . . . . . . . |
+    | . . . . . . . . |
+      - - - - - - - - 
+
+For this reason, when you have your guesses checked, the game will check that your solution produces the same results as the computer's, rather than that your solution is identical to the computer's. So in the above example, you could put the fifth ball at any of the locations marked with an x, and you would still win.
+</details>
+
+Note: This puzzle is one of the very rare puzzles where CP-SAT is not a good fit because for every placement of the balls the state of the beams is dynamically changes and thus required a lot of variables to construct and constraint. This is why the resulting model is large and slow.
+
+**Unsolved puzzle**
+
+<img src="https://raw.githubusercontent.com/Ar-Kareem/puzzle_solver/master/images/black_box_unsolved.png" alt="Black Box unsolved" width="500">
+
+Code to utilize this package and solve the puzzle:
+```python
+from puzzle_solver import black_box_solver as solver
+top = ['1', 'H', 'R', 'R', 'H', 'R', '2', '3']
+left = ['H', '1', 'H', '7', '5', '6', 'H', 'H']
+right = ['2', 'H', '4', 'H', '5', '6', 'H', 'H'] 
+bottom = ['7', 'R', 'H', 'R', 'H', 'R', '4', '3']
+
+# create board and solve; ball count if between 3 and 6
+binst = solver.Board(top=top, left=left, bottom=bottom, right=right, ball_count=(3, 6))
+solutions = binst.solve_and_print()
+```
+**Script Output**
+
+As the instructions say, the solution to this puzzle is not garunteed to be unique.
+
+```python
+Solution found
+[[' ' ' ' ' ' ' ' 'O' ' ' ' ' ' ']
+ [' ' ' ' ' ' ' ' ' ' 'O' ' ' ' ']
+ [' ' 'O' ' ' ' ' ' ' ' ' ' ' ' ']
+ [' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ']
+ [' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ']
+ [' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ']
+ [' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ']
+ [' ' ' ' 'O' ' ' 'O' ' ' ' ' ' ']]
+Solution found
+[[' ' ' ' ' ' ' ' 'O' ' ' ' ' ' ']
+ [' ' ' ' ' ' ' ' ' ' 'O' ' ' ' ']
+ [' ' 'O' ' ' 'O' ' ' ' ' ' ' ' ']
+ [' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ']
+ [' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ']
+ [' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ']
+ [' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ']
+ [' ' ' ' 'O' ' ' 'O' ' ' ' ' ' ']]
+Solutions found: 2
+status: OPTIMAL
+Time taken: 30.33 seconds
+```
+
+**Solved puzzle**
+
+<img src="https://raw.githubusercontent.com/Ar-Kareem/puzzle_solver/master/images/black_box_solved.png" alt="Black Box solved" width="500">
+
+---
+
 ---
 
 ## Why SAT / CP-SAT?
@@ -2866,3 +2976,4 @@ Issues and PRs welcome!
 [31]: https://github.com/Ar-Kareem/puzzle_solver/tree/master/src/puzzle_solver/puzzles/star_battle "puzzle_solver/src/puzzle_solver/puzzles/star_battle at master · Ar-Kareem/puzzle_solver · GitHub"
 [32]: https://github.com/Ar-Kareem/puzzle_solver/tree/master/src/puzzle_solver/puzzles/star_battle_shapeless "puzzle_solver/src/puzzle_solver/puzzles/star_battle_shapeless at master · Ar-Kareem/puzzle_solver · GitHub"
 [33]: https://github.com/Ar-Kareem/puzzle_solver/tree/master/src/puzzle_solver/puzzles/lits "puzzle_solver/src/puzzle_solver/puzzles/lits at master · Ar-Kareem/puzzle_solver · GitHub"
+[34]: https://github.com/Ar-Kareem/puzzle_solver/tree/master/src/puzzle_solver/puzzles/black_box "puzzle_solver/src/puzzle_solver/puzzles/black_box at master · Ar-Kareem/puzzle_solver · GitHub"

{multi_puzzle_solver-0.9.13.dist-info → multi_puzzle_solver-0.9.14.dist-info}/RECORD

@@ -1,33 +1,34 @@
-puzzle_solver/__init__.py,sha256=3aQDyvMPWTlYKDo3j-v4x_lUcNbp7KyallMChQEeJY0,2429
-puzzle_solver/core/utils.py,sha256=D7enPxJjnsTbGDqqtOtGaRaetwGs0nqrNtTnrqhMB-g,3408
-puzzle_solver/core/utils_ortools.py,sha256=eoT9hSJe-c67A_hsu1jnMpyRgMrTtUs5n2j_m5Hk8Do,7362
+puzzle_solver/__init__.py,sha256=-7Mdi0aljanRFso8IlRMDx_TxX1x8joDABRaBpC69fc,2503
+puzzle_solver/core/utils.py,sha256=_LA81kHrsgvqPvq7RISBeaurXmYMKAU9N6qmV8n0G7s,8063
+puzzle_solver/core/utils_ortools.py,sha256=USUl23e6AyE_FGTIN1oYkmMJOuwmKXNges9K2G4ccNM,10360
 puzzle_solver/puzzles/aquarium/aquarium.py,sha256=BUfkAS2d9eG3TdMoe1cOGGeNYgKUebRvn-z9nsC9gvE,5708
-puzzle_solver/puzzles/battleships/battleships.py,sha256=6cYFHnOH7RYLfH5DFVz6SRPHY5GauB9YN4hPU7YNUHU,7444
+puzzle_solver/puzzles/battleships/battleships.py,sha256=RuYCrs4j0vUjlU139NRYYP-uNPAgO0V7hAzbsHrRwD8,7446
+puzzle_solver/puzzles/black_box/black_box.py,sha256=ZnHDVt6PFS_r1kMNSsbz9hav1hxIrNDUvPyERGPjLjM,15635
 puzzle_solver/puzzles/bridges/bridges.py,sha256=15A9uV4xjoqPRo_9CTnoKeGRxS3z2aMF619T1n0dTOQ,5402
 puzzle_solver/puzzles/chess_range/chess_melee.py,sha256=D-_Oi8OyxsVe1j3dIKYwRlxgeb3NWLmDWGcv-oclY0c,195
 puzzle_solver/puzzles/chess_range/chess_range.py,sha256=uMQGTIwzGskHIhI-tPYjT9a3wHUBIkZ18eXjV9IpUE4,21071
 puzzle_solver/puzzles/chess_range/chess_solo.py,sha256=U3v766UsZHx_dC3gxqU90VbjAXn-OlYhtrnnvJYFvrQ,401
 puzzle_solver/puzzles/chess_sequence/chess_sequence.py,sha256=6ap3Wouf2PxHV4P56B9ol1QT98Ym6VHaxorQZWl6LnY,13692
 puzzle_solver/puzzles/dominosa/dominosa.py,sha256=Nmb7pn8U27QJwGy9F3wo8ylqo2_U51OAo3GN2soaNpc,7195
-puzzle_solver/puzzles/filling/filling.py,sha256=UAkNYjlfxOrYGrRVmuElhWPeW10xD6kiWuB8oELzy3w,9141
+puzzle_solver/puzzles/filling/filling.py,sha256=vrOIil285_r3IQ0F4c9mUBWMRVlPH4vowog_z1tCGdI,5567
 puzzle_solver/puzzles/guess/guess.py,sha256=sH-NlYhxM3DNbhk4eGde09kgM0KaDvSbLrpHQiwcFGo,10791
 puzzle_solver/puzzles/inertia/inertia.py,sha256=gJBahkh69CrSWNscalKEoP1j4X-Q3XpbIBMiG9PUpU0,5657
-puzzle_solver/puzzles/inertia/tsp.py,sha256=6ZDxdg2f7GDsZeQpnSR2ay0-T4ZhTESJtkKMcm49OS0,15204
+puzzle_solver/puzzles/inertia/tsp.py,sha256=gobiISHtARA4Elq0jr90p6Yhq11ULjGoqsS-rLFhYcc,15389
 puzzle_solver/puzzles/inertia/parse_map/parse_map.py,sha256=A9JQTNqamUdzlwqks0XQp3Hge3mzyTIVK6YtDJvqpL4,8422
 puzzle_solver/puzzles/kakurasu/kakurasu.py,sha256=VNGMJnBHDi6WkghLObRLhUvkmrPaGphTTUDMC0TkQvQ,2064
 puzzle_solver/puzzles/keen/keen.py,sha256=tDb6C5S3Q0JAKPsdw-84WQ6PxRADELZHr_BK8FDH-NA,5039
 puzzle_solver/puzzles/light_up/light_up.py,sha256=iSA1rjZMFsnI0V0Nxivxox4qZkB7PvUrROSHXcoUXds,4541
-puzzle_solver/puzzles/lits/lits.py,sha256=gYAcsuWucSer2JWs5eKOroiVmjfi-VzccmZvBIUIFks,12014
+puzzle_solver/puzzles/lits/lits.py,sha256=6Yp9EqhQpuWz_rc_rXtu9dG_pUrmBAhWj1Q9IyAfxPk,7891
 puzzle_solver/puzzles/magnets/magnets.py,sha256=-Wl49JD_PKeq735zQVMQ3XSQX6gdHiY-7PKw-Sh16jw,6474
 puzzle_solver/puzzles/map/map.py,sha256=sxc57tapB8Tsgam-yoDitln1o-EB_SbIYvO6WEYy3us,2582
 puzzle_solver/puzzles/minesweeper/minesweeper.py,sha256=LiQVOGkWCsc1WtX8CdPgL_WwAcaeUFuoi5_eqH8U2Og,5876
 puzzle_solver/puzzles/mosaic/mosaic.py,sha256=QX_nVpVKQg8OfaUcqFk9tKqsDyVqvZc6-XWvfI3YcSw,2175
 puzzle_solver/puzzles/nonograms/nonograms.py,sha256=1jmDTOCnmivmBlwtMDyyk3TVqH5IjapzLn7zLQ4qubk,6056
 puzzle_solver/puzzles/norinori/norinori.py,sha256=Z2c0iEn7a6S6gaaJlvNMNNbAQwpztNLB0LTH_XVgu74,12269
-puzzle_solver/puzzles/pearl/pearl.py,sha256=AP0whWwwZ-1zKingW14OwseYylNAr6NkXSrvdnPU6Rw,8566
-puzzle_solver/puzzles/range/range.py,sha256=g6ZuHuulYLpNFsqbnPoIB5KoGPllYppU10-Zzqfj5f8,6993
+puzzle_solver/puzzles/pearl/pearl.py,sha256=OhzpMYpxqvR3GCd5NH4ETT0NO4X753kRi6p5omYLChM,6798
+puzzle_solver/puzzles/range/range.py,sha256=rruvD5ZSaOgvQuX6uGV_Dkr82nSiWZ5kDz03_j7Tt24,4425
 puzzle_solver/puzzles/signpost/signpost.py,sha256=-0_S6ycwzwlUf9-ZhP127Rgo5gMBOHiTM6t08dLLDac,3869
-puzzle_solver/puzzles/singles/singles.py,sha256=kwMENfqQ-OP3YIz5baY6LRcvYCsNfhImEXN00lwazKM,5658
+puzzle_solver/puzzles/singles/singles.py,sha256=3wACiUa1Vmh2ce6szQ2hPjyBuH7aHiQ888p4R2jFkW4,3342
 puzzle_solver/puzzles/star_battle/star_battle.py,sha256=IX6w4H3sifN01kPPtrAVRCK0Nl_xlXXSHvJKw8K1EuE,3718
 puzzle_solver/puzzles/star_battle/star_battle_shapeless.py,sha256=lj05V0Y3A3NjMo1boMkPIwBhMtm6SWydjgAMeCf5EIo,225
 puzzle_solver/puzzles/stitches/stitches.py,sha256=iK8t02q43gH3FPbuIDn4dK0sbaOgZOnw8yHNRNvNuIU,6534
@@ -36,11 +37,11 @@ puzzle_solver/puzzles/sudoku/sudoku.py,sha256=M_pry7XyKKzlfCF5rFi02lyOrj5GWZzXnD
 puzzle_solver/puzzles/tents/tents.py,sha256=iyVK2WXfIT5j_9qqlQg0WmwvixwXlZSsHGK3XA-KpII,6283
 puzzle_solver/puzzles/thermometers/thermometers.py,sha256=nsvJZkm7G8FALT27bpaB0lv5E_AWawqmvapQI8QcYXw,4015
 puzzle_solver/puzzles/towers/towers.py,sha256=QvL0Pp-Z2ewCeq9ZkNrh8MShKOh-Y52sFBSudve68wk,6496
-puzzle_solver/puzzles/tracks/tracks.py,sha256=0K1YZMHiRIMmFwoD_JxB2c_xB6GYV8spgNUCL-JwDJM,9073
+puzzle_solver/puzzles/tracks/tracks.py,sha256=98xds9SKNqtOLFTRUX_KSMC7XYmZo567LOFeqotVQaM,7237
 puzzle_solver/puzzles/undead/undead.py,sha256=IrCUfzQFBem658P5KKqldG7vd2TugTHehcwseCarerM,6604
 puzzle_solver/puzzles/unruly/unruly.py,sha256=sDF0oKT50G-NshyW2DYrvAgD9q9Ku9ANUyNhGSAu7cQ,3827
 puzzle_solver/utils/visualizer.py,sha256=tsX1yEKwmwXBYuBJpx_oZGe2UUt1g5yV73G3UbtmvtE,6817
-multi_puzzle_solver-0.9.13.dist-info/METADATA,sha256=x82w11xGJo2Rb4cGGQkmlbQNZ1i7MPGuhxCjOyaj61Y,143181
-multi_puzzle_solver-0.9.13.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-multi_puzzle_solver-0.9.13.dist-info/top_level.txt,sha256=exwVUQa-anK9vYrpKzBPvH8bX43iElWI4VeNiAyBGJY,14
-multi_puzzle_solver-0.9.13.dist-info/RECORD,,
+multi_puzzle_solver-0.9.14.dist-info/METADATA,sha256=HYspx5V6VWQi6fmAy1I6WaNrDlGumsChUCY2mjZQArI,148507
+multi_puzzle_solver-0.9.14.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+multi_puzzle_solver-0.9.14.dist-info/top_level.txt,sha256=exwVUQa-anK9vYrpKzBPvH8bX43iElWI4VeNiAyBGJY,14
+multi_puzzle_solver-0.9.14.dist-info/RECORD,,

puzzle_solver/__init__.py

@@ -1,5 +1,6 @@
 from puzzle_solver.puzzles.aquarium import aquarium as aquarium_solver
 from puzzle_solver.puzzles.battleships import battleships as battleships_solver
+from puzzle_solver.puzzles.black_box import black_box as black_box_solver
 from puzzle_solver.puzzles.bridges import bridges as bridges_solver
 from puzzle_solver.puzzles.chess_range import chess_range as chess_range_solver
 from puzzle_solver.puzzles.chess_range import chess_solo as chess_solo_solver
@@ -34,4 +35,4 @@ from puzzle_solver.puzzles.unruly import unruly as unruly_solver
 
 from puzzle_solver.puzzles.inertia.parse_map.parse_map import main as inertia_image_parser
 
-__version__ = '0.9.13'
+__version__ = '0.9.14'

puzzle_solver/core/utils.py

@@ -1,127 +1,228 @@
-from dataclasses import dataclass
-from typing import Tuple, Iterable, Union
-from enum import Enum
-
-import numpy as np
-
-
-class Direction(Enum):
-    UP = 1
-    DOWN = 2
-    LEFT = 3
-    RIGHT = 4
-
-class Direction8(Enum):
-    UP = 1
-    DOWN = 2
-    LEFT = 3
-    RIGHT = 4
-    UP_LEFT = 5
-    UP_RIGHT = 6
-    DOWN_LEFT = 7
-    DOWN_RIGHT = 8
-
-@dataclass(frozen=True, order=True)
-class Pos:
-    x: int
-    y: int
-
-
-def get_pos(x: int, y: int) -> Pos:
-    return Pos(x=x, y=y)
-
-
-def get_next_pos(cur_pos: Pos, direction: Union[Direction, Direction8]) -> Pos:
-    delta_x, delta_y = get_deltas(direction)
-    return get_pos(cur_pos.x+delta_x, cur_pos.y+delta_y)
-
-
-def get_neighbors4(pos: Pos, V: int, H: int) -> Iterable[Pos]:
-    for dx, dy in ((1,0),(-1,0),(0,1),(0,-1)):
-        p2 = get_pos(x=pos.x+dx, y=pos.y+dy)
-        if in_bounds(p2, V, H):
-            yield p2
-
-
-def get_neighbors8(pos: Pos, V: int, H: int = None, include_self: bool = False) -> Iterable[Pos]:
-    if H is None:
-        H = V
-    for dx in [-1, 0, 1]:
-        for dy in [-1, 0, 1]:
-            if not include_self and (dx, dy) == (0, 0):
-                continue
-            d_pos = get_pos(x=pos.x+dx, y=pos.y+dy)
-            if in_bounds(d_pos, V, H):
-                yield d_pos
-
-
-def get_row_pos(row_idx: int, H: int) -> Iterable[Pos]:
-    for x in range(H):
-        yield get_pos(x=x, y=row_idx)
-
-
-def get_col_pos(col_idx: int, V: int) -> Iterable[Pos]:
-    for y in range(V):
-        yield get_pos(x=col_idx, y=y)
-
-
-def get_all_pos(V, H=None):
-    if H is None:
-        H = V
-    for y in range(V):
-        for x in range(H):
-            yield get_pos(x=x, y=y)
-
-
-def get_all_pos_to_idx_dict(V, H=None) -> dict[Pos, int]:
-    if H is None:
-        H = V
-    return {get_pos(x=x, y=y): y*H+x for y in range(V) for x in range(H)}
-
-
-def get_char(board: np.array, pos: Pos) -> str:
-    return board[pos.y][pos.x]
-
-
-def set_char(board: np.array, pos: Pos, char: str):
-    board[pos.y][pos.x] = char
-
-
-def in_bounds(pos: Pos, V: int, H: int = None) -> bool:
-    if H is None:
-        H = V
-    return 0 <= pos.y < V and 0 <= pos.x < H
-
-
-def get_opposite_direction(direction: Direction) -> Direction:
-    if direction == Direction.RIGHT:
-        return Direction.LEFT
-    elif direction == Direction.LEFT:
-        return Direction.RIGHT
-    elif direction == Direction.DOWN:
-        return Direction.UP
-    elif direction == Direction.UP:
-        return Direction.DOWN
-    else:
-        raise ValueError(f'invalid direction: {direction}')
-
-
-def get_deltas(direction: Union[Direction, Direction8]) -> Tuple[int, int]:
-    if direction == Direction.RIGHT or direction == Direction8.RIGHT:
-        return +1, 0
-    elif direction == Direction.LEFT or direction == Direction8.LEFT:
-        return -1, 0
-    elif direction == Direction.DOWN or direction == Direction8.DOWN:
-        return 0, +1
-    elif direction == Direction.UP or direction == Direction8.UP:
-        return 0, -1
-    elif direction == Direction8.UP_LEFT:
-        return -1, -1
-    elif direction == Direction8.UP_RIGHT:
-        return +1, -1
-    elif direction == Direction8.DOWN_LEFT:
-        return -1, +1
-    elif direction == Direction8.DOWN_RIGHT:
-        return +1, +1
-    else:
-        raise ValueError(f'invalid direction: {direction}')
+from dataclasses import dataclass
+from typing import Tuple, Iterable, Union
+from enum import Enum
+
+import numpy as np
+
+
+class Direction(Enum):
+    UP = 1
+    DOWN = 2
+    LEFT = 3
+    RIGHT = 4
+
+class Direction8(Enum):
+    UP = 1
+    DOWN = 2
+    LEFT = 3
+    RIGHT = 4
+    UP_LEFT = 5
+    UP_RIGHT = 6
+    DOWN_LEFT = 7
+    DOWN_RIGHT = 8
+
+@dataclass(frozen=True, order=True)
+class Pos:
+    x: int
+    y: int
+
+    def __add__(self, other: 'Pos') -> 'Pos':
+        return get_pos(self.x + other.x, self.y + other.y)
+
+
+Shape = frozenset[Pos]  # a shape on the 2d board is just a set of positions
+
+
+def get_pos(x: int, y: int) -> Pos:
+    return Pos(x=x, y=y)
+
+
+def get_next_pos(cur_pos: Pos, direction: Union[Direction, Direction8]) -> Pos:
+    delta_x, delta_y = get_deltas(direction)
+    return get_pos(cur_pos.x+delta_x, cur_pos.y+delta_y)
+
+
+def get_neighbors4(pos: Pos, V: int, H: int) -> Iterable[Pos]:
+    for dx, dy in ((1,0),(-1,0),(0,1),(0,-1)):
+        p2 = get_pos(x=pos.x+dx, y=pos.y+dy)
+        if in_bounds(p2, V, H):
+            yield p2
+
+
+def get_neighbors8(pos: Pos, V: int, H: int = None, include_self: bool = False) -> Iterable[Pos]:
+    if H is None:
+        H = V
+    for dx in [-1, 0, 1]:
+        for dy in [-1, 0, 1]:
+            if not include_self and (dx, dy) == (0, 0):
+                continue
+            d_pos = get_pos(x=pos.x+dx, y=pos.y+dy)
+            if in_bounds(d_pos, V, H):
+                yield d_pos
+
+
+def get_row_pos(row_idx: int, H: int) -> Iterable[Pos]:
+    for x in range(H):
+        yield get_pos(x=x, y=row_idx)
+
+
+def get_col_pos(col_idx: int, V: int) -> Iterable[Pos]:
+    for y in range(V):
+        yield get_pos(x=col_idx, y=y)
+
+
+def get_all_pos(V, H=None):
+    if H is None:
+        H = V
+    for y in range(V):
+        for x in range(H):
+            yield get_pos(x=x, y=y)
+
+
+def get_all_pos_to_idx_dict(V, H=None) -> dict[Pos, int]:
+    if H is None:
+        H = V
+    return {get_pos(x=x, y=y): y*H+x for y in range(V) for x in range(H)}
+
+
+def get_char(board: np.array, pos: Pos) -> str:
+    return board[pos.y][pos.x]
+
+
+def set_char(board: np.array, pos: Pos, char: str):
+    board[pos.y][pos.x] = char
+
+
+def in_bounds(pos: Pos, V: int, H: int = None) -> bool:
+    if H is None:
+        H = V
+    return 0 <= pos.y < V and 0 <= pos.x < H
+
+
+def get_opposite_direction(direction: Direction) -> Direction:
+    if direction == Direction.RIGHT:
+        return Direction.LEFT
+    elif direction == Direction.LEFT:
+        return Direction.RIGHT
+    elif direction == Direction.DOWN:
+        return Direction.UP
+    elif direction == Direction.UP:
+        return Direction.DOWN
+    else:
+        raise ValueError(f'invalid direction: {direction}')
+
+
+def get_deltas(direction: Union[Direction, Direction8]) -> Tuple[int, int]:
+    if direction == Direction.RIGHT or direction == Direction8.RIGHT:
+        return +1, 0
+    elif direction == Direction.LEFT or direction == Direction8.LEFT:
+        return -1, 0
+    elif direction == Direction.DOWN or direction == Direction8.DOWN:
+        return 0, +1
+    elif direction == Direction.UP or direction == Direction8.UP:
+        return 0, -1
+    elif direction == Direction8.UP_LEFT:
+        return -1, -1
+    elif direction == Direction8.UP_RIGHT:
+        return +1, -1
+    elif direction == Direction8.DOWN_LEFT:
+        return -1, +1
+    elif direction == Direction8.DOWN_RIGHT:
+        return +1, +1
+    else:
+        raise ValueError(f'invalid direction: {direction}')
+
+
+def polyominoes(N):
+    """Generate all polyominoes of size N. Every rotation and reflection is considered different and included in the result.
+    Translation is not considered different and is removed from the result (otherwise the result would be infinite).
+
+    Below is the number of unique polyominoes of size N (not including rotations and reflections) and the lenth of the returned result (which includes all rotations and reflections)
+    N	name		#shapes		#results
+    1	monomino	1			1
+    2	domino		1			2
+    3	tromino		2			6
+    4	tetromino	5			19
+    5	pentomino	12			63
+    6	hexomino	35			216
+    7	heptomino	108			760
+    8	octomino	369			2,725
+    9	nonomino	1,285		9,910
+    10	decomino	4,655		36,446
+    11	undecomino	17,073		135,268
+    12	dodecomino	63,600		505,861
+    Source: https://en.wikipedia.org/wiki/Polyomino
+
+    Args:
+        N (int): The size of the polyominoes to generate.
+
+    Returns:
+        set[(frozenset[Pos], int)]: A set of all polyominoes of size N (rotated and reflected up to D4 symmetry).
+    """
+    assert N >= 1, 'N cannot be less than 1'
+    # need a frozenset because regular sets are not hashable
+    FastShape = frozenset[Tuple[int, int]]
+    shapes: set[FastShape] = {frozenset({(0, 0)})}
+    for i in range(1, N):
+        next_shapes: set[FastShape] = set()
+        directions = ((1,0),(-1,0),(0,1)) if i > 1 else (((1,0),(0,1)))  # cannot take left on first step, if confused read: https://louridas.github.io/rwa/assignments/polyominoes/
+        for s in shapes:
+            # frontier of a single shape: all 4-neighbors of existing cells not already in the shape
+            frontier = set()
+            for x, y in s:
+                # only need to consider 3 directions and neighbors condition is (n.y > 0 or (n.y == 0 and n.x >= 0)) it's obvious if you plot it
+                # if confused read: https://louridas.github.io/rwa/assignments/polyominoes/
+                for dx, dy in directions:
+                    n = (x + dx, y + dy)
+                    if n not in s and (n[1] > 0 or (n[1] == 0 and n[0] >= 0)):
+                        frontier.add(n)
+            for cell in frontier:
+                t = s | {cell}
+                # normalize by translation only: shift so min x,y is (0,0). This removes translational symmetries.
+                minx = min(x for x, y in t)
+                miny = min(y for x, y in t)
+                t0 = frozenset((x - minx, y - miny) for x, y in t)
+                next_shapes.add(t0)
+        shapes = next_shapes
+    # shapes is now complete, now classify up to D4 symmetry (rotations/reflections), translations ignored
+    shapes = {frozenset(Pos(x, y) for x, y in s) for s in shapes}  # regular class, not the dirty-fast one
+    return shapes
+
+def polyominoes_with_shape_id(N):
+    """Refer to polyominoes() for more details. This function returns a set of all polyominoes of size N (rotated and reflected up to D4 symmetry) along with a unique ID for each polyomino that is unique up to D4 symmetry.
+    Args:
+        N (int): The size of the polyominoes to generate.
+
+    Returns:
+        set[(frozenset[Pos], int)]: A set of all polyominoes of size N (rotated and reflected up to D4 symmetry) along with a unique ID for each polyomino that is unique up to D4 symmetry.
+    """
+    FastPos = Tuple[int, int]
+    FastShape = frozenset[Tuple[int, int]]
+    shapes = polyominoes(N)
+    shapes = {frozenset((p.x, p.y) for p in s) for s in shapes}
+    mats = (
+        ( 1, 0,  0, 1),  # regular
+        (-1, 0,  0, 1),  # reflect about x
+        ( 1, 0,  0,-1),  # reflect about y
+        (-1, 0,  0,-1),  # reflect about x and y
+        # trnaspose then all 4 above
+        ( 0, 1,  1, 0), ( 0, 1, -1, 0), ( 0,-1,  1, 0), ( 0,-1, -1, 0),
+    )
+    # compute canonical representative for each shape (lexicographically smallest normalized transform)
+    shape_to_canon: dict[FastShape, tuple[FastPos, ...]] = {}
+    for s in shapes:
+        reps: list[tuple[FastPos, ...]] = []
+        for a, b, c, d in mats:
+            pts = {(a*x + b*y, c*x + d*y) for x, y in s}
+            minx = min(x for x, y in pts)
+            miny = min(y for x, y in pts)
+            rep = tuple(sorted((x - minx, y - miny) for x, y in pts))
+            reps.append(rep)
+        canon = min(reps)
+        shape_to_canon[s] = canon
+
+    canon_set = set(shape_to_canon.values())
+    canon_to_id = {canon: i for i, canon in enumerate(sorted(canon_set))}
+    result = {(s, canon_to_id[shape_to_canon[s]]) for s in shapes}
+    result = {(frozenset(Pos(x, y) for x, y in s), _id) for s, _id in result}
+    return result