Merge pull request #308 from realpython/python-minimax-nim

Add materials for Nim Minimax tutorial

Author: KateFinegan

python-minimax-nim/README.md

@@ -0,0 +1,30 @@
+# Minimax in Python: Learn How to Lose the Game of Nim
+
+Here you can find supplementary material for the Real Python tutorial [Minimax in Python: Learn How to Lose the Game of Nim](https://realpython.com/python-minimax-nim/).
+
+This directory contains source code from the tutorial. Additionally, [`nim/`](nim/) contains an implementation of a small game engine that allows you to play Nim against a minimax player.
+
+Run the game as follows:
+
+```console
+$ cd nim/
+$ python nim.py
+```
+
+Make your choices by entering a corresponding character and hit enter. You can choose between the different variants that are described in the tutorial.
+
+If you want to add a variant yourself, you can do so by adding a new file named with a `game_` prefix. Inside this file, you need to implement the following functions:
+
+- `initial_state()` should set up the initial game state.
+- `possible_new_states(state)` should list the possible states that you can move to from the current state.
+- `evaluate(state, is_maximizing)` should evaluate an end game state and return `None` if the game isn't over.
+
+See the existing `game_*.py` files for examples.
+
+## Author
+
+- **Geir Arne Hjelle**, E-mail: [[email protected]]([email protected])
+
+## License
+
+Distributed under the MIT license. See [`LICENSE`](../LICENSE) for more information.

python-minimax-nim/alphabeta_nim.py

@@ -0,0 +1,38 @@
+from functools import cache
+
+
+@cache
+def minimax(state, is_maximizing, alpha=-1, beta=1):
+    if (score := evaluate(state, is_maximizing)) is not None:
+        return score
+
+    scores = []
+    for new_state in possible_new_states(state):
+        scores.append(
+            score := minimax(new_state, not is_maximizing, alpha, beta)
+        )
+        if is_maximizing:
+            alpha = max(alpha, score)
+        else:
+            beta = min(beta, score)
+        if beta <= alpha:
+            break
+    return (max if is_maximizing else min)(scores)
+
+
+def best_move(state):
+    return max(
+        (minimax(new_state, is_maximizing=False), new_state)
+        for new_state in possible_new_states(state)
+    )
+
+
+def possible_new_states(state):
+    for pile, counters in enumerate(state):
+        for remain in range(counters):
+            yield state[:pile] + (remain,) + state[pile + 1 :]
+
+
+def evaluate(state, is_maximizing):
+    if all(counters == 0 for counters in state):
+        return 1 if is_maximizing else -1

python-minimax-nim/minimax_nim.py

@@ -0,0 +1,30 @@
+from functools import cache
+
+
+@cache
+def minimax(state, is_maximizing):
+    if (score := evaluate(state, is_maximizing)) is not None:
+        return score
+
+    return (max if is_maximizing else min)(
+        minimax(new_state, is_maximizing=not is_maximizing)
+        for new_state in possible_new_states(state)
+    )
+
+
+def best_move(state):
+    return max(
+        (minimax(new_state, is_maximizing=False), new_state)
+        for new_state in possible_new_states(state)
+    )
+
+
+def possible_new_states(state):
+    for pile, counters in enumerate(state):
+        for remain in range(counters):
+            yield state[:pile] + (remain,) + state[pile + 1 :]
+
+
+def evaluate(state, is_maximizing):
+    if all(counters == 0 for counters in state):
+        return 1 if is_maximizing else -1

python-minimax-nim/minimax_nim_split.py

@@ -0,0 +1,30 @@
+from functools import cache
+
+
+@cache
+def minimax(state, is_maximizing):
+    if (score := evaluate(state, is_maximizing)) is not None:
+        return score
+
+    return (max if is_maximizing else min)(
+        minimax(new_state, is_maximizing=not is_maximizing)
+        for new_state in possible_new_states(state)
+    )
+
+
+def best_move(state):
+    return max(
+        (minimax(new_state, is_maximizing=False), new_state)
+        for new_state in possible_new_states(state)
+    )
+
+
+def possible_new_states(state):
+    for pile, counters in enumerate(state):
+        for take in range(1, (counters + 1) // 2):
+            yield state[:pile] + (counters - take, take) + state[pile + 1 :]
+
+
+def evaluate(state, is_maximizing):
+    if all(counters <= 2 for counters in state):
+        return -1 if is_maximizing else 1

python-minimax-nim/minimax_nim_winner_takes_last.py

@@ -0,0 +1,30 @@
+from functools import cache
+
+
+@cache
+def minimax(state, is_maximizing):
+    if (score := evaluate(state, is_maximizing)) is not None:
+        return score
+
+    return (max if is_maximizing else min)(
+        minimax(new_state, is_maximizing=not is_maximizing)
+        for new_state in possible_new_states(state)
+    )
+
+
+def best_move(state):
+    return max(
+        (minimax(new_state, is_maximizing=False), new_state)
+        for new_state in possible_new_states(state)
+    )
+
+
+def possible_new_states(state):
+    for pile, counters in enumerate(state):
+        for remain in range(counters):
+            yield state[:pile] + (remain,) + state[pile + 1 :]
+
+
+def evaluate(state, is_maximizing):
+    if all(counters == 0 for counters in state):
+        return -1 if is_maximizing else 1

python-minimax-nim/minimax_simplenim.py

@@ -0,0 +1,28 @@
+from functools import cache
+
+
+@cache
+def minimax(state, is_maximizing):
+    if (score := evaluate(state, is_maximizing)) is not None:
+        return score
+
+    return (max if is_maximizing else min)(
+        minimax(new_state, is_maximizing=not is_maximizing)
+        for new_state in possible_new_states(state)
+    )
+
+
+def best_move(state):
+    return max(
+        (minimax(new_state, is_maximizing=False), new_state)
+        for new_state in possible_new_states(state)
+    )
+
+
+def possible_new_states(state):
+    return [state - take for take in (1, 2, 3) if take <= state]
+
+
+def evaluate(state, is_maximizing):
+    if state == 0:
+        return 1 if is_maximizing else -1

python-minimax-nim/nim/game_nim.py

@@ -0,0 +1,16 @@
+import random
+
+
+def initial_state():
+    return tuple(random.randint(3, 9) for _ in range(random.randint(3, 5)))
+
+
+def possible_new_states(state):
+    for pile, counters in enumerate(state):
+        for remain in range(counters):
+            yield state[:pile] + (remain,) + state[pile + 1 :]
+
+
+def evaluate(state, is_maximizing):
+    if all(counters == 0 for counters in state):
+        return 1 if is_maximizing else -1

python-minimax-nim/nim/game_nim_simple.py

@@ -0,0 +1,14 @@
+import random
+
+
+def initial_state():
+    return random.randint(10, 25)
+
+
+def possible_new_states(state):
+    return [state - take for take in (1, 2, 3) if take <= state]
+
+
+def evaluate(state, is_maximizing):
+    if state == 0:
+        return 1 if is_maximizing else -1

python-minimax-nim/nim/game_nim_split.py

@@ -0,0 +1,16 @@
+import random
+
+
+def initial_state():
+    return (random.randint(6, 18),)
+
+
+def possible_new_states(state):
+    for pile, counters in enumerate(state):
+        for take in range(1, (counters + 1) // 2):
+            yield state[:pile] + (counters - take, take) + state[pile + 1 :]
+
+
+def evaluate(state, is_maximizing):
+    if all(counters <= 2 for counters in state):
+        return -1 if is_maximizing else 1

python-minimax-nim/nim/game_nim_winner_takes_last.py

@@ -0,0 +1,16 @@
+import random
+
+
+def initial_state():
+    return tuple(random.randint(3, 9) for _ in range(random.randint(3, 5)))
+
+
+def possible_new_states(state):
+    for pile, counters in enumerate(state):
+        for remain in range(counters):
+            yield state[:pile] + (remain,) + state[pile + 1 :]
+
+
+def evaluate(state, is_maximizing):
+    if all(counters == 0 for counters in state):
+        return -1 if is_maximizing else 1