multi-puzzle-solver 0.1.0__py3-none-any.whl

puzzle_solver/puzzles/filling/filling.py

@@ -0,0 +1,192 @@
+import numpy as np
+from ortools.sat.python import cp_model
+
+from puzzle_solver.core.utils import Pos, get_all_pos, get_char, set_char, get_neighbors4, get_all_pos_to_idx_dict
+from puzzle_solver.core.utils_ortools import generic_solve_all, SingleSolution, and_constraint
+
+
+class Board:
+    """
+    Per cell p:
+      val[p]    ∈ {1..9} (respect givens)
+      region[p] ∈ {0..N-1}   # region id is the linear index of the region's root
+      is_root[p] <=> (region[p] == idx[p])
+      # NOTE: root is the minimum index among its members via region[p] ≤ idx[p]
+
+    Per (p, k) where k is a root index (0..N-1):
+      in_region[p,k]  <=> (region[p] == k)
+      dist[p,k] ∈ {0..INF}
+        - If in_region[p,k] = 0  ⇒  dist[p,k] = INF
+        - If p == pos_of(k) and is_root[pos_of(k)] = 1  ⇒  dist[p,k] = 0
+        - If in_region[p,k] = 1 and p != pos_of(k)  ⇒
+              dist[p,k] = 1 + min_n masked_dist[n,k]
+          where masked_dist[n,k] = dist[n,k] + 1 if in_region[n,k] else INF
+
+    Edge (u,v):
+      same-digit neighbors must be in same region.
+
+    Region sizes:
+      For each k: size[k] == #{p : region[p] == k}
+      If is_root[pos_of(k)] → size[k] == val[pos_of(k)]
+      Else size[k] == 0
+    """
+
+    def __init__(self, board: np.ndarray):
+        assert board.ndim == 2, f'board must be 2d, got {board.ndim}'
+        self.board = board
+        self.V, self.H = board.shape
+        assert all((c == '*') or (str(c).isdecimal() and 0 <= int(c) <= 9)
+                   for c in np.nditer(board)), "board must contain '*' or digits 0..9"
+
+        self.N = self.V * self.H
+        self.INF = self.N + 1  # a safe "infinity" upper bound for distances
+
+        # Linear index maps (keyed by Pos; do NOT construct tuples)
+        self.idx_of: dict[Pos, int] = get_all_pos_to_idx_dict(self.V, self.H)
+        self.pos_of: list[Pos] = [None] * self.N
+        for pos, idx in self.idx_of.items():
+            self.pos_of[idx] = pos
+
+        m = self.model = cp_model.CpModel()
+
+        # Variables
+        self.val = {}          # val[p]
+        self.region = {}       # region[p]
+        self.same_region = {}  # same_region[(p,q)]
+        self.is_root = {}      # is_root[p]
+        self.is_val = {}       # is_val[(p,k)]  (k=1..9)
+        self.in_region = {}    # in_region[(p,k)]  (k = 0..N-1)
+        self.dist = {}         # dist[(p,k)] ∈ [0..INF]
+
+        # Per-cell vars and givens
+        for p in get_all_pos(self.V, self.H):
+            idx = self.idx_of[p]
+
+            v = m.NewIntVar(1, 9, f'val[{idx}]')
+            ch = get_char(self.board, p)
+            if str(ch).isdecimal():
+                m.Add(v == int(ch))
+            self.val[p] = v
+
+            r = m.NewIntVar(0, self.N - 1, f'region[{idx}]')
+            self.region[p] = r
+
+            b = m.NewBoolVar(f'is_root[{idx}]')
+            self.is_root[p] = b
+            m.Add(r == idx).OnlyEnforceIf(b)
+            m.Add(r != idx).OnlyEnforceIf(b.Not())
+
+            # is_val indicators (for same-digit merge)
+            for k in range(1, 10):
+                bv = m.NewBoolVar(f'is_val[{idx}=={k}]')
+                self.is_val[(p, k)] = bv
+                m.Add(self.val[p] == k).OnlyEnforceIf(bv)
+                m.Add(self.val[p] != k).OnlyEnforceIf(bv.Not())
+
+        # Root = minimum index among members
+        for p in get_all_pos(self.V, self.H):
+            m.Add(self.region[p] <= self.idx_of[p])
+
+        # Membership indicators in_region[p,k] <=> region[p] == k
+        for k in range(self.N):
+            for p in get_all_pos(self.V, self.H):
+                bmem = m.NewBoolVar(f'in_region[{self.idx_of[p]}=={k}]')
+                self.in_region[(p, k)] = bmem
+                m.Add(self.region[p] == k).OnlyEnforceIf(bmem)
+                m.Add(self.region[p] != k).OnlyEnforceIf(bmem.Not())
+
+        # same-digit neighbors must be in the same region
+        for u in get_all_pos(self.V, self.H):
+            for v in get_neighbors4(u, self.V, self.H):
+                if self.idx_of[v] < self.idx_of[u]:
+                    continue  # undirected pair once
+                # If val[u]==k and val[v]==k for any k in 1..9, then region[u]==region[v]
+                # Implement as: for each k, (is_val[u,k] & is_val[v,k]) ⇒ (region[u]==region[v])
+                for k in range(1, 10):
+                    m.Add(self.region[u] == self.region[v])\
+                        .OnlyEnforceIf([self.is_val[(u, k)], self.is_val[(v, k)]])
+
+        for u in get_all_pos(self.V, self.H):
+            for v in get_neighbors4(u, self.V, self.H):
+                b = self.model.NewBoolVar(f'same_region[{self.idx_of[u]},{self.idx_of[v]}]')
+                self.same_region[(u, v)] = b
+                self.model.Add(self.region[u] == self.region[v]).OnlyEnforceIf(b)
+                self.model.Add(self.region[u] != self.region[v]).OnlyEnforceIf(b.Not())
+                self.model.Add(self.val[u] == self.val[v]).OnlyEnforceIf(b)
+
+        # Distance variables dist[p,k] and masked AddMinEquality
+        for k in range(self.N):
+            root_pos = self.pos_of[k]
+
+            for p in get_all_pos(self.V, self.H):
+                dp = m.NewIntVar(0, self.INF, f'dist[{self.idx_of[p]},{k}]')
+                self.dist[(p, k)] = dp
+
+                # If p not in region k -> dist = INF
+                m.Add(dp == self.INF).OnlyEnforceIf(self.in_region[(p, k)].Not())
+
+                # Root distance: if k is active at its own position -> dist[root,k] = 0
+                if p == root_pos:
+                    m.Add(dp == 0).OnlyEnforceIf(self.is_root[root_pos])
+                    # If root_pos isn't the root for k, membership is 0 and above rule sets INF.
+
+            # For non-root members p of region k: dist[p,k] = 1 + min masked neighbor distances
+            for p in get_all_pos(self.V, self.H):
+                if p == root_pos:
+                    continue  # handled above
+
+                # Build masked neighbor candidates: INF if neighbor not in region k; else dist[n,k] + 1
+                cand_vars = []
+                for n in get_neighbors4(p, self.V, self.H):
+                    cn = m.NewIntVar(0, self.INF, f'canddist[{self.idx_of[p]},{k}->{self.idx_of[n]}]')
+                    cand_vars.append(cn)
+
+                    both_in_region_k = m.NewBoolVar(f'both_in_region_k[{self.idx_of[p]} in {k} and {self.idx_of[n]} in {k}]')
+                    and_constraint(m, both_in_region_k, [self.in_region[(p, k)], self.in_region[(n, k)]])
+
+                    # Reified equality:
+                    # in_region[n,k] => cn == dist[n,k] + 1
+                    m.Add(cn == self.dist[(n, k)] + 1).OnlyEnforceIf(both_in_region_k)
+                    # not in_region[n,k] => cn == INF
+                    m.Add(cn == self.INF).OnlyEnforceIf(both_in_region_k.Not())
+
+                # Only enforce the min equation when p is actually in region k (and not the root position).
+                # If p ∉ region k, dp is already INF via the earlier rule.
+                if cand_vars:
+                    m.AddMinEquality(self.dist[(p, k)], cand_vars)
+        for p in get_all_pos(self.V, self.H):
+            # every cell must have 1 dist != INF (lets just do at least 1 dist != INF)
+            not_infs = []
+            for k in range(self.N):
+                not_inf = m.NewBoolVar(f'not_inf[{self.idx_of[p]},{k}]')
+                m.Add(self.dist[(p, k)] != self.INF).OnlyEnforceIf(not_inf)
+                m.Add(self.dist[(p, k)] == self.INF).OnlyEnforceIf(not_inf.Not())
+                not_infs.append(not_inf)
+            m.AddBoolOr(not_infs)
+
+        # Region sizes
+        for k in range(self.N):
+            root_pos = self.pos_of[k]
+            members = [self.in_region[(p, k)] for p in get_all_pos(self.V, self.H)]
+            size_k = m.NewIntVar(0, self.N, f'size[{k}]')
+            m.Add(size_k == sum(members))
+            # Active root -> size equals its value
+            m.Add(size_k == self.val[root_pos]).OnlyEnforceIf(self.is_root[root_pos])
+            # Inactive root id -> size 0
+            m.Add(size_k == 0).OnlyEnforceIf(self.is_root[root_pos].Not())
+
+    def solve_and_print(self):
+        def board_to_solution(board: "Board", solver: cp_model.CpSolverSolutionCallback) -> SingleSolution:
+            assignment: dict[Pos, int] = {}
+            for p in get_all_pos(board.V, board.H):
+                assignment[p] = solver.Value(board.val[p])
+            return SingleSolution(assignment=assignment)
+        def callback(single_res: SingleSolution):
+            print("Solution found")
+            res = np.full((self.V, self.H), ' ', dtype=object)
+            for pos in get_all_pos(self.V, self.H):
+                c = get_char(self.board, pos)
+                c = single_res.assignment[pos]
+                set_char(res, pos, c)
+            print(res)
+        return generic_solve_all(self, board_to_solution, callback=callback)

