Add PourProblem (water-pouring) search problem (#1333)

Canonical water-pouring problem as a Problem subclass + test. Supersedes #1029 by @geekypathak21.

Author: dmeoli

search.py

@@ -883,6 +883,46 @@ def and_search(states, problem, path):
 directions8.update({'NW': (-1, 1), 'NE': (1, 1), 'SE': (1, -1), 'SW': (-1, -1)})
 
 
+class PourProblem(Problem):
+    """Problem about pouring water between jugs to achieve some water level.
+    Each state is a tuple of levels. In the initialization, provide a tuple of
+    capacities, e.g. PourProblem(initial=(2, 4, 3), goals={7}, capacities=(8, 16, 32)),
+    which means three jugs of capacity 8, 16, 32 currently filled with 2, 4, 3 units
+    of water, respectively, and the goal is to get a level of 7 in any one of the jugs."""
+
+    def __init__(self, initial=None, goals=(), capacities=None):
+        super().__init__(initial, goals)
+        self.goals = goals
+        self.capacities = capacities
+
+    def actions(self, state):
+        """The actions executable in this state: fill or dump any jug, or pour one into another."""
+        jugs = range(len(state))
+        return ([('Fill', i) for i in jugs if state[i] != self.capacities[i]] +
+                [('Dump', i) for i in jugs if state[i] != 0] +
+                [('Pour', i, j) for i in jugs for j in jugs if i != j])
+
+    def result(self, state, action):
+        """The state that results from executing this action in this state."""
+        result = list(state)
+        act, i, j = action[0], action[1], action[-1]
+        if act == 'Fill':  # fill jug i to its capacity
+            result[i] = self.capacities[i]
+        elif act == 'Dump':  # empty jug i
+            result[i] = 0
+        elif act == 'Pour':  # pour jug i into jug j
+            a, b = state[i], state[j]
+            result[i], result[j] = ((0, a + b) if (a + b <= self.capacities[j])
+                                    else (a + b - self.capacities[j], self.capacities[j]))
+        else:
+            raise ValueError('unknown action', action)
+        return tuple(result)
+
+    def goal_test(self, state):
+        """True if any of the jugs has a level equal to one of the goal levels."""
+        return any(level in self.goals for level in state)
+
+
 class PeakFindingProblem(Problem):
     """Problem of finding the highest peak in a limited grid"""
 

tests/test_search.py

@@ -102,6 +102,14 @@ def test_traveling_salesman():
     assert tsp.value(solution) == pytest.approx(3 + 5 ** 0.5)
 
 
+def test_pour_problem():
+    # the classic two-jug puzzle: with jugs of capacity 3 and 5, measure out 4
+    problem = PourProblem(initial=(0, 0), goals={4}, capacities=(3, 5))
+    solution = breadth_first_graph_search(problem)
+    assert solution is not None
+    assert any(level == 4 for level in solution.state)
+
+
 def test_find_blank_square():
     assert eight_puzzle.find_blank_square((0, 1, 2, 3, 4, 5, 6, 7, 8)) == 0
     assert eight_puzzle.find_blank_square((6, 3, 5, 1, 8, 4, 2, 0, 7)) == 7