feat(algorithms, graphs): cat and mouse

Author: BrianLusina

algorithms/graphs/cat_and_mouse/README.md

@@ -0,0 +1,116 @@
+# Cat and Mouse
+
+A game on an undirected graph is played by two players, Mouse and Cat, who alternate turns.
+
+The graph is given as follows: graph[a] is a list of all nodes b such that ab is an edge of the graph.
+
+The mouse starts at node 1 and goes first, the cat starts at node 2 and goes second, and there is a hole at node 0.
+
+During each player's turn, they must travel along one edge of the graph that meets where they are.  For example, if the 
+Mouse is at node 1, it must travel to any node in graph[1].
+
+Additionally, it is not allowed for the Cat to travel to the Hole (node 0).
+
+Then, the game can end in three ways:
+
+- If ever the Cat occupies the same node as the Mouse, the Cat wins.
+- If ever the Mouse reaches the Hole, the Mouse wins.
+- If ever a position is repeated (i.e., the players are in the same position as a previous turn, and it is the same 
+- player's turn to move), the game is a draw.
+Given a graph, and assuming both players play optimally, return
+
+- 1 if the mouse wins the game,
+- 2 if the cat wins the game, or
+- 0 if the game is a draw.
+
+## Examples
+
+![Example 1](./images/examples/cat_and_mouse_example_1.png)
+
+```text
+Input: graph = [[2,5],[3],[0,4,5],[1,4,5],[2,3],[0,2,3]]
+Output: 0
+```
+
+![Example 2](./images/examples/cat_and_mouse_example_2.png)
+```text
+Input: graph = [[1,3],[0],[3],[0,2]]
+Output: 1
+```
+
+## Constraints
+
+- 3 <= graph.length <= 50
+- 1 <= graph[i].length < graph.length
+- 0 <= graph[i][j] < graph.length
+- graph[i][j] != i
+- graph[i] is unique.
+- The mouse and the cat can always move. 
+
+## Related Topics
+
+- Math
+- Dynamic Programming
+- Graph
+- Topological Sort
+- Memoization
+- Game Theory
+
+## Solution
+
+### Minimax/Percolate from Resolved States
+
+The state of the game can be represented as (m, c, t) where m is the location of the mouse, c is the location of the 
+cat, and t is 1 if it is the mouse's move, else 2. Let's call these states nodes. These states form a directed graph: 
+the player whose turn it is has various moves which can be considered as outgoing edges from this node to other nodes.
+
+Some of these nodes are already resolved: if the mouse is at the hole (m = 0), then the mouse wins; if the cat is where
+the mouse is (c = m), then the cat wins. Let's say that nodes will either be colored MOUSE, CAT, or DRAW depending on
+which player is assured victory.
+
+As in a standard minimax algorithm, the Mouse player will prefer MOUSE nodes first, DRAW nodes second, and CAT nodes
+last, and the Cat player prefers these nodes in the opposite order.
+
+#### Algorithm
+
+We will color each node marked DRAW according to the following rule. (We'll suppose the node has node.turn = Mouse: the
+other case is similar.)
+
+- ("Immediate coloring"): If there is a child that is colored MOUSE, then this node will also be colored MOUSE.
+- ("Eventual coloring"): If all children are colored CAT, then this node will also be colored CAT.
+
+We will repeatedly do this kind of coloring until no node satisfies the above conditions. To perform this coloring 
+efficiently, we will use a queue and perform a bottom-up percolation:
+
+- Enqueue any node initially colored (because the Mouse is at the Hole, or the Cat is at the Mouse.)
+- For every node in the queue, for each parent of that node:
+  - Do an immediate coloring of parent if you can.
+  - If you can't, then decrement the side-count of the number of children marked DRAW. If it becomes zero, then do an 
+    "eventual coloring" of this parent. 
+  - All parents that were colored in this manner get enqueued to the queue.
+
+#### Proof of Correctness
+
+Our proof is similar to a proof that minimax works.
+
+Say we cannot color any nodes any more, and say from any node colored CAT or MOUSE we need at most K moves to win. If
+say, some node marked DRAW is actually a win for Mouse, it must have been with >K moves. Then, a path along optimal play
+(that tries to prolong the loss as long as possible) must arrive at a node colored MOUSE
+(as eventually the Mouse reaches the Hole.) Thus, there must have been some transition DRAW→MOUSE along this path.
+
+If this transition occurred at a node with node.turn = Mouse, then it breaks our immediate coloring rule. If it occured
+with node.turn = Cat, and all children of node have color MOUSE, then it breaks our eventual coloring rule. If some child
+has color CAT, then it breaks our immediate coloring rule. Thus, in this case node will have some child with DRAW, which
+breaks our optimal play assumption, as moving to this child ends the game in >K moves, whereas moving to the colored
+neighbor ends the game in ≤K moves.
+
+#### Complexity Analysis
+
+##### Time Complexity
+
+O(N^3), where N is the number of nodes in the graph. There are O(N^2) states, and each state has an
+outdegree of N, as there are at most N different moves.
+
+##### Space Complexity
+
+O(N^2).

algorithms/graphs/cat_and_mouse/__init__.py

@@ -0,0 +1,60 @@
+from typing import List, Deque, DefaultDict, Tuple
+from collections import deque, defaultdict
+
+
+def cat_mouse_game(graph: List[List[int]]) -> int:
+    n = len(graph)
+
+    # Final game states that determine which player wins
+    draw, mouse, cat = 0, 1, 2
+    color: DefaultDict[Tuple[int, int, int], int] = defaultdict(int)
+
+    # What nodes could play their turn to
+    # arrive at node (m, c, t) ?
+    def parents(m, c, t):
+        if t == 2:
+            for m2 in graph[m]:
+                yield m2, c, 3 - t
+        else:
+            for c2 in graph[c]:
+                if c2:
+                    yield m, c2, 3 - t
+
+    # degree[node] : the number of neutral children of this node
+    degree = {}
+    for m in range(n):
+        for c in range(n):
+            degree[m, c, 1] = len(graph[m])
+            degree[m, c, 2] = len(graph[c]) - (0 in graph[c])
+
+    # enqueued : all nodes that are colored
+    queue: Deque[Tuple[int, int, int, int]] = deque([])
+    for i in range(n):
+        for t in range(1, 3):
+            color[0, i, t] = mouse
+            queue.append((0, i, t, mouse))
+            if i > 0:
+                color[i, i, t] = cat
+                queue.append((i, i, t, cat))
+
+    # percolate
+    while queue:
+        # for nodes that are colored :
+        i, j, t, c = queue.popleft()
+        # for every parent of this node i, j, t :
+        for i2, j2, t2 in parents(i, j, t):
+            # if this parent is not colored :
+            if color[i2, j2, t2] is draw:
+                # if the parent can make a winning move (ie. mouse to MOUSE), do so
+                if t2 == c:  # winning move
+                    color[i2, j2, t2] = c
+                    queue.append((i2, j2, t2, c))
+                # else, this parent has degree[parent]--, and enqueue if all children
+                # of this parent are colored as losing moves
+                else:
+                    degree[i2, j2, t2] -= 1
+                    if degree[i2, j2, t2] == 0:
+                        color[i2, j2, t2] = 3 - t2
+                        queue.append((i2, j2, t2, 3 - t2))
+
+    return color[1, 2, 1]

algorithms/graphs/cat_and_mouse/images/examples/cat_and_mouse_example_1.png

@@ -0,0 +1,20 @@
+import unittest
+from typing import List
+from parameterized import parameterized
+from algorithms.graphs.cat_and_mouse import cat_mouse_game
+
+CAT_AND_MOUSE_GAME_TESTS = [
+    ([[2, 5], [3], [0, 4, 5], [1, 4, 5], [2, 3], [0, 2, 3]], 0),
+    ([[1, 3], [0], [3], [0, 2]], 1),
+]
+
+
+class CatAndMouseGameTestCase(unittest.TestCase):
+    @parameterized.expand(CAT_AND_MOUSE_GAME_TESTS)
+    def test_cat_and_mouse_game(self, graph: List[List[int]], expected: int):
+        actual = cat_mouse_game(graph)
+        self.assertEqual(expected, actual)
+
+
+if __name__ == "__main__":
+    unittest.main()