puzzle_solver/puzzles/guess/guess.py

@@ -0,0 +1,231 @@
+from collections import defaultdict
+import numpy as np
+from collections import Counter
+from itertools import product
+
+class Board:
+    def __init__(self, num_pegs: int = 4, all_colors: list[str] = ['R', 'Y', 'G', 'B', 'O', 'P'], show_warnings: bool = True, show_progress: bool = False):
+        assert num_pegs >= 1, 'num_pegs must be at least 1'
+        assert len(all_colors) == len(set(all_colors)), 'all_colors must contain only unique colors'
+        self.previous_guesses = []
+        self.num_pegs = num_pegs
+        self.all_colors = all_colors
+        self.show_progress = show_progress
+        self.tqdm = None
+        if self.show_progress:
+            try:
+                from tqdm import tqdm
+                self.tqdm = tqdm
+            except ImportError:
+                print('tqdm is not installed, so progress bar will not be shown')
+                self.tqdm = None
+        self.possible_triplets = set((i, j, num_pegs-i-j) for i in range(num_pegs+1) for j in range(num_pegs+1-i))
+        int_to_color = {i: c for i, c in enumerate(self.all_colors)}
+        c = len(self.all_colors)**num_pegs
+        if c > 10**5 and show_warnings:
+            print(f'Warning: len(all_colors)**num_pegs is too large (= {c:,}). The solver may take infinitely long to run.')
+        self.all_possible_pegs = tuple({(i, int_to_color[int_]) for i, int_ in enumerate(ints)} for ints in product(range(len(self.all_colors)), repeat=num_pegs))
+
+    def add_guess(self, guess: tuple[tuple[int, str]], guess_result: tuple[int, int, int]):
+        assert len(guess) == self.num_pegs, 'previous guess must have the same number of pegs as the game'
+        assert not set(guess) - set(self.all_colors), f'previous guess must contain only colors in all_colors; invalid colors: {set(guess) - set(self.all_colors)}'
+        assert sum(guess_result) == self.num_pegs, 'guess result must sum to num_pegs'
+        self.previous_guesses.append((guess, guess_result))
+
+    def get_possible_ground_truths(self):
+        """
+        Returns the possible ground truths based on the previous guesses.
+        """
+        previous_guesses = self.previous_guesses
+        all_possible_pegs = self.all_possible_pegs
+        possible_triplets = self.possible_triplets
+        if self.tqdm is not None:
+            previous_guesses = self.tqdm(previous_guesses, desc='Step 1/2: Filtering possible ground truths')
+        # filter possible ground truths based on previous guesses
+        pair_mask = np.full((len(all_possible_pegs), ), True, dtype=bool)
+        for previous_guess, guess_result in previous_guesses:
+            previous_guess = tuple(tuple((i, c) for i, c in enumerate(previous_guess)))
+            pairs = np_information_gain(guess=previous_guess, possible_ground_truths=all_possible_pegs, possible_triplets=possible_triplets, return_pairs=True)
+            mask = np.all(pairs == guess_result, axis=1)
+            pair_mask &= mask
+        possible_ground_truths = tuple(all_possible_pegs[i] for i in range(len(all_possible_pegs)) if pair_mask[i])
+        return possible_ground_truths
+
+    def best_next_guess(
+        self,
+        return_guess_entropy: bool = False,
+        verbose: bool = True,
+    ):
+        """
+        Returns the best next guess that would maximize the Shannon entropy of the next guess.
+        """
+        possible_triplets = self.possible_triplets
+        all_possible_pegs = self.all_possible_pegs
+        possible_ground_truths = self.get_possible_ground_truths()
+        ng = len(possible_ground_truths)  # number of possible ground truths
+        if ng == 0:
+            print('No possible ground truths found. This should not happen in a real game, please check your inputted guesses.')
+            return ng, None
+        elif ng == 1:
+            answer = [c for i, c in sorted(possible_ground_truths[0], key=lambda x: x[0])]
+            if verbose:
+                print(f'Solution found! The solution is: {answer}')
+            return ng, answer
+        if verbose:
+            print(f'out of {len(all_possible_pegs)} possible ground truths, only {ng} are still possible.')
+
+        if self.tqdm is not None:
+            all_possible_pegs = self.tqdm(all_possible_pegs, desc='Step 2/2: Calculating entropy for each guess')
+        guess_entropy = []
+        possible_ground_truths_set = set(tuple((i, c) for i, c in guess) for guess in possible_ground_truths)
+        for guess in all_possible_pegs:
+            entropy = np_information_gain(guess=guess, possible_ground_truths=possible_ground_truths, possible_triplets=possible_triplets)
+            is_possible = tuple(guess) in possible_ground_truths_set
+            guess_entropy.append((guess, entropy, is_possible))
+        guess_entropy = sorted(guess_entropy, key=lambda x: (x[1], x[2]), reverse=True)
+        max_entropy_guess = guess_entropy[0]
+        if verbose:
+            answer = [c for i, c in sorted(max_entropy_guess[0], key=lambda x: x[0])]
+            print(f'max entropy guess is: {answer} with entropy {max_entropy_guess[1]:.4f}')
+        if return_guess_entropy:
+            return ng, max_entropy_guess, guess_entropy
+        else:
+            return ng, max_entropy_guess
+
+
+
+
+def get_triplets(guess, ground_truth, verbose=False):
+    """
+    Returns
+        1. Number of guesses that match the color and location
+        2. Number of guesses that match the color but not the location
+        3. Number of guesses that do not match the color or the location
+    e.g.
+        if guess is ((0, 'Y'), (1, 'R'), (2, 'R'), (3, 'R')) and ground_truth is ((0, 'Y'), (1, 'Y'), (2, 'R'), (3, 'R')), then the triplets are (3, 0, 1)
+        if guess is ((0, 'R'), (1, 'Y'), (2, 'Y'), (3, 'Y')) and ground_truth is ((0, 'Y'), (1, 'Y'), (2, 'R'), (3, 'R')), then the triplets are (1, 2, 1)
+    """
+    color_count = defaultdict(int)
+    for _, color in ground_truth:
+        color_count[color] += 1
+    matching_color_and_location = 0
+    matching_color_but_not_location = 0
+    not_matching = 0
+    done_locs = set()
+    for (loc, color) in guess:
+        if (loc, color) in ground_truth:
+            if verbose:
+                print(f'loc {loc} color {color} matched perfectly')
+            matching_color_and_location += 1
+            color_count[color] -= 1
+            done_locs.add(loc)
+    for (loc, color) in guess:
+        if loc in done_locs:
+            continue
+        if color_count.get(color, 0) > 0:
+            if verbose:
+                print(f'loc {loc} color {color} matched but not in the right location')
+            matching_color_but_not_location += 1
+            color_count[color] -= 1
+        else:
+            not_matching += 1
+    return matching_color_and_location, matching_color_but_not_location, not_matching
+
+def slow_information_gain(guess: set[tuple[int, str]], possible_ground_truths: set[set[tuple[int, str]]], possible_triplets: set[tuple[int, int, int]]):
+    # safe but slow solution used as a reference
+    counts = {triplet: 0 for triplet in possible_triplets}
+    for ground_truth in possible_ground_truths:
+        counts[tuple(get_triplets(guess, ground_truth))] += 1
+    px = {triplet: count / len(possible_ground_truths) for triplet, count in counts.items()}
+    entropy = -sum(px[triplet] * np.log2(px[triplet]) for triplet in possible_triplets if px[triplet] > 0)
+    # print(counts)
+    return entropy
+
+
+def np_information_gain(guess: tuple[tuple[int, str]], possible_ground_truths: tuple[set[tuple[int, str]]], possible_triplets: set[tuple[int, int, int]], return_pairs: bool = False):
+    # my attempt of a vectorized np solution
+    n = len(guess)
+    all_colors = set()
+    for _, color in guess:
+        all_colors.add(color)
+    for gt in possible_ground_truths:
+        for _, color in gt:
+            all_colors.add(color)
+    guess_mask = {c: np.full((n, 1), 0, dtype=np.int8) for c in all_colors}
+    for loc, color in guess:
+        guess_mask[color][loc] = 1
+    guess_mask_repeated = {c: np.repeat(guess_mask[c].T, len(possible_ground_truths), axis=0) for c in all_colors}
+
+    color_matrices = {c: np.full((len(possible_ground_truths), n), 0, dtype=np.int8) for c in all_colors}
+    for i, gt in enumerate(possible_ground_truths):
+        for loc, color in gt:
+            color_matrices[color][i, loc] = 1
+
+    pair_1 = sum(color_matrices[c] @ guess_mask[c] for c in all_colors)
+
+    pair_2_diff = {c: guess_mask_repeated[c] - color_matrices[c] for c in all_colors}
+    pos_mask = {c: pair_2_diff[c] > 0 for c in all_colors}
+    pair_2_extra_guess = {c: pair_2_diff[c].copy() for c in all_colors}
+    pair_2_extra_ground = {c: pair_2_diff[c].copy() for c in all_colors}
+    pair_2 = {}
+    for c in all_colors:
+        pair_2_extra_guess[c][~pos_mask[c]] = 0
+        pair_2_extra_guess[c] = np.sum(pair_2_extra_guess[c], axis=1)
+        pair_2_extra_ground[c][pos_mask[c]] = 0
+        pair_2_extra_ground[c] = np.abs(np.sum(pair_2_extra_ground[c], axis=1))
+        pair_2[c] = np.minimum(pair_2_extra_guess[c], pair_2_extra_ground[c])
+
+    pair_2 = sum(pair_2[c] for c in all_colors)
+    pair_2 = pair_2[:, None]
+
+    pair_3 = n - pair_1 - pair_2
+
+    pair = np.concatenate([pair_1, pair_2, pair_3], axis=1)
+    pair_counter = Counter(tuple(t) for t in pair)
+    counts = {triplet: pair_counter[triplet] for triplet in possible_triplets}
+    px = {triplet: count / len(possible_ground_truths) for triplet, count in counts.items()}
+    entropy = -sum(px[triplet] * np.log2(px[triplet]) for triplet in possible_triplets if px[triplet] > 0)
+    # print(counts)
+    if return_pairs:
+        return pair
+    else:
+        return entropy
+
+
+
+
+
+
+def fast_information_gain(guess: set[tuple[int, str]],
+                          possible_ground_truths: set[set[tuple[int, str]]],
+                          possible_triplets: set[tuple[int, int, int]]):
+    # chatgpt fast solution + many modifications by me
+    counts = {t: 0 for t in possible_triplets}
+
+    for gt in possible_ground_truths:
+        color_count = {}
+        for _, c in gt:
+            color_count[c] = color_count.get(c, 0) + 1
+
+        H = 0
+        for loc, c in guess:
+            if (loc, c) in gt:
+                H += 1
+                color_count[c] -= 1  # safe: gt contributes this occurrence
+
+        color_only = 0
+        for loc, c in guess:
+            if (loc, c) in gt:
+                continue
+            remain = color_count.get(c, 0)
+            if remain > 0:
+                color_only += 1
+                color_count[c] = remain - 1
+
+        triplet = (H, color_only, len(guess) - H - color_only)
+        counts[triplet] += 1
+
+    px = {triplet: count / len(possible_ground_truths) for triplet, count in counts.items()}
+    entropy = -sum(px[triplet] * np.log2(px[triplet]) for triplet in possible_triplets if px[triplet] > 0)
+    # print(counts)
+    return entropy

puzzle_solver/puzzles/inertia/inertia.py

@@ -0,0 +1,122 @@
+from collections import defaultdict
+
+import numpy as np
+
+from puzzle_solver.core.utils import Direction8, Pos, get_all_pos, get_char, in_bounds, get_next_pos
+
+from . import tsp
+
+
+def _jump(board: np.array, pos: Pos, direction: Direction8) -> tuple[Pos, list[Pos]]:
+    # jump from pos in direction, return the next position and the positions of the gems that would be achieved (mostly likely None)
+    initial_pos = pos
+    out = []
+    while True:
+        next_pos = get_next_pos(pos, direction)
+        if not in_bounds(next_pos, board.shape[0], board.shape[1]):
+            break
+        ch = get_char(board, next_pos)
+        if ch == 'W':
+            break
+        if ch == 'O':
+            pos = next_pos
+            break
+        if ch == 'B':  # Note: the ball always starts ontop of an 'O' cell, thus hitting a 'B' is like hitting a 'O'
+            pos = next_pos
+            break
+        if ch == 'M':  # WE HIT A MINE
+            return None, None
+        if ch == 'G':
+            pos = next_pos
+            out.append(next_pos)
+            continue
+        if ch == ' ':
+            pos = next_pos
+            continue
+    if pos == initial_pos:  # we did not move
+        return None, None
+    return pos, out
+
+def parse_nodes_and_edges(board: np.array):
+    "parses the board into a graph where an edge is 1 move, and each gem lists the edges that would get it"
+    assert board.ndim == 2, 'board must be 2d'
+    assert all(c.item() in [' ', 'W', 'O', 'B', 'M', 'G'] for c in np.nditer(board)), 'board must contain only spaces, W, O, B, M, or G'
+    todo_nodes: set[Pos] = set()
+    completed_nodes: set[Pos] = set()
+    edges_to_direction: dict[tuple[Pos, Pos], Direction8] = {}  # edge (u: Pos, v: Pos) -> direction
+    gems_to_edges: dict[Pos, list[tuple[Pos, Pos]]] = defaultdict(list)  # gem position -> list of edges that would get this gem
+    V, H = board.shape
+    start_pos = [p for p in get_all_pos(V, H) if get_char(board, p) == 'B']
+    assert len(start_pos) == 1, 'board must have exactly one start position'
+    start_pos = start_pos[0]
+    todo_nodes.add(start_pos)
+    while todo_nodes:
+        pos = todo_nodes.pop()
+        for direction in Direction8:
+            next_pos, gems = _jump(board, pos, direction)
+            if next_pos is None:
+                continue
+            e = (pos, next_pos)
+            assert e not in edges_to_direction, 'edge already exists'
+            edges_to_direction[e] = direction
+            if len(gems) > 0:
+                for gem in gems:
+                    assert e not in gems_to_edges[gem], 'edge already in gems_to_edges'
+                    gems_to_edges[gem].append(e)
+            if next_pos not in completed_nodes:
+                todo_nodes.add(next_pos)
+        completed_nodes.add(pos)
+    assert len(gems_to_edges) == len([p for p in get_all_pos(V, H) if get_char(board, p) == 'G']), 'some gems are not reachable'
+    edges = set(edges_to_direction.keys())
+    return start_pos, edges, edges_to_direction, gems_to_edges
+
+def get_moves_from_walk(walk: list[tuple[Pos, Pos]], edges_to_direction: dict[tuple[Pos, Pos], Direction8], verbose: bool = True) -> list[str]:
+    direction_to_str = {Direction8.UP: '↑', Direction8.DOWN: '↓', Direction8.LEFT: '←', Direction8.RIGHT: '→', Direction8.UP_LEFT: '↖', Direction8.UP_RIGHT: '↗', Direction8.DOWN_LEFT: '↙', Direction8.DOWN_RIGHT: '↘'}
+    for edge in walk:
+        assert edge in edges_to_direction, f'edge {edge} not valid yet was in walk'
+    walk_directions = [edges_to_direction[edge] for edge in walk]
+    walk_directions_printable = [direction_to_str[x] for x in walk_directions]
+    if verbose:
+        print("number of moves", len(walk_directions))
+        for i, direction in enumerate(walk_directions_printable):
+            print(f"{direction}", end=' ')
+            if i % 10 == 9:
+                print()
+        print()
+    return walk_directions
+
+def simulate_moves(board: np.array, moves: list[str]) -> bool:
+    V, H = board.shape
+    start_pos = [p for p in get_all_pos(V, H) if get_char(board, p) == 'B']
+    assert len(start_pos) == 1, 'board must have exactly one start position'
+    gems_collected_so_far = set()
+    start_pos = start_pos[0]
+    current_pos = start_pos
+    for move in moves:
+        next_pos, gems = _jump(board, current_pos, move)
+        if next_pos is None:
+            print(f'invalid move {move} from {current_pos}. Either hit a wall (considered illegal here) or a mine (dead)')
+            return set()  # Running into a mine is fatal. Even if you picked up the last gem in the same move which then hit a mine, the game will count you as dead rather than victorious.
+        current_pos = next_pos
+        gems_collected_so_far.update(gems)
+    return gems_collected_so_far
+
+
+def is_board_completed(board: np.array, moves: list[str]) -> bool:
+    V, H = board.shape
+    all_gems = set(p for p in get_all_pos(V, H) if get_char(board, p) == 'G')
+    gems_collected = simulate_moves(board, moves)
+    assert gems_collected.issubset(all_gems), f'collected gems that are not on the board??? should not happen, {gems_collected - all_gems}'
+    return gems_collected == all_gems
+
+def solve_optimal_walk(
+    start_pos: Pos,
+    edges: set[tuple[Pos, Pos]],
+    gems_to_edges: defaultdict[Pos, list[tuple[Pos, Pos]]],
+    *,
+    restarts: int = 1,          # try more for harder instances (e.g., 48–128)
+    time_limit_ms: int = 1000,   # per restart
+    seed: int = 0,
+    verbose: bool = False
+) -> list[tuple[Pos, Pos]]:
+    return tsp.solve_optimal_walk(start_pos, edges, gems_to_edges, restarts=restarts, time_limit_ms=time_limit_ms, seed=seed, verbose=verbose